The Card That Wouldn't Boot CP/M

A few months ago I taught a modern circuit board to pretend to be a 1980 Apple display card, and the card worked. Then I got a report that it stopped an operating system from booting. This series is about chasing that down, and the first thing you need is a little context about the board.

The board is called the A2FPGA. It is an open-source project, principally Ed Anuff’s, and I am one of the contributors. A real Apple ][ from the early 1980s had a row of slots inside it, and you filled those slots with expansion cards: a card for a clock, a card for more memory, a card for an 80-column screen, and so on. The A2FPGA replaces that whole stack with one board built around a chip called an FPGA. An FPGA is a chip you can rewire in software to behave like almost any other circuit, so a single board can stand in for many different vintage cards at once, on real hardware you plug into a real Apple. My additions to the project include a clock card, a handful of timing fixes, and the one that matters here: a re-creation of the Videx Videoterm.

The Videoterm is an 80-column display board from 1980. The original Apple ][ could only show 40 columns of text across the screen, all of it uppercase, which was fine for games and for typing in BASIC programs but cramped for real work. The Videoterm doubled that to 80 columns and added lowercase, which is what made the machine usable for word processing and spreadsheets. My re-creation, running on the A2FPGA, emulated the Videoterm hardware and ran the card’s actual built-in software, and it worked. Eighty columns, real lowercase, the cursor blinking right where it should.

Then I received a bug report I did not want. Microsoft Z-80 SoftCard CP/M would not boot with the A2FPGA when my 80-column emulation was enabled. CP/M was the serious business operating system of that era, the thing you ran to do actual work, and on an Apple it needed a second processor on a plug-in card to run at all. With the Videoterm active, you would turn the machine on, the disk drive would spin and chatter, and then nothing. No prompt, no error, no first line of text. A dead machine. Disable the Videoterm 80-column emulation and CP/M started up fine, albeit in 40-column mode.

My first thought was the obvious one. The variable appears to be the Videoterm emulation, and it’s relatively new. That’s very likely where the bug is.

The cast

A quick word on the players, because there are a few names here and I will use them throughout.

The Apple ][ is a small home computer first sold in 1977 and still in wide use into the early 1980s, built around a processor called the 6502. CP/M was the business operating system of that era, but it needed a different kind of processor, a Z-80, which the Apple did not have. Microsoft solved that by selling the Microsoft Z-80 SoftCard, a board you plugged into the Apple that added a Z-80 CPU and let the machine run CP/M. The Videoterm was the 80-column display card you added on top of all that. A well-equipped 1981 desk had all three at once: the Apple, the SoftCard so it could run CP/M, and the Videoterm so CP/M had a proper 80-column screen. Sadly, that combination would not boot.

Not my bug

While I was looking for my bug, a new report came in. The same failure happens when using a real, physical Videoterm board instead of my emulated one. Apparently my emulation of the hardware was so true to the actual hardware that CP/M failed to boot with either one. No searches on the Internet uncovered any discussion of such a failure. It seems like something someone would have noticed “back in the day.”

That left me with a question. Why does adding a display card stop an operating system before it can print a single character?

There was a second piece that made it stranger. The failure only happens in 80-column mode. Run the same setup in plain 40-column mode and it boots fine. But in that mode, the Videoterm isn’t being used. Pointing the finger back towards it. Microsoft SoftCard CP/M version 2.20 was the failing version. I found a later version, SoftCard CP/M version 2.23. That version boots to the A> prompt with the Videoterm in 80-column mode - both the hardware Videoterm and my emulation of it. Something changed between those two releases. But what, and why? And, somewhat related, can I update my emulation such that it works with the 2.20 failing version?

How this went

Answering those questions wasn’t an easy task. This series is where I work it out. I am going to assume you have never touched an Apple ][ or used CP/M, and I will introduce every piece as it comes up. The story stays at the level of what the machine was doing and why, rather than the individual bytes. If you want the low-level details, I provide two companion series that dive deep. I’ll point you to them at the end.

Along the way I built two tools I am glad to have, and I had a lot of help building them. The help came from Claude, an AI coding assistant. It was a tireless builder but a very poor detective, and that combination shaped the whole hunt. Claude could build almost anything I described, far faster than I could by hand, and it is the only reason a side project got this far. More than once, however, it would state a conclusion (really just a hypothesis) as fact. And, when questioned, back up its ‘conclusion’ with test cases showing its ‘correctness’. Only my refusal to accept its hypothesis eventually led me to the actual bug. More on these false starts coming up.

What is coming

Four parts, in order, no Apple ][ knowledge assumed.

• Part 2, The Answer That Agreed With Itself: the fast, confident, wrong explanation, and why the test built to prove it could only ever agree.
• Part 3, Two Right Parts, One Dead Machine: the real reason the machine hangs, and the answer to whether my emulation owed anyone a fix.
• Part 4, Two Tools and a Whole Distribution: how chasing one bug turned into rebuilding the entire operating system from readable source.

Those are the four parts. It starts with me being wrong about my own card.