Tiny8 Documentation

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.

Animated bubble sort visualization

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

Features

🎯 Interactive Terminal Debugger

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

Install Tiny8 using pip:

pip install tiny8

Your First Program

Create a file called fibonacci.asm:

; Fibonacci Sequence Calculator
; Calculates the 10th Fibonacci number (F(10) = 55)

    ldi r16, 0          ; F(0) = 0
    ldi r17, 1          ; F(1) = 1
    ldi r18, 9          ; Counter: 9 more iterations

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 with the interactive debugger:

tiny8 fibonacci.asm

Or generate an animation:

tiny8 fibonacci.asm -m ani -o fibonacci.gif

Using the Python API

from tiny8 import CPU, assemble_file

# Assemble and load program
asm = assemble_file("fibonacci.asm")
cpu = CPU()
cpu.load_program(asm)

# Run the program
cpu.run(max_steps=1000)

# Check the result
print(f"Result: R17 = {cpu.read_reg(17)}")  # Final Fibonacci number

Documentation Contents

User Guide

Examples

API Reference

Indices and Tables