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.

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

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

Memory Display Options

CLI Mode Options

Animation Mode Options

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

Arithmetic Operations

Logical & Bit Operations

Shifts & Rotates

Control Flow

Compare Instructions

Skip Instructions

MCU Control

Status Register (SREG) Flags

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

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!