diff --git a/cpu/cz80/readme.txt b/cpu/cz80/readme.txt new file mode 100644 index 000000000..2a5d6b069 --- /dev/null +++ b/cpu/cz80/readme.txt @@ -0,0 +1,246 @@ +************************************************ +* * +* CZ80 (Z80 CPU emulator) version 0.91 * +* Compiled with Dev-C++ * +* Copyright 2004-2005 Stéphane Dallongeville * +* * +************************************************ + +CZ80 is a Z80 CPU emulator, priorities were given to : +- code size +- speed +- accuracy +- portablity + +It supports almost all undocumented opcodes and flags. + +The emulator can be freely distribued and used for any non commercial +project as long you don't forget to credit me somewhere :) +If you want some support about the CZ80, you can contact me on +the Gens forum (http://gens.consolemul.com then go to the forum). + + +You should find the following files in the emulation pack : +- cz80.h -> header file (prototypes, declarations...) +- cz80.c -> contains emulation core itself +- cz80.inc -> contains most used macros +- cz80jmp.inc -> Jump table definition when Jump Table used +- cz80exec.inc -> contains the major Cz80_Exec(...) function +- cz80_op.inc -> contains code for simple Z80 opcodes emulation +- cz80_opCB.inc -> contains code for CB prefixed Z80 opcodes emulation +- cz80_opED.inc -> contains code for ED prefixed Z80 opcodes emulation +- cz80_opXY.inc -> contains code for DD/FD prefixed Z80 opcodes emulation +- cz80_opXYCB.inc -> contains code for DD/FD + CB prefixed Z80 opcodes emulation +- readme.txt -> the current file you're reading ;) + + +* How compile the emulator ? +**************************** + +The emulator has been written with Dev-CPP 4.9.X.X +You will maybe need to modify the u8, u16, u32, s8, s16, s32 and FASTCALL +definitions (cz80.h) according to your C compiler and the target system. +Then compile the cz80.c file, you should obtain a cz80.o (or cz80.obj) file... +at this moment, you're ready to use the emulator just by linking the file in your project :) + + +* How to use the emulator ? +*************************** + +1) Include the header file in your source : +------------------------------------------ + +#include "cz80.h" + + +2) Init the CZ80 core : +----------------------- + +If you want to use the internal CZ80 context offered : + + Cz80_Init(&CZ80); + +but you can also define your own CZ80 context : + + cz80_struc My_Z80; + + .... + + Cz80_Init(&My_Z80); + + +You'll can emulate as many Z80 CPU as you want by defining severals CZ80 contexts. + + +3) Set up your fetch region (where the Z80 will run code from) : +---------------------------------------------------------------- + + Cz80_Set_Fetch(&CZ80, 0x0000, 0x7FFF, (u32) your_ROM); + Cz80_Set_Fetch(&CZ80, 0xA000, 0xFFFF, (u32) your_RAM); + ... + + +4) Set up your memory (where the Z80 will read and write data) : +---------------------------------------------------------------- + + Cz80_Set_ReadB(&CZ80, your_z80readbyte_function); + Cz80_Set_WriteB(&CZ80, your_z80readbyte_function); + +You can improve CZ80 performance by using WORD read/write function. +For that, you need to enable the 'CZ80_USE_WORD_HANDLER' define in cz80.h file. +In this case, you'll need to add that : + +#if CZ80_USE_WORD_HANDLER + Cz80_Set_ReadW(&CZ80, your_z80readword_function); + Cz80_Set_WriteW(&CZ80, your_z80readword_function); +#endif + +Your read function need to be of CZ80_READ type : +typedef u32 FASTCALL CZ80_READ(u32 adr); + +Your write function need to be of CZ80_WRITE type : +typedef void FASTCALL CZ80_WRITE(u32 adr, u32 data); + + +5) Set Up your port (where the Z80 will read and write IO data) : +----------------------------------------------------------------- + + Cz80_Set_INPort(&CZ80, your_z80readport_function); + Cz80_Set_OUTPort(&CZ80, your_z80writport_function); + +Your readPort function need to be of CZ80_READ type : +typedef u32 FASTCALL CZ80_READ(u32 adr); + +Your writePort function need to be of CZ80_WRITE type : +typedef void FASTCALL CZ80_WRITE(u32 adr, u32 data); + + +6) Set Up your interrupt callback function : +-------------------------------------------- + + Cz80_Set_IRQ_Callback(&CZ80, your_z80irqcallback_function); + +Your IRQ callback function need to be of CZ80_INT_CALLBACK type : +typedef s32 FASTCALL CZ80_INT_CALLBACK(s32 param); + +If you don't understand what i am talking about here, just ignore... +it's not needed in almost case. + + +6) Set Up your RETI callback function : +--------------------------------------- + + Cz80_Set_RETI_Callback(&CZ80, your_z80reticallback_function); + +Your RETI callback function need to be of CZ80_RETI_CALLBACKtype : +typedef void FASTCALL CZ80_RETI_CALLBACK(); + +Again, if you don't understand what i am talking about here, ignore... + + +7) Reset the CZ80 core before fisrt use : +----------------------------------------- + + Cz80_Reset(&CZ80); + + +8) Do some cycles : +------------------- + +Then it's time to really do some work, if you want to execute 1000 cycles, just do : + + cycles_done = Cz80_Exec(&CZ80, 1000); + +Cz80_Exec function return the number of cycles actually done. +Since each instruction take more than 1 cycle, Cz80_Exec will execute a bit more than +you requested, for instance here, it can return 1008 cycles instead of 1000. +In this case, adjust the number of cycle to do like that : + + cycles_by_frame = 4800; + extra_cycles = 0; + while (true) + { + ... + extra_cycles = CZ80_Exec(&CZ80, cycles_by_frame - extra_cycles) - cycles_by_frame; + ... + } + +If Cz80_Exec returns a negatif value, an error occured. + + +9) Do an interrupt request : +---------------------------- + + Cz80_Set_IRQ(&CZ80, 0); + +or for a NMI : + + Cz80_Set_NMI(&CZ80); + + +10) Cancel an interrupt request : +--------------------------------- + + Cz80_Clear_IRQ(&CZ80); + +or for a NMI : + + Cz80_Clear_NMI(&CZ80); + + + +* Switchs +********* + +There are severals switchs in the cz80.h file which permit you to configure +CZ80 depending your needs. + +- CZ80_FETCH_BITS (default = 4) + +This defines the number of bits to select fetch region. +This value must be 4 <= X <= 12 +Greater value offers permit to have more fetch region. +In almost case, 4 is enough, but if you have fetch region smaller than 0x1000 bytes, +increase this value. + +- CZ80_LITTLE_ENDIAN + +Define the endianess of the target platform. +x86 CPU use Little Endian. + +- CZ80_USE_JUMPTABLE + +Set it to 1 to use Jump table instead of big case statement. +This can bring some small speed improvemen. +Be careful, some compiler doesn't support (computed label) so it's +saffer to not use it. + +- CZ80_SIZE_OPT + +Add some extras optimisation for the code size versus speed. +Minor changes anyway... + +- CZ80_USE_WORD_HANDLER + +See the "Set Up Memory" section for more détail. + +- CZ80_EXACT + +Enable accurate emulation of extended undocumented opcode and flags. +minor speed decrease when activated. +Even without that flag, CZ80 is already uite accurate, keep it +disable unless you need it or if speed isn't important for you. + +- CZ80_DEBUG + +Used by me, keep it disable :p + + + +* History +********* + +Version 0.90 : +-------------- + +* Initial release for debugging purpose ^^