Z80 High Score Save Starter Kit - Arcade Games

Z80 High Score Save Starter Kit
Prepared By: Jason Souza (Jason@souzaonline.com)
Document Version Control
Version
Date
Author
Change Description
0.001
01/06/11
Jason Souza
Initial Draft
0.002
01/10/11
Jason Souza
Added content to GAL section
0.003
01/17/11
Jason Souza
Added content to MAME section
0.004
01/20/11
Jason Souza
Added some kit assembly photos
1.000
02/02/11
Jason Souza
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 can’t 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
From Left to Right A15 to A0
$0000
0000 0000 0000 0000
$1000
0001 0000 0000 0000
$2000
0001 0000 0000 0000
$3000
0011 0000 0000 0000
$4000
0100 0000 0000 0000
$5000
0101 0000 0000 0000
$6000
0110 0000 0000 0000
$7000
0111 0000 0000 0000
$8000
1000 0000 0000 0000
$9000
1001 0000 0000 0000
$A000
1010 0000 0000 0000
$B000
1011 0000 0000 0000
$C000
1100 0000 0000 0000
$D000
1101 0000 0000 0000
$E000
1110 0000 0000 0000
$F000
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 don’t 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 don’t 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 z80’s 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
PCB’s in cages may not be a good choice
o
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 let’s 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