src/libcpu/readme.txt

   1                                     MUSASHI
   2                                     =======
   3
   4                                   Version 3.4
   5
   6              A portable Motorola M680x0 processor emulation engine.
   7             Copyright 1998-2002 Karl Stenerud.  All rights reserved.
   8
   9
  10
  11 INTRODUCTION:
  12 ------------
  13
  14 Musashi is a Motorola 68000, 68010, 68EC020, and 68020 emulator written in C.
  15 This emulator was written with two goals in mind: portability and speed.
  16
  17 The emulator is written to ANSI C89 specifications.  It also uses inline
  18 functions, which are C9X compliant.
  19
  20 It has been successfully running in the MAME project (www.mame.net) for years
  21 and so has had time to mature.
  22
  23
  24
  25 LICENSE AND COPYRIGHT:
  26 ---------------------
  27
  28 Copyright © 1998-2001 Karl Stenerud
  29
  30 Permission is hereby granted, free of charge, to any person obtaining a copy
  31 of this software and associated documentation files (the "Software"), to deal
  32 in the Software without restriction, including without limitation the rights
  33 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  34 copies of the Software, and to permit persons to whom the Software is
  35 furnished to do so, subject to the following conditions:
  36
  37 The above copyright notice and this permission notice shall be included in
  38 all copies or substantial portions of the Software.
  39
  40 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  41 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  42 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  43 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  44 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  45 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  46 THE SOFTWARE.
  47
  48
  49
  50 AVAILABILITY:
  51 ------------
  52 The latest version of this code can be obtained at:
  53 https://github.com/kstenerud/Musashi
  54
  55
  56
  57 CONTACTING THE AUTHOR:
  58 ---------------------
  59 I can be reached at kstenerud@gmail.com
  60
  61
  62
  63 BASIC CONFIGURATION:
  64 -------------------
  65 The basic configuration will give you a standard 68000 that has sufficient
  66 functionality to work in a primitive environment.
  67
  68 This setup assumes that you only have 1 device interrupting it, that the
  69 device will always request an autovectored interrupt, and it will always clear
  70 the interrupt before the interrupt service routine finishes (but could
  71 possibly re-assert the interrupt).
  72 You will have only one address space, no tracing, and no instruction prefetch.
  73
  74 To implement the basic configuration:
  75
  76 - Open m68kconf.h and verify that the settings for INLINE will work with your
  77   compiler. (Currently set to "static __inline__", which works in gcc 2.9.
  78   For C9X compliance, it should be "inline")
  79
  80 - In your host program, implement the following functions:
  81     unsigned int  m68k_read_memory_8(unsigned int address);
  82     unsigned int  m68k_read_memory_16(unsigned int address);
  83     unsigned int  m68k_read_memory_32(unsigned int address);
  84     void m68k_write_memory_8(unsigned int address, unsigned int value);
  85     void m68k_write_memory_16(unsigned int address, unsigned int value);
  86     void m68k_write_memory_32(unsigned int address, unsigned int value);
  87
  88 - In your host program, be sure to call m68k_pulse_reset() once before calling
  89   any of the other functions as this initializes the core.
  90
  91 - Use m68k_execute() to execute instructions and m68k_set_irq() to cause an
  92   interrupt.
  93
  94
  95
  96 ADDING PROPER INTERRUPT HANDLING:
  97 --------------------------------
  98 The interrupt handling in the basic configuration doesn't emulate the
  99 interrupt acknowledge phase of the CPU and automatically clears an interrupt
 100 request during interrupt processing.
 101 While this works for most systems, you may need more accurate interrupt
 102 handling.
 103
 104 To add proper interrupt handling:
 105
 106 - In m68kconf.h, set M68K_EMULATE_INT_ACK to OPT_SPECIFY_HANDLER
 107
 108 - In m68kconf.h, set M68K_INT_ACK_CALLBACK(A) to your interrupt acknowledge
 109   routine
 110
 111 - Your interrupt acknowledge routine must return an interrupt vector,
 112   M68K_INT_ACK_AUTOVECTOR, or M68K_INT_ACK_SPURIOUS.  most m68k
 113   implementations just use autovectored interrupts.
 114
 115 - When the interrupting device is satisfied, you must call m68k_set_irq(0) to
 116   remove the interrupt request.
 117
 118
 119
 120 MULTIPLE INTERRUPTS:
 121 -------------------
 122 The above system will work if you have only one device interrupting the CPU,
 123 but if you have more than one device, you must do a bit more.
 124
 125 To add multiple interrupts:
 126
 127 - You must make an interrupt arbitration device that will take the highest
 128   priority interrupt and encode it onto the IRQ pins on the CPU.
 129
 130 - The interrupt arbitration device should use m68k_set_irq() to set the
 131   highest pending interrupt, or 0 for no interrupts pending.
 132
 133
 134
 135 SEPARATE IMMEDIATE READS:
 136 ------------------------
 137 You can write faster memory access functions if you know whether you are
 138 fetching from ROM or RAM.  Immediate reads are always from the program space
 139 (Always in ROM unless it is running self-modifying code).
 140
 141 To enable separate immediate reads:
 142
 143 - In m68kconf.h, turn on M68K_SEPARATE_READ_IMM.
 144
 145 - In your host program, implement the following functions:
 146     unsigned int  m68k_read_immediate_16(unsigned int address);
 147     unsigned int  m68k_read_immediate_32(unsigned int address);
 148
 149 - If you need to know the current PC (for banking and such), set
 150   M68K_MONITOR_PC to OPT_SPECIFY_HANDLER, and set M68K_SET_PC_CALLBACK(A) to
 151   your routine.
 152
 153
 154
 155 ADDRESS SPACES:
 156 --------------
 157 Most systems will only implement one address space, placing ROM at the lower
 158 addresses and RAM at the higher.  However, there is the possibility that a
 159 system will implement ROM and RAM in the same address range, but in different
 160 address spaces.
 161
 162 In this case, you might get away with assuming that immediate reads are in the
 163 program space and all other reads are in the data space, if it weren't for the
 164 fact that the exception vectors are fetched from the data space.  As a result,
 165 anyone implementing this kind of system will have to copy the vector table
 166 from ROM to RAM using pc-relative instructions.
 167
 168 This makes things bad for emulation, because this means that a non-immediate
 169 read is not necessarily in the data space.
 170 The m68k deals with this by encoding the requested address space on the
 171 function code pins:
 172
 173                        FC
 174     Address Space      210
 175     ------------------ ---
 176     USER DATA          001
 177     USER PROGRAM       010
 178     SUPERVISOR DATA    101
 179     SUPERVISOR PROGRAM 110
 180     CPU SPACE          111 <-- not emulated in this core since we emulate
 181                                interrupt acknowledge in another way.
 182
 183 To emulate the function code pins:
 184
 185 - In m68kconf.h, set M68K_EMULATE_FC to OPT_SPECIFY_HANDLER and set
 186   M68K_SET_FC_CALLBACK(A) to your function code handler function.
 187
 188 - Your function code handler should select the proper address space for
 189   subsequent calls to m68k_read_xx (and m68k_write_xx for 68010+).
 190
 191 Note: immediate reads are always done from program space, so technically you
 192       don't need to implement the separate immediate reads, although you could
 193       gain more speed improvements leaving them in and doing some clever
 194       programming.
 195
 196
 197
 198 USING DIFFERENT CPU TYPES:
 199 -------------------------
 200 The default is to enable only the 68000 cpu type.  To change this, change the
 201 settings for M68K_EMULATE_010 etc in m68kconf.h.
 202
 203 To set the CPU type you want to use:
 204
 205 - Make sure it is enabled in m68kconf.h.  Current switches are:
 206     M68K_EMULATE_010
 207     M68K_EMULATE_EC020
 208     M68K_EMULATE_020
 209
 210 - In your host program, call m68k_set_cpu_type() and then call
 211   m68k_pulse_reset().  Valid CPU types are:
 212     M68K_CPU_TYPE_68000,
 213     M68K_CPU_TYPE_68010,
 214     M68K_CPU_TYPE_68EC020,
 215     M68K_CPU_TYPE_68020
 216
 217
 218
 219 CLOCK FREQUENCY:
 220 ---------------
 221 In order to emulate the correct clock frequency, you will have to calculate
 222 how long it takes the emulation to execute a certain number of "cycles" and
 223 vary your calls to m68k_execute() accordingly.
 224 As well, it is a good idea to take away the CPU's timeslice when it writes to
 225 a memory-mapped port in order to give the device it wrote to a chance to
 226 react.
 227
 228 You can use the functions m68k_cycles_run(), m68k_cycles_remaining(),
 229 m68k_modify_timeslice(), and m68k_end_timeslice() to do this.
 230 Try to use large cycle values in your calls to m68k_execute() since it will
 231 increase throughput.  You can always take away the timeslice later.
 232
 233
 234
 235 MORE CORRECT EMULATION:
 236 ----------------------
 237 You may need to enable these in order to properly emulate some of the more
 238 obscure functions of the m68k:
 239
 240 - M68K_EMULATE_BKPT_ACK causes the CPU to call a breakpoint handler on a BKPT
 241   instruction
 242
 243 - M68K_EMULATE_TRACE causes the CPU to generate trace exceptions when the
 244   trace bits are set
 245
 246 - M68K_EMULATE_RESET causes the CPU to call a reset handler on a RESET
 247   instruction.
 248
 249 - M68K_EMULATE_PREFETCH emulates the 4-word instruction prefetch that is part
 250   of the 68000/68010 (needed for Amiga emulation).
 251   NOTE: if the CPU fetches a word or longword at an odd address when this
 252   option is on, it will yield unpredictable results, which is why a real
 253   68000 will generate an address error exception.
 254
 255 - M68K_EMULATE_ADDRESS_ERROR will cause the CPU to generate address error
 256   exceptions if it attempts to read a word or longword at an odd address.
 257
 258 - call m68k_pulse_halt() to emulate the HALT pin.
 259
 260
 261
 262 CONVENIENCE FUNCTIONS:
 263 ---------------------
 264 These are in here for programmer convenience:
 265
 266 - M68K_INSTRUCTION_HOOK lets you call a handler before each instruction.
 267
 268 - M68K_LOG_ENABLE and M68K_LOG_1010_1111 lets you log illegal and A/F-line
 269   instructions.
 270
 271
 272
 273 MULTIPLE CPU EMULATION:
 274 ----------------------
 275 The default is to use only one CPU.  To use more than one CPU in this core,
 276 there are some things to keep in mind:
 277
 278 - To have different cpus call different functions, use OPT_ON instead of
 279   OPT_SPECIFY_HANDLER, and use the m68k_set_xxx_callback() functions to set
 280   your callback handlers on a per-cpu basis.
 281
 282 - Be sure to call set_cpu_type() for each CPU you use.
 283
 284 - Use m68k_set_context() and m68k_get_context() to switch to another CPU.
 285
 286
 287
 288 LOAD AND SAVE CPU CONTEXTS FROM DISK:
 289 ------------------------------------
 290 You can use them68k_load_context() and m68k_save_context() functions to load
 291 and save the CPU state to disk.
 292
 293
 294
 295 GET/SET INFORMATION FROM THE CPU:
 296 --------------------------------
 297 You can use m68k_get_reg() and m68k_set_reg() to gain access to the internals
 298 of the CPU.
 299
 300
 301
 302 EXAMPLE:
 303 -------
 304
 305 The subdir example contains a full example (currently DOS only).