Visualization¶

Tiny8 provides two powerful visualization tools to help you understand program execution: an interactive terminal debugger and a graphical animation system for generating videos.

Terminal Debugger¶

The interactive terminal debugger provides a comprehensive, real-time view of your program execution with Vim-style keyboard controls.

Launching the Debugger¶

Run any assembly program with the tiny8 command:

tiny8 program.asm

This opens the terminal-based visualizer showing your program state.

Interface Overview¶

The debugger interface is divided into several sections:

┌─────────────────────────────────────────────┐
│          SOURCE CODE (with PC)              │
│  Shows your assembly with current line      │
├─────────────────────────────────────────────┤
│              REGISTERS                      │
│  R0-R31 with changed values highlighted     │
├─────────────────────────────────────────────┤
│            STATUS FLAGS (SREG)              │
│  I T H S V N Z C - visual indicators        │
├─────────────────────────────────────────────┤
│               MEMORY                        │
│  RAM contents with addresses and values     │
├─────────────────────────────────────────────┤
│            CONTROL INFO                     │
│  PC, SP, Step count, Help hint              │
└─────────────────────────────────────────────┘

Keyboard Controls¶

Navigation¶

Key	Action
`l` or `→`	Step forward one instruction
`h` or `←`	Step backward one instruction
`0`	Go to first step
`$`	Go to last step
`w`	Jump forward 10 steps
`b`	Jump backward 10 steps
`Space`	Toggle play/pause mode
`[` / `]`	Slower/faster playback speed

Auto-Play Mode¶

Press Space to automatically advance through execution:

Program steps forward continuously
Use [ and ] to adjust playback speed (slower/faster)
Press Space again to pause
Press l/h to take manual control

Commands and Search¶

Press : to enter command mode for advanced navigation:

Command Examples:

123 - Jump to step 123
+50 - Jump forward 50 steps
-20 - Jump backward 20 steps
/add - Search forward for “add” instruction
?ldi - Search backward for “ldi” instruction
@100 - Jump to PC address 100
r10 - Find next change to register R10
r10=42 - Find where R10 equals 42
m100 - Find next change to memory[100]
m100=0xFF - Find where memory[100] equals 0xFF
fZ - Find next change to flag Z
fC=1 - Find where flag C equals 1
h or help - Show command help

Marks and Bookmarks¶

Set marks to quickly jump to important execution points:

Key	Action
`m` + letter	Set mark at current step (e.g., `ma`, `mb`)
`'` + letter	Jump to mark (e.g., `'a`, `'b`)

Example workflow:

Step to an interesting point: ma (set mark ‘a’)
Explore elsewhere in execution
Return instantly: 'a (jump to mark ‘a’)

View Options¶

Key	Action
`r`	Toggle between changed/all registers view
`M`	Toggle between non-zero/all memory view
`j`	Scroll memory view down
`k`	Scroll memory view up
`=`	Show detailed step information

Other Controls¶

Key	Action
`/`	Show help screen
`q` or `Esc`	Quit debugger

Visual Indicators¶

Change Highlighting¶

The debugger highlights changes at each step:

Registers: Changed values appear in a different color
Flags: Set flags are highlighted
Memory: Modified memory cells are marked
PC indicator: Shows current instruction with ► or color

Understanding the Display¶

Registers Display

R0:  000  R1:  000  R2:  000  R3:  000
R16: 042  R17: 010  R18: 005  R19: 000
     ^^^       ^^^  (highlighted if changed)

Status Flags (SREG)

SREG: [I:0] [T:0] [H:0] [S:0] [V:0] [N:0] [Z:1] [C:0]
                                          ^^^
                                          (set flags highlighted)

Memory Display

0x0200: 42  ← Changed this step
0x0201: 00
0x0202: FF  ← Changed this step

Tips and Tricks¶

Debugging Workflow¶

Set marks at key points: Before loops, after calculations
Use search: Find where registers or memory addresses are accessed
Toggle views: Show only changed registers when debugging large programs
Auto-play: Watch algorithm execution in real-time

Finding Issues¶

Infinite loops: Watch step counter; if PC stops changing, you’re stuck
Wrong results: Step through and watch registers; mark where values diverge
Memory issues: Search for memory addresses; check reads/writes
Flag problems: Watch SREG; verify flags after comparisons

Graphical Animation¶

Generate high-quality GIF or MP4 videos showing program execution with register and memory evolution.

Basic Animation¶

Create an animation from your program:

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

This generates output.gif showing:

SREG flag evolution over time
All 32 registers as a heatmap
Memory contents in a specified range

Advanced Options¶

Command-Line Arguments¶

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

Option	Description
`-m ani`	Enable animation mode
`-o FILE`	Output filename (.gif or .mp4)
`--mem-start ADDR`	Start address for memory visualization
`--mem-end ADDR`	End address for memory visualization
`--interval MS`	Milliseconds per frame
`--fps N`	Frames per second (for video)

Animation Layout¶

The generated animation has three panels:

Top Panel: SREG Flags: 8 rows showing each flag (I, T, H, S, V, N, Z, C) over time * Bright = flag set (1) * Dark = flag clear (0)
Middle Panel: Registers: 32 rows (R0-R31) showing register values over time * Color intensity = value (0-255) * Bright = high values * Dark = low values
Bottom Panel: Memory: Selected memory range showing contents over time * Same color scheme as registers * Track data structure evolution

Reading the Animation¶

Time Axis (Horizontal): Each column represents one execution step * Left side: Program start * Right side: Program end * Watch values change across time
Value Axis (Vertical): Each row is a register or memory location * Track individual items vertically * See patterns and data flow

Example Use Cases¶

Visualizing Algorithms¶

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

Watch the sorting algorithm:

Registers holding array indices
Memory showing array elements being swapped
Flags changing during comparisons

Debugging Data Flow¶

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

Observe:

R16 and R17 alternating as Fibonacci numbers grow
Loop counter (R18) decrementing
Flag changes at each iteration

Presentations and Education¶

Animations are perfect for:

Teaching computer architecture concepts
Explaining algorithms visually
Documenting program behavior
Creating engaging educational content

Python API for Visualization¶

You can also create visualizations programmatically using the Python API.

Using the Visualizer Class¶

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
)

Customization Options¶

The animate_execution method accepts several parameters:

viz.animate_execution(
    mem_addr_start=0x60,      # Start of memory range
    mem_addr_end=0x7F,        # End of memory range
    filename="output.gif",    # Output file
    interval=200,              # Frame interval (ms)
    fps=30,                   # Frames per second
    fontsize=9,               # Label font size
    cmap="inferno",           # Color map name
    plot_every=1              # Downsample: plot every N steps
)

Available colormaps: viridis, plasma, inferno, magma, cividis, cool, hot, and many more from Matplotlib.

Visualization Best Practices¶

For Terminal Debugging¶

Start simple: Run through once to understand program flow
Mark key points: Set marks at loop starts, branches, important calculations
Use search: Find where specific registers/memory are modified
Toggle views: Hide unchanged registers for clarity in large programs
Auto-play for overview: Watch execution flow at high level

For Animations¶

Choose memory range carefully: Show only relevant data
Adjust frame rate: Slower for detailed analysis, faster for overview
Pick good colormaps: High contrast for presentations, perceptually uniform for analysis
Downsample long programs: Use plot_every to skip steps
Combine with comments: Explain what viewers should watch for

Performance Tips¶

For very long-running programs:

Use max_steps parameter to limit execution
Enable plot_every downsampling for animations
Focus memory range on active data regions
Consider using the CLI debugger instead of generating full animation