A VGA text screen for the SAPHO, written with toma()

Status: implemented 2026-10-20 (SAPHO/myVGAText.v, Scripts/hw/tb_vgatext.v, Scripts/gen_vga_font.py, regress pass VGATEXT); for v9.1; 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), decided (Luciano).

1. Where it comes from

Dênis’s video, done for the DE2-115 (project received 2026-10-19). Facts from his code:

  • vga_sync.v: 640x480 at 60 Hz from a 25 MHz pixel clock, 800 x 525 counts, HS and VS active low; the colour is white or black on the board’s 8-bit converter (ADV7123: vga_clk, blank_n, sync_n).

  • screen_map.v: 80 x 30 = 2,400 character codes, one write port (the SAPHO’s side), one read port (the scan).

  • font_bitmap_rom.v: 256 characters of 8 x 16 pixels, moderndos_8x16.hex (4,096 lines, 32 kbits). Its origin and licence are not known yet.

  • map_cursor.v: three output ports and one input: out(0, c) writes c at the cursor and advances it (\n jumps to the next line, the last line wraps to the top, no scrolling; code 8 is drawn, not a backspace); out(1, line*256 + column) places the cursor; out(2, x) clears, one position per cycle, 2,400 cycles, with busy (= in(0)) high meanwhile, including the cycle of the pulse itself. A character sent while clearing is ignored without notice: the program must wait with while (in(0)).

  • video.v reads the column as col + 2 to make up for the two cycles of the two memories, instead of delaying HS, VS and the active window.

2. Decided

  1. The program talks to the block over a toma link (Luciano, 2026-10-19), as the keyboard does over cade: the SAPHO writes, the block reads and takes a word only when it can carry it out, so a program cannot lose a character while the screen clears and needs no busy port. One channel, so the word itself says what it is.

  2. A command and its arguments, as the old text terminals (Luciano): a word 0 to 127 is an ASCII character; 128 clears the screen; 129 followed by two words, the line and then the column, places the cursor. Works with an 8-bit SAPHO (the keyboard’s minimum too), at the cost of three toma for a cursor move and a state in the block; codes 128 to 255 are commands, so the font’s upper half cannot be written (the keyboard only gives ASCII). A one-word form (0x9000 + line*128 + column) was weighed and needs at least 16 bits.

  3. The screen scrolls, with a top-line register (Luciano): a 5-bit register says which memory line shows at the top; scrolling adds 1 to it (mod 30) and clears the line just freed (80 cycles, the SAPHO waiting in toma); the scan reads memory line (L + top) mod 30 for screen line L. Nothing is copied. Weighed: wrapping to the top (Dênis’s, free, the new text lands over the old) and copying every line up (needs another memory port or contention with the scan, ~2,400 cycles). The cursor command speaks in screen lines; the block adds the offset.

  4. Control characters (Luciano): 10 goes to column 0 of the next line (scrolling on the last); 8 moves the cursor back one column and erases it (writes a space), and does nothing at column 0; 9 advances to the next column that is a multiple of 8 (past 79, the next line); 27 and every other code below 32 is ignored (nothing drawn, the cursor stays), so the font’s symbols in that range cannot be written.

  5. Generic one-bit outputs (Luciano): the block gives hs, vs, an active-window flag and pixel (lit or not); each board’s top maps them to its converter (DE2-115: {8{pixel & active}} on each colour, blank_n = active, sync_n = 0, vga_clk = the pixel clock). The mapping for each board is documented, and tested on the boards at hand.

  6. One clock in the block, the 25 MHz pixel clock (Luciano): the crossing between clocks, when there is one, is the link’s. A SAPHO on the same clock writes with toma_sync(k, ...); a SAPHO on another clock with the plain toma(k, ...), whose synchronizers item 20 built and tested. Corrected 2026-10-30 (GitHub issue #64): those synchronizers are the SAPHO’s, for the block’s bit; the block took the program’s T and word in one cycle, so on another clock it could act on a T whose word had not settled. The block now has LINK_SYNC, default 0: T through two flip-flops of the pixel clock; 1 leaves them out on one clock. Weighed: a single 25 MHz clock for everything (ties the SAPHO to 25 MHz) and two clocks inside the block (the scroll register and the clear state would cross clocks).

  7. The font: “Modern DOS” 8x16 by Jayvee Enaguas, generated by a script in the repository, ASCII only (Luciano). The ROM is built from the original font by a script under Scripts/, its header naming the source and the licence, so anyone can rebuild and check it; Dênis’s .hex has no known provenance. Only the 128 ASCII codes are stored (16 kbits instead of 32): 0-31 and 127 are empty, 128-255 are commands. Licence: CC0 1.0 since version 2018.09.29-1 (OFL 1.1 before), per the font’s own changelog and the AUR package (version 20190101.02, CC0-1.0); the author’s NotABug repository answered 404 on 2026-10-19, so its LICENSE file was not read. If the source taken at implementation turns out not to be CC0, another free 8x16 font (Spleen, BSD; Terminus, OFL) replaces it.

  8. The two-cycle latency is matched by delaying the scan signals (Luciano): the memories are addressed with the plain counters, and HS, VS, the active flag and the pixel’s position inside the cell go through two registers, so everything meets in the same cycle by construction. Replaces Dênis’s col + 2, which made up for the latency only on the memory address (fragile if a latency changes, and two pixels off from the sync at the edges of a line).

  9. A visible cursor: an underline that blinks, always on (Luciano): the bottom two pixel rows of the cursor’s cell are lit, on and off about twice a second (a frame counter on VS). In hardware, in the scan: a compare of the cell being drawn with the cursor, a 5-bit counter, a gate on the pixel; no memory, no command, nothing for the program to do. Dênis’s newer version (seen in his 2026-10-19 video, code not sent) has a blinking block cursor; weighed: no cursor, a block, and hide/show commands 130/131.

  10. Monochrome (Luciano): a character is lit or not, white on black on the DE2-115 mapping; the output stays the one-bit pixel of decision 5. Weighed: one colour for the whole screen (a register, a command, 3-bit RGB out) and a colour per character (3 to 6 more bits a cell, 7.2 to 14.4 kbits more memory). Colour can come later without changing the codes 0-131.

  11. Name SAPHO/myVGAText.v, module myVGAText (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 #4):

  1. The code ranges, shared with the keyboard (refines decision 2): 0-127 ASCII; 128-159 screen commands (128 clear, 129 cursor, 130-159 kept for later commands, ignored now); 160-255 the keyboard’s special keys, which the screen ignores for good. An echo loop stays correct when the keyboard learns new keys.

  2. The screen memory’s read address is held at 0 outside the visible window. In the blanking the cell counters run to column 99 and line 32, and the address went up to 2,579 in a memory of 2,400: unspecified on a synthesizer, x in simulation.

  3. The outputs are reset: hs and vs at 1 (inactive), ativo and pixel at 0, and the two pipeline stages that feed them, so the monitor sees no stray sync while the reset is held.

  4. On reset C takes the program’s T, and a word offered during the reset’s clear waits for it. Before, C went to 0 and the end of the clear flipped C whenever T != C: a word the program offered in the first 2,400 cycles after a common reset was answered without being carried out (lost). Now the clear ends without touching C when the reset, not a word, asked for it (fword). Found in the audit, beyond the list Luciano approved, as the same defect class as the keyboard’s decision 17.

  5. On the DE2-115, VGA_CLK = ~clk is recommended (refines decision 5): the ADV7123 latches on the rising edge, the block’s outputs change on the rising edge of clk; inverted, the converter samples in the middle of the pixel. Checked on the board (Luciano, 2026-10-27): the project sent to Dênis on 2026-10-20, inverted, shows the picture on his DE2-115; his own earlier project, not inverted, did too. Not compared with Terasic’s demo.

  6. The link is read through a register (Luciano, 2026-10-20: “resolver o problema da queda de frequência”; GitHub issue #6). The SAPHO’s toma word comes straight out of its ALU, so the block decoding it in the same cycle joined the SAPHO’s longest path to its own decode. Surveyed on the DE2-115 project for Dênis (32-bit C++ SAPHO with <iostream>, both blocks, PLL; Quartus 24.1, three seeds each): as it was 26.15 / 26.29 / 26.57 MHz; A, T and the word registered at the input, 27.99 / 27.68 / 27.92 MHz (+32 LEs, +33 registers); B, the decode on the low 8 bits plus a “high bits zero” flag, 26.19 MHz (no gain); A and B, 27.11 MHz. A was taken. With it the worst path ends at the new register, level with the SAPHO’s own path to its accumulator. One cycle more per word; the SAPHO holds its word while it waits (checked by the regress pass VGATEXT, three real SAPHOs).

  7. The codes are an int of 8 bits, -128 to 127 (Luciano, 2026-10-28, refines decision 12: “quem tem que mudar é o periférico”). 128 does not fit the int of an 8-bit SAPHO, and C± is to stop on a literal past the word (GitHub issue #14), so toma_sync(1, 128) would no longer compile at 8 bits. The commands are now -128 (clear) and -127 (cursor), -126 to -97 kept, and the keyboard’s special keys -96 to -1: at 8 bits the same bits as before. The block compares the whole word with the command sign-extended to NUBITS, so a program writes -128 at every width; a 32-bit word 128 is no longer a command. Weighed: keeping 128 and writing it 0x80 at 8 bits (a program would change with its width), and accepting decimals up to 255 at 8 bits (a change to C± for one peripheral).

3. Specification (approved 2026-10-20, as implemented)

Parameter. NUBITS (32): width of the word toma sends (at least 8). The timing is fixed: 640x480 at 60 Hz, the clock is the 25 MHz pixel clock.

Pins.

pin

dir

to

clk, rst

in

the 25 MHz pixel clock, reset active high

toma

in

the SAPHO’s toma_k (its T bit)

dado [NUBITS]

in

the SAPHO’s toma_dado

valeu

out

the SAPHO’s valeu_k (the block’s C bit)

hs, vs

out

sync pulses, active low, aligned with pixel

ativo

out

1 in the visible 640x480 window

pixel

out

1 = lit

What the program writes. toma_sync(k, w) (the SAPHO on the same 25 MHz clock) or toma(k, w) (another clock), one word at a time:

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 (past 79, the next line)

0-31 others, 127

ignored

-128

clear: 2,400 spaces, cursor at (0, 0), the top register at 0

-127, line, column

the cursor at that screen line and column; out of range gives 0

-126 to -97

ignored (kept for later commands, decisions 12 and 18)

-96 to -1

ignored for good (the keyboard’s special keys)

“The next line” from the last screen line scrolls: the top register goes up by one (mod 30) and the line it frees is cleared (80 cycles).

Inside.

  1. Scan: two counters (0-799, 0-524), HS/VS/active from them.

  2. Screen memory: 2,400 x 7 bits (ASCII needs 7), one write port, one read port, both on clk. The scan reads line (L + top) mod 30.

  3. Font ROM: 128 x 16 lines x 8 bits, read registered; its contents generated by a script under Scripts/ from Modern DOS 8x16 and written into myVGAText.v itself, so the block is one file with no path to a data file.

  4. HS, VS, active and the pixel’s position in its cell delayed two cycles, to meet the two memories (decision 8).

  5. Cursor: an underline in the bottom two pixel rows of its cell, blinking with a frame counter (decision 9).

  6. Link: when T != C and the block is idle, it takes dado, carries the word out (after the cycle of its input register: one cycle for a character; 80 for a scroll; 2,400 for a clear) and only then flips C, so the SAPHO waits in toma meanwhile. A command with arguments (-127) takes three words; the block remembers which one comes next.

Tests. Scripts/hw/tb_vgatext.v: words in through the link as the SAPHO sends them, then: the screen memory and the cursor after characters, control codes, clear, cursor moves, a scroll; the timing (800 x 525, the pulse widths and positions); the rendered pixels of some cells against the font; the cursor’s blink. A regress pass with a C+- and a C++ SAPHO of 8 bits writing text. Board check on the DE2-115 with Dênis.

4. What was measured and changed while building it

  • The font: the .hex in Dênis’s project is this very font: its 1,520 rows of the codes 32-126 equal the rasterized Modern DOS 8x16 of release 20190101.02, taken from the read-only mirror github.com/notpeter/ ttf-moderndos at commit 2dfa3241 (the original NotABug repository was down), whose LICENSE is CC0 1.0. Scripts/gen_vga_font.py checks the file’s sha256 and writes the ROM into the .v.

  • The font ROM written as a case with a registered output stayed in logic on Quartus 24.1 (the block took 1,299 LEs); written as an array filled in an initial block and read through a register, Quartus put it in two M9K blocks and the block fell to 324 LEs, 118 registers, 33,184 memory bits. A whole 8-bit system (C± SAPHO, myKeyPS2, myVGAText, PLL) on the DE2-115: 629 LEs, Fmax 97.8 MHz for 25 MHz. After the v9.1 changes (2026-10-20, one seed, VGA_CLK = ~clk): the block 332 LEs, 118 registers; the system 692 LEs, 100.4 MHz. With decision 17 (input register), three seeds each: the block 337 LEs, 127 registers; the system 689 LEs, 88.5 / 92.9 / 92.5 MHz, against 100.4 / 91.1 / 88.4 MHz for the block without it. The limit in all six is the keyboard’s table (frame -> ch): the 100.4 MHz above was one lucky seed.

  • The screen memory is written through a register, one cycle after the block flips C: harmless for the SAPHO (the writes go in order, the program never reads the screen back); the testbench checks one cycle later.

  • Mutation-checked: the sync not delayed (1,916 errors), a scroll that does not clear the new line, a clear that releases the SAPHO at once, a backspace that writes another character: all four caught.

  • v9.1, mutation-checked (2026-10-20): without the hold at 0 the testbench sees reads at 2,400 and up; with the old reset (C to 0, the clear ending on new_word) the word offered during the reset’s clear is lost.

  • Quartus warns, for a tiny program, that the SAPHO’s memories are deeper than their .mif files (data 4 against 3 words, instructions 16 against 11); the rest is set to 0. Seen here, not studied (TODO).

5. For the documentation (issue #40)

Written: docs/peripherals.md, section “Screen: myVGAText”; v9.1: the code table shared with the keyboard (section “Character codes”), reset, the inverted VGA_CLK.