I’ve written several times about Yellowstone’s need for in-system FPGA reprogramming. Once the Yellowstone card is in the user’s hands, the user needs a way to update the FPGA firmware when new versions are released, without requiring a JTAG programmer or some kind of USB interface built into the card. The current Yellowstone prototype was designed to support in-system FPGA programming, but it had never been tested until today. The photo here shows a BASIC program on an Apple IIe successfully communicating with the FPGA’s SysConfig port and reading its device ID. I’ve verified that 01 2B A0 43 is the expected ID for the Lattice MachXO2-1200HC FPGA on the Yellowstone board, so everything looks correct. It will still be a long road from here to reach the point where the FPGA is actually reprogrammed, but this proves that the basic communication mechanism works, which was the part I was most concerned about.

Yellowstone’s in-system programming support doesn’t require any extra hardware on the board, which is great! It’s all implemented through PCB routing, connecting the right signals to the right pins. The MachXO2 FPGA supports communication with its built-in SysConfig hardware through many different interfaces including JTAG, I2C, and a Wishbone interface implemented in the FPGA logic, but I’ve chosen to use the SPI interface. This is a “hard” SPI port, so reconfiguration and reprogramming via SPI should work even if the FPGA is in a fubared state or is completely blank.

How do you connect the Apple II peripheral bus to the SPI port, in a way that avoids accidental transitions on the SPI I/O signals, but allows for full bidirectional SPI I/O when needed? Here’s how I did it.

CS: The SPI SysConfig port has a chip select input pin, which is normally high, leaving the SPI port disabled. As long as CS remains high, it doesn’t matter what’s happening on the other SPI I/O signals, and the FPGA will ignore it. The CS input is connected to another FPGA pin that’s normally in a Hi-Z state, but that can be driven low by FPGA logic. This makes it possible to programmatically enable the SPI port by having the Apple II CPU write a magic value to a special address, which the FPGA logic watches for, in order to drive CS low. For situations where the FPGA is blank or in a bad state, the programmatic enable may not work. In this case there’s also a hardware jumper on the PCB that can be used to force CS low.

DI: The data input is address line A0.

CLK: The SPI clock is the Apple II /DEVSEL signal. This means an SPI data bit will be clocked into the FPGA from A0 whenever there’s a low-to-high transition on /DEVSEL. This signal is normally high, but it goes low for about 500 ns whenever the Apple II CPU makes a memory reference to the “device” region of the peripheral card’s memory. For Yellowstone, this region is where the virtual IWM lives, in address range $C0E0 to $C0EF (assuming the card is in slot 6).

DO: The data output from the SPI port is connected to another FPGA input pin. Yellowstone’s FPGA logic includes a special behavior that makes use of this. If the SPI port is enabled and the CPU reads from address $C0EA or $C0EB, the FPGA will return the SPI DO bit that it sampled on its other pin, rather than the normal return value from the IWM.

If this last piece sounds somewhat complicated, it is. The DO bit needs to get on the data bus somehow, so that the CPU can read it. But DO can’t be directly connected to the 5V data bus – it must connect somewhere on the 3.3V side in the Yellowstone logic, and then the ‘245 bus driver must be enabled at the proper time to drive the DO value onto the 5V bus. The ‘245 enable timing is under control of the FPGA logic. That means when the FPGA is blank or in a bad state, there’s no ‘245 enable, so there’s no way for the CPU to read DO. In short, a correctly-configured FPGA is a requirement for reading DO. Without this, the program running on the Apple II will need to proceed with blind SPI communication in which it can send data but not receive it. Fortunately this seems to be sufficient to perform FPGA reprogramming. I don’t see any way around this inability to read DO when the FPGA is blank without adding extra hardware to Yellowstone, which I’m loathe to do for such a rare situation. So be it.

When all of this is put together, the SPI communication looks like this: The CPU writes a magic value to a special address to force CS low. Then it begins a series of reads from $C0EA or $C0EB. Every read from $C0EA transmits a 0 bit because A0 is 0, and every read from $C0EB transmits a 1 bit. In either case, D7 of the byte that’s read is the reply bit from the SPI port. The rest is all software to transmit the correct bit sequences and make sense of the replies.

Now onward to the FPGA datasheet, where I can learn what sorts of magic SPI incantations are required to actually reprogram this thing.

The Yellowstone disk controller’s whole reason for existence is its ability to control any type of Apple II disk drive, but for a few Apple II programs, this universality causes problems. Yellowstone handles standard 5.25 inch drives just fine, but some software gets confused when it doesn’t find the ROM for a standard Disk II Interface Card in slot 6. For these rare cases, Yellowstone has an option to enable a “compatibility mode” where it emulates a plain vanilla Disk II Interface Card without any extra bells and whistles. The question is how does the user enable compatibility mode?

In the current version of the Yellowstone prototype, the choice is determined by a DIP switch. But as I’ve been refining the design, I’ve developed a strong dislike of DIP switches. They’re big and awkward, and not at all user-friendly. I’ve already managed to find ways to eliminate two of the four DIP switches on the board, and if I can find another solution for enabling compatibility mode then I can eliminate a third DIP switch.

My first thought was to check the keyboard immediately after the computer is powered-on, before loading anything from the disk. If the ‘C’ key is held down (c for compatibility), I could enable compatibility mode, otherwise I could proceed normally. On the Apple II it’s easy to check for keypresses by examining memory address $C000. If there’s a keypress waiting, the MSB will be 1 and the lower seven bits will hold the ASCII value of the key. So I could check for the value $C3 ($80 plus $43) and everything would be peachy.

Unfortunately, I quickly discovered that one of the first things the Apple II ROM does after a reset is to clear the keyboard buffer. This happens before control is transferred to Yellowstone’s ROM, so by the time my code checks the keyboard buffer, it’s too late. What to do?

 
Rely on the Buffer’s Lower Bits

From testing on my Apple IIe, the keyboard buffer isn’t actually zeroed when it’s “cleared”. The MSB is set to 0, but the other seven bits still retain the ASCII value of the key. So perhaps my code could just check $C000 for $43 instead of $C3 to detect the ‘C’ key, and it would work as originally intended.

This seems slightly dubious, since I’m not sure if this is documented behavior, or if other models of Apple II will clear the keyboard buffer in the same way. There’s also a small bug this introduces: if ‘C’ was the last key typed, and you then turn off the computer and turn it on again within 1-2 seconds, $C000 will still hold the value $43 during power-up. This may lead to accidentally detecting non-existent keypresses and enabling compatibility mode when the user didn’t intend to.

 
Delay Booting and Poll the Buffer

Another option is for Yellowstone to sit in a busy loop after the computer is first powered-on, and continuously poll the keyboard buffer looking for the value $C3. If the keyboard has a key repeat behavior, then $C3 will appear in the buffer after roughly 0.75 seconds if the ‘C’ key is continuously held down. Or the user could be instructed to quickly tap-tap-tap the ‘C’ key when the computer is powered-on, instead of holding it continuously down. This would eliminate any dependency on the keyboard’s key repeat behavior. At least one modern Apple II peripheral card uses this method.

The main drawback of this approach is that it would introduce a busy-waiting delay every time the computer is turned on. To reliably detect a key repeat or a tap-tap-tap, Yellowstone would need to insert a startup delay of about one second, every time the computer powers-on or resets. It sounds like a small thing, but I think I’d find this delay very annoying. Furthermore, the key repeat behavior might not work on the original Apple II or Apple II+ keyboard, so tap-tap-tap is probably the only reliable solution.

 
Check the Open Apple Key

A third alternative is to check whether the Open Apple key is held down, instead of the ‘C’ key or any other standard key. The behavior of the Open Apple key is very different from the other keys. Open Apple is just a duplicate of the first button on the first game controller, and its current status can be read at memory address $C061. As long as Open Apple is held down, the MSB of $C061 will be 1.

The Closed Apple key works identically, and its state can be read at address $C062. But holding the Closed Apple key during power-up will trigger the Apple II’s built-in diagnostics, so that key isn’t a good candidate for triggering Yellowstone behavior changes.

For now I’ve implemented Yellowstone’s compatibility mode enable using the Open Apple key, and it works well on my Apple IIe. Unfortunately, earlier models of Apple II computers don’t have an Open Apple or Closed Apple key. Users with those computers would need to attach a game controller and press its button during power-on, which is far from ideal. There’s also a risk that some other third-party peripheral cards might use Open Apple in the same way, which would make it impossible to trigger Yellowstone’s compatibility mode without also affecting the other card. But I don’t know of any specific cards that use Open Apple, so maybe I shouldn’t be concerned.

 
Something Else

I could stick with the DIP switch, despite its awkwardness. Or I could ask users to perform some voodoo in the Apple II monitor, and write a magic value to a special address in the card’s memory to enable compatibility mode. Or some other solution I haven’t thought of yet. Opinions?

I’ve fallen into a deep hole involving current-limiting circuits and current sources, in an attempt to solve a minor problem with the Yellowstone disk controller. In the big scheme of things, this isn’t a very important problem, but it has me intrigued. I’ve created a simulation of a circuit that may solve the problem, but it exhibits some transistor behavior that I don’t understand. Specifically, the base currents of the transistors don’t seem to follow the rules that I thought I understood.

You can see a working simulation of the circuit here.

The are two SPDT switches at the top of the diagram, representing Yellowstone’s two disk connectors. On pin 9 of this connector, some types of drives will have a 10K resistor connected to the +12V supply. This type of drive needs a -12V supply input on pin 9. It will use about 3 mA at most from -12V. Other types of drives will have a direct connection to +5V on pin 9 (+5V is also provided on pin 11 to all drive types). Yellowstone can either provide an additional +5V supply on pin 9 for this type of drive, or more simply, just leave the pin unconnected.

The basic idea here is to establish a current limiter of about 10-20 mA for pin 9. That’s more than enough for normal operation with the -12V supply, and it prevents dangerously high amounts of current flowing if -12V is directly connected to +5V as in the second type of drive.

Here’s the puzzle: the three NPN transistors have all their bases connected, and all their emitters connected. As shown, they all have the same base-emitter voltage Vbe of 0.668 volts. My mental model is that the base-emitter connection is essentially like a diode. With identical diodes, identical Vbe, and a single shared 470 ohm current-limiting resistor, I would expect the base current Ib to be identical for all three transistors. Yet they’re not. The middle transistor’s Ib is 7.2 mA while the others are only 0.165 mA.

The fact that one transistor is in saturation must be relevant. But the “base-emitter connection is a diode” assumption is failing here, and I can’t explain why. I need to read more transistor theory.