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:

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 r16, 0x80
EOR Rd, Rr	Exclusive OR	eor r16, r17
EORI Rd, K	XOR with immediate	eori r16, 0xFF
COM Rd	One's complement	com r16
CLR Rd	Clear register (XOR with self)	clr r16
SER Rd	Set register to 0xFF	ser r16
TST Rd	Test for zero or negative	tst r16
SWAP Rd	Swap nibbles (high/low 4 bits)	swap r16
SBI port, bit	Set bit in I/O register	sbi 0x18, 3
CBI port, bit	Clear bit in I/O register	cbi 0x18, 3

Shifts & Rotates

Instruction	Description	Example
LSL Rd	Logical shift left	lsl r16
LSR Rd	Logical shift right	lsr r16
ROL Rd	Rotate left through carry	rol r16
ROR Rd	Rotate right through carry	ror r16

Control Flow

Instruction	Description	Example
JMP label	Unconditional jump	jmp loop
RJMP offset	Relative jump	rjmp -5
CALL label	Call subroutine	call function
RCALL offset	Relative call	rcall -10
RET	Return from subroutine	ret
RETI	Return from interrupt	reti
BRNE label	Branch if not equal (Z=0)	brne loop
BREQ label	Branch if equal (Z=1)	breq done
BRCS label	Branch if carry set (C=1)	brcs overflow
BRCC label	Branch if carry clear (C=0)	brcc no_carry
BRGE label	Branch if greater/equal	brge positive
BRLT label	Branch if less than	brlt negative
BRMI label	Branch if minus (N=1)	brmi negative
BRPL label	Branch if plus (N=0)	brpl positive

Compare Instructions

Instruction	Description	Example
CP Rd, Rr	Compare registers (Rd - Rr)	cp r16, r17
CPI Rd, K	Compare with immediate	cpi r16, 42
CPSE Rd, Rr	Compare, skip if equal	cpse r16, r17

Skip Instructions

Instruction	Description	Example
SBRS Rd, bit	Skip if bit in register is set	sbrs r16, 7
SBRC Rd, bit	Skip if bit in register is clear	sbrc r16, 7
SBIS port, bit	Skip if bit in I/O register is set	sbis 0x16, 3
SBIC port, bit	Skip if bit in I/O register is clear	sbic 0x16, 3

MCU Control

Instruction	Description	Example
NOP	No operation	nop
SEI	Set global interrupt enable	sei
CLI	Clear global interrupt enable	cli

Status Register (SREG) Flags

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

Bit	Flag	Description
7	I	Global interrupt enable
6	T	Bit copy storage
5	H	Half carry (BCD arithmetic)
4	S	Sign bit (N ⊕ V)
3	V	Two's complement overflow
2	N	Negative
1	Z	Zero
0	C	Carry/borrow

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!