MTX PC Keyboard Interface

Propeller Logic Description  [Courtesy of Bill Brendling]

[Also available as Bill's Open Document format file]

The Propeller chip is a fast 32 bit micro-controller, designed for hardware interfacing, with eight largely independent cores, called "Cogs" in Propeller speak. It can be programmed in assembler, a high level language designed specifically for the chip called "Spin", or in a number of other languages such as C. In designing software for the Propeller it is typical for each cog to be dedicated to a specific task, such as controlling a piece of hardware, and for the cogs to cooperate to implement the entire functionality.

The keyboard interface uses a 6MHz crystal which is multiplied internally by 16, to give a 96MHz clock. This is slightly over-clocking (although fairly common), the Propeller was originally designed for a 5MHz crystal, and 80MHz internal clock. Each of the Propeller cogs can execute one assembler instruction in typically 4 internal clocks. At 96MHz clock, this gives the Propeller, when using all eight cores, the capability of executing 192 instructions per microsecond. For the keyboard interface, the cogs are used as follows:

Master Cog

The propeller always starts by executing code written in Spin on the first cog. This may be a major part of the software, or it may just be initialisation code. In this case it initialises some addresses in memory and then starts a cog for sending diagnostic messages to the programming interface. After outputting an initial diagnostic signature message, the master cog reads the position of the keyboard type jumper. What happens next depends upon the type of keyboard selected.

PS/2 Keyboard

If a PS/2 keyboard is selected, five additional cogs are started (giving seven used in total), running:

• PS/2 interface
• Key matrix mapping
• MTX interface (2 cogs)
• Key map reprogramming  

The function of these cogs are described below.

For the PS/2 keyboard, it would be possible for the master cog to stop at this point. However, for diagnostic purposes it continues to run, and sends key events and remap diagnostics to the diagnostics cog.

USB Keyboard

If a USB keyboard is selected, then six additional cogs are started (using all eight of the Propeller cogs), running:

•  USB driver (2 cogs)
• Key matrix mapping
• MTX interface (2 cogs)
• Key map reprogramming

The USB driver cogs only provide a low level interface to the keyboard. Routines on the master cog use this interface to enumerate and configure the keyboard. The master cog next flashes the keyboard LEDs in sequence (this helps to differentiate USB mode from PS/2 mode which flashes all three LEDs simultaneously).

Having completed keyboard initialisation, the master cog starts a loop, repeatedly polling the keyboard for key status. Any change (a key pressed or released) causes a key event code (7 bit USB key number, plus 8th bit to identify key press or release) to be placed in a first-in, first-out (FIFO) buffer for processing by the key matrix mapping cog. The key event code is also sent to the diagnostic output cog.

The master cog loop also checks the state of the keyboard lock bits (maintained by the mapping cog), and if these have changed, uses the USB driver to update the keyboard LEDs.

PS/2 Keyboard Driver

Much of the code was borrowed from the Propeller Object Exchange. When a key is pressed or released on a PS/2 keyboard, the keyboard sends 1-3 bytes of serial data over clock and data lines to the Propeller. The PS/2 driver cog receives this data and turns it into a one byte event code, with 7 bits identifying the key, and one bit to indicate key press or release. The key codes used are the same as those for USB keys. These event codes are queued in the key event FIFO.

This cog performs two other functions:

• On startup of the cog, it first sends a reset command to the keyboard, so that it is in a known state. This causes the three keyboard LEDs to flash simultaneously. The auto-repeat rate on the PS/2 keyboard is then set to the slowest possible. I would have turned auto-repeat off if that was an option. Note, on the MTX the keys will still auto-repeat, but that is functionality built into the MTX ROM, not the PS/2 keyboard repeat.
• This cog also checks the state of the keyboard lock bits (maintained by the mapping cog), and if these have changed, updates the keyboard LEDs.

USB Driver

The USB driver came from the Parallax forums (http://forums.parallax.com/discussion/121321).

The original version was produced by Scanlime (https://scanlime.org/2010/04/its-alive-bit-banging-full-speed-usb-host-for-the-propeller/). This version supported full speed (12MHz) USB devices only. This version requires the Propeller to be clocked at 96MHz.

The code was subsequently modified by Saucy Solition (https://github.com/SaucySoliton/propeller-usb-host) to also support low speed devices (1.5MHz), and to work with an 80MHz Propeller clock.

The version used for the keyboard interface has been modified slightly from the latter source:

•  Operation with a 96MHz clock has been re-instated (with conditional compilation options).
• The restriction on which propeller pins can be used for the USB interface has been relaxed, although in the end no advantage was taken of this.
• A small amount of diagnostic code was cleaned up.
• Despite these modifications, the author cannot claim anything like full understanding of the operation of this code.

As mentioned earlier, this code provides a low level interface, which in principle can support many types of USB device. Details of the keyboard implementation were copied from (http://forums.parallax.com/discussion/167592/propeller-ansi-vt-100-terminal-with-vga-and-usb-keyboard-support).

Without the efforts of the above referenced authors, who’s work was shamelessly borrowed, USB support would not have been possible.

Key Matrix Mapping Cog

This cog retrieves key events from the FIFO buffer, and updates an in-memory model of the MTX keyboard accordingly. The Propeller code implements eight different mappings between PC keyboard keys and MTX keys, depending upon the state of the shift keys, and scroll-lock and num-lock flags:

• For many keys (such as the letter keys), the translation from PC to MTX key is the same for all eight mappings.
• For some keys (such as the “9” key) the shifted character (open bracket for the “9” key) is on a different key on the MTX keyboard (MTX key “8” for open bracket). So a different translation is used depending upon whether or not shift is down.
• A few symbols (such as equals) have different shift states on the PC and MTX keyboards. Because of the way the MTX scans the keyboard, it is not possible to modify the shift state for individual key presses. Therefore, Andy Key defined (originally for MEMU, see here) alternate keys to press to produce these symbols. By default the Propeller uses the same translations. However, if scroll-lock is selected, most of these symbols are translated to one of the three key matrix positions which don’t have a key on the MTX keyboard. The enhanced ROM in the MTX+ then translates these additional locations to the correct symbols. It is possible to load additional drivers on an unmodified MTX which will also translate these additional locations.
• To maximise usability for games, Andy Key defined for MEMU a mapping for the numeric keypad keys which preserved physical layout. By default the Propeller follows this mapping. However, this results in the shifted keys producing digits other than those displayed on the PC keys. Turning on the num-lock bit, changes the mapping so that shifted keypad keys produces the digits as displayed. Because Andy’s mapping uses the keypad num-lock key for the MTX “Page”/”7” key, the PC “F12” key is used (by default) to toggle the num-lock bit.
• Engaging both scroll-lock and num-lock combines the effect of the two previously described mappings.

It is possible to change any of the mappings, either permanently by changing the mapping tables in the Propeller ROM, or temporarily by re-programming from the MTX as described below.

The translated MTX key has to be remembered so that the correct MTX key can be released on receiving the corresponding key release event.

As well as mapping PC key events to the MTX keyboard matrix, this cog also maps keys to toggle the scroll-lock and num-lock bits, and to generate an MTX reset.

MTX Interface

The MTX Z80 writes the drive lines with one instruction, and reads the sense lines with the very next instruction. With a real keyboard the sense lines update instantly (or at least at the speed of light). The Propeller is significantly faster than the Z80 but updating the sense lines is still a challenge. Earlier versions of the keyboard interface assumed that only one drive line is active at any one time. This is always true for the MTX ROM, but may not be true for all games that implement their own keyboard decoding. The Propeller code used a binary search to identify the active drive line. This enabled the required keyboard row to be selected using only three tests.

Tony Brewer made a number of observations on MEMORUM:

• That it was common, at least on the Spectrum to have multiple sense lines active at the same time, to enable rapid detection of a key press.
• By unrolling the loop it was possible to process multiple sense lines more rapidly than I had appreciated.
• By outputting logic ones for the active keys, rather than logic zeros, it was possible to use the Propeller hardware to combine results from multiple cogs. The Propeller needs output buffers anyway to go from 3.3v logic to 5v logic, and these buffers can be inverting to turn the active ones into active zeros that the MTX expects.

As a result of these comments, the MTX interface now uses two cogs, one of which samples the lower four drive lines and outputs the corresponding sense bits, the other cog sampling the upper four drive lines.

Key Map Reprogramming Cog

As described in the section on the “Key Matrix Mapping Cog”, the Propeller firmware has eight different key mappings built in to provide different compromises for the differences between PC and MTX key layouts. However others may have different preferences, for example Martin wanted the unshifted keypad to produce numbers. Therefore this cog provides the ability to temporarily update the mappings from the MTX. To do this the MTX has to first disable keyboard scanning, so that this is not sending any bytes to the keyboard drive port. It also has to ignore the values on the sense lines while reprogramming is in progress.

 To enable reprogramming, the MTX writes the following four bytes to the scan line port (port 0x05): 0xF0, 0x0F, 0x55, 0xAA. Once enabled, any byte sent to the scan line port with less than two zero bits will disable reprogramming. Typically 0xFF will be used to complete the programming sequence.

Once programming is enabled, a sequence of four bytes is used to update a map position:

If updating multiple mappings, the first three bytes only have to be resent if they have changed from the previous value, This means that the amount of data to be sent can be reduced by:

•  Updating multiple keys with the same drive line
• Updating multiple keys with the same sense line
• Updating keys in the same map, and the adjacent PC key codes (same top two bits)

The following table lists the key event codes used in the Propeller, and are needed for bytes 3 and 4 of the key map reprogramming. These are standard USB key codes, except for 0x64 to 0x6b which have been added to define the various shift keys.

Diagnostic Cog

This cog outputs diagnostic messages in serial format at 115,200 baud, 8 bits, no parity, 1 stop bit. The output is 3.3v TTL on pin 39 (I/O bit 30) of the propeller, which is connected to the programming connector.

The output consists of:

• Firmware identification string, including version number.
• Keyboard type message (USB or PS/2).
• Cog initiation messages.
• USB configuration messages (if appropriate)
• Two digit key event codes, as per table above, with high bit set for key release.
• Eight digit diagnostic codes from the remap cog.

This cog a standard Parallax Propeller object, accessed from driver routines running on the main code. It is also capable of receiving incoming serial characters from the programming connector, although this feature is not currently used.

Firmware Distribution

Parallax Propeller
Version	By	Zip	PCB	Description
180610	WB		1.0	Modified key mapping, added dynamic remapping
180504	WB		1.0	Optimisation of drive line decoding (suggested by Tony Brewer) (Chips U3 & U4 must be inverting buffers, e.g., 7406, 7416) (All future release will be written for inverting buffers)
180429	WB		1.0	Initial release supporting USB and PS/2 keyboards (Chips U3 & U4 must be non-inverting buffers, e.g. 7407, 7417)
MTX "BASIC" ROM (ROM 'B') (Optional)
1.0	MA		1.0	Enables "Scroll Lock" mode without CP/M or SDX

Software

Ver.	Host	Zip	PCB	Description
1.0	CP/M		1.0	Initial release - enables "Scroll Lock" for CP/M (.com)
1.0	SDX		1.0	Initial release - enables "Scroll Lock" for non-CP/M SDX (.run)
1.0	Tape		1.0	Initial release - enables "Scroll Lock" for "tape" users CP/M (.wav) (Currently not tested on real hardware)