Z80 High Score Save Starter Kit

Prepared By: Jason Souza (Jason@souzaonline.com) Document Version Control

Version 0.001 0.002 0.003 0.004 1.000

Date 01/06/11 01/10/11 01/17/11 01/20/11 02/02/11

Author Jason Souza Jason Souza Jason Souza Jason Souza Jason Souza

Change Description Initial Draft Added content to GAL section Added content to MAME section Added some kit assembly photos Final review and updates

Introduction ..........................................................................................................4 Prerequisites .................................................................................................4 Hardware .............................................................................................................4 Overview .......................................................................................................4 Inventory .......................................................................................................4 Kit Assembly .................................................................................................5 GAL 16v8 ...........................................................................................................11 Address Decoding ......................................................................................11 MAME Drivers ............................................................................................12 Software ......................................................................................................12 The main screen.........................................................................................13 Modules ......................................................................................................13 Syntax .........................................................................................................14 LOW = /.......................................................................................................14 AND = * .......................................................................................................14 OR = + ........................................................................................................14 XOR = :+: ...................................................................................................14 Pin-out .........................................................................................................14 Example ......................................................................................................15 Game Selection.................................................................................................16 Required .....................................................................................................16 Nice to Have ...............................................................................................16 Game Code .......................................................................................................16 Tools ...........................................................................................................16 Hex Editor ...................................................................................................16 MAMED ......................................................................................................16 Disassembler ..............................................................................................16 Assembler ...................................................................................................17 Rom Saver..................................................................................................17 Program Code Concatenation ...................................................................17 Checksum ...................................................................................................17

Example ......................................................................................................17 Free Play and Coin with Attract Mode.......................................................18 High Score Save ........................................................................................18 Example ......................................................................................................18 Clearing the High Score Table ..................................................................19 Example ......................................................................................................19

Introduction
This document is a collection of information that is used as a reference is making a High Score Kit or Rom Saver Kit. The focus is on building the kit, programming the GAL and pointing you in the right direction as far as making a High Score Save Kit. This document will not focus much attention on programming z80 assembly language or modifying game code. This document assumes you have a basic understanding of the follow concepts 1. Burning and erasing eproms 2. Modifying game code and the high level structure a. You cant just add your own code, you need to remove something so the following addresses line up. If you want to add a call to your function you will need to find 3 bytes to steal from somewhere (3 nops or commenting out another call function) 3. Basic soldering skills 4. Basic understanding of z80 assembly language 5. Basic understanding of address decoding

Prerequisites
Soldering Iron The kit does not come assembled so a soldering iron and some basic soldering skills are required Solder to accompany the soldering iron Eprom Programmer / Eprom eraser You will likely want to erase and reprogram the 27c512 eprom often. GAL programmer In many cases this is the same device as the eprom programmer. I use a TOP2007 that programs eproms and GALS just fine.

Hardware
Overview
The kit is pretty simple, it has four main components. The Z80 which is the core of the game, the GAL that does the address decoding, the Eprom that contains the main program code and the NVRAM that stores the high score table and other configuration data. The GAL has 7 inputs from the z80 (A15, A14, A13, A12, A11, WE and MREQ). These are the main components of the equations that need to be created to make the kit work. These equations generate the 4 outputs of the GAL (EPROM, BANK, NVOE and NVWR). EPROM is tied to the chip select and output enable pins of the 27c512 Eprom. BANK is most commonly just a pass through for A15 on the Eprom, this could potentially be used for bank switching in the future. NVOE is the chip select for the NVRAM and NVWR is the write enable for the NVRAM.

Inventory
The photo below is what you get in the kit (also includes but not pictured the capacitor, socket for the GAL and some additional header pins in case any get broken)

HSS Kit PCB Sockets Header Pins Blank 27c512 Eprom Blank 16v8 GAL

Kit Assembly
Here are step by step photos of how to assemble the kit. The photo is BELOW the line that describes it.

Solder one of the header pin rows (second row of empty holes)

Solder the z80 socket over the header pins you just installed

Solder the second row of header pins to the right of the z80 socket

Install the socket for the GAL (only in development mode)

Cut the bottom and top piece off of the Eprom 28 pin socket (only in dev mode)

Solder the two halves of the Eprom socket

Solder in the 24 pin NVRAM socket

Install the capacitor (make sure to notice the + and polarity)

If you have a programmed GAL insert it now

Insert another 28 pin socket on top of the GAL for the Eprom (Not Included)

Another view

Now you just need to insert the NVRAM, Eprom and Z80 to complete the kit. You can probably build the kit in a different order but this is how I normally build it.

GAL 16v8
Address Decoding
This table can be used to help write your equation for the GAL. The left column is a memory address and the left column is what it looks like in binary. Address lines A15 A11 are highlighted since those are inputs to the GAL. A11 is used to adjust the address by $800 for example: $F000 = 1111 0000 0000 0000 $F800 = 1111 1000 0000 0000 So in this case if you want your eprom to be enable for $F800 to FFFF then it would look something like this (see below for GAL syntax using OPALjr) ; $F000 to F7FF /EPROM = A15 * A14 * A13 * A12 * /A11 Or ; $F800 to FFFF /EPROM = A15 * A14 * A13 * A12 * A11

Address $0000 $1000 $2000

From Left to Right A15 to A0 0000 0000 0000 0000 0001 0000 0000 0000 0001 0000 0000 0000

$3000 $4000 $5000 $6000 $7000 $8000 $9000 $A000 $B000 $C000 $D000 $E000 $F000

0011 0000 0000 0000 0100 0000 0000 0000 0101 0000 0000 0000 0110 0000 0000 0000 0111 0000 0000 0000 1000 0000 0000 0000 1001 0000 0000 0000 1010 0000 0000 0000 1011 0000 0000 0000 1100 0000 0000 0000 1101 0000 0000 0000 1110 0000 0000 0000 1111 0000 0000 0000

MAME Drivers
To determine the memory map of a certain game you can either look at the schematics or look at the MAME driver code. Deriving the memory map from the schematics is outside the scope of this document. The MAME drivers can be viewed here at on the MAME DEV website located at http://mamedev.org/source/src/mame/drivers/index.html In most cases the memory map is right at the top of the driver as seen in the driver for Lady Bug http://mamedev.org/source/src/mame/drivers/ladybug.c.html Memory map (preliminary) 0000-5fff ROM 6000-6fff RAM d000-d3ff video RAM d000-d007/d020-d027/d040-d047/d060-d067 contain the column scroll registers (not used by Lady Bug) d400-d7ff color RAM (4 bits wide) From looking at this we can see that the main program rom is from $0000 to $5FFF and there is plenty of space remaining for nvram (I choose $F800 - $FFFF as a standard and that will work here). We dont need to add any additional rom space for helper roms since all of the modified code will fit in the blank space in the program rom. Normally the additional rom space is added if the game does not have a High Score Table and we want to add one. In any case there is additional space in the memory map if you decide to add on screen dip settings or diagnostics.

Software
I like to use OPALJr because it is easy and free. Unfortunately it does not have a simulator or other cool features included but it gets the job done. You can download version 2.0 from my website. Just download it and unzip it to a directory on your

computer. I will not give an exhaustive overview of this tool, just the two main items needed for writing GAL code for this kit. http://arcade.souzaonline.com/Downloads/opaljr.zip The main screen I usually just use the dos version opaljr.exe, when you run this exe you will see the following screen. Type in your equations (or open a saved one) and save it as <filename>.eqn

Modules Under the modules file menu there is an option called EQN2JED. This converts your equation file to a JEDEC format with a .jed file extension. This is the file you will program to the GAL with your programmer. Make sure you fill in the following information and change the device type to G16V8 and you are ready to click the run button.

If you dont get any errors you should have a file called devkit.jed (or whatever you named it) that is ready to be programmed to the GAL16v8.

Syntax
This is not a conclusive list but here are the main syntax items when working with OPALjr. LOW = / If you want to represent a value as low (0) then you put a / in front of it Example: /EPROM = A15 Explanation: When A15 is high (1) then EPROM is low (0), otherwise EPROM is high (1) AND = * If you want to AND two items then you use the * character in your equation. Example: /EPROM = A15 * /A14 Explanation: When A15 is high AND A14 is low then EPROM is low OR = + Example: /EPROM = A15 + A14 Explanation: If A15 is high OR A14 is high then EPROM is low XOR = :+: Example: /EPROM = A15 :+: A14 Explanation: Explanation: If A15 is high OR A14 is high (but not both) then EPROM is low

For additional reading, here is a good tutorial http://arcade.souzaonline.com/Docs/PLDTUTOR.pdf

Pin-out
This is the pin-out the 16v8 GAL. The CLK and Registered pins are outside the scope of this document. Pin 1 to 9 can only be inputs into the GAL Pin 11 to 19 can be either input or output Please refer to the data sheet for additional information http://www.latticesemi.com/lit/docs/datasheets/pal_gal/16v8.pdf

This is the pin-out of the GAL for version 1.0 of the kit. The inputs into the GAL are A15, A14, A13, A12, A11, WR and MREQ The outputs from the GAL are EPROM, BANK, NVOE and NVWR

As you can see there are plenty of pins left if you in this version and you can use these additional inputs and outputs by soldering a wire from the bottom of the HSS kit pcb.

Example
Here is a pretty common example of an equation file (.eqn) that can be converted to a .jed file for programming.

; Address decoding (Z80 HSS) ; Jason Souza 01/06/2011 ; Memory Map ; 0000-37ff Program ROMS ; f000-f7ff Helper ROM HSS ; f800-ffff NVRAM CHIP decode 16V8 ; Set pin configuration ; Row 1: pin 1-> pin 10 ; Row 2: pin 11 - pin 20 NC1 A15 A14 A13 A12 A11 WR MREQ NC3 GND NC4 NC5 NC6 NC7 NC8 NVWR NVOE BANK EPROM VCC EQUATIONS

; Eprom enable (0000-37ff and f000-f7ff) /EPROM = /A15 * /A14 * /MREQ + A15 * A14 * A13 * A12 * /A11 * /MREQ ; Pass-through for now, my be used for bank switching in the future BANK = A15 ; NVRAM enable and write pins ($f800 - $ffff) /NVOE = A15 * A14 * A13 * A12 * A11 * /MREQ * WR /NVWR = A15 * A14 * A13 * A12 * A11 * /MREQ * /WR

Game Selection
Required
Z80 processor is used to run the main program code o Some games have multiple z80s on them (as a sound processor for example) so make sure you are piggybacking the right one

The kit will fit unobstructed on the pcb and in the cabinet o o PCBs in cages may not be a good choice PCB stacks with the z80 on the bottom are not ideal but may work if you add longer pcb separators

Nice to Have
Existing High Score Table Socketed Z80 Program code is not encrypted

Game Code
Tools
Hex Editor Hex editors are outside the scope of this doc but can be useful if you want to change a couple of bytes on the rom directly or do a search for a pattern. Many games will show ASCII text for strings and they can be edited directly from the hex editor. There are lots of free hex editors out there, just search google. MAMED MAMED has a debugger built into it and allows you to step through code, set break points, change values on the fly, look at memory locations, search memory locations, etc. Using MAMED is outside the scope of this document but here is a good reference. http://mess.redump.net/debugger Disassembler I like to use IDA Pro, it has the ability to disassemble older processors such as z80, 6502, etc. Saldy the free version does not support this and the Pro version is quite expensive. There are other free ones out there but I have not had good experience with any of them.

Assembler I use TASM for z80 (http://home.comcast.net/~tasm/) it rocks for z80 games. I have not had a lot of luck assembling 6502 but have not has any issues with any z80 game.

Rom Saver
The simplest kit that can be made is a simple Rom saver that does not modify any of the program code (no free play mode or high score saving). This is commonly used to remove older smaller Eproms. The 27C512 is more efficient than 4+ older Eproms and only uses 5 volts for power. All you need for the Rom saver is to concatenate the program code and burn it to the 27C512 and program the GAL with the EPROM and BANK outputs. You do not even need to install the NVRAM for this configuration. Program Code Concatenation The only tool you need is built into your operating system. I use copy.exe in the following way. In this example lets say there are 4 program roms named rom1.bin, rom2.bin, rom3.bin and rom4.bin. The order is important so you can use the MAME driver to see the order to put them in. 1. Copy the program roms into a single directory 2. From a command window do the following a. Navigate to the directory where you have the roms b. Copy /b rom1.bin+rom2.bin+rom3.bin+rom4.bin combined.bin 3. Burn combined.bin to the 27c512 Eprom 4. See below for help on writing the GAL equation

Checksum
Some games have a checksum to make sure that the rom has not been tampered with and does not have any bit rot. Most rom checksums will add up all the bytes from the program code (or every other byte) and expect the value to be zero. These functions are usually pretty easy to spot because the first thing they do is set HL equal to $0000 and then set bc to some value (the size of each rom usually). There are a couple of different ways to handle the checksum. In some cases it is easiest just to nop out the jump when a is not equal to zero (last line in the example below). I like to just find some free space in the program code to adjust for the checksum. This way it keeps the integrity of the program code in case the eprom goes bad. You can use MAMED and set a break point where is checks a and see what the value is and then adjust accordingly. This takes time because you need to adjust each time you modify the rom, but it is the cleanest option. For example if the value in register A is $EA instead of zero I used the following equation $FF - $EA + 1 (once FF is reached the next hex value is $00) The calculator built into windows handles this with ease and the value is $16 Find some empty code in the program and put .db $16 Example ; Check rom checksums ld hl,$0000 ld bc,$1000 ld ($50c0),a ld a,c add a,(hl) ld c,a ; Kick the dog

ld a,l add a,$02 ld l,a cp $02 jp nc,$3009 inc h djnz $3006 ld a,c and a ; If a is not zero then it is a bad checksum ; Jump to somewhere to handle jr nz,$3031

Free Play and Coin with Attract Mode

Unfortunately this is not an area where I have a lot of advice. In many cases it is hours in front of MAMED playing around to see how to keep the game in attract mode when coins are inserted or in free play mode. Here are some basic steps that may help in a simple example. 1. Check near the beginning of the program RAM, that is usually where the game mode is stored. If ram starts at $C000 keep an eye on the first 20 bytes when you insert a coin. A lot of games use a similar format in the game mode byte: a. ; GALAXIAN $4005 is the mode 1=attract, 2=press start page, 3=game mode 2. Next find the place in the code where it gets bumped from 1 to 2 and comment it out 3. Now the game should stay in attract mode when coins are dropped but the code is not run to check for game start. You will need to insert your own function into the attract mode to check for P1 and P2 start pressed. Make sure to check for the correct amount of coins in your function then you need to jump where the game starts. This will take a lot of time probing in MAME, but the payoff is great.

High Score Save

The easiest this to do is find a game that already has a high score table. Then all you need to do is find a place in the game code to restore the high score table and save off the high score table. Finding out where to restore the high score table from NVRAM is easy, the best place to do this is right after the startup code finishes clearing the program ram (if you do it before this then the HST will get wiped out). Finding out where you should save the HST off to NVRAM can be a little bit trickier. You need to step through the code and right after the user enters initials and the HST is saved to ram is the ideal time to save the HST to NVRAM. Once this is done you just need to have a way to clear the HST (see below). If the game you choose does not have a HST then you need to create your own and that is outside the scope of this document. Example Here is an example of a function that will copy memory (High Score Table) from its original location to NVRAM. The restore function is almost exactly the same but copies from NVRAM to the location in memory where the HST is stored SaveHST: ; Save registers push hl push de push bc ; Copy 30 bytes from $4200 to $F800 ld hl, $4200 ld de, $F800

ld bc, $001e ldir ; Restore registers pop bc pop de pop hl ret

Clearing the High Score Table

If you are saving high scores you will definitely need a way to clear high scores. Generally you want to choose a combination that is not usually triggered in normal game play. I usually choose to have it triggered by holding Player 1 and Player 2 start buttons during boot up of the game. Some other options are to use an unused dip switch or test switch. The technique I use is to have a byte or two I am expecting to be there for valid NVRAM. This serves two purposes 1. If there is unformatted NVRAM it will initialize it by running the clear nvram method 2. All you need to do when the clear nvram sequence is triggered is change those two bytes. Example ; This example is from lady bug, it is called early on in the game boot up sequence. ; Usually replaces the function that sets the high score defaults rstscorenv:: ; Before we check the nvram, see if we should clear HST ; The following functions checks call chkclr ;check to see of 12 and 89 is at $f800 and f801 ; if not clear nvram ld a, ($f800) cp $12 jr nz, badnv ld a, ($f801) cp $89 jr nz, badnv rstsav:: ; Restore the scores ld hl, $f802 ld de, $6073 ld bc, $001B ldir ret badnv:: ; Call the functions to clear the HST ; These are from the original game code call $2F9 ; Now that it is clear save it off ; The following function saves the HST to nvram call rstsav ld a, $12 ld ($f800), a ld a, $89 ld ($f801), a ret chkclr:: push hl

push af ; Check if P1 + P2 start are being held down ld hl, 9000h ld a, (hl) and $60 call z, badnv pop af pop hl ret