A PS/2 keyboard block for the SAPHO, read with cade()

Status: implemented 2026-10-19 (SAPHO/myKeyPS2.v, Scripts/hw/tb_keyps2.v, regress pass KEYPS2); checked on the board by Dênis in his keyboard + VGA example (Luciano, 2026-10-27). Marks: fact (read in code or measured), deduced (to be checked on a board), decided (Luciano).

1. Where it comes from

Dênis (IC student) has a SAPHO on a DE2-115 reading a PS/2 keyboard and writing on a VGA text screen (project received 2026-10-19). Facts from his project:

  • The keyboard path is in Verilog: two-flop synchronizer, 11-bit frame with start/parity/stop check, a 16-byte FIFO; the SAPHO polls in(1) (queue not empty) and reads in(2) (oldest scancode, popped by req_in[2]).

  • The program (C++) turns scancodes into characters: the F0 (release) and E0 (extended) prefixes, the Shift state, Caps Lock as a toggle, two 132-entry tables (lower/upper case).

  • Fact (code reading, not tried on the board): his E0 handling skips the byte after E0, so a release E0 F0 5A (keypad Enter) loses the F0 and 5A arrives as a press: releasing keypad Enter prints a newline.

  • Fact (measured with yanc 8.0): the two tables cost 819 of the 1,012 instructions (cppcomp fills initialized arrays with code, three instructions per element, zeros included) and 264 data words: about 3/4 of the processor’s memory.

2. Decided

  1. A block in SAPHO/, like myFIFO.v: on one side the PS/2 pins, on the other the cade link pins (taqui, cade_dado, from the SAPHO cade). The program reads a key with c = cade(k); (Luciano).

  2. The block delivers the character ready: Shift, E0/F0 and the table live in the hardware, “a circuit takes care of whatever it can” (Luciano). The program does not parse scancodes.

  3. The layout is a parameter, LAYOUT = "ABNT2" (the default, Luciano) or "US" (Luciano, 2026-10-19; replaces “only the keys common to both”, decided earlier the same day: without ; : / ? [ ] { } ' " | \ ~ ^ and the backquote, nobody can type a C program). Each key gives the symbol of its position on the chosen layout. ABNT2’s accent keys give the symbol itself, no composition (~, ^, `). Characters outside ASCII (ç, ´, ¨) give nothing, by decision 6. Deduced: the ABNT2 positions below are from memory of the layout, to be checked on a real ABNT2 keyboard.

    scancode

    US

    US + Shift

    ABNT2

    ABNT2 + Shift

    0E

    `

    ~

    '

    "

    36 (6)

    6

    ^

    6

    none (¨)

    54

    [

    {

    none (´)

    `

    5B

    ]

    }

    [

    {

    4C

    ;

    :

    none (ç)

    none (Ç)

    52

    '

    "

    ~

    ^

    5D

    \

    |

    ]

    }

    4A

    /

    ?

    ;

    :

    61 (ISO, beside Z)

    \

    |

    \

    |

    51 (ABNT2 only)

    none

    none

    /

    ?

    Every other key of the list (letters, digits, - _ = + , < . >, space, Enter, Backspace, Tab, Esc, the other shifted digits) is the same on both.

  4. Burst is not needed here (issue #18): a few tens of scancodes per second; the handshake matters, not the rate.

  5. Presses only: a release never reaches the program, and there is no parameter to ask for releases (Luciano). Holding a key repeats it, by the keyboard’s own typematic repeat.

  6. Keys without a character are dropped, for now (Luciano): arrows, F1-F12, Home/End/Delete and the layout-dependent keys of decision 3 never reach the program. Every word cade() returns is a character: printable ASCII, or Enter = 10, Backspace = 8, Tab = 9, Esc = 27. Delivering them later (a marker bit with a key code was proposed) does not change the words a program gets today, only adds new ones.

  7. No Caps Lock, for now (Luciano): the key is ignored, only Shift gives capitals. No hidden state, nothing sent back to the keyboard: the PS/2 pins stay inputs and the block has no transmitter. (Caps Lock with its LED needs the host-to-device command ED, open-drain inout pins and a transmitter about the size of the receiver; Dênis has one, ps2_tx.v.)

  8. The numeric keypad is dropped, for now (Luciano): only the digit row types digits; the keypad keys (and keypad Enter, E0 5A) give nothing. (Its / * - + are where they are on both layouts: an easy addition.)

  9. Name SAPHO/myKeyPS2.v, module myKeyPS2 (Luciano).

  10. Queue size: parameter DEPTH, default 4, read synchronously (Luciano, 2026-10-19; first 16 with an unregistered read). Measured on the DE2-115: 16 characters read without a register took 128 flip-flops and the block 364 LEs, as much as the SAPHO; with a registered read the synthesizer may put the queue in a memory block when there is memory to spare, and DEPTH 4 keeps it at a few registers when there is not.

  11. A full queue drops the new character (Luciano): what was typed first arrives whole, the excess is lost until the program reads.

  12. A frame timeout (Luciano): ps2_clk still for about 1 ms in the middle of a frame restarts the bit count, so a lost bit (noise, a keyboard plugged in with the board on) costs one byte, not every byte until reset. Hence the parameter CLK_KHZ, to count 1 ms.

  13. The block runs on the SAPHO’s clock, read with cade_sync(k) (no link synchronizer): the case tested and documented as the default (Luciano). A block on another clock works with the plain cade(k), the same block. Corrected 2026-10-30 (GitHub issue #64): the plain cade(k) synchronizes only the block’s bit, on the SAPHO’s side, and the block took the program’s C straight into its queue logic. The block now has LINK_SYNC, default 0: C through two flip-flops of its clock; 1 leaves them out on the SAPHO’s clock.

  14. Claude writes the block, its testbench and the whole-processor test; Dênis gets it tested and explained step by step, and checks it on the board (Luciano).

Added for v9.1, after an audit of the block (Luciano, 2026-10-20: “implement everything you suggested”; what was left for later is in GitHub issue #3):

  1. ps2_clk is filtered: the synchronized wire must hold a new level for FILT = 8 cycles before it counts (320 ns at 25 MHz; the keyboard holds each level 30 us at least). The lines are open drain with pull-ups; a slow or ringing edge crossing the threshold twice made an extra falling edge, one bit too many, the frame lost. Replaces the plain edge detect of item 1 of the specification (Dênis’s).

  2. Ctrl gives control codes: either Ctrl (left 14, right E0 14) held, a letter gives 1 to 26 (Ctrl+A = 1), Shift or not; Ctrl with any other key gives nothing. Ctrl is the second state after Shift; still nothing is sent back to the keyboard (decision 7).

  3. On reset T takes the program’s C (t <= cade, nothing offered): resetting the block alone while C = 1 made T != C at once, and the program read a character nobody typed.

  4. An output tem_tecla = the queue is not empty, for an input port: the program asks “is there a key?” without blocking in cade_sync.

  5. The codes are shared with the screen: 0-127 ASCII; 128-159 screen commands, never from the keyboard; 160-255 for the keyboard’s special keys (arrows, F-keys, later; decision 6), which the screen always ignores. Today the block gives 1-127 only. Since 2026-10-28 the codes are an int of 8 bits: the commands are -128 to -97 and the special keys -96 to -1, the same bit patterns, and the block sign-extends its word (vga-text.md, decision 18).

3. Specification (as implemented)

File and module. SAPHO/myKeyPS2.v, module myKeyPS2 (name: Luciano), beside myFIFO.v/myDCFIFO.v.

Parameters. NUBITS (32): width of the word handed to cade(), the character zero-extended. DEPTH (4): characters the queue holds. CLK_KHZ (25000): the clock, only to size the frame timeout below.

Pins.

pin

dir

to

clk, rst

in

the SAPHO’s clock and reset (one clock)

ps2_clk, ps2_dat

in

the keyboard (inputs only: nothing is sent back)

taqui

out

the SAPHO’s taqui_k (the block’s T bit)

dado [NUBITS]

out

the SAPHO’s cade_dado_k

cade

in

the SAPHO’s cade_k (the program’s C bit)

tem_tecla

out

optional, to an input port: 1 while the queue is not empty

What the program writes. c = cade_sync(k); (same clock, no synchronizer); plain cade(k) also works. The word is always a character: a-z, A-Z with Shift, 0-9, the shifted digits but ^, space, - _ = + , < . >, Enter = 10, Backspace = 8, Tab = 9, Esc = 27, and 1-26 for Ctrl+letter (decision 16).

Inside, in order.

  1. Two flip-flops on ps2_clk/ps2_dat; ps2_clk filtered (a level counts after 8 cycles, decision 15) and its falling edge taken from the filtered level.

  2. Receiver: 11-bit frame, start/parity/stop checked, a bad frame dropped (as Dênis). New: a timeout (no ps2_clk edge for about 1 ms restarts the bit count), so one lost bit cannot shift every later frame; Dênis’s receiver has none.

  3. Decoder: remembers F0 (next code is a release) and E0 (next code is extended), the two Shift keys and the two Ctrl keys held. A release only clears Shift or Ctrl; an extended key, a keypad key, Caps Lock and every key outside the list give nothing. The E0 F0 5A case of section 1 is handled by keeping both flags.

  4. Table: a ROM, scancode -> (character, character with Shift), 0 = none.

  5. Queue of DEPTH characters; a character arriving with the queue full is dropped.

  6. Link: while the queue is not empty and T == C (the last word was taken), put the oldest character on dado and flip T; when C flips back to T, pop it. dado holds still while T != C. On reset T takes C (decision 17).

Tests. Scripts/hw/tb_keyps2.v: PS/2 frames in (bit timing as a keyboard), the link driven as CAD does, characters checked out: every key of the list with and without Shift, E0 keys and the E0 F0 5A release, releases, a bad parity, a lost bit (timeout), a full queue; since v9.1 also frames whose ps2_clk rings at both edges (glitches of 2 cycles), Ctrl (Ctrl+c = 3, Ctrl+Shift+a = 1, Ctrl+h = 8, Ctrl+1 and Ctrl+Enter nothing, right Ctrl E0 14), tem_tecla with the queue full and empty, and a reset of the block alone with C = 1. A regress pass runs it. Then a whole-processor case: a C+- and a C++ program that echo cade_sync(0) to out(0), with the block in the testbench top. Board check on the DE2-115 with Dênis.

4. What was measured and changed while building it

  • The queue was first read without a register: 16 characters took 128 flip-flops and the block 364 LEs. With a registered read and DEPTH 4: 233 LEs, 92 registers (Quartus 24.1, Cyclone IV E). Quartus keeps memories this small in logic (“uninferred due to inappropriate RAM size”), at 4 and at 16; the registered read lets a synthesizer choose.

  • A guard against reading a stale word in the cycle a word is written was written, then removed: the testbench passed without it, and the reason is structural (the program reads dado only after T flips, one cycle after the queue changes at the earliest).

  • Quartus refuses a "\\" string escape that Icarus accepts: the backslash and the double quote are 8'h5C and 8'h22 in the table.

  • Dênis’s project rebuilt with the block, yanc 8.0 and a 25 MHz PLL for everything: 7,792 -> 831 LEs, Fmax 53.4 MHz (was 67.6 MHz at 50 MHz with no .sdc), the worst path inside the SAPHO.

  • An 8-bit echo found a processor defect unrelated to the keyboard: the port number was cut to the data-address width (fixed in 849f5cc).

  • v9.1, mutation-checked (2026-10-20): with FILT = 1 (no filter) the ringing frames decode wrong (5 errors); with the old reset (t <= 0) a reset of the block alone hands the program a phantom character.

  • v9.1 refit of the DE2-115 system (2026-10-20, one seed): the block went from 233 LEs / 92 registers to 294 / 99 (filter, Ctrl). With Ctrl written as k - 96 the worst path of the whole system became the table plus that subtraction (frame -> ch, Fmax 88.0 MHz); taking the letter’s low 5 bits instead (a = 0x61) brought it to 100.4 MHz. That was one seed: three seeds later gave 88 to 100 MHz, the table still the limit (vga-text.md, section 4).

5. For the documentation (issue #40)

Written: docs/peripherals.md (pins, parameters, the words cade() returns, the key list, wiring, the clock, the size, 8 bits); v9.1: the code table shared with the screen, Ctrl, tem_tecla with its wiring, reset, the filter.