Tiny8

An educational 8-bit CPU simulator with interactive visualization

Tiny8 is a lightweight and educational toolkit for exploring the fundamentals of computer architecture through hands-on assembly programming and real-time visualization. Designed for learning and experimentation, it features an AVR-inspired 8-bit CPU with 32 registers, a rich instruction set, and powerful debugging tools — all with zero heavy dependencies.

Real-time visualization of a bubble sort algorithm executing on Tiny8

✨ Features

🎯 Interactive Terminal Debugger

Vim-style navigation: Step through execution with intuitive keyboard controls
Change highlighting: See exactly what changed at each step (registers, flags, memory)
Advanced search: Find instructions, track register/memory changes, locate PC addresses
Marks and bookmarks: Set and jump to important execution points
Vertical scrolling: Handle programs with large memory footprints

🎬 Graphical Animation

Generate high-quality GIF/MP4 videos of program execution
Visualize register evolution, memory access patterns, and flag changes
Perfect for presentations, documentation, and learning materials

🏗️ Complete 8-bit Architecture

32 general-purpose registers (R0-R31)
8-bit ALU with arithmetic, logical, and bit manipulation operations
Status register (SREG) with 8 condition flags
2KB address space for unified memory and I/O
Stack operations with dedicated stack pointer
AVR-inspired instruction set with 60+ instructions

📚 Educational Focus

Clean, readable Python implementation
Comprehensive examples (Fibonacci, bubble sort, factorial, and more)
Step-by-step execution traces for debugging
Full API documentation and instruction set reference

🚀 Quick Start

Installation

pip install tiny8

Your First Program

Create fibonacci.asm:

; Fibonacci Sequence Calculator; Calculates the 10th Fibonacci number (F(10) = 55); F(0) = 0, F(1) = 1, F(n) = F(n-1) + F(n-2);; Results stored in registers:; R16 and R17 hold the two most recent Fibonacci numbers ldi r16,0 ; F(0) = 0 ldi r17,1 ; F(1) = 1 ldi r18,9 ; Counter: 9 more iterations to reach F(10)loop:add r16, r17 ; F(n) = F(n-1) + F(n-2)mov r19, r16 ; Save result temporarilymov r16, r17 ; Shift: previous = currentmov r17, r19 ; Shift: current = new resultdec r18 ; Decrement counter brne loop ; Continue if counter != 0done:jmp done ; Infinite loop at end

Run it:

tiny8 fibonacci.asm # Interactive debugger
tiny8 fibonacci.asm -m ani -o fibonacci.gif # Generate animation

Python API

fromtiny8importCPU, assemble_fileasm=assemble_file("fibonacci.asm")
cpu=CPU()
cpu.load_program(asm)
cpu.run(max_steps=1000)
print(f"Result: R17 = {cpu.read_reg(17)}") # Final Fibonacci number

💡 Why Tiny8?

For Students — Write assembly, see immediate results with visual feedback. Understand how each instruction affects CPU state without abstractions.

For Educators — Interactive demonstrations, easy assignment creation, and generate animations for lectures.

For Hobbyists — Rapid algorithm prototyping at the hardware level with minimal overhead and an extensible, readable codebase.

📖 Documentation

Full Documentation — Complete API reference and guides
Instruction Set Reference — All 60+ instructions
CLI Guide — Terminal debugger keyboard shortcuts
Examples — Sample programs with explanations
Contributing — Guidelines for contributors

🎮 Interactive CLI Controls

The terminal-based debugger provides powerful navigation and inspection capabilities.

Navigation & Playback

l / h or → / ← — Step forward/backward
w / b — Jump ±10 steps
0 / $ — Jump to first/last step
Space — Play/pause auto-execution
[ / ] — Decrease/increase playback speed

Display & Inspection

r — Toggle register display (all/changed only)
M — Toggle memory display (all/non-zero only)
= — Show detailed step information
j / k — Scroll memory view up/down

Search & Navigation Commands (press `:`)

:123 — Jump to step 123
:+50 / :-20 — Relative jumps
:/ldi — Search forward for instruction "ldi"
:?add — Search backward for "add"
:@0x100 — Jump to PC address 0x100
:r10 — Find next change to register R10
:r10=42 — Find where R10 equals 42
:m100 — Find next change to memory[100]
:fZ — Find next change to flag Z

Marks & Help

ma — Set mark 'a' at current step
'a — Jump to mark 'a'
/ — Show help screen
q or ESC — Quit

🎓 Examples

The examples/ directory contains programs demonstrating key concepts:

Example	Description
`fibonacci.asm`	Fibonacci sequence using registers
`bubblesort.asm`	Sorting algorithm with memory visualization
`factorial.asm`	Recursive factorial calculation
`find_max.asm`	Finding maximum value in array
`is_prime.asm`	Prime number checking algorithm
`gcd.asm`	Greatest common divisor (Euclidean algorithm)

Bubble Sort

Sort 32 bytes in memory:

tiny8 examples/bubblesort.asm -ms 0x60 -me 0x80 # Watch live
tiny8 examples/bubblesort.asm -m ani -o sort.gif -ms 0x60 -me 0x80 # Create GIF

Using Python

fromtiny8importCPU, assemble_filecpu=CPU()
cpu.load_program(assemble_file("examples/bubblesort.asm"))
cpu.run()
print("Sorted:", [cpu.read_ram(i) foriinrange(0x60, 0x80)])

🔧 CLI Options

Command Syntax

tiny8 FILE [OPTIONS]

General Options

Option	Description
`-m, --mode {cli,ani}`	Visualization mode: `cli` for interactive debugger (default), `ani` for animation
`-v, --version`	Show version and exit
`--max-steps N`	Maximum execution steps (default: `15000`)

Memory Display Options

Option	Description
`-ms, --mem-start ADDR`	Starting memory address (decimal or `0xHEX`, default: `0x00`)
`-me, --mem-end ADDR`	Ending memory address (decimal or `0xHEX`, default: `0xFF`)

CLI Mode Options

Option	Description
`-d, --delay SEC`	Initial playback delay in seconds (default: `0.15`)

Animation Mode Options

Option	Description
`-o, --output FILE`	Output filename (`.gif`, `.mp4`, `.png`)
`-f, --fps FPS`	Frames per second (default: `60`)
`-i, --interval MS`	Update interval in milliseconds (default: `1`)
`-pe, --plot-every N`	Update plot every N steps (default: `100`, higher = faster)

Windows: CLI debugger requires WSL or windows-curses. Animation works natively.

📋 Instruction Set Reference

Tiny8 implements an AVR-inspired instruction set with 62 instructions organized into logical categories. All mnemonics are case-insensitive. Registers are specified as R0-R31, immediates support decimal, hex ($FF or 0xFF), and binary (0b11111111) notation.

Data Transfer

Instruction	Description	Example
`LDI Rd, K`	Load 8-bit immediate into register	`ldi r16, 42`
`MOV Rd, Rr`	Copy register to register	`mov r17, r16`
`LD Rd, Rr`	Load from RAM at address in Rr	`ld r18, r16`
`ST Rr, Rs`	Store Rs to RAM at address in Rr	`st r16, r18`
`IN Rd, port`	Read from I/O port into register	`in r16, 0x3F`
`OUT port, Rr`	Write register to I/O port	`out 0x3F, r16`
`PUSH Rr`	Push register onto stack	`push r16`
`POP Rd`	Pop from stack into register	`pop r16`

Arithmetic Operations

Instruction	Description	Example
`ADD Rd, Rr`	Add registers	`add r16, r17`
`ADC Rd, Rr`	Add with carry	`adc r16, r17`
`SUB Rd, Rr`	Subtract registers	`sub r16, r17`
`SUBI Rd, K`	Subtract immediate	`subi r16, 10`
`SBC Rd, Rr`	Subtract with carry	`sbc r16, r17`
`SBCI Rd, K`	Subtract immediate with carry	`sbci r16, 5`
`INC Rd`	Increment register	`inc r16`
`DEC Rd`	Decrement register	`dec r16`
`MUL Rd, Rr`	Multiply (result in Rd:Rd+1)	`mul r16, r17`
`DIV Rd, Rr`	Divide (quotient→Rd, remainder→Rd+1)	`div r16, r17`
`NEG Rd`	Two's complement negation	`neg r16`
`ADIW Rd, K`	Add immediate to word (16-bit)	`adiw r24, 1`
`SBIW Rd, K`	Subtract immediate from word	`sbiw r24, 1`

Logical & Bit Operations

Instruction	Description	Example
`AND Rd, Rr`	Logical AND	`and r16, r17`
`ANDI Rd, K`	AND with immediate	`andi r16, 0x0F`
`OR Rd, Rr`	Logical OR	`or r16, r17`
`ORI Rd, K`	OR with immediate	`ori r16, 0x80`
`EOR Rd, Rr`	Exclusive OR	`eor r16, r17`
`EORI Rd, K`	XOR with immediate	`eori r16, 0xFF`
`COM Rd`	One's complement	`com r16`
`CLR Rd`	Clear register (XOR with self)	`clr r16`
`SER Rd`	Set register to 0xFF	`ser r16`
`TST Rd`	Test for zero or negative	`tst r16`
`SWAP Rd`	Swap nibbles (high/low 4 bits)	`swap r16`
`SBI port, bit`	Set bit in I/O register	`sbi 0x18, 3`
`CBI port, bit`	Clear bit in I/O register	`cbi 0x18, 3`

Shifts & Rotates

Instruction	Description	Example
`LSL Rd`	Logical shift left	`lsl r16`
`LSR Rd`	Logical shift right	`lsr r16`
`ROL Rd`	Rotate left through carry	`rol r16`
`ROR Rd`	Rotate right through carry	`ror r16`

Control Flow

Instruction	Description	Example
`JMP label`	Unconditional jump	`jmp loop`
`RJMP offset`	Relative jump	`rjmp -5`
`CALL label`	Call subroutine	`call function`
`RCALL offset`	Relative call	`rcall -10`
`RET`	Return from subroutine	`ret`
`RETI`	Return from interrupt	`reti`
`BRNE label`	Branch if not equal (Z=0)	`brne loop`
`BREQ label`	Branch if equal (Z=1)	`breq done`
`BRCS label`	Branch if carry set (C=1)	`brcs overflow`
`BRCC label`	Branch if carry clear (C=0)	`brcc no_carry`
`BRGE label`	Branch if greater/equal	`brge positive`
`BRLT label`	Branch if less than	`brlt negative`
`BRMI label`	Branch if minus (N=1)	`brmi negative`
`BRPL label`	Branch if plus (N=0)	`brpl positive`

Compare Instructions

Instruction	Description	Example
`CP Rd, Rr`	Compare registers (Rd - Rr)	`cp r16, r17`
`CPI Rd, K`	Compare with immediate	`cpi r16, 42`
`CPSE Rd, Rr`	Compare, skip if equal	`cpse r16, r17`

Skip Instructions

Instruction	Description	Example
`SBRS Rd, bit`	Skip if bit in register is set	`sbrs r16, 7`
`SBRC Rd, bit`	Skip if bit in register is clear	`sbrc r16, 7`
`SBIS port, bit`	Skip if bit in I/O register is set	`sbis 0x16, 3`
`SBIC port, bit`	Skip if bit in I/O register is clear	`sbic 0x16, 3`

MCU Control

Instruction	Description	Example
`NOP`	No operation	`nop`
`SEI`	Set global interrupt enable	`sei`
`CLI`	Clear global interrupt enable	`cli`

Status Register (SREG) Flags

The 8-bit status register contains condition flags updated by instructions:

Bit	Flag	Description
7	I	Global interrupt enable
6	T	Bit copy storage
5	H	Half carry (BCD arithmetic)
4	S	Sign bit (N ⊕ V)
3	V	Two's complement overflow
2	N	Negative
1	Z	Zero
0	C	Carry/borrow

Flags are used for conditional branching and tracking arithmetic results.

Assembly Syntax Notes

Comments: Use ; for line comments
Labels: Must end with : (e.g., loop:)
Registers: Case-insensitive R0-R31 (r16, R16 equivalent)
Immediates: Decimal (42), hex ($2A, 0x2A), binary (0b00101010)
Whitespace: Flexible indentation, spaces/tabs interchangeable

🏗️ Architecture Overview

CPU Components

32 General-Purpose Registers (R0-R31) — 8-bit working registers
Program Counter (PC) — 16-bit, addresses up to 64KB
Stack Pointer (SP) — 16-bit, grows downward from high memory
Status Register (SREG) — 8 condition flags (I, T, H, S, V, N, Z, C)
64KB Address Space — Unified memory for RAM and I/O

Memory Map

0x0000 - 0x001F Memory-mapped I/O (optional)
0x0020 - 0xFFFF Available RAM (stack grows downward from top)

🧪 Testing

pytest # Run all tests
pytest --cov=src/tiny8 --cov-report=html # With coverage
pytest tests/test_arithmetic.py # Specific test file

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

Areas for contribution: New instructions, example programs, documentation, visualizations, performance optimizations.

📄 License

MIT License — see LICENSE for details.

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: sql-hkr.github.io/tiny8

Made with ❤️ for learners, educators, and curious minds

Star ⭐ the repo if you find it useful!

Name		Name	Last commit message	Last commit date
Latest commit History 35 Commits
.github/workflows		.github/workflows
.vscode		.vscode
docs		docs
examples		examples
src/tiny8		src/tiny8
tests		tests
.gitignore		.gitignore
.python-version		.python-version
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation