apps/plugins/zxbox/README.Z80

   1 This file describes how to use the Z80 processor emulation as a
   2 standalone module (without the ZX Spectrum emulation).
   3
   4 ===========================================================================
   5 You will need the following files:
   6
   7 For the 'intel x86' assembly version:
   8 -------------------------------------
   9
  10 z80.c z80.h z80_type.h i386step.S i386def.S i386op1.S i386op1x.S
  11 i386op2.S i386op2x.S i386op3.S i386op3x.S i386op4.S i386op5.S i386op6.S
  12 sp_to_s.c
  13
  14 For the 'C' version:
  15 --------------------
  16
  17 z80.c z80.h z80_type.h z80_step.c z80_def.h z80_ari.h z80optab.c z80optab.h
  18 z80_op1.c z80_op1x.c z80_op1.h z80_op2.c z80_op2x.c z80_op2.h
  19 z80_op3.c z80_op3x.c z80_op3.h z80_op4.c z80_op4x.c z80_op4.h
  20 z80_op5.c z80_op5.h z80_op6.c z80_op6.h
  21
  22 ===========================================================================
  23 Makefile rules:
  24
  25 For the 'intel x86' assembly version:
  26 -------------------------------------
  27
  28 CC = gcc
  29 AR = ar
  30 CPPFLAGS =
  31 CFLAGS = -Wall -O3
  32 CPP = $(CC) -E
  33
  34 z80_i386_objs = z80.o i386emul.o
  35
  36 libz80.a: $(z80_i386_objs)
  37     $(AR) cr libz80.a $(z80_i386_objs)
  38
  39 i386emul.o: i386emul.s
  40     $(CC) -c $(CFLAGS) i386emul.s
  41
  42 i386emul.s: i386emul.sp sp_to_s
  43     ./sp_to_s < i386emul.sp > i386emul.s
  44
  45 i386emul.sp: i386step.S
  46     $(CPP) $(CPPFLAGS) i386step.S > i386emul.sp
  47
  48 sp_to_s: sp_to_s.o
  49     $(CC) -o sp_to_s $(LDFLAGS) sp_to_s.o
  50
  51 .SUFFIXES:
  52 .SUFFIXES: .c .o
  53
  54 .c.o:
  55     $(CC) -c $(CFLAGS) $(CPPFLAGS) $<
  56
  57
  58 For 'C' version:
  59 ----------------
  60
  61 CC = gcc
  62 AR = ar
  63 CPPFLAGS = -DZ80C
  64 CFLAGS = -Wall -O3 -fomit-frame-pointer -funroll-loops
  65
  66 z80_c_objs = z80.o z80_step.o z80optab.o z80_op1.o z80_op2.o z80_op3.o \
  67              z80_op4.o z80_op5.o z80_op6.o
  68
  69 libz80.a: $(z80_c_objs)
  70     $(AR) cr libz80.a $(z80_c_objs)
  71
  72 .SUFFIXES:
  73 .SUFFIXES: .c .o
  74
  75 .c.o:
  76     $(CC) -c $(CFLAGS) $(CPPFLAGS) $<
  77
  78 ===========================================================================
  79 The following functions are defined by libz80.a:
  80
  81 void z80_init()
  82 ---------------
  83
  84 This function initializes the processor emulation. This must be called
  85 only once at the beginning of the program.
  86
  87 int z80_step(int ticknum)
  88 -------------------------
  89
  90 This function executes z80 instructions for 'ticknum' number of clock
  91 cycles. It returns the remaining number of ticks.
  92
  93 NOTE: the remaining number of ticks is always zero or negative,
  94 meaning that exactly, or more than the given 'ticknum' clock cycles
  95 were executed. This is because WHOLE instructions are executed at a
  96 time.
  97
  98 NOTE: HALT, LDDR, etc... do not count as one instruction, but as a
  99 series of instructions (e.g. HALT is a series of NOPs).
 100
 101 void z80_reset()
 102 ----------------
 103
 104 This function resets the Z80 processor. This has the same effect as
 105 applying a pulse to the RESET input of the processor.
 106
 107 NOTE: z80_init() does not reset the Z80, z80_reset() should be called
 108 after it.
 109
 110 void z80_interrupt(int data)
 111 -----------------------------
 112
 113 Causes a Maskable Interrupt. Interrupt mode 1 and 2 are emulated
 114 correctly, in interrupt mode 2 'data' is used in the address
 115 calculation. In interrupt mode 0, it is assumed (as on the ZX
 116 Spectrum) that 0xFF is on the data bus, and always RST 38 is
 117 generated.
 118
 119 NOTE: It is not emulated, that in the instruction after EI no
 120 interrupt can be generated.
 121
 122 void z80_nmi()
 123 --------------
 124
 125 Causes a Non Maskable Interrupt.
 126
 127 ===========================================================================
 128 Accessing the memory, the I/O ports and the Z80 processor's state
 129 (i.e. registers, etc...)
 130
 131 To use the functions above and the variables below, include the
 132 "z80.h" include file.
 133
 134 Memory
 135 ------
 136
 137 The memory is stored in the z80_proc.mem[] byte array, which has a
 138 size of 65536. By default it is all RAM. To make parts of it read
 139 only, you have to redefine the appropriate macros in i386step.S and/or
 140 z80_def.h. (These macros are sorounded by #ifdef SPECT_MEM, #else,
 141 #endif statements.)
 142
 143 The memory is initialised to random data. You must fill it in before
 144 starting the emulation, but AFTER the call to z80_init().
 145
 146 I/O
 147 ---
 148
 149 The input port values are stored in z80_inports[] array, which has a
 150 size of 256. The IN instruction will use the appropriate element of
 151 this array. This array is initialised to all zeroes.
 152
 153 The output port values can be queried from the z80_outports[] array,
 154 which has also a size of 256. The OUT instruction will store the value
 155 in the element addressed by the instruction.
 156
 157 If you need more complex behaviour of the I/O, you must redefine the
 158 appropriate macros in i386step.S and z80_def.h.
 159
 160 Processor state
 161 ---------------
 162
 163 You can access the processor's state with the following variables and
 164 macros defined in "z80.h".
 165
 166 Registers:
 167
 168 Double registers:
 169   normal:  BC, DE, HL, AF, IR, IX, IY, PC, SP,
 170   aux:     BCBK, DEBK, HLBK, AFBK
 171
 172 Single registers:
 173   RB, RC, RD, RE, RH, RL, RA, RF, RI, RR, XH, XL, YH, YL, PCH, PCL, SPH, SPL
 174
 175 Misc state:
 176   z80_proc.haltstate   (1: processor is in halt mode, 0: processor is runnig)
 177   z80_proc.it_mode     (interrupt mode 0, 1 or 2)
 178   z80_proc.iff1        (interrupt flip-flop 1)
 179   z80_proc.iff2        (interrupt flip-flop 2)
 180
 181 You need not access the other parts of z80_proc, they are meaningless
 182 outside the z80_step() function.