tiny8

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:

…

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 hi