C89 MSVC doesn't support 'inline' - will have to make define for

[picodrive.git] / cpu / DrZ80 / DrZ80.txt

\r
___________________________________________________________________________\r
\r
  DrZ80 (c) Copyright 2004 Reesy.   Free for non-commercial use\r
\r
  Reesy's e-mail: drsms_reesy(atsymbol)yahoo.co.uk\r
  Replace (atsymbol) with @\r
  \r
___________________________________________________________________________\r
\r
\r
What is it?\r
-----------\r
\r
DrZ80 is an emulator for the Z80 microprocessor, written in ARM 32-bit assembly.\r
It is aimed at chips such as ARM7 and ARM9 cores, StrongARM and XScale, to interpret Z80\r
code as fast as possible.\r
\r
Flags are mapped onto ARM flags whenever possible, which speeds up the processing of an opcode.\r
\r
ARM Register Usage\r
------------------\r
\r
See source code for up to date of register usage, however a summary is here:\r
\r
  r0-3: Temporary registers\r
  r3  : Pointer to Opcode Jump table\r
  r4  : T-States remaining\r
  r5  : Pointer to Cpu Context\r
  r6  : Current PC + Memory Base (i.e. pointer to next opcode)\r
  r7  : Z80 A Register in top 8 bits (i.e. 0xAA000000)\r
  r8  : Z80 F Register (Flags) (NZCV) in lowest four bits\r
  r9  : Z80 BC Register pair in top 16 bits (i.e. 0xBBCC0000)\r
  r10 : Z80 DE Register pair in top 16 bits (i.e. 0xDDEE0000)\r
  r11 : Z80 HL Register pair in top 16 bits (i.e. 0xHHLL0000)\r
  r12 : Z80 Stack + Memory Base (i.e. pointer to current stack in host system memory)\r
\r
( note: r3,r12 are always preserved when calling external memory functions )\r
\r
How to Compile\r
--------------\r
\r
The core is targeted for the GNU compiler, so to compile just add the "DrZ80.o" object\r
to your makefile and that should be it.\r
\r
If you want to compile it seperately, use:  as -o DrZ80.o DrZ80.s\r
\r
( note: If you want to use DrZ80 with a different compiler you will need to run\r
        some sort of parser through the source to make the syntax of the source\r
	compatible with your target compiler )\r
\r
\r
Adding to your project\r
----------------------\r
\r
To add DrZ80 to your project, add DrZ80.o, and include DrZ80.h\r
There is one structure: 'struct DrZ80', and  three functions: DrZ80Run,DrZ80RaiseInt\r
and DrZ80_irq_callback.\r
\r
Don't worry if this seem very minimal - its all you need to run as many Z80s as you want.\r
It works with both C and C++.\r
\r
( Note: DrZ80_irq_callback is just a pointer to an irq call back function that needs\r
        to be written by you )\r
\r
Declaring a Memory handlers\r
---------------------------\r
\r
Before you can reset or execute Z80 opcodes you must first set up a set of memory handlers.\r
There are 8 functions you have to set up per CPU, like this:\r
\r
  unsigned int z80_rebaseSP(unsigned short new_sp);\r
  unsigned int z80_rebasePC(unsigned short new_pc);\r
  unsigned char z80_read8(unsigned short a);\r
  unsigned short z80_read16(unsigned short a);\r
  void z80_write8(unsigned char d,unsigned short a); \r
  void z80_write16(unsigned short d,unsigned short a); \r
  unsigned char z80_in(unsigned char p);\r
  void z80_out(unsigned char p,unsigned char d);\r
  \r
You can think of these functions representing the Z80's memory bus.\r
The Read and Write functions are called whenever the Z80 reads or writes memory.\r
The In and Out functions are called whenever the Z80 uses the I/O ports.\r
The z80_rebasePC and z80_rebaseSP functions are to do with creating direct memory\r
pointers in the host machines memory, I will explain more about this later.\r
\r
Declaring a CPU Context\r
-----------------------\r
\r
To declare a CPU simple declare a struct Cyclone in your code. For example to declare\r
two Z80s:\r
\r
  struct DrZ80 MyCpu;\r
  struct DrZ80 MyCpu2;\r
\r
It's probably a good idea to initialise the memory to zero:\r
\r
  memset(&MyCpu, 0,sizeof(MyCpu));\r
  memset(&MyCpu2,0,sizeof(MyCpu2));\r
\r
Next point to your memory handlers:\r
\r
  MyCpu.z80_rebasePC=z80_rebasePC;\r
  MyCpu.z80_rebaseSP=z80_rebaseSP;\r
  MyCpu.z80_read8   =z80_read8;\r
  MyCpu.z80_read16  =z80_read16;\r
  MyCpu.z80_write8  =z80_write8;\r
  MyCpu.z80_write16 =z80_write16;\r
  MyCpu.z80_in      =z80_in;\r
  MyCpu.z80_out     =z80_out;\r
\r
Now you are nearly ready to reset the Z80, except you need one more function: checkpc().\r
\r
The z80_rebasePC() function\r
---------------------------\r
\r
When DrZ80 reads opcodes, it doesn't use a memory handler every time, this would be\r
far too slow, instead it uses a direct pointer to ARM memory.\r
For example if your Rom image was at 0x3000000 and the program counter was $206,\r
Cyclone's program counter would be 0x3000206.\r
\r
The difference between an ARM address and a Z80 address is also stored in a variable called\r
'pc_membase'. In the above example it's 0x3000000. To retrieve the real PC, DrZ80 just\r
subtracts 'pc_membase'.\r
\r
Everytime the Z80 PC is modified, i.e. by a jump,branch intructions or by an interupt, DrZ80\r
calls the z80_rebasePC function. If the PC is in a different bank, for example Ram instead \r
of Rom, change 'pc_membase', recalculate the new PC and return it.\r
\r
The z80_rebaseSP() function\r
---------------------------\r
\r
When DrZ80 pushs/pops to the Z80 stack pointer, it doesn't use a memory handler every time.  In\r
order to gain more speed a direct pointer to ARM memory is used.  For example if your Ram was at \r
0x3000000 and the z80 stack pointer counter was 0xD000, DrZ80's stack pointer would be 0x300D000.\r
\r
The difference between an ARM address and a Z80 address is also stored in a variable called\r
'sp_membase'. In the above example it's 0x3000000. To retrieve the real SP, DrZ80 just\r
subtracts 'sp_membase'.\r
\r
Everytime the Z80 SP is modified ( i.e. set with a new value LD SP,NN etc ) DrZ80\r
calls the z80_rebaseSP function. If the SP is in a different bank, for example Rom instead \r
of Ram, change 'sp_membase', recalculate the new SP and return it.\r
\r