Peripherals

Blocks in the SAPHO/ folder that sit beside a processor, in the Verilog top level you write: they are not generated from a program, you instantiate them and wire them to the processor’s pins. Each one has a testbench under Scripts/hw/ that the regress runs.

block

what it is

the program reads or writes it with

myFIFO

a buffer of words, one clock

out() on one side, in() on the other

myDCFIFO

a buffer of words between two clocks

out() on one side, in() on the other

myKeyPS2

a PS/2 keyboard, characters ready

cade_sync(k)

myVGAText

a VGA text screen, 80 x 30 characters

toma_sync(k, w)

FIFOs: myFIFO and myDCFIFO

When a program produces a buffer of words for another (or for other logic), a FIFO between an output port and an input port lets the writer go on without waiting for each word to be taken.

  • myFIFO: one clock. Ports clk, sclr, data, wrreq, full, q, rdreq, empty, almost_empty, usedw; parameters WORD, LENGTH, ALMOST. It holds LENGTH - 1 words.

  • myDCFIFO: two clocks, ports in the style of the Quartus dcfifo: aclr; wrclk, data, wrreq, wrfull, wrusedw on the writer’s side; rdclk, rdreq, q, rdempty, rdalmost_empty, rdusedw on the reader’s. It holds LENGTH words (a power of two); a word shows up on the reader’s side 2 to 3 reader cycles after it is written. Hold aclr for a few cycles of the slower clock.

In both, the word on data is stored in the cycle wrreq is 1, q shows the oldest word, and rdreq moves to the next. Wired to two SAPHOs (as the regress does in Compilers/CMMComp/Tests/FIFO):

// writer: out() on port 0
fifo_w W (.clk(clk_a), .rst(rst_a), .out(w_out), .out_en(w_en));
myDCFIFO #(.WORD(16), .LENGTH(16)) D (.aclr(rst),
    .wrclk(clk_a), .data(w_out), .wrreq(w_en[0]), .wrfull(full),
    .rdclk(clk_b), .rdreq(r_req[0]), .rdempty(empty), .q(q));
// reader: in(1) is the empty flag, in(0) takes the oldest word
assign r_in = r_req[1] ? {15'd0, empty} : q;
fifo_r R (.clk(clk_b), .rst(rst_b), .in(r_in), .req_in(r_req), .out(r_out), .out_en(r_en));

The reader waits with while (in(1)) { } and takes a word with x = in(0);. A writer that may outrun the reader reads the full flag the same way before each out().

Checked by Scripts/hw/tb_fifo.v and Scripts/hw/tb_dcfifo.v.

Character codes: keyboard and screen

The keyboard and the screen share one table of codes, so a program can pass what cade_sync() returns straight to toma_sync(). A code is an int of 8 bits, from -128 to 127, so a program writes the same numbers at any #NUBITS:

codes

what they are

keyboard

screen

0 to 127

ASCII

gives them

draws 32 to 126, obeys 8, 9, 10, ignores the rest

-128 to -97

screen commands

never gives them

-128 clear, -127 cursor; -126 to -97 kept for later commands, ignored now

-96 to -1

the keyboard’s special keys

none yet (arrows, F-keys… later)

always ignored

A code the screen ignores costs the program one toma and nothing else, so an echo loop toma_sync(1, cade_sync(0)); stays correct when the keyboard learns new keys.

Keyboard: myKeyPS2

A PS/2 keyboard read with cade(): the block takes the keyboard’s two wires and hands the program one character per key press, ready to use.

int c = cade_sync(0);     // waits for a key; c is its character

What the program gets. Only presses (holding a key repeats it, the keyboard’s own repeat). Every word is a character: the printable ASCII of the key’s position on the chosen layout, Shift included, or Enter = 10, Backspace = 8, Tab = 9, Esc = 27. Keys without an ASCII character give nothing: the arrows, F1 to F12, the numeric keypad, Caps Lock (only Shift makes capitals), and on ABNT2 the ç, the acute ´ and the diaeresis ¨. ABNT2’s accent keys give the accent itself (~, ^, `), with no composition.

Ctrl. With either Ctrl held, a letter gives its control code, as on a terminal: Ctrl+A = 1 up to Ctrl+Z = 26, with or without Shift (so Ctrl+H, Ctrl+I and Ctrl+J are 8, 9 and 10, the same as Backspace, Tab and Enter). Ctrl with any other key gives nothing.

Parameters.

parameter

default

meaning

LAYOUT

"ABNT2"

"ABNT2" or "US": which symbol each key position gives

NUBITS

32

width of the word cade() returns (the program’s #NUBITS, at least 8)

DEPTH

4

characters the block holds while the program does not read; one more is dropped

CLK_KHZ

25000

the clock in kHz, only to count a 1 ms timeout (a wrong value just changes it)

LINK_SYNC

0

0: the program’s cade_k goes through two flip-flops of the block’s clock, so the processor may be on any clock; 1: the processor on the block’s clock, two cycles less a key

Pins.

pin

direction

connect to

clk, rst

in

the processor’s clock and reset

ps2_clk, ps2_dat

in

the keyboard (inputs only: nothing is sent to the keyboard)

taqui

out

the processor’s taqui_k

dado

out

the processor’s cade_dado_k

cade

in

the processor’s cade_k

tem_tecla

out

optional: 1 while a character waits; to an input port

Wiring, link 0, on the processor’s clock:

nucleo sapho (.clk(clk), .rst(rst), .in(in), .out(out), .req_in(req_in), .out_en(out_en),
              .cade_0(cade_0), .taqui_0(taqui_0), .cade_dado_0(cade_dado_0));

myKeyPS2 #(.LAYOUT("ABNT2"), .CLK_KHZ(25000), .LINK_SYNC(1)) kbd (
    .clk(clk), .rst(rst), .ps2_clk(PS2_CLK), .ps2_dat(PS2_DAT),
    .taqui(taqui_0), .dado(cade_dado_0), .cade(cade_0));

The same in C± and in C++: c = cade_sync(0);. With the block on another clock than the processor, the program uses the plain cade(0) instead, whose link synchronizes the block’s bit on the processor’s side (Several processors), and the block is left at LINK_SYNC 0, which synchronizes the program’s bit on its side. Up to v9.1 the block had no such parameter and took the program’s bit as it came, right only on one clock (GitHub issue #64).

Is there a key? cade_sync(0) waits until a key comes. A program that has other work to do wires tem_tecla to an input port and reads it first:

assign in = tem;                     // port 0: 1 while a character waits
if (in(0)) c = cade_sync(0);         // takes a key only when there is one

Reset. On reset the block’s T bit takes the program’s C bit, so the block can be reset alone, with the processor running, without handing the program a character nobody typed. The queue is emptied.

Clock. The link is a handshake, not a timing, so the processor’s clock does not have to be any particular one: the testbench runs the block at 2 and at 25 MHz. The block samples the keyboard’s 10 to 17 kHz clock, so keep the processor well above that (a few MHz). ps2_clk is filtered: a new level counts only after it holds for 8 cycles of clk (320 ns at 25 MHz), so a slow or ringing edge on the open-drain line does not count twice. CLK_KHZ only sizes the 1 ms after which a frame cut in the middle (noise, a keyboard plugged in with the board on) is forgotten.

Size, measured with Quartus 24.1 on a Cyclone IV E (DE2-115), DEPTH 4: 294 logic elements and 99 registers, no memory bits. The queue stays in flip-flops: the read is registered, so a synthesizer may use a memory block, but Quartus keeps memories this small in logic.

An 8-bit processor is enough: a character fits in 8 bits. The regress runs the block on two SAPHOs with #NUBITS 8 (Compilers/CMMComp/Tests/KEYPS2): a C± one on a US keyboard and a C++ one on an ABNT2 keyboard, both echoing cade_sync(0) to a port. In C++ the word width is #pragma yanc nubits 8. With the screen block, a whole keyboard-and-screen system fits in an 8-bit SAPHO too (regress pass VGATEXT).

Checked by Scripts/hw/tb_keyps2.v: every key of both layouts with and without Shift, releases, extended keys, a bad parity, a cut frame, a full queue, frames whose ps2_clk rings at every edge, Ctrl with both Ctrl keys, tem_tecla, a reset of the block alone. Design and decisions: design/ps2-keyboard.md.

Screen: myVGAText

A VGA text screen written with toma(): 640 x 480 at 60 Hz, 80 columns by 30 lines of 8 x 16 characters, white on black, with a blinking underline cursor. The program sends one word at a time, and the block shows it.

toma_sync(1, 'A');        // writes A at the cursor
toma_sync(1, -128);       // clears the screen (the program waits until it is done)

The words.

words

effect

32 to 126

the character, at the cursor; the cursor advances (past column 79, the next line)

10

column 0 of the next line

8

the cursor back one column, a space written there; nothing at column 0

9

the next column that is a multiple of 8

-128

clear: the whole screen blank, the cursor at line 0, column 0

-127, line, column

three words: the cursor at that line and column (out of range gives 0)

anything else

ignored: -126 to -97 are kept for later commands, -96 to -1 are the keyboard’s special keys (codes)

A new line from the last line scrolls the screen up: the text moves one line up and the last line comes out blank. The block takes a word only when it can carry it out, and answers the toma only when it is done: one cycle for a character, 80 for a scroll, 2,400 for a clear, and one more for the register the word comes in through. The program never waits on a port of its own, and no character is lost while the screen clears.

A helper in C++, as the regress program Tests/VGATEXT/vga_cpp.cpp does:

void escreve(const char *s) { while (*s) toma_sync(1, *s++); }
void cursor(int linha, int coluna) { toma_sync(1, -127); toma_sync(1, linha); toma_sync(1, coluna); }

Parameters. NUBITS (32): the width of the word toma() sends, the program’s #NUBITS; at least 8 (the commands fit in 8 bits). LINK_SYNC (0): 0 puts the program’s toma_k through two flip-flops of the pixel clock, so the processor may be on any clock; 1, the processor on the pixel clock, saves two cycles a word.

Pins.

pin

direction

connect to

clk, rst

in

the 25 MHz pixel clock, reset (active high; reset also clears the screen; the syncs stay at 1 and the screen dark while it is held)

toma

in

the processor’s toma_k

dado

in

the processor’s toma_dado

valeu

out

the processor’s valeu_k

hs, vs

out

the sync pulses, active low

ativo

out

1 in the visible 640 x 480 window

pixel

out

1 = lit

The board. The outputs are logic, the same on every board; the top of each board maps them to its converter. The DE2-115 (8 bits a colour, an ADV7123 converter):

assign VGA_R = {8{pixel & ativo}};
assign VGA_G = {8{pixel & ativo}};
assign VGA_B = {8{pixel & ativo}};
assign VGA_BLANK_N = ativo;
assign VGA_SYNC_N  = 1'b0;
assign VGA_CLK     = ~clk;           // the 25 MHz pixel clock, inverted
assign VGA_HS = hs;
assign VGA_VS = vs;

The converter latches the colour on the rising edge of VGA_CLK. The block’s outputs change on the rising edge of clk, so with VGA_CLK = clk the converter samples them as they change, with only the routing delays as margin; inverted, it samples them half a period (20 ns) later, in the middle of the pixel. Checked on the board (DE2-115, Dênis, 2026-10): the project sent to him on 2026-10-20, with VGA_CLK = ~clk as above, shows the picture. His earlier project, with the clock not inverted, did too, so on this board both work; the inverted clock is the one with the margin.

A board with a resistor converter (4 bits a colour, say) takes {4{pixel & ativo}} on each colour and only the sync pins.

Clock. The block’s clock is the 25 MHz pixel clock, from a PLL on the board. A processor on that same clock writes with toma_sync(k, w), and the block may take .LINK_SYNC(1); a processor on another clock writes with the plain toma(k, w), whose link synchronizes the block’s bit on the processor’s side, and the block is left at LINK_SYNC 0, which synchronizes the program’s bit on its side. Up to v9.1 the block took the program’s bit and word in the same cycle, right only on one clock (GitHub issue #64).

The font is “Modern DOS” 8x16 by Jayvee Enaguas (CC0 1.0), the ASCII characters only, inside myVGAText.v itself: the block is one file, with no data file to point at. Scripts/gen_vga_font.py writes it from the original font file and says where that comes from.

Size, measured with Quartus 24.1 on a Cyclone IV E (DE2-115), with NUBITS 8: 337 logic elements, 127 registers and 33,184 memory bits (the screen, 2,400 x 7 bits, and the font, 2,048 x 8, both in memory blocks). A whole system with an 8-bit C± SAPHO, myKeyPS2 and myVGAText takes 689 logic elements, with the clock at up to 88 to 100 MHz (three fitter seeds; the keyboard’s table is the limit) for the 25 MHz asked. A 32-bit C++ SAPHO with <iostream>, the two blocks and a PLL takes 3,174 logic elements and runs at up to 27.7 to 28.0 MHz, the limit being the SAPHO’s own float ALU. These were measured before LINK_SYNC; at its default each block has two registers more (not measured).

Why the word goes through a register. The SAPHO puts the toma word straight out of its ALU. Decoded in the same cycle, the SAPHO’s longest path (data memory, float adder, normaliser) and the block’s decode were one path: that 32-bit system ran at 26.2 to 26.6 MHz, 1.8 ns of margin at 25 MHz. The register cuts it there, at one cycle more per word. The word on out also comes straight from the ALU: a block of your own that decodes a toma or an out word, rather than only storing it, should register it first (GitHub issue #7 weighs a register inside the SAPHO).

Reset clears the screen (2,400 cycles). A word the program offers meanwhile waits and is carried out after it. On reset the block’s C bit takes the program’s T bit, so the block can be reset alone without taking an old word for a new one.

Checked by Scripts/hw/tb_vgatext.v: the picture rebuilt from the output pins as a monitor would (the timing, a glyph against the font, the cursor blinking), every word and control code, the codes -126 to -1 ignored, the cursor command, a scroll, a clear and how long each holds the program, the outputs during and after reset, a word offered during the reset’s clear, a reset of the block alone, the screen memory never read past its end. The regress pass VGATEXT runs a C± and a C++ SAPHO of 8 bits, each with a keyboard and a screen, echoing what a simulated keyboard types, and a 32-bit C++ SAPHO that uses <iostream>. Design and decisions: design/vga-text.md.

Text from C++: <iostream> and <cstdio>

With the keyboard on link 0 and the screen on link 1, both on the processor’s clock (the wiring above), a C++ program needs no cade_sync or toma_sync of its own:

#include <iostream>
using namespace std;

int main()
{
    int n;
    cout << "n? ";
    cin >> n;                        // typed with echo and backspace, ended by Enter
    cout << "2n = " << n + n << endl;
    return 0;
}

<cstdio> gives putchar, puts, getchar and fgets. Other links, or blocks on another clock, are set with #define before the #include. The whole list, what cin and cout take and what they cost: The C++ language. Design: design/cpp-iostream.md.