home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 2 / FFMCD02.bin / new / misc / emu / z80 / z80.doc < prev    next >
Text File  |  1993-12-21  |  12KB  |  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