Multi-Z80 32 Bit emulatorCopyright 1996, 1997, 1998, 1999, 2000 - Neil Bradley, All rights reserved			    MZ80 License agreement			    -----------------------(MZ80 Refers to both the assembly code emitted by makez80.c and makez80.citself)MZ80 May be distributed in unmodified form to any medium.MZ80 May not be sold, or sold as a part of a commercial package withoutthe express written permission of Neil Bradley (neil@synthcom.com). Thisincludes shareware.Modified versions of MZ80 may not be publicly redistributed without authorapproval (neil@synthcom.com). This includes distributing via a publiclyaccessible LAN. You may make your own source modifications and distributeMZ80 in source or object form, but if you make modifications to MZ80then it should be noted in the top as a comment in makez80.c.MZ80 Licensing for commercial applications is available. Please emailneil@synthcom.com for details.Synthcom Systems, Inc, and Neil Bradley will not be held responsible forany damage done by the use of MZ80. It is purely "as-is".If you use MZ80 in a freeware application, credit in the following text:"Multi-Z80 CPU emulator by Neil Bradley (neil@synthcom.com)"must accompany the freeware application within the application itself orin the documentation.Legal stuff aside:If you find problems with MZ80, please email the author so they can getresolved. If you find a bug and fix it, please also email the author sothat those bug fixes can be propogated to the installed base of MZ80users. If you find performance improvements or problems with MZ80, pleaseemail the author with your changes/suggestions and they will be rolled inwith subsequent releases of MZ80.The whole idea of this emulator is to have the fastest available 32 bitMulti-Z80 emulator for the x86, giving maximum performance.                          MZ80 Contact information			  -------------------------Author      : Neil Bradley (neil@synthcom.com)Distribution: ftp://ftp.synthcom.com/pub/emulators/cpu/makez80.zip (latest)You can join the cpuemu mailing list on Synthcom for discussion of NeilBradley's Z80 (and other) CPU emulators. Send a message to "cpuemu-request@synthcom.com" with "subscribe" in the message body. Thetraffic is fairly low, and is used as a general discussion and announcementfor aforementioned emulators.			     MZ80 Documentation			     -------------------MZ80 Is a full featured Z80 emulator coded in 32 bit assembly. It runs wellover a hundred games, in addition to it supporting many undocumented Z80instructions required to run some of the Midway MCR games, Galaga, andcountless other wonderful Z80 based arcade games.MZ80 Contains a makez80.c program that must be compiled. It is the programthat emits the assembly code that NASM will compile. This minimizes thepossibility of bugs creeping in to MZ80 for the different addressing modesfor each instruction. It requires NASM 0.97 or greater.The goal of MZ80 is to have a high performance Z80 emulator that is capableof running multiple emulations concurrently at full speed, even on lower-endmachines (486/33). MZ80 Harnesses the striking similarities of both the Z80and the x86 instruction sets to take advantage of flag handling which greatlyreduces the time required to emulate a processor, so no extra time is spentcomputing things that are already available in the native x86 processor,allowing it to perform leaps and bounds over comparable C based Z80 emulatorson the same platform.MZ80 Is designed exclusively for use with NASM, the Netwide Assembler. Thisgives the ultimate in flexibility, as NASM can emit object files that workwith Watcom, Microsoft Visual C++ (4.0-current), DJGPP, Borland C++, andgcc under FreeBSD or Linux. MZ80 Has been tested with each one of thesecompilers and is known to work properly on each.			    What's in the package			    ---------------------MZ80.TXT               - This text fileMAKEZ80.C              - Multi Z80 32 Bit emulator emitter programMZ80.H                 - C Header file for MZ80 functions			  What's new in this release			  --------------------------Revision 3.3:	* Undocumented opcodes added to the C emitter	* Bug fix to the C emission that properly handles shared RAM regions	  (I.E. with handlers that are NULL)	* Now using 32 bit registers to do register/memory access. Slight	  speed increase (assembly version only)Revision 3.2:		* R Register emulation now accurate with a real Z80	* mz80int() Called when interrupts are disabled causes the	  z80intPending flag to be set, and an interrupt will be caused after	  the execution of EI and the next instruction. See "IMPORTANT NOTE	  ABOUT INTERRUPTS" below	* The instruction after EI executes fully before interrupt status is	  checked. (as does a real Z80)Revision 3.1:	* Fixed bug in memory dereference when handler was set to NULL (keeps	  system from crashing or faulting)	* Removed the only stricmp() from the entire file and replaced it	  with strcmp() so that stdlibs without it will compile	* Changed cyclesRemaining > 0 to cyclesRemaining >= 0 to be compatible	  with the ASM core	* Removed additional sub [dwCyclesRemaining], 5 at the beginning of	  mz80exec() (ASM Core only). Increases timing accuracy.	* NMIs And INTs add additional time to dwElapsedTicks as it should	* mz80ReleaseTimeslice() Sets remaining clocks to 0 instead of 1Revision 3.0:	* All instructions validated against a real Z80. Used an ISA card	  with a Z80 on it to validate flag handling, instruction handling,	  timing, and other goodies. The only thing not implemented/emulated	  is flag bit 3 & 5 emulation. Believed to be 100% bug free!	* 80% Speed improvement over version 2.7 of mz80	* z80stb.c Removed. Use -c to emit a C version of mz80! API compatible!	  Note that this is mostly, but not fully, debugged, so consider the	  C version a beta! It's at least healthier than z80stb.c was. The C 	  version does not include the undocumented Z80 instructions.	* mz80nmi() No longer trashes registers it uses when using -cs	* IN/OUT Instructions work properly when using -16	* IN A, (xxh) uses A as high 8 bits of I/O fetch address when using -16	* IM 0/IM 1 Description in documentation fixed	* Sizes of all context registers increased to 32 bits - for speed!	* IFF1/IFF2 Now properly emulated	* JR Instruction offset can fetch from $ffff and properly wrap	* LDIR/LDDR Instruction now won't go to completion - instead it will	  run until BC=0 or the # of cycles to execute have expired. These	  instructions used to run to completion - even beyond the # of cycles	  left to execute	* INI/IND/INIR/INDR countdown bug fixed - it was decrementing B twice	  for each IN! Whoops!	* If you specify NULL as a handler address to a memory region, mz80 will	  use vpData as a pointer to where that block of data resides. Quite	  useful for multiprocessor emulations that share the same memory.	* EDI Now keeps track of cycle counting for faster execution	* Modified memory region scanning code to use 32 bit registers instead	  of their 16 bit counterparts	* Get/SetContext() uses rep movsd/movsb. Insignificant overall, but	  why waste the time?	* Debugging routines added. See the "DEBUGGING" section below for more	  information. NOTE: The debugging routines are not yet available in	  the C emission.	* Timing done slightly differently now. Mz80 now executes one 	  instruction past the timing given on input. For example, mz80exec(0)	  will cause a single instruction to be executed (thusly -ss was	  removed).Revision 2.7:	* Fixed OTIR/OTDR/INIR/INDR instructions so their 16 bit counterparts	  work properly	* Emulation core 30-70% faster overall than 2.6 due to optimization to	  the timing routines	* Replaced word reads/writes with a special word write routine rather	  than the standard calling to read/write byte functions	* z80stb.c (the C equivalent of mz80) compiles properly now	* Fixed OS/2 text/segment issue	* Fixed bug in set/getCPU context that ensures that ES=DS and avoids	  crashes. Caused crashes under OS/2 and other OS'sRevision 2.6:	* Emulator core 5-30% faster overall. Some 16 and 8 bit instructions	  sped up when using their 32 bit equivalents.	* Fix to -l so that proper labels without leading and trailing 	  underscores so Linux/FreeBSD compiles will work properly	* Single step now executes the # of instructions passed in to z80exec()	  instead of just 1 as it had in prior releases. This is only active	  when the -ss option is used.	* The -nt option was added. This will cause the timing information to	  not be added in, speeding up execution. Warning: Only do this if your	  emulated target does not require instruction timing!	* Updated documentation errors	* C Version of mz80 (mz80.c) that is API compliant is distributed with	  the archive (With kind permission of Edward Massey).Revision 2.5:	* Fixed an unconditional flag being cleared in the ddcbxx instructions.	  It caused Donkey Kong's barrels to not roll.Revision 2.4:	* Fixed improper HALT handling (didn't advance the PTR when it should)	* Fixed SRL (IX+$xx) instruction so that carry wasn't trashed	* Fixed single stepping problems with it giving too much time to 	  any given instruction	* Fixed half carry flag handling with 16 bit SBC and ADD instructions	* Fixed DAA emulation so that parity flags weren't getting trashedRevision 2.3:	* Fixed many stack handling bugs	* Timing problems fixed. The prior version was causing massive 	  overruns on maximum timeslices with some insutructions.Revision 2.2:	* Fixed a bug in CPI/CPD/CPIR/CPDR that mishandled flags	* All known bugs are out of mz80 now	* Added the -cs option to route all stack operations through the	  handlers (required for games like Galaga)Revision 2.1:	* Fixed a bug in CPI/CPD/CPIR/CPDR that caused intermittent lockups.	  Also fixed a bug that caused erratic behavior in several video games.	* Added INI/IND/INIR/INDR instruction group	* Added OUTI/OUTD/OTIR/OTDR instruction groupRevision 1.0:	* First release! The whole thing is new!ASSEMBLING FOR USE WITH WATCOM C/C++------------------------------------Watcom, by default, uses register calling conventions, as does MZ80. Tocreate a proper emulator for Watcom:	makez80 MZ80.asm -x86From here:	nasm -f win32 MZ80.asmLink the MZ80.obj with your Watcom linker.ASSEMBLING FOR USE WITH MICROSOFT VISUAL C++ AND BORLAND C++--------------------------------------------------------------------Visual C++ and Borland C++ use stack calling conventions by default. Tocreate a proper emulator for these compilers:	makez80 MZ80.asm -s -x86For Visual C++ or Borland C++:	nasm -f win32 MZ80.asmLink with your standard Visual C++ or Borland C++.ASSEMBLING FOR USE WITH DJGPP, GCC/FREEBSD, OR GCC/LINUX--------------------------------------------------------------------DJGPP Uses stack calling conventions:	makez80 MZ80.asm -s -x86To assemble:	nasm -f coff MZ80.asmLink with your standard DJGPP linker. The same holds true for GCC underFreeBSD or Linux. If you're using GCC, use the -l option to generate "plain"labels so that gcc's linker will properly link things.MAKEZ80 COMMAND LINE OPTIONS-----------------------------s	- Use stack calling conventions (DJGPP, MSVC, Borland, etc...)-cs	- Force all stack operations to go through the Read/Write memory handlers.	  This slows things down, but is useful when needed.-16	- Treat all I/O input and output as 16 bit (BC)-l	- Create 'plain' labels - ones without leading and trailing underscores-nt	- Do not generate timing code - this speeds the emulator up, but the	  downside is that no timing info is available.-c	- Emit a C mz80 emulator (API Compatible with the assembly version - 	  handy for porters!)-x86	- Emit an assembly (x86) mz80 emulator-os2	- Generate OS/2 compatible segmentationIMPORTANT NOTE ABOUT INTERRUPTS-------------------------------A minor change was made between the 3.1 and 3.2 versions of makez80 in theway that interrupts were handled.On a real Z80, the !INT line is a level triggered interrupt, meaning that ifthe interrupt line is held low, the Z80 will continue to take interrupts immediately after the instruction after the EI instruction is executed untilthe interrupt line is high again.In 3.1, if an interrupt came in and interrupts were disabled, the interruptwould never be "latched" for later execution. The Z80 does not have anyinternal latching capabilities, however external hardware often does holdthe interrupt line low until the interrupt is executed, in effect, a latch.I've only found one video game so far that requires the "raising/lowering"of the interrupt line (Ataxx). In the games that I've tried, it has improvedperformance, in some cases drastically, and in others not at all. This canbe accounted for by interrupts being taken now, where they were being droppedin prior mz80 releases.mz80 Emulates the most commonly used scenario. Now when mz80int() is executedand a nonzero value is returned (indicating interrupts were disabled), itwill set z80intPending, and the interrupt will be taken after execution ofone instruction beyond the EI instruction.So now, if mz80int() returns a nonzero value, that means an interrupt islatched. If clearing this latch is desired or the old behavior of 3.1 is desired, make a call to the mz80ClearPendingInterrupt() call. It's a 2 instruction call that has extremely small overhead and will not affect performance in any measurable way.In any case, MZ80 will now execute one instruction after EI regardless ofhow much time is available to avoid the possibility of an interrupt requestcoming in directly after the EI instruction. STEPS TO EMULATION------------------NOTE: -16 Is a command line option that will treat all I/O as 16 bit. Thatis, in an instruction like "IN AL, (C)", the addressed passed to the I/Ohandler will be BC instead of just C. Bear this in mind when considering youremulated platform.There are a few steps you want to go through to get proper emulation, and afew guidelines must be followed.1) Create a MZ80CONTEXT2) Create your virtual 64K memory space using whatever means of obtaining   memory you need to do.3) Set mz80Base in your context to be the base of your 64K memory space4) Load up your image to be emulated within that 64K address space.5) Set z80IoRead and z80IoWrite to their appropriate structure arrays. Here's   an example:struct z80PortRead ReadPorts[] ={	{0x10,	0x1f,	SoundChip1Read},	{0x20,	0x2f,	SoundChip2Read}	{(UINT32) -1,     (UINT32) -1, NULL}};When an IN instruction occurs, mz80 will probe this table looking for ahandler to the address of the "IN" instruction. If it is found in the list,it's up to the handler to return the proper value. Otherwise, a value of0ffh is returned internally if no handler for that I/O address is found. Inthe case above, SoundChip1Read is called when the I/O address is between 0x10-0x1f. A similar structure is used for I/O writes as well (OUT):struct z80PortWrite WritePorts[] ={	{0x20,	0x2f,	SoundChip2Write},	{0x30,	0x36,	VideoCtrlWrite},	{(UINT32) -1, 	(UINT32) -1, NULL}}Of course, this does the opposite that the z80PortRead struct, and insteadlooks for a handler to hand some data to. If it doesn't find an appropriatehandler, nothing happens.6) Set mz80MemoryRead & mz80MemoryWrite to their appropriate structure   arrays. Here is an example:struct MemoryWriteByte GameWrite[] ={