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.

<div align="center"> <img src="https://github.com/user-attachments/assets/ffbcb2c4-2c3a-469f-b7b7-e6e86eb374da" alt="Animated bubble sort visualization" width="600"> <p><em>Real-time visualization of a bubble sort algorithm executing on Tiny8</em></p> </div>

✨ Features

🎯 Interactive Terminal Debugger

<img width="600" src="https://github.com/user-attachments/assets/0bbd4382-806e-4b5a-af0b-54d83417fcfb" alt="CLI visualizer screenshot">

• 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.

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