P8X Glossary — acronyms & signals¶

A reference for the abbreviations, signal names, and register/bus terms used across the P8X project. Authoritative sources where a term has one: - control word / opcodes → microcode/genucode.py - bus pinout → hardware/backplane/p8x-bus-definition.md - monitor/BIOS ABI → docs/p8x-monitor.md - parts → hardware/p8x-bom.csv (from generators/gen_bom.py)

General abbreviations¶

Term	Meaning
P8X	The project: a hand-built 8-bit microcoded TTL CPU (~130 74HCT chips, 8-slot DIN 41612 backplane) — and, since 2026-08, the same microarchitecture on an FPGA.
FPGA	Field-Programmable Gate Array. The `fpga/` track implements P8X on one, running the same microcode; a parallel build, not a replacement for the TTL cards.
RTL	Register-Transfer Level — the Verilog description of the hardware in `fpga/rtl/`.
co-sim	Co-simulation: running the same program on the RTL and on the C emulator and diffing their per-cycle architectural state. The emulator is the golden model, so a divergence names an exact microcycle. `fpga/sim/run.sh`.
BSRAM	Block RAM — the FPGA's dedicated on-chip memory blocks (46 of them on the GW2AR-18), used for the microcode ROM and the 64K main memory.
Tang Nano 20K	The Sipeed board the FPGA build targets: Gowin GW2AR-18, 27 MHz, onboard USB-JTAG/UART bridge and microSD slot.
SPI	Serial Peripheral Interface — how the FPGA build talks to the microSD, behind the same `$FF10..$FF17` CF task file the BIOS already drives.
ISA	Instruction Set Architecture — the opcodes/registers a programmer sees.
ABI	Application Binary Interface — the fixed binary contracts (entry addresses, layouts, conventions) that let separately-built code interoperate. See the BIOS jump table, the TPA, SBUF/LBA.
API	Application Programming Interface — the source-level contract (vs ABI, the binary one).
BIOS	The monitor's published service routines (jump table at `$0100`).
TPA	Transient Program Area — RAM where `run`-loaded programs and the OS's `>`-redirect buffer live. `$5900`–`$F7FF` (~39.8 KB; base dropped `$6A00` → `$6300` → `$6100` → `$5900` over 2026-09-13/14 as scratch relocated, most recently into the $1800–$1FFF island the 6 KB ROM freed).
BOM	Bill of Materials — the orderable parts list (`hardware/p8x-bom.csv`).
DNP	Do Not Populate — a footprint laid down on the board but left unstuffed (provisioned for later).
DRC	Design Rule Check — the EDA tool's electrical/clearance verification of a routed board.
THT / SMD	Through-Hole Technology / Surface-Mount Device. P8X is all THT.
NOS	New Old Stock — obsolete parts bought new from old inventory (e.g. the 6850, 74181).
R/A	Right-Angle (connector mounting orientation).
LSB / MSB	Least / Most Significant Byte (or Bit).
TTL / HCT	Transistor-Transistor Logic; 74HCT = high-speed CMOS, TTL-compatible levels (5 V).

Registers & pointers¶

Name	Meaning
A	Accumulator — ALU operand A and primary result register.
B	Operand register — the ALU's second (B-side) operand.
T, T2	Microcode scratch byte registers. `T` is also selectable as the ALU B operand via BSEL (rev C); `LDT` loads it.
P0–P3	The 4×16-bit pointer bank. P0 = PC (program counter), P3 = SP (stack pointer, empty-descending from `$FEFF`); P1/P2 are general pointers.
PT	Hidden microcode-only scratch pointer (PSEL=4), used for absolute addressing; not programmer-visible.
PT2	Second hidden scratch pointer (PSEL=5, rev D), the write cursor for `MOVW` (16-bit mem→mem move); not programmer-visible. Adds no bus line (PSEL is already 3 bits).
IR	Instruction Register — holds the current opcode.
FLAGS	The 4-bit status register (C, Z, N, V).

Flags¶

Flag	Meaning
C	Carry. Conventional active-high (rev B): `C=1` = carry-out (ADD) / no-borrow i.e. `A≥B` (SUB/CMP). Unsigned ordering.
Z	Zero — result was 0.
N	Negative — result bit 7 set.
V	Overflow — signed arithmetic overflow (rev C). Valid after ADD/SUB/CMP. Signed ordering uses `N^V`.

Microcode control word (32 bits)¶

The word burned to the 4× 28C64 EPROMs and interpreted by the emulator. Bit map (authoritative: genucode.py); each bit is latched in control-card pipeline U14–U17 and, where needed, routed across the backplane.

Bits	Signal	Meaning
0–3	DOE	Data-Output Enable — which source drives the data bus (idle/A/B/T/T2/ALU/FLAGS/MEM/PTRL/PTRH).
4–7	DLD	Data-LoaD — which destination latches the bus at the clock edge.
8–10	PSEL	Pointer SELect (P0–P3 + PT=4 + PT2=5; 3-bit since rev B).
11	PINC	Increment the selected pointer.
12	PDEC	Decrement the selected pointer.
13–16	ALUS	74181 ALU function select S0–S3.
17	ALUM	74181 mode (M): logic vs arithmetic.
18	CIN	Carry-IN pin to the 74181 (active-low carry).
19	SH0	Shifter: shift left.
20	SH1	Shifter: shift right.
21	LDF	Latch Flags — load all four flags from the ALU.
22–24	FCOND	Condition-mux select for branches: never/always/C/Z/N/V/LT/LE.
25	µRST / URST	Microcode reset — step counter → 0, ends the instruction.
26	HALT	Gate the clock off (resume via front panel / reset).
27	LDZN	Latch Z,N from the bus on loads (without touching C/V).
28	SHCIN	Shifter shift-in = current C (rotate-through-carry).
29	SETC	Force C = 1 (SEC).
30	CLRC	Force C = 0 (CLC).
31	BSEL	ALU B-input mux select (rev C): 0 = B register, 1 = T register.

FCOND conditions: LT = N^V (signed A<B), LE = (N^V)|Z (signed A≤B).

Backplane bus signals¶

(Full pin map: hardware/backplane/p8x-bus-definition.md.)

Signal	Meaning
D0–D7	8-bit data bus (one driver per microcycle).
A0–A15	16-bit address bus (always driven by the register-bank card's selected pointer).
DOE0–3 / DLD0–3	The encoded DOE/DLD fields, broadcast on the bus; each card decodes its own codes.
PSEL0–2, PINC, PDEC, ALUS0–3, ALUM, CIN, SH0/1, LDF, LDZN, SHCIN, SETC, CLRC, BSEL	Control signals (see the control-word table) routed control-card → consuming cards.
FC, FZ, FN, FV	The four flag lines, ALU card → control card (read by the condition mux).
CLK, CLKB	System clock and its complement (CLKB = "CLK-bar"; write strobes gate on it).
-RES / RES̄	System reset, active low.
IRQ	Maskable interrupt request (rev C, B29; controller is DNP).
SPARE11	Uncommitted bus line on B30.
SPARE12–SPARE23	12 uncommitted bus lines on the even row-B pins B4,B6,…,B26 (rev D; the odd B pins stay GND guards).

Naming: a leading - (or overbar) means active-low (e.g. -RES, -RD, !OE).

Memory map & BIOS ABI¶

Term	Meaning
EEPROM	`$0000–$17FF` (6 KB; shrunk from 8 KB 2026-09-14 to free the $1800–$1FFF RAM island) — monitor + BIOS at `$0000` (~4.9 KB used). BASIC is no longer ROM-resident; it runs as the disk program `/bin/basic.bin`.
SRAM / RAM	`$2000–$FEFF` (56 KB, rev E — 2× 62256).
SBUF	512-byte sector buffer at `$1D00` (in the $1800–$1FFF RAM island; was `$6100`, then `$5E00`). Fixed by the BIOS — `CFWRITE` reads from it.
LBA	Logical Block Address — the CF sector number; the BIOS reads the target LBA from fixed bytes at `$1F47`–`$1F49` (`LBA`/`LBA1`/`LBA2`).
RBUF	The OS's `>`-redirect capture buffer (= the TPA base, `$5900`).
CONIN / CONOUT / CONST	BIOS console in / out / status (`$0100/$0103/$0106`).
CFINIT / CFREAD / CFWRITE	BIOS CompactFlash init / read-sector / write-sector (`$0109/$010C/$010F`).
CFSEL / CFCURDRV / DRVSEL	Dual-volume drive select: `CFSEL` (`$0148`, `A`=0/1) routes sector/FS I/O to that CF card via the `DRVSEL` byte (ORed into `CFHEAD` as the ATA device-select bit); `CFCURDRV` (`$014B`) reads the current drive. Two cards share the `$FF10` task-file port.
PUTS / PHEX8	BIOS print-string / print-byte-as-hex (`$0112/$0115`).
GCLS	BIOS clear-the-glass-TTY + home-cursor (`$014E`) — the on-screen text console of two-mode operation. A no-op when no GL card is fitted.
two-mode operation	The same OS runs headless over serial OR as a GL graphics desktop, auto-selected at wake by the `GFXPRES` flag. See `docs/p8x-two-mode-design.md`.
glass TTY	The on-screen text console: with a GL card, `CONOUT` MIRRORS every byte onto the display via stroke `TEXT` as well as the serial port — so the ROM monitor, the OS and every program are on the LCD. On by default whenever a card is fitted (the monitor switches it on and installs the font at wake); `screen off` disables it for a session.
GFXPRES / GCONEN / GTSUSP	The two-mode flags at `$1FA4`/`$1FAF`/`$1FA7`: GL card present / glass-TTY console enabled / console suspended because a full-screen program owns the screen. Generated in `generators/gen_memmap.py`.
2nd ACIA	The second 6850 serial port at `$FF08`/`$FF09` (status/data), register-identical to the console ACIA — added for two-mode operation; the `kermit` command transfers files over it while the console keeps `$FF04`. Emulator: `-2i`/`-2o`.

Filesystem (P8XFS) & OS¶

Term	Meaning
P8XFS	The P8X File System on CompactFlash. v2 (hierarchical: directories-are-files, `.`/`..`, paths) is the only format; v1 (flat directory) has been retired.
boot block	LBA 0 — signature, version byte, OS sector count, free pointer.
extent	A file/directory's contiguous run of data sectors.
PACK	Compaction — reclaim the gaps left by deleted files by sliding extents down.
fsck	Filesystem consistency check — host tool `p8xfs.py fsck` (exhaustive) and the on-target OS `fsck` command (read-only quick check).
F_FILE / F_DIR	Directory-entry flag bytes: regular file ($01) / subdirectory ($02). ($FF = deleted.)
OS / monitor / BASIC	P8X/OS (disk shell), the ROM monitor (`$0000`), and the integer BASIC interpreter.

Components & chips¶

Part	Role
74181	4-bit ALU slice (×2 for 8-bit), with 74182 carry-look-ahead.
74HCT00/02/08/32/86	NAND / NOR / AND / OR / XOR quad gates (generic 14-pin).
74HCT10/30	Triple-3-input NAND / 8-input NAND.
74HCT138/139	3-to-8 / dual 2-to-4 decoders (field decode, port/load select).
74HCT151	8:1 mux (condition mux).
74HCT157 / 257	Quad 2:1 mux (157) / with tri-state (257) — shifters, B-mux, readback.
74HCT161	Binary counter (clock divider, baud, step counter).
74HCT169	Up/down counter — the pointer-bank building block (16 of them).
74HCT175 / 7474	Quad / dual D flip-flop (flag register; C-flag FF; sync).
74HCT244 / 245	Octal buffer / bus transceiver.
74HCT260	Dual 5-input NOR (bus zero-detect for Z).
74HCT374 / 377	Octal D register (pipeline latches; output port; A/B/T/T2).
6850 (ACIA)	Asynchronous Communications Interface Adapter — the serial UART (console, 9600 8N1).
MAX232	RS-232 line driver/receiver (logic ↔ ±12 V).
28C256 / 28C64	Parallel EEPROM — program ROM ($8000-class) / microcode ROMs.
62256	32K×8 SRAM.
DS1302	Serial real-time clock (rev C, DNP).
DIN 41612	The 96-pin backplane connector standard. FABC96R = the card-edge connector part; the backplane has the mating receptacles.
CF / IDE	CompactFlash storage in 8-bit True IDE mode (`$FF10–$FF17`).

Generator footprint & device codes (`generators/gen_eagle.py`)¶

Code	Meaning
DEV	Device table — logical pin names + pin→pad map + package, per part type.
PKG	Package table — pad geometry (name, x, y, drill, dia) per footprint.
DIP8/14/16/20/24W/28W	Dual In-line Package, N pins. `W` = wide (0.6″ row spacing).
SIP9/16	Single In-line Package (resistor networks).
DIN96 / DIN96C	DIN 41612 96-pin: backplane receptacle / card edge connector (the `C` variant carries the FABC96R mounting holes).
HDR3/4/40	0.1″ pin headers, N pins.
TB4	4-position terminal block.
LED5 / LEDARR8	3 mm LED footprint / 8-segment LED bar array (DIP).
OSC4	Full-can oscillator (4-pin DIP-style).
SW2P / SW2	2-pin switch footprint / device (RESET/RUN/STEP).
RNISO8	Isolated 8-resistor network (SIP).
R_AXIAL	Axial-lead resistor.
C_DISC / CP_RADIAL	Disc ceramic cap / radial polarised (electrolytic) cap.
MEM28K8	The wide memory footprint shared by the 28C256 EEPROM and 62256 SRAM.
GATES14 / HEX14	Generic 14-pin quad-gate (74HCT00/08/32/86) / hex inverter (74HCT14).
MHn	Mounting Hole — non-plated mechanical hole (e.g. on `DIN96C`).
CDn	The per-IC 100 nF decoupling Cap, one beside each chip (`CD1`, `CD2`, …).
Un / Jn / Xn	Reference designators: IC / connector / crystal-or-oscillator.
busnet() / mnet() / card() / fp_box()	Generator helpers: bus-pin→net map / memory-card net add / build-a-card / footprint bounding box.

Hardware register / protocol bits¶

Bit	Meaning
RDRF	ACIA Receive Data Register Full — a byte arrived (read `$FF04` status).
TDRE	ACIA Transmit Data Register Empty — OK to send the next byte.
RW / RS / CS / E	ACIA Read/Write, Register Select, Chip Select, Enable control lines.
BSY	CF/IDE Busy — drive is processing; poll before access.
DRQ	CF/IDE Data Request — drive ready to transfer a data word.
DRDY / DASP / PDIAG / IORDY	CF/IDE drive-ready / drive-active-slave-present / passed-diagnostic / I/O-ready.
PC / SP / MAR	Program Counter / Stack Pointer / Memory Address Register — the classic roles, all subsumed by the P0–P3 pointer bank here (no separate MAR).
UART	Universal Asynchronous Receiver/Transmitter — the serial-port role the 6850 ACIA fills.

Graphics display (`$FF20-$FF2F`)¶

Same device whether it is inside the FPGA P8X or on a bus card, so one command set and one golden model (gpu_* in emulator/p8xemu.c) serve both.

Term	Meaning
framebuffer	The pixel memory the display scans out of: 480x272 at 16 bpp RGB565, two pages in the Tang Nano's in-package SDRAM behind the streaming controller (FLIP swaps them). The 240x136/2 bpp BSRAM framebuffer was the stage-4 original.
pen	The current drawing colour, a whole RGB565 value since direct colour (stages 5-6). ONE pen since the single-interface migration: the GL walker's (`COLOR` verb) — the walker loads it into its private register file while drawing. BASIC's `COLOR` statement and the C library's `gcolor()` both just emit the verb.
palette	RETIRED (stages 5-6, with the four-pen modes): the table that mapped each pen to a 12-bit RGB value. Direct colour has no palette — `SETPAL` and BASIC's `PALETTE` went with it.
scanout	The read side: `sdram_video.v` fetching each panel line from the SDRAM framebuffer through the controller's stream port into a ping-pong line buffer, and emitting RGB + DE. (`video_rgb.v` and the shared-port `sc_en` era belong to the retired BSRAM framebuffer.)
drawing engine	The state machine in the card that renders a primitive from the walker's register file. Why a filled box is a few GL stream bytes and not 32640 read-modify-writes.
Bresenham / midpoint	The integer line and circle/ellipse algorithms. Transliterated between C and Verilog step for step — a cleverer version that lights a different pixel is a bug, because the co-sim compares framebuffers byte for byte.
DE-only	The panel takes a Data Enable strobe with no real HSYNC/VSYNC. 560x297 total at 9 MHz = 54.11 Hz.
GX0/GY0/GX1/GY1 (+H)	Coordinate registers, 16-bit as low/high pairs (low write clears high) — since the single-interface migration, the GL walker's PRIVATE register file, no longer bus-decoded.
GPARM / GPARM2	Scalar arguments in that register file: `ELLIPSE` x/y radius, the `LINPAT` pattern pair.
GCMD / GSTAT / GDATA	The walker-facing command register / busy status / `PIXELR` read-back of the same file. (`IDENT` and `RESET` retired with the CPU door.)
GID0/GID1	RETIRED (single-interface migration): the device door's `$50 $47` = `"PG"` presence signature — two fixed bytes because an absent card floats the bus to `$FF`. `'G'` at GLID ($FF54) is the one presence signal now.
Screen geometry	480×272 at 16 bpp RGB565 — a pixel is its colour — and nothing else. The display was briefly two palettized modes (240×136/2 bpp, 480×272/8 bpp); SETMODE, `SCREEN`, the palette and `PALETTE` were all retired on the way to direct colour (stages 5–6).
RGB565	The pixel and pen format: 5 bits red, 6 green, 5 blue — the panel's own wiring, the machine's word size, two pixels per SDRAM word. `RGB(r,g,b)` packs one in BASIC; bright colours print negative through signed 16-bit ints but compare bit-for-bit.
MDU	The multiply-divide unit at `$FF30` (stage 8a): hardware `(a*b)/c`, signed, 32-bit intermediate, truncate-toward-zero, saturate ±32767 — bit-exact to `lib_g3d`'s software `muldiv`. Probe: `MDID` reads `'M'`. One datapath (`mdu_core.v`) serves it and the geometry engine.
geometry engine	Historically the record walker at `$FF40` (stage 8b, RETIRED at stage 10b); today the term means the GL engine behind the graphics language at `$FF50` — same transform/clip/draw pipeline, driven by a command stream instead of registers. Probe: `GLID` reads `'G'`.
GL / graphics language	The stage-10 command port at `$FF50` (STAGE10-DESIGN.md, modelled on the Matrox PG-640A): opcode + int16 parameters into a FIFO; primitives, card-side modeling/viewing matrices, projection, hither/yon clipping, pages, command lists. Two encodings, switchable with `CA`/`CX`: hex opcodes, or ASCII keywords parsed IN FABRIC (stage 10d). Reachable three ways: the `gl` console command, BASIC's `GL s$` string statement, and — since 10d — the verbs as NATIVE BASIC statements (`MDROTY A`, `POLY3 3,...`; tokens generated by gen_glkw.py, the same table the RTL and emulator use). `man gl` on-target is the reference card.
page flip	Double buffering: two 512K-aligned framebuffer pages (address bit 19). The engine owns the state; a flip latches at the scanout frame boundary with the rule display ← draw, draw ← other. Power-on page contents are UNDEFINED — clear both before flipping — and `PGSYNC` (GECMD 4 / `g3sync()`) is the only way back to single-buffer.
typed records	The retired stage-9 list format (type byte, flags, RGB565 colour, vertices). Superseded at stage 10 by the GL command stream — a scene is now a command list, not a record list.
scene	GL command list 0 (stage 10c): the byte stream `tri` records (`tri …k` appends via CLAPP) and `rotate`/`camera` replay with new matrices. Stored on the card in SDRAM; the card's matrix/window state persists alongside it.
command list	A GL byte stream stored on the card (CLBEG…CLEND, 256 slots of 4KB at `$100000`), replayed by CLRUN/CLOOP. Matrix deltas inside a looped list accumulate per pass — the fly-through/self-spinning-demo mechanism.
P8I	The display's own picture format: `"P8I"`, version, width/height little-endian, depth `$10`, then raw RGB565 row-major. Self-describing, so BASIC's `IMAGE x,y,name$` cannot be lied to. `tools/p8img.py` converts anything into one.
GTEXT	Died and was REBORN (2026-09-01): the old software-rasterized bitmap text is gone — PGC `TEXT` draws stroke glyphs card-side from the font the OS streams from `/FONT.GL` at boot (raw 3D idiom: `MOVE3 x,y,0 : TEXT s$`). The `GTEXT x,y,size,s$` statement survives as pure-GL 2D sugar over it: it resets the matrix and camera each call and anchors unscaled at window (x,y).
FONT57	RETIRED (2026-09-01, with the GTEXT rasterizer): the 5x7 bitmap glyph table and its generator. Text is stroke glyphs now — `generators/gen_font.py` builds `/FONT.GL`, the TDEFIN stream the OS loads at boot; lowercase still folds onto uppercase.
SELFTEST (`$F0`)	RETIRED (single-interface migration): the emulator-only test pattern went with the device door — there is no register to poke it through. A card with no software behind it is proven by the bridge PING, the GLID probe and the monitor's wake-up console (blank screen + banner on the LCD; it replaced the boot splash).

BASIC internals (`basic/p8xbasic.asm`)¶

Term	Meaning
BASORG / BASRAM	Build parameters: code origin / data (variables + program text) base.
PBUF	Rebuild scratch buffer (fixed at `$C000`).
VARTAB	Variable symbol table.
NAMLEN / NVARS	Tunable limits: significant chars per name (6) / max variables (32).
CRUNCH / MATCHKW	Tokenizer: crush a line to tokens / match a keyword.
EVAL / TERM / FACTOR	Recursive-descent expression parser levels.
TOK_xxx	Keyword token bytes (e.g. `TOK_FOR`, `TOK_BYE`).
LCG	Linear Congruential Generator — the `RND()` pseudo-random algorithm.
GPEN	RETIRED (2026-09-01, with GTEXT, its last consumer): BASIC's shadow of the write-only device pen. The pen is pure GL state now — `COLOR` emits the GL COLOR verb and nothing else; `IMAGE` rides the GL BLIT verb, whose payload carries its own colours.
GWAIT / GEXEC / GSTORE / GARG	RETIRED (2026-09-01, single-interface migration): BASIC's device-door helpers — busy-poll, command issue, register-pair write, argument-to-register. Everything emits GL through `GLPUT` now. (`GWAIT` once clobbered A, which turned every command into a NOP — the war story survives the code.)
GSADR / GSTGT / GCTMP / GELL	RETIRED graphics scratch bytes, freed with their owners above (GELL with CIRCLE's move onto GL ELIPSE).
DOGLINE	The `LINE` statement handler — named around the pre-existing `DOLINE`, which parses a program line.

Code identifiers & internal abbreviations (OS / monitor)¶

Term	Meaning
CWD / CWDPATH	Current Working Directory / its textual path. Not just the prompt: `SYS_GETCWD` hands it to programs to resolve relative paths, and `DERIVEDRV` picks the drive by matching a leading `/d1`. 48 bytes — `SETPATH` keeps it collapsed (no `..`) and bounded.
REDIRF	Redirect Flag — 1 while OS output is being captured to a file.
OUTCH / OPUTS / OPHEX8	The OS output sink and its string / hex-byte helpers (route through it for redirection).
SDIR / DLBA / ECNT / ENTP	Directory op state: scanned-dir start/count / dir-sector LBA / entries-left / entry pointer.
FREELO/FREEHI / SECCNT	Boot-block free pointer (next free LBA) / sector count for a transfer.
RESOLVE / DESCEND / FINDENT / FINDSLOT / WRENT / MKEXT / SAVECORE	OS directory routines: split a path → parent+leaf / walk into a subdir / find an entry by name / find a free slot / write an entry / init a new dir extent / copy memory→file.
GETHEX / GETLN / PARSEW / CONIN/CONOUT	parse a hex arg / read a line / parse the command word / BIOS console I/O.

Toolchain¶

Tool	Role
genucode.py	Microcode generator — single source of truth for the control word + opcode table; emits the four `u.bin` EPROM images (burned and* interpreted).
p8xasm.py	Two-pass assembler (imports the opcode table from `genucode.py`).
p8xemu.c	Cycle-level emulator — interprets the same `u*.bin` the hardware burns.
p8xfs.py	Host tool for P8XFS images (create/boot/put/get/ls/mkdir/tree/fsck).
gen_eagle.py	The canonical board netlists (`CARDS`, `busnet()`) that the KiCad flow (`gen_kicad.py`) builds the boards from; its own Eagle output is frozen at rev E (2026-09-18).
gen_bom.py / render_board_pdf.py / gen_bus_pdf.py	BOM, placement-view PDFs (of the frozen Eagle boards), bus-map PDF.