tiny8 0.1.0

Simulator for an 8-bit CPU with registers, memory, and a stack.

Tiny8 documentation

Tiny8 is a minimal, easy-to-use library for working with compact data structures and simple in-memory storage patterns. It is designed for learning, experimentation, and small-scale projects where a lightweight dependency footprint is desirable. This documentation covers installation, examples, and the API to help you get started quickly.

Installation

Tiny8 supports Python 3.11 and newer. It has no heavy external dependencies and is suitable for inclusion in virtual environments. Follow the steps below to prepare your environment and install from source or PyPI.

Prerequisites

• Python 3.11+
• Git (for installing from the repository)
• Recommended: create and use a virtual environment

From source (development)

git clone https://github.com/sql-hkr/tiny8.git
cd tiny8
uv venv
source .venv/bin/activate
uv sync

[!TIP] uv is an extremely fast Python package and project manager, written in Rust. To install it, run:

# On macOS and Linux.
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows.
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

This flow sets up a development virtual environment, installs development requirements, and prepares the project for local editing and testing.

From PyPI (stable)

uv add tiny8

Examples

Bubble sort

This example demonstrates a simple bubble sort algorithm implemented in assembly language for the Tiny8 CPU. The program first fills a section of RAM with pseudo-random bytes, then sorts those bytes using the bubble sort algorithm. Finally, a Python script runs the assembly program and visualizes the sorting process.

bubblesort.asm:

; Bubble sort using RAM (addresses 100..131) - 32 elements
; Purpose: fill RAM[100..131] with pseudo-random bytes and sort them
; Registers:
;   R0 - base address (start = 100)
;   R1 - index / loop counter for initialization
;   R2 - PRNG state (seed)
;   R3..R8 - temporary registers used in loops and swaps
;   R9 - PRNG multiplier (kept aside to avoid clobber in MUL)
;
; The code below is split into two phases:
; 1) init_loop: generate and store 32 pseudo-random bytes at RAM[100..131]
; 2) outer/inner loops: perform a simple bubble sort over those 32 bytes

    ; initialize pointers and PRNG
    ldi r0, 100    ; base address
    ldi r1, 0      ; index = 0
    ldi r2, 123    ; PRNG seed
    ldi r9, 75     ; PRNG multiplier (kept in r9 so mul doesn't clobber it)

init_loop:
    ; PRNG step: r2 := lowbyte(r2 * 75), then tweak
    mul r2, r9     ; r2 = low byte of (r2 * 75)
    inc r2         ; small increment to avoid repeating patterns
    ; store generated byte into memory at base + index
    st r0, r2      ; RAM[base] = r2
    inc r0         ; advance base pointer
    inc r1         ; increment index
    ldi r7, 32
    cp r1, r7
    brne init_loop

; Bubble sort for 32 elements (perform passes until i == 31)
    ldi r2, 0      ; i = 0 (outer loop counter)
outer_loop:
    ldi r3, 0      ; j = 0 (inner loop counter)
inner_loop:
    ; compute address of element A = base + j
    ldi r4, 100
    add r4, r3
    ld r5, r4      ; r5 = A
    ; compute address of element B = base + j + 1
    ldi r6, 100
    add r6, r3
    ldi r7, 1
    add r6, r7
    ld r8, r6      ; r8 = B
    ; compare A and B (we'll swap if A > B)
    cp r8, r5      ; sets carry if r8 < r5 (unsigned)
    brcs no_swap   ; branch if carry set => r8 < r5 => A > B? (keep original order)
    ; swap A and B: store B into A's address, A into B's address
    st r4, r8
    st r6, r5
no_swap:
    inc r3
    ldi r7, 31
    cp r3, r7
    breq end_inner
    jmp inner_loop
end_inner:
    inc r2
    ldi r7, 31
    cp r2, r7
    breq done
    jmp outer_loop

done:
    jmp done

Python Code:

from tiny8 import CPU, Visualizer, assemble_file

prog, labels = assemble_file("examples/bubblesort.asm")
cpu = CPU()
cpu.load_program(prog, labels)
cpu.run(max_cycles=15000)

print([cpu.read_ram(i) for i in range(100, 132)])

viz = Visualizer(cpu)
base = 100
viz.animate_combined(
    interval=1,
    mem_addr_start=base,
    mem_addr_end=base + 31,
    plot_every=100,
    # filename="bubblesort.gif",
    # fps=60,
)

Example Output:

[6, 10, 15, 23, 26, 34, 50, 54, 94, 102, 106, 127, 130, 135, 139, 142, 150, 155, 159, 167, 171, 186, 187, 190, 195, 210, 211, 227, 238, 239, 243, 247]

API Reference

The API section documents the public modules, classes, functions, and configuration options. See:

• tiny8 package

License

Tiny8 is licensed under the MIT License. See LICENSE for details.

Contributions, bug reports, and pull requests are welcome; please follow the repository's CONTRIBUTING guidelines.