DEV Community: transistor fet

Emulating the Sega Genesis - Part III

transistor fet — Fri, 14 Jan 2022 18:13:41 +0000

Originally published at jabberwocky.ca

Written December 2021/January 2022 by transistor_fet

A few months ago, I wrote a 68000 emulator in Rust named Moa. My original goal was to emulate a simple computer I had previously built. After only a few weeks, I had that software up and running in the emulator, and my attention turned to what other platforms with 68000s I could try emulating. My thoughts quickly turned to the Sega Genesis and without thinking about it too much, I dove right in. What started as an unserious half-thought of "wouldn't that be cool" turned into a few months of fighting documentation, game programming hacks, and my sanity with some side quests along the way, all in the name of finding and squashing bugs in the 68k emulator I had already written.

This is Part III in the series. If you haven't already read Part I and Part II, you might want to do so. Part I covers setting up the emulator, getting some game ROMs to run, and implementing the DMA and memory features of the VDP. Part II covers adding a graphical frontend to Moa, and then implementing a first attempt at generating video output. Part III will be about debugging the various problems in the VDP and CPU implementations to get a working emulator capable of playing games. For more details on the 68000 and the basic design of Moa, check out Making a 68000 Emulator in Rust.

Previously
Fixing The Colours
Drawing A Blank
What About Those Interrupts
And Now For Something (A Little) Different
Back to the Genesis
VRAM Discrepancies
You Can't Write There, Sir
Fixing Sprites
Not All The Data
Scrolling The Scrolls
Fixing Line Scrolling
Rewriting
Conclusion

Previously

After about two weeks of work on adding Sega Genesis support to my emulator, I had implemented memory operations for the video display processor (VDP), and written a draw loop to generate the video frames according to the SEGA documentation. The result of all that work was this:

This is Sonic 1 attempting to show the SEGA logo at startup. It's better than Sonic 2 which was just a black screen, a few log messages, and then... nothing... The few other games I tried were no better.

When I had started this project, I thought it probably wouldn't be too hard to get something as simple as the SEGA logo working, but I was wrong. After spending a day or two fiddling with quick fixes that didn't fix much of anything, I committed my work in progress to git, so that I could track and undo any changes I made, and started in to some serious debugging. The following is my journey of debugging, on and off over the next six weeks, until I managed to get Sonic 2 running well enough to play.

Fixing The Colours

The most obvious thing that was wrong was the colours, so I looked into this first. Since I couldn't be sure that all the data was getting into the VDP correctly, I needed to simplify the output a bit, so I wrote an alternate draw_frame() function to display just the patterns instead of the scroll tables. It would draw each pattern in memory across the screen from left to right, top to bottom so that I could inspect them better. They might not look like a coherent picture, being only 8x8 pixels each and arranged in an unintended order, but it should at least show something. The result was this:

There is definitely some kind of pattern data being displayed because the patterns are not a solid colour, but the colours are clearly wrong. I'm expecting some blue colours since it should be printing the SEGA logo.

For about a day I was doubting and testing the transfer of data into CRAM. I had found a minor bug earlier in that code. After staring at the values in CRAM for a while, I noticed that the colour values were actually correct. There were values of 0xEEE and 0xE00 and a few others, so it had to be a problem with reading the CRAM to get the u32 colours value. The code to convert CRAM values into colours was:

let rgb = read_beu16(&self.cram[((palette * 16) + colour) as usize..]);
(((rgb & 0xF00) as u32) >> 4) | (((rgb & 0x0F0) as u32) << 8) | (((rgb & 0x00F) as u32) << 20)

There had definitely been some problems with those complex shift operations, but the tricker problem turned out to be the index into the CRAM that was wrong. Since the CRAM is an array of u8, which was chosen in order to reuse the same transfer and DMA code with VRAM, I needed to multiply the index by 2 before reading the word at that location. Now the colours actually make sense:

Switching back to displaying the scrolls I'm now getting a white screen, but not much else. sigh In Sonic 1, parts of the SEGA logo were displayed if I only drew Scroll A or Scroll B, but displaying both together didn't work. I needed to add the mask colour, which is always colour 0 in each palette. I modified the .blit() method to not draw anything if the colour 0 is used (later changed to 0xFFFFFFFF to avoid a conflict with the colour black, represented by 0), and now I was getting something.

Now it's actually showing the SEGA logo! The scrolls are finally working, even if they still don't look right and the animation is painfully slow.

Drawing A Blank

While Sonic 1 seemed to at least try to display something, Sonic 2 and a few other games wouldn't display anything at all. With the various debug messages turned on, the logs showed it was initializing various devices and then would get caught in a loop where it would read the status word of the VDP over and over again. Clearly it was looking for a specific bit value in the status word before it would move on, but I didn't know which one.

The status word is returned when reading (instead of writing) from the VDP's control port. It contains a number of status flag bits and is one of the few ways the CPU can get feedback from the VDP, with interrupts being the other. In my existing code, the FIFO and NTSC bits were set statically, and the DMA bit was being set and reset during DMA operations, so it probably wasn't related to those. Given that this problem happens right away, it's probably not looking at the sprite flags either. I reckon it's something to do with the HBLANK/VBLANK bits, or possibly the V Interrupt Happened bit.

The HBLANK and VBLANK bits are set when the video output signal is in its blanking phases. On a CRT, it takes time after a line has been drawn for the electron beam to move back to the start of the next line, and be ready to output the next line of data. It also takes time (a lot more time) after the entire screen has been drawn for the beam to move back to the top of the screen again to start the next refresh. Since the video signal's data is directly output to the CRT as soon as it's received (the joys of analogue signals), the video signal itself needs to incorporate these blanking delays where no data is sent. These blanking periods just so happen to be convenient times for the CPU to update or change data in the VDP, when those changes wont affect the output. This is especially important during the vertical blanking period, when the positions of everything on the screen can be updated at once before the next frame is drawn to prevent artifacts and glitches in the image.

I was moving fast to get something working, so I quickly implemented the vertical blanking bit by setting it just before getting to the end of the frame, at 14_218_000 ns, and then resetting the bit at 16_630_000 ns when the frame is drawn and the vertical interrupt is triggered.

This worked for the time being, but it turned out to cause another error that slowed the animation down by half, which I didn't notice until after I had the scrolling working. It wasn't until I could actually play the games that I noticed the problem, and by that point I had forgotten about this bit. It took me a day or two of debugging before I finally tracked down the problem to the VBLANK bit.

After the vertical interrupt occurs, some games would busy wait until the vertical blanking bit was set before actually running the game loop. Sonic 2 is one such game, but Sonic 1 doesn't do this check. Since the bit is only set about 2ms before the next vertical interrupt, the game's frame updater would only start 2ms before the next interrupt, and would still be updating the frame at that point, so it would ignore the second vertical interrupt. As a result, it would take two frames of time (2 vertical interrupts) before one frame of the game would be drawn, and only one cycle of the game loop would execute. Sonic was moving at exactly half speed. Doubling the amount of simulated time fixed the issue (which didn't make any sense at first). I even went to the trouble of implementing more accurate instruction timing in the 68000 in order to see if it was caused by the fact that all the instructions had previously been running in 4 clock cycles. Shown below is the more recent code with the fixed blanking behaviour.

The following code is in the updated VDP's .step() function, including the VBLANK bit handling. The HBLANK code looks similar but with different timing values.

self.state.v_clock += diff;
if (self.state.status & STATUS_IN_VBLANK) != 0 && self.state.v_clock >= 1_205_992 && self.state.v_clock <= 15_424_008 {
    self.state.status &= !STATUS_IN_VBLANK;
}
if (self.state.status & STATUS_IN_VBLANK) == 0 && self.state.v_clock >= 15_424_008 {
    self.state.status |= STATUS_IN_VBLANK;

    ...     // Vertical Interrupt and Frame Update Code

}
if self.state.v_clock > 16_630_000 {
    self.state.v_clock -= 16_630_000;
}

Finally! The SEGA logo in Sonic 2 is (almost) displaying correctly. There are a few glitches in the logo but that's because I hadn't implemented the reverse patterns yet. Adding support for that fixed the logo right up.

What About Those Interrupts

While Sonic 2 was now advancing enough to show the scrolls, it was very slow, the same as Sonic 1, from the start of the program through displaying the logo and then finally getting to the title screen. It was taking half a minute or more.

My first suspicion was to check the interrupts, since it's usually the vertical interrupt that triggers the progression of time in these games. It's a reliable signal to use for knowing how long to show the logo screen for, or when to read the controller input, calculate movement, and then update the screen. Turning on the debugging output for the interrupts showed that they weren't occurring anywhere near as fast as they should be. It would take seconds before an interrupt occurred, and they would occur randomly rather than at a regular pace.

I'm not all that surprised given that I knew there were issues with the implementation, and I had run into problems with them when working on Computie support, but I hadn't been sure how I wanted to fix them. Now I needed to fix them.

In the original implementation, there was a trait for Interruptable devices with a function that would be called by the interrupt controller when an interrupt occurred, which would trigger the interrupt handler. That works in theory, but an interrupt might not be handled right away if interrupts are disabled, and the callback might not be re-called when interrupts were re-enabled. There was also no mechanism for acknowledging an interrupt, and the 68k implementation's handling of the interrupt priority mask was buggy. The result was that interrupts would only occur when everything happened to line up, which wasn't very often.

For the 68000, an interrupt can occur with a priority between 1 and 7. A higher number is a higher priority, and interrupts below a certain priority number can be disabled using a priority mask value stored in the %sr register. When an interrupt occurs, the CPU will check that priority number against the priority mask. If the requested interrupt number is strictly higher than the mask, then the %sr and %pc registers will be pushed onto the stack, the priority mask will be changed to the current number (to prevent a duplicate handling of the same interrupt), and the handler will be run. If the interrupt priority equals or is lower than the mask, the CPU will keep running whatever it had been running before, at least until the priority mask changes, or a higher priority unmasked interrupt occurs.

For devices like the serial controller in Computie, the interrupt signal will be asserted and stay asserted until the cause of the interrupt is manually acknowledged by writing a certain value to the serial controller. For the Genesis, on the other hand, the interrupts behave more like one-shots where there is no manual acknowledgement, and the signal should be de-asserted as soon as it's acknowledged, essentially.

As for the CPU, if an interrupt is masked when the signal was assert, and then unmasked while the signal is still asserted, it will run the handler (ie. the interrupt signals are level triggered, not edge triggered). If the signal goes away before the interrupt is unmasked, the handler will never be run.

In hardware, interrupts will only be checked at a certain point in the CPU's cycle, usually between the execution of instructions, so it's actually pretty reasonable for the emulated CPU to manually check for interrupts at the end of an instruction cycle. All it has to do is check the interrupt controller object in System. The Interruptable trait wasn't needed anymore. Devices call the interrupt controller to set an interrupt, and the CPU calls the interrupt controller to check if any are active. It's not a terribly complicated problem, but it's easy to get wrong in subtle ways, such that it might work for some devices but not others.

Now it runs at what seems like the right speed! Lets ignore, for a minute, the other glaring issues...

And Now For Something (A Little) Different

At this point, I had the colours and interrupts sorted out, the scrolls were being displayed somewhat correctly, and the sprites were sort of working, but multi-cell sprites were still broken. Everything I had tried to fix the sprites didn't work, and I had no idea if it was because of the VDP implementation or a bug in the CPU. And to make matters worse, Sonic was falling through the floor during the gameplay.

And here I got stuck. I had been doing nothing but debugging for a week at this point, three weeks after starting on the Genesis and about five weeks since I had started the emulator. I had made good progress but this last week was a grind. There were multiple issues, both in the VDP and the CPU. I had already fixed the few things that really stood out, but I was running out of threads to pull on, and getting frustrated. I needed to try something else.

I had not yet proven out the 68000 implementation, so some of the problems I was encountering could be in there and not in the VDP code. There was no easy way to tell where the problem was without tracing a lot of assembly code to figure out what it was supposed to do, looking for a one bit change somewhere in the CPU registers or in memory. I needed a way to test the 68000 better, and why not try implementing another system?

The Macintosh 512k also used the 68000 and it's a fairly simple computer, in terms of I/O. It had a very basic video display circuit made from generic logic that looped through memory addresses and shifted the bits into the video output stream. The display only supported black and white so each pixel was a single bit that was either on or off. The ROMs that were embedded on the motherboard are available at archive.org, so I started making some devices and running the ROMs to see if I could find some bugs in the 68000 emulation alone.

At the same time, I looked into implementing the Z80 that the Genesis would also need. Some games seemed to get stuck waiting for the non-existent Z80 to respond, so I thought I might as well start a Z80 implementation too. It would be something different to work on when I was stuck on everything else. At least then I'd make some progress, which would encourage me to keep going.

In order to develop a Z80 implementation, I needed some Z80 code to run on it, and any I/O devices that the code needed. I could write my own Z80 code of course, but that wouldn't test the implementation well enough, beyond just basic functioning of the instructions. I needed code for an existing platform, with all its expectations of how the real system behaves embedded in its logic, and that meant implementing devices for an existing platform. I looked around for the simplest Z80 platform I could find, which turned out to be the TRS-80. I'm not the biggest fan of the TRS-80, but I did have a "Model I" in my computer collection at one point (that I sadly had to sell), so it wasn't entirely foreign to me. I could get away with just implementing the video display and the keyboard in order to run the BASIC interpreter that comes in its ROM.

Over the next month, I mostly worked on these sub-projects, as well as on another Computie hardware iteration. The TRS-80 implementation came together fairly smoothly apart from a bug in the Z80 implementation's shift operation that took me a day or two of tracing the Level I BASIC ROM's assembly code to fix. (Thanks to George Phillips for the well documented assembly code).

The Macintosh implementation didn't go as smoothly however. I did manage to find and fix a few bugs in the 68000, and I got far enough to display the Dead Mac screen, but I got stuck just before the end of the ROM's initialization where it opens the default device drivers. At some point, it attempts to write to a location in the ROM. In hardware that shouldn't have an affect, except that I have some code in Moa to raise an error when that happens, since it's likely a bug. Ignoring that error didn't make it get any farther. I couldn't for the life of me find out what was wrong, but at one point, using another emulator, I was able to confirm that if the ROMs ran on a system that didn't mirror the RAM and ROM address exactly as the hardware does, the ROM wont boot. facepalm Effort went into making sure the Macintosh was not cloned like the IBM PC, so I was fighting against those effort as well. After a while I decided to give the Genesis a try again.

Back to the Genesis

After getting stuck on the Macintosh implementation, I picked up the Genesis again. I had spent almost an entire month away. In that time, I had worked on another hardware revision for Computie, and wrote the article "Making a 68000 Emulator In Rust". I also had improved the Moa debugger, implemented the Z80 entirely, filled in a number of missing 68k instructions, and finished implementing all the 68k instruction decoding (although a few instructions are still not implemented because they aren't use by any code I've tried to run). I also fixed some bugs in existing instructions, such as MOVEM which copies data to or from multiple registers at a time. Perhaps some things could be fixed?

On the surface though, the results were the same as last time. The scrolls were mostly working, but the sprites were broken, and Sonic was still falling through the floor to his death. I had added the Z80 coprocessor into the system, now that it was implemented (I might as well), but I had left the Z80 address space as one big 64 KB MemoryBlock. The Z80 alone didn't changed anything in Sonic 2, or in Sonic 1, which was still getting stuck at the title screen as it a had before.

I needed a way to isolate the drawing of sprites so I could better figure out what was wrong, and it was only at this point it occurred to me to search for demo and test ROMs that might help. That immediately turned up ComradeOj's demos, particularly Tiny Demo, which scrolls some text across the screen, and GenTest v3 which contains a number of screens with different graphics to test possible issues, including a display of some static sprites.

I also came across the BlastEm emulator in C, which has a builtin debugger. I was able to modify and compile a local version which dumps out the contents of VRAM at a specific point in a ROM's execution. With this, I could verify that the data in VRAM in Moa was correct and the DMA and transfer code was in fact working correctly. I ended up not digging into the BlastEm code much beyond this, but the validation it provided was extremely helpful.

VRAM Discrepancies

The above image is the results of running TinyDemo. Clearly the text is all garbled but I haven't a clue what could be causing it. At least it was a very small ROM, with straight-forward assembly code.

The first thing I could do was to try to isolate where the problem was. Was it caused by getting data into VRAM, or was it somewhere else. I started by running the demo in BlastEm and dumping the VRAM at the point in the ROM just after the VDP is initialized, at address 0xDE. I went to the same point in Moa and again dumped the contents of VRAM to compare them.

From BlastEm, the start of VRAM where the patterns are stored looks like this:

0000: 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 
0010: 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 
0020: 0x0110 0x0110 0x0110 0x0110 0x0110 0x0110 0x0111 0x1110 
0030: 0x0110 0x0110 0x0110 0x0110 0x0110 0x0110 0x0000 0x0000 
0040: 0x0011 0x1111 0x0011 0x0000 0x0011 0x0000 0x0011 0x1110 
0050: 0x0011 0x0000 0x0011 0x0000 0x0011 0x1111 0x0000 0x0000 
0060: 0x0110 0x0110 0x0110 0x0110 0x0110 0x0110 0x0011 0x1100 
0070: 0x0001 0x1000 0x0001 0x1000 0x0001 0x1000 0x0000 0x0000 
0080: 0x0011 0x1111 0x0011 0x0000 0x0011 0x0000 0x0011 0x1110 
0090: 0x0011 0x0000 0x0011 0x0000 0x0011 0x0000 0x0000 0x0000 
00a0: 0x0111 0x1110 0x0001 0x1000 0x0001 0x1000 0x0001 0x1000 
00b0: 0x0001 0x1000 0x0001 0x1000 0x0001 0x1000 0x0000 0x0000 
00c0: 0x0011 0x0000 0x0011 0x0000 0x0100 0x0000 0x0000 0x0000 
00d0: 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 
00e0: 0x0111 0x1110 0x0110 0x0011 0x0110 0x0011 0x0111 0x1110 
00f0: 0x0110 0x1000 0x0110 0x0110 0x0110 0x0111 0x0000 0x0000

And from Moa, it looks like this:

0000: 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 
0010: 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 
0020: 0x0110 0x0110 0x0110 0x0110 0x0110 0x0110 0x0111 0x1110 
0030: 0x0110 0x0110 0x0110 0x0110 0x0110 0x0110 0x0000 0x0000 
0040: 0x0011 0x1111 0x0011 0x1111 0x0011 0x1111 0x0011 0x1111 
0050: 0x0000 0x0011 0x0011 0x1111 0x0011 0x1111 0x0011 0x0011 
0060: 0x1100 0x0110 0x0110 0x0110 0x0110 0x0110 0x0000 0x0000 
0070: 0x1100 0x1100 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 
0080: 0x0011 0x1111 0x0011 0x1111 0x0011 0x1111 0x0011 0x1111 
0090: 0x0000 0x0011 0x0011 0x1111 0x0011 0x1111 0x0000 0x0000 
00a0: 0x1111 0x1110 0x0110 0x1100 0x0000 0x0000 0x0000 0x0000 
00b0: 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 
00c0: 0x0011 0x1111 0x0011 0x1111 0x0011 0x0100 0x0000 0x0011 
00d0: 0x1111 0x1111 0x1111 0x1111 0x1111 0x1111 0x1111 0x1111 
00e0: 0x1111 0x1110 0x0110 0x0110 0x1111 0x0110 0x1111 0x0110 
00f0: 0x0110 0x0110 0x1011 0x0000 0x0110 0x0111 0x1110 0x0000

It's almost the same, but if you look closely there are a few discrepancies. Of course I was expecting it to be caused by the transfer code, but I traced the assembly for TinyDemo to see where the data in VRAM was coming from. There's a loop that simply copied data from RAM address 0xFF0000 into VRAM address 0x0000. I dumped the contents of RAM at that location and sure enough, the difference occurred there too, so it was something further up the chain. Finally I was making some progress now that I could narrow down the problems better.

Tracing back in the disassembled output quickly led to the decompress function, which loads and decompresses the raw binary data in the ROM into an in-memory representation that the VDP can use.

...
 1f2:   e24d            lsrw #1,%d5             ; start of decompress loop
 1f4:   40c6            movew %sr,%d6
 1f6:   51cc 000c       dbf %d4,0x204

 1fa:   1f5d 0001       moveb %a5@+,%sp@(1)
 1fe:   1e9d            moveb %a5@+,%sp@
 200:   3a17            movew %sp@,%d5
 202:   780f            moveq #15,%d4
 204:   44c6            movew %d6,%ccr
 206:   6404            bccs 0x20c

 208:   12dd            moveb %a5@+,%a1@+
 20a:   60e6            bras 0x1f2              ; jump to start of outer loop

 20c:   7600            moveq #0,%d3
 20e:   e24d            lsrw #1,%d5
 210:   40c6            movew %sr,%d6
 212:   51cc 000c       dbf %d4,0x220

 216:   1f5d 0001       moveb %a5@+,%sp@(1)
 21a:   1e9d            moveb %a5@+,%sp@
 21c:   3a17            movew %sp@,%d5
 21e:   780f            moveq #15,%d4
 220:   44c6            movew %d6,%ccr
 222:   652c            bcss 0x250

 224:   e24d            lsrw #1,%d5
 226:   51cc 000c       dbf %d4,0x234

 22a:   1f5d 0001       moveb %a5@+,%sp@(1)
 22e:   1e9d            moveb %a5@+,%sp@
 230:   3a17            movew %sp@,%d5
 232:   780f            moveq #15,%d4
 234:   e353            roxlw #1,%d3
 236:   e24d            lsrw #1,%d5
 238:   51cc 000c       dbf %d4,0x246

 23c:   1f5d 0001       moveb %a5@+,%sp@(1)
 240:   1e9d            moveb %a5@+,%sp@
 242:   3a17            movew %sp@,%d5
 244:   780f            moveq #15,%d4
 246:   e353            roxlw #1,%d3
 248:   5243            addqw #1,%d3
 24a:   74ff            moveq #-1,%d2
 24c:   141d            moveb %a5@+,%d2
 24e:   6016            bras 0x266

 250:   101d            moveb %a5@+,%d0
 252:   121d            moveb %a5@+,%d1
 254:   74ff            moveq #-1,%d2
 256:   1401            moveb %d1,%d2
 258:   eb4a            lslw #5,%d2
 25a:   1400            moveb %d0,%d2
 25c:   0241 0007       andiw #7,%d1
 260:   6710            beqs 0x272
 262:   1601            moveb %d1,%d3
 264:   5243            addqw #1,%d3
 266:   1031 2000       moveb %a1@(0000000000000000,%d2:w),%d0
 26a:   12c0            moveb %d0,%a1@+
 26c:   51cb fff8       dbf %d3,0x266

 270:   6080            bras 0x1f2              ; jump to the start of the outer loop
...

The above snippet only shows the main loop of the decompress function and not the beginning and ending parts of the function. Instructions 0x266 and 0x26a are where a byte of data is written to the location in RAM where the decompressed data goes, and which will then be loaded into VRAM verbatim.

I knew from the above dumps that the first byte that differs occurs at offset 0x46, and dumping the registers shows the address 0xFF0000 in register %a1, which is incremented each time the loop occurs. To get to the point of failure, I just need to set a breakpoint at 0x266 and continue until register %a1 contains 0xFF0046, and then dump all the register values to look for a difference between Moa's register values and BlastEm's.

Aha! The value of %d6 is different. Moa has 0x2710 while BlastEm has 0x2700. Looking at the disassembly, the only use of %d6 is to temporarily hold the contents of the flags register (%ccr which is the lower byte of status register %sr). The flag register values are also different! The Extend bit, which is the 5th bit in the status register is the only difference between the two emulators. I was already suspicious of the flags, since they are rather complicated to simulate and can behave differently for different instructions. Of all the flags, the Extend which isn't used by many instructions is probably the one I'm not emulating correctly, so I seem to be on the right track.

Stepping through the program in BlastEm shows that the Extend flag is set after the lsrw #1,%d5 instruction, which occurs a few times in the function. The Motorola Documentation for the LSR instruction shows that both the Extend flag and Carry flag should be set to the bit value shifted out (the least significant bit). The rust code for the LSd instruction, which sets the flags, is shown below.

self.set_logic_flags(pair.0, size);
if pair.1 {
    self.set_flag(Flags::Carry, true);
    self.set_flag(Flags::Extend, true);
}

I must have assumed that the .set_logic_flags function would clear the Extend flag when I originally wrote this code, as it does for the other four flags. Most logic operations don't affect the Extend flag though, so the .set_logic_flags() function is only clearing the lower 4 bits (the Extend flag being the 5th bit). After the call, the Extend and Carry flags are set to true only if the bit shifted out, which is stored inpair.1, is true. If the Extend flag was set to true from a previous instruction, it wouldn't be cleared. That was enough of a discrepancy to cause the garbled text, and a whole lot more. Effing flags...

While the Extend flag is never directly tested in a comparison in this function, there are some ROXd instructions (where d is the direction (L)eft or (R)ight). Unlike the ROd instruction, which rotates bits within the same value, the ROXd instruction rotates through the Extend flag, so the value in Extend will be put into the number (either the left or right end), and the bit rotated out of the opposite end will be put into Extend. So an error in the Extend flag could definitely cause some problem with the decompress code.

Adding a line of code to clear the Extend flag before the .set_logic_flags() function is called is enough to fix it. Now the text in the demo is showing legibly. It's still nothing like what it looks like in BlastEm, which has a moving background that stretches the text vertically, but I'm still calling it a win.

And looking at Sonic 2, it's still very garbled but Sonic is no longer falling to his death! The Extend flag in the shift and rotate instructions was the cause of whichever comparison lead to Sonic not being on firm ground. I didn't even have to dig into the source of that problem in the Sonic 2 ROM to fix it, which was a relief.

You Can't Write There, Sir

Switching gears, I tried GenTestV3, which would immediately fail when run because it attempted to write to what should have been a read only memory area (the ROM data itself). I had added a way to mark a MemoryBlock as read only, which would raise an error when the .write() function is called on that block, as a means of catching errors. It had helped catch a few things when working on the Macintosh support, so I had added it to the Genesis ROMs as well.

Since I was getting an error when the attempted write occurred, I knew exactly where the fault was, address 0x2976, and I also knew what the values of the registers at that point were:

...
292c:   7000            moveq #0,%d0
292e:   7200            moveq #0,%d1
2930:   7400            moveq #0,%d2
2932:   7600            moveq #0,%d3
2934:   7800            moveq #0,%d4
2936:   7a00            moveq #0,%d5
2938:   7c00            moveq #0,%d6
293a:   7e00            moveq #0,%d7
293c:   207c 0000 0000  moveal #0,%a0
2942:   227c 0000 0000  moveal #0,%a1
2948:   247c 0000 0000  moveal #0,%a2
294e:   287c 0000 0000  moveal #0,%a4
2954:   2a7c 0000 0000  moveal #0,%a5
295a:   2e7c 0000 0000  moveal #0,%sp
2960:   4ed6            jmp %fp@

2962:   303c 7fff       movew #0x7fff,%d0
2966:   207c 00ff 0000  moveal #0xff0000,%a0
296c:   30fc 0000       movew #0,%a0@+
2970:   51c8 fffa       dbf %d0,0x296c
2974:   4ed2            jmp %a2@

2976:   297c 4000 0000  movel #0x40000000,%a4@(4)       ; invalid write here
297c:   0004 
297e:   383c 7fff       movew #0x7fff,%d4
2982:   38bc 0000       movew #0,%a4@
2986:   51cc fffa       dbf %d4,0x2982
298a:   4ed2            jmp %a2@
...

And the register values:

Breakpoint reached: Attempt to write to read-only memory at 4 with data [64, 0]
@ 18201056 ns
0x0000297e: 383c 7fff 
        movew   #00007fff, %d4

Status: Running
PC: 0x0000297e
SR: 0x2700
D0: 0x00000000        A0:  0x00000000
D1: 0x00000000        A1:  0x00000000
D2: 0x00000000        A2:  0x00002592
D3: 0x00000000        A3:  0x00000000
D4: 0x00000000        A4:  0x00000000
D5: 0x00000000        A5:  0x00000000
D6: 0x00000000        A6:  0x00002588
D7: 0x00000000
SSP: 0x00000000
USP: 0x00000000
Current Instruction: 0x0000297e MOVE(Immediate(32767), DirectDReg(4), Word)

0x00000000: 0x00ff 0xfffe 0x0000 0x0200 0x0000 0x30e2 0x0000 0x30ee 
0x00000010: 0x0000 0x3076 0x0000 0x308e 0x0000 0x309a 0x0000 0x30a6 
0x00000020: 0x0000 0x30b2 0x0000 0x30be 0x0000 0x30ca 0x0000 0x30d6 
0x00000030: 0x0000 0x306a 0x444f 0x4e27 0x5420 0x4c4f 0x4f4b 0x2041

The register %a4 contains 0x00000000, plus an offset of 4, so it's trying to write to address 0x00000004, the reset vector. That can't possibly be right. In BlastEm, I tried setting the same address as a breakpoint and, would you look at that, the breakpoint isn't reached! That code isn't even running in BlastEm when GenTest is run. If you notice from the snippet above, jmp instructions are being used to return to the calling function, and branch instructions are being used to call them, rather than using the stack. So the return address is not on the stack, but in register %a2, which contains 0x2592 which is the instruction after the one that called this function. We're on to something here.

256c:   6700 dcae       beqw 0x21c
2570:   60d8            bras 0x254a

2572:   7400            moveq #0,%d2
2574:   3e7c 0000       moveaw #0,%sp
2578:   2c7c 0000 0000  moveal #0,%fp
257e:   4df9 0000 2588  lea 0x2588,%fp
2584:   6000 03a6       braw 0x292c     ; jump to a different function (shown above)

2588:   45f9 0000 2592  lea 0x2592,%a2
258e:   6000 03e6       braw 0x2976     ; jump to the troublesome function

2592:   297c 6000 0002  movel #1610612738,%a4@(4)
2598:   0004 
259a:   4bf9 0000 8156  lea 0x8156,%a5

Address 0x258e contains a branch instruction to the exact address that the erroneous write occurs on, and before that, the return register %a2 is loaded with the return value. What about the instruction before that? It's a branch to 0x292c which appears in the previous snippet, which seems to be a function that sets all the register values to 0! Wait, why would it do that? The register values were almost all 0 when the error occurred, except for the two registers used as return values, so it did run that code, but why would it clear everything just before using an now zero'd register as an address.

I set a breakpoint for 0x2572, which looked like the start of the current function, given that there's a branch instruction just before. The %a4 register, interestingly enough, contains 0xc00000, which would make sense as the intended value of %a4 where the erroneous write occurred, if all the registers hadn't been cleared just before. Most of the other registers are 0 except for %a2 which contains 0x2554, possibly the return value of the caller.

...
253e:   297c 6000 0002  movel #1610612738,%a4@(4)
2544:   0004 
2546:   6000 0396       braw 0x28de
254a:   45f9 0000 2554  lea 0x2554,%a2
2550:   6000 04f8       braw 0x2a4a

2554:   1e03            moveb %d3,%d7
2556:   0007 00ef       orib #-17,%d7
255a:   0c07 00ef       cmpib #-17,%d7  ; the value of %d7 should
                                        ; be 0xff, but it's 0xef

255e:   6700 0012       beqw 0x2572     ; this is where the problem
                                        ; occurs (shouldn't jump but does)

2562:   1e03            moveb %d3,%d7
2564:   0007 00bf       orib #-65,%d7
2568:   0c07 00bf       cmpib #-65,%d7
256c:   6700 dcae       beqw 0x21c
2570:   60d8            bras 0x254a
...

There's a jump to the start of our function that shouldn't run at 0x255e, which... isn't quite what I was expecting. I was somehow expecting the previous code to somehow make sense, but alright, it's maybe taking a jump that shouldn't happen (even though it seems like it should never ever happen), so why is it jumping when it shouldn't.

I set a breakpoint for 0x2554 in both emulators to see if that code would run and this time, BlastEm runs that code. Stepping through the code in both emulators shows the status register values are different just after the comparison at 0x255a. groan Not the flags again.

Looking closer at the code though, the values of %d7 are different between the emulators as well. The comparison in Moa is setting the flags correctly for the data used, but the data values are different, and so BlastEm doesn't make the branch where Moa does. Ok, so maybe it's not the flags this time. So why are the values of %d7 different. Well it's set just a few instructions ahead with the lower byte value of %d3, which in Moa is 0. In BlastEm, it's 0xff. Aha! So where is %d3 set?

It's not set in the code just above the comparison, but there is a branch to 0x2a4a just before which looks like a register-returning function call, and the code at that location does change %d3.

2a4a:   7600            moveq #0,%d3
2a4c:   7e00            moveq #0,%d7
2a4e:   13fc 0040 00a1  moveb #0x40,0xa10009
2a54:   0009 
2a56:   13fc 0040 00a1  moveb #0x40,0xa10003
2a5c:   0003 
2a5e:   4e71            nop
2a60:   4e71            nop
2a62:   1639 00a1 0003  moveb 0xa10003,%d3
2a68:   0203 003f       andib #0x3f,%d3
2a6c:   13fc 0000 00a1  moveb #0,0xa10003
2a72:   0003 
2a74:   4e71            nop
2a76:   4e71            nop
2a78:   1e39 00a1 0003  moveb 0xa10003,%d7
2a7e:   0207 0030       andib #0x30,%d7
2a82:   e50f            lslb #2,%d7
2a84:   8607            orb %d7,%d3
2a86:   4ed2            jmp %a2@

Tracing through the debuggers shows that this is the code where BlastEm gets 0xff into register %d3 and it's doing it by reading the controller input. 0xa10003 is the byte address of the data port for controller 1, and 0xa10009 is the control port for controller 1. I had taken a stab at implementing the weird TH counting that the controllers need to do, but I hadn't tested it. I had only hooked up the Start button to a key press, which was all I had needed up until this point, to get through the title screen to the game play.

Here, from the code, it seemed as if the correct behaviour, at least according to how BlastEm worked, was for the controllers to return 0xff when no buttons are pressed, rather than 0. Changing that one thing is Moa got to the first screen of GenTest asking which test to run! Success! Well, I still needed to fix the controllers properly, since button presses still didn't work, but this is at least the cause of GenTest not running.

There turned out to be quite a few minor bugs in the TH counting code. The count was incrementing twice as often as it should have, and the button states needed to be inverted (1 means the button is not pressed and 0 means it is). I also needed to reset the counter when the control port was written to, for the count to be in sync with what the ROM was expecting. Not all ROMs progressed through the entire count, if they only needed to read a few buttons. Eventually I got it sorted out and buttons were working but it took a while to get them right. The latest code for the controllers is here

Fixing Sprites

I had been back at it for about 4 or 5 days now and I had already ticked off two major issues. I could now control the characters in game play, even though I couldn't see much of what was going on still. The elephant in the room was those sprites not working, so with my enthusiasm high, I pressed on to tackle the sprites.

Fixing the Extend flag bug fixed Sonic falling through the floor to his death, so that was a significant step forward, but multi-cell sprites were still being drawn incorrectly. Luckily the GenTest ROM has a page that displays a static multi-pattern sprite, both forward and reversed.

The forward sprite (Knuckles) works fine, but the reversed sprite (Sonic) is messed up. If you look closely, you can see the vertical columns of cells seem to line up correctly, but the horizontal arrangement of the columns is mixed up. This one turned out to be a bit subtle.

I had tried fiddling with reversing the cell drawing order in multicell sprites but to no avail. It turned out when switching the revere-sprite code I was changing both the order of the cells, and also reversing the positions they were drawn in, rather than switching only one. I was also adjusting both coordinates instead of just the horizontal arrangement. At the time I didn't have a way of just drawing one sprite in one location to inspect it closely enough to figure out what was wrong, but the GenTest ROM made it much clearer what was wrong. I also had an off by one error with reversed sprites where I needed to subtract one from the size in order to get the right vertical row of patterns to use.

First, the existing code is shown below. Note: Multi-cell sprites are drawn top to bottom, left to right, unlike everything else in the Genesis, so the outer loop is for the horizontal direction, and the inner loop is the vertical direction. The variables that appear are defined as follows:

pattern_name is the 16-bit pattern specifier
(h_pos, v_pos) is the pixel position on screen where the sprite should be drawn
(size_h, size_v) is the size in cells of the sprite
(h_rev, v_rev) are bools of whether the sprite should be reversed in a given direction
self.is_sprite_on_screen(x, y) returns whether those pixel positions are on-screen (sprites can be entirely off the screen, in which case they wont be drawn)

for ih in 0..size_h {
    for iv in 0..size_v {
        let h = if !h_rev { ih } else { size_h - ih };
        let v = if !v_rev { iv } else { size_v - iv };
        let (x, y) = (h_pos + h * 8, v_pos + v * 8);

        if self.is_sprite_on_screen(x, y) {
            let iter = self.get_pattern_iter(
                (pattern_name & 0xF800)
                | ((pattern_name & 0x07FF) + (h * size_v) + v)
            );

            frame.blit(x as u32 - 128, y as u32 - 128, iter, 8, 8);
        }
    }
}

Changing the following lines is enough to fix it. It needs to take an extra 1 off the h and v values when the sprite is reversed, and also use the loop's values to calculate the position where the cell should be drawn instead of using the previously calculated cell positions, which have already been reversed.

    let h = if !h_rev { ih } else { size_h - 1 - ih };
    let v = if !v_rev { iv } else { size_v - 1 - iv };
    let (x, y) = (h_pos + ih * 8, v_pos + iv * 8);

And now the sprites work! That was surprisingly simple given how broken they looked before. I had been close, but it only takes an off by one error to make the output mangled beyond recognition sometimes.

The intro sprites in Earthworm Jim are working now too. I had tried to use that game for testing sprites before I had taken that break, but it wasn't as helpful as the GenTest sprite screen.

Not All The Data

How is Sonic 2 looking now that the sprites have been fixed.

Well... it honestly doesn't look any different. In fact this is the same image from after the Extend flag was fixed, but before the sprites were fixed. I literally could not tell the difference between the image before and after fixing the sprites, they were so identical, so I didn't even bother adding another screenshot. No wonder I couldn't fix the sprites before, when I was using Sonic 2 to test with. The garbled sprites in Sonic 2 were caused by something else entirely.

Are there any other test screens in the GenTest ROM that looked messed up? Sure enough, all the video output patterns are broken. I'll use the colour bleed test as an example.

Well that's definitely not what it should look like. Inspecting the VRAM shows shows that only about half the data is loaded that should be loaded by comparison to BlastEm. I found the spot in the ROM where the data is loaded into the VDP using a DMA transfer. The source data in RAM actually is complete this time, even though the VRAM data is only partially present, so this time it is an issue with transferring data into the VDP. Playing around with the debugger in BlastEm I noticed something in the output for the VDP state:

**DMA Group**
13: 00 |
14: 46 | DMA Length: $4600 words
15: 00 |
16: 88 |
17: 7F | DMA Source Address: $FF1000, Type: 68K

It says the DMA length is 0x4600 words (not bytes). Crap... I had assumed that the DMA count was in bytes, not words. Could it really be that simple a problem? Yup...

I was subtracting 2 instead of 1 from the count every iteration of the DMA loop, causing it to end half way through the intended transfer size. It really was that simple

And now Sonic 2 looks like this:

Much better! It almost looks right except for the foreground that's out of place. I haven't even attempted to implement the horizontal and vertical scrolling functionality of the VDP yet, so that must be what's going on. This is finally coming together.

Scrolling The Scrolls

It had been less than a week since I had returned to it, and I had fixed all the glaring issues that were mangling the graphics. It was finally time to implement something new from the Sega docs, that I had left for later. Later was now! It was time to implement the scrolling features.

As mentioned before, the scrolls are much bigger than can fit on the screen at once. In order to be able to quickly update what's shown on the screen without changing all the cell data, the scroll planes can be moved relative to the screen to change what part of the scroll plane will appear on the screen. Each scroll can be moved independently of each other to create a parallax effect.

The vertical and horizontal scrolling work a bit differently from each other. For one, the vertical scroll direction has its own special memory, the VSRAM, where as the horizontal scroll data is stored in a table in VRAM, with the starting address of the table set by a VDP register.

For the vertical scroll position, either a single offset can be used to move the whole plane, or every two cells can have a different vertical offset. Each offset is an unsigned number between 0 and 1023 (which is the maximum number of pixel of the largest possible scroll size of 128 cells). Since VSRAM is 80 bytes, that means there can be 40 16-bit words, 20 for each of the two scrolls interleaved with each other, which covers the maximum 40 cell width of the screen.

For the horizontal scroll position, either a single offset can move the whole plane, or every cell can have a different offset, or every line can have a different offset. For the cell offset setting, only a maximum of 30 offsets for each scroll are needed, but they are stored in a table with the same size as used by the per-line scrolling mode. The per-line scrolling mode needs 896 bytes for the NTSC version's 224 line output (960 bytes for the full 240 line resolution of PAL). Like the vertical offsets, each offset is a 16-bit word and ranges from 0-1023, and the offsets for Scroll A and Scroll B are interleaved in the horizontal scroll table.

pub fn get_hscroll(&self, hcell: usize, line: usize) -> (u32, u32) {
    let scroll_addr = match self.mode_3 & MODE3_BF_H_SCROLL_MODE {
        0 => self.hscroll_addr,
        2 => self.hscroll_addr + (hcell << 5),
        3 => self.hscroll_addr + (hcell << 5) + (line * 2 * 2),
        _ => panic!("Unsupported horizontal scroll mode"),
    };

    let scroll_a = read_beu16(&self.vram[scroll_addr..]) as u32 & 0x3FF;
    let scroll_b = read_beu16(&self.vram[scroll_addr + 2..]) as u32 & 0x3FF;
    (scroll_a, scroll_b)
}

pub fn get_vscroll(&self, vcell: usize) -> (u32, u32) {
    let scroll_addr = match (self.mode_3 & MODE3_BF_V_SCROLL_MODE) {
        0 => 0,
        _ => vcell >> 1,
    };

    let scroll_a = read_beu16(&self.vsram[scroll_addr..]) as u32 & 0x3FF;
    let scroll_b = read_beu16(&self.vsram[scroll_addr + 2..]) as u32 & 0x3FF;
    (scroll_a, scroll_b)
}

There are some weird glitches in Scroll B but Scroll A seems to work fine. It only moves a whole cell at a time, so Scroll A appears jerky compared to the sprites. It's especially noticeable at the edge of the bridge. The bridge is made of sprites, which can be positioned to the exact pixel, but the ground where the bridge is supposed to be attached to will only move when a whole cell has changed.

Fixing Line Scrolling

It had been about a week and a half since I took up the Genesis again. With the help of the test ROMs and BlastEm, I had made pretty quick work of a whole bunch of little bugs, going from what was still a very garbled output to having the games playable. I wasn't done yet though.

After spending a week working on Computie when my new PCBs arrived, I returned to the Genesis to work on the per-line scrolling. I also dabbled a bit with audio support, adding a dummy device for the YM2612 audio FM synthesizer chip, which is mapped to the Z80 coprocessor's address space, and fixing the Z80 banked memory area, so that it could access the 68k ROM or RAM data. With that, I was able to get the Z80 coprocessor working well enough that Sonic 1 would get past the title screen and into the game.

I was bothered that per-line scrolling wasn't working, and that the scrolls moved in a jerky fashion. I needed to fix it but it would require more than a few simple changes. Since the per-cell scrolling was working, I chose to write a completely different version of the draw_scrolls function just for per-line scrolling. I could integrate them later if possible but it would be easier to completely rewrite it without breaking what I already had.

I was still hoping to use the pattern iterator I had written, but I would need to change it to take the line number on initialization, so that I could output only one line of a pattern at a time. I then used another loop inside the horizontal and vertical cell loops to iterate over each of the 8 lines in a pattern, using a different offset for each line of the pattern.

My first attempt used the same loop to draw both scrolls at once, but the results were this:

There is clearly an issue caused by the scrolling since moving until the screen is on a cell boundary shows the foreground plane (Scroll A) completely on top of the background plane (Scroll B), but when the offset is between cells, Scroll B is getting drawn on top. Separating the drawing of each scroll (at the cost of duplicating the loops) fixed this problem, but there is still an issue with these strange black artifacts showing on the screen.

It took me a while of fussing around with the code before I realized that I had the line and column coordinates backwards when passing them to the scroll fetching functions. That's a little embarrassing. I was sending the cell_x value to the horizontal scroll offset when it should have been getting the cell_y value (ie. the horizontal offset is based on what line is currently being drawn, so you give it the line number and it gives you the x offset). Swapping these around and reorganizing the loops fixed this. Now the scrolling is smooth!

Rewriting

There were still some issues with the left hand and bottom edges of the screen where the foreground is not drawn to the edge because the scroll offset is not on a cell boundary. Changing the existing code to add an extra cell was not as trivial as it would appear. Shifting the cells over caused the sprites to be misaligned with the background, and starting the iterators one cell early would mean starting at -1, which would require changing to signed numbers, and possibly calculating an invalid offset due to the presence of negatives, or adding many checks to prevent that.

I also didn't have drawing priority working because I didn't have all the cell and sprite priority bits calculated at the same time, to determine which to display, and the code was awfully messy at this point. It was time to rewrite all the display code. I had learned so much and run into so many issue by this point. I had a better understanding of how it was all supposed to work now, and I could incorporate all those lessons in the next version.

In order to recreate the video output more accurately, I opted to more faithfully simulate what the hardware VDP would be doing. Since it's generating a video signal on the fly, it draws the image pixel by pixel, line by line, exactly in step with the CRT. If I did it this way, it would also allow me to implement the priority bits to decide on which pixel from the different planes should be drawn to the screen, since everything would be in the same loop. There would be a lot more duplicated calculations and slower performance as a result, but since the existing performance wasn't an issue, it should still be fast enough to emulate at full speed.

To make it easier to debug in the short term, I duplicated the code to calculate the cell indices for the scrolls. Later, I can break this up into multiple functions to reuse code, and also store some of the calculated values across iterations to avoid recalculating, but I wanted everything in one loop to make it easier to adjust while I debugged it. I did break out the vertical drawing loop from the horizontal one, which will eventually be used to step through the drawing line by line, instead of drawing the whole frame before the vertical interrupt, but this isn't yet implemented.

pub fn draw_frame(&mut self, frame: &mut Frame) {
    self.build_sprites_lists();

    for y in 0..(self.screen_size.1 * 8) {
        self.draw_frame_line(frame, y);
    }
}

pub fn draw_frame_line(&mut self, frame: &mut Frame, y: usize) {
    let bg_colour = ((self.background & 0x30) >> 4, self.background & 0x0f);

    let (hscrolling_a, hscrolling_b) = self.get_hscroll(y / 8, y % 8);
    for x in 0..(self.screen_size.0 * 8) {
        let (vscrolling_a, vscrolling_b) = self.get_vscroll(x / 8);

        let pixel_b_x = (x - hscrolling_b) % (self.scroll_size.0 * 8);
        let pixel_b_y = (y + vscrolling_b) % (self.scroll_size.1 * 8);
        let pattern_b_addr = self.get_pattern_addr(self.scroll_b_addr, pixel_b_x / 8, pixel_b_y / 8);
        let pattern_b_word = self.memory.read_beu16(Memory::Vram, pattern_b_addr);
        let priority_b = (pattern_b_word & 0x8000) != 0;
        let pixel_b = self.get_pattern_pixel(pattern_b_word, pixel_b_x % 8, pixel_b_y % 8);

        let pixel_a_x = (x - hscrolling_a) % (self.scroll_size.0 * 8);
        let pixel_a_y = (y + vscrolling_a) % (self.scroll_size.1 * 8);
        let pattern_a_addr = self.get_pattern_addr(self.scroll_a_addr, pixel_a_x / 8, pixel_a_y / 8);
        let pattern_a_word = self.memory.read_beu16(Memory::Vram, pattern_a_addr);
        let mut priority_a = (pattern_a_word & 0x8000) != 0;
        let mut pixel_a = self.get_pattern_pixel(pattern_a_word, pixel_a_x % 8, pixel_a_y % 8);

        if self.window_addr != 0 && self.is_inside_window(x, y) { 
            let pixel_win_x = x - self.window_pos.0.0 * 8;
            let pixel_win_y = y - self.window_pos.0.1 * 8;
            let pattern_win_addr = self.get_pattern_addr(self.window_addr, pixel_win_x / 8, pixel_win_y / 8);
            let pattern_win_word = self.memory.read_beu16(Memory::Vram, pattern_win_addr);

            // Scroll A is not displayed where ever the Window is displayed, so we replace Scroll A's data
            priority_a = (pattern_win_word & 0x8000) != 0;
            pixel_a = self.get_pattern_pixel(pattern_win_word, pixel_win_x % 8, pixel_win_y % 8);
        };

        let mut pixel_sprite = (0, 0);
        let mut priority_sprite = false;
        for sprite_num in self.sprites_by_line[y].iter() {
            let sprite = &self.sprites[*sprite_num];
            let offset_x = x as i16 - sprite.pos.0;
            let offset_y = y as i16 - sprite.pos.1;

            if offset_x >= 0 && offset_x < (sprite.size.0 as i16 * 8) {
                let pattern = sprite.calculate_pattern(offset_x as usize / 8, offset_y as usize / 8);
                priority_sprite = (pattern & 0x8000) != 0;

                pixel_sprite = self.get_pattern_pixel(pattern, offset_x as usize % 8, offset_y as usize % 8);
                if pixel_sprite.1 != 0 {
                    break;
                }
            }
        }

        let pixels = match (priority_sprite, priority_a, priority_b) {
            (false, false, true)  => [ pixel_b,      pixel_sprite, pixel_a,      bg_colour ],
            (true,  false, true)  => [ pixel_sprite, pixel_b,      pixel_a,      bg_colour ],
            (false, true,  false) => [ pixel_a,      pixel_sprite, pixel_b,      bg_colour ],
            (false, true,  true)  => [ pixel_a,      pixel_b,      pixel_sprite, bg_colour ],
            _                     => [ pixel_sprite, pixel_a,      pixel_b,      bg_colour ],
        };

        for i in 0..pixels.len() {
            if pixels[i].1 != 0 || i == pixels.len() - 1 {
                let mode = if pixels[i] == (3, 14) {
                    ColourMode::Highlight
                } else if (!priority_a && !priority_b) || pixels[i] == (3, 15) {
                    ColourMode::Shadow
                } else {
                    ColourMode::Normal
                };

                frame.set_pixel(x as u32, y as u32, self.get_palette_colour(pixels[i].0, pixels[i].1, mode));
                break;
            }
        }
    }
}

#[inline(always)]
fn get_pattern_addr(&self, cell_table: usize, cell_x: usize, cell_y: usize) -> usize {
    cell_table + ((cell_x + (cell_y * self.scroll_size.0 as usize)) << 1)
}

fn get_pattern_pixel(&self, pattern_word: u16, x: usize, y: usize) -> (u8, u8) {
    let pattern_addr = (pattern_word & 0x07FF) << 5;
    let palette = ((pattern_word & 0x6000) >> 13) as u8;
    let h_rev = (pattern_word & 0x0800) != 0;
    let v_rev = (pattern_word & 0x1000) != 0;

    let line = if !v_rev { y } else { 7 - y };
    let column = if !h_rev { x / 2 } else { 3 - (x / 2) };

    let offset = pattern_addr as usize + line * 4 + column;
    let second = x % 2 == 1;
    let value = if (!h_rev && !second) || (h_rev && second) {
        (palette, self.memory.vram[offset] >> 4)
    } else {
        (palette, self.memory.vram[offset] & 0x0f)
    };

    value
}

fn build_sprites_lists(&mut self) {
    let sprite_table = self.sprites_addr;
    let max_lines = self.screen_size.1 * 8;

    self.sprites.clear();
    self.sprites_by_line = vec![vec![]; max_lines];

    let mut link = 0;
    loop {
        let sprite = Sprite::new(&self.memory.vram[sprite_table + (link * 8)..]);

        let start_y = sprite.pos.1;
        for y in 0..(sprite.size.1 as i16 * 8) {
            let pos_y = start_y + y;
            if pos_y >= 0 && pos_y < max_lines as i16 {
                self.sprites_by_line[pos_y as usize].push(self.sprites.len());
            }
        }

        link = sprite.link as usize;
        self.sprites.push(sprite);

        if link == 0 {
            break;
        }
    }
}

Finally... It's working pretty good, it scrolls smoothly, it sorts out the priority so Sonic appears behind the trees. It works better than this gif even shows. I recorded it at 15 frames a second instead of 30 or 60, to keep the file size small, so when Sonic gets his fast boots, it seems like the sprite isn't animated, but it's actually just moving too fast to be recorded.

For those who are curious, out of each 16.6ms interval between updating a frame, the old display code was running in around 2ms, and the new code is running in around 6ms, so the new code is significantly slower (but still well within the time available). This is in part because I'm calculating which cell to draw for each of the planes, and fetching the scroll values, for each pixel on the screen. This could be improved upon by storing the pattern data for the current cells for each plane between iterations and only updating them when the cell changes. That said, doing so will only make a small improvement in performance, while also making the code harder to read.

Conclusion

This project definitely turned into more than I was expecting when I started. I had hoped to get some pretty graphics after only a few weeks of work, (the initial implementation only took about that long), but that didn't happen and it quickly became my white whale. I had to finish it. The real journey was the eight weeks of switching between debugging and working on other projects while the problems percolated in the back of my brain. But I did it. I got it to a playable (albeit still buggy) state.

Special thanks to ComradeOj for the demo ROMs, and Mike Pavone and the other contributors for BlastEm (github mirror). Without these, it would have taken a lot more time to get this working.

There is still a lot to do, and I will likely work on this project on and off for a while to come. Audio needs to be added, and a lot of games don't quite run correctly because of one reason or another. Thanks for joining me and I hope you learned something as well, or at least got to enjoy some nostalgic thoughts of the Sega Genesis. If there's anything you'd like to me to write more about or you have any feedback about these posts, I'd love to hear it on twitter or by email. Happy Emulating!

Emulating the Sega Genesis - Part II

transistor fet — Wed, 12 Jan 2022 18:55:07 +0000

Originally published at jabberwocky.ca

Written December 2021/January 2022 by transistor_fet

This is Part II in the series. If you haven't already read Part I, you might want to do so. It covers setting up the emulator, getting some game ROMs to run, and implementing the DMA and memory features of the VDP. Part II covers adding a graphical frontend to Moa, and then implementing a first attempt at generating video output. Part III will be about debugging the various problems in the VDP and CPU implementations to get a working emulator capable of playing games. For more detail on the 68000 and the basic design of Moa, check out Making a 68000 Emulator in Rust.

Previously
Choosing A Graphics Crate
Abstracting Out The Frontend
Updating Windows
The VDP Device
Colours And Patterns
Scrolls And Sprites
Next Time

Previously

In less than a week, I had taken my 68000 emulator, plugged some Sega Genesis ROMs into it, written some boilerplate devices, and implemented the memory and DMA operations of the Genesis' video display processor (VDP). I could watch the log messages produced by the emulator as the ROMs were being interpreted instruction by instruction, reading the controller data, writing to the VDP, and generally doing things. (Doing what? I didn't quite know yet).

The CPU interface to the VDP was pretty much done, so the next thing to work on was actually displaying output. The data, which is already loaded into VRAM, CRAM, and VSRAM, as well as the internal VDP registers, needs to be turned into pictures. While the real hardware would generate a CRT video signal which would directly control a CRT-based television, the emulator will generate a single frame of video at a time, stored in a buffer, and display that buffer in a local window on the host computer. Do this fast enough and I'll video.

Choosing A Graphics Crate

Before I could implement the display output, I needed something to draw the images onto. There are quite a few Rust crates available to create a GUI window and update it with 2D graphics. Most of these are of course intended for making games, and also include ways of getting key presses as input, which I'll also need. I looked at Piston, which I've used before on other projects, Macroquad, which also supports web assembly as well as desktop targets, Pixels, which is intended specifically for 2D games, and Minifb, which is also specifically for 2D applications, but is much simpler. I also tried out libretro, which is specifically made for video game emulation, but I found it much more restrictive than the others because of it's narrow focus.

Initially I had wanted to run the simulation in another thread so that I could run it the same way I had been for emulating Computie, but most of these libraries are set up to use a single thread and single main loop where everything happens in-line with the screen updating and input reading. For a typical video game, the gameplay and any frame updating would be done just before submitting the frame buffer to the library to be drawn to the screen, and then the library would block until the next frame is needed.

In order to run it inline with the update loop, I added a function to System to only run the step functions for a given amount of simulated time before returning, which would allow the simulation to proceed far enough for the next frame to be updated before the loop updates the GUI window. Even though there is no specific coordination between when the frame is updated vs how much simulated time has passed, it still works surprisingly well. That said I'm still concerned with the fact that the emulator is not cycle-accurate yet, so the simulated time is not accurate either. Having the option of running it in another thread would allow me to use other means of coordinating the simulation with the real clock, and would give me more options when I implement other platforms. This was a major factor in choosing a library.

Piston is feature rich, and it's modular design allows it to be tailored for any given use, but it's a bit more than I need for this project. It includes all sorts of drawing primitives for 2D graphics, but what I really want is to just draw individual pixels to a buffer, or update the entire screen at once from a pre-drawn buffer. The size of the compiled binary using Piston was over 100MB too, with Pixels coming in a close second in size.

Pixels was also a bit more than I needed. It's based on wgpu which supports all sorts of GPU features like shading, but I don't need any of that since the Genesis will only generate raw pixel data, so the extra features just make it more complicated than it needs to be.

Macroquad is much lighter, by comparison, but because it can run in a web browser, it has some restrictions on how the updating can be done. It uses an async main function because in WebAssembly, the main loop cannot block like a normal loop without inhibiting other background code. It would be neat to run Moa in web assembly, but porting it to run in web assembly could be a lot of work that I don't intend to do any time soon, and since Macroquad wont easily support the threaded mode, I'll leave it as a possible secondary frontend for a later date.

Libretro has a similar restriction in that you give it a function to be called each time a frame is needed, and the simulation would have to be run in that time. However it also supplies its own main function and update loop, and control is only passed to the specific machine emulator when a game is loaded (which is also handled by the library) or when the next frame of data is needed. It might be fine for a single-purpose video game emulator but it really doesn't fit with my hope for a more general simulation platform, so this definitely isn't a good choice as my primary frontend.

That left Minifb, which turned out to be the best fit. It's very simple without a lot of features. You create a window (just one function call), a frame buffer to fill the window, and a main loop which just has to call a function to update the frame buffer to the screen. An optional frame limiter can be used, which causes the update function to block until the next frame is needed, but the simulation can be run on a separate thread too. Input can be read during the main loop, and the main loop is implemented entirely in the application-side, so it's a bit more flexible without being complicated for my needs. The compiled binary comes in at only 5 or 6 MB as well, which nice.

Abstracting Out The Frontend

As usual, given my obsession with flexibility and modularity, I set up the frontend so that it can be swapped out with another one. I need both a console-only "frontend" for Computie, and the minifb frontend for the Sega Genesis, so I made separate crates for each. Cargo has a "workspaces" feature to make it easy to organize a single repository into multiple crates, each compiled separately. The Cargo.toml file in the root directory of the project needs the following lines:

[workspace]
members = [".", "frontends/moa-console", "frontends/moa-minifb"]

The first directory is the current directory, which has the common Moa code in src/, and dependencies for that crate also go in the same Cargo.toml file in the root of the project. Each of the frontends have their own Cargo.toml files with their own dependencies and feature flags. They also contain files in frontends/<name>/src/bin/<machine>.rs which will be compiled into separate binaries, one for each machine that can be run using that frontend, which makes it easier to run different machines. In this configuration, if using cargo to compile and run a given binary, both the crate and binary name must be specified or else cargo will use the configured default.

The Genesis machine can be run using:

cargo run -p moa-minifb --bin moa-genesis

The moa-genesis binary looks something like this, with all the details hidden in init_frontend and start:

use moa_minifb;
use moa::machines::genesis::build_genesis;

fn main() {
    let mut frontend = MiniFrontend::init_frontend();
    let mut system = build_genesis(&frontend).unwrap();

    frontend.start(system);
}

In order to provide a generic frontend-agnostic interface between the common Moa devices and a specific frontend, there is a Host trait which is implemented by each frontend, and passed to the machine building function to build the System object. Through that trait, the machine definition can register a callback for whichever devices need to output video data (which is machine-specific). Separate callbacks can be registered through the same Host trait to get data from the keyboard or controllers.

pub trait Host {
    fn add_window(&mut self, _updater: Box<dyn WindowUpdater>) -> Result<(), Error> {
        // Default implementation if it's not defined in the 'impl Host for ...'
        Err(Error::new("This frontend doesn't support windows"))
    }

    fn register_controller(&mut self, _device: ControllerDevice, _input: Box<dyn ControllerUpdater>) -> Result<(), Error> {
        // Default implementation if it's not defined in the 'impl Host for ...'
        Err(Error::new("This frontend doesn't support game controllers"))
    }
}

pub trait WindowUpdater: Send {
    fn get_size(&mut self) -> (u32, u32);
    fn update_frame(&mut self, width: u32, height: u32, bitmap: &mut [u32]);
}

pub trait ControllerUpdater: Send {
    fn update_controller(&mut self, event: ControllerEvent);
}

The Host trait is implemented by each frontend and passed to the function that builds the machine configuration, before the simulation is started. The machine configuration can choose to create a window only when needed by that machine. Not shown in the above snippet are the Host functions to create PTYs (used only by Computie), and to register a keyboard updater (used by the TRS-80 and Macintosh machines).

pub struct MiniFrontend {
    pub updater: Option<Box<dyn WindowUpdater>>,
}

impl Host for MiniFrontend {
    fn add_window(&self, updater: Box<dyn WindowUpdater>) -> Result<(), Error> {
        if self.updater.is_some() {
            return Err(Error::new("A window updater has already been registered with the frontend"));
        }
        self.updater = Some(updater);
        Ok(())
    }
}

impl MiniFrontend {
    pub fn init_frontend() -> MiniFrontend {
        MiniFrontend {
            updater: None,
        }
    }

    pub fn start(&self, mut system: System) {
        let buffer = vec![0; WIDTH * HEIGHT]
        let options = minifb::WindowOptions::default();
        let mut window = minifb::Window::new("Test", WIDTH, HEIGHT, options).unwrap();

        // Limit to max ~60 fps update rate
        window.limit_update_rate(Some(Duration::from_micros(16600)));

        while window.is_open() && !window.is_key_down(Key::Escape) {
            // Run the simulation for 16.6ms, the same as the frame limiter
            system.run_for(16_600_000).unwrap();

            if let Some(updater) = self.updater {
                updater.update_frame(WIDTH as u32, HEIGHT as u32, &mut buffer);
                window.update_with_buffer(&buffer, WIDTH, HEIGHT).unwrap();
            }
        }
    }
}

There's not much to it. Only one window can be created at the moment, and input is not yet supported. The threaded option is also not shown here. Before long, the code grew more complicated, and now includes parsing of command line arguments with the clap crate. To see the latest version, check out the Genesis machine-specific binary and the MiniFB host impl and main loop

Updating Windows

I now needed to implement the WindowUpdater trait and to do this, I made a Frame object which holds a single frame in a buffer. When the update function is called, the frame buffer will be copied to the minifb buffer. Pixel data can be fed to the .blit function using an Iterator, rather than using yet another intermediate buffer for individual images drawn to the frame. The Arc<Mutex<Frame>> used in the updater is necessary for the threaded version, so that the frame can be held both by the simulation thread and by the UI thread at the same time.

// If a pixel has this value, it wont be copied to the buffer
const MASK_COLOUR: u32 = 0xFFFFFFFF;

pub trait BlitableSurface {
    fn blit<B: Iterator<Item=u32>>(&mut self, pos_x: u32, pos_y: u32, bitmap: B, width: u32, height: u32);
    fn clear(&mut self, value: u32);
}

#[derive(Clone)]
pub struct Frame {
    pub width: u32,
    pub height: u32,
    pub bitmap: Vec<u32>,
}

impl Frame {
    pub fn new(width: u32, height: u32) -> Self {
        Self { width, height, bitmap: vec![0; (width * height) as usize] }
    }
}

impl BlitableSurface for Frame {
    fn blit<B: Iterator<Item=u32>>(&mut self, pos_x: u32, pos_y: u32, mut bitmap: B, width: u32, height: u32) {
        for y in pos_y..(pos_y + height) {
            for x in pos_x..(pos_x + width) {
                match bitmap.next().unwrap() {
                    MASK_COLOUR =>
                        { },
                    value if x < self.width && y < self.height =>
                        { self.bitmap[(x + (y * self.width)) as usize] = value; },
                    _ =>
                        { },
                }
            }
        }
    }

    fn clear(&mut self, value: u32) {
        let value = if value == MASK_COLOUR { 0 } else { value };
        for i in 0..((self.width as usize) * (self.height as usize)) {
            self.bitmap[i] = value;
        }
    }
}

pub struct FrameUpdateWrapper(Arc<Mutex<Frame>>);

impl WindowUpdater for FrameUpdateWrapper {
    fn get_size(&mut self) -> (u32, u32) {
        let frame = self.0.lock().unwrap();
        (frame.width, frame.height)
    }

    fn update_frame(&mut self, width: u32, _height: u32, bitmap: &mut [u32]) {
        let frame = self.0.lock().unwrap();
        for y in 0..frame.height {
            for x in 0..frame.width {
                bitmap[(x + (y * width)) as usize] =
                    frame.bitmap[(x + (y * frame.width)) as usize];
            }
        }
    }
}

I know I'm copying the buffer twice when updating the frame, but it's a compromise in the name of flexibility. A buffer held only by the frontend is passed into WindowUpdate::update_frame(), into which the frame data is copied, and then that frontend buffer is passed to minifb's .update_with_buffer() function. The trouble is that minifb uses its .update_with_buffer() function to also limit the frame rate. The frame limiter is set to 60 updates a second, and the delay that's necessary to achieve that limit happens before the update function returns. The delay is typically between 10 to 12 ms in order to achieve a total 16.6ms delay between frames.

If the shared frame buffer is passed to the minifb update function, the lock on the frame will be held until the delay expires and the function returns. If the simulation code is run between frames, then holding the lock isn't so much a problem because it's only after the update function returns that the frame will be accessed, but if the simulation is run in a separate thread, then the lock contention makes the frame rate excruciatingly slow. Since I wanted the option to run the simulation in a separate thread, and since the extra buffer copy is negligible on a typical desktop, I've kept it, but if I ever try to run in on slower hardware, I might see about redesigning this.

There is also the issue of partial frames. Currently the VDP simulation code draws an entire frame at once instead of more accurately drawing it line by line spread out over many calls to its step function. I suspect that this causes the issue with the Sonic 2 title screen where Tails appears to be an incorrect colour. The ROM might be trying to change the colour palette while the image is being updated in order to pack more colours onto the screen at once.

The advantage of updating all at once, however, is that the frame will always be completely drawn when the frame buffer lock is obtained. I had originally written some code have two frames, and to swap them after each draw cycle is complete, so that there's always a complete frame available when the screen is updated. If the simulation is running slow, then the same completed frame will be sent more than once. If it's too fast, then some frames wont be sent to the screen at all before being redrawn. This turned out to not be necessary because of the all-at-once update, but since I will likely need to change to line-by-line updating in the future, the FrameSwapper code has been left in place in the actual Moa code.

The VDP Device

I can now add the frame buffer to the VDP device, including the call to .add_window() to register it with the frontend, and some logic to handle the horizontal and vertical interrupts.

pub struct Ym7101State {
    pub regs: [22; u8],                 // The internal registers of the VDP

    pub last_clock: Clock,
    pub h_clock: u32,                   // Used to generate the horizontal interrupt
    pub v_clock: u32,                   // Used to generate the vertical interrupt
    pub h_scanlines: u32,

    ...                                 // Additional fields used by memory/DMA code
}

pub struct Ym7101 {
    pub frame: Arc<Mutex<Frame>>,       // The output video frame, shared with the frontend
    pub state: Ym7101State,
}

impl Ym7101 {
    pub fn new<H: Host>(host: &H) -> Ym7101 {
        let frame = Frame::new(320, 224);

        host.add_window(Box::new(frame.clone()));

        Ym7101 {
            frame,
            state: Ym7101State::new(),
        }
    }
}

impl Steppable for Ym7101 {
    fn step(&mut self, system: &System) -> Result<ClockElapsed, Error> {
        // Calculate the actual time since the last step occured
        let diff = (system.clock - self.state.last_clock) as u32;
        self.state.last_clock = system.clock;

        // Reset the interrupts
        if self.state.reset_int {
            system.get_interrupt_controller().set(false, 4, 28)?;
            system.get_interrupt_controller().set(false, 6, 30)?;
        }

        self.state.h_clock += diff;
        if self.state.h_clock > 63_500 {
            self.state.h_clock -= 63_500;

            // Trigger the horizontal interrupt
            //   The H Interrupt register has the number of lines that should be
            //   drawn before the interrupt occurs
            self.state.h_scanlines = self.state.h_scanlines.wrapping_add(1);
            if self.state.hsync_int_enabled() && self.state.h_scanlines >= self.state.regs[REG_H_INTERRUPT] {
                self.state.h_scanlines = 0;
                system.get_interrupt_controller().set(true, 4, 28)?;
                self.state.reset_int = true;
            }
        }

        self.state.v_clock += diff;
        if self.state.v_clock > 16_630_000 {
            self.state.v_clock -= 16_630_000;

            // Trigger the vertical interrupt
            if self.state.vsync_int_enabled() {
                system.get_interrupt_controller().set(true, 6, 30)?;
                self.state.reset_int = true;
            }

            // Lock the frame and update it
            let mut frame = self.frame.lock().unwrap();
            self.state.draw_frame(&mut frame);
        }

        // Run the DMA transfer if configured
        self.state.step_dma(system)?;

        Ok((1_000_000_000 / 13_423_294) * 4)
    }
}

The .step() function will increment the v_clock until it has counted the number of nanoseconds between refreshes on an NTSC television, which is 16.63 milliseconds. At that point, it will trigger the vertical interrupt and update the frame all at once. There is also a horizontal interrupt which can be configured to trigger only after a certain number of lines have been drawn.

I've shown here the original way I implemented interrupts, which was only intended to be temporary. It definitely caused problems and was fixed not long after, but I'll go into more detail in Part III where I talk about the process of debugging.

Colours And Patterns

Before anything can be drawn, there needs to be some colours, and all the colours drawn by the VDP are stored in the CRAM. The CRAM can hold up to 4 different 16-colour palettes, with each palette colour specified as a 9-bit RGB colour, which is actually organized as a 12-bit colour in a 16-bit memory location. (Yikes) The extra bits are not actually implemented in the hardware VDP to save space on the chip, but for the purposes of emulating, I'll just store each colour in a 16-bit word. This means CRAM will be 128 bytes in size. The colours are actually stored in BGR order in the word, so a middle red colour would be 0x008 and a middle blue colour would be 0x800. To make the brightest white, the colour value would be 0xEEE (since the lower bit of each RGB component is always 0).

Technically this allows up to 512 different colours to be displayed, but only 64 of them can be on the screen at once because of the limited palette size. A further limit is that the 0 colour of each palette is a special mask colour which won't be drawn, so that any pixel below it will show through. This is especially useful for sprites, so that they can be drawn on top of the other graphics without squared edges. There are also special highlight and shadow modes which shift the colour output either high or low so that the 9-bit colour value is spread across only half of the colour range, which increases the total possible colours that can be displayed. That feature has some complex conditions to determine when to use the shadow or highlight mode, so I just left it unimplemented for the time being.

All graphics generated by the VDP are made up of 8x8 pixel images called cells. A cell is generated using a pattern which contains the pixel data, in combination with a palette number. Each pixel in the pattern is a 4-bit number, which selects one of 16 colours from the current colour palette. That means each pattern is 32 bytes long, and each byte in the pattern will contain two pixels of data with the upper nibble being the first pixel, and the lower nibble being the second. The first pixel in the first byte corresponds to the upper left hand corner of the pattern, and the pixels are organized from left to right, top to bottom.

All the patterns must be in VRAM to be drawn, and they start from address 0 in VRAM, with the first 32 bytes being pattern 0, the next 32 bytes being pattern 1, and so on. When a pattern is referenced, an 11-bit number is used, which is then multiplied by 32 (or shifted to the left by 5 bits) to get the address in VRAM where the patterns starts. So a pattern can be anywhere in the 64KB of VRAM, so long as it's aligned to a 32 byte boundary. The pattern reference also includes the palette number to use for drawing the pattern, and whether the pattern should be reversed in the horizontal and/or vertical direction. This allows the same pattern to be used more often, saving space in VRAM.

Since generating the pattern data takes some translation, I opted to use an iterator to return the data. Each iteration will return one of 64 pixels as a 32-bit number which can then be written directly to the frame buffer.

pub struct PatternIterator<'a> {
    state: &'a Ym7101State,     // A stored reference which is needed to access the colour values
    palette: u8,                // The palette number (0-3)
    base: usize,                // The base address in VRAM where the pattern starts
    h_rev: bool,                // Whether to reverse it horizontally
    v_rev: bool,                // Whether to reverse it vertically
    line: i8,                   // Current line (needed by reversing code)
    col: i8,                    // Current column (needed by reversing code)
    second: bool,               // Whether this is the second pixel (lower nibble) in the byte
}

impl<'a> PatternIterator<'a> {
    pub fn new(state: &'a Ym7101State, start: u32, palette: u8, h_rev: bool, v_rev: bool) -> Self {
        Self {
            state,
            palette,
            base: start as usize,
            h_rev,
            v_rev,
            line: 0,
            col: 0,
            second: false,
        }
    }
}

impl<'a> Iterator for PatternIterator<'a> {
    type Item = u32;

    fn next(&mut self) -> Option<Self::Item> {
        let line = (if !self.v_rev { self.line } else { 7 - self.line }) as usize;
        let column = (if !self.h_rev { self.col } else { 3 - self.col }) as usize;
        let offset = self.base + line * 4 + column;

        let value = if (!self.h_rev && !self.second) || (self.h_rev && self.second) {
            self.state.get_palette_colour(self.palette, self.state.vram[offset] >> 4)
        } else {
            self.state.get_palette_colour(self.palette, self.state.vram[offset] & 0x0f)
        };

        if !self.second {
            self.second = true;
        } else {
            self.second = false;
            self.col += 1;
            if self.col >= 4 {
                self.col = 0;
                self.line += 1;
            }
        }

        Some(value)
    }
}

It's a bit messy, and I'm sure I could optimize it, but it works for now. At this point I'm still focused on getting something working more than cleaning up and optimizing the code. (Note: I ended up throwing this code away, which goes to show it's not always worth getting hung up on the quality of code when in early development and things are changing rapidly. I'll talk more about the change in Part III).

Scrolls And Sprites

Now that there's a way to draw cells to the screen, how is the VDP told which ones to draw and where? There are two ways. They can either be specified in one of the two scroll tables, or they can be specified in a sprite.

There are two moveable planes called Scroll A and Scroll B, the tables for which are stored in VRAM and the starting address of each table is stored in their own VDP registers. Each table is an array of 16-bit words where each word is called a pattern name and contains the pattern number, the colour palette to render it with, two bits to reverse the pattern in the horizontal and/or vertical direction, and a priority bit used to determine the draw order of the different planes. The exact format in memory is better shown at megadrive.org and segaretro.org

Both scrolls must be the same size, but the size can be any combination of 32, 64, or 128 cells in either direction. This means they are usually bigger than the size of the screen itself, which for the NTSC version is usually 40 x 28 cells (320 x 224 pixels). Which portion of the scroll plane to draw on the screen can be controlled using the scrolling features of the VDP, which at its simplest is just two numbers per plane to specify the vertical and horizontal offset of the scroll relative to the upper left corner of the screen, but at it's most complex can have a different offset for each line of pixels which controls the horizontal position of each line. I left the scrolling functionality unimplemented until the scroll planes were working, so I'll go into more detail about it later. For the logo and title screens, there usually isn't a scroll offset, so displaying the upper left corner of the scroll at the upper left corner of the screen should still display something.

There is also a special fixed plane called the window, but not many games seem to use it and my early attempts at implementing it caused weird graphics, so I left it for later.

The other way to draw to the screen is using sprites. Like the scrolls, a table of sprite data is stored in VRAM and a special register contains the address of the start of that table. Unlike the scrolls, each entry in the sprite table is four 16-bit words instead of just one, with each entry corresponding to an independent sprite. For each sprite, there is a vertical and horizontal position (relative to the upper left corner of the screen minus 128 pixels in each direction), the size of the sprite in cells (a single sprite can be comprised of up to 4 x 4 cells), the pattern name to use for the first cell (in the same format as the scrolls), and a link number. The organization of a sprite entry is more clearly displayed here

The link number is used to determine the sprite priority. Sprite 0, which is the first entry in the table, is always the highest priority sprite. Its link number is the index in the sprite table for the next highest priority sprite, which could be anywhere in the sprite table. That sprite's link number would then point to the next highest priority sprite and so on until a sprite has a link number of 0. When multiple sprites are on top of each other, the highest priority sprite will appear on top.

This shows the breakdown of the different planes that are combined to form the final output. From the top left to the bottom right is Scroll B (the background), Scroll A (the foreground), the Sprites (the moveable graphics), and then the final image is the three planes combined.

The following code is my first attempt at implementing this. (Please note: this code contains many issues but it wasn't until after much debugging that I figured out what they all were. I'd like to describe the process of debugging this code in Part III, so I'm showing the code that I started with here. Bonus points to anyone who can figure out the bugs without reading onward).

pub fn draw_frame(&mut self, frame: &mut Frame) {
    self.draw_background(frame);
    self.draw_cell_table(frame, ((self.regs[REG_SCROLL_B_ADDR] as u16) << 13) as u32);
    self.draw_cell_table(frame, ((self.regs[REG_SCROLL_A_ADDR] as u16) << 10) as u32);
    self.draw_sprites(frame);
}

fn draw_background(&mut self, frame: &mut Frame) {
    let bg_colour = self.get_palette_colour((self.regs[REG_BACKGROUND] & 0x30) >> 4, self.regs[REG_BACKGROUND] & 0x0f);
    frame.clear(bg_colour);
}

fn draw_cell_table(&mut self, frame: &mut Frame, cell_table: u32) {
    let (scroll_h, scroll_v) = self.get_scroll_size();
    let (cells_h, cells_v) = self.get_screen_size();

    for cell_y in 0..cells_v {
        for cell_x in 0..cells_h {
            let pattern_name = read_beu16(&self.vram[(cell_table + ((cell_x + (cell_y * scroll_h)) << 1) as u32) as usize..]);
            let iter = self.get_pattern_iter(pattern_name);
            frame.blit((cell_x << 3) as u32, (cell_y << 3) as u32, iter, 8, 8);
        }
    }
}

fn build_link_list(&mut self, sprite_table: usize, links: &mut [usize]) -> usize {
    links[0] = 0;
    let mut i = 0;
    loop {
        let link = self.vram[sprite_table + (links[i] * 8) + 3];
        if link == 0 || link > 80 {
            break;
        }
        i += 1;
        links[i] = link as usize;
    }
    i
}

fn draw_sprites(&mut self, frame: &mut Frame) {
    let sprite_table = (self.regs[REG_SPRITES_ADDR] as usize) << 9;
    let (cells_h, cells_v) = self.get_screen_size();
    let (pos_limit_h, pos_limit_v) = (if cells_h == 32 { 383 } else { 447 }, if cells_v == 28 { 351 } else { 367 });

    let mut links = [0; 80];
    let lowest = self.build_link_list(sprite_table, &mut links);

    for i in (0..lowest + 1).rev() {
        let sprite_data = &self.vram[(sprite_table + (links[i] * 8))..];

        let v_pos = read_beu16(&sprite_data[0..]);
        let size = sprite_data[2];
        let pattern_name = read_beu16(&sprite_data[4..]);
        let h_pos = read_beu16(&sprite_data[6..]);

        let (size_h, size_v) = (((size >> 2) & 0x03) as u16 + 1, (size & 0x03) as u16 + 1);
        let h_rev = (pattern_name & 0x0800) != 0;
        let v_rev = (pattern_name & 0x1000) != 0;

        for ih in 0..size_h {
            for iv in 0..size_v {
                let (h, v) = (if !h_rev { ih } else { size_h - ih }, if !v_rev { iv } else { size_v - iv });
                let (x, y) = (h_pos + h * 8, v_pos + v * 8);
                if x > 128 && x < pos_limit_h && y > 128 && y < pos_limit_v {
                    let iter = self.get_pattern_iter(pattern_name + (h * size_v) + v);

                    frame.blit(x as u32 - 128, y as u32 - 128, iter, 8, 8);
                }
            }
        }
    }
}

fn get_pattern_iter<'a>(&'a self, pattern_name: u16) -> PatternIterator<'a> {
    let pattern_addr = (pattern_name & 0x07FF) << 5;
    let pattern_palette = ((pattern_name & 0x6000) >> 13) as u8;
    let h_rev = (pattern_name & 0x0800) != 0;
    let v_rev = (pattern_name & 0x1000) != 0;
    PatternIterator::new(&self, pattern_addr as u32, pattern_palette, h_rev, v_rev)
}

fn get_scroll_size(&self) -> (u16, u16) {
    let h = scroll_size(self.regs[REG_SCROLL_SIZE] & 0x03);
    let v = scroll_size((self.regs[REG_SCROLL_SIZE] >> 4) & 0x03);
    (h, v)
}

fn get_screen_size(&self) -> (u16, u16) {
    let h_cells = if (self.regs[REG_MODE_SET_4] & MODE4_BF_H_CELL_MODE) == 0 { 32 } else { 40 };
    let v_cells = if (self.regs[REG_MODE_SET_2] & MODE2_BF_V_CELL_MODE) == 0 { 28 } else { 30 };
    (h_cells, v_cells)
}

And after running this with the Sonic 1 ROM, I'm greeted by...

Well it kinda looks like the SEGA logo but why are the colours so wrong...

Next Time

After about two weeks or so of working on the Sega Genesis support for Moa, reading up on the internal workings of the console, implementing a simple swappable frontend, and implementing my first best guess of how it should work, I could display a very mangled image with bright magenta colours instead of blues. To be honest, I was a bit dejected. I was hoping to have something that at least looked coherent before I added my work in progress to git. Fiddling with it wasn't improving matters at all, so it wasn't going to be a quick fix. I was going to have roll up my sleeves and grind it out.

This is where the real journey began, tirelessly debugging until I hit a wall, taking some detours, working on other projects for a while, eventually returning to it, isolating the problems with the help of some test ROMs and another Genesis emulator as a reference, and finally getting it working. Stay tuned for the (not so) thrilling conclusion in Part III of Emulating The Sega Genesis.

Emulating the Sega Genesis - Part I

transistor fet — Mon, 10 Jan 2022 00:01:00 +0000

Originally published at jabberwocky.ca

Written December 2021/January 2022 by transistor_fet

If you haven't already, you might want to read Making a 68000 Emulator in Rust where I talk about the basic structure and function of the emulator, as well as details about the 68000. I wont go into too much detail about that here and instead focus on the Genesis-specific hardware, and the challenges of debugging the emulator itself.

This is Part I in the series, which covers setting up the emulator, getting some game ROMs to run, and implementing the DMA and memory features of the VDP. Part II will cover adding a graphical frontend to Moa, and then implementing a first attempt at generating video output. Part III will be about debugging the various problems in the VDP and CPU implementations to get a working emulator capable of playing games.

The Start
Sega Genesis/Mega Drive
The Games
Diving In
Dummy Devices
Memory and DMA
Talking To The VDP
Implementing The Memory Ops
Next Time

The Start

Before starting Moa, I had never tried to make an emulator, but I have worked on projects with some similarities such as interpreters, artificial life simulators, and some simple games. I had been looking for a fun distracting project, so I was approaching this as a fun challenge. Especially with the Genesis support, I wanted to get something up and running fast, just to see if it would work at all, so rather than taking my more usual measured approach, I was working fast and loose to get a proof of concept running. I could always go back and fix things later, right?

I was primarily hoping to simulate the video chip in the Sega Genesis, enough to see the intended graphics output and play the games. Not only would it be a nice accomplishment to get some visual feedback, but I would have to work out a way of creating a separate frontend that could display graphics to a host window, which I could use for other systems as well. I was less concerned with audio, since that would require getting the Z80 working, which wasn't even on my horizon at the time. I was hoping that I could get away with just the 68k for now (which is certainly possible for some but not all games).

Sega Genesis/Mega Drive

(From Wikipedia by Evan-Amos, used under the Creative Commons license.)

The Sega Genesis (also known as the Mega Drive outside of North America) was released in 1988/1989 as a successor to the popular Sega Master System. It's main processor is a 68000 clocked at just under 8 MHz, which compared to computers of the time was pretty outdated, but it's slower speed is compensated by the custom video display processor (VDP), as well as a Z80 coprocessor, both of which can offload work from the 68000. While the 68000 can address up to 16 MB, it only has 64KB of main RAM, located at address 0xFF0000. The VDP (also known by the part number of the chip, YM7101) has it's own separate 64KB of RAM which is only accessible through the VDP, either by writing data to the VDP's ports, or configuring a DMA (direct memory access) transfer from main memory to video memory, which is performed by the VDP. Game cartridges are mapped to address 0 of the 68000's address space, and can be up to 4MB. It also has two sound generation chips, the SN76489 and YM2612, but I don't have audio working yet so I wont talk much about these.

The Genesis was one of the first video game consoles to have some backwards compatibility with it's predecessor, although a special pin-converter was needed in order to plug Master System cartridges into the Genesis. In order to accomplish this, the Genesis has a Z80 processor (in addition to the main 68000 processor), which can run on it's own with it's own bus and memory. It only has 2 KB of RAM instead of the 24 KB of the Master System, but the 68000's address space can be mapped into a banked area that the Z80 can access. While some games work fine without the Z80 present, others will wait for certain data to be written by the Z80 before proceeding, which results in the game hanging.

The VDP or Video Display Processor is the central peripheral device in the console. It generates the video output signal, controls the video memory, handles DMA (Direct Memory Access) to transfer data to the video memory, as well as handling all the interrupts in the system (there are 3, one each for the horizontal and vertical blanking, and one for the game controllers). It has it's own 64KB of video memory (VRAM) which holds all the graphics and data tables that describe which graphics should be displayed and where on the screen. Internal to the VDP there is also the colour ram (CRAM), and vertical scroll ram (VSRAM), which have their own separate address spaces, and hold the colour palettes and vertical cell offset numbers respectively. In addition, there are 22 internal 8-bit registers which configure how the VDP behaves, which can only be accessed indirectly through the memory-mapped interface to the VDP. They control the graphics mode to use, the size of the scrollable planes, the locations in VRAM of the scroll and sprite tables, the length and source address to use for DMA transfers, and a few other things.

The Games

I'll mostly refer to "Sonic The Hedgehog 2" in examples because in the end, it's the game that worked the best, even though I actually started with Sonic 1. During development, I also tried Earthworm Jim, Ren and Stimpy's Invention, and a few others that didn't work as well. It wasn't until I took a break and came back to it that I found ComradeOj's demos and test ROMs, which where much easier to test with.

In order to better trace the ROM's execution, the .bin ROM images can be disassembled using m68k-gcc's objdump command:

m68k-linux-gnu-objdump -b binary -m m68k:68000 -D binaries/genesis/Sonic2.bin > Sonic2.asm

One of the nice things about working with the 68000 is that it's still a supported architecture in the latest version of gcc, so all the latest gcc tools can be used to compile and inspect binaries. It's uncertain how much longer that will be the case, but that said, support was recently added to LLVM and experimental support is available in Rust, so who knows. Maybe there's still a long life ahead for the 68000 architecture.

Diving In

The first thing to sort out was the format of Sega Genesis game ROMs. Some ROMs use a flat binary format which can be directly loaded at address 0 without any changes or special parsing. Other ROMs use a format with the file extension .smd which interleaves the even- and odd-addressed bytes of the ROM in 16 KB chunks, but there are utilities available that convert from .smd to .bin format. Since I was hoping to focus my attention on simulating the VDP, I chose to just use the binary format for ROMs since the emulator can already load flat binaries, and I can use the available conversion utilities to convert any .smd ROMs I had into .bin ROMs.

That was easier than I was expecting. All I had to do was load the ROM file into a MemoryBlock object in the emulator, and map that object to address 0. I also needed 64 KB of RAM mapped to addresses 0xFF0000 through 0xFFFFFF, which also uses a MemoryBlock. My Moa machine definition looked something like this:

let mut system = System::new();

let rom = MemoryBlock::load("binaries/genesis/Sonic2.bin").unwrap();
system.add_addressable_device(0x00000000, wrap_transmutable(rom)).unwrap();

let ram = MemoryBlock::new(vec![0; 0x00010000]);
system.add_addressable_device(0x00FF0000, wrap_transmutable(ram)).unwrap();

let mut cpu = M68k::new(M68kType::MC68000, 7_670_454);
cpu.enable_tracing();
system.add_device("cpu", wrap_transmutable(cpu)).unwrap();

Ok(system)

Running this gave the results:

0x00000206: 4ab9 00a1 0008 
        tstl    (#00a10008)

Status: Running
PC: 0x0000020c
SR: 0x2700
D0: 0x00000000        A0:  0x00000000
D1: 0x00000000        A1:  0x00000000
D2: 0x00000000        A2:  0x00000000
D3: 0x00000000        A3:  0x00000000
D4: 0x00000000        A4:  0x00000000
D5: 0x00000000        A5:  0x00000000
D6: 0x00000000        A6:  0x00000000
D7: 0x00000000
SSP: 0xfffffe00
USP: 0x00000000
Current Instruction: 0x00000206 TST(IndirectMemory(10551304), Long)

0x00fffe00: 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 
0x00fffe10: 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 
0x00fffe20: 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 
0x00fffe30: 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 

Error { err: Emulator, native: 0, msg: "No segment found at 0xa10008" }
thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value: Error { err: Emulator, native: 0, msg: "No segment found at 0xa10008" }', frontends/moa-minifb/src/lib.rs:70:40

Wow, It worked! (sort of). The first line of the output shows the address of the instruction being executed (0x206), followed by the instruction data that was decoded. Below that is the decoded instruction in assembly notation. When an error occurs, Moa will dump the values of the CPU registers along with a dump of the stack area, which in this case is located at address 0xfffe00. The tstl (#0xa10008) instruction that's being executed is supposed to compare the value stored at the address 0xa10008 to zero, and set the flags in the %sr register accordingly. The error that occurs means there was an attempt to access address 0xa10008, which isn't mapped to a valid area on the data bus, and Moa is currently configured to cause a fatal error in that case.

According to the memory map for the Genesis, the address 0xa10008 is the control port for Controller 1, which makes sense. It's doing something that would be expected of a Genesis ROM, even if it only gets one instruction in before dying.

Taking a look at the first 16 bytes of the ROM shows:

00000000:  FF FF FE 00 00 00 02 06 00 00 02 00 00 00 02 00

The first 4 bytes are the stack pointer (0xfffffe00) and the next 4 bytes are the reset address, which is the same address as the starting instruction, 0x206. (If your curious, the two addresses that follow the reset address are for the bus error and address error handlers respectively, which point to the same handler at 0x200).

You may have noticed that the stack pointer value (0xfffffe00) is a full 32-bit address, but the 68000 only supports 24-bit addresses. In hardware, the extra 8-bits at the top (ie. 0xff) would be ignored. I had to modify the emulator to allow an address mask to be configured, so that all 32-bit addresses coming from the 68000 are masked to only 24-bits. I eventually made a more complete and configurable solution that's described later.

To get around the no segment found error, I added another memory block for 0xa10000 in order to prevent the error, and now a handful of instructions are running correctly until the next "No segment found" error occurs.

0x00000206: 4ab9 00a1 0008 
        tstl    (#00a10008)

0x0000020c: 6606 
        bne     6

0x0000020e: 4a79 00a1 000c 
        tstw    (#00a1000c)

0x00000214: 667c 
        bne     124

0x00000216: 4bfa 007c 
        lea     (%pc + #007c), %a5

0x0000021a: 4c9d 00e0 
        movemw  (%a5)+, %d5-%d7

0x0000021e: 4cdd 1f00 
        moveml  (%a5)+, %a0-%a4

0x00000222: 1029 ef01 
        moveb   (%a1 + #ffffef01), %d0

0x00000226: 0200 000f 
        andb    #0000000f, %d0

0x0000022a: 6708 
        beq     8

0x00000234: 3014 
        movew   (%a4), %d0

Status: Running
PC: 0x00000236
SR: 0x2704
D0: 0x00000000        A0:  0x00a00000
D1: 0x00000000        A1:  0x00a11100
D2: 0x00000000        A2:  0x00a11200
D3: 0x00000000        A3:  0x00c00000
D4: 0x00000000        A4:  0x00c00004
D5: 0xffff8000        A5:  0x000002ae
D6: 0x00003fff        A6:  0x00000000
D7: 0x00000100
SSP: 0xfffffe00
USP: 0x00000000
Current Instruction: 0x00000234 MOVE(IndirectAReg(4), DirectDReg(0), Word)

0xfffffe00: 

Error { err: Emulator, native: 0, msg: "No segment found at 0xc00004" }

Another missing I/O device. The 0xc00004 address is the control port of the VDP, so again that makes sense. Adding another MemoryBlock for that address range prevents the emulator from hitting another error, but it instead gets stuck in a loop.

0x0000024c: 3287 
        movew   %d7, (%a1)

0x0000024e: 3487 
        movew   %d7, (%a2)

0x00000250: 0111 
        btstb   %d0, (%a1)

0x00000252: 66fc 
        bne     -4

0x00000250: 0111 
        btstb   %d0, (%a1)

0x00000252: 66fc 
        bne     -4

0x00000250: 0111 
        btstb   %d0, (%a1)

0x00000252: 66fc 
        bne     -4
...

The register %a1 has the value 0xa11100, %d0 has 0x00, and %d7 has 0x0100. The code first writes the value 0x0100 to address 0xa11100, and then tests if the bit that was just set at that memory location is 1. It then loops back to the bit test instruction until it becomes 0, which never happens because that address is just a memory location at the moment, and not an I/O device. That address, according to the map, is the Z80 bus request location for enabling or disabling the bus request pin on the Z80.

At this point I'll need to start properly implementing the devices at these address locations in order to get further in the execution of a program. It's only executed a hundred or so instructions to get to this infinite loop, which isn't very much, but this is very promising.

Dummy Devices

In order to get the game ROMs to run further, I needed some basic devices that can respond to the addresses of the various peripherals. It was just a matter of looking through the memory map and filling in the gaps. The Sega CD and 32X devices could be ignored, since I was only working on basic Genesis support for now, but the rest will need to respond in some way, so they will need to be assigned to Moa devices.

To start with, there is a 64KB chunk of addresses at 0xa00000 for accessing the Z80's address space, which can be filled with a MemoryBlock for now.

Then there's a chunk of 0x20 addresses starting at 0xa10000, which are mostly related to the controllers. An exception to that is the special version register at the start of that range. It's supposed to always return a constant value to indicate which hardware version of the console the ROM is running on. I can just add that location to the same device as the controllers to make it easy. I'll need a Transmutable object to represent all the controllers.

pub struct GenesisControllerPort {
    pub data: u16,
    pub ctrl: u8,
    pub th_count: u8,
    pub next_read: u8,
}

pub struct GenesisControllers {
    pub port_1: GenesisControllerPort,
    pub port_2: GenesisControllerPort,
    pub expansion: GenesisControllerPort,
}

impl Addressable for GenesisControllers {
    fn len(&self) -> usize {
        0x20
    }

    fn read(&mut self, mut addr: Address, data: &mut [u8]) -> Result<(), Error> {
        // If the address is even, only the second byte (odd byte) will be meaningful
        let mut i = 0;
        if (addr % 2) == 0 {
            addr += 1;
            i += 1;
        }

        match addr {
            REG_VERSION => { data[i] = 0xA0; } // Overseas Version, NTSC, No Expansion
            REG_DATA1 => { data[i] = self.port_1.next_read; },
            REG_DATA2 => { data[i] = self.port_2.next_read; },
            REG_DATA3 => { data[i] = self.expansion.next_read; },
            REG_CTRL1 => { data[i] = self.port_1.ctrl; },
            REG_CTRL2 => { data[i] = self.port_2.ctrl; },
            REG_CTRL3 => { data[i] = self.expansion.ctrl; },
            _ => { warning!("{}: !!! unhandled reading from {:0x}", DEV_NAME, addr); },
        }
        info!("{}: read from register {:x} the value {:x}", DEV_NAME, addr, data[0]);
        Ok(())
    }

    fn write(&mut self, addr: Address, data: &[u8]) -> Result<(), Error> {
        info!("{}: write to register {:x} with {:x}", DEV_NAME, addr, data[0]);
        match addr {
            REG_DATA1 => { self.port_1.set_data(data[0]); }
            REG_DATA2 => { self.port_2.set_data(data[0]); },
            REG_DATA3 => { self.expansion.set_data(data[0]); },
            REG_CTRL1 => { self.port_1.ctrl = data[0]; },
            REG_CTRL2 => { self.port_2.ctrl = data[0]; },
            REG_CTRL3 => { self.expansion.ctrl = data[0]; },
            _ => { warning!("{}: !!! unhandled write of {:0x} to {:0x}", DEV_NAME, data[0], addr); },
        }
        Ok(())
    }
}

The next set of addresses are a bit clumsy unfortunately. The addresses 0xa11000, 0xa11100, and 0xa11200 are special registers used for controlling the Z80, and all other addresses in that range are "prohibited" (not that that stops ROMs from accessing those areas, as I've found out, in frustration). 0xa11000 is used to configure DRAM mode for ROM development on the hardware, which isn't needed here. The other two locations control the Z80's reset and bus request lines respectively. The bus request signal will tell the Z80 to stop running and disconnect itself from the memory bus, so that the 68000 can access the Z80's RAM directly. Without this, the read and writes could conflict with each other resulting in both CPUs reading or writing garbage. This wont reset the Z80, which will continue running where it left off, when the bus request signal is de-asserted. The reset signal allows the Z80 to be reset so that it starts in a known state. Again, I'll need a custom Transmutable device to handle these locations, and the unmapped areas will just return nothing.

pub struct CoprocessorControl {
    pub bus_request: bool,
    pub reset: bool,
}

impl Addressable for CoprocessorControl {
    fn len(&self) -> usize {
        0x4000
    }

    fn read(&mut self, addr: Address, data: &mut [u8]) -> Result<(), Error> {
        match addr {
            0x100 => {
                data[0] = if self.bus_request && self.reset { 0x01 } else { 0x00 };
            },
            _ => { warning!("{}: !!! unhandled read from {:0x}", DEV_NAME, addr); },
        }
        info!("{}: read from register {:x} of {:?}", DEV_NAME, addr, data);
        Ok(())
    }

    fn write(&mut self, addr: Address, data: &[u8]) -> Result<(), Error> {
        info!("{}: write to register {:x} with {:x}", DEV_NAME, addr, data[0]);
        match addr {
            0x000 => { /* ROM vs DRAM mode (not implemented) */ },
            0x100 => {
                self.bus_request = data[0] != 0;
            },
            0x200 => {
                self.reset = data[0] == 0;
            },
            _ => { warning!("{}: !!! unhandled write {:0x} to {:0x}", DEV_NAME, data[0], addr); },
        }
        Ok(())
    }
}

The last area of the address space to implement is 0xc00000 to 0xc00020, which is mapped to the VDP. While there's a lot of internal state to the VDP, it has quite a small interface to the rest of the system. Most features of the VDP will be performed during the .step() function, where the device has access to the System object. Copying data from main memory requires access to the System's Bus object, so DMA will be implemented in the .step().

pub struct Ym7101State {
    pub ctrl_port_buffer: Option<u16>,  // Used to store the first word of a transfer request
    pub regs: [22; u8],                 // The internal registers of the VDP
}

pub struct Ym7101 {
    pub state: Ym7101State,
}

impl Ym7101 {
    pub fn new() -> Ym7101 {
        Ym7101 {
            state: Ym7101State::new(),
        }
    }
}

impl Steppable for Ym7101 {
    fn step(&mut self, system: &System) -> Result<ClockElapsed, Error> {

        Ok((1_000_000_000 / 13_423_294) * 4)
    }
}

impl Addressable for Ym7101 {
    fn len(&self) -> usize {
        0x20
    }

    fn read(&mut self, addr: Address, data: &mut [u8]) -> Result<(), Error> {
        match addr {
            // Read from Data Port
            0x00 | 0x02 => {

            },

            // Read from Control Port
            0x04 | 0x06 => {

            },

            _ => { println!("{}: !!! unhandled read from {:x}", DEV_NAME, addr); },
        }
        Ok(())
    }

    fn write(&mut self, addr: Address, data: &[u8]) -> Result<(), Error> {
        match addr {
            // Write to Data Port
            0x00 | 0x02 => {

            },

            // Write to Control Port
            0x04 | 0x06 => {

            },

            _ => { warning!("{}: !!! unhandled write to {:x} with {:?}", DEV_NAME, addr, data); },
        }
        Ok(())
    }
}

Early in development I called this device Ym7101 after the part number, and it's stuck since then, so just know that Ym7101 is the VDP device. I'm using a separate Ym7101State object here for the actual internal data of the VDP because it'll get pretty complicated pretty quickly. I've since broken it into 3 objects, one for the DMA and memory management, one for updating the display, and one to tie it all together and handle the nitty gritty interfacing details, but at this point in the project, it was just two Rust objects.

The system definition now looks like this:

let mut system = System::new();

let rom = MemoryBlock::load("binaries/genesis/Sonic2.bin").unwrap();
system.add_addressable_device(0x00000000, wrap_transmutable(rom)).unwrap();

let ram = MemoryBlock::new(vec![0; 0x00010000]);
system.add_addressable_device(0x00ff0000, wrap_transmutable(ram)).unwrap();

let coproc_mem = MemoryBlock::new(vec![0; 0x00010000]);
system.add_addressable_device(0x00a00000, wrap_transmutable(coproc_mem)).unwrap();

let controllers = genesis::controllers::GenesisControllers::new();
system.add_addressable_device(0x00a10000, wrap_transmutable(controllers)).unwrap();

let coproc = genesis::coproc_memory::CoprocessorControl::new();
system.add_addressable_device(0x00a11000, wrap_transmutable(coproc)).unwrap();

let vdp = genesis::ym7101::Ym7101::new();
system.add_addressable_device(0x00c00000, wrap_transmutable(vdp)).unwrap();

let mut cpu = M68k::new(M68kType::MC68000, 7_670_454);
system.add_device("cpu", wrap_transmutable(cpu)).unwrap();

Ok(system)

The ROM still gets stuck in a loop after a certain point, probably because the VDP's interrupts are not yet implemented, but it gets much farther than before now that the CoprocessorControl object is responding as the ROM expects.

After putting some print statements into the VDP read and write functions to get a sense of what's going on, I get the following log messages:

genesis_controller: read from register 9 the value 0
genesis_controller: read from register b the value 0
genesis_controller: read from register d the value 0
genesis_controller: read from register 1 the value a0
ym7101: control port read 2 bytes from 4 with [0, 0]
ym7101: control port write 2 bytes to 4 with [128, 4]
ym7101: control port write 2 bytes to 4 with [129, 20]
ym7101: control port write 2 bytes to 4 with [130, 48]
ym7101: control port write 2 bytes to 4 with [131, 60]
ym7101: control port write 2 bytes to 4 with [132, 7]
ym7101: control port write 2 bytes to 4 with [133, 108]
ym7101: control port write 2 bytes to 4 with [134, 0]
ym7101: control port write 2 bytes to 4 with [135, 0]
ym7101: control port write 2 bytes to 4 with [136, 0]
ym7101: control port write 2 bytes to 4 with [137, 0]
ym7101: control port write 2 bytes to 4 with [138, 255]
ym7101: control port write 2 bytes to 4 with [139, 0]
ym7101: control port write 2 bytes to 4 with [140, 129]
ym7101: control port write 2 bytes to 4 with [141, 55]
ym7101: control port write 2 bytes to 4 with [142, 0]
ym7101: control port write 2 bytes to 4 with [143, 1]
ym7101: control port write 2 bytes to 4 with [144, 1]
ym7101: control port write 2 bytes to 4 with [145, 0]
ym7101: control port write 2 bytes to 4 with [146, 0]
ym7101: control port write 2 bytes to 4 with [147, 255]
ym7101: control port write 2 bytes to 4 with [148, 255]
ym7101: control port write 2 bytes to 4 with [149, 0]
ym7101: control port write 2 bytes to 4 with [150, 0]
ym7101: control port write 2 bytes to 4 with [151, 128]
ym7101: control port write 2 bytes to 4 with [64, 0]
ym7101: control port write 2 bytes to 6 with [0, 128]
ym7101: data port write 2 bytes to 0 with [0, 0]
coprocessor: write to register 100 with 1
coprocessor: write to register 200 with 1
coprocessor: read from register 100 of [0]
coprocessor: write to register 200 with 0
coprocessor: write to register 100 with 0
coprocessor: write to register 200 with 1
ym7101: write 2 bytes to port 4 with data [129, 4]
ym7101: write 2 bytes to port 6 with data [143, 2]
ym7101: write 2 bytes to port 4 with data [192, 0]
ym7101: write 2 bytes to port 6 with data [0, 0]
ym7101: write 2 bytes to port 0 with data [0, 0]
...

There's more output than this but it eventually stops after a few seconds of running. The controllers are accessed first, followed by a bunch of activity trying to talk to the VDP. The coprocessor is reset, and then the VDP is accessed again and data is directly written to it. It continues for another 200 or so lines after what's shown here. It's mainly the VDP that needs to do something at this point, in order to get further in the ROM's execution.

Memory and DMA

It's time to get into the details of the VDP, and the natural first place to start is with getting data into the VDP's various memory areas. It uses its own memory exclusively to generate the display output, so data needs to be loaded before anything can be displayed. As I already mentioned above, there are three different memory areas that are directly accessible only by the VDP: VRAM, CRAM, and VSRAM. CRAM and VSRAM are very small, but VRAM is much larger (64KB, the same size as main memory), and is used for most of the VDP's functions.

In addition, the CPU and VDP can both directly access main memory, as long as the other is not accessing it at the same time. In hardware, this is handled through bus arbitration. The VDP can assert the bus request signal, which when active will cause the CPU to temporarily suspend what it's doing, disconnect from the memory bus, and assert an acknowledge signal to tell the VDP it can use the bus. The VDP is then free to access main memory until it de-asserts the bus request signal.

The green arrows show that the CPU can make a memory request to the VDP or to main RAM, and the VDP can also make a memory request to main RAM, but only the VDP interface logic can access CRAM, VSRAM, or VRAM.

The only reason the VDP needs to access main memory is to perform a direct memory access (DMA) operation, which will copy some contents of main memory into a VDP memory area without using the CPU. This direct copying is much faster than if the CPU were to alternate between reading data from RAM and writing it to the VDP's memory-mapped I/O ports. It is however possible to also write data through the CPU, which is used when only a little bit of data needs to be sent. There is more overhead required in order to set up a DMA transfer than a CPU transfer, and that might not always be worth the extra cycles, just to transfer a few words.

Talking To The VDP

To access the VDP from the 68000, the address range from 0xc00000 to 0xc00020 is used to read and write to different VDP "ports" (distinct from the VDP "registers"). Each port is 16-bits wide and most are mapped to multiple adjacent addresses. The data port for example, at address 0xc00000 is also mirrored at 0xc00002 so writing a word to either location has the same effect.

Only two ports are really important for most VDP functions: the data port and the control port. The control port is used to both set the internal register values of the VDP, as well as to set up memory operations. The data port only used to send data to a VDP memory area from the CPU, rather than through a DMA transfer.

To set a register, the upper most two bits of the 16-bit word written to the control port must be 0b10. The rest of the upper byte will have the register number (0x00 to 0x17) and the lower byte will have the new value to load into the register. The other control words written to the control port (as part of a transfer setup) are guaranteed to never contain 0b10 as the upper two bits, so these bits can be used to distinguish between the two types of requests.

To set up a memory operation, two words must be written to the control port. The first word contains almost the entire 16-bit destination address for the operation, minus the two most significant bits. The upper two most bits are actually part of the operation mode number, and exchanging them with the lower two bits of the second word will give the full destination address in the first word. The control bits in the second word need to be shifted down two bits, and ORed with the two bits from the first word to get a 6-bit operation mode which determines the transfer type. The operation mode specifies if DMA should be used or not, whether to read or write data, and which of the three memory areas to target. A DMA request requires more info than provided, which must be written to the appropriate registers before the transfer request is sent to the control port.

So in the write() method of the Addressable trait from the previous section, I need something like this:

debug!("{}: write {} bytes to port {:x} with data {:?}", DEV_NAME, data.len(), addr, data);

let value = read_beu16(data);
if (value & 0xC000) == 0x8000 {
    self.regs[((data & 0x1F00) >> 8) as usize] = (data & 0x00FF) as u8;
} else {
    match self.state.ctrl_port_buffer {
        None => {
            self.state.ctrl_port_buffer = Some(value)
        },
        Some(first) => {
            let second = value;
            self.state.ctrl_port_buffer = None;

            self.transfer_type = ((((first & 0xC000) >> 14) | ((second & 0x00F0) >> 2))) as u8;
            self.transfer_addr = ((first & 0x3FFF) | ((second & 0x0003) << 14)) as u32;
            debug!("{}: transfer requested of type {:x} to address {:x}", DEV_NAME, self.transfer_type, self.transfer_addr);
        },
    }
}

Hmmm... when I run it I get the following log message, but not the log message that a transfer was requested.

ym7101: write 4 bytes to port 4 with data [0x40, 0x00, 0x00, 0x80]

The CPU is writing 4 bytes at once. Oh right! Of course it is. The CPU implementation is using the helper functions to read and write 4 bytes at once when an instruction accesses a long word. The ROM is using a single movel instruction to write both words of the transfer setup rather than using two instructions. This is also why the VDP's data and control ports are mirrored at the adjacent addresses, because in hardware, the CPU would write a word to the first address, and then write a second word to that address plus two.

Digging around in the logs shows that the same thing is actually being done with register assignments as well. Two register assignments can be put into a single instruction like movel #0x80048114, (%a4), where %a4 contains the address of the control port 0xC00004. That would set both VDP register 0 to 0x04, and VDP register 1 to 0x14.

For now, I'll just modify the .write() function to allow long word accesses:

let value = read_beu16(data);
if (value & 0xC000) == 0x8000 {
    self.state.set_register(value);
    if data.len() == 4 {
        let value = read_beu16(&data[2..]);
        if (value & 0xC000) != 0x8000 {
            return Err(Error::new(&format!("{}: unexpected second byte {:x}", DEV_NAME, value)));
        }
        self.state.set_register(value);
    }
} else {
    match (data.len(), self.state.ctrl_port_buffer) {
        (2, None) => { self.state.ctrl_port_buffer = Some(value) },
        (2, Some(upper)) => self.state.setup_transfer(upper, read_beu16(data)),
        (4, None) => self.state.setup_transfer(value, read_beu16(&data[2..])),
        _ => { error!("{}: !!! error when writing to control port with {} bytes of {:?}", DEV_NAME, data.len(), data); },
    }
}

It's a bit clumsy but it works for testing. I eventually added a mechanism called BusPort which simulates the CPU's connection to the Bus object in System. The BusPort is created when the CPU object is created, and it's stored in the CPU object. The CPU will then use it for all read and write operations to more accurately simulate the bus. Any read or write call on BusPort will be broken into multiple operations if necessary in order to fit the given data bus size, and the address will be masked to the given address bus size. This will also fix the issue with 24-bit addressing on the 68000. At the same time, it's possible to configure a CPU as a 68030 with a 32-bit address and data bus, which I intend to use for future Computie hardware revisions, and possibly other systems.

Implementing The Memory Ops

Now that the Addressable implementation can receive the control port transfer setup, it's time to actually implement the transfer operations, both through the data port and through DMA. For a manual transfer, once configured, data can either be read from or written to the data port. After each memory operation, the destination address will be increment by the value stored in the auto increment register of the VDP (register 0x0f). It doesn't matter what size the operation was; the address will always be incremented by that value, so it must be set correctly.

A DMA transfer, on the other hand, takes place as soon as the second transfer configuration word is written to the control port, assuming the DMA enable bit is set in the Mode2 register (0x01). In hardware, the VDP would assert the bus request signal to tell the CPU to disconnect from the memory bus while the VDP directly accesses the main RAM to copy data into its VRAM. Once the operation is complete, the VDP would de-assert the bus request signal and the CPU would continue where it left off. I cheated a bit by simply performing the complete operation in one call to the .step() function, rather than simulating the time it would take. It's worked fine so far.

In order to perform a DMA transfer, there are two additional values that are needed. The source address in RAM where the data to copy is located, and the amount of data to be copied. These values are stored across 5 different 8-bit registers in the VDP, which must be set before configuring the transfer through the control port. The count value is split across registers 0x13 and 0x14, each containing half of the 16-bit count. The source address is split across registers 0x15 to 0x17 where the address is shifted to the right one bit, since the address must start on an even byte address (ie. bit 0 must always be zero, so it's not even stored in the register). The upper two bits of register 0x17, which is the high part of the address, specifies whether the operation is a transfer, copy, or fill. See VDP Registers for details.

To make the code easier to understand, I made a simple enum called DmaType to hold the type of operation, or DmaType::None if there is no operation pending. The addresses and counts are assembled from the register values when the transfer is set up through the control port.

The following code was then added to the VDP's .step() function. The transfer operation type is selected by the self.transfer_run value. Each type has its own loop which iterates until the remaining count is 0. The destination address is incremented by the value of the auto increment register (0x0f) after each iteration, just like a manual transfer. The DmaType::Memory operation is a bit more involved since it must use the system bus to read data. In order to reuse the same loop for each of the three target memory areas, the .get_transfer_target_mut() function returns a slice of the appropriate memory area.

match self.transfer_run {
    DmaType::None => { /* Do Nothing */ },

    DmaType::Memory => {
        info!("{}: starting dma transfer {:x} from Mem:{:x} to {:?}:{:x} ({} bytes)", DEV_NAME, self.transfer_type, self.transfer_src_addr, self.transfer_target, self.transfer_dest_addr, self.transfer_remain);
        let mut bus = system.get_bus();

        while self.transfer_remain > 0 {
            let mut data = [0; 2];
            bus.read(self.transfer_src_addr as Address, &mut data)?;

            let addr = self.transfer_dest_addr as usize;
            let target = self.get_transfer_target_mut();
            target[addr % target.len()] = data[0];
            target[(addr + 1) % target.len()] = data[1];

            self.transfer_dest_addr += self.transfer_auto_inc;
            self.transfer_src_addr += 2;
            self.transfer_remain -= 2;
        }
    },

    DmaType::Copy => {
        info!("{}: starting dma copy from VRAM:{:x} to VRAM:{:x} ({} bytes)", DEV_NAME, self.transfer_src_addr, self.transfer_dest_addr, self.transfer_remain);
        while self.transfer_remain > 0 {
            self.vram[self.transfer_dest_addr as usize] = self.vram[self.transfer_src_addr as usize];
            self.transfer_dest_addr += self.transfer_auto_inc;
            self.transfer_src_addr += 1;
            self.transfer_remain -= 1;
        }
    },

    DmaType::Fill => {
        info!("{}: starting dma fill to VRAM:{:x} ({} bytes) with {:x}", DEV_NAME, self.transfer_dest_addr, self.transfer_remain, self.transfer_fill_word);
        while self.transfer_remain > 0 {
            self.vram[self.transfer_dest_addr as usize] = self.transfer_fill_word as u8;
            self.transfer_dest_addr += self.transfer_auto_inc;
            self.transfer_remain -= 1;
        }
    },
}

// Reset the mode after a transfer has completed
self.set_dma_mode(DmaType::None);

Note: this code includes a bug that I'll fix in Part III. Bonus points if you can spot it

The helper function .set_dma_mode() is used to also control the DMA busy flag in the VDP's status word, which is returned when reading from VDP's control port (instead of writing). It's probably not that important since the CPU technically shouldn't be running when a DMA is in progress, but I threw it in for completeness.

pub fn set_dma_mode(&mut self, mode: DmaType) {
    match mode {
        DmaType::None => {
            self.status &= !STATUS_DMA_BUSY;
            self.transfer_run = DmaType::None;
        },
        _ => {
            self.status |= STATUS_DMA_BUSY;
            self.transfer_run = mode;
        },
    }
}

Phew! That was a lot of boring bits, but it's done now. Testing is another matter, but without a reference to compare it to, it's hard to find problems without the display output. It will get more interesting soon.

Next Time

By this point I had only been working on the Genesis support for about a week, while also working on other parts of the emulator. The time spent on the Genesis was mostly reading up on how it worked. I was flying through everything, making great progress, and having a lot of fun at the same time.

The CPU to VDP interface was pretty much implemented and I could get data into the VDP registers and memory areas. The next step was to use that data to generate an image and send it to some kind of window on the local machine. That's an entire post's worth of effort, so... I'll make another post! Click Part II to continue

Making a 68000 Emulator in Rust

transistor fet — Thu, 09 Dec 2021 23:54:03 +0000

Originally published at jabberwocky.ca

Written November 2021 by transistor_fet

A few months ago, I was looking for a project to do while recovering from a bout of illness. I needed something that was straight-forward enough to work on without getting stuck on tough decisions or the need to learn a lot before diving in, which was the case with all the other projects on my plate at the time. My girlfriend suggested writing an emulator, and my first thought was to try emulating the computer I made last year, Computie, since I already had a fair amount of code for it that I knew well, and the 68000 architecture and assembly language was still fresh in my mind. Naturally I chose to write it in Rust.

I've worked on different projects that have some vague similarities to emulators, such as programming language interpreters and artificial life simulations but I haven't actually tried to make an emulator before. I'm not aiming to make a fast emulator, and since this is meant to be fun, I'm not as concerned about accuracy (specifically instruction execution time accuracy). I would, however, like something that's flexible enough to experiment with different hardware designs. Perhaps I could use this with some of my future hardware designs to test out hardware configurations and to develop and test the software that runs on them. It would also be nice to emulate some vintage computers that use the 68000, which each have their own I/O devices that would need simulating. With that in mind, we should work towards making independent components for each device, which interact in regular ways and can be combined in different configurations without the need to modify the components themselves (ie. no tight coupling of components)

I chose Rust because it's currently my favorite systems language. I've used C and C++ quite a bit as well, but Rust's advanced type system is much more pleasant to work with, and the compile-time checks means I can focus less on simple bugs and more on the problem at hand, getting more done in the same amount of time. I'm assuming here some familiarity with Rust, as well as the basic principles of how a computer works, but not necessarily that much about the 68000 or emulators. We will start with some code to simulate the computer memory, creating an abstract way of accessing data. We'll then implement the NOP (no operation) instruction, the simplest possible instruction, for the 68000, and expand the implementation from there. Once we've created a way of handling the passage of time for the CPUs and I/O devices, we'll implement a simple serial port controller which will act as our primary I/O device. From there we'll make all of our simulated devices, represented as struct objects in Rust, look the same so that we can treat them the same, regardless of what they represent internally. We'll then be able to package them up into single working system and set them in motion to run the Computie software from binaries images.

The Computer
The 68000
The 68681 Serial Port Controller
The Memory
Simulating The CPU
Adding Instructions
Abstracting Time
Some I/O
Box It Up
An Addressable of Addressables (The Data Bus)
A Happy Little System
Tying It All Together
Now What

The Computer

Computie is a single board computer with a Motorola 68010 CPU connected to 1MB of RAM, some flash, and an MC68681 dual serial port controller, which handles most of the I/O. (The 68010 is almost identical to the 68000 but with some minor fixes which won't affect us here. I'll mostly be referring to the common aspects of both processors). One of the serial connections is used as a TTY to interact with either the unix-like Computie OS, or the monitor software that's normally stored in the flash chip. It also supports a CompactFlash card and SLIP connection over the other serial port for internet access, but we wont cover those here. In order to get a working emulator, we'll focus on just the CPU, memory, and MC68681 controller.

The 68000

The 68000 is 32-bit processor with a 16-bit data bus and 16-bit arithmetic logic unit. It was used on many early computers including the early Macintosh series, the early Sun Microsystems workstations, the Amiga, the Atari ST, and the Sega Genesis/Mega Drive, just to name a few. It was almost chosen for the IBM PC as well, but IBM wanted to use an inexpensive 8-bit data bus in the PC, and the 68008 (with an 8-bit data bus) wasn't available at the time. The 8088, with it's 8-bit bus, was available however, and we have been stuck with that decision ever since.

The 68000 has 8 32-bit general purpose data registers, and 7 32-bit general purpose address registers plus two stack registers which can be accessed as the 8th address register depending on whether the CPU is in Supervisor mode or User mode. Internally the address registers use a separate bus and adder unit from the main arithmetic logic unit, which only operates on the data registers. This affects which instructions can be used with which registers, and operations on address registers don't always affect the condition flags (which has caused me many troubles both when writing the Computie software, and with the implementation of instructions here).

A 16-bit status register is used for condition codes and for privileged flags like the Supervisor mode enable flag and the interrupt priority level. Only the lower 8 bits can be modified from User mode. The conditions flags are set by many of the instructions based on their results, and can be checked by the conditional jump instructions to branch based on the results of comparisons.

The program counter register keeps track of the next instruction to be executed. Instructions are always a multiple of 2-byte words, and the CPU uses big endian byte order, so the most significant byte will always be in the lower byte address in memory. As an example, the NOP instruction uses the opcode 0x4E71, where 0x4E would be the first byte in memory followed by 0x71. A longer instruction like ADDI can have instruction words after the opcode (in this case the immediate data to add). For example, addil #0x12345678, %d0 which adds the hex number 0x12345678 to data register 0 would be encoded as the sequence of words [0x0680, 0x1234, 0x5678]. The opcode word, 0x0680, has encoded in it that it's an ADDI instruction, that the size of the operation is a long word (32-bit), and that it should use data register 0 as both the number to add to, and the destination where the result will be stored. (Note: 68000 assembly language instructions move data from the left hand operand to the right hand operand, unlike Intel x86 assembly language which uses the reverse).

A vector table is expected at address 0 which contains an array of up to 256 32-bit addresses. The first address contains the value to be loaded into the Supervisor stack register upon reset, and the remaining addresses are the value loaded into the program counter when a given exception occurs. This table cannot be relocated on the 68000, but it can be changed after reset on the 68010. Computie uses the 68010 for this exact feature, so that the OS can put the vector table in RAM, but the monitor software doesn't use interrupts. We wont cover interrupts here so this feature isn't needed for now and we can focus only on emulating the 68000. As for the vector table, we just need to simulate how the processor starts up on power on or after a reset, in which case the vector table is always at address 0, and the first two long words are the stack pointer and initial program counter respectively.

The 68681 Serial Port Controller

The MC68681 is a peripheral controller designed specifically for use with the 68000 series. It has two serial channels, A and B, as well as an onboard 16-bit timer/counter, 8 general purpose output pins, and 6 general purpose input pins. Internally it has 16 registers which can be read or written to from the CPU. The behaviour of the 16 registers is sometimes different between reading and writing, such as the status registers (SRA & SRB) which indicate the current status of the serial ports when read, and the clock select registers (CSRA & CSRB) which configure the serial port clocks when writing to the same address as the status registers. It can also generate an interrupt for one of 8 different internal conditions, such as data ready to read on a given channel, or the timer reaching zero. It uses it's own clock signal to generate the serial clocks and to count down with, so it will need to run some code along side the CPU to simulate its internal state.

The Memory

Now that we have a bit of background on the devices we'll be emulating, lets start making the emulator. The first thing we'll need in order to emulate our computer is a way of accessing and addressing memory where instruction data can be read from. We need to eventually have a common way of reading and writing to either simulated ram, or simulated I/O devices. Since we want to keep things generic and interchangeable, using Rust enums for the different devices in the system would be too tightly-coupled. Traits it is, so we'll start with an Addressable trait.

type Address = u64;     // I (wishfully) chose u64 here in case
                        // I ever emulate a 64-bit system

pub trait Addressable {
    fn len(&self) -> usize;
    fn read(&mut self, addr: Address, data: &mut [u8]) -> Result<(), Error>;
    fn write(&mut self, addr: Address, data: &[u8]) -> Result<(), Error>;
    ...
}

I went through a few different iterations of this, especially for the .read() method. At first I returned an iterator over the data starting at the address given, which works well for simulated memory, but reading from an I/O device could return data that is unique to when it was read. For example, when reading the next byte of data from a serial port, the data will be removed from the device's internal FIFO and returned, and since at that point it wont be stored anywhere, we can't have a reference to it. We need the data (of variable length) to be owned by the caller when the method returns, and passing in a reference to a mutable array to hold that data is a simple way to do that.

We can also add some default methods to the trait which will make it easier to access multi-byte values. The example here only shows methods to read and write 16 bit numbers in big endian byte order but there are also similar methods for 32-bit numbers and for little endian numbers.

pub trait Addressable {
    ...
    fn read_beu16(&mut self, addr: Address) -> Result<u16, Error> {
        let mut data = [0; 2];
        self.read(addr, &mut data)?;
        Ok(read_beu16(&data))
    }

    fn write_beu16(&mut self, addr: Address, value: u16) -> Result<(), Error> {
        let mut data = [0; 2];
        write_beu16(&mut data, value);
        self.write(addr, &data)
    }
    ...
}

#[inline(always)]
pub fn read_beu16(data: &[u8]) -> u16 {
    (data[0] as u16) << 8 |
    (data[1] as u16)
}

#[inline(always)]
pub fn write_beu16(data: &mut [u8], value: u16) -> &mut [u8] {
    data[0] = (value >> 8) as u8;
    data[1] = value as u8;
    data
}

Now for some simulated ram that implements our trait. (I'm leaving out the .new() methods for most of the code snippets because they are pretty straight-forward, but you can assume they exist, and take the their field values as arguments, or set their fields to 0).

pub struct MemoryBlock {
    pub content: Vec<u8>,
}

impl Addressable for MemoryBlock {
    fn len(&self) -> usize {
        self.contents.len()
    }

    fn read(&mut self, addr: Address, data: &mut [u8]) -> Result<(), Error> {
        for i in 0..data.len() {
            data[i] = self.contents[(addr as usize) + i];
        }
        Ok(())
    }

    fn write(&mut self, addr: Address, data: &[u8]) -> Result<(), Error> {
        for i in 0..data.len() {
            self.contents[(addr as usize) + i] = data[i];
        }
        Ok(())
    }
}

Simulating The CPU

With just the Addressable trait, we can start simulating the CPU. Each cycle of the CPU involves reading in instruction data, decoding it, executing the instruction, modifying the stored state of the CPU, and finally checking for interrupts or breakpoints before looping again. We don't need all of this to start though, so first lets make some CPU state so that we at least have a PC (program counter) to keep track of the instruction data we've read.

#[derive(Copy, Clone, Debug, PartialEq)]
pub enum M68kStatus {
    Init,
    Running,
    Stopped,
}

#[derive(Clone, Debug, PartialEq)]
pub struct M68kState {
    pub status: M68kStatus,

    pub pc: u32,            // Program Counter
    pub sr: u16,            // Status Register
    pub d_reg: [u32; 8],    // Data Registers
    pub a_reg: [u32; 7],    // Address Registers
    pub ssp: u32,           // Supervisor Stack Pointer
    pub usp: u32,           // User Stack Pointer
}

pub struct M68k {
    pub state: M68kState,
    ...
}

(I've separated the state into its own struct, separate from the M68k struct, in part to make it cleaner, but mostly to make it easier to test. We can get a complete known state using just M68kState::new(), and we can clone, modify, and compare states because we've derived PartialEq, so after running a test on a given instruction, we only need one assert_eq!(cpu.state, expected_state) to check if the resulting state is what we expected).

Next we need to initialize the CPU. When the 68000 is reset, it first reads in the stack pointer and initial value of the PC register from the beginning of memory where the vector table is located.

impl M68k {
    ...
    pub fn init(&mut self, memory: &mut dyn Addressable) -> Result<(), Error> {
        self.state.ssp = memory.read_beu32(0)?;
        self.state.pc = memory.read_beu32(4)?;
        self.state.status = M68kStatus::Running;
        Ok(())
    }
    ...
}

Since the decoding of instructions can be a bit convoluted, and since speed is not our utmost goal, it's cleaner to decode the instructions fully into some kind of internal representation, and then execute them based on that representation. For now, lets just add a NOP instruction.

#[derive(Clone, Debug)]
pub enum Instruction {
    NOP,
}

impl M68k {
    pub fn read_instruction_word(&mut self, memory: &mut dyn Addressable) -> Result<u16, Error> {
        let ins = memory.read_beu16(self.state.pc as Address)?;
        self.state.pc += 2;
        Ok(ins)
    }

    pub fn decode(&mut self, memory: &mut dyn Addressable) -> Result<Instruction, Error> {
        let ins = self.read_instruction_word(memory)?;

        match ins {
            0x4E71 => Ok(Instruction::NOP),
            _ => panic!("instruction not yet supported: {:#04X}", ins),
        }
    }
}

We can then make a function to execute the decoded instruction

impl M68k {
    pub fn execute(&mut self, memory: &mut dyn Addressable, instruction: Instruction) -> Result<(), Error> {
        match instruction {
            Instruction::NOP => {
                // Do Nothing
                Ok(())
            },
            _ => panic!("Instruction not implemented: {:?}", instruction),
        }
    }
}

And finally a function to wrap these stages together into a single step. For debugging purposes we'll print out what instruction we're about to execute after decoding but before executing.

impl M68k {
    pub fn step(&mut self, memory: &mut dyn Addressable) -> Result<(), Error> {
        match self.state.status {
            M68kStatus::Init => self.init(memory),
            M68kStatus::Stopped => Err(Error::new("cpu has stopped")),
            M68kStatus::Running => {
                let addr = self.state.pc;
                let instruction = self.decode(memory)?;
                println!("{:08x}: {:?}", addr, instruction);
                self.execute(memory, instruction)?;
                Ok(())
            },
        }
    }
}

At this point we have enough pieces to loop over a series of NOP instructions. Our main function looks like the following

const ROM: &[u16] = &[
    0x0010, 0x0000,     // Initial stack address is at 0x00100000
    0x0000, 0x0008,     // Initial PC address is at 0x8, which is the word
                        //  that follows this

    0x4e71,             // 4 NOP instructions
    0x4e71,             
    0x4e71,
    0x4e71,             

    0x4e72, 0x2700      // The STOP #0x2700 instruction, which would normally
                        //  stop the CPU but it's unsupported, so it will
                        //  cause a panic!()
];

let mut cpu = M68k::new();
let mut memory = MemoryBlock::from_u16(ROM);
loop {
    cpu.step(&mut memory).unwrap();
}

Our output should look something like this:

00000008: NOP
0000000a: NOP
0000000c: NOP
0000000e: NOP
thread 'main' panicked at 'instruction not yet supported: 0x4E72', src/main.rs:184:18

Adding Instructions

Since the 68000 has a reasonably orthogonal instruction set, we can break down the opcode word into sub-components, and build up instructions by separately interpreting those sub-components, rather than having a match arm for each of the 65536 combinations. There is a really helpful chart by GoldenCrystal which shows the full breakdown of opcodes for the 68000. We can look at the first 4 bits of the instruction word to separate it into 16 broad categories of instruction, and then further break it down from there. The full code can be seen here

We can extend our Instruction type to contain more instructions, including the addressing modes that the 68000 supports. A MOVE instruction for example can move data to or from a data or address register, or to memory indirectly using an address in an address register (optionally pre-decrementing or post-incrementing the address), or indirectly using an offset added to an address register, as well as a few others. Since these different addressing modes are available for most instructions, we can wrap them up into a Target type, and use that as the arguments of instructions in the Instruction type. For example, the instruction addil #0x12345678, %d0 would be represented as Instruction::ADD(Target::Immediate(0x12345678), Target::DirectDReg(0), Size::Long). We will maintain the same operand order as the 68k assembly language so data will move from the left hand operand (0x12345678) to the right hand operand (%d0).

pub type Register = u8;

#[derive(Copy, Clone, Debug, PartialEq)]
pub enum Size {
    Byte,
    Word,
    Long,
}

#[derive(Copy, Clone, Debug, PartialEq)]
pub enum Condition {
    NotEqual,
    Equal,
    ...
}

#[derive(Copy, Clone, Debug, PartialEq)]
pub enum Target {
    Immediate(u32),                     // A u32 literal
    DirectDReg(Register),               // Contents of a data register
    DirectAReg(Register),               // Contents of an address register
    IndirectAReg(Register),             // Contents of a memory location given by an address register
    IndirectARegInc(Register),          // Same as IndirectAReg but increment the address register
                                        // by the size of the operation *after* reading memory
    IndirectARegDec(Register),          // Same as IndirectAReg but decrement the address register
                                        // by the size of the operation *before* reading memory
    IndirectARegOffset(Register, i32),  // Contents of memory given by an address register plus the
                                        // signed offset (address register will *not* be modified)
    IndirectPCOffset(i32),              // Same as IndirectARegOffset but using the PC register
    IndirectMemory(u32),                // Contents of memory location given by literal u32 value
}

#[derive(Clone, Debug, PartialEq)]
pub enum Instruction {
    ADD(Target, Target, Size),          // Addition
    ADDA(Target, Register, Size),       // Adding to an address register
                                        //  doesn't affect flags

    Bcc(Condition, i32),                // Branch Conditionally
    BRA(i32),                           // Branch to PC + offset
    BSR(i32),                           // Branch to Subroutine
                                        //  (Push PC; PC = PC + offset)

    JMP(Target),                        // Set the PC to the given value
    JSR(Target),                        // Push PC to the stack and then
                                        //  set PC to the given value

    LEA(Target, Register),              // Load effective address into
                                        //  address register

    MOVE(Target, Target, Size),
    MOVEA(Target, Register, Size),
    NOP,

    RTS,                                // Return from subroutine (Pop PC)
    STOP(u16),                          // Load word into SR register and
                                        //  stop until an interrupt

    SUB(Target, Target, Size),          // Subtraction
    SUBA(Target, Register, Size),
    ...
}

This is just an example of the instruction type definitions. The full code can be found here. Note: it's possible to express more combinations with these instruction types than there are legal instruction combinations. Some combinations are illegal on the 68000 but allowed on the 68020 and up, which the emulator supports using an enum to represent the different 68000 model numbers. Most of the error checking and version difference checking is done during the decode phase (and an illegal instruction exception raised if necessary). Some instructions have special behaviours, so they've been given their own variant in the enum, like ADDA to add a value to an address register which doesn't affect the condition codes the way the ADD instruction does, or CMPA to compare an address register which sign extends byte or word operands to long words before comparing them.

Abstracting Time

In the case of a real CPU, the clock signal is what drives the CPU forward, but it's not the only device in the system that is driven by a clock. I/O devices, such as the MC68681 serial port controller also take an input clock which affects their state over time. In the case of the serial port controller, it has a timer which needs to count down periodically. We're going to need some way of running code for different devices based on the clock, so lets use another trait for this.

pub type Clock = u64;
pub type ClockElapsed = u64;

trait Steppable {
    fn step(&mut self, memory: &mut dyn Addressable, clock: Clock) -> Result<ClockElapsed, Error>;
}

Now we can call the step() method each cycle and pass it the current clock value. It will return the number of clock ticks that should elapse before the next call to that device's step() method.

In the case of Computie, the CPU runs at 10 MHz, but the serial port controller runs on a separate clock at 3.6864 MHz. In order to handle these different clock speeds, we can arbitrarily decide that our Clock value will be the number of nanoseconds from the start of the simulation, and ClockElapsed will be a difference in nanoseconds from the start of the start of the step. We use a u64 here so that we can keep track of simulation time in nanoseconds for approximately 584 which should be enough. Keeping track of the time will allow us to later limit how much time passes (either speeding up or slowing down the execution relative to real-time). With this, we can get a somewhat accurate count when simulating the timer in the serial controller chip. That said, we wont worry about simulating CPU execution times, which varies quite a bit based on each instruction and it's operands, so can add a lot of complexity.

Some I/O

It's time to implement the MC68681 serial port controller. Since it's both an Addressable device and a Steppable device, we'll need to implement both traits. The registers we'll need to support first are the serial port channel A registers. REG_TBA_WR is the transmit write buffer, which will output the character written to it over serial channel A. We can just print the character written to this register to the screen for now. We also need to implement the REG_SRA_RD register, which is a status register. Bits 3 and 2 of the status register indicate if the transmit buffer for channel A is ready and empty. The software for Computie checks the status register before writing data because the real MC68681 can't transmit fast enough to avoid a buffer overrun, so as long as we return a value with those bits set, the software will write characters to the REG_TBA_WR register. This example also shows the REG_RBA_RD register for reading serial data in, but setting the port_a_input field is not shown for simplicity. The full code has be viewed here

// Register Addresses (relative to mapped address)
const REG_SRA_RD: Address = 0x03;       // Ch A Status Register
const REG_TBA_WR: Address = 0x07;       // Ch A Byte to Transmit
const REG_RBA_RD: Address = 0x07;       // Ch A Received Byte
const REG_ISR_RD: Address = 0x0B;       // Interrupt Status Register

// Status Register Bits (SRA/SRB)
const SR_TX_EMPTY: u8  = 0x08;
const SR_TX_READY: u8  = 0x04;
const SR_RX_FULL: u8   = 0x02;
const SR_RX_READY: u8  = 0x01;

// Interrupt Status/Mask Bits (ISR/IVR)
const ISR_TIMER_CHANGE: u8 = 0x08;

struct MC68681 {
    pub port_a_status: u8,
    pub port_a_input: u8,

    pub is_timing: bool,
    pub timer: u16,
    pub int_status: u8,
}

impl Addressable for MC68681 {
    fn len(&self) -> usize {
        0x10
    }

    fn read(&mut self, addr: Address, data: &mut [u8]) -> Result<(), Error> {
        match addr {
            REG_SRA_RD => {
                data[0] = SR_TX_READY | SR_TX_EMPTY;
            },
            REG_RBA_RD => {
                data[0] = self.port_a_input;
                self.port_a_status &= !SR_RX_READY;
            },
            REG_ISR_RD => {
                data[0] = self.int_status;
            },
            _ => { },
        }
        debug!("{}: read from {:0x} of {:0x}", DEV_NAME, addr, data[0]);
        Ok(())
    }

    fn write(&mut self, addr: Address, data: &[u8]) -> Result<(), Error> {
        debug!("{}: writing {:0x} to {:0x}", DEV_NAME, data[0], addr);
        match addr {
            REG_TBA_WR => {
                // Print the character
                println!("{}", data[0] as char);
            },
            _ => { },
        }
        Ok(())
    }
}

impl Steppable for MC68681 {
    fn step(&mut self, memory: &mut dyn Addressable, clock: Clock) -> Result<ClockElapsed, Error> {
        if self.is_timing {
            // Count down, wrapping around from 0 to 0xFFFF
            self.timer = self.timer.wrapping_sub(1);

            if self.timer == 0 {
                // Set the interrupt flag
                self.int_status |= ISR_TIMER_CHANGE;
            }
        }

        // Delay for the number of nanoseconds of our 3.6864 MHz clock
        Ok(1_000_000_000 / 3_686_400)
    }
}

This implementation is enough to print the Welcome to the 68k Monitor! message that the monitor software prints at boot, but we can't accept input yet. Since Computie is meant to be connected via TTY, we could open a new pseudoterminal on the host computer (Linux in this case), and then connect to that pseudoterminal using miniterm like we would with the real Computie. This will also free the console window for debugging and log messages.

I originally implemented this using non-blocking input to check for a new character received on the machine-end of the pseudoterm, and then storing it in a single byte in the MC68681 object, but I later changed this to use a separate thread for polling, and mpsc channels to communicate with the simulation thread. It's a bit too much code to include here but you can see the full tty implementation here

Box It Up

We have 3 different devices objects at this point: the CPU (M68k), the memory (MemoryBlock), and the serial port controller (MC68681). The CPU implements the Steppable trait, the memory implements the Addressable trait, and the controller implements both. That last one is a problem because we can't have two mutable references to both the Addressable and Steppable trait objects of the controller at the same time, and rust doesn't yet support trait objects implementing multiple traits under these conditions. Generics wont work either because we need to store the Addressables in some kind of list, and items in a list must have the same type, so we need some other way of getting a reference to one of the trait objects only when we need to use it. If we weren't so adamant about making this flexible and configurable, we could possibly keep this simpler, but alas, we are that adamant. So lets introduce another trait, and some reference counted boxes!

pub trait Transmutable {
    fn as_steppable(&mut self) -> Option<&mut dyn Steppable> {
        None
    }

    fn as_addressable(&mut self) -> Option<&mut dyn Addressable> {
        None
    }
}

The Transmutable trait can be implemented for each device object, and it has a method for each of our traits, which returns the trait object reference we need. The default implementations return None to indicate that the trait is not implemented for that device object. Device objects that do implement a given trait can redefine the Transmutable function to return Some(self) instead. That means that any Transmutable trait object can be turned into either an Addressable or a Steppable, if supported by the underlying device object, and we have a way of checking that support at runtime.

We top it all off with TransmutableBox which will allow us to have multiple references to any Transmutable objects, so we can pass them around to build our machine configuration. wrap_transmutable is a helper function to box up the device object during startup. The device objects will be set up once at start up and then not changed until the program terminates, so we're not too concerned about reference cycles.

pub type TransmutableBox = Rc<RefCell<Box<dyn Transmutable>>>;

pub fn wrap_transmutable<T: Transmutable + 'static>(value: T) -> TransmutableBox {
    Rc::new(RefCell::new(Box::new(value)))
}

Using this method does introduce some performance penalties, but they are marginal relative to the decode and execution times of each instruction and we can still achieve pretty decent instruction cycle speeds despite the overhead. If speed was a concern, we might try to avoid the Transmutable trait by also eliminating our Steppable trait and using a static machine configuration where the device object types are known at compile time and the top level function for each machine configuration would drive the simulation forward. This latter style architecture is used by many other emulators, such as the ClockSignal (CLK) emulator (which has a very well organized and easy to read codebase if you're looking for another emulator project to learn from). The downside is that each machine requires more machine-specific top level code to tie the pieces together.

If anyone knows of a better way to organize this so that we can get the best of both worlds, speed and the ability to abstract away all the devices without tight coupling, I'd love to heard about it. I'm always looking for new ways to design things in Rust.

An Addressable of Addressables (The Data Bus)

With this new trait, all of our devices look the same regardless of the combinations of traits they implement. We can store them all in the same list, as well as pass them to other objects to be turned into their respective trait references when needed. We can now implement a Bus to hold our Addressables so that we can access them all through the same address space

pub struct Block {
    pub base: Address,
    pub length: usize,
    pub dev: TransmutableBox,
}

pub struct Bus {
    pub blocks: Vec<Block>,
}

impl Bus {
    /// Insert the devices in the correct address order
    pub fn insert(&mut self, base: Address, length: usize, dev: TransmutableBox) {
        let block = Block { base, length, dev };
        let i = self.blocks.iter().position(|cur| cur.base > block.base).unwrap_or(self.blocks.len());
        self.blocks.insert(i, block);
    }

    /// Find the device that's mapped to the given address range, and return
    /// the device, as well as the given address minus the device's base address
    pub fn get_device_at(&self, addr: Address, count: usize) -> Result<(TransmutableBox, Address), Error> {
        for block in &self.blocks {
            if addr >= block.base && addr < (block.base + block.length as Address) {
                let relative_addr = addr - block.base;
                if relative_addr as usize + count <= block.length {
                    return Ok((block.dev.clone(), relative_addr));
                } else {
                    return Err(Error::new(&format!("Error reading address {:#010x}", addr)));
                }
            }
        }
        return Err(Error::new(&format!("No segment found at {:#010x}", addr)));
    }
}

impl Addressable for Bus {
    fn len(&self) -> usize {
        let block = &self.blocks[self.blocks.len() - 1];
        (block.base as usize) + block.length
    }

    fn read(&mut self, addr: Address, data: &mut [u8]) -> Result<(), Error> {
        let (dev, relative_addr) = self.get_device_at(addr, data.len())?;
        let result = dev.borrow_mut().as_addressable().unwrap().read(relative_addr, data);
        result
    }

    fn write(&mut self, addr: Address, data: &[u8]) -> Result<(), Error> {
        let (dev, relative_addr) = self.get_device_at(addr, data.len())?;
        let result = dev.borrow_mut().as_addressable().unwrap().write(relative_addr, data);
        result
    }
}

Our Bus can act like an Addressable, so anything that's mapped to an address on the bus can be accessed through the same &mut Addressable allowing us to pass it to the CPU's .step() method.

A Happy Little System

The last piece we need is a way to call all of our .step() methods, but only the top level loop needs to be able to call them, so we don't need to package them up the same as Addressable. We do, however, need to keep track of the passage of time. We can make a System to hold our pieces, which can also hold our event tracking code, and our Bus.

pub struct NextStep {
    pub next_clock: Clock,
    pub device: TransmutableBox,
}

struct System {
    pub clock: Clock,
    pub bus: Bus,
    pub event_queue: Vec<NextStep>,
}

impl System {
    /// Insert into the queue such that the last device is the next step to execute
    fn queue_device(&mut self, device_step: NextStep) {
        for i in (0..self.event_queue.len()).rev() {
            if self.event_queue[i].next_clock > device_step.next_clock {
                self.event_queue.insert(i + 1, device_step);
                return;
            }
        }
        self.event_queue.insert(0, device_step);
    }

    /// Add a device to the system, and if it's `Steppable` then queue it
    pub fn add_device(&mut self, device: TransmutableBox) -> Result<(), Error> {
        if device.borrow_mut().as_steppable().is_some() {
            self.queue_device(NextStep::new(device));
        }
        Ok(())
    }

    /// Add a device to the system while also mapping it to the given address on the bus
    pub fn add_addressable_device(&mut self, addr: Address, device: TransmutableBox) -> Result<(), Error> {
        let length = device.borrow_mut().as_addressable().unwrap().len();
        self.bus.insert(addr, length, device.clone());
        self.add_device(device)
    }

    /// Execute one step function from the queue
    pub fn step(&mut self) -> Result<(), Error> {
        // Remove the last item in the queue which is the next step to execute
        let mut next_device = self.event_queue.pop().unwrap();

        self.clock = next_device.next_clock;
        let memory = self.bus.as_addressable().unwrap();

        // Execute the step function
        let diff = next_device.device.borrow_mut().as_steppable().unwrap().step(memory, self.clock)?;
        // Adjust the device's next scheduled step
        next_device.next_clock = self.clock + diff;

        // Re-insert into the queue in order of next event
        self.queue_device(next_device);
        Ok(())
    }

    /// Run step functions until the system clock has changed by the given time in nanoseconds
    pub fn run_for(&mut self, elapsed: ClockElapsed) -> Result<(), Error> {
        let target = self.clock + elapsed;

        while self.clock < target {
            self.step()?;
        }
        Ok(())
    }
}

In later iterations, I pass the whole immutable reference to System into the step functions, and put Bus inside a RefCell which can then be accessed if needed by the .step() function for the device object. I've also added an interrupt controller to System which can be used for hardware interrupts from devices (MC68681 in the case of Computie).

Tying It All Together

Finally we can tie all our pieces together and set them in motion.

fn main() -> Result<(), Error> {
    let mut system = System::new();

    // Create our Flash memory, pre-loaded with our Computie monitor firmware
    let rom = MemoryBlock::load("binaries/computie/monitor.bin")?;
    system.add_addressable_device(0x00000000, wrap_transmutable(rom))?;

    // Create a RAM segment at the 1MB address
    let mut ram = MemoryBlock::new(vec![0; 0x00100000]);
    system.add_addressable_device(0x00100000, wrap_transmutable(ram))?;

    let mut serial = MC68681::new();
    // Open a new PTY and launch a terminal emulator that in turn
    // launches miniterm and connects to the other end of the PTY
    launch_terminal_emulator(serial.port_a.connect(Box::new(SimplePty::open()?))?);
    system.add_addressable_device(0x00700000, wrap_transmutable(serial))?;

    let mut cpu = M68k::new(M68kType::MC68010);
    system.add_device(wrap_transmutable(cpu))?;

    // Run forever
    system.run_for(u64::MAX)?;
    Ok(())
}

pub fn launch_terminal_emulator(name: String) {
    use std::thread;
    use std::time::Duration;
    use std::process::Command;

    Command::new("x-terminal-emulator").arg("-e").arg(&format!("pyserial-miniterm {}", name)).spawn().unwrap();
    thread::sleep(Duration::from_secs(1));
}

We can now boot our monitor firmware and once interrupts are added, we can even boot the OS!

Now What

After only a couple weeks I was able to get all of the Computie software running, including the OS, albeit with a buggy and incomplete 68000 implementation. That didn't seem too hard. What else can I get running inside this emulator. How about I try emulating the Sega Genesis! How hard can it be? Well... after a few months it's damn near broken me, but I'm determined to complete it eventually. I've also taken detours into emulating the original Macintosh (simpler than the Genesis so easier to debug the 68k implementation with) and the TRS-80 (in order to test the Z80 implementation I made to eventually use in the Genesis). I'm hoping to write more about those other efforts, once I get them somewhat working. Until then, happy emulating!

Bootstrapping a Homebuilt Computer Using An Arduino

transistor fet — Sat, 27 Nov 2021 03:02:13 +0000

Originally published at jabberwocky.ca

Written September 2021

Over the last couple of years I've been working on a series of projects to build my own computer from scratch. It had been a dream of mine when I first started learning about computers and electronics to build my own computer, and I tried designing some on paper with what I knew, but such a complex project was out of reach at the time. I've learned so much in the many years since then and after seeing the awesome project PDP-11/Hack, I thought you know, why not try fiddling with CPUs again and see how far I get, just for the fun of it.

As I thought about how to approach the problem of getting a program into a minimal system built on a breadboard, I thought perhaps I could use an Arduino Mega, with it's multitude of I/O pins. Initially I thought I could use it to program a Flash or EEPROM chip separately, but after thinking about it a bit, I realized I could program a RAM chip in the same circuit as the CPU. What follows is my journey towards building my first single board computer through incremental experimentation.

The Chips

PDP-11/Hack is based around an old PDP-11 processor module that was bought online on Ebay. I hadn't thought about buying used parts online before since I didn't expect them to work, but that got me searching around for what was available. While Ebay had many used chips, especially the less common ones, AliExpress had the best deals, with lots of old 8-bit CPUs, memory chips, and peripheral controllers, sometimes for less than a dollar a chip. I figured I'd order some and see if I could get them working. To my surprise, a fair number of the chips I received worked as expected, even the ones that were clearly relabelled. For more information on relabelled and counterfeit chips, check out this great video about "Fake Chips" by David Viens, discussing this problem with popular audio synth chips. In my various purchases of used chips, the audio chips were most likely to be counterfeit due to the large demand for them and the higher prices they fetch. Some of the CPU and memory chips that I received were also counterfeit but they tended to still be functional. The date codes would often be changed, with each chip in the lot having the same date code, and in the case of the memory chips, sometimes a compatible memory chip of the same size would be relabelled as a more popular part number, such as the popular HM628512 static RAM chip.

I ordered some Z80s, 6502s, 65816s, 68000s, 68010s, 8088s, and 8086s, as well as some peripheral chips for each CPU, some memory chips, and various speeds of crystals.

The First Fiddlings

While waiting for my first orders of chips to arrive, I searched though the various old chips that I had scavenged from disassembled equipment over the years. I happened to have a Mitsubishi M5M5118P Static RAM chip on-hand, which is organized as 2 kilobytes of 8-bits. I wired each address and data pin, as well as the W (write) and S1 (chip select 1) pins, to pins on the Arduino Mega. For the S2 (chip select 2) pin, I wired it to ground so that only S1 needed to be brought low to start a transfer. For the address and data pins, I made sure to use the arduino pins that correspond to specific hardware port registers so that I could write directly to the ATMega's PORTx registers to set all 8 bits at once.

The code first initializes the I/O pins. Port A has the 8 data pins connected to it, with Port L and C used for the upper and lower address pins respectively. The chip select and write pins use arduino digitalWrite() functions since we only need to set 2 bits per request, and it's a bit easier to understand and edit than bit operations on the PORTG register. (The MEM_RD pin is left disconnected for the M5M5118P, but it is used by some chips, so I've left it in the code).

#define MEM_CS      39      // PG2
#define MEM_RD      40      // PG1
#define MEM_WR      41      // PG0

// Address Bus
PORTL = 0x00;               // A8 - A15
DDRL = 0xFF;                // Configure as outputs
PORTC = 0x00;               // A0 - A7
DDRC = 0xFF;                // Configure as outputs

// Data Bus
PORTA = 0x00;               // D0 - D7
DDRA = 0x00;                // Configure the data bus as inputs by default

// Controls
pinMode(MEM_CS, OUTPUT);
pinMode(MEM_RD, OUTPUT);
pinMode(MEM_WR, OUTPUT);
digitalWrite(MEM_CS, 1);    // Each control signal is normally-high,
digitalWrite(MEM_RD, 1);    // active-low, so set them all to "high"
digitalWrite(MEM_WR, 1);    // to disable the chip

The data written to each memory address during the write test will be the lower byte of the address, so the data returned should be a sequence of numbers from 0x00 to 0xFF

PORTA = 0x00;
DDRA = 0xFF;                    // Set the PORTA pins to "output" mode
for (int i = 0; i < 2048; i++) {
    PORTL = (i >> 8);           // Set the upper address bits
    PORTC = 0x00FF & i;         // Set the lower address bits
    PORTA = (i & 0x00FF);       // Set the output data byte
    digitalWrite(MEM_WR, 0);    // Set the WR and CS pins to low to start a memory write
    digitalWrite(MEM_CS, 0);
    //delayMicroseconds(1);     // Optional delay for slower chips
    digitalWrite(MEM_WR, 1);    // Set the WR and CS pins high to end the memory write
    digitalWrite(MEM_CS, 1);
}

The data is then read back and printed to the arduino serial monitor. When a byte is read that doesn't match the lower byte of that address, it's recorded as an error and displayed at the end. This will give us an indication if there was a glitch during reading or writing, or if the cell is not working properly, although it's not a conclusive test because only one value is tested per cell.

byte value;
int errors = 0;

PORTA = 0x00;
DDRA = 0x00;                    // Set the PORTA pins to "input" mode
for (int i = 0; i < 2048; i++) {
    PORTL = (i >> 8);           // Set the upper address bits
    PORTC = 0x00FF & i;         // Set the lower address bits
    digitalWrite(MEM_RD, 0);    // Start a memory read by setting CS and RD low
    digitalWrite(MEM_CS, 0);
    //delayMicroseconds(1);     // Optional delay for slower chips
    value = PINA;               // Read in the data and store in temporarily
    digitalWrite(MEM_RD, 1);    // Stop the memory read by setting CS and RD high
    digitalWrite(MEM_CS, 1);

    if (value != (i & 0x00FF))  // If the value isn't the expected value, record as an error
        errors += 1;
    Serial.print(value, HEX);   // Print the value read in hexadecimal
    Serial.print(" ");
    if (i % 64 == 63)           // Wrap the output line every 64 bytes for readability
        Serial.print("\n");
}

Serial.print("\n");
Serial.print("Errors: ");
Serial.print(errors, DEC);
Serial.print("\n");

The complete MemTest code

I tried running this code on a few different memory chips and most chips had no errors. When a chip was broken, it would often contain either entirely random or all zero data and no cells would write. After a while I started noticing glitches where a couple of cells would produce errors, but it would often be different cells or different numbers of errors every time I tried to read. After much fiddling I found these were caused by poor electrical connections in the breadboard wiring. This was a frequent issue throughout this project, but it tended to be intermittent. I would sometimes go weeks without a problem, and then have constant glitches for days until I remembered to try jiggling or rearranging the wires.

I had also gotten some EEPROM chips from AliExpress, which I ran the MemTest code on as well. They were quite cheap, so I figured it was worth a try, even though I expected the memory cells to be worn out. I was initially surprised that the EEPROMs did often save the data written to them, with no or almost no errors when read back, with the exception of one batch of chips that were clearly counterfeit and non-functional. Sadly though, I found out with 68k-SBC Rev.0, which used the EEPROMs, that the data would often disappear after a few hours or days. Luckily I didn't need them while testing Rev.0, so I didn't bother buying new EEPROMs from digikey, and I switched to Flash chips for the next revision.

On To Z80s

The Z80 CPUs I had ordered arrived first, so I started with them. The Z80 has separate pins for the address and data lines, which simplifies the wiring, and it also has a static core, so running it at a very low frequency is possible. I whipped up a simple oscillator using a 555 timer set to somewhere around 80 Hz (yes singular Hz).

(This chip turned out to be relabelled. The black paint on top comes off with acetone or alcohol, the ejection holes show that it was sanded down, and the date codes of all 10 chips were identical, despite being desoldered. They are labelled as being 20MHz, but I never ran them above 1MHz. They are definitely a Z80 of some kind, and they worked alright for my experiments, but if you're looking for a reliable part, beware what you buy)

The red breadboard has the 555 oscillator on it, and the the other chip with lots of wires going to it is a memory chip. The Arduino Uno clone in the picture is being used as a logic analyzer, while I was waiting for the generic analyzer I had ordered to arrive.

I had originally thought I would program the RAM chips in-circuit with the CPU. I could use the CPU's bus arbitration signals to disconnect it from the shared bus while the arduino was writing to the RAM, and then configure the arduino pins as inputs to effectively disconnect them from the bus while CPU had control. While that did work, I realized that perhaps I could directly intercept the bus requests if the CPU was slow enough, and directly feed bytes of data to the CPU without the extra step of writing the data to RAM first. The arduino could assert the WAIT signal to the CPU to delay the request until it was ready to complete, thus taking as long as it needed to process the request. I wouldn't necessarily need a RAM chip at all, and it would make it faster to test an updated Z80 program.

In order to intercept the transfer, I set up a pin change interrupt in the arduino for the MREQ input from the CPU, which goes low whenever a byte is read or written by the CPU. The interrupt handler would then assert the WAIT signal and check the MREQ, RD and WR signals to figure out what to do. In the arduino, there was a large array used as the "virtual" memory. It could be pre-initialized with a Z80 program, and any read or write requests would read or write the corresponding location in the array. Since the WAIT signal was asserted throughout this, the arduino could take as much time as it liked, so it was possible to print out debug information to the arduino's serial monitor. It would print the address being accessed and the data value either fetched or written by the bus request. From this I could see that the CPU was actually executing the program step by step, and trace which program address was fetched next to confirm the jump and call instructions were executing as expected.

#define Z80_HADDR_PORT  PORTC
#define Z80_HADDR_PIN   PINC
#define Z80_HADDR_DDR   DDRC

#define Z80_LADDR_PORT  PORTL
#define Z80_LADDR_PIN   PINL
#define Z80_LADDR_DDR   DDRL

#define Z80_LDATA_PORT  PORTA
#define Z80_LDATA_PIN   PINA
#define Z80_LDATA_DDR   DDRA

#define Z80_IS_MREQ()   (!(PINB & 0x01))
#define Z80_IS_RD()     (!(PINB & 0x02))
#define Z80_IS_WR()     (!(PINB & 0x04))

#define Z80_SET_WAIT()  ((PINB | 0x08))
#define Z80_CLR_WAIT()  ((PINB & 0xF7))

word mem_size = 4096;
byte mem[4096] = {
// The Makefile that compiles the Z80 program will format the binary as
// C-compatible text which is #included here, so that whenever this arduino
// code is uploaded, it will have the latest Z80 binary image
#include "../Z80Monitor/output.txt"
};

// This interrupt will only be enabled when the CPU is running
// and the arduino is listening for requests ("device" mode)
ISR (PCINT0_vect)
{
    PCICR = 0x00;       // Disable pin change interrupts

    if (Z80_IS_MREQ() && Z80_HADDR_PIN < 0x20) {
        Z80_CLR_WAIT();                     // Assert the wait signal

        // CPU Read Operation
        if (Z80_IS_RD()) {
            register word addr = (Z80_HADDR_PIN << 8) | Z80_LADDR_PIN;
            Z80_LDATA_DDR = 0xFF;           // Configure data bus pins as output

            #if BUS_DEBUG                   // Print debug information
            Serial.write('R');
            Serial.print(addr, HEX);
            if (addr < mem_size) {
                Serial.write('|');
                Serial.print(mem[addr], HEX);
            }
            Serial.write('\n');
            #endif

            if (addr < mem_size)
                Z80_LDATA_PORT = mem[addr]; // Output the requested byte
            else
                Z80_LDATA_PORT = 0x00;      // Output 0 for all other addresses

            Z80_SET_WAIT();                 // Clear the wait signal
            while (Z80_IS_MREQ()) { }       // Wait until the CPU ends the MREQ
            Z80_LDATA_PORT = 0x00;
            Z80_LDATA_DDR = 0x00;           // Configure data bus pins as inputs
        }
        // CPU Write Operation
        else if (Z80_IS_WR()) {
            register word addr = (Z80_HADDR_PIN << 8) | Z80_LADDR_PIN;

            #if BUS_DEBUG                   // Print debug information
            Serial.write('W');
            Serial.print(addr, HEX);
            Serial.write('|');
            Serial.print(Z80_LDATA_PIN, HEX);
            Serial.write('\n');
            #endif

            if (addr < mem_size)
                mem[addr] = Z80_LDATA_PIN;  // Save the byte from the data bus

            Z80_SET_WAIT();                 // Clear the wait signal
            while (Z80_IS_MREQ()) { }       // Wait until the CPU ends the MREQ
        }
    }

    PCIFR = 0x00;       // Clear pin change interrupt flag
    PCICR = 0x01;       // Enable pin change interrupts
}

Check out the Z80 Supervisor code for more details

Next I added a check for the IOREQ signal, which would respond to specific IO port addresses. When writing to IO port 0xFF, it would either set or reset the arduino LED based on whether 0x00 was written or not. To test it, I made a simple Z80 program that used the out instruction to output 1 to the LED port, which confirmed that the IOREQ code was working and the Z80 was running. Then I added a check for port 0xF1, which would send the byte written by the CPU to the arduino's serial monitor. The following Z80 program could then be run to print a message to the serial monitor!

The first Z80 program, welcome.asm, which was compiled using SDCC's assembler

    org 0000h         ; After a reset, the Z80 starts executing at 0x0000
    jp  start

start:
    ld   sp, 0200h    ; Set the stack pointer to an area above the program
    call _main
    halt

_main:
    ld  a, 01h
    out (00FFh), a    ; Output 1 to our arduino LED control port to turn it on

    ld  de, msg       ; Load the address of the message to print

loop:
    ld  a, (de)       ; Load the byte at message address
    cp  0             ; If it's a null character, jump to loop_end
    jp  Z, loop_end
    out (00F1h), a    ; Output the character to arduino serial
    inc de
    jp  loop

loop_end:

    ret               ; End of _main

msg:    defm    "Welcome To Bread80!\n\n\0"

Z80 Monitor for more Z80 code and build files

I was able to get some C code compiled and running using SDCC, but I was starting to get more glitches, and timing issues. The low speed of the CPU was also becoming a hindrance, but the arduino was not able to assert the wait signal in time at higher CPU speeds. The arduino is not that much faster than the CPU, and the interrupt contains a lot of overhead before the wait signal is asserted. I considered using a flip flop to lock in the wait signal whenever a memory request was initiated, which would be reset by the arduino when it had completed its checks, but that would involve a bunch more wiring, which was already a bit flakey, and I was aiming for minimal external hardware.

There were a lot of wires at this point and poor connections were becoming a problem again. I tried using a section of the breadboard as a patch panel to distribute the data and address signals, but some of the breadboard pins got damaged after I inserted some of the wires at the wrong angle. I lost a lot of time trying to figure out why the program was not executing as expected, before I realized it was caused by the damage to the breadboard. The fact that all the wires were still joined together in bundles of 8 or 12 also caused issues since they couldn't move relative to each other, and the tension caused by this would pull out some of the wires, causing poor connections.

Add Simplicity

With the concept of intercepting the bus request proven, I set about making a much simpler breadboard setup without memory chips. By this point, I had homed in on the 68000 as the CPU to push forward with. It would have more processing power and addressable memory than most of the 8-bit CPUs, which would come in handy when I eventually tried writing an OS, and it required significantly less external circuitry than the 8086/8088, since the address and data buses are not multiplexed like they are on the 8086/8088. The 68000 also has an asynchronous bus, which uses the DTACK signal to indicate the end of the request, rather than a WAIT signal to delay the end of the request. This means I could avoid the need for a flip flop to lock in the wait state.

I started by wiring up a 68000 directly to the arduino pins, along with the necessary pull-up resistors for the control signals. A simple 74HC14-based crystal oscillator provides the clock signal (on the mini green breadboard). The 68000 needs a clock that is at least 4 MHz, or else the dynamic registers used in the CPU will lose their values and cause the CPU to misbehave, but running at such a fast speed wont be a problem here, because of the asynchronous bus. I ended up running it at 8 MHz without issue. The actual execution speed was limited by the arduino's response time, which was often more than 1 microsecond per instruction. No other memory or interfacing chips are needed for a minimal system, besides the arduino.

Note the extra wire bundles and the generic logic analyzer in the upper left corner. This turned out to be very handy indeed. I used Logic 1.2.18 from Saleae to capture various control and data pins to debug various issues I came across. I also purchased a new oscilloscope, which helped a lot for a few tricky problems, especially with the later PCBs.

The 68000 starts a bit differently than the Z80. I didn't realize this at first and had some trouble trying to get it to run as expected until I read the manual closer. At the start of memory is an interrupt vector table from 0x000000 to 0x000400, with 256 entries of 4 bytes each. Each 4 bytes specifies a 32-bit address which should be loaded into the program counter when the corresponding interrupt occurs. The exception to this is the first entry in the table which is the address to be loaded into the stack register upon reset. The second entry contains the program counter on reset. The 6 entries after contain the location of the error handlers for common program errors such as "Illegal Instruction" and "Bus Error". While testing on the breadboard and arduino (with its limited memory), I only reserved space for the first 8 entries in the vector table, and put the program in the remaining space, since those other interrupts would not occur during a simple program. This worked fine for testing.

This interrupt vector table is always located at address 0x000000 on the 68000, but on the 68010, it can be changed after reset using the special IVR register. I later switched to the 68010 when developing the OS in order to use this feature.

The first 68k program, welcome.s, compiled with GCC 9/10 for m68k. Note the assembly syntax here is quite different. Register names are preceded with a % character and data is moved from the left-hand location to the right-hand location, so move.b #0x01, %d1 loads the D1 register with the value 0x01. The comments should also start with | but I changed them to ; for the code formatter here.

    .org    0x0000          ; After reset, the 68k expects the interrupt vector table here

    .word   0x0000          ; stack pointer value loaded on reset
    .word   0x1000
    .word   0x0000          ; PC value loaded on reset
    .word   0x0020

    .org    0x0020          ; Reserve space for the first 8 interrupt vectors
_start:

    move.b  #0x01, %d1
    lea     0x20ff, %a1     ; Load the address of the LED register
    move.b  %d1, (%a1)      ; Write 0x01 to turn the LED on

    lea     message, %a1    ; Load the message address
    lea     0x20f1, %a2     ; Load the address of serial output register

loop:
    move.b  (%a1)+, %d2     ; Load the next character and increment the pointer
    move.b  %d2, (%a2)      ; Write the character to serial

    cmpi.b  #0x00, %d2      ; Loop until the null character is found
    bne     loop

    stop    #0x2700         ; Halt the CPU

message: .ascii "Welcome to Bread68k!\n\n\0"

The 68000 uses memory-mapped IO so the arduino program recognizes the addresses 0x2000 - 0x20FF as IO registers. The 0x20FF register is used for the LED, and the 0x20F1 register for serial bytes.

68k Supervisor is the arduino code. It's a bit messy since it has involved a lot of trial and error while debugging problems, and changes as I've experimented with different chips. The code is now only really used to load an initial program into the onboard Flash chips of the newer 68k-SBC and 68k-SMT boards.

When the Supervisor first runs, it will start in "device" mode (as if it were a device connected to the CPU's bus), and allow the CPU to run freely. While the CPU is running, any input to the serial monitor will be made available if the CPU reads the memory-mapped IO address for serial bytes. To escape out of the input-capture mode, a single backtick "`" character followed by enter can be typed, which will cause the arduino to request the CPU bus through the bus arbitration signals, and enter "controller" mode. In controller mode, the CPU will be suspended, and in the serial monitor a prompt will be displayed which responds to some simple commands, such as run to start the cpu and reset to reset it. The memory chip tests can be run from the command prompt as well. I've mostly hand-changed the address and size values used by the memory tests as needed rather than allowing them to be specified in the command.

Adding Serial via MC68681

The ultimate goal was a standalone computer on a custom PCB, so I needed an IO device that wasn't the arduino. The obvious choice was the MC68681 chip, which is designed to interface easily to the 68000, and which is still widely available. It has 2 serial ports, 6 general purpose input pins, and 8 general purpose output pins. Some of these GPIO pins are needed for the serial port CTS and DTR flow control signals (which turned out to be crucially important for sending large amounts of data over the serial ports), but some could be used for debugging as well. Before getting a circuit board printed, I wanted to make sure all the parts of the complete design would work as expected.

I assembled a circuit on a separate breadboard, and wired it to the data and address buses. I also added an inverter to address line A14 which would go low whenever an address in the 0x4000 range was accessed, which I could use as the chip select signal for the MC68681. The serial port pins were wired to an FTDI module (the small red circuit board in the images) with ground pin connected to the system ground, and the power pin unconnected. The CPU and MC68681 were powered by the Arduino Mega, which was powered through its USB port.

The MC68681 on a half-sized breadboard, with an FTDI Serial-to-USB adapter (the red circuit board) wired to the serial pins. The red LED and a push button are wired to GPIO pins for debugging.

The main breadboard at this point, with the serial board just out of frame. The logic chip on the right is a 74HC14 hex inverter used for decoding the address for the MC68681.

By this point, I had a simple C program that would run on the breadboarded 68k, and use the MC68681 to output text via the FTDI module to a serial terminal program, which was running on my desktop. The code for the monitor at this point in time can be seen here. I was already starting to implementing some of the standard C library functions for formatting numbers and strings, so that I could easily print out debug information to the serial terminal

The First PCB

While experimenting with the 68k on a breadboard, I started working on the PCB design in KiCad for a system that could run without the arduino, 68k-SBC Rev.0. (Note: I started with revision numbers from 0 but later decided I should start from 1 instead, so I skipped Rev.1, and the second version after this board is named Rev.2). The board has the MC68681 with headers for FTDI modules, since I didn't plan on using actual RS-232 connectors with it. It has 2 x 512KB static RAM chips for the upper and lower byte, mapped to address 0x100000, as well as 2 x 32KB EEPROMs, mapped to address 0x000000. There are also 2 x 40 pin headers for all the address, data, and control signals, so that I could hook up the arduino to it. To make this easier with so many wires, I also designed an arduino shield with matching 2 x 40 pin headers wired to the appropriate arduino pins so that I could use ribbon cables to connect them instead of individual wires. That said, I didn't actually use the ribbon cables until Rev.2 so that I could access the unwired control pins for further testing and expansion.

This board also has two jumpers in the lower right corner. One will enable or disable the onboard DTACK generation. With it disabled, the ardunio can provide the DTACK instead, giving it a chance to print each memory request, even if the CPU is reading data from a memory chip. The other jumper will move the address of the EEPROM from 0x000000 to 0x200000. This allows the arudino to respond to addresses in the 0x000000 range, which is where the boot vector table is, allowing it to boot the CPU without the EEPROMs. The EEPROMs can also be programmed while in the 0x200000 address range.

There were various issues with this board and it wasn't long before I moved on to the next revision, but I'll save that for another post.

End of the Beginning

It's been such a fun and rewarding experience playing around with old CPUs again. Using an arduino to bootstrap the process made it a lot easier to experiment and test things out quickly. From the time I started playing around with memory chips in October of 2019, and working a full time job, I had a working single board standalone computer by the end of March 2020. From there, I started writing a proper operating system and made a few upgraded versions of the same system. While I've been spending time on other projects lately, I plan to eventually push further with MC68030s and perhaps more. I hope this inspires others to give it a try and get started in their own experiments with these wonderful classic CPUs.