home *** CD-ROM | disk | FTP | other *** search
/ Gold Fish 2 / goldfish_vol2_cd1.bin / files / misc / emu / z80 / z80.doc < prev    next >
Encoding:
Text File  |  1993-12-21  |  11.8 KB  |  270 lines
  1.  
  2.     Zilog Z80 CPU emulator package for the Motorola M68000 family.
  3.  
  4.     Version 0.99b
  5.  
  6.     (C) Copyright 1993 Richard Carlsson
  7.  
  8.     Author: Richard Carlsson
  9.  
  10.     E-Mail: m90rca @ tdb.uu.se (Uppsala University, Sweden)
  11.     Mail: Solgatan 58, 195 55  Maersta, Sweden.
  12.  
  13.  
  14.     The emulator package is freeware. It may be distributed freely as long
  15.     as nothing is charged for the distribution beyond the actual costs of
  16.     media and transfer. If the package is used in a program, the same rules
  17.     for distribution must apply to that program unless the rights to charge
  18.     a fee have been explicitly obtained from the author.
  19.  
  20.     That should cover just about everything. If you include the emulator in
  21.     a project, I would like to hear about it. Please always inform me if
  22.     you release such a project as public domain or freeware.
  23.  
  24.     I have done my best to make the emulator as flexible as possible. The
  25.     interface should be easy to understand and use, from C as well as from
  26.     assembler. The C stubs and the header file Z80.h should make it easy to
  27.     use the emulator from a shell written in C. (As I have done myself.)
  28.     Please report any bugs, assembler or machine incompatibilities, or mere
  29.     stupidity in my code, and I shall fix it as soon as possible. You are
  30.     of course also welcome to present new ideas, but please read the file
  31.     cache.txt before you attempt to improve the emulation method itself.
  32.  
  33.     The other goal of this project has been emulation speed. There are
  34.     Z80 emulators that may be even more flexible and accurate in emulation
  35.     than this one, but I know of no one that is also this fast.
  36.  
  37.     This program is a tribute to Sir Clive Sinclair.
  38.  
  39.     Credits:
  40.  
  41.     To Peter McGavin, for the basic idea of using threaded code,
  42.     for a lot of idea bouncing and testing, and for giving me new
  43.     inspiration to finish this old project. Also to Linus and Oliver
  44.     for starting this whole business. See the history below.
  45.  
  46.  
  47.     Examples of emulation speed:
  48.  
  49.         Run on processor    Corresponds to    Hz factor
  50.  
  51.     Full-featured version:
  52.         68000, 7.16 MHz     0.52 MHz Z80    0.073
  53.         68030, 40 MHz        3.3 MHz Z80     0.083
  54.  
  55.     Stripped "games" version:
  56.         68000, 7.16 MHz     0.67 MHz Z80    0.094
  57.         68030, 40 MHz        3.8 MHz Z80     0.095
  58.  
  59.     The tests were run on an Amiga, with the system up and running,
  60.     and lots of other tasks loaded (most of them in waiting state).
  61.     To find out what the emulator would correspond to on your machine,
  62.     multiply the frequency of your processor with the "Hz factor". For
  63.     instance, a 33 MHz 68030 running the full version gives 33 * 0.083
  64.     -> 2.7 MHz Z80. Of course this will vary with different memory
  65.     configurations etc.
  66.  
  67.  
  68.     Main files of interest:
  69.  
  70.     Z80.a        The main emulator source file.
  71.     Z80.i        Include file for using the emulator.
  72.     Z80_struct.i    Include file defining the control structure.
  73.     Z80_coding.i    Include file with definitions needed to code the
  74.               Z80 instruction emulation routines.
  75.     extern_instr.a    File for external compilation of implementation-
  76.               specific Z80 instructions like In/Out.
  77.     generic_macs.i    Include file defining the implementation-specific
  78.               Z80 instructions (generic versions).
  79.     user.i        User definitions.
  80.     Z80.h        Header file for using the emulator from C.
  81.     c_stubs.a    File defining the assembler stubs for calling
  82.               the emulator functions from C.
  83.     files        A more detailed description of all included files.
  84.  
  85.     Use:
  86.  
  87.       Includes/header files
  88.  
  89.     Assembler:
  90.     All constants and cross-references are defined in Z80.i. The
  91.     control structure, offsets and size, are defined in Z80_struct.i.
  92.     The function calls are documented in Z80.i.
  93.  
  94.     C:
  95.     Constants, function prototypes and documentation, structure
  96.     declarations and so on are all defined/declared in Z80.h.
  97.  
  98.       Allocating memory
  99.  
  100.     The emulator needs several areas of memory to execute:
  101.                 Size        Comment
  102.       * Z80 address space    Z80_MEMSIZE
  103.       * Cache memory    Z80_CACHESIZE    Must be word-aligned
  104.       * Control structure    Z80_StructSize    Must be word-aligned.
  105.  
  106.     If the memory write access checking feature is used, memory for the
  107.     control flags is also needed:
  108.       * Flag memory     Z80_FLAGMEMSIZE
  109.  
  110.     Z80_MEMSIZE and Z80_FLAGMEMSIZE are approx. 64 K each.
  111.     Z80_CACHESIZE is approx. 128 K. The control structure takes about
  112.     500 bytes.
  113.  
  114.       Setting up before coldstart
  115.  
  116.     Set the fields Z80_Memory and Z80_Cachemem of the control
  117.     structure to point to the corresponding memory areas. If memory
  118.     checking is used, set the Z80_Flagmem field to point to the flag
  119.     memory, or to zero if the feature is not used.    Also set the field
  120.     Z80_MemHandler to the address of a user-defined memory exception
  121.     handler routine, or to zero if no such routine exists.
  122.       After that, call Z80_Init to initialise the remaining fields of
  123.     the control structure. The user environment data area is not
  124.     affected.
  125.       Call Z80_SetMemFlag to flag any memory areas before start.
  126.     Documentation on the flags and the User Exception Handler Call can
  127.     be found in Z80.i. Other helper functions could for instance be
  128.     used to initialise the memory before start.
  129.  
  130.       Coldstart
  131.  
  132.     A coldstart does a CPU reset as it starts the emulation. When (and
  133.     if) the emulation exits (see Exit emulation below), you may inspect
  134.     and even change the public fields of the control structure, where
  135.     the Cpu Status entries are the most interesting ones.
  136.  
  137.       Continuing emulation
  138.  
  139.     Call Z80_Continue each time you want the emulation to proceed
  140.     with the information in the Cpu Status entries. Z80_Init sets up
  141.     these entries as after a CPU reset. For no other fields of the
  142.     control structure are changes guaranteed to have any effect when
  143.     calling Z80_Continue directly afterwards (see Reallocating Memory
  144.     Areas below).
  145.  
  146.       Exit emulation
  147.  
  148.     Presently, the only way to exit the emulator is to call
  149.     Z80_EXITreq from an outside task or interrupt routine. I intend
  150.     to make it possible to patch Z80 instructions (particularly
  151.     undefined ones) to take on special meanings, like EXIT. It will
  152.     then be possible for the task running the emulator to return "by
  153.     its own will".
  154.  
  155.       Reallocating memory areas
  156.  
  157.     To inform the emulator that changes to the public fields like
  158.     the memory pointers have taken place, call Z80_NewSettings.
  159.     Calling Z80_Continue will then proceed using the new locations
  160.     (see Continuing emulation above). Do not move a memory area or
  161.     call Z80_NewSettings before the emulation has stopped (inspect
  162.     the Running field of the control structure).
  163.       The control structure may be moved without calling Z80_Realloc,
  164.     since its address is always passed as a parameter.
  165.  
  166.     Compilation:
  167.  
  168.     The main emulator file Z80.a and its associated files are written
  169.     in Devpac 3 (and mostly Devpac 2 compatible) macro assembler
  170.     syntax. The main not generally compatible feature is the local
  171.     labels, which are on the form .<label> (that is, an identifier
  172.     beginning with a dot).
  173.       Compilation of Z80.a can be to either a single stand-alone object
  174.     file containing the whole emulator function package, or to a
  175.     generic object file that needs external labels (see the section on
  176.     In/Out and other implementation-dependent instructions below).
  177.  
  178.       The include files Z80.i and Z80_struct.i as well as the files
  179.     external_instr.a, generic_macs.i, Z80_coding.i and c_stubs.a are in
  180.     a more standardized macro assembler form.
  181.       All user definitions are to be entered in user.i.
  182.       Compiling the C stubs should be straightforward. Check with your
  183.     C compiler manual to see if they are behaving as they should.
  184.  
  185.     I/O instructions and other implementation-dependent behaviour:
  186.  
  187.     All instructions that are involved with external signalling and I/O
  188.     and generally depend on your environment, should be possible to
  189.     redesign fairly easily with only a small amount of knowledge about
  190.     the internal workings of the emulator. The prototypical examples in
  191.     generic_macs.i are probably not exactly what you want, so:
  192.     Copy the file generic_macs.i to a file machine_macs.i, and edit the
  193.     macros in it. Set Z80_ENV_SIZE (see Z80.i) to suit your needs, and
  194.     modify any compilation flags in the file you are compiling. Then
  195.     recompile (to object code) either the file external_instr.i (to
  196.     link with a 'generic object' emulator object file), or the main
  197.     emulator file Z80.a itself (see the compilation flags in Z80.a).
  198.  
  199.     Coding rules:
  200.     Every instruction routine must end with a call of the "next" macro.
  201.     Always use the putsr/getsr macros to access the 68000 flags.
  202.     Always use the getz/putz macros to access the Z80 memory, even if
  203.     you only change a single bit or simply clear a byte.
  204.     On entering the instruction routine, the PPC (Pseudo-PC) points to
  205.     the word corresponding to the byte following the first byte of the
  206.     opcode. Use the getRPC macro to translate the PPC into a Real-PC
  207.     Z80 address.
  208.     The Z80_Envdata structure is there for quick access relative to the
  209.     TableB register. It is provided for use by the implementation-
  210.     dependent instruction routines.
  211.     "Use the source". The generic macros should be easy to modify.
  212.     All macros are defined in Z80_coding.i, and are described there.
  213.  
  214.  
  215.     History:
  216.  
  217.     Somewhere around 1987/88, Linus Eklund gets the bizarre idea of
  218.     turning a multitasking Amiga 500 into a single-tasking "the machine
  219.     is all yours" system with a Basic-like language and a full-screen
  220.     editor with a horrible font (the Sinclair ZX Spectrum 8x8 pixel
  221.     font, "because it was easy to obtain a hex listing of it").
  222.       Some time later, he stepped up the project to actually emulate
  223.     Z80 instructions (so he could run the Spectrum ROM code, which would
  224.     spare him the writing of an own Basic interpreter).  He did a
  225.     straight fetch-decode-jump emulation and implemented the more common
  226.     instructions (he ran a statistics program on the 'Hungry Horace'
  227.     program file).
  228.       Around 1989 a friend, Oliver Waldegg, joined in and together they
  229.     got an emulator going that successfully emulated (in multi-coloured
  230.     bitmap on a white background) exactly one game - Hungry Horace.
  231.       In September 1990, I (Richard Carlsson) bought an Amiga to upgrade
  232.     from my old 48K ZX Spectrum, on which I had been hacking for many
  233.     years. I got interested in this emulator thing and began to work on
  234.     it. I made some progress, improving the emulation a bit, and
  235.     implementing all official instructions, but mostly on emulating the
  236.     Spectrum hardware.
  237.       Some time in 1991, I downloaded a ZX Spectrum emulator from the
  238.     internet. It was written by Peter McGavin, whom I contacted. He had
  239.     shown that using a translation cache (my term), or 'threaded code',
  240.     was not only possible, but also faster than the fetch-decode-jump
  241.     method. I got extremely interested in this, which totally ruined my
  242.     studies at the university for that year, but I managed to improve
  243.     his method and extend it to also caching prefixed instructions.
  244.     (Don't mail him to say "did you know that..." - he is also using
  245.     the improved method now.) See the file cache.txt if you are
  246.     interested in the (rather hairy) details.
  247.       Seeing that Peters emulator was more or less doing what I had
  248.     intended mine to do, I changed my goal to be a pure Z80 emulator
  249.     package that could be included in any Z80-based emulation project
  250.     on a 680x0, while retaining maximal speed of emulation.
  251.       Having a somewhat stable version running, I put it on the shelf
  252.     in April 1992 and got back to studying. I did not touch it again
  253.     until July 1993, when I had recovered sufficiently.
  254.  
  255.     Released versions:
  256.       0.99b  October 1993.    Developing version number 32.
  257.     All code can be shared.
  258.     Memory write access checking as compile option (does RAM, ROM,
  259.     Access Count and User Exception Handler Call).
  260.     Copes with all forms of modified code.
  261.     Interrupts and other requests have priority levels. Requests of
  262.     lower priority are remembered.
  263.     All "undocumented" Z80 instructions implemented; compile option
  264.     to treat them as undefined.
  265.     BCD information storage for normal arithmetic instructions.
  266.     Push AF can stack CCR form or Z80 F form.
  267.     Compile option to store/retreive BCD information upon Push/Pop AF.
  268.  
  269.     --------
  270.