mz80.txt

著名ARC模拟器源码,包括多个平台

	{0x3000, 0x3fff,  VideoWrite},
	{0x4000, 0x4fff,  SpriteWrite},
	{(UINT32) -1,     (UINT32) -1, NULL}
};

The above example says that any time a write occurs in the 0x3000-0x3fff
range, call the VideoWrite routine. The same holds true for the SpriteWrite
region as well.

NOTE: When your write handler is called, it is passed the address of the
write and the data that is to be written to it. If your handler doesn't
write the data to the virtual image, the mz80 internal code will not.

NOTE: These routines will *NOT* be called when execution asks for these
addresses. It will only call them when a particular instruction uses the
memory at these locations.

If you wish for a region to be RAM, just leave it out of your memory region
exception list. The WriteMemoryByte routine will treat it as read/write
RAM and will write to mz80Base + addr directly.

If you wish to protect ROM regions (not often necessary), create a range that
encompasses the ROM image, and have it call a routine that does nothing. This
will prevent data from being written back onto the ROM image.

Leave your last entry in the table as shown above, with a null handler and
0xffffffff-0xffffffff as your read address. Even though the Z80 only
addresses 64K of space, the read/write handlers are defined as 32 bit so
the compiler won't pass junk in the upper 16 bits of the address lines. Not
only that, it allows orthoganality for future CPU emulators that may use
these upper bits.

You can do a mz80GetContext() if you'd like to read the current context of
the registers. Note that by the time your handler gets called, the program
counter will be pointing to the *NEXT* instruction.

struct MemoryReadByte GameRead[] =
{
	{0x2000,        0x200f,         ReadHandler},
	{(UINT32) -1,     (UINT32) -1,  NULL}
};

Same story here. If you have a special handler for an attempted read at a
particular address, place its range in this table and create a handler
routine for it.   

If you don't define a handler for a particular region, then the ReadMemoryByte
in mz80.ASM will actually read the value out of mz80Base + the offset 
required to complete the instruction.

7) Set the intAddr and nmiAddr to the addresses where you want mz80 to start
   executing when an interrupt or NMI happens. Take a look at the section
   entitled "INTERRUPTS" below for more information on this.

8) Call mz80SetContext() on your Z80 context

9) Call mz80Reset(). This will prime the program counter and cause a virtual
   CPU-wide reset.

10) Once you have those defined, you're ready to begin emulation. There's some
    sort of main loop that you'll want. Maybe something like:

	while (hit == 0)
	{
		if (lastSec != (UINT32) time(0))
		{
			diff = (mz80clockticks - prior) / 3000000;
			printf("%ld Clockticks, %ld frames, %ld Times original speed\n", MZ80clockticks - prior, frames, diff);
			frames = 0;
			prior = mz80clockticks;
			lastSec = time(0);
			if (kbhit())
			{
				getch();
				hit = 1;
			}
		}

		/* 9000 Cycles per NMI (~3 milliseconds @ 3MHZ) */

		dwResult = mz80exec(9000);
		mz80clockticks += mz80GetElapsedTicks(TRUE);
		mz80nmi();

		/* If the result is not 0x80000000, it's an address where
		   an invalid instruction was hit. */

		if (0x80000000 != dwResult)
		{
			mz80GetContext(&sCpu1);
			printf("Invalid instruction at %.2x\n", sCpu1.MZ80pc);
			exit(1);
		}
	}

Call mz80exec() With the # of virtual CPU cycles you'd like mz80 to
execute. Be sure to use the mz80GetElapsedTicks() call *AFTER* execution to
see how many virtual CPU cycles it actually executed. For example, if you tell
mz80 to execute 500 virtual CPU cycles, it will execute slightly more. Anything
from 500 to 524 (24 cycles being the longest any 1 instruction takes in the
Z80).

Use the mz80GetElapsedTicks() call for more accurate cycle counting. Of course,
this is only if you have *NOT* included the -nt option.

If you pass FALSE to the mz80GetElapsedTicks() function, the internal CPU 
elapsed tick clock will not be reset. The elapsed tick counter is something 
that continues to increase every emulated instruction, and like an odometer,
will keep counting unless you pass TRUE to mz80GetElapsedTicks(), of which 
case it will return you the current value of the elapsed ticks and set it to 
0 when complete.

NOTE: The bigger value you pass to mz80exec, the greater benefit you get out
of the virtual registers persisting within the emulator, and it will run
faster. Pass in a value that is large enough to take advantage of it, but
not so often that you can't handle nmi or int's properly.

If you wish to create a virtual NMI, call mz80nmi(), and it will be taken
the next time you call mz80exec, or alternately if you have a handler call
mz80nmi/mz80int(), the interrupt will be taken upon return. Note that 
mz80nmi() doesn't actually execute any code - it only primes the emulator to
begin executing NMI/INT code.

NOTE: mz80int() is defined with a UINT32 as a formal parameter. Depending 
upon what interrupt mode you're executing in (described later), it may or may
not take a value.

NMI's can interrupt interrupts, but not the other way around - just like a
real Z80. If your program is already in an interrupt, another one will not be
taken. The same holds true for an NMI - Just like a real Z80!


MUTLI-PROCESSOR NOTES
---------------------

Doing multi processor support is a bit trickier, but is still fairly straight-
forward.

For each processor to be emulated, go through steps 1-7 above - giving each
CPU its own memory space, register storage, and read/write handlers.


EXECUTION OF MULTI-CPUS:
-------------------------

When you're ready to execute a given CPU, do the following:

	mz80SetContext(contextPointer);

This will load up all information saved before into the emulator and ready it
for execution. Then execute step 7 above to do your virtual NMI's, interrupts,
etc... All CPU state information is saved within a context.

When the execution cycle is complete, do the following to save the updated
context away for later:

	mz80GetContext(contextPointer);

Give each virtual processor a slice of time to execute. Don't make the values
too small or it will spend its time swapping contexts. While this in itself
isn't particularly CPU expensive, the more time you spend executing the better.
mz80 Keeps all of the Z80 register in native x86 register (including most
of the flags, HL, BC, and A). If no context swap is needed, then you get the
added advantage of the register storage. For example, let's say you were 
running two Z80s - one at 2.0MHZ and one at 3.0MHZ. An example like this 
might be desirable:

	mz80SetContext(cpu1Context);	// Set CPU #1's information
	mz80exec(2000);		// 2000 Instructions for 2.0MHZ CPU
	mz80GetContext(cpu1Context);	// Get CPU #1's state info

	mz80SetContext(cpu2Context);	// Set CPU #2's state information
	mz80exec(3000);		// 3000 Instructions for 3.0MHZ CPU
	mz80GetContext(cpu2Context);	// Get CPU #2's state information

This isn't entirely realistic, but if you keep the instruction or timing
ratios between the emulated CPUs even, then timing is a bit more accurate.

NOTE: If you need to make a particular CPU give up its own time cycle because
of a memory read/write, simply trap a particular address (say, a write to a
slave processor) and call mz80ReleaseTimeslice(). It will not execute any 
further instructions, and will give up its timeslice. Put this in your 
read/write memory trap.

NOTE: You are responsible for "holding back" the processor emulator from
running too fast.


INTERRUPTS
----------

The Z80 has three interrupt modes: IM 0 - IM 2. Each act differently. Here's
a description of each:

IM 0

This mode will cause the Z80 to be able to pull a "single byte instruction"
off the bus when an interrupt occurs. Since we're not doing bus cycle
emulation, it acts identically to mode 1 (described below). The formal
parameter to mz80int() is ignored. There is really no point in actually 
emulating the instruction execution since any instruction that would be
executed would be a branch instruction!

IM 1

This mode is the "default" mode that the Z80 (and mz80 for that matter) comes
up in. When you call mz80reset(), the interrupt address is set to 38h and
the NMI address is set to 66h. So when you're in IM 1 and mz80int() is
called, the formal parameter is ignored and the z80intAddr/z80nmiAddr values
are appropriately loaded into the program counter.

IM 2

This mode causes the Z80 to read the upper 8 bits from the current value
of the "I" register, and the lower 8 bits from the value passed into mz80int().
So, if I contained 35h, and you did an mz80int(0x64), then an interrupt at
address 3564h would be taken. Simple!


OTHER GOODIES
-------------

MZ80 Has a nice feature for allowing the same handler to handle different
data regions on a single handler. Here's an example:

struct PokeyDataStruct Pokey1;
struct PokeyDataStruct Pokey2;

struct MemoryWriteByte GameWrite[] =
{
	{0x1000, 0x100f,  PokeyHandler, Pokey1},
	{0x1010, 0x101f,  PokeyHandler, Pokey2},
	{(UINT32) -1,     (UINT32) -1, NULL}
};

void PokeyHandler(UINT32 dwAddr, UINT8 bData, struct sMemoryWriteByte *psMem)
{
	struct PokeyDataStruct *psPokey = psMem->pUserArea;

	// Do stuff with psPokey here....
}

This passes in the pointer to the sMemoryWriteByte structure that caused
the handler to be called. The pUserArea is a user defined address that can
be anything. It is not necessary to fill it in with anything or even
initialize it if the handler doesn't actually use it.

This allows a single handler to handle multiple data references. This is
particularly useful when handling sound chip emulation, where there might
be more than one of a given device. Sure beats having multiple unique
handlers that are identical with the exception of the data area where it
writes! This allows a good deal of flexibility.

The same construct holds for MemoryReadByte, z80PortRead, and z80PortWrite,
so all can take advantage of this feature.


SHARED MEMORY FEATURES
----------------------

MZ80 Also has another useful feature for dealing with shared memory regions:

UINT8 bSharedRAM[0x100];

struct MemoryWriteByte Processor1[] = 
{
	{0x1000, 0x10ff, NULL, bSharedRAM},
	{(UINT32) -1, (UINT32) -1, NULL}
};

struct MemoryWriteByte Processor2[] = 
{
	{0x1000, 0x10ff, NULL, bSharedRAM},
	{(UINT32) -1, (UINT32) -1, NULL}
};

If the handler address is NULL, mz80 will look at the pUserArea field as a
pointer to RAM to read from/write to. This comes in extremely handy when you
have an emulation that requires two or more processors writing to the same
memory block. And it's lots faster than creating a handler that writes to
a common area as well.


DEBUGGING
---------

Several new functions have been added to mz80 that assist the emulator
author by providing a standard set of functions for register access:

UINT8 mz80SetRegisterValue(void *pContext, UINT32 dwRegister, UINT32 dwValue)

This allows setting of any register within the Z80. The register field can be
one of the following values (defined in mz80.h):

	CPUREG_PC
	CPUREG_Z80_AF
	CPUREG_Z80_BC
	CPUREG_Z80_DE
	CPUREG_Z80_HL
	CPUREG_Z80_AFPRIME
	CPUREG_Z80_BCPRIME
	CPUREG_Z80_DEPRIME
	CPUREG_Z80_HLPRIME
	CPUREG_Z80_IX
	CPUREG_Z80_IY
	CPUREG_Z80_SP
	CPUREG_Z80_I
	CPUREG_Z80_R
	CPUREG_Z80_A
	CPUREG_Z80_B
	CPUREG_Z80_C
	CPUREG_Z80_D
	CPUREG_Z80_E
	CPUREG_Z80_H
	CPUREG_Z80_L
	CPUREG_Z80_F
	CPUREG_Z80_CARRY
	CPUREG_Z80_NEGATIVE
	CPUREG_Z80_PARITY
	CPUREG_Z80_OVERFLOW
	CPUREG_Z80_HALFCARRY
	CPUREG_Z80_ZERO
	CPUREG_Z80_SIGN
	CPUREG_Z80_IFF1
	CPUREG_Z80_IFF2

Each individual register's value can be set, including the flags at the end.
The only valid values for the flags are 1 and 0. Setting these will
automatically adjust the "F" register. 

If pContext is NULL, then the registers in the currently active context are
changed. If pContext points to a non-NULL area, that area is assumed to be
a CONTEXTMZ80 structure where the new register value will be written.

If mz80SetRegisterValue() returns a nonzero value, either the register value
or register is out of range or invalid.


UINT32 mz80GetRegisterValue(void *pContext, UINT32 dwRegister)

This returns the value of the register given on input (listed above as
CPUREG_Z80_xxxxx). Flag values will be 1 or 0.

If pContext is NULL, then the registers in the currently active context are
read. If pContext points to a non-NULL area, that area is assumed to be
a CONTEXTMZ80 structure from which register values are pulled.


UINT32 mz80GetRegisterTextValue(void *pContext, UINT32 dwRegister, 
				 UINT8 *pbTextArea)

This returns the textual representation of the value of a given register.
It is a text printable string that can be used in sprintf() statements and
the like. This function is useful because different representations for
registers (like flags) can be a group of 8 flag bytes instead of a single
value.

On entry, pContext being set to NULL indicates that mz80 should get the
register value from the currently active context. Otherwise, it is assumed
to be pointing to a CONTEXTMZ80 structure, which contains the value of the
registers to be read.

pbTextArea points to a buffer where the value text can be written. This points
to a user supplied buffer.

On exit, if any nonzero value is encountered, either the register # is out
of range or pbTextArea is NULL.


UINT8 *mz80GetRegisterName(UINT32 dwRegister)

This returns a pointer to the textual name of the register passed in. NULL
Is returned if the register index (CPUREG_Z80_xxxx table described above) is
out of range. DO NOT MODIFY THE TEXT! It is static data.


FINAL NOTES
-----------

I have debugged MZ80.ASM to the best of my abilities. There might still be
a few bugs floating around in it, but I'm not aware of any. I've validated
all instructions (That I could) against a custom built Z80 on an ISA card
(that fits in a PC) so I'm quite confident that it works just like a real
Z80. 

If you see any problems, please point them out to me, as I am eager to make
mz80 the best emulator that I can. 

If you have questions, comments, etc... about mz80, please don't hesitate
to send me an email. And if you use mz80 in your emulator, I'd love to take
a look at your work. If you have special needs, or need implementation
specific hints, feel free to email me, Neil Bradley ([e-mail]). I
will do my best to help you.

Enjoy!

Neil Bradley
[e-mail]