cpu/Cyclone/Cyclone.txt

   1 \r
   2       _____            __                                     \r
   3      / ___/__ __ ____ / /___   ___  ___   ___________________ \r
   4     / /__ / // // __// // _ \ / _ \/ -_) ___________________  \r
   5     \___/ \_, / \__//_/ \___//_//_/\__/ ___________________   \r
   6          /___/                                                \r
   7          ___________________  ____ ___   ___   ___   ___      \r
   8         ___________________  / __// _ \ / _ \ / _ \ / _ \     \r
   9        ___________________  / _ \/ _  // // // // // // /     \r
  10                             \___/\___/ \___/ \___/ \___/      \r
  11                                                               \r
  12 ___________________________________________________________________________\r
  13 \r
  14   Cyclone 68000 (c) Copyright 2004 Dave.   Free for non-commercial use\r
  15 \r
  16   Homepage: http://www.finalburn.com/\r
  17   Dave's e-mail: dev(atsymbol)finalburn.com\r
  18   Replace (atsymbol) with @\r
  19 \r
  20   Additional coding and bugfixes done by notaz, 2005, 2006\r
  21   Homepage: http://mif.vu.lt/~grig2790/Cyclone/\r
  22   e-mail: notasas(atsymbol)gmail.com\r
  23 ___________________________________________________________________________\r
  24 \r
  25 \r
  26 What is it?\r
  27 -----------\r
  28 \r
  29 Cyclone 68000 is an emulator for the 68000 microprocessor, written in ARM 32-bit assembly.\r
  30 It is aimed at chips such as ARM7 and ARM9 cores, StrongARM and XScale, to interpret 68000\r
  31 code as fast as possible.\r
  32 \r
  33 Flags are mapped onto ARM flags whenever possible, which speeds up the processing of opcode.\r
  34 \r
  35 \r
  36 What's New\r
  37 ----------\r
  38 v0.0086 notaz\r
  39   + Cyclone now can be customized to better suit your project, see config.h .\r
  40   + Added an option to compress the jumptable at compile-time. Must call CycloneInit()\r
  41     at runtime to decompress it if enabled (see config.h).\r
  42   + Added missing CHK opcode handler (used by SeaQuest DSV).\r
  43   + Added missing TAS opcode handler (Gargoyles,Bubba N Stix,...). As in real genesis,\r
  44     memory write-back phase is ignored (but can be enabled in config.h if needed).\r
  45   + Added missing NBCD and TRAPV opcode handlers.\r
  46   + Added missing addressing mode for CMP/EOR.\r
  47   + Added some minor optimizations.\r
  48   - Removed 216 handlers for 2927 opcodes which were generated for invalid addressing modes.\r
  49   + Fixed flags for ASL, NEG, NEGX, DIVU, ADDX, SUBX, ROXR.\r
  50   + Bugs fixed in MOVEP, LINK, ADDQ, DIVS handlers.\r
  51   * Undocumented flags for CHK, ABCD, SBCD and NBCD are now emulated the same way as in Musashi.\r
  52   + Added Uninitialized Interrupt emulation.\r
  53   + Altered timing for about half of opcodes to match Musashi's.\r
  54 \r
  55 v0.0082 Reesy\r
  56   + Change cyclone to clear cycles before returning when halted\r
  57   + Added Irq call back function.  This allows emulators to be notified\r
  58     when cyclone has taken an interrupt allowing them to set internal flags\r
  59     which can help fix timing problems.\r
  60 \r
  61 v0.0081 notaz\r
  62   + .asm version was broken and did not compile with armasm. Fixed.\r
  63   + Finished implementing Stop opcode. Now it really stops the processor.\r
  64 \r
  65 v0.0080 notaz\r
  66   + Added real cmpm opcode, it was using eor handler before this.\r
  67     Fixes Dune and Sensible Soccer.\r
  68 \r
  69 v0.0078 notaz\r
  70   note: these bugs were actually found Reesy, I reimplemented these by\r
  71         using his changelog as a guide.\r
  72   + Fixed a problem with divu which was using long divisor instead of word.\r
  73     Fixes gear switching in Top Gear 2.\r
  74   + Fixed btst opcode, The bit to test should shifted a max of 31 or 7\r
  75     depending on if a register or memory location is being tested.\r
  76   + Fixed abcd,sbcd. They did bad decimal correction on invalid BCD numbers\r
  77     Score counters in Streets of Rage level end work now.\r
  78   + Changed flag handling of abcd,sbcd,addx,subx,asl,lsl,...\r
  79     Some ops did not have flag handling at all.\r
  80     Some ops must not change Z flag when result is zero, but they did.\r
  81     Shift ops must not change X if shift count is zero, but they did.\r
  82     There are probably still some flag problems left.\r
  83   + Patially implemented Stop and Reset opcodes - Fixes Thunderforce IV\r
  84 \r
  85 v0.0075 notaz\r
  86   + Added missing displacement addressing mode for movem (Fantastic Dizzy)\r
  87   + Added OSP <-> A7 swapping code in opcodes, which change privilege mode\r
  88   + Implemented privilege violation, line emulator and divide by zero exceptions\r
  89   + Added negx opcode (Shining Force works!)\r
  90   + Added overflow detection for divs/divu\r
  91 \r
  92 v0.0072 notaz\r
  93   note: I could only get v0.0069 cyclone, so I had to implement these myself using Dave's\r
  94         changelog as a guide.\r
  95   + Fixed a problem with divs - remainder should be negative when divident is negative\r
  96   + Added movep opcode (Sonic 3 works)\r
  97   + Fixed a problem with DBcc incorrectly decrementing if the condition is true (Shadow of the Beast)\r
  98 \r
  99 v0.0069\r
 100   + Added SBCD and the flags for ABCD/SBCD. Score and time now works in games such as\r
 101     Rolling Thunder 2, Ghouls 'N Ghosts\r
 102   + Fixed a problem with addx and subx with 8-bit and 16-bit values.\r
 103     Ghouls 'N' Ghosts now works!\r
 104 \r
 105 v0.0068\r
 106   + Added ABCD opcode (Streets of Rage works now!)\r
 107 \r
 108 v0.0067\r
 109   + Added dbCC (After Burner)\r
 110   + Added asr EA (Sonic 1 Boss/Labyrinth Zone)\r
 111   + Added andi/ori/eori ccr (Altered Beast)\r
 112   + Added trap (After Burner)\r
 113   + Added special case for move.b (a7)+ and -(a7), stepping by 2\r
 114     After Burner is playable! Eternal Champions shows more\r
 115   + Fixed lsr.b/w zero flag (Ghostbusters)\r
 116     Rolling Thunder 2 now works!\r
 117   + Fixed N flag for .b and .w arithmetic. Golden Axe works!\r
 118 \r
 119 v0.0066\r
 120   + Fixed a stupid typo for exg (orr r10,r10, not orr r10,r8), which caused alignment\r
 121     crashes on Strider\r
 122 \r
 123 v0.0065\r
 124   + Fixed a problem with immediate values - they weren't being shifted up correctly for some\r
 125     opcodes. Spiderman works, After Burner shows a bit of graphics.\r
 126   + Fixed a problem with EA:"110nnn" extension word. 32-bit offsets were being decoded as 8-bit\r
 127     offsets by mistake. Castlevania Bloodlines seems fine now.\r
 128   + Added exg opcode\r
 129   + Fixed asr opcode (Sonic jumping left is fixed)\r
 130   + Fixed a problem with the carry bit in rol.b (Marble Madness)\r
 131 \r
 132 v0.0064\r
 133   + Added rtr\r
 134   + Fixed addq/subq.l (all An opcodes are 32-bit) (Road Rash)\r
 135   + Fixed various little timings\r
 136 \r
 137 v0.0063\r
 138   + Added link/unlk opcodes\r
 139   + Fixed various little timings\r
 140   + Fixed a problem with dbCC opcode being emitted at set opcodes\r
 141   + Improved long register access, the EA fetch now does ldr r0,[r7,r0,lsl #2] whenever\r
 142      possible, saving 1 or 2 cycles on many opcodes, which should give a nice speed up.\r
 143   + May have fixed N flag on ext opcode?\r
 144   + Added dasm for link opcode.\r
 145 \r
 146 v0.0062\r
 147   * I was a bit too keen with the Arithmetic opcodes! Some of them should have been abcd,\r
 148     exg and addx. Removed the incorrect opcodes, pending re-adding them as abcd, exg and addx.\r
 149   + Changed unknown opcodes to act as nops.\r
 150     Not very technical, but fun - a few more games show more graphics ;)\r
 151 \r
 152 v0.0060\r
 153   + Fixed divu (EA intro)\r
 154   + Added sf (set false) opcode - SOR2\r
 155   * Todo: pea/link/unlk opcodes\r
 156 \r
 157 v0.0059: Added remainder to divide opcodes.\r
 158 \r
 159 \r
 160 The new stuff\r
 161 -------------\r
 162 \r
 163 Before using Cyclone, be sure to customize config.h to better suit your project. All options\r
 164 are documented inside that file.\r
 165 \r
 166 IrqCallback has been changed a bit, unlike in previous version, it should not return anything.\r
 167 If you need to change IRQ level, you can safely do that in your handler.\r
 168 \r
 169 Cyclone has changed quite a bit from the time when Dave stopped updating it, but the rest of\r
 170 documentation still applies, so read it if you haven't done that yet. If you have, check the\r
 171 "Accessing ..." parts.\r
 172 \r
 173 \r
 174 ARM Register Usage\r
 175 ------------------\r
 176 \r
 177 See source code for up to date of register usage, however a summary is here:\r
 178 \r
 179   r0-3: Temporary registers\r
 180   r4  : Current PC + Memory Base (i.e. pointer to next opcode)\r
 181   r5  : Cycles remaining\r
 182   r6  : Pointer to Opcode Jump table\r
 183   r7  : Pointer to Cpu Context\r
 184   r8  : Current Opcode\r
 185   r9  : Flags (NZCV) in highest four bits\r
 186  (r10 : Temporary source value or Memory Base)\r
 187  (r11 : Temporary register)\r
 188 \r
 189 \r
 190 How to Compile\r
 191 --------------\r
 192 \r
 193 Like Starscream and A68K, Cyclone uses a 'Core Creator' program which calculates and outputs\r
 194 all possible 68000 Opcodes and a jump table into files called Cyclone.s and .asm\r
 195 It then assembles these files into Cyclone.o and .obj\r
 196 \r
 197 Cyclone.o is the GCC assembled version and Cyclone.obj is the Microsoft assembled version.\r
 198 \r
 199 First unzip "Cyclone.zip" into a "Cyclone" directory.\r
 200 If you are compiling for Windows CE, find ARMASM.EXE (the Microsoft ARM assembler) and\r
 201 put it in the directory as well or put it on your path.\r
 202 \r
 203 Open up Cyclone.dsw in Visual Studio 6.0, compile and run the project.\r
 204 Cyclone.obj and Cyclone.o will be created.\r
 205 \r
 206 \r
 207 Compiling without Visual C++\r
 208 ----------------------------\r
 209 If you aren't using Visual C++, it still shouldn't be too hard to compile, just get a C compiler,\r
 210 compile all the CPPs and C file, link them into an EXE, and run the exe.\r
 211 \r
 212   e.g. gcc Main.cpp OpAny.cpp OpArith.cpp OpBranch.cpp OpLogic.cpp OpMove.cpp Disa.c\r
 213   Main.exe\r
 214 \r
 215 \r
 216 Adding to your project\r
 217 ----------------------\r
 218 \r
 219 To add Cyclone to you project, add Cyclone.o or obj, and include Cyclone.h\r
 220 There is one structure: 'struct Cyclone', and one function: CycloneRun\r
 221 \r
 222 Don't worry if this seem very minimal - its all you need to run as many 68000s as you want.\r
 223 It works with both C and C++.\r
 224 \r
 225 Byteswapped Memory\r
 226 ------------------\r
 227 \r
 228 If you have used Starscream, A68K or Turbo68K or similar emulators you'll be familiar with this!\r
 229 \r
 230 Any memory which the 68000 can access directly must be have every two bytes swapped around.\r
 231 This is to speed up 16-bit memory accesses, because the 68000 has Big-Endian memory\r
 232 and ARM has Little-Endian memory.\r
 233 \r
 234 Now you may think you only technically have to byteswap ROM, not RAM, because\r
 235 16-bit RAM reads go through a memory handler and you could just return (mem[a]<<8) | mem[a+1].\r
 236 \r
 237 This would work, but remember some systems can execute code from RAM as well as ROM, and\r
 238 that would fail.\r
 239 So it's best to use byteswapped ROM and RAM if the 68000 can access it directly.\r
 240 It's also faster for the memory handlers, because you can do this:\r
 241   \r
 242   return *(unsigned short *)(mem+a)\r
 243 \r
 244 \r
 245 Declaring Memory handlers\r
 246 -------------------------\r
 247 \r
 248 Before you can reset or execute 68000 opcodes you must first set up a set of memory handlers.\r
 249 There are 7 functions you have to set up per CPU, like this:\r
 250 \r
 251   static unsigned int   MyCheckPc(unsigned int pc)\r
 252   static unsigned char  MyRead8  (unsigned int a)\r
 253   static unsigned short MyRead16 (unsigned int a)\r
 254   static unsigned int   MyRead32 (unsigned int a)\r
 255   static void MyWrite8 (unsigned int a,unsigned char  d)\r
 256   static void MyWrite16(unsigned int a,unsigned short d)\r
 257   static void MyWrite32(unsigned int a,unsigned int   d)\r
 258 \r
 259 You can think of these functions representing the 68000's memory bus.\r
 260 The Read and Write functions are called whenever the 68000 reads or writes memory.\r
 261 For example you might set MyRead8 like this:\r
 262 \r
 263   unsigned char MyRead8(unsigned int a)\r
 264   {\r
 265     a&=0xffffff; // Clip address to 24-bits\r
 266 \r
 267     if (a<RomLength) return RomData[a^1]; // ^1 because the memory is byteswapped\r
 268     if (a>=0xe00000) return RamData[(a^1)&0xffff];\r
 269     return 0xff; // Out of range memory access\r
 270   }\r
 271 \r
 272 The other 5 read/write functions are similar. I'll describe the CheckPc function later on.\r
 273 \r
 274 Declaring a CPU Context\r
 275 -----------------------\r
 276 \r
 277 To declare a CPU simple declare a struct Cyclone in your code. For example to declare\r
 278 two 68000s:\r
 279 \r
 280   struct Cyclone MyCpu;\r
 281   struct Cyclone MyCpu2;\r
 282 \r
 283 It's probably a good idea to initialise the memory to zero:\r
 284 \r
 285   memset(&MyCpu, 0,sizeof(MyCpu));\r
 286   memset(&MyCpu2,0,sizeof(MyCpu2));\r
 287 \r
 288 Next point to your memory handlers:\r
 289 \r
 290   MyCpu.checkpc=MyCheckPc;\r
 291   MyCpu.read8  =MyRead8;\r
 292   MyCpu.read16 =MyRead16;\r
 293   MyCpu.read32 =MyRead32;\r
 294   MyCpu.write8 =MyWrite8;\r
 295   MyCpu.write16=MyWrite16;\r
 296   MyCpu.write32=MyWrite32;\r
 297 \r
 298 You also need to point the fetch handlers - for most systems out there you can just\r
 299 point them at the read handlers:\r
 300   MyCpu.fetch8  =MyRead8;\r
 301   MyCpu.fetch16 =MyRead16;\r
 302   MyCpu.fetch32 =MyRead32;\r
 303 \r
 304 ( Why a different set of function pointers for fetch?\r
 305   Well there are some systems, the main one being CPS2, which return different data\r
 306   depending on whether the 'fetch' line on the 68000 bus is high or low.\r
 307   If this is the case, you can set up different functions for fetch reads.\r
 308   Generally though you don't need to. )\r
 309 \r
 310 Now you are nearly ready to reset the 68000, except you need one more function: checkpc().\r
 311 \r
 312 The checkpc() function\r
 313 ----------------------\r
 314 \r
 315 When Cyclone reads opcodes, it doesn't use a memory handler every time, this would be\r
 316 far too slow, instead it uses a direct pointer to ARM memory.\r
 317 For example if your Rom image was at 0x3000000 and the program counter was $206,\r
 318 Cyclone's program counter would be 0x3000206.\r
 319 \r
 320 The difference between an ARM address and a 68000 address is also stored in a variable called\r
 321 'membase'. In the above example it's 0x3000000. To retrieve the real PC, Cyclone just\r
 322 subtracts 'membase'.\r
 323 \r
 324 When a long jump happens, Cyclone calls checkpc(). If the PC is in a different bank,\r
 325 for example Ram instead of Rom, change 'membase', recalculate the new PC and return it:\r
 326 \r
 327 static int MyCheckPc(unsigned int pc)\r
 328 {\r
 329   pc-=MyCpu.membase; // Get the real program counter\r
 330 \r
 331   if (pc<RomLength) MyCpu.membase=(int)RomMem;          // Jump to Rom\r
 332   if (pc>=0xff0000) MyCpu.membase=(int)RamMem-0xff0000; // Jump to Ram\r
 333 \r
 334   return MyCpu.membase+pc; // New program counter\r
 335 }\r
 336 \r
 337 Notice that the membase is always ARM address minus 68000 address.\r
 338 \r
 339 The above example doesn't consider mirrored ram, but for an example of what to do see\r
 340 PicoDrive (in Memory.cpp).\r
 341 \r
 342 \r
 343 Almost there - Reset the 68000!\r
 344 -------------------------------\r
 345 \r
 346 Next we need to Reset the 68000 to get the initial Program Counter and Stack Pointer. This\r
 347 is obtained from addresses 000000 and 000004.\r
 348 \r
 349 Here is code which resets the 68000 (using your memory handlers):\r
 350 \r
 351   MyCpu.srh=0x27; // Set supervisor mode\r
 352   MyCpu.a[7]=MyCpu.read32(0); // Get Stack Pointer\r
 353   MyCpu.membase=0;\r
 354   MyCpu.pc=MyCpu.checkpc(MyCpu.read32(4)); // Get Program Counter\r
 355 \r
 356 And that's ready to go.\r
 357 \r
 358 \r
 359 Executing the 68000\r
 360 -------------------\r
 361 \r
 362 To execute the 68000, set the 'cycles' variable to the number of cycles you wish to execute,\r
 363 and then call CycloneRun with a pointer to the Cyclone structure.\r
 364 \r
 365 e.g.:\r
 366   // Execute 1000 cycles on the 68000:\r
 367   MyCpu.cycles=1000; CycloneRun(&MyCpu);\r
 368 \r
 369 For each opcode, the number of cycles it took is subtracted and the function returns when\r
 370 it reaches 0.\r
 371 \r
 372 e.g.\r
 373   // Execute one instruction on the 68000:\r
 374   MyCpu.cycles=0; CycloneRun(&MyCpu);\r
 375   printf("  The opcode took %d cycles\n", -MyCpu.cycles);\r
 376 \r
 377 You should try to execute as many cycles as you can for maximum speed.\r
 378 The number actually executed may be slightly more than requested, i.e. cycles may come\r
 379 out with a small negative value:\r
 380 \r
 381 e.g.\r
 382   int todo=12000000/60; // 12Mhz, for one 60hz frame\r
 383   MyCpu.cycles=todo; CycloneRun(&MyCpu);\r
 384   printf("  Actually executed %d cycles\n", todo-MyCpu.cycles);\r
 385 \r
 386 To calculate the number of cycles executed, use this formula:\r
 387   Number of cycles requested - Cycle counter at the end\r
 388 \r
 389 \r
 390 Interrupts\r
 391 ----------\r
 392 \r
 393 Causing an interrupt is very simple, simply set the irq variable in the Cyclone structure\r
 394 to the IRQ number.\r
 395 To lower the IRQ line, set it to zero.\r
 396 \r
 397 e.g:\r
 398   MyCpu.irq=6; // Interrupt level 6\r
 399   MyCpu.cycles=20000; CycloneRun(&MyCpu);\r
 400 \r
 401 Note that the interrupt is not actually processed until the next call to CycloneRun,\r
 402 and the interrupt may not be taken until the 68000 interrupt mask is changed to allow it.\r
 403 \r
 404 ( The IRQ isn't checked on exiting from a memory handler: I don't think this will cause\r
 405   me any trouble because I've never needed to trigger an interrupt from a memory handler,\r
 406   but if someone needs to, let me know...)\r
 407 \r
 408 \r
 409 Accessing Cycle Counter\r
 410 -----------------------\r
 411 \r
 412 The cycle counter in the Cyclone structure is not, by default, updated before\r
 413 calling a memory handler, only at the end of an execution.\r
 414 \r
 415 *update*\r
 416 Now this is configurable in config.h, there is no 'debug' variable.\r
 417 \r
 418 \r
 419 Accessing Program Counter and registers\r
 420 ---------------------------------------\r
 421 \r
 422 You can read Cyclone's registers directly from the structure at any time (as far as I know).\r
 423 \r
 424 The Program Counter, should you need to read or write it, is stored with membase\r
 425 added on. So use this formula to calculate the real 68000 program counter:\r
 426 \r
 427   pc = MyCpu.pc - MyCpu.membase;\r
 428 \r
 429 The program counter is stored in r4 during execution, and isn't written back to the\r
 430 structure until the end of execution, which means you can't read normally real it from\r
 431 a memory handler.\r
 432 \r
 433 *update*\r
 434 Now this is configurable in config.h, there is no 'debug' variable. You can even enable\r
 435 access to SR if you need. However changing PC in memhandlers is still not safe, you should\r
 436 better clear cycles, wait untill CycloneRun() returns and then do whatever you need.\r
 437 \r
 438 \r
 439 Emulating more than one CPU\r
 440 ---------------------------\r
 441 \r
 442 Since everything is based on the structures, emulating more than one cpu at the same time\r
 443 is just a matter of declaring more than one structures and timeslicing. You can emulate\r
 444 as many 68000s as you want.\r
 445 Just set up the memory handlers for each cpu and run each cpu for a certain number of cycles.\r
 446 \r
 447 e.g.\r
 448   // Execute 1000 cycles on 68000 #1:\r
 449   MyCpu.cycles=1000; CycloneRun(&MyCpu);\r
 450 \r
 451   // Execute 1000 cycles on 68000 #2:\r
 452   MyCpu2.cycles=1000; CycloneRun(&MyCpu2);\r
 453 \r
 454 \r
 455 Thanks to...\r
 456 ------------\r
 457 \r
 458 * All the previous code-generating assembler cpu core guys!\r
 459   Who are iirc... Neill Corlett, Neil Bradley, Mike Coates, Darren Olafson\r
 460     and Bart Trzynadlowski\r
 461 \r
 462 * Charles Macdonald, for researching just about every console ever\r
 463 * MameDev+FBA, for keeping on going and going and going\r
 464 \r
 465 \r
 466 -------------\r
 467 \r
 468 Dave  - 17th April 2004\r
 469 notaz - 17th July 2006\r
 470 \r
 471 Homepage: http://www.finalburn.com/\r
 472 Dave's e-mail: dev(atsymbol)finalburn.com\r
 473 Replace (atsymbol) with @\r