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 |
|---|---|---|
|
a buffer of words, one clock |
|
|
a buffer of words between two clocks |
|
|
a PS/2 keyboard, characters ready |
|
|
a VGA text screen, 80 x 30 characters |
|
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. Portsclk,sclr,data,wrreq,full,q,rdreq,empty,almost_empty,usedw; parametersWORD,LENGTH,ALMOST. It holdsLENGTH - 1words.myDCFIFO: two clocks, ports in the style of the Quartusdcfifo:aclr;wrclk,data,wrreq,wrfull,wrusedwon the writer’s side;rdclk,rdreq,q,rdempty,rdalmost_empty,rdusedwon the reader’s. It holdsLENGTHwords (a power of two); a word shows up on the reader’s side 2 to 3 reader cycles after it is written. Holdaclrfor 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 |
|---|---|---|
|
|
|
|
32 |
width of the word |
|
4 |
characters the block holds while the program does not read; one more is dropped |
|
25000 |
the clock in kHz, only to count a 1 ms timeout (a wrong value just changes it) |
|
0 |
0: the program’s |
Pins.
pin |
direction |
connect to |
|---|---|---|
|
in |
the processor’s clock and reset |
|
in |
the keyboard (inputs only: nothing is sent to the keyboard) |
|
out |
the processor’s |
|
out |
the processor’s |
|
in |
the processor’s |
|
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 |
|---|---|---|
|
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) |
|
in |
the processor’s |
|
in |
the processor’s |
|
out |
the processor’s |
|
out |
the sync pulses, active low |
|
out |
1 in the visible 640 x 480 window |
|
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.