Tiny8

https://github.com/sql-hkr/tiny8
Admin
Tiny8 is a lightweight and educational 8-bit CPU simulator with an AVR-inspired architecture,...
Tokens:38,655
Snippets:296
Trust Score:8.5
License:MIT
Update:10 months ago
Show doc for...
Tokens:
Raw
### Tiny8 Initialization Example

Source: https://github.com/sql-hkr/tiny8/blob/main/docs/assembly_language.md

Shows how to initialize working registers and memory at the beginning of a Tiny8 program using `ldi` and `sts` instructions.

```asm
; Initialize working registers
ldi r16, 0           ; Counter
ldi r17, 1           ; Accumulator
ldi r18, 10          ; Loop limit

; Initialize memory if needed
ldi r19, 0xFF
sts 0x0200, r19      ; Store initial value
```

--------------------------------

### Set Up Development Environment with uv

Source: https://github.com/sql-hkr/tiny8/blob/main/CONTRIBUTING.md

Instructions for setting up a Python development environment using 'uv' for dependency management. It covers installing uv, creating a virtual environment, and installing project dependencies.

```bash
# Install uv if you haven't already
# macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh

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

# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv sync
```

--------------------------------

### Verify Development Setup

Source: https://github.com/sql-hkr/tiny8/blob/main/CONTRIBUTING.md

Commands to verify the development setup by running tests, checking code linting, and trying the command-line interface (CLI) of the Tiny8 simulator.

```bash
# Run tests
pytest

# Check linting
ruff check .

# Try the CLI
tiny8 examples/fibonacci.asm
```

--------------------------------

### Install Tiny8 with Pip

Source: https://github.com/sql-hkr/tiny8/blob/main/docs/index.md

Installs the Tiny8 package using pip, a Python package installer. This is the primary method for setting up Tiny8 on your system.

```bash
pip install tiny8
```

--------------------------------

### Tiny8 Two-Pass Assembly Example

Source: https://github.com/sql-hkr/tiny8/blob/main/docs/assembly_language.md

Explains and demonstrates the two-pass assembly process in Tiny8, which allows for forward references by first collecting labels and then resolving references.

```asm
; Forward reference (allowed)
    jmp forward_label
    nop
    nop
forward_label:
    ret
```

--------------------------------

### Set Up Development Environment with pip

Source: https://github.com/sql-hkr/tiny8/blob/main/CONTRIBUTING.md

Instructions for setting up a Python development environment using the standard 'pip' and 'venv' modules. It covers creating a virtual environment and installing project dependencies.

```bash
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e ".[dev]"
```

--------------------------------

### Visualize Bubble Sort Algorithm (Bash)

Source: https://github.com/sql-hkr/tiny8/blob/main/docs/visualization.md

A command-line example demonstrating the visualization of a bubble sort algorithm. This helps in observing register changes and memory swaps during the sorting process.

```bash
# Visualize bubble sort
tiny8 examples/bubblesort.asm -m ani -o bubblesort.gif
```

--------------------------------

### Run Tiny8 Assembly Example with Interactive Debugger

Source: https://github.com/sql-hkr/tiny8/blob/main/docs/examples/index.md

Demonstrates how to execute a Tiny8 assembly program using the interactive debugger. This is useful for stepping through code and understanding its execution flow. No external dependencies are required beyond the `tiny8` tool.

```bash
tiny8 examples/fibonacci.asm
```

--------------------------------

### Visualize Fibonacci Sequence Generation (Bash)

Source: https://github.com/sql-hkr/tiny8/blob/main/docs/visualization.md

A command-line example for visualizing the generation of a Fibonacci sequence. This aids in tracking register values, loop counters, and flag changes during the iterative process.

```bash
# Track Fibonacci sequence generation
tiny8 examples/fibonacci.asm -m ani -o fib.gif
```

--------------------------------

### Python Type Hinting and Docstring Example

Source: https://github.com/sql-hkr/tiny8/blob/main/CONTRIBUTING.md

An example demonstrating Python code style guidelines, including type hints for function signatures and Google-style docstrings for documenting functions, arguments, and potential exceptions.

```python
def execute_instruction(self, opcode: int, operands: list[int]) -> None:
    """Execute a single instruction.    
    Args:
        opcode: The instruction opcode.
        operands: List of operand values.        
    Raises:
        InvalidOpcodeError: If opcode is not recognized.
    """
    # Implementation
```

--------------------------------

### Tiny8 Assembly Example Template

Source: https://github.com/sql-hkr/tiny8/blob/main/CONTRIBUTING.md

A template for creating example assembly files in the 'examples/' directory. It includes sections for algorithm name, description, explanation, registers used, and expected results, followed by a basic code structure.

```asm
; Algorithm Name
; Brief description of what this program does
; 
; Algorithm explanation:
; - Step 1 description
; - Step 2 description
; 
; Registers used:
; - R16: Purpose
; - R17: Purpose
; 
; Expected result: Description

    ldi r16, 0          ; Initialize
    ; ... your code
    
done:
    jmp done            ; Halt
```

--------------------------------

### Tiny8 Code Organization Best Practice

Source: https://github.com/sql-hkr/tiny8/blob/main/docs/assembly_language.md

Provides an example of well-organized Tiny8 assembly code, emphasizing meaningful labels, comments, grouping related code, and using blank lines for separation.

```asm
; Good: Clear structure and documentation
; Calculate factorial of N
; Input: R16 = N
; Output: R17 = N!
factorial:
    ldi r17, 1           ; result = 1

fact_loop:
    mul r17, r16         ; result *= N
    dec r16              ; N--
    brne fact_loop       ; Continue if N != 0
    ret
```

--------------------------------

### Tiny8 Assembly: Example Program for Summation

Source: https://github.com/sql-hkr/tiny8/blob/main/docs/assembly_language.md

This example demonstrates a basic Tiny8 assembly program to calculate the sum of numbers from 1 to N. It utilizes instructions for loading immediate values, arithmetic operations, comparisons, and branching. N is expected to be in register R16, and the result is stored in R17.

```asm
; Calculate the sum of 1 to N
; N is stored in R16, result in R17

    ldi r16, 10         ; N = 10
    ldi r17, 0          ; Sum = 0
    ldi r18, 1          ; Counter = 1

loop:
    add r17, r18        ; Sum += Counter
    inc r18             ; Counter++
    cp r18, r16         ; Compare Counter with N
    brlo loop           ; Loop if Counter < N
    breq loop           ; Loop if Counter == N

done:
    jmp done            ; Infinite loop

```

--------------------------------

### Tiny8 Assembly: Store 'HELLO' String in Memory

Source: https://github.com/sql-hkr/tiny8/blob/main/docs/examples/hello_world.md

This Tiny8 assembly program demonstrates how to store the ASCII characters for 'HELLO' into sequential memory locations starting at address 0x60. It utilizes immediate load instructions (ldi) to load values into registers and store instructions (st) to write register contents to memory. The program concludes with an infinite loop to halt execution.

```asm
; Hello World - Store ASCII string "HELLO" in memory
; Demonstrates basic memory store operations
; Output: RAM[0x60..0x64] contains "HELLO" in ASCII

start:
    ldi r16, 0x60     ; Base address
    
    ldi r17, 72       ; 'H'
    st r16, r17
    inc r16
    
    ldi r17, 69       ; 'E'
    st r16, r17
    inc r16
    
    ldi r17, 76       ; 'L'
    st r16, r17
    inc r16
    
    st r16, r17       ; 'L' (reuse value)
    inc r16
    
    ldi r17, 79       ; 'O'
    st r16, r17

done:
    jmp done          ; infinite loop (halt)

```

--------------------------------

### Run Bubble Sort Example in CLI and Animation Modes

Source: https://github.com/sql-hkr/tiny8/blob/main/README.md

Demonstrates how to execute the Bubble Sort assembly program using the Tiny8 CLI. It shows commands for interactive debugging with specified memory ranges and for generating an animated GIF of the sorting process.

```bash
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
```

--------------------------------

### Verify Tiny8 Installation

Source: https://github.com/sql-hkr/tiny8/blob/main/docs/getting_started.md

Checks if the Tiny8 installation was successful by displaying its version number in the terminal.

```bash
tiny8 --version
```

--------------------------------

### Tiny8 Assembly: Valid and Invalid Labels

Source: https://github.com/sql-hkr/tiny8/blob/main/docs/assembly_language.md

Provides examples of valid and invalid label definitions in Tiny8 assembly. Labels must end with a colon, be case-sensitive, and adhere to character restrictions (letters, digits, underscore), not starting with a digit and not being reserved mnemonics.

```asm
start:
loop_1:
CalculateFibonacci:
_private:

```

--------------------------------

### Tiny8 Case Sensitivity Rules

Source: https://github.com/sql-hkr/tiny8/blob/main/docs/assembly_language.md

Demonstrates the case sensitivity rules for Tiny8 assembly. Instructions and registers are case-insensitive, while labels are case-sensitive. This example shows equivalent instructions and distinct labels.

```asm
; These are all equivalent
ADD r16, r17
add r16, r17
Add R16, R17

; But these labels are different
Loop:
    ; ...
    jmp loop        ; Error! Label "loop" not defined
```

--------------------------------

### Tiny8 Assembly: Instruction Format and Operand Counts

Source: https://github.com/sql-hkr/tiny8/blob/main/docs/assembly_language.md

Explains the general structure of Tiny8 assembly instructions, which follows the pattern `[label:] mnemonic [operand1[, operand2[, ...]]]`. It also provides examples of instructions with zero, one, or two operands.

```asm
; Zero operands
nop                  ; No operation
ret                  ; Return from subroutine

; One operand
inc r16              ; Increment register
dec r17              ; Decrement register
jmp loop             ; Jump to label
push r16             ; Push register

; Two operands
mov r16, r17         ; Move R17 to R16
add r16, r17         ; Add R17 to R16
ldi r16, 42          ; Load immediate into R16
lds r16, 0x0200      ; Load from memory

```

--------------------------------

### Conventional Commit Message Example

Source: https://github.com/sql-hkr/tiny8/blob/main/CONTRIBUTING.md

An example demonstrating the conventional commit message format, including type, summary, body, and footer for referencing issues. This format helps in automating changelog generation and understanding commit history.

```git
feat: add MUL instruction support

- Implement 8-bit multiplication
- Update instruction decoder
- Add comprehensive tests
- Update documentation

Closes #123
```

--------------------------------

### Fibonacci Assembly Program for Tiny8

Source: https://github.com/sql-hkr/tiny8/blob/main/docs/index.md

An example assembly program for the Tiny8 simulator that calculates the 10th Fibonacci number. It demonstrates basic instructions like load immediate (ldi), add, move (mov), decrement (dec), and conditional branch (brne).

```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

```

--------------------------------

### Tiny8 Value Range and Overflow Example

Source: https://github.com/sql-hkr/tiny8/blob/main/docs/assembly_language.md

Illustrates the 8-bit value ranges (0-255 unsigned, -128 to +127 signed) in Tiny8 and how overflow occurs with wrap-around behavior using `inc` and `dec`.

```asm
ldi r16, 255
inc r16              ; R16 = 0 (wraps around)

ldi r17, 0
dec r17              ; R17 = 255 (wraps around)
```

--------------------------------

### Generate Animation of Tiny8 Assembly Execution

Source: https://github.com/sql-hkr/tiny8/blob/main/docs/examples/index.md

Shows how to generate an animated GIF from the execution of a Tiny8 assembly program. This feature is helpful for visualizing complex algorithms like bubble sort. Requires the `tiny8` tool and an output file path.

```bash
tiny8 examples/bubblesort.asm -m ani -o bubblesort.gif
```

--------------------------------

### Pytest Example Test Structure

Source: https://github.com/sql-hkr/tiny8/blob/main/CONTRIBUTING.md

An example structure for writing a test case using the pytest framework in Python. It demonstrates the Arrange-Act-Assert pattern for testing CPU functionality.

```python
def test_feature_name():
    """Test description."""
    # Arrange
    cpu = CPU()
    cpu.load_program(...)
    
    # Act
    cpu.step()
    
    # Assert
    assert cpu.read_reg(16) == expected_value
```

--------------------------------

### Tiny8 Assembly: Single-Line Comments

Source: https://github.com/sql-hkr/tiny8/blob/main/docs/assembly_language.md

Demonstrates the usage of single-line comments in Tiny8 assembly. Comments start with a semicolon (`;`) and extend to the end of the line, aiding in code documentation. These comments are ignored by the assembler.

```asm
ldi r16, 42          ; Load the answer
; This is a full-line comment
add r16, r17         ; Add registers

```

--------------------------------

### Run Tiny8 Assembly Program from CLI

Source: https://github.com/sql-hkr/tiny8/blob/main/docs/index.md

Executes an assembly program using the Tiny8 command-line interface. This command starts the interactive debugger for the specified assembly file.

```bash
tiny8 fibonacci.asm
```

--------------------------------

### Run Tiny8 Assembly Program using Python API

Source: https://github.com/sql-hkr/tiny8/blob/main/docs/examples/index.md

Illustrates how to load and run a Tiny8 assembly program using the Python API. This involves creating a CPU instance, assembling the file, and executing the program with a step limit. Requires the `tiny8` Python library.

```python
from tiny8 import CPU, assemble_file

cpu = CPU()
cpu.load_program(assemble_file("examples/fibonacci.asm"))
cpu.run(max_steps=1000)
```

--------------------------------

### Typical Tiny8 Program Layout

Source: https://github.com/sql-hkr/tiny8/blob/main/docs/assembly_language.md

Illustrates the standard structure of a Tiny8 program, including header comments, initialization, main loop, subroutines, and program termination with an infinite loop.

```asm
; ============================================
; Program: Description
; Author: Your Name
; Description: What the program does
; ============================================

; --- Initialization ---
    ldi r16, initial_value
    ldi r17, 0

; --- Main Loop ---
main_loop:
    ; ... main program logic ...
    jmp main_loop

; --- Subroutines ---
subroutine1:
    ; ... subroutine code ...
    ret

subroutine2:
    ; ... subroutine code ...
    ret

; --- End ---
done:
    jmp done         ; Infinite loop
```

--------------------------------

### Tiny8 Instruction Format and Examples (Python)

Source: https://github.com/sql-hkr/tiny8/blob/main/docs/architecture.md

Illustrates the internal representation of Tiny8 instructions as Python tuples, including mnemonic and operands. This format is used for storing instructions in memory and parsing them during execution.

```python
("ldi", (("reg", 16), 42))      # ldi r16, 42
("add", (("reg", 16), ("reg", 17)))  # add r16, r17
("jmp", ("loop",))              # jmp loop
```

--------------------------------

### Tiny8 Memory Access Examples (Assembly)

Source: https://github.com/sql-hkr/tiny8/blob/main/docs/architecture.md

Demonstrates how to load data from and store data to memory using register-indirect addressing in Tiny8 assembly. It involves setting up address pointers in specific registers (R26, R27) and then using the 'ld' (load) and 'st' (store) instructions.

```text
ldi r26, 0x00        ; Set address low byte
ldi r27, 0x02        ; Set address high byte (address = 0x0200)
ld r16, r26          ; Load byte from address in R26 into R16

; Store to memory
ldi r26, 0x50        ; Address = 0x50
ldi r16, 42          ; Value to store
st r26, r16          ; Store R16 to memory[R26]
```

--------------------------------

### Tiny8 Memory Display Configuration Options

Source: https://github.com/sql-hkr/tiny8/blob/main/README.md

Details the command-line options for configuring the memory display range in the Tiny8 debugger. These options allow users to specify the starting and ending addresses for memory visualization.

```bash
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`)
```

--------------------------------

### Tiny8 Number Parsing Formats

Source: https://github.com/sql-hkr/tiny8/blob/main/docs/assembly_language.md

Shows the different number formats recognized by the Tiny8 assembler, including decimal, negative decimal, hexadecimal (0x and $), and binary.

```asm
; Decimal: 42
; Negative decimal: -10 (stored as 246 in 8-bit)
; Hexadecimal (0x): 0xFF (255)
; Hexadecimal ($): $FF (255)
; Binary: 0b11111111 (255)
```

--------------------------------

### Tiny8 Python: Inspecting CPU State

Source: https://github.com/sql-hkr/tiny8/blob/main/docs/getting_started.md

Provides examples of how to inspect the state of a Tiny8 CPU instance within Python. This includes reading register values, memory contents, checking status flags, and accessing trace information for registers and memory.

```python
# Read registers
value = cpu.read_reg(16)

# Read memory
mem_value = cpu.mem.read(0x0100)

# Check flags
zero_flag = cpu.get_flag(1)  # Z flag
carry_flag = cpu.get_flag(0)  # C flag

# Get trace information
reg_changes = cpu.reg_trace
mem_changes = cpu.mem_trace

```

--------------------------------

### Tiny8 Assembly: Immediate Value Operand Formats

Source: https://github.com/sql-hkr/tiny8/blob/main/docs/assembly_language.md

Demonstrates the different formats for specifying immediate values (constants) in Tiny8 assembly instructions. Supports decimal (default), hexadecimal (0x or $ prefix), and binary (0b prefix). An optional '#' prefix can also be used.

```asm
; Decimal
ldi r16, 42          ; Decimal 42
ldi r17, 255         ; Decimal 255
ldi r18, -1          ; Negative values allowed

; Hexadecimal
ldi r16, 0xFF        ; Hexadecimal FF (255)
ldi r17, $A5         ; Hexadecimal A5 (165)
ldi r18, 0x10        ; Hexadecimal 10 (16)

; Binary
ldi r16, 0b11111111  ; Binary (255)
ldi r17, 0b10101010  ; Binary (170)
ldi r18, 0b00001111  ; Binary (15)

; With Immediate Marker
ldi r16, #42         ; # is optional and ignored
ldi r17, #0xFF

```

--------------------------------

### Tiny8 Main Loop Structure

Source: https://github.com/sql-hkr/tiny8/blob/main/docs/assembly_language.md

Demonstrates a typical main execution loop in Tiny8 assembly, including reading input, calling a processing subroutine, writing output, and repeating the loop.

```asm
main:
    ; Read input
    lds r16, input_addr

    ; Process
    call process_data

    ; Write output
    sts output_addr, r16

    ; Repeat
    jmp main
```

--------------------------------

### Tiny8 Assembly: Label Definition and Usage

Source: https://github.com/sql-hkr/tiny8/blob/main/docs/assembly_language.md

Illustrates how to define and use labels in Tiny8 assembly. Labels mark locations in the program and are terminated by a colon (`:`). They are essential for control flow, such as jump and branch targets.

```asm
start:               ; Label on its own line
    ldi r16, 0

loop: dec r16        ; Label before instruction
    brne loop

; Using labels with control flow instructions
    jmp start
    breq equal_handler
    call calculate_sum

subroutine:
    ; ... code ...
    ret

```

--------------------------------

### Run Bubble Sort with Tiny8 Debugger

Source: https://github.com/sql-hkr/tiny8/blob/main/docs/examples/bubblesort.md

Execute the bubble sort example using the Tiny8 interactive debugger. This allows for step-by-step observation of the sorting process, and users can set marks within the code (e.g., at the beginning of inner_loop) to track the progress of each pass.

```bash
tiny8 examples/bubblesort.asm
```

--------------------------------

### Animate Bubble Sort with Tiny8

Source: https://github.com/sql-hkr/tiny8/blob/main/docs/examples/bubblesort.md

Generate an animated GIF of the bubble sort process using Tiny8. This visualization aids in understanding memory and register changes during sorting, showing how values move to their correct positions. Key parameters include memory start and end addresses for the array.

```bash
tiny8 examples/bubblesort.asm -m ani -o bubblesort.gif \
    --mem-start 0x60 --mem-end 0x7F
```

--------------------------------

### CPU Class Initialization and Program Execution in Python

Source: https://context7.com/sql-hkr/tiny8/llms.txt

Demonstrates how to initialize the CPU, assemble and load a program, execute it with a step limit, read register and memory values, check status flags, and inspect the execution trace. Requires the 'tiny8' library and 'matplotlib' for visualization.

```python
from tiny8 import CPU, assemble_file

# Create CPU instance with default memory
cpu = CPU()

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

# Execute program with step limit
cpu.run(max_steps=1000, show_progress=True)

# Read final register values
result = cpu.read_reg(17)  # R17 contains 10th Fibonacci number (55)
print(f"Fibonacci F(10) = {result}")

# Access memory
cpu.write_ram(0x100, 42)
value = cpu.read_ram(0x100)

# Check status register flags
zero_flag = cpu.get_flag(1)  # SREG bit 1 (Z flag)
carry_flag = cpu.get_flag(0)  # SREG bit 0 (C flag)

# Inspect execution trace
for step in cpu.step_trace[:5]:
    print(f"Step {step['step']}: PC=0x{step['pc']:04X}, {step['instr']}")
    print(f"  Registers: {step['regs'][:8]}")  # First 8 registers
    print(f"  SREG: 0x{step['sreg']:02X}")
```

--------------------------------

### Tiny8 CLI Command Syntax and General Options

Source: https://github.com/sql-hkr/tiny8/blob/main/README.md

Illustrates the basic command structure for the Tiny8 CLI tool, specifying the file and optional arguments. It also lists general options available for controlling the execution and displaying information.

```bash
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`)
```

--------------------------------

### Testing with Pytest

Source: https://github.com/sql-hkr/tiny8/blob/main/README.md

Demonstrates common pytest commands for running tests, including running all tests, running tests with coverage reporting (generating an HTML report), and running tests from a specific file.

```bash
pytest
pytest --cov=src/tiny8 --cov-report=html
pytest tests/test_arithmetic.py
```

--------------------------------

### Tiny8 Assembly: Loop Structure Example

Source: https://github.com/sql-hkr/tiny8/blob/main/docs/examples/fibonacci.md

This assembly snippet illustrates a common loop structure used in embedded programming. It initializes a counter register (R18) to a specific value (N) and then enters a loop. Inside the loop, operations are performed, followed by decrementing the counter and branching back to the loop's start if the counter is not zero. This pattern is fundamental for repetitive tasks.

```asm
ldi r18, N          ; Initialize counter
loop:
    ; ... loop body ...
    dec r18         ; Decrement counter
    brne loop       ; Branch if not equal to zero

```

--------------------------------

### CPU Class Initialization and Program Execution

Source: https://context7.com/sql-hkr/tiny8/llms.txt

This section details how to initialize the CPU, load and execute assembly programs, and read register and memory values. It also covers accessing status register flags and inspecting the execution trace.

```APIDOC
## CPU Class Initialization and Program Execution

### Description
Initializes the core 8-bit CPU simulator, loads assembly programs, executes them, and provides methods to inspect the CPU's state, including registers, memory, and status flags.

### Method
Python Class Methods

### Parameters
N/A (Class methods)

### Request Example
```python
from tiny8 import CPU, assemble_file

# Create CPU instance with default memory
cpu = CPU()

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

# Execute program with step limit
cpu.run(max_steps=1000, show_progress=True)

# Read final register values
result = cpu.read_reg(17)  # R17 contains 10th Fibonacci number (55)
print(f"Fibonacci F(10) = {result}")

# Access memory
cpu.write_ram(0x100, 42)
value = cpu.read_ram(0x100)

# Check status register flags
zero_flag = cpu.get_flag(1)  # SREG bit 1 (Z flag)
carry_flag = cpu.get_flag(0)  # SREG bit 0 (C flag)

# Inspect execution trace
for step in cpu.step_trace[:5]:
    print(f"Step {step['step']}: PC=0x{step['pc']:04X}, {step['instr']}")
    print(f"  Registers: {step['regs'][:8]}")  # First 8 registers
    print(f"  SREG: 0x{step['sreg']:02X}")
```

### Response
#### Success Response
Execution results, register values, memory contents, status flags, and execution trace data.

#### Response Example
```json
{
  "result": 55, 
  "memory_value_at_0x100": 42,
  "zero_flag": 0, 
  "carry_flag": 0,
  "execution_trace_sample": [
    {
      "step": 1,
      "pc": "0x0000",
      "instr": "LDI R16, 0",
      "regs": [0, 0, ...],
      "sreg": "0x00"
    }
  ]
}
```
```

--------------------------------

### Control tiny8 Execution and Visualization via CLI

Source: https://context7.com/sql-hkr/tiny8/llms.txt

The command-line interface (CLI) tool allows for assembly, execution, and visualization of programs. It supports basic execution with an interactive debugger, animated visualization generation, custom memory range display, adjustable playback speed, and high-quality video output with configurable settings.

```bash
# Basic execution with interactive debugger
tiny8 program.asm

# Generate animated visualization
tiny8 fibonacci.asm -m ani -o fibonacci.gif

# Custom memory range display (hex addresses supported)
tiny8 bubblesort.asm --mem-start 0x60 --mem-end 0x7F

# Slow playback for teaching (0.5 seconds per step)
tiny8 program.asm -d 0.5

# High-quality video with custom settings
tiny8 bubblesort.asm -m ani -o output.mp4 \
    --fps 30 \
    --plot-every 50 \
    --mem-start 96 \
    --mem-end 127

# Long-running program with increased step limit
tiny8 complex.asm --max-steps 50000

# Fast animation generation
tiny8 program.asm -m ani -o demo.gif -f 60 -i 1 -pe 200

```

--------------------------------

### Create Animation using Python API

Source: https://github.com/sql-hkr/tiny8/blob/main/docs/visualization.md

Demonstrates how to programmatically create an execution animation using the tiny8 Python API. This involves assembling code, running it on a simulated CPU, and then using the Visualizer class to generate the animation file.

```python
from tiny8 import CPU, assemble, Visualizer

# Create and run program
code = """
    ldi r16, 0
    ldi r17, 10
loop:
    add r16, r17
    dec r17
    brne loop
"""

asm = assemble(code)
cpu = CPU()
cpu.load_program(asm)
cpu.run(max_steps=100)

# Create visualization
viz = Visualizer(cpu)
viz.animate_execution(
    mem_addr_start=0x0200,
    mem_addr_end=0x02FF,
    filename="my_animation.gif",
    interval=200,  # ms between frames
    fps=30,
    cmap="viridis"  # matplotlib colormap
)
```

--------------------------------

### Tiny8 Assembly: Loading Immediate Values

Source: https://github.com/sql-hkr/tiny8/blob/main/docs/getting_started.md

Illustrates how to load immediate values into registers using different number formats: decimal, hexadecimal, and binary.

```asm
ldi r16, 42         ; Load decimal
lDi r17, 0xFF       ; Load hexadecimal
lDi r18, 0b1010     ; Load binary

```

--------------------------------

### Reverse Array in Place using Tiny8 Assembly

Source: https://github.com/sql-hkr/tiny8/blob/main/docs/examples/reverse.md

This code snippet reverses an array stored in RAM starting at address 0x60. It uses two pointers, one starting at the beginning of the array and the other at the end. The pointers move towards each other, swapping the elements they point to until they meet or cross. The array is modified in place.

```assembly
; Reverse: reverse array [10, 20, 30, 40, 50, 60]
; Output: RAM[0x60..0x65] = [60, 50, 40, 30, 20, 10]

start:
    ; store array at RAM[0x60..0x65]
    ldi r20, 0x60
    ldi r21, 10
    st r20, r21
    
    ldi r20, 0x61
    ldi r21, 20
    st r20, r21
    
    ldi r20, 0x62
    ldi r21, 30
    st r20, r21
    
    ldi r20, 0x63
    ldi r21, 40
    st r20, r21
    
    ldi r20, 0x64
    ldi r21, 50
    st r20, r21
    
    ldi r20, 0x65
    ldi r21, 60
    st r20, r21
    
    ; reverse: swap from both ends
    ldi r16, 0x60     ; left = 0x60
    ldi r17, 0x65     ; right = 0x65

reverse_loop:
    ; check if left >= right
    cp r16, r17
    brge done
    
    ; swap RAM[left] and RAM[right]
    ld r18, r16       ; temp = RAM[left]
    ld r19, r17       ; RAM[left] = RAM[right]
    st r16, r19
    st r17, r18       ; RAM[right] = temp
    
    ; move pointers
    inc r16           ; left++
    dec r17           ; right--
    
    jmp reverse_loop

done:
    jmp done

```

--------------------------------

### Use Tiny8 Python API to Run Program

Source: https://github.com/sql-hkr/tiny8/blob/main/docs/index.md

Demonstrates how to use the Tiny8 Python API to assemble and run an assembly program. It involves importing the CPU and assemble_file functions, loading the program, running it, and reading the result from a register.

```python
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

```

--------------------------------

### Execute Tiny8 Assembly Program using Python

Source: https://github.com/sql-hkr/tiny8/blob/main/README.md

Shows how to use the Tiny8 Python library to assemble and run an assembly file. It demonstrates loading a program, executing it, and then reading the modified memory contents to verify the sorting result.

```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)])
```

--------------------------------

### Assembly Language Programming and Parsing in Python

Source: https://context7.com/sql-hkr/tiny8/llms.txt

Shows how to assemble inline assembly code using the 'assemble' function, which returns program length, labels, and the instruction list. It then demonstrates loading and executing this assembled program with the CPU class and retrieving results. Requires the 'tiny8' library.

```python
from tiny8 import assemble, CPU

# Assemble inline assembly code
asm_code = """
; Calculate sum of 1 to N
    ldi r16, 0          ; sum = 0
    ldi r17, 1          ; i = 1
    ldi r18, 10         ; N = 10

loop:
    add r16, r17        ; sum += i
    inc r17             ; i++
    ldi r19, 11
    cp r17, r19         ; compare i with N+1
    brne loop           ; continue if i != N+1

done:
    jmp done            ; halt
"""

result = assemble(asm_code)
print(f"Program length: {len(result.program)} instructions")
print(f"Labels: {result.labels}")  # {'loop': 3, 'done': 8}
print(f"First instruction: {result.program[0]}")  # ('LDI', (('reg', 16), 0))

# Execute assembled program
cpu = CPU()
cpu.load_program(result)
cpu.run(max_steps=200)
sum_result = cpu.read_reg(16)
print(f"Sum of 1 to 10 = {sum_result}")  # 55
```

--------------------------------

### Tiny8 Program Termination

Source: https://github.com/sql-hkr/tiny8/blob/main/docs/assembly_language.md

Illustrates methods for program termination in Tiny8 assembly, typically by creating an infinite loop using `jmp` or a `nop` and `jmp` sequence.

```asm
done:
    jmp done         ; Loop forever

; Or explicitly spin
end:
    nop
    jmp end
```

--------------------------------

### Interactive CLI Debugger Usage in Python

Source: https://context7.com/sql-hkr/tiny8/llms.txt

Illustrates launching the terminal-based CLI debugger for a given CPU state. It allows step-through execution, memory inspection, and utilizes various keyboard commands for navigation, searching, and state modification. Requires 'tiny8' library and a pre-assembled program.

```python
from tiny8 import CPU, assemble_file, run_cli

# Prepare and execute program
asm = assemble_file("examples/bubblesort.asm")
cpu = CPU()
cpu.load_program(asm)
cpu.run(max_steps=10000)

# Launch interactive debugger
# Shows memory range 0x60-0x7F where array is stored
# Delay of 0.2s between auto-advance steps
run_cli(
    cpu,
    mem_addr_start=0x60,
    mem_addr_end=0x7F,
    delay=0.2,
    source_lines=asm.source_lines
)

# CLI keyboard commands (used interactively):
# l/h or ←/→  : step forward/backward
# w/b         : jump ±10 steps
# 0/$         : first/last step
# Space       : play/pause
# [/]         : slower/faster playback
# r           : toggle all registers / changed only
# M           : toggle all memory / non-zero only
# j/k         : scroll memory view
# :123        : jump to step 123
# :+50        : jump forward 50 steps
# :/ldi       : search forward for "ldi" instruction
# :?add       : search backward for "add" instruction
# :@0x100     : jump to PC address 0x100
# :r16        : find next change to register R16
# :r16=42     : find where R16 equals 42
# :m100       : find next change to memory[100]
# :m0x60=0xFF : find where memory[0x60] equals 0xFF
# :fZ         : find next change to Zero flag
# :fC=1       : find where Carry flag equals 1
# ma          : set mark 'a'
# 'a          : jump to mark 'a'
```

--------------------------------

### Visualize Program Execution with tiny8 Python API

Source: https://context7.com/sql-hkr/tiny8/llms.txt

Generates animated GIFs and MP4 videos of program execution, static plots of register history, memory access heatmaps, SREG flag activity, and execution statistics. Requires the CPU and Visualizer classes from the tiny8 library. Inputs include memory addresses, filenames, and animation parameters.

```python
from tiny8 import CPU, assemble_file, Visualizer

# Load and execute bubble sort
asm = assemble_file("examples/bubblesort.asm")
cpu = CPU()
cpu.load_program(asm)
cpu.run(max_steps=15000)

# Create visualizer
viz = Visualizer(cpu)

# Generate animated GIF showing execution
viz.animate_execution(
    mem_addr_start=0x60,      # Display memory range 0x60-0x7F
    mem_addr_end=0x7F,
    filename="bubblesort.gif",
    interval=1,               # 1ms between frames
    fps=60,                   # 60 frames per second
    fontsize=9,
    cmap="inferno",           # Color scheme
    plot_every=100            # Update plot every 100 steps (performance)
)

# Generate MP4 video instead
viz.animate_execution(
    mem_addr_start=0x60,
    mem_addr_end=0x7F,
    filename="bubblesort.mp4",
    interval=1,
    fps=30,
    plot_every=50
)

# Show static register history plot
viz.show_register_history(
    registers=[16, 17, 18, 19],  # Track R16-R19
    figsize=(14, 8)
)

# Show memory access heatmap
viz.show_memory_access(
    mem_addr_start=0x60,
    mem_addr_end=0x7F,
    figsize=(12, 8)
)

# Show SREG flag activity over time
viz.show_flag_history(figsize=(14, 6))

# Show execution statistics
viz.show_statistics(top_n=10)  # Top 10 instructions and memory locations

```

--------------------------------

### Tiny8 Assembly: Count Down Loop

Source: https://github.com/sql-hkr/tiny8/blob/main/docs/getting_started.md

A Tiny8 assembly code example that implements a loop to count down from 10 to 0. It uses the 'dec' instruction to decrement a register and 'brne' to branch if the result is not zero.

```asm
; Count down from 10 to 0
    ldi r16, 10

loop:
    dec r16             ; Decrement R16
    brne loop           ; Branch if not equal to zero

; Continue execution here

```

--------------------------------

### Interactive CLI Debugger

Source: https://context7.com/sql-hkr/tiny8/llms.txt

Launches an interactive terminal-based debugger that allows step-through execution, register and memory inspection, and navigation using vim-style commands.

```APIDOC
## Interactive CLI Debugger

### Description
Starts an interactive command-line interface (CLI) debugger for the Tiny8 CPU. This debugger allows for granular control over program execution, enabling users to step forward/backward, play/pause, adjust playback speed, and inspect/search register and memory states.

### Method
Python Function

### Parameters
- **cpu** (CPU object) - The CPU instance to debug.
- **mem_addr_start** (int) - Optional - The starting memory address to display in the debugger.
- **mem_addr_end** (int) - Optional - The ending memory address to display in the debugger.
- **delay** (float) - Optional - The delay in seconds between auto-advance steps when playing.
- **source_lines** (dict) - Optional - A dictionary mapping line numbers to source code strings for displaying source code alongside execution.

### Request Example
```python
from tiny8 import CPU, assemble_file, run_cli

# Prepare and execute program
asm = assemble_file("examples/bubblesort.asm")
cpu = CPU()
cpu.load_program(asm)
cpu.run(max_steps=10000)

# Launch interactive debugger
# Shows memory range 0x60-0x7F where array is stored
# Delay of 0.2s between auto-advance steps
run_cli(
    cpu,
    mem_addr_start=0x60,
    mem_addr_end=0x7F,
    delay=0.2,
    source_lines=asm.source_lines
)

# CLI keyboard commands (used interactively):
# l/h or ←/→  : step forward/backward
# w/b         : jump ±10 steps
# 0/$         : first/last step
# Space       : play/pause
# [/]         : slower/faster playback
# r           : toggle all registers / changed only
# M           : toggle all memory / non-zero only
# j/k         : scroll memory view
# :123        : jump to step 123
# :+50        : jump forward 50 steps
# :/ldi       : search forward for "ldi" instruction
# :?add       : search backward for "add" instruction
# :@0x100     : jump to PC address 0x100
# :r16        : find next change to register R16
# :r16=42     : find where R16 equals 42
# :m100       : find next change to memory[100]
# :m0x60=0xFF : find where memory[0x60] equals 0xFF
# :fZ         : find next change to Zero flag
# :fC=1       : find where Carry flag equals 1
# ma          : set mark 'a'
# 'a          : jump to mark 'a'
```

### Response
#### Success Response
Launches an interactive terminal interface. No direct return value, but modifies the execution flow.

#### Response Example
(Interactive Terminal Output - No direct JSON response)
```

--------------------------------

### Generate Basic Animation (Bash)

Source: https://github.com/sql-hkr/tiny8/blob/main/docs/visualization.md

Generates a basic animation GIF of program execution using the tiny8 command-line tool. The output includes SREG flag evolution, register heatmaps, and memory contents.

```bash
tiny8 program.asm -m ani -o output.gif
```

--------------------------------

### Build Tiny8 Documentation

Source: https://github.com/sql-hkr/tiny8/blob/main/CONTRIBUTING.md

Commands for building the documentation for the Tiny8 project using Sphinx. This includes generating API documentation, building HTML files, and opening the generated documentation.

```bash
# Generate API documentation
sphinx-apidoc -efo docs/api/ src/

# Build HTML docs
cd docs
make html

# View docs
open _build/html/index.html  # macOS
# or
xdg-open _build/html/index.html  # Linux
# or
start _build/html/index.html  # Windows
```

--------------------------------

### Tiny8 Python: Step-by-Step Execution

Source: https://github.com/sql-hkr/tiny8/blob/main/docs/getting_started.md

Shows how to assemble assembly code directly from a string and execute it step-by-step using the Tiny8 Python API. This allows for granular control and inspection during program execution.

```python
from tiny8 import CPU, assemble

# Parse assembly code directly
code = """
    ldi r16, 10
    ldi r17, 5
    sub r16, r17
"""
asm = assemble(code)

# Set up and run
cpu = CPU()
cpu.load_program(asm)

# Step through manually
while cpu.pc < len(cpu.program):
    print(f"Step {cpu.step_count}: PC={cpu.pc}")
    cpu.step()
    if cpu.step_count > 10:
        break

print(f"Final result: R16 = {cpu.read_reg(16)}")

```

--------------------------------

### Tiny8 Assembly: Memory Address Operand Usage

Source: https://github.com/sql-hkr/tiny8/blob/main/docs/assembly_language.md

Illustrates the use of memory addresses as operands in Tiny8 assembly, primarily with load (lds) and store (sts) instructions. Both hexadecimal and decimal representations of memory addresses are supported.

```asm
lds r16, 0x0200      ; Load from address 0x0200
sts 0x0300, r16      ; Store to address 0x0300
lds r17, 512         ; Decimal addresses also work

```

--------------------------------

### Manual Step-by-Step Execution and Debugging with tiny8

Source: https://context7.com/sql-hkr/tiny8/llms.txt

Enables low-level, step-by-step execution of assembly code for detailed debugging. It allows inspection of CPU state (PC, registers, SREG) after each instruction, access to execution traces (instructions, register changes, memory changes), and implements conditional breakpoints based on register values.

```python
from tiny8 import CPU, assemble

# Simple program to demonstrate stepping
code = """
    ldi r16, 5
    ldi r17, 3
    add r16, r17    ; r16 = 5 + 3 = 8
    mul r16, r17    ; r16:r17 = 8 * 3 = 24
    nop
"""

cpu = CPU()
asm = assemble(code)
cpu.load_program(asm)

# Manual step-by-step execution
while cpu.pc < len(cpu.program):
    # Capture pre-execution state
    pc_before = cpu.pc
    r16_before = cpu.read_reg(16)

    # Execute one instruction
    success = cpu.step()
    if not success:
        break

    # Inspect post-execution state
    step_info = cpu.step_trace[-1]
    print(f"Step {cpu.step_count}:")
    print(f"  Executed: {step_info['instr']}")
    print(f"  PC: 0x{pc_before:04X} → 0x{cpu.pc:04X}")
    print(f"  R16: {r16_before} → {cpu.read_reg(16)}")
    print(f"  SREG: 0x{cpu.sreg:02X}")

    # Access register trace changes
    if cpu.reg_trace:
        last_reg_change = cpu.reg_trace[-1]
        step, reg, val = last_reg_change
        print(f"  Register change: R{reg} = {val}")

    # Conditional breakpoint
    if cpu.read_reg(16) == 8:
        print("  BREAKPOINT: R16 reached 8")
        # Inspect or modify state here
        break

# Final state inspection
print(f"\nFinal state:")
print(f"  R16 = {cpu.read_reg(16)}")
print(f"  R17 = {cpu.read_reg(17)}")
print(f"  Total steps: {cpu.step_count}")
print(f"  Register changes: {len(cpu.reg_trace)}")
print(f"  Memory changes: {len(cpu.mem_trace)}")

```

--------------------------------

### Tiny8 Assembly: Register Operand Usage

Source: https://github.com/sql-hkr/tiny8/blob/main/docs/assembly_language.md

Shows how to use register operands in Tiny8 assembly. Registers are denoted by 'r' followed by their number (0-31). Note that some instructions, like 'ldi', have restrictions on which registers they can use (R16-R31).

```asm
mov r0, r1           ; R0-R31 are valid
add r16, r17
ldi r31, 255

```

--------------------------------

### Generate Advanced Animation with Options (Bash)

Source: https://github.com/sql-hkr/tiny8/blob/main/docs/visualization.md

Creates an animation (GIF or MP4) with advanced options, specifying the output filename, memory visualization range, frame interval, and frames per second. This allows for more detailed and customized visual outputs.

```bash
tiny8 program.asm -m ani \
    --output animation.gif \
    --mem-start 0x0200 \
    --mem-end 0x02FF \
    --interval 200 \
    --fps 30
```

--------------------------------

### Clone Tiny8 Repository

Source: https://github.com/sql-hkr/tiny8/blob/main/CONTRIBUTING.md

Steps to fork and clone the Tiny8 project repository using Git. This is the initial step for any contribution.

```bash
git clone https://github.com/YOUR_USERNAME/tiny8.git
cd tiny8
```
Tokens:
Raw