6o6 v1.1: Faster 6502-on-6502 virtualization for a C64/Apple II Apple-1 emulator

I'm doing periodic updates on some of my long-term projects, one of them being 6o6, a fully virtualized NMOS 6502 CPU core that runs on a 6502 written in 6502 assembly language. 6o6 implements a completely abstracted memory model and a fully controlled execution environment, but by using the host's ALU and providing a primitive means of instruction fusion it can be faster than a naïve interpreter. This library was something I wrote over two decades earlier for my KIM-1 emulator project for the Commodore 64, and relatively recently I open-sourced and discussed it in detail. It runs on just about any 6502-based system with sufficient memory.

For this update I made some efficiency improvements to addressing modes, trimmed an instruction out of the hot path, provided an option for even more control of the 6502 interrupt flag and implemented a faster lane for direct stores to 6502 zero page (as well as the usual custodial and documentation updates). And, of course, any complex library needs a suite of examples, and of course, any update to a complex library demands new examples to play with too.

So, given that this year is Apple's 50th anniversary (and, as it happens, my own 50th year of existence personally), what better way to show off a 6502-on-6502 virtualization library than with an Apple-1 emulator ... that runs on the Commodore 64 or Apple II? Now yea, verily, this is hardly the first such example and several others have done something of the sort, but I submit that 6o6 makes our take on it here unique, and as a bit of fun we'll discuss the Apple-1's hardware and look at all that prior 8-bit emulator art for comparison (for the C64 and Apple II and even more exotic systems like the SAM Coupé).

Microsoft makes 6502 BASIC open source

It was probably going to happen sooner or later, but Microsoft has officially released the source code for 6502 BASIC. The specific revision is very Commodore-centric: it's the 1977 "8K" BASIC variant "1.1," which Commodore users know better as BASIC V2.0, the same BASIC used in the early PET and with later spot changes from Commodore (including removing Bill Gates' famous Easter egg) in the VIC-20 and Commodore 64. I put "8K" in quotes because the 40-bit Microsoft Binary Format version, which is most familiar as the native floating point format for most 8-bit BASICs derived from Microsoft's and all Commodore BASICs from the PET on up, actually starts at 9K in size. In the C64, because there is RAM and I/O between the BASIC ROM and the Kernal ROM, there is an extra JMP at the end of the BASIC ROM to continue to the routine in the lowest portions of the Kernal ROM. The jump doesn't exist in the VIC-20 where the ROM is contiguous and as a result everything past that point is shifted by three bytes on the C64, the length of the instruction.

This is, of course, the same BASIC that Gates wanted a percentage of but Jack Tramiel famously refused to budge on the $25,000 one-time fee, claiming "I'm already married." Gates yielded to Tramiel, as most people did then, but I suspect the slight was never forgotten. Not until the 128 did Microsoft officially appear in the credits for Commodore BASIC, and then likely only as a way to push its bona fides as a low-end business computer. Microsoft's source release also includes changes from Commodore's own John Feagans, who rewrote the garbage collection routine, and was the original developer of the Commodore Kernal and later Magic Desk.

The source code is all in one big file (typical for the time) and supports six machine models, the first most likely a vapourware 6502 system never finished by Canadian company Semi-Tech Microelectronics (STM) better known for the CP/M-based Pied Piper, then the Apple II, the Commodore (in this case PET 2001), the Ohio Scientific (OSI) Challenger, the Commodore/MOS KIM-1, and most intriguingly a PDP-10-based simulator written by Paul Allen. The source code, in fact, was cross-assembled on a PDP-10 using MACRO-10, and when assembled for the PDP-10 emulator it actually emits a PDP-10 executable that traps on every instruction into the simulator linked with it — an interesting way of effectively accomplishing threaded code. A similar setup was used for their 8080 emulator. Unfortunately, I don't believe Allen's code has been released anywhere, though I'd love to be proven wrong if people know otherwise. Note that they presently don't even mention the STM port in the Github README, possibly because no one was sure what it did.

While MACRO-10 source for 6502 BASIC has circulated before and been analysed in detail, most notably by Michael Steil, this is nevertheless the first official release where it is truly open-source under the MIT license and Microsoft should be commended for doing so. This also makes it much easier to pull a BASIC up for your own 6502 homebrew system — there's nothing like the original.

Virtualizing the 6502 on a 6502 with 6o6 (and The Incredible KIMplement goes 1.0)

Okay, promises, promises. Here's the first of my bucket list projects I'm completing which I've intermittently worked on for literally two decades. Now that I've finally shaken out more bugs, tuned it up and cleaned it off, it's time to let people play with the source code.

This is the official 1.0 release of the Incredible KIMplement, an emulator of the one kilobyte, 1MHz MOS/Commodore KIM-1 6502-based single board computer. It provides access to the KIM's built-in TTY support (even through your computer's real serial port) and has expanded RAM with 16K of addressing space, all on an unexpanded stock Commodore 64.

It's almost burying the lede to announce that, though, because the real meat in this entry is how the Commodore 64 manages to emulate a very different 6502-based system. That piece is "6o6," for "6502-on-6502," and is a full virtualized software NMOS 6502 CPU that runs on a 6502 CPU — which I've open-sourced too. It has full control of guest code execution, including trapping undocumented and jam opcodes, and completely abstracts all memory access, making it possible to remap addresses, intercept illegal reads or writes, or even run entirely from virtual memory. On top of that, it's complete enough to not only pass a full functional test but also virtualize itself virtualizing itself:

These GIF screencasts are real-time with no tricks. Here a Commodore 64 and Apple IIe are both running a guest "hello world" payload within 6o6 (stage 1), which is nearly instantaneous, then 6o6 running the payload as a payload within another instance of 6o6 (stage 2), which is a little slower, then 6o6 running 6o6 running 6o6 running the payload (stage 3), which is glacial. But all of it works!

What the KIM-1 really needs is an LCD screen

Giving the 1976 1K RAM, 1MHz 6502-based KIM-1 single-board computer bubble memory storage was all well and good, but the basic unit is still just six numeric LEDs for its display. Let's solve that problem.

Here's a sidecar screen for my KIM-1 that's large enough to be useful, small enough to be portable, and efficient enough to be powered by my unit's built-in power supply. Plus, it can be driven by the KIM-1's unallocated I/O lines so that its 20mA current loop terminal interface remains available, with bonus points for being self-lit so you can see it like the LEDs. And the output driver takes up just 64 bytes of RAM.

Refurb weekend(s): Commodore/MOS KIM-1

Actually, it was more like a whole stinking Refurb Two Months. The KIM-1 is one of the earliest MOS 6502 computers, a single-board system with 1K of RAM (actually 1152 bytes total) and a one-megahertz CPU developed by Chuck Peddle in 1975 as a way to introduce engineers to the new 8-bit microprocessor. However, its low cost meant it ended up taking on a life of its own as it was one of the cheapest ways to assemble an entire working hobbyist system, and Commodore continued to sell them for several years after they bought MOS. You could hand-key in programs with the hexadecimal keypad and the six LEDs as a display or wire up a TTY. It also supported saving and loading from cassette and paper tape, all built-in to the standard ROMs.

I have a couple KIM-1s and they are the oldest machines in my personal collection, including a Revision A pre-Commodore MOS unit with ceramic processor and RRIOTs, but the one that's the most special to me is the briefcase Revision D system you've seen here in other entries. The Revision D is notable historically as the first Commodore-branded KIM after their 1976 buyout, but it's important to me because this unit was my first KIM, and the one we got in high school from our high school math teacher and learned to program it over the weekend (we'd grown up with the Commodore 64, so we already knew all the machine language opcodes). It conveniently sits in a briefcase with a power supply and has one of Bob Applegate (RIP)'s I/O boards to provide the RS-232 connection.

While working on our most recent KIM-1 project, I noticed that the RAM from $0280 to $02bf wasn't working right. The serial uploads from KIMup would succeed, but the data it stored in that range was wrong, and when I checked with the monitor it would only store values 0-3. I got around the problem by assembling the code to a different address, but on a system with a single kilobyte of memory, you can't ignore a whole 32-byte failure. It was time for a Refurb Weekend.

The KIM-1 that sounds like Stephen Hawking (or: "jitbanging" DECtalk)

My 1976 briefcase Commodore/MOS KIM-1, a 1 MHz single-board computer with a 6502 CPU and 1K of RAM, has learned to talk — with a familiar-sounding voice.

The KIM-1's serial lines are connected to the last and smallest member of Digital Equipment Corporation's true DECtalk hardware speech synthesizers, the 1994 DECtalk Express. The DECtalk's classic default voice heard in this video is Perfect Paul, which (with adjustments) was the voice of Dr Stephen Hawking as produced with the 1988 Speech Plus CallText 5010.

The 15 keys we can read off the KIM's hexadecimal keypad are polled by a "talker" program that sends the DECtalk Express words and phrases to speak. However, although the KIM-1 has 20mA current loop output you can turn into RS-232 serial, its built-in ROM routines can't reliably communicate at the 9600 baud rate the DECtalk Express demands.

So, in today's entry, we have a veritable smorgasboard of geriatric geekery: using our KIM-1 serial uploader to push a program for execution, let's write a bitbanged 9600 baud serial transmitter routine in 6502 assembly and let the KIM-1 have its say — and crack the DECtalk Express open and look at the insides while we're at it. (Teaser: you'll find its CPU very familiar.)

Instruction fusion and a real serial port for your virtual KIM-1: The Incredible KIMplement 0.3

Everyone should have the retrocomputing experience of a 1976 1MHz MOS 6502 single-board computer with 1K of memory, six hex digit LEDs and a keypad. One of the earliest such systems and one of the least expensive, you program the KIM-1 in 6502 assembly language right on the keypad in hexadecimal and it's amazing what you could do with a system that little. You could even hook up a cassette deck and an external terminal and have a full system for just a few hundred dollars; MOS Technology (and later Commodore) consequently sold a ton of them. We first experienced the KIM-1 in high school and having grown up with Commodore 64s and 128s it was like meeting their long-lost little brother. We spent the whole weekend typing in hex opcodes and learned how to bang on the hardware and make it do surprising things in a space that small. That's the very unit in the picture, still in my possession, and over four and a half decades old it still works.

While I now personally own four KIMs (an MOS Revision A, plus a Commodore Revision D, a Commodore Revision G and this Commodore Revision F, my first), it's naturally more convenient to develop on an emulator and then test on the real thing. The KIM is such an easy system to understand that there are other KIM-1 emulators like it, but this one is mine. And the Incredible KIMplement runs on a Commodore 64, so anyone can run it on just about anything that can emulate a Commodore 64, or even a real Commodore 64.

However, I also think the KIMplement is a darn handy emulator if I do say so my darn self. It naturally supports the keypad and hex LEDs, and loads and saves memory like every other basic KIM-1 emulator, but it also supports a virtual teletype on the Commodore 64's console (the MAME driver still can't do that) and implements a true KIM-4 expander with 16K of total addressing space.

But new in this version, and the only emulator that currently supports it so far, is you can now redirect the virtual KIM's TTY to the Commodore 64 user port as a real physical serial connection: a physical serial port for your virtual KIM-1. The picture shows a real Commodore 128D running the emulator, connected to minicom on my Linux workstation over USB serial from the 128's userport at 300 baud. From the Linux machine's perspective it's practically indistinguishable from my real Revision F unit, and on Commodore 64 emulators that support it (like VICE), you can tunnel the emulated 64's user port over a TCP socket to give your virtual KIM an Internet connection — we'll demonstrate that below. Plus, this means your virtual KIM can now call out to the real world as well as in! (What can you do with that? Stay tuned for a future entry!)

What the KIM-1 really needs is bubble memory (plus: 20mA current loop for fun and profit)

It seems like everything has flash. Flash mobs, flash photography, Flash Gordon, flash memory. (Other than the past couple years, of course, which haven't been very flash.) And, because solid-state-all-the-things, you can get flash storage devices for tons of classic computers where even the tiny microcontroller in the SD cards is probably more powerful than the systems they're being interfaced to. Why, you can even connect one to an MOS KIM-1, the famous mid-1970s MOS 6502 single-board computer. Now at last you don't need to rekey everything in or screw around with an audio recorder.

But, of course, if you've read this blog for any period of time you know I don't go in for that sort of new-fangled nonsense around here. I like my retrocomputing frivolities period-correct. What the KIM-1 really needs as a mass storage medium ... is bubble memory.

KIMdle: Sorta-Wordle for the KIM-1

UPDATE: I'm trying to solve a debouncing bug for someone who reported it, though I can't reproduce it. If you have a similar issue on real hardware, please try the version up now.

Wordle mania (trademark, probably, of the New York Times) continues. My wife and I, who bonded over word games and later got married because that's how you pick a good life partner, play daily on a private instance, except that she's 19 hours ahead so she has to be careful not to give out spoilers. Retro has gotten into the action. There are Wordle ports for Windows 3.1, Palm Pilots, Game Boys and at least three versions for the Commodore 64, such as this, this and this poop themed one called Turdle, ha ha ha.

Still, however, while these ports ditch dependence on JavaScript and HTML, they still rely on other modern conveniences such as, you know, a screen, a keyboard, and multiple kilobytes of RAM.

You see where I'm going with this.

The Incredible KIMplement 0.2b: a KIM-1 emulator for the Commodore 64 (and the Superkim)

As I manage to eke out a little more time now for personal projects, since TenFourFox is coming to a close and the OpenPOWER JIT is developing at record pace, it's time to dust off some older items I've really neglected. This last week I started by updating the Incredible KIMplement, my MOS/Commodore KIM-1 emulator for the Commodore 64.

No, that's not a joke. The KIMplement runs real KIM-1 code using a software 6502 core I've christened "6o6" (6502-on-6502). 6o6 implements protected memory, exception handling and all legal NMOS instructions. In addition, the KIMplement not only emulates those famous six seven-segment LEDs and the hex keypad, but also is one of the few KIM-1 emulators that emulates a TTY connection (an old-school ASR-33) and a KIM-4 expander with 16K of RAM, allowing you to run "big programs" too.

The KIM-1 is one of the earliest single-board computers, at least in the sense we conceive of them today. It was introduced in 1976 as an enticement for engineers to play with the MOS Technology 6502 which was then the cheapest microprocessor on the market. MOS had just gotten its pants sued off by Motorola, who did not like the prospect of an inexpensive drop-in replacement for their 6800 CPU; the MOS 6501 was completely pin- and bus-compatible, and where the 6800 cost $179 the 6501 was priced at just $25. The "lawsuit compatible" 6502 was just as cheap, but because the pins had been rearranged, couldn't be substituted without additional design work. The KIM-1 provided a platform for engineers to become more accustomed with the 6502, featuring a 1MHz CPU, 1K of RAM, cardedge I/O, a keypad, LEDs and in-ROM support for teletypes, punch tape and cassette tape, for only $245.

MOS expected this would be a low-volume item mostly of interest to circuit designers. Instead, hobbyists bought them in large numbers because it was easily the least expensive microcomputer you could purchase at the time. With a KIM-1 at its center, you could have a full system with teletype, power supply and cassette storage for around $500. No other system came close to competing on cost. When Commodore Business Machines bought the ailing MOS in 1977, they wisely kept producing the KIM-1 until 1979 even after the introduction of the PET. Several clone systems exist, most notably including the Synertek VIM-1/SYM-1, as well as one unusual clone I'll talk about in a moment. I am the proud owner of four KIMs (including an original pre-Commodore KIM-1) and they all work.

I don't know if KIMplement's CPU core could be truly considered "virtualizing" the 6502, but it's more than just a naïve emulation. Rather than manually setting results and flags, the core looks at the guest instruction and runs the same instruction (or a safe variant) in the core context so that all the side effects, in particular changes to the status register, occur "for free." There is no way that a Commodore 64 at 1.0225MHz (or, worse, 0.978MHz for PAL) can do full-speed emulation of a KIM-1 running at 1MHz, but because there is much less code running per instruction, I think this scheme is probably near the fastest way a 6502 can run "untrusted" 6502 code. In practice it is about 35-50 times slower than native code, and this upsets programs that use tight timing or cycle counts, but it's still absolutely enough to actually "do things."

What sorts of things? Besides a couple LED-based games (originally Jim Butterfield's version of Lunar Lander, and I also added the misère game variant Black Match) and toy applications, you can run Tom Pittman's Tiny BASIC in the TTY, and with the bug fixes in 0.2b now you can successfully run FOCAL-65:

This screenshot in VICE shows the emulated 64 running a full FOCAL-65 program to manually compute square roots using Newton's method. It takes it a few seconds to do each iteration, but it all works. This is also a good demonstration of the FOCAL programming language itself including its unusual "floating point" line numbers (actually module and line), which it inherited from its more complex ancestor JOSS.

For this version of the emulator (0.2b), I finally finished some performance improvements to the CPU core that had been gestating in my mind for literally years -- the last version of the KIMplement was released in 2006! -- and also fixed a problem with the TTY emulation where typing characters could get out of sync under CPU load. It can still drop keystrokes if you overflow the Kernal keyboard buffer, but it's a lot smoother generally. I also worked around a bug in VICE where, if you try to load files from a directory on the host machine, the RENAME-the-file-to-itself test used to check for the file's presence doesn't work (a real 1541 would respond with error 63 FILE EXISTS but VICE says 0 OK).

The other bug I fixed was caused by the CPU core, but can't be fixed in it. The 6502 has a decimal flag which can be set in the status register and causes add and subtract instructions to operate in binary coded decimal (e.g., $90 - $01 normally is $8F, but in BCD mode it's $89). Famously, or perhaps infamously, the Commodore 64 Kernal IRQ doesn't turn off the decimal flag, and there is at least one SBC in the normal execution path. Because 6o6 executes instructions for their side effects, if a program had previously set the decimal flag (and this is not at all uncommon in KIM-1 code) it needs to be on for those math operations. The usual solution is to turn on the interrupt flag first with SEI to suppress IRQs while decimal mode is on, but the normal state of guest code is to have the interrupt flag clear because the KIM-1 doesn't have this problem. If an IRQ hits right that moment, the IRQ will be executed with the decimal flag on, and possible unexpected behaviour could result.

This is an extremely infrequent occurrence, but in a long-running system "infrequent" is a synonym for "inevitable." This can't be efficiently solved in the core because there is no atomic method for controlling two flags at once. A better solution is very simple: we just make a patched IRQ that clears the decimal flag explicitly, and calls the normal Kernal IRQ. I did the same for NMIs as a belt-and-suspenders approach.

The eventual goal is to open-source the KIMplement, and in particular 6o6, but I want to have another demonstration application for 6o6 as well before I do. A small multitasking general-purpose kernel sounds like an ideal way to show off how it works.

On my main KIM-1 site I also put in a few words about the microproducts Superkim. This 1979 variant of the KIM-1 was developed in Redondo Beach by Paul Lamar, who had been using KIM-1s for automotive performance testing but was unsatisfied with their expansion capacity. Unlike the hobbyist audience of the KIM-1, the Superkim is all business. The unit in my possession was clearly in a card cage; the hex keypad was never even fitted. It uses a custom board rather than a modified KIM-1 with sockets for RAM, ROM and up to four 6522 VIAs (this unit has 4K of static RAM and a Rockwell R6502P), and sports a full prototyping breadboard on-unit. But its most noticeable (and, I might add, intimidating) characteristic is the 200 gold wirewrap pins penetrating the board:

I have no idea what the sam heck this board was doing, but it clearly did something major in whatever its application was. Don't ask me to power this thing up because I'm worried I'll short something out somewhere. I don't know how many of these were ever sold and Commodore and MOS seem to have had nothing to do with its development.

Of the clones I find the Superkim the most interesting. While many people mention the Rockwell AIM-65 as a clone (my unit is above), and it is strongly based internally on the KIM-1, its substantial expansion (wide alphanumeric LED screen, full keyboard, printer) would not make it generally recognizeable as such. I think the Synertek VIM-1/SYM-1 are more characteristic, though that is one unit I don't personally possess.

In the future, and hopefully that future isn't in another 15 years, I want to add actual cassette support (right now you just dump memory to and from disk) and maybe support for one of the hi-res video boards like the Visable. It may also be worth trying to port the KIMplement to a faster 6502-based system like the Commodore Plus/4 or the Commodore 128 in 80-column mode, or maybe even the Apple IIgs, though all of these would need a solution for the sprites I currently use for the LEDs. (Okay, you Atari freaks, I know, I know.) The KIM-1 is a great little machine and surprisingly capable. The fact all of mine have survived over four decades proves they don't make them like they used to.

You can download a .d64 or .sdas of the Incredible KIMplement and its demo applications, or read more about the KIM-1.