6 November 2026

BIT4 Programmer's Manual

#BIT4
#Assembly
#Computer Architecture
#Manual

About this manual

BIT4 is a fantasy 4-bit computer that I designed and built from scratch in C#: its own CPU, ALU, banked RAM, character ROM, video unit, sprite engine and assembler, without any emulation framework. The long-term goal is to run it on real hardware with an Arduino and a TFT display.

This manual describes the machine as it is today. Use the buttons or the arrow keys to turn the pages.

Part	Detail
CPU	4-bit, stack-based, 2 registers (AX, BX)
ALU	AND, OR, XOR, NOT, ADD, SUB, SHL, SHR, INC, DEC
Instructions	38
RAM	16 banks × 16 cells × 4 bits = 128 bytes
Character ROM	4 pages × 16 glyphs, 4×5 pixels each
Display	32×32 logical pixels, 16 CGA colors in 8×8 attribute cells
Sprites	One 4×5 sprite in bank 15, PSET or XOR drawing
Input	Paged keyboard port, 4-bit random number port

Read how BIT4 was built →

Architecture

Register	Width	Purpose
AX	4 bit	Primary general-purpose register
BX	4 bit	Secondary register, also the address register for indirect memory access
PC	—	Program counter, points at the current line
ZF	1 bit	Zero flag, set when a result or a comparison is zero / equal

The stack is the data path. Registers are loaded with MOV, values move to the stack with PUSH, and every ALU operation takes its operands from the stack and pushes the result back. STORE and PRINT also take their value from the stack.

mov ax,0011   ; AX = 3
push ax       ; stack: [3]
mov ax,0100   ; AX = 4
push ax       ; stack: [3, 4]
add           ; stack: [7]
pop ax        ; AX = 7

One hardware path for the ALU. Before every ALU operation two values are latched from the stack, the first into TempB and the second into TempA. Unary operations such as INC or SHL use the same path. All internal buffers are cleared at the end of every cycle, so no state leaks into the next instruction.

Execution model. The assembler executes the program from its source text, line by line, and jumps to labels. Every instruction also has an 8-bit display code that the debugger shows next to the source. A few of those codes are shared (for example HALT and JZ), because the engine identifies instructions by mnemonic. They will become unique when jumps move from labels to addresses.

Instruction set: ALU and compare

All values are 4 bits wide and wrap around: 1111 + 0001 = 0000.

Mnemonic	Code	Stack	Effect
`AND`	`0000`	−1	Pop two values, push a AND b
`OR`	`0001`	−1	Pop two values, push a OR b
`XOR`	`0010`	−1	Pop two values, push a XOR b
`NOT`	`0011`	0	Invert the top value
`ADD`	`0100`	−1	Pop two values, push (a + b) mod 16
`SUB`	`0101`	−1	Pop two values, push (a − b) mod 16
`SHL`	`1000`	0	Shift the top value left by one bit
`SHR`	`1001`	0	Shift the top value right by one bit
`INC`	`1010`	0	Add 1 to the top value
`DEC`	`1011`	0	Subtract 1 from the top value

ALU results set the zero flag when they are 0000. XOR with the same value is the classic way to test for equality.

Mnemonic	Effect
`CMP AX,n`	ZF = 1 if AX equals the immediate value n
`CMP BX,n`	ZF = 1 if BX equals n
`CMP AX,BX`	ZF = 1 if AX equals BX
`CMP BX,AX`	ZF = 1 if BX equals AX

Compare instructions do not touch the stack. Register-to-register compares were added for collision tests in games.

Instruction set: registers and memory

Mnemonic	Stack	Effect
`MOV AX,n`	0	Load the 4-bit immediate n into AX
`MOV BX,n`	0	Load n into BX
`MOV AX,BX`	0	Copy BX into AX
`MOV BX,AX`	0	Copy AX into BX
`PUSH AX` / `PUSH BX`	+1	Copy the register onto the stack
`POP AX` / `POP BX`	−1	Move the top of the stack into the register

Each bank has 16 cells, addressed 0000–000F. Bank numbers are written in decimal.

Mnemonic	Stack	Effect
`LOAD addr`	+1	Push RAM[addr] of the active bank (or read a port)
`STORE addr`	−1	Pop a value into RAM[addr] (or write to a port)
`LOADB bank,addr`	+1	Read any bank directly, without switching
`STOREB bank,addr`	−1	Write any bank directly, no port intercept
`LOADBI bank`	+1	Read bank[BX]: BX holds the address
`STOREBI bank`	−1	Write bank[BX]
`LOADBI+ bank`	+1	Like `LOADBI`, then BX = BX + 1
`STOREBI+ bank`	−1	Like `STOREBI`, then BX = BX + 1

The auto-increment forms walk through a bank like an array: ideal for sprites, buffers and tables without extra INC code.

Instruction set: control flow, video and system

Mnemonic	Effect
`label:`	Marks a jump target. Not executed
`JMP label`	Always jump to the label
`JZ label`	Jump if the zero flag is set
`JNZ label`	Jump if the zero flag is clear
`CALL label`	Save the return address and jump to a subroutine
`RET`	Return to the line after the last `CALL`
`PRINT`	Pop a character ID and draw it from the active ROM page at the cursor
`NOP`	Do nothing for one cycle
`HALT`	Stop the CPU

A small subroutine:

call newline
halt

newline:
mov ax,0110   ; 6 rows down
push ax
store 000B    ; cursor Y += 6
mov ax,0000
push ax
store 000D    ; carriage return: X = 0
ret

Conventions: n and addr are always 4-bit values written in binary (0101) or as a 4-digit address (000B). Mnemonics are not case-sensitive.

Port map: STORE

The 16 addresses of bank 0 double as hardware ports. A STORE to a port is intercepted and sent to the video unit or the system instead of RAM.

Addr	Command	Effect
`0x00`	Draw mode	0 = normal (PSET), 1 = XOR (draw / erase)
`0x01`	Backspace	Cursor one character back and erase that cell
`0x02`	Cursor left	Cursor one character back, no erase
`0x03`	X high	Cursor X high nibble
`0x04`	Y absolute	Cursor Y, reaches the full screen with one 4-bit value
`0x05`	RAM bank	Switch the active RAM bank (0–15)
`0x06`	Draw sprite	Draw the 4×5 sprite from bank 15 at the cursor
`0x07`	X absolute	Cursor X low nibble
`0x08`	Cursor	0 = hide, anything else = show the text cursor
`0x09`	ROM page	Select the character ROM page for `PRINT`
`0x0A`	CLS	Clear the screen, cursor to (0,0)
`0x0B`	Newline	Cursor Y += value (relative)
`0x0C`	Fast forward	Cursor X += value
`0x0D`	Carriage return	Cursor X = 0
`0x0E`	Color	Set the active color (0–15)
`0x0F`	Draw pixels	Draw 4 raw pixels at the cursor and advance

Every port write follows the same pattern: put the value on the stack, then STORE.

mov ax,1110
push ax
store 000E    ; color = bright yellow

Port map: LOAD and memory banks

Addr	Source	Value pushed to the stack
`0x01`	Random	4-bit LFSR random number (period 15)
`0x02`	Cursor X	Current cursor X, in character steps
`0x06`	Keyboard page	Page of the last key press (0–3)
`0x08`	Keyboard code	Code of the last key press (0–15)

All other addresses read normal RAM.

16 banks of RAM. Each bank has 16 cells of 4 bits. Bank 0 is the I/O page, so in practice programs keep their variables in banks 1–14, and bank 15 holds the sprite.

Bank	Use
0	I/O ports and system
1–14	Free: game state, counters, buffers
15	Sprite data (rows 0–4)

LOADB / STOREB reach any bank without switching. To work in one bank for a longer time, switch with store 0005, and switch back to bank 0 before using the video ports.

loadb 1,0000    ; stack: [a]
loadb 2,0000    ; stack: [a, b]
add             ; stack: [a + b]
storeb 3,0000   ; bank 3, cell 0 = a + b

Display and sprites

The display works like a ZX Spectrum: a monochrome pixel buffer plus a color attribute matrix, where color belongs to an 8×8 cell instead of a single pixel.

Constant	Value
Logical area	32 × 32 pixels
Host window	256 × 256 pixels (scale 8)
Color cells	32 × 32 cells of 8×8 host pixels
Character glyph	4 × 5 pixels

The screen was deliberately downscaled from 128×128 to 32×32: now the Y coordinate fits in a single 4-bit value, sprites have real weight on screen, and the framebuffer is small enough to stream over serial to real hardware.

Sprite engine. Bank 15 holds one 4×5 sprite, one row per cell. store 0006 draws it at the cursor with the active color and draw mode. In XOR mode, drawing the same sprite twice at the same place erases it: the classic "erase old, draw new" animation without clearing the screen.

mov ax,0110      ; row 0:  .##.
push ax
storeb 15,0000
mov ax,1111      ; row 1:  ####
push ax
storeb 15,0001
; ... rows 2-4 in cells 0002-0004
mov ax,0001
push ax
store 0000       ; draw mode = XOR
mov ax,0000
push ax
store 0006       ; draw the sprite at the cursor

Character ROM and colors

PRINT draws a character by its ID (0–15) from the active ROM page. Switch pages with store 0009.

Page	Characters
0	`A B C D E F G H I J K L M N O P`
1	`Q R S T U V W X Y Z [ \ ] ^ _` and space
2	`! " # $ % & ' ( ) * + , - . / ?`
3	`0 1 2 3 4 5 6 7 8 9 : ; < = >`

The ID is the position on the page: H is ID 7 on page 0, 5 is ID 5 on page 3.

Code	Color	Code	Color
0	Black	8	Dark gray
1	Dark blue	9	Bright blue
2	Dark green	10	Bright green
3	Dark cyan	11	Bright cyan
4	Dark red	12	Bright red
5	Dark magenta	13	Bright magenta
6	Brown	14	Bright yellow (default)
7	Light gray	15	White

Keyboard

A key press is reported as a page (port 0x06) and a code (port 0x08). Both are 0 when no key is pressed.

Page	Keys	Code
0	Up, Down, Left, Right	1, 2, 3, 4
0	Space, Enter, Escape, Backspace	5, 6, 7, 8
0	`<>`, `*`, `+`, `-`, `/`, `.`	9 – 14
1	A – P	0 – 15
2	Q – Z	0 – 9
3	0 – 9	0 – 9

The letter and digit codes match the character ROM, so a key can be printed directly: read the page, select the matching ROM page, read the code and PRINT.

Waiting for a key:

listen:
load 0006       ; key page
mov ax,0000
push ax
xor             ; ZF = 1 if page is 0
pop ax
jnz got_key
load 0008       ; key code
mov ax,0000
push ax
xor
pop ax
jz listen       ; nothing pressed yet
got_key:
; handle the key here

Example: Hello

The first program every machine deserves.

mov ax,0000
push ax
store 000A      ; clear the screen
mov ax,1110
push ax
store 000E      ; color: bright yellow
mov ax,0000
push ax
store 0009      ; ROM page 0 (A-P)
mov ax,0111     ; H
push ax
print
mov ax,0100     ; E
push ax
print
mov ax,1011     ; L
push ax
print
mov ax,1011     ; L
push ax
print
mov ax,1110     ; O
push ax
print
halt

Next steps on the roadmap: a Game & Watch style demo for the sprite engine, address-based jumps with unique machine codes, and streaming the framebuffer over serial to an Arduino with a TFT display.