GitHub - sql-hkr/tiny8: A tiny CPU simulator written in Python · GitHub

main

Go to file

Code

NameName

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
View all files

Repository files navigation

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 temporarily
    mov r16, r17        ; Shift: previous = current
    mov r17, r19        ; Shift: current = new result
    dec r18             ; Decrement counter
    brne loop           ; Continue if counter != 0

done:
    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

from tiny8 import CPU, assemble_file

asm = 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

from tiny8 import CPU, assemble_file

cpu = CPU()
cpu.load_program(assemble_file("examples/bubblesort.asm"))
cpu.run()

print("Sorted:", [cpu.read_ram(i) for i in range(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.