diff --git a/.gitignore b/.gitignore index 3a0c30d..c929cde 100644 --- a/.gitignore +++ b/.gitignore @@ -6,6 +6,8 @@ dist/ wheels/ *.egg-info .pytest_cache/ +.ruff_cache/ +data/ # Virtual environments .venv @@ -15,4 +17,6 @@ wheels/ # sphinx docs/_build/ -docs/api/ \ No newline at end of file +docs/api/ +*.mo +.doctrees/ \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d3dab86..8919127 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,36 +4,36 @@ Thank you for your interest in contributing to Tiny8! This guide will help you g Whether you're fixing a bug, adding a feature, improving documentation, or creating new assembly examples, your contributions are welcome and appreciated. -## ๐ŸŒŸ Ways to Contribute +## Ways to Contribute -### ๐Ÿ› Bug Reports +### Bug Reports - Search [existing issues](https://github.com/sql-hkr/tiny8/issues) first - Provide a clear description and minimal reproduction steps - Include your Python version and operating system - Add relevant code snippets or assembly programs -### ๐Ÿ’ก Feature Requests +### Feature Requests - Open an issue describing the feature and its use case - Discuss design decisions before implementing large changes - Consider backward compatibility and educational value -### ๐Ÿ“ Documentation +### Documentation - Fix typos and improve clarity - Add more code examples - Enhance API documentation - Create tutorials or guides -### ๐ŸŽ“ Assembly Examples +### Assembly Examples - Create educational assembly programs - Document algorithms and implementation details - Add visualizations demonstrating key concepts -### ๐Ÿงช Testing +### Testing - Improve test coverage - Add edge case tests - Test on different platforms -## ๐Ÿš€ Getting Started +## Getting Started ### Prerequisites @@ -87,7 +87,7 @@ Whether you're fixing a bug, adding a feature, improving documentation, or creat tiny8 examples/fibonacci.asm ``` -## ๐Ÿงช Testing +## Testing ### Running Tests @@ -135,7 +135,7 @@ def test_feature_name(): assert cpu.read_reg(16) == expected_value ``` -## ๐ŸŽจ Code Style +## Code Style ### Linting and Formatting @@ -183,7 +183,7 @@ def execute_instruction(self, opcode: int, operands: list[int]) -> None: # Implementation ``` -## ๐Ÿ“š Documentation +## Documentation ### Building Documentation @@ -211,7 +211,7 @@ start _build/html/index.html # Windows - Update `docs/index.rst` for significant features - Include code examples in docstrings when helpful -## ๐ŸŽฏ Assembly Examples +## Assembly Examples ### Creating Examples @@ -251,7 +251,7 @@ done: - **Test coverage**: Add corresponding unit tests - **Documentation**: Reference in README or docs if significant -## ๐Ÿ”„ Pull Request Process +## Pull Request Process ### Before Submitting @@ -300,14 +300,14 @@ Before submitting your PR, ensure: - [ ] Branch is up-to-date with main - [ ] No unrelated changes included -## ๐Ÿ” Code Review Process +## Code Review Process - Maintainers will review PRs within a few days - Address feedback constructively - Push additional commits to the same branch - Request re-review after addressing comments -## ๐ŸŒ Community Guidelines +## Community Guidelines ### Code of Conduct @@ -323,7 +323,7 @@ Before submitting your PR, ensure: - **Discussions**: Use GitHub Discussions for questions and ideas - **Email**: For security issues only (see below) -## ๐Ÿ”’ Security Issues +## Security Issues If you discover a security vulnerability: @@ -332,21 +332,21 @@ If you discover a security vulnerability: 3. Provide detailed information about the vulnerability 4. Allow time for a fix before public disclosure -## ๐Ÿ“„ License +## License By contributing to Tiny8, you agree that your contributions will be licensed under the [MIT License](LICENSE). Your contributions will be attributed in the project's commit history and release notes. -## โ“ Questions? +## Questions? - Check the [documentation](https://sql-hkr.github.io/tiny8/) - Search [existing issues](https://github.com/sql-hkr/tiny8/issues) - Open a new issue for discussion - Join [GitHub Discussions](https://github.com/sql-hkr/tiny8/discussions) -## ๐Ÿ™ Thank You! +## Thank You! Thank you for taking the time to contribute to Tiny8! Your efforts help make this project a better learning tool for everyone exploring computer architecture. -Every contribution, no matter how small, makes a difference. We appreciate your support! โญ +Every contribution, no matter how small, makes a difference. We appreciate your support! diff --git a/README.md b/README.md index b4bd250..e0547a6 100644 --- a/README.md +++ b/README.md @@ -6,47 +6,62 @@ [![CI](https://github.com/sql-hkr/tiny8/actions/workflows/ci.yml/badge.svg)](https://github.com/sql-hkr/tiny8/actions/workflows/ci.yml) [![codecov](https://codecov.io/github/sql-hkr/tiny8/graph/badge.svg?token=OBM58R8MCL)](https://codecov.io/github/sql-hkr/tiny8) -> **An educational 8-bit CPU simulator with interactive visualization** +> **From bare-metal computer architecture to Generative AI โ€” an educational 8-bit AVR RISC CPU simulator with real-time 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. +Tiny8 is a lightweight educational toolkit that bridges bare-metal computer architecture and modern Generative AI. Designed for hands-on learning and experimentation, it guides you through the full stack of computing โ€” from 32 general-purpose registers, ALU operations, stack frames, and C compilation up to executing an iterative reverse-diffusion model synthesizing 28x28 MNIST digits directly on an AVR 8-bit RISC processor. With an interactive Vim-inspired terminal debugger, time-travel reverse execution, and a 32x32 TrueColor memory heatmap, Tiny8 lets you see, step through, and understand computation at every level.
- Animated bubble sort visualization -

Real-time visualization of a bubble sort algorithm executing on Tiny8

+ Native 28x28 Generative Diffusion synthesis executing at x5,000 speed in Tiny8 TUI +

Real-time generative reverse-diffusion synthesis (MNIST digit 8) executing at x5,000 speed in Tiny8 TUI (HEX mode for weight/LFSR init → PIXEL mode for reverse denoising trajectory)

-## โœจ Features +## Features -### ๐ŸŽฏ **Interactive Terminal Debugger** -CLI visualizer screenshot +### **Modern Textual TUI Debugger & Dashboard** +- **Reactive Terminal Dashboard**: Real-time panels with gradient heatmap bars, SREG condition timeline, call stack, and memory dump +- **Bottom statusline**: High-contrast mode badges (`NORMAL`, `RUNNING`, `INSERT`, `COMMAND`), file progress, and key hints (`h: help`) +- **Interactive controls**: Step forward/back (`n`/`p`), continue (`c`), toggle breakpoint (`b`), play/pause (`Space`), speed control (`+`/`-`), TUI application help guide (`h` / `?`), and instruction inspector modal (`i`) +- **Seamless Vim Editor**: Press `e` anytime to jump into the built-in editor, modify code, and hit `:run` to debug -- **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 +### **Built-in Vim-Style Modal Editor** +- **Standalone file creation & editing**: Run `tiny8` or `tiny8 my_prog.c` to create and edit files directly inside the terminal +- **Complete Vim modes**: + - `NORMAL`: `h`/`j`/`k`/`l` movement, `w`/`b` word jump, `0`/`$` line limits, `gg`/`G` bounds, `x` delete char, `dd` delete line, `yy` yank, `p` paste, `u` undo, `Ctrl+r` redo + - `INSERT`: Full typing with syntax highlighting, line numbers, and `` to return to normal mode + - `COMMAND` (`:`): `:w` (save), `:w `, `:q` (exit), `:wq` / `:x` (save and run), `:run` (compile/assemble and launch debugger), `:e ` (switch file) -### ๐ŸŽฌ **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 +### **32x32 Heatmap Memory Dump & Diffusion Synthesis** +- **32x32 Heatmap Memory Grid (1024 Bytes)**: TrueColor gradient heatmap background mapped directly to memory (`0x0200`..`0x05FF` VRAM default), rendering 28x28 MNIST handwritten digits directly inside the memory dump with 1:1 pixel aspect ratio. +- **Embedded Generative AI**: Iterative reverse-diffusion synthesis generating MNIST digits on Tiny8 AVR CPU (`tiny8 examples/diffusion_mnist8.asm`). +- **Viridis & Grayscale Palettes**: Supports both colorful Viridis heatmap and realistic MNIST Grayscale pixel display modes (toggle with `g` for gray/viridis and `x` for hex/pixel). +- **Sample Programs**: Native 28x28 diffusion generation (`tiny8 examples/diffusion_mnist8.asm`) showcasing real-time image synthesis on the 32x32 VRAM heatmap monitor. -### ๐Ÿ—๏ธ **Complete 8-bit Architecture** +### **Built-in C Compiler & Extensions** +- **Compile and run C programs directly**: Write C code (`.c`) and execute on Tiny8 (`tiny8 program.c`) +- **Enhanced C features**: Character literals (`'A'`, `'#'`), string literals, fixed-size arrays (`int arr[4];`), `for` loops, `break;`, logical `&&` and `||`, function calls, `peek()`/`poke()`, and VRAM helpers (`vram_set`, `vram_get`, `vram_puts`, `vram_clear`) +- **Compile-to-assembly inspection**: Generate and inspect clean Tiny8 assembly with `-c` flag + +### **Optimized AVR Instruction Set** +- **Extended SRAM Addressing**: `LDS Rd, k` (Load Direct from SRAM) and `STS k, Rr` (Store Direct to SRAM) for direct 16-bit address access +- **16-bit Pointer Pairs**: Full support for pointer pairs `Z (R31:R30)`, `X (R27:R26)`, and `Y (R29:R28)` with `LD` and `ST` across the entire 64KB address space + + +### **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 +- **64KB address space** for unified memory and I/O - **Stack operations** with dedicated stack pointer -- **AVR-inspired instruction set** with 60+ instructions +- **AVR instruction set** with 67 instructions compliant with Microchip DS40002198A -### ๐Ÿ“š **Educational Focus** +### **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 +## Quick Start ### Installation @@ -83,24 +98,29 @@ done: Run it: ```bash -tiny8 fibonacci.asm # Interactive debugger -tiny8 fibonacci.asm -m ani -o fibonacci.gif # Generate animation +tiny8 fibonacci.asm # Interactive Textual debugger +tiny8 examples/factorial.c # Run C program directly in debugger +tiny8 examples/factorial.c -c # Print compiled Tiny8 assembly ``` ### Python API ```python -from tiny8 import CPU, assemble_file +from tiny8 import CPU, assemble_file, compile_c +# Run assembly program asm = assemble_file("fibonacci.asm") cpu = CPU() cpu.load_program(asm) cpu.run(max_steps=1000) +print(f"Result: R17 = {cpu.read_reg(17)}") -print(f"Result: R17 = {cpu.read_reg(17)}") # Final Fibonacci number +# Or compile and run C code directly! +asm_from_c = compile_c("int main() { return 10 + 32; }") ``` -## ๐Ÿ’ก Why Tiny8? + +## Why Tiny8? **For Students** โ€” Write assembly, see immediate results with visual feedback. Understand how each instruction affects CPU state without abstractions. @@ -108,7 +128,7 @@ print(f"Result: R17 = {cpu.read_reg(17)}") # Final Fibonacci number **For Hobbyists** โ€” Rapid algorithm prototyping at the hardware level with minimal overhead and an extensible, readable codebase. -## ๐Ÿ“– Documentation +## Documentation - [**Full Documentation**](https://sql-hkr.github.io/tiny8/) โ€” Complete API reference and guides - [**Instruction Set Reference**](#instruction-set-reference) โ€” All 60+ instructions @@ -116,45 +136,55 @@ print(f"Result: R17 = {cpu.read_reg(17)}") # Final Fibonacci number - [**Examples**](#examples) โ€” Sample programs with explanations - [**Contributing**](CONTRIBUTING.md) โ€” 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 +## Interactive CLI Controls + +The terminal debugger provides modern modal navigation and inspection capabilities. + +### Navigation & Execution Shortcuts + +- `n` / `p` โ€” Step forward / backward (+1 / -1) +- `c` โ€” Continue run forward until next breakpoint, watchpoint, or program completion +- `C` (Shift+C) โ€” Reverse continue run backward until previous breakpoint or watchpoint +- `b` โ€” Toggle breakpoint at current PC +- `Space` โ€” Play / pause automatic step execution +- `+` / `-` โ€” Increase / decrease playback speed +- `j` / `k` (or `J` / `K`) โ€” Scroll memory dump down / up (by 32-byte line or fast 128-byte page) +- `e` โ€” Open full-screen Vim Editor for source code +- `r` โ€” Reset execution to step 0 +- `h` / `?` โ€” Open TUI application usage & keyboard guide modal +- `i` โ€” Inspect specification & status details for the currently selected instruction +- `q` โ€” Quit debugger + +### Tabbed Views (Inspector & Telemetry) + +- **Registers & Memory** โ€” Gradient heatmap bars for R0..R31 alongside 32x32 memory dump with TrueColor heatmap background (0x0200..0x05FF VRAM) +- **C Variables** โ€” Live symbol table tracking C variable names, types, memory addresses, hex/dec values, and update status +- **Call Stack** โ€” Dynamic function call backtrace reconstructed from execution calls and returns + +### Command Bar (press `:`) + +- `:` or `:goto ` โ€” Jump directly to step number +- `:b ` or `:break ` โ€” Toggle breakpoint at PC (`0x000E` or `14`) +- `:b if ` โ€” Set conditional breakpoint (e.g. `:b 10 if R16 == 42`, `:b 0x12 if mem[0x60] > 0`) +- `:bc` or `:clear` โ€” Clear all breakpoints and conditional breakpoints +- `:watch ` or `:w ` โ€” Add watchpoint on register, memory address, or condition (e.g. `:watch R0`, `:watch mem[0x60]`) +- `:unwatch [expr]` โ€” Remove watchpoint or clear all watchpoints +- `:mark ` โ€” Create bookmark for current execution state +- `:'` or `:goto ` โ€” Jump to bookmarked step +- `:c` or `:run` โ€” Continue execution to next breakpoint +- `:rc` or `:rev` โ€” Reverse continue execution backward +- `:set R ` โ€” Live modify register value in current state (e.g. `:set R16 42`) +- `:poke ` โ€” Live modify memory value at address (e.g. `:poke 0x60 255`) +- `:exec ` โ€” Mini REPL: assemble and execute an instruction on the fly (e.g. `:exec LDI R17, 88`) +- `:mem ` or `:m ` โ€” Jump memory view to address (`0x0060`) +- `:find ` โ€” Search forward for instruction +- `:e [file]` โ€” Open Vim editor for file +- `:r` or `:reset` โ€” Reset to step 0 +- `:h` or `:help` โ€” Show instruction reference modal +- `:q` or `:quit` โ€” Exit tiny8 +- `` โ€” Cancel command bar / close modal dialog + +## Examples The `examples/` directory contains programs demonstrating key concepts: @@ -162,18 +192,17 @@ The `examples/` directory contains programs demonstrating key concepts: |---------|-------------| | `fibonacci.asm` | Fibonacci sequence using registers | | `bubblesort.asm` | Sorting algorithm with memory visualization | -| `factorial.asm` | Recursive factorial calculation | +| `diffusion_mnist8.asm` | Native 28x28 MNIST digit generation using an iterative reverse diffusion process | | `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: +Sort 32 pseudo-random bytes in ascending order (RAM 0x60..0x7F): ```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 +tiny8 examples/bubblesort.asm ``` ### Using Python @@ -188,166 +217,169 @@ cpu.run() print("Sorted:", [cpu.read_ram(i) for i in range(0x60, 0x80)]) ``` -## ๐Ÿ”ง CLI Options +## CLI Options ### Command Syntax ```bash -tiny8 FILE [OPTIONS] +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`) | +| `-e, --edit` | Launch directly into Vim editor mode | +| `--max-steps N` | Maximum execution steps (default: until infinite loop or halt) | +| `-c, --compile-only` | Compile C program and print generated Tiny8 assembly without running | -### Memory Display Options +### Interactive Controls (Textual TUI) -| 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`) | +| Key | Action | +|-----|--------| +| `Space` | Play / Pause auto execution | +| `Shift+Space` | Reverse playback auto execution | +| `n` | Step forward (+1 instruction) | +| `p` | Step backward (-1 instruction, time-travel) | +| `c` | Continue execution forward to next breakpoint | +| `C` (`Shift+c`) | Reverse continue backward to previous breakpoint | +| `b` | Toggle breakpoint on current instruction | +| `:` | Open command line prompt (e.g. `:goto `, `:b `, `:q`) | +| `j` / `k` (or `J` / `K`) | Scroll memory viewport down / up by 32 bytes (or 128-byte fast page) | +| `g` | Toggle Grayscale / Viridis color palette | +| `x` | Toggle Hexadecimal digits (02X) / Graphic Pixel blocks | +| `m` | Cycle view modes (Viridis+Hex -> Viridis+Pixel -> Grayscale+Pixel -> Grayscale+Hex) | +| `e` | Launch full-screen Vim-style modal editor | +| `h` / `?` | Open TUI Application Usage & Keyboard Guide | +| `i` | Open Instruction Reference modal (all 67 instructions) | +| `+` / `-` | Increase / Decrease playback speed | +| `r` | Reset execution back to step 0 | +| `q` | Quit debugger | -### 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 +## 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. +Tiny8's instruction set strictly adheres to the official **[Microchip AVRยฎ Instruction Set Manual (DS40002198A)](https://ww1.microchip.com/downloads/en/DeviceDoc/AVR-Instruction-Set-Manual-DS40002198A.pdf)**. All mnemonics are case-insensitive. Registers are specified as `R0`โ€“`R31`, and immediates support decimal, hex (`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` | +| Instruction | Description (DS40002198A) | Operation | Example | +|-------------|---------------------------|-----------|---------| +| `LDI Rd, K` | Load Immediate | Rd โ† K (16 โ‰ค d โ‰ค 31) | `ldi r16, 42` | +| `MOV Rd, Rr` | Copy Register | Rd โ† Rr | `mov r17, r16` | +| `LD Rd, Rr` | Load Indirect from Data Space | Rd โ† (Rr) | `ld r18, r26` | +| `ST Rr, Rs` | Store Indirect to Data Space | (Rr) โ† Rs | `st r26, r18` | +| `LDS Rd, k` | Load Direct from Data Space | Rd โ† (k) | `lds r16, 0x0200` | +| `STS k, Rr` | Store Direct to Data Space | (k) โ† Rr | `sts 0x0200, r16` | +| `IN Rd, P` | Load an I/O Location to Register | Rd โ† P | `in r16, 0x3F` | +| `OUT P, Rr` | Store Register to an I/O Location | P โ† Rr | `out 0x3F, r16` | +| `PUSH Rr` | Push Register on Stack | STACK โ† Rr, SP โ† SP - 1 | `push r16` | +| `POP Rd` | Pop Register from Stack | SP โ† SP + 1, Rd โ† STACK | `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` | +| Instruction | Description (DS40002198A) | Operation | Flags | Example | +|-------------|---------------------------|-----------|-------|---------| +| `ADD Rd, Rr` | Add without Carry | Rd โ† Rd + Rr | H, S, V, N, Z, C | `add r16, r17` | +| `ADC Rd, Rr` | Add with Carry | Rd โ† Rd + Rr + C | H, S, V, N, Z, C | `adc r16, r17` | +| `ADIW Rd, K` | Add Immediate to Word | Rd+1:Rd โ† Rd+1:Rd + K | S, V, N, Z, C | `adiw r24, 1` | +| `SUB Rd, Rr` | Subtract without Carry | Rd โ† Rd - Rr | H, S, V, N, Z, C | `sub r16, r17` | +| `SUBI Rd, K` | Subtract Immediate | Rd โ† Rd - K | H, S, V, N, Z, C | `subi r16, 10` | +| `SBC Rd, Rr` | Subtract with Carry | Rd โ† Rd - Rr - C | H, S, V, N, Z, C | `sbc r16, r17` | +| `SBCI Rd, K` | Subtract Immediate with Carry | Rd โ† Rd - K - C | H, S, V, N, Z, C | `sbci r16, 5` | +| `SBIW Rd, K` | Subtract Immediate from Word | Rd+1:Rd โ† Rd+1:Rd - K | S, V, N, Z, C | `sbiw r24, 1` | +| `INC Rd` | Increment | Rd โ† Rd + 1 | S, V, N, Z | `inc r16` | +| `DEC Rd` | Decrement | Rd โ† Rd - 1 | S, V, N, Z | `dec r16` | +| `MUL Rd, Rr` | Multiply Unsigned | R1:R0 โ† Rd ร— Rr | Z, C | `mul r16, r17` | +| `MULS Rd, Rr` | Multiply Signed | R1:R0 โ† Rd ร— Rr (signed) | Z, C | `muls r16, r17` | +| `MULSU Rd, Rr` | Multiply Signed with Unsigned | R1:R0 โ† Rd ร— Rr (Rd signed, Rr unsigned) | Z, C | `mulsu r16, r17` | +| `NEG Rd` | Two's Complement Negation | Rd โ† 0x00 - Rd | H, S, V, N, Z, C | `neg r16` | ### 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` | +| Instruction | Description (DS40002198A) | Operation | Flags | Example | +|-------------|---------------------------|-----------|-------|---------| +| `AND Rd, Rr` | Logical AND | Rd โ† Rd ยท Rr | S, V=0, N, Z | `and r16, r17` | +| `ANDI Rd, K` | Logical AND with Immediate | Rd โ† Rd ยท K | S, V=0, N, Z | `andi r16, 0x0F` | +| `OR Rd, Rr` | Logical OR | Rd โ† Rd โˆจ Rr | S, V=0, N, Z | `or r16, r17` | +| `ORI Rd, K` | Logical OR with Immediate | Rd โ† Rd โˆจ K | S, V=0, N, Z | `ori r16, 0x80` | +| `EOR Rd, Rr` | Exclusive OR | Rd โ† Rd โŠ• Rr | S, V=0, N, Z | `eor r16, r17` | +| `COM Rd` | One's Complement | Rd โ† 0xFF - Rd | S, V=0, N, Z, C=1 | `com r16` | +| `CLR Rd` | Clear Register (Alias: EOR Rd, Rd) | Rd โ† Rd โŠ• Rd | S=0, V=0, N=0, Z=1 | `clr r16` | +| `SER Rd` | Set Register (Alias: LDI Rd, 0xFF) | Rd โ† 0xFF | None | `ser r16` | +| `TST Rd` | Test for Zero or Minus (Alias: AND Rd, Rd) | Rd โ† Rd ยท Rd | S, V=0, N, Z | `tst r16` | +| `SWAP Rd` | Swap Nibbles | Rd(7..4) โ†” Rd(3..0) | None | `swap r16` | +| `SBI P, b` | Set Bit in I/O Register | I/O(P, b) โ† 1 | None | `sbi 0x18, 3` | +| `CBI P, b` | Clear Bit in I/O Register | I/O(P, b) โ† 0 | None | `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` | +| Instruction | Description (DS40002198A) | Operation | Flags | Example | +|-------------|---------------------------|-----------|-------|---------| +| `LSL Rd` | Logical Shift Left (Alias: ADD Rd, Rd) | Rd โ† Rd โ‰ช 1 | H, S, V, N, Z, C | `lsl r16` | +| `LSR Rd` | Logical Shift Right | 0 โ†’ Rd7 โ€ฆ Rd0 โ†’ C | S, V, N, Z, C | `lsr r16` | +| `ASR Rd` | Arithmetic Shift Right | Rd7 โ†’ Rd7 โ€ฆ Rd0 โ†’ C | S, V, N, Z, C | `asr r16` | +| `ROL Rd` | Rotate Left through Carry (Alias: ADC Rd, Rd) | C โ† Rd7 โ€ฆ Rd0 โ† C | H, S, V, N, Z, C | `rol r16` | +| `ROR Rd` | Rotate Right through Carry | C โ†’ Rd7 โ€ฆ Rd0 โ†’ C | S, V, N, Z, C | `ror r16` | + +### Control Flow & Branches + +| Instruction | Description (DS40002198A) | Condition / Target | Flags | Example | +|-------------|---------------------------|--------------------|-------|---------| +| `JMP k` | Jump | PC โ† k | None | `jmp loop` | +| `RJMP k` | Relative Jump | PC โ† PC + k + 1 | None | `rjmp -5` | +| `CALL k` | Long Call to Subroutine | STACK โ† PC + 1, PC โ† k | None | `call function` | +| `RCALL k` | Relative Call to Subroutine | STACK โ† PC + 1, PC โ† PC + k + 1 | None | `rcall -10` | +| `RET` | Return from Subroutine | PC โ† STACK | None | `ret` | +| `RETI` | Return from Interrupt | PC โ† STACK, I โ† 1 | I | `reti` | +| `BREQ k` | Branch if Equal | Z = 1 | None | `breq done` | +| `BRNE k` | Branch if Not Equal | Z = 0 | None | `brne loop` | +| `BRCS k` | Branch if Carry Set | C = 1 | None | `brcs overflow` | +| `BRCC k` | Branch if Carry Clear | C = 0 | None | `brcc no_carry` | +| `BRLO k` | Branch if Lower (Unsigned) | C = 1 (Alias for BRCS) | None | `brlo lower` | +| `BRSH k` | Branch if Same or Higher (Unsigned) | C = 0 (Alias for BRCC) | None | `brsh same_or_higher` | +| `BRGE k` | Branch if Greater or Equal (Signed) | S = 0 (N โŠ• V = 0) | None | `brge positive` | +| `BRLT k` | Branch if Less Than (Signed) | S = 1 (N โŠ• V = 1) | None | `brlt negative` | +| `BRMI k` | Branch if Minus | N = 1 | None | `brmi negative` | +| `BRPL k` | Branch if Plus | N = 0 | None | `brpl positive` | + +### Compare & Skip Instructions + +| Instruction | Description (DS40002198A) | Operation | Flags | Example | +|-------------|---------------------------|-----------|-------|---------| +| `CP Rd, Rr` | Compare | Rd - Rr | H, S, V, N, Z, C | `cp r16, r17` | +| `CPI Rd, K` | Compare with Immediate | Rd - K | H, S, V, N, Z, C | `cpi r16, 42` | +| `CPSE Rd, Rr` | Compare Skip if Equal | Skip next if Rd = Rr | None | `cpse r16, r17` | +| `SBRS Rd, b` | Skip if Bit in Register is Set | Skip next if Rd(b) = 1 | None | `sbrs r16, 7` | +| `SBRC Rd, b` | Skip if Bit in Register is Cleared | Skip next if Rd(b) = 0 | None | `sbrc r16, 7` | +| `SBIS P, b` | Skip if Bit in I/O Register is Set | Skip next if I/O(P, b) = 1 | None | `sbis 0x16, 3` | +| `SBIC P, b` | Skip if Bit in I/O Register is Cleared | Skip next if I/O(P, b) = 0 | None | `sbic 0x16, 3` | ### MCU Control -| Instruction | Description | Example | -|-------------|-------------|---------| -| `NOP` | No operation | `nop` | -| `SEI` | Set global interrupt enable | `sei` | -| `CLI` | Clear global interrupt enable | `cli` | +| Instruction | Description (DS40002198A) | Operation | Flags | Example | +|-------------|---------------------------|-----------|-------|---------| +| `NOP` | No Operation | None | None | `nop` | +| `SEI` | Set Global Interrupt Flag | I โ† 1 | I | `sei` | +| `CLI` | Clear Global Interrupt Flag | I โ† 0 | I | `cli` | ### Status Register (SREG) Flags -The 8-bit status register contains condition flags updated by instructions: +The 8-bit Status Register (SREG) contains condition flags updated by ALU instructions according to exact formulas defined in **DS40002198A**: -| 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 | +| Bit | Flag | Name | DS40002198A Formula & Meaning | +|-----|------|------|-------------------------------| +| 7 | **I** | Global Interrupt Enable | Set by `SEI`, cleared by `CLI` | +| 6 | **T** | Bit Copy Storage | Bit copy buffer for `BST` / `BLD` | +| 5 | **H** | Half Carry Flag | Carry/borrow between bit 3 and bit 4 (BCD arithmetic) | +| 4 | **S** | Sign Bit | True algebraic sign test: S = N โŠ• V | +| 3 | **V** | Two's Complement Overflow | Set when signed arithmetic overflows range [-128, +127] | +| 2 | **N** | Negative Flag | Set if MSB is 1 (N = R7) | +| 1 | **Z** | Zero Flag | Set if result is zero (R == 0) | +| 0 | **C** | Carry / Borrow Flag | Unsigned carry from MSB (R7) or borrow | Flags are used for conditional branching and tracking arithmetic results. @@ -356,10 +388,10 @@ Flags are used for conditional branching and tracking arithmetic results. - **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) +- **Immediates**: Decimal (42), hex (0x2A), binary (0b00101010) - **Whitespace**: Flexible indentation, spaces/tabs interchangeable -## ๐Ÿ—๏ธ Architecture Overview +## Architecture Overview ### CPU Components @@ -372,11 +404,14 @@ Flags are used for conditional branching and tracking arithmetic results. ### Memory Map ```text -0x0000 - 0x001F Memory-mapped I/O (optional) -0x0020 - 0xFFFF Available RAM (stack grows downward from top) +0x0000 - 0x001F General-Purpose Registers (R0 - R31) / System Reserved +0x0020 - 0x005F I/O Registers (64 ports: 0x00 - 0x3F via IN/OUT) +0x0060 - 0x01FF User SRAM (general variables & arrays start at 0x0060) +0x0200 - 0x05FF 32x32 Heatmap VRAM (1,024 bytes, writable visual memory) +0x0600 - 0xFFFF Extended User SRAM (general data, heap & downward-growing stack) ``` -## ๐Ÿงช Testing +## Testing ```bash pytest # Run all tests @@ -384,17 +419,17 @@ pytest --cov=src/tiny8 --cov-report=html # With coverage pytest tests/test_arithmetic.py # Specific test file ``` -## ๐Ÿค Contributing +## Contributing Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. **Areas for contribution**: New instructions, example programs, documentation, visualizations, performance optimizations. -## ๐Ÿ“„ License +## License MIT License โ€” see [LICENSE](LICENSE) for details. -## ๐Ÿ“ž Support +## Support - **Issues**: [GitHub Issues](https://github.com/sql-hkr/tiny8/issues) - **Discussions**: [GitHub Discussions](https://github.com/sql-hkr/tiny8/discussions) @@ -402,6 +437,6 @@ MIT License โ€” see [LICENSE](LICENSE) for details. --- -**Made with โค๏ธ for learners, educators, and curious minds** +**Made for learners, educators, and curious minds** -*Star โญ the repo if you find it useful!* +*Star the repo if you find it useful!* diff --git a/docs/Makefile b/docs/Makefile index d4bb2cb..72ec676 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -4,7 +4,7 @@ # You can set these variables from the command line, and also # from the environment for the first two. SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build +SPHINXBUILD ?= $(shell command -v sphinx-build 2>/dev/null || echo "uv run sphinx-build") SOURCEDIR = . BUILDDIR = _build @@ -12,7 +12,28 @@ BUILDDIR = _build help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -.PHONY: help Makefile +.PHONY: help Makefile gettext update-po html html-ja html-en html-all apidoc + +html: html-all + +apidoc: + @uv run sphinx-apidoc -f -o api ../src/tiny8 2>/dev/null || true + +gettext: apidoc + @$(SPHINXBUILD) -b gettext "$(SOURCEDIR)" locales/pot $(SPHINXOPTS) + +update-po: gettext + sphinx-intl update -p locales/pot -l ja -d locales + +html-ja: apidoc + @$(SPHINXBUILD) -b html -D language=ja "$(SOURCEDIR)" "$(BUILDDIR)/html/ja" $(SPHINXOPTS) + +html-en: apidoc + @$(SPHINXBUILD) -b html -D language=en "$(SOURCEDIR)" "$(BUILDDIR)/html/en" $(SPHINXOPTS) + +html-all: html-en html-ja + @mkdir -p "$(BUILDDIR)/html" + @cp -f "$(SOURCEDIR)/_templates/root_index.html" "$(BUILDDIR)/html/index.html" 2>/dev/null || true # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). diff --git a/docs/_static/.gitkeep b/docs/_static/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/_templates/components/nav-languages.html b/docs/_templates/components/nav-languages.html new file mode 100644 index 0000000..4527960 --- /dev/null +++ b/docs/_templates/components/nav-languages.html @@ -0,0 +1,11 @@ +
+ {% if current_language == 'ja' %} + EN + | + JA + {% else %} + EN + | + JA + {% endif %} +
diff --git a/docs/_templates/partials/site-head.html b/docs/_templates/partials/site-head.html new file mode 100644 index 0000000..b374ec8 --- /dev/null +++ b/docs/_templates/partials/site-head.html @@ -0,0 +1,43 @@ +{%- macro render_logo(src, classname) -%} + {%- if src and src.startswith(('https://', 'http://')) -%} + {{ project }} + {%- elif src -%} + {{ project }} + {%- elif logo_url -%} + {{ project }} + {%- endif -%} +{%- endmacro -%} + +
+
+
+ + {{ render_logo(theme_light_logo, 'light-logo') }} + {{ render_logo(theme_dark_logo, 'dark-logo') }} + {{ project }} + +
+ +
+ {%- include "components/searchbox.html" -%} + {%- include "components/nav-versions.html" -%} + {%- include "partials/nav-socials.html" -%} +
+
+
+ {%- include "components/nav-languages.html" -%} + {%- include "components/theme-switch.html" -%} + +
+
+
diff --git a/docs/_templates/root_index.html b/docs/_templates/root_index.html new file mode 100644 index 0000000..bb1b367 --- /dev/null +++ b/docs/_templates/root_index.html @@ -0,0 +1,25 @@ + + + + + Tiny8 Documentation + + + + +
+

Tiny8 Documentation

+

Redirecting to English / ๆ—ฅๆœฌ่ชž...

+
+ + diff --git a/docs/architecture.rst b/docs/architecture.rst index 4f7f9bb..e7973ec 100644 --- a/docs/architecture.rst +++ b/docs/architecture.rst @@ -6,162 +6,153 @@ This guide provides a detailed overview of the Tiny8 CPU architecture, including CPU Overview ------------ -Tiny8 implements a simplified 8-bit CPU architecture inspired by the AVR family (ATmega series). The design prioritizes educational clarity over cycle-accurate emulation, making it ideal for learning computer architecture fundamentals. +Tiny8 implements an 8-bit RISC CPU architecture modeled directly after the Atmel / Microchip AVR instruction set architecture. Instruction semantics, flag behaviors, and operations strictly adhere to the official specification: + +* **Official Specification**: `Microchip AVRยฎ Instruction Set Manual (DS40002198A) `_ + +The design balances hardware realism with educational clarity, providing full visibility and interactive step debugging. Key Specifications ~~~~~~~~~~~~~~~~~~ * **Word size**: 8 bits * **Registers**: 32 general-purpose 8-bit registers (R0-R31) -* **Memory**: 2KB RAM (configurable) -* **Stack**: Grows downward from high memory -* **Instruction set**: ~60 instructions (AVR-inspired) -* **Status register**: 8 flags (SREG) +* **Memory**: 64KB RAM (configurable) +* **Stack**: Grows downward from high memory (SP decrements on push) +* **Instruction set**: 67 instructions compliant with AVR DS40002198A +* **Status register**: 8 flags (SREG: I, T, H, S, V, N, Z, C) Register Architecture --------------------- -General-Purpose Registers -~~~~~~~~~~~~~~~~~~~~~~~~~ - -Tiny8 has 32 general-purpose 8-bit registers, labeled **R0** through **R31**. +In strict alignment with the **Microchip AVRยฎ Instruction Set Manual (DS40002198A, Section 4)**, the CPU register file consists of 32 8-bit general-purpose working registers, labeled **R0** through **R31**. All 32 registers have direct, single-cycle access to the Arithmetic Logic Unit (ALU). .. code-block:: text - โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” - โ”‚ R0 โ”‚ R1 โ”‚ R2 โ”‚ ... โ”‚ R31 โ”‚ - โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค - โ”‚ 32 x 8-bit registers โ”‚ - โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ - -All registers are fully general-purpose - there are no dedicated accumulator, index, or pointer registers. However, some instructions may work only with specific register ranges: - -* **LDI (Load Immediate)**: Only works with R16-R31 -* **Most arithmetic/logic**: Works with any register R0-R31 - -.. note:: - While all registers are general-purpose, you may want to establish conventions in your programs (e.g., using R0-R15 for temporary values and R16-R31 for important data). + โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” + โ”‚ AVR Register File โ”‚ + โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค + โ”‚ R0 โ€“ R15 (General) โ”‚ R16 โ€“ R31 (Upper Working) โ”‚ + โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค + โ”‚ R0 R1 ... R14 R15 โ”‚ R16 R17 ... R24 R25 โ”‚ + โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ R26 (XL) R27 (XH) โ†’ X-register โ”‚ + โ”‚ R28 (YL) R29 (YH) โ†’ Y-register โ”‚ + โ”‚ R30 (ZL) R31 (ZH) โ†’ Z-register โ”‚ + โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + +Register Organization & Special Functions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* **General Working Registers (R0โ€“R15)**: + Operate with all two-register arithmetic, logical, and bit operations (e.g., ``ADD``, ``SUB``, ``AND``, ``OR``, ``EOR``, ``MOV``, ``CP``). +* **Upper Registers (R16โ€“R31)**: + Support direct immediate instructions (``LDI``, ``SUBI``, ``SBCI``, ``ANDI``, ``ORI``, ``CPI``) where an 8-bit constant :math:`K` is supplied in the instruction. +* **16-bit Word Operand Pairs (R25:R24, X, Y, Z)**: + The word operations ``ADIW`` (Add Immediate to Word) and ``SBIW`` (Subtract Immediate from Word) operate exclusively on the upper register pairs: + * ``R25:R24`` + * ``R27:R26`` (X-register) + * ``R29:R28`` (Y-register) + * ``R31:R30`` (Z-register) +* **16-bit Pointer Registers (X, Y, Z)**: + Six registers (R26โ€“R31) serve as three 16-bit indirect address pointers for Data Space memory addressing: + * **X-register**: ``XL = R26`` (low byte), ``XH = R27`` (high byte) + * **Y-register**: ``YL = R28`` (low byte), ``YH = R29`` (high byte) + * **Z-register**: ``ZL = R30`` (low byte), ``ZH = R31`` (high byte) Special Registers ~~~~~~~~~~~~~~~~~ -In addition to general-purpose registers, the CPU has several special registers: - Program Counter (PC) ^^^^^^^^^^^^^^^^^^^^ -* Points to the current instruction in the program -* Automatically increments after each instruction -* Modified by branch, jump, and call instructions -* **Width**: Depends on program size (virtual, not a physical register) +* 16-bit program address pointer referencing instructions in program memory. +* Automatically increments during sequential execution. +* Modified by jump (``JMP``, ``RJMP``), subroutine call/return (``CALL``, ``RCALL``, ``RET``, ``RETI``), skip instructions (``CPSE``, ``SBRS``, ``SBRC``, ``SBIS``, ``SBIC``), and conditional branches (``BRxx``). Stack Pointer (SP) ^^^^^^^^^^^^^^^^^^ -* Points to the top of the stack in memory -* Initialized to the end of RAM (default: 0x07FF with 2KB RAM) -* Decrements on PUSH, increments on POP -* Used implicitly by CALL and RET instructions +* 16-bit stack pointer pointing to the current top of the stack in Data SRAM. +* Initialized to the end of RAM (default: ``0xFFFF`` with 64KB RAM). +* Decrements during ``PUSH``, ``CALL``, and ``RCALL`` (post-decrement). +* Increments during ``POP``, ``RET``, and ``RETI`` (pre-increment). Status Register (SREG) ^^^^^^^^^^^^^^^^^^^^^^ -* 8-bit register containing condition flags -* Updated by arithmetic, logic, and comparison instructions -* Used by conditional branch instructions +* 8-bit condition flag register containing flags: ``I``, ``T``, ``H``, ``S``, ``V``, ``N``, ``Z``, ``C``. +* Updated by arithmetic, logical, and shift operations according to exact Boolean algebra defined in DS40002198A. .. code-block:: text SREG: [ I | T | H | S | V | N | Z | C ] Bit 7 Bit 0 -See the `Status Flags`_ section for detailed flag descriptions. - -Memory Model ------------- - -Address Space -~~~~~~~~~~~~~ +Memory Model & Addressing Modes +------------------------------- -Tiny8 uses a flexible, byte-addressable memory model with configurable RAM size. - -**Default Configuration:** - -* RAM size: 2048 bytes (2KB) -* Address range: 0x0000 to 0x07FF -* Stack pointer initializes to 0x07FF (ram_size - 1) +Data Memory Space +~~~~~~~~~~~~~~~~~ -**Memory Layout:** +Tiny8 provides a flat, byte-addressable memory space modeled after AVR SRAM with configurable capacity (default: 65536 bytes / 64KB, addressable range ``0x0000`` to ``0xFFFF``). .. code-block:: text - 0x07FF โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ† SP (initial position) - โ”‚ โ”‚ - โ”‚ Stack Area โ”‚ Stack grows downward (PUSH decrements SP) - โ”‚ โ”‚ - โ”‚ โ†“ โ†“ โ†“ โ†“ โ†“ โ†“ โ”‚ - โ”‚ โ”‚ - โ”‚ โ”‚ - โ”‚ Free RAM โ”‚ Available for program use - โ”‚ โ”‚ - โ”‚ โ”‚ - โ”‚ โ†‘ โ†‘ โ†‘ โ†‘ โ†‘ โ†‘ โ”‚ - โ”‚ โ”‚ - โ”‚ Data Area โ”‚ Variables and data grow upward - โ”‚ โ”‚ - 0x0000 โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ Program starts here (PC=0) - -**Key Points:** - -* Memory is byte-addressable (each address holds one 8-bit value) -* Full 2KB address space available by default -* No fixed boundaries between stack and data areas -* Stack and data can grow toward each other (watch for collisions!) -* All memory initializes to 0 on CPU creation -* RAM size is configurable via ``Memory(ram_size=...)`` - -**Memory Access:** - -The CPU uses register-indirect addressing for memory operations: + 0xFFFF โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ† SP (Initial Position) + โ”‚ Stack Area โ”‚ Stack grows downward (PUSH, CALL) + โ”‚ โ†“ โ†“ โ†“ โ†“ โ”‚ + 0x0600 โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค + โ”‚ Upper RAM & Model Weights โ”‚ Dynamic data, arrays, diffusion weights + 0x0200 โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค + โ”‚ Display VRAM Matrix (32x32) โ”‚ Memory-mapped display (1024 bytes) + โ”‚ ASCII Text & Heatmap Output โ”‚ Fits 28x28 MNIST digits (margin: 2) + 0x0060 โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค + โ”‚ User SRAM โ”‚ General data & arrays start at 0x0060 + 0x0020 โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค + โ”‚ I/O Registers โ”‚ 64 I/O ports (0x00..0x3F via IN/OUT) + 0x0000 โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค + โ”‚ General Working Registers โ”‚ 32 registers (R0..R31) / Reserved + โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + +AVR Addressing Modes +~~~~~~~~~~~~~~~~~~~~ + +Tiny8 strictly adheres to the standard AVR addressing modes specified in DS40002198A: + +1. **Direct Single Register**: Operates on a single working register :math:`Rd` (e.g. ``INC Rd``, ``DEC Rd``, ``NEG Rd``, ``COM Rd``, ``CLR Rd``, ``SER Rd``, ``SWAP Rd``, ``LSL Rd``, ``LSR Rd``). +2. **Direct Two-Register**: Operates on two working registers :math:`Rd` and :math:`Rr` (e.g. ``ADD Rd, Rr``, ``ADC Rd, Rr``, ``SUB Rd, Rr``, ``SBC Rd, Rr``, ``AND Rd, Rr``, ``OR Rd, Rr``, ``EOR Rd, Rr``, ``CP Rd, Rr``, ``MOV Rd, Rr``). +3. **Immediate Addressing**: An 8-bit constant :math:`K` operates on an upper register :math:`R16 \le Rd \le R31` (e.g. ``LDI Rd, K``, ``SUBI Rd, K``, ``SBCI Rd, K``, ``ANDI Rd, K``, ``ORI Rd, K``, ``CPI Rd, K``). +4. **Word Immediate Addressing**: A 6-bit constant :math:`0 \le K \le 63` operates on register pairs :math:`R25:R24`, :math:`X`, :math:`Y`, or :math:`Z` (e.g. ``ADIW Rd, K``, ``SBIW Rd, K``). +5. **Direct Data Addressing**: 16-bit absolute memory address :math:`k` loads or stores directly to Data Space (e.g. ``LDS Rd, k``, ``STS k, Rr``). +6. **Data Indirect Addressing with Pointer Registers (X, Y, Z)**: Accesses Data Space through 16-bit register pointers :math:`X` (R27:R26), :math:`Y` (R29:R28), or :math:`Z` (R31:R30) (e.g. ``LD Rd, X``, ``ST X, Rr``). +7. **I/O Direct Addressing**: Reads or writes to 6-bit I/O addresses :math:`0 \le P \le 63` (e.g. ``IN Rd, P``, ``OUT P, Rr``, ``SBI P, b``, ``CBI P, b``, ``SBIS P, b``, ``SBIC P, b``). +8. **Relative Program Addressing**: Jumps or branches relative to the current Program Counter within range :math:`PC + k + 1` (e.g. ``RJMP k``, ``RCALL k``, ``BREQ k``, ``BRNE k``, ``BRCS k``, ``BRCC k``, ``BRLO k``, ``BRSH k``, ``BRGE k``, ``BRLT k``, ``BRMI k``, ``BRPL k``). +9. **Direct Program Addressing**: Unconditional jump or long subroutine call directly to 16-bit program address :math:`k` (e.g. ``JMP k``, ``CALL k``). +10. **Indirect Program Addressing**: Return from subroutine or interrupt through return address popped from the stack (e.g. ``RET``, ``RETI``). + +Memory Access Examples +~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: asm - ; Load from memory - 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 + ; 1. Direct Data Addressing + lds r16, 0x0200 ; Load byte directly from address 0x0200 + sts 0x0200, r16 ; Store byte directly to address 0x0200 - ; Store to memory - ldi r26, 0x50 ; Address = 0x50 - ldi r16, 42 ; Value to store - st r26, r16 ; Store R16 to memory[R26] - -Memory Operations -~~~~~~~~~~~~~~~~~ - -**Stack Operations** - -The stack is used for temporary storage and subroutine calls: - -.. code-block:: asm + ; 2. Data Indirect Addressing via X Pointer Register (R27:R26) + ldi r26, 0x50 ; XL = 0x50 + ldi r27, 0x02 ; XH = 0x02 (X = 0x0250) + ld r16, r26 ; Load from memory[X] into R16 + st r26, r17 ; Store R17 to memory[X] + ; 3. Stack Operations push r16 ; Push R16 onto stack (SP decrements) pop r17 ; Pop from stack into R17 (SP increments) - - call my_function ; Pushes return address, then jumps - ret ; Pops return address, then returns -**I/O Operations** - -Access I/O ports and special registers: - -.. code-block:: asm - - in r16, 0x3F ; Read from I/O port 0x3F into R16 - out 0x3F, r16 ; Write R16 to I/O port 0x3F - -Memory Initialization -~~~~~~~~~~~~~~~~~~~~~ + ; 4. I/O Port Operations + in r16, 0x10 ; Read from keyboard buffer port (0x0010) + out 0x3F, r16 ; Write to I/O port 0x3F * All memory is initialized to 0 on CPU creation * The assembler loads program instructions starting at address 0 @@ -170,176 +161,201 @@ Memory Initialization Status Flags ------------ -The Status Register (SREG) contains 8 condition flags that reflect the result of operations and control program flow. +The Status Register (SREG) contains 8 condition flags that reflect the result of operations and control program flow. In accordance with the **Microchip AVRยฎ Instruction Set Manual (DS40002198A)**, each flag is defined and updated according to exact Boolean algebraic formulas. -Flag Descriptions -~~~~~~~~~~~~~~~~~ +Flag Descriptions & Boolean Formulas +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. list-table:: :header-rows: 1 - :widths: 10 15 75 + :widths: 6 12 22 60 * - Bit + - Flag - Name - - Description + - DS40002198A Definition & Formula * - 7 - - **I** (Interrupt) - - Global interrupt enable flag. When set, interrupts are enabled. + - **I** + - Global Interrupt + - Set by ``SEI``, cleared by ``CLI`` or hardware interrupt entry. * - 6 - - **T** (Transfer) - - Bit copy storage. Used by BLD and BST instructions for bit manipulation. + - **T** + - Bit Copy Storage + - Transferred between SREG and register bit locations by ``BST`` / ``BLD``. * - 5 - - **H** (Half Carry) - - Half-carry flag. Set when there's a carry from bit 3 to bit 4 in arithmetic operations. Used for BCD arithmetic. + - **H** + - Half Carry + - Indicates carry/borrow across nibble boundary (bit 3 to bit 4). ADD: :math:`Rd3 \cdot Rr3 + Rr3 \cdot \overline{R3} + \overline{R3} \cdot Rd3`. SUB: :math:`\overline{Rd3} \cdot Rr3 + Rr3 \cdot R3 + R3 \cdot \overline{Rd3}`. * - 4 - - **S** (Sign) - - Sign flag, computed as N โŠ• V (N XOR V). Indicates true sign of result considering two's complement overflow. + - **S** + - Sign Bit + - True algebraic sign test considering two's complement overflow: :math:`S = N \oplus V`. * - 3 - - **V** (Overflow) - - Two's complement overflow flag. Set when signed arithmetic produces a result outside the range -128 to +127. + - **V** + - Overflow + - Two's complement signed overflow flag. ADD: :math:`Rd7 \cdot Rr7 \cdot \overline{R7} + \overline{Rd7} \cdot \overline{Rr7} \cdot R7`. SUB: :math:`Rd7 \cdot \overline{Rr7} \cdot \overline{R7} + \overline{Rd7} \cdot Rr7 \cdot R7`. * - 2 - - **N** (Negative) - - Negative flag. Set when the result of an operation has bit 7 set (i.e., the result is negative in two's complement). + - **N** + - Negative + - Set if the most significant bit (MSB, bit 7) of the result is 1: :math:`N = R7`. * - 1 - - **Z** (Zero) - - Zero flag. Set when the result of an operation is zero. + - **Z** + - Zero + - Set if the result equals zero: :math:`Z = \overline{R7} \cdot \overline{R6} \cdot \overline{R5} \cdot \overline{R4} \cdot \overline{R3} \cdot \overline{R2} \cdot \overline{R1} \cdot \overline{R0}`. * - 0 - - **C** (Carry) - - Carry flag. Set when there's a carry out of bit 7 (unsigned overflow) or a borrow in subtraction. + - **C** + - Carry / Borrow + - Unsigned carry out of bit 7 or borrow. ADD: :math:`Rd7 \cdot Rr7 + Rr7 \cdot \overline{R7} + \overline{R7} \cdot Rd7`. SUB: :math:`\overline{Rd7} \cdot Rr7 + Rr7 \cdot R7 + R7 \cdot \overline{Rd7}`. -Flag Updates -~~~~~~~~~~~~ +Flag Updates by Instruction Category +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Different instructions update flags in different ways: +According to AVR Instruction Set Manual DS40002198A: -**Arithmetic Instructions** (ADD, SUB, ADC, SBC) - Update all flags: C, Z, N, V, S, H +**Arithmetic (ADD, ADC, SUB, SUBI, SBC, SBCI)** + Updates all condition flags: ``H``, ``S``, ``V``, ``N``, ``Z``, ``C``. -**Logical Instructions** (AND, OR, EOR) - Update Z, N, S; Clear V; Leave C unchanged +**Comparisons (CP, CPI)** + Identical flag updates to subtraction (``SUB`` / ``SUBI``), but the register value is discarded. -**Comparison** (CP, CPI) - Update all flags like subtraction, but don't store result +**Bitwise Logical (AND, ANDI, OR, ORI, EOR, TST)** + Updates ``S``, ``V=0`` (cleared), ``N``, ``Z``. Carry ``C`` and Half-Carry ``H`` are **unaffected** (``-``). ``TST Rd`` is an alias for ``AND Rd, Rd``. -**Test** (TST) - Update Z, N, S, V; Clear V +**Register Clearing & Setting (CLR, SER)** + * ``CLR Rd`` is an alias for ``EOR Rd, Rd``: sets ``Z=1``, ``S=0``, ``V=0``, ``N=0``; leaves ``C`` and ``H`` unaffected. + * ``SER Rd`` is an alias for ``LDI Rd, 0xFF``: **no flags affected**. -**Increment/Decrement** (INC, DEC) - Update Z, N, V, S; Leave C unchanged +**Single-Operand Arithmetic (INC, DEC, NEG, COM)** + * ``INC`` / ``DEC``: Update ``S``, ``V``, ``N``, ``Z``. Carry ``C`` is **unaffected** (allows loop counters without clobbering carry). + * ``NEG``: Two's complement negation (:math:`R = 0 - Rd`). Updates ``H``, ``S``, ``V``, ``N``, ``Z``, ``C``. (:math:`C = (R \neq 0)`, :math:`V = (Rd = 0x80)`). + * ``COM``: One's complement inversion (:math:`R = 0xFF - Rd`). Updates ``S``, ``V=0``, ``N``, ``Z``, and forces ``C=1``. -Using Flags for Branches -~~~~~~~~~~~~~~~~~~~~~~~~~ +**Shifts & Rotates (LSL, LSR, ROL, ROR, SWAP)** + * ``LSL Rd``: Alias for ``ADD Rd, Rd``. + * ``ROL Rd``: Alias for ``ADC Rd, Rd``. + * ``LSR Rd``: Logical shift right. Sets :math:`C = Rd0`, :math:`N = 0`, :math:`Z = (R = 0)`, :math:`V = N \oplus C = C`, :math:`S = N \oplus V = C`. + * ``ROR Rd``: Rotate right through carry. Sets :math:`C = Rd0`, :math:`N = R7`, :math:`Z = (R = 0)`, :math:`V = N \oplus C`, :math:`S = N \oplus V`. + * ``SWAP Rd``: Swaps nibbles. **No flags affected**. -Conditional branch instructions test specific flag conditions: +**Word Operations (ADIW, SBIW)** + 16-bit word addition / subtraction on pointer register pairs (R25:R24, R27:R26, R29:R28, R31:R30). Updates ``S``, ``V``, ``N``, ``Z``, ``C``. -.. code-block:: asm +**Data Transfer & Branches (LDI, MOV, LD, ST, LDS, STS, PUSH, POP, IN, OUT, JMP, RJMP, CALL, RCALL, RET, BRxx)** + Do not affect status flags, except ``RETI`` which sets the Global Interrupt Flag ``I = 1``. - ; Branch if equal (Z flag set) - breq label - - ; Branch if not equal (Z flag clear) - brne label - - ; Branch if carry set (C flag set) - brcs label - - ; Branch if less than (signed: S flag set) - brlt label - - ; Branch if lower (unsigned: C flag set) - brlo label +Using Flags for Branches +~~~~~~~~~~~~~~~~~~~~~~~~~ -Instruction Execution ---------------------- +Conditional branch instructions inspect specific SREG condition flags (all branches take target label or relative offset without altering flags): -Fetch-Decode-Execute Cycle -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. list-table:: + :header-rows: 1 + :widths: 15 20 65 + + * - Mnemonic + - Condition + - Description (per DS40002198A) + * - ``BREQ label`` + - Z = 1 + - Branch if Equal + * - ``BRNE label`` + - Z = 0 + - Branch if Not Equal + * - ``BRCS label`` + - C = 1 + - Branch if Carry Set + * - ``BRCC label`` + - C = 0 + - Branch if Carry Clear + * - ``BRLO label`` + - C = 1 + - Branch if Lower (Unsigned, alias for ``BRCS``) + * - ``BRSH label`` + - C = 0 + - Branch if Same or Higher (Unsigned, alias for ``BRCC``) + * - ``BRGE label`` + - S = 0 (N โŠ• V = 0) + - Branch if Greater or Equal (Signed) + * - ``BRLT label`` + - S = 1 (N โŠ• V = 1) + - Branch if Less Than (Signed) + * - ``BRMI label`` + - N = 1 + - Branch if Minus + * - ``BRPL label`` + - N = 0 + - Branch if Plus + +Instruction Execution & ALU +---------------------------- + +ALU Operation & Register Access +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In strict compliance with the **AVRยฎ Instruction Set Manual (DS40002198A, Section 4)**, the high-performance AVR Arithmetic Logic Unit (ALU) operates in direct connection with all 32 general-purpose registers: + +* **Single-Cycle Operation**: Arithmetic and logical register-to-register operations execute within a single instruction transition. In this cycle: + 1. Two operand registers are read from the Register File. + 2. The operation (Arithmetic, Logical, or Bit manipulation) is evaluated. + 3. The result is written back to the destination register :math:`Rd`. + 4. The Status Register (SREG) condition flags are updated according to exact Boolean algebraic formulas. +* **ALU Functional Blocks**: + * **Arithmetic**: Addition (``ADD``, ``ADC``, ``ADIW``), Subtraction (``SUB``, ``SUBI``, ``SBC``, ``SBCI``, ``SBIW``), Comparison (``CP``, ``CPI``), Negation (``NEG``), Increment (``INC``), Decrement (``DEC``), and Multiplication (``MUL``, ``MULS``, ``MULSU``). + * **Logical**: Bitwise AND (``AND``, ``ANDI``, ``TST``), OR (``OR``, ``ORI``), Exclusive-OR (``EOR``, ``CLR``), and One's Complement (``COM``). + * **Bit & Shift Functions**: Bit set/clear (``SBI``, ``CBI``), Shifts (``LSL``, ``LSR``, ``ASR``), Rotates through carry (``ROL``, ``ROR``), and Nibble swap (``SWAP``). -Tiny8 uses a simplified instruction execution model: +Fetch-Decode-Execute Cycle +~~~~~~~~~~~~~~~~~~~~~~~~~~ -1. **Fetch**: Read instruction at address PC -2. **Decode**: Parse instruction mnemonic and operands -3. **Execute**: Perform the operation -4. **Update**: Increment PC, update flags, record traces +Tiny8 executes programs through the classical CPU cycle: .. code-block:: text - โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” - โ”‚ FETCH โ”‚ โ† Read instruction at PC - โ””โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”˜ - โ”‚ - โ”Œโ”€โ”€โ”€โ”€โ–ผโ”€โ”€โ”€โ”€โ”€โ” - โ”‚ DECODE โ”‚ โ† Parse mnemonic and operands - โ””โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”˜ - โ”‚ - โ”Œโ”€โ”€โ”€โ”€โ–ผโ”€โ”€โ”€โ”€โ”€โ” - โ”‚ EXECUTE โ”‚ โ† Perform operation - โ””โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”˜ - โ”‚ - โ”Œโ”€โ”€โ”€โ”€โ–ผโ”€โ”€โ”€โ”€โ”€โ” - โ”‚ UPDATE โ”‚ โ† Update PC, flags, traces - โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ - -Instruction Format -~~~~~~~~~~~~~~~~~~ + โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” + โ”‚ CPU Cycle โ”‚ + โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค + โ”‚ FETCH โ”‚ DECODE โ”‚ EXECUTE โ”‚ WRITE & STEP โ”‚ + โ”‚ Read from โ”‚ Opcode & โ”‚ ALU / Branch / โ”‚ Update Reg/RAM, โ”‚ + โ”‚ PC addressโ”‚ Operands โ”‚ Memory Operation โ”‚ SREG & Advance โ”‚ + โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ -Instructions are stored as tuples in memory: +Instruction Format & Encoding +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. code-block:: python - - (mnemonic, (operand1, operand2, ...)) - - # Examples: - ("ldi", (("reg", 16), 42)) # ldi r16, 42 - ("add", (("reg", 16), ("reg", 17))) # add r16, r17 - ("jmp", ("loop",)) # jmp loop - -Operand Types -~~~~~~~~~~~~~ - -Operands can be: +In physical AVR microcontrollers: +* Most instructions are **16-bit (1-word)** opcodes. +* Direct memory instructions (``LDS``, ``STS``) and long jumps/calls (``JMP``, ``CALL``) are **32-bit (2-word)** opcodes. -* **Register**: ``("reg", N)`` where N is 0-31 -* **Immediate**: Integer value -* **Label**: String referring to a program location -* **Address**: Memory address (integer) +In Tiny8, the assembler validates operands according to AVR DS40002198A constraints (e.g., verifying that ``LDI``, ``SUBI``, ``CPI`` only target upper registers R16โ€“R31, and that ``ADIW`` / ``SBIW`` target valid pointer register pairs), then stores them as pre-decoded execution tuples: -Step Tracing -~~~~~~~~~~~~ - -The CPU automatically records traces during execution: - -**Register Trace** - Records all register changes as ``(step, register, new_value)`` - -**Memory Trace** - Records all memory writes as ``(step, address, new_value)`` +.. code-block:: python -**Step Trace** - Records full CPU state snapshots for visualization + (mnemonic, (operand1, operand2, ...)) -These traces enable the interactive debugger and animation features. + # Examples: + ("ldi", (16, 42)) # LDI R16, 42 + ("add", (16, 17)) # ADD R16, R17 + ("lds", (16, 0x0200)) # LDS R16, 0x0200 + ("jmp", ("loop",)) # JMP loop -Performance Characteristics ---------------------------- +Step Tracing & State Inspection +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Execution Model -~~~~~~~~~~~~~~~ +During each execution step, Tiny8 records changes to facilitate visual debugging: -* **Single-cycle execution**: Each instruction completes in one "step" -* **No pipeline**: Instructions execute sequentially -* **No timing accuracy**: Simplified model for education +* **Register Trace**: Tracks register writes as ``(step, register_index, new_value)``. +* **Memory Trace**: Tracks SRAM writes as ``(step, address, new_value)``. +* **Step Telemetry**: Records PC, SREG flags, cycle counts, and call stack backtraces. -.. note:: - Real AVR microcontrollers have variable instruction timing (1-4 cycles) and pipelined execution. Tiny8 abstracts these details for simplicity. +Hardware Realism & AVR Compliance +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Limitations -~~~~~~~~~~~ +Tiny8 is strictly grounded in the **Microchip AVRยฎ Instruction Set Manual (DS40002198A)**: -* No I/O peripherals (timers, UART, etc.) -* No interrupt handling (I flag exists but not functional) -* Simplified flag semantics -* No program memory vs. data memory separation (Von Neumann architecture) +* **Instruction Set Fidelity**: All 61 supported instructions strictly follow official Microchip AVR definitions, operands, and SREG Boolean formulas without non-standard instruction extensions. +* **Hardware MUL Compliance**: In accordance with AVR DS40002198A, ``MUL Rd, Rr`` writes the 16-bit unsigned product strictly into the dedicated register pair ``R1:R0`` (R0 = low byte, R1 = high byte). +* **Software Division**: Conforming to physical AVR silicon, integer division is performed via standard software routines (e.g., subtraction loops or shift-and-subtract) rather than non-standard hardware instructions. +* **Execution & Memory Model**: Instructions execute in discrete single-step transitions across a unified flat address space with memory-mapped I/O (ports 0x00..0x3F including CRT matrix and keyboard buffer) for full visibility and educational inspectability. Design Philosophy ----------------- @@ -352,7 +368,7 @@ Tiny8's architecture is designed with these principles: 4. **Extensibility**: Easy to add new instructions 5. **Practicality**: Can run real algorithms and demonstrate CS concepts -The architecture strikes a balance between realism (AVR-inspired) and pedagogy (simplified execution model), making it suitable for: +The architecture strikes a balance between realism (standard AVR architecture) and pedagogy (simplified execution model), making it suitable for: * Computer architecture courses * Assembly language learning diff --git a/docs/assembly_language.rst b/docs/assembly_language.rst index 105bc55..83ceadf 100644 --- a/docs/assembly_language.rst +++ b/docs/assembly_language.rst @@ -486,3 +486,338 @@ Common Patterns --------------- See the :doc:`getting_started` guide for common assembly patterns like loops, conditionals, and memory operations. + +Instruction Set Reference +------------------------- + +The Tiny8 instruction set strictly follows the **Microchip AVRยฎ Instruction Set Manual (DS40002198A)**. All mnemonics and register identifiers are case-insensitive. Immediates can be specified in decimal, hexadecimal (``$FF`` or ``0xFF``), or binary (``0b11111111``). + +Arithmetic and Logic Instructions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + :widths: 18 26 36 20 + + * - Mnemonic & Operands + - Description (DS40002198A) + - Operation + - Flags + * - ``ADD Rd, Rr`` + - Add without Carry + - Rd โ† Rd + Rr + - H, S, V, N, Z, C + * - ``ADC Rd, Rr`` + - Add with Carry + - Rd โ† Rd + Rr + C + - H, S, V, N, Z, C + * - ``ADIW Rd, K`` + - Add Immediate to Word + - Rd+1:Rd โ† Rd+1:Rd + K + - S, V, N, Z, C + * - ``SUB Rd, Rr`` + - Subtract without Carry + - Rd โ† Rd - Rr + - H, S, V, N, Z, C + * - ``SUBI Rd, K`` + - Subtract Immediate + - Rd โ† Rd - K + - H, S, V, N, Z, C + * - ``SBC Rd, Rr`` + - Subtract with Carry + - Rd โ† Rd - Rr - C + - H, S, V, N, Z, C + * - ``SBCI Rd, K`` + - Subtract Immediate with Carry + - Rd โ† Rd - K - C + - H, S, V, N, Z, C + * - ``SBIW Rd, K`` + - Subtract Immediate from Word + - Rd+1:Rd โ† Rd+1:Rd - K + - S, V, N, Z, C + * - ``AND Rd, Rr`` + - Logical AND + - Rd โ† Rd ยท Rr + - S, V=0, N, Z + * - ``ANDI Rd, K`` + - Logical AND with Immediate + - Rd โ† Rd ยท K + - S, V=0, N, Z + * - ``OR Rd, Rr`` + - Logical OR + - Rd โ† Rd โˆจ Rr + - S, V=0, N, Z + * - ``ORI Rd, K`` + - Logical OR with Immediate + - Rd โ† Rd โˆจ K + - S, V=0, N, Z + * - ``EOR Rd, Rr`` + - Exclusive OR + - Rd โ† Rd โŠ• Rr + - S, V=0, N, Z + * - ``COM Rd`` + - One's Complement + - Rd โ† 0xFF - Rd + - S, V=0, N, Z, C=1 + * - ``NEG Rd`` + - Two's Complement Negation + - Rd โ† 0x00 - Rd + - H, S, V, N, Z, C + * - ``INC Rd`` + - Increment + - Rd โ† Rd + 1 + - S, V, N, Z + * - ``DEC Rd`` + - Decrement + - Rd โ† Rd - 1 + - S, V, N, Z + * - ``TST Rd`` + - Test for Zero or Minus + - Rd โ† Rd ยท Rd (alias for AND) + - S, V=0, N, Z + * - ``CLR Rd`` + - Clear Register + - Rd โ† Rd โŠ• Rd (alias for EOR) + - S=0, V=0, N=0, Z=1 + * - ``SER Rd`` + - Set Register + - Rd โ† 0xFF (alias for LDI) + - None + * - ``MUL Rd, Rr`` + - Multiply Unsigned + - R1:R0 โ† Rd ร— Rr + - Z, C + * - ``MULS Rd, Rr`` + - Multiply Signed + - R1:R0 โ† Rd ร— Rr (signed) + - Z, C + * - ``MULSU Rd, Rr`` + - Multiply Signed with Unsigned + - R1:R0 โ† Rd ร— Rr (Rd signed, Rr unsigned) + - Z, C + +Branch Instructions +~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + :widths: 18 26 36 20 + + * - Mnemonic & Operands + - Description (DS40002198A) + - Operation + - Flags + * - ``JMP target`` + - Jump + - PC โ† target + - None + * - ``RJMP offset`` + - Relative Jump + - PC โ† PC + offset + 1 + - None + * - ``CALL target`` + - Long Call to Subroutine + - STACK โ† PC + 1, PC โ† target + - None + * - ``RCALL offset`` + - Relative Call to Subroutine + - STACK โ† PC + 1, PC โ† PC + offset + 1 + - None + * - ``RET`` + - Return from Subroutine + - PC โ† STACK + - None + * - ``RETI`` + - Return from Interrupt + - PC โ† STACK, I โ† 1 + - I + * - ``CPSE Rd, Rr`` + - Compare Skip if Equal + - If Rd = Rr then skip next instruction + - None + * - ``CP Rd, Rr`` + - Compare + - Rd - Rr + - H, S, V, N, Z, C + * - ``CPI Rd, K`` + - Compare with Immediate + - Rd - K + - H, S, V, N, Z, C + * - ``BREQ label`` + - Branch if Equal + - If Z = 1 then PC โ† label + - None + * - ``BRNE label`` + - Branch if Not Equal + - If Z = 0 then PC โ† label + - None + * - ``BRCS label`` + - Branch if Carry Set + - If C = 1 then PC โ† label + - None + * - ``BRCC label`` + - Branch if Carry Clear + - If C = 0 then PC โ† label + - None + * - ``BRLO label`` + - Branch if Lower (Unsigned) + - If C = 1 then PC โ† label (alias for BRCS) + - None + * - ``BRSH label`` + - Branch if Same or Higher + - If C = 0 then PC โ† label (alias for BRCC) + - None + * - ``BRGE label`` + - Branch if Greater or Equal (Signed) + - If S = 0 (N โŠ• V = 0) then PC โ† label + - None + * - ``BRLT label`` + - Branch if Less Than (Signed) + - If S = 1 (N โŠ• V = 1) then PC โ† label + - None + * - ``BRMI label`` + - Branch if Minus + - If N = 1 then PC โ† label + - None + * - ``BRPL label`` + - Branch if Plus + - If N = 0 then PC โ† label + - None + +Data Transfer Instructions +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + :widths: 18 26 36 20 + + * - Mnemonic & Operands + - Description (DS40002198A) + - Operation + - Flags + * - ``MOV Rd, Rr`` + - Copy Register + - Rd โ† Rr + - None + * - ``LDI Rd, K`` + - Load Immediate + - Rd โ† K (16 โ‰ค d โ‰ค 31) + - None + * - ``LD Rd, addr_reg`` + - Load Indirect from Data Space + - Rd โ† (addr_reg) + - None + * - ``ST addr_reg, Rr`` + - Store Indirect to Data Space + - (addr_reg) โ† Rr + - None + * - ``LDS Rd, addr`` + - Load Direct from Data Space + - Rd โ† (addr) + - None + * - ``STS addr, Rr`` + - Store Direct to Data Space + - (addr) โ† Rr + - None + * - ``IN Rd, port`` + - Load an I/O Location to Register + - Rd โ† P + - None + * - ``OUT port, Rr`` + - Store Register to an I/O Location + - P โ† Rr + - None + * - ``PUSH Rr`` + - Push Register on Stack + - STACK โ† Rr, SP โ† SP - 1 + - None + * - ``POP Rd`` + - Pop Register from Stack + - SP โ† SP + 1, Rd โ† STACK + - None + +Bit and Bit-Test Instructions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + :widths: 18 26 36 20 + + * - Mnemonic & Operands + - Description (DS40002198A) + - Operation + - Flags + * - ``SBI port, bit`` + - Set Bit in I/O Register + - I/O(P, bit) โ† 1 + - None + * - ``CBI port, bit`` + - Clear Bit in I/O Register + - I/O(P, bit) โ† 0 + - None + * - ``LSL Rd`` + - Logical Shift Left + - Rd โ† Rd โ‰ช 1 (alias for ADD Rd, Rd) + - H, S, V, N, Z, C + * - ``LSR Rd`` + - Logical Shift Right + - 0 โ†’ Rd7 โ€ฆ Rd0 โ†’ C + - S, V, N, Z, C + * - ``ASR Rd`` + - Arithmetic Shift Right + - Rd7 โ†’ Rd7 โ€ฆ Rd0 โ†’ C + - S, V, N, Z, C + * - ``ROL Rd`` + - Rotate Left through Carry + - C โ† Rd7 โ€ฆ Rd0 โ† C (alias for ADC Rd, Rd) + - H, S, V, N, Z, C + * - ``ROR Rd`` + - Rotate Right through Carry + - C โ†’ Rd7 โ€ฆ Rd0 โ†’ C + - S, V, N, Z, C + * - ``SWAP Rd`` + - Swap Nibbles + - Rd(7..4) โ†” Rd(3..0) + - None + * - ``SBRS Rd, bit`` + - Skip if Bit in Register is Set + - If Rd(bit) = 1 then skip next instruction + - None + * - ``SBRC Rd, bit`` + - Skip if Bit in Register is Cleared + - If Rd(bit) = 0 then skip next instruction + - None + * - ``SBIS port, bit`` + - Skip if Bit in I/O Register is Set + - If I/O(P, bit) = 1 then skip next instruction + - None + * - ``SBIC port, bit`` + - Skip if Bit in I/O Register is Cleared + - If I/O(P, bit) = 0 then skip next instruction + - None + +MCU Control Instructions +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + :widths: 18 26 36 20 + + * - Mnemonic & Operands + - Description (DS40002198A) + - Operation + - Flags + * - ``NOP`` + - No Operation + - No operation performed + - None + * - ``SEI`` + - Set Global Interrupt Flag + - I โ† 1 + - I + * - ``CLI`` + - Clear Global Interrupt Flag + - I โ† 0 + - I + + diff --git a/docs/conf.py b/docs/conf.py index a53e5fc..541f52f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -35,6 +35,8 @@ exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] language = "en" +locale_dirs = ["locales/"] +gettext_compact = False # -- Autodoc configuration --------------------------------------------------- autodoc_default_options = { @@ -74,7 +76,7 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output html_theme = "shibuya" -html_static_path = [] # No static files yet +html_static_path = ["_static"] # Theme options html_theme_options = { @@ -112,3 +114,24 @@ "Miscellaneous", ), ] + + +def setup(app): + """Sphinx application setup hook.""" + + def add_language_switcher_context(app, pagename, templatename, context, doctree): + depth = pagename.count("/") + prefix = "../" * depth + outdir_name = os.path.basename(os.path.abspath(app.outdir)) + current_lang = app.config.language or "en" + context["current_language"] = current_lang + + if outdir_name in ("en", "ja"): + up_to_langs = prefix + "../" + context["en_page_url"] = f"{up_to_langs}en/{pagename}.html" + context["ja_page_url"] = f"{up_to_langs}ja/{pagename}.html" + else: + context["en_page_url"] = f"{prefix}en/{pagename}.html" + context["ja_page_url"] = f"{prefix}ja/{pagename}.html" + + app.connect("html-page-context", add_language_switcher_context) diff --git a/docs/examples/bubblesort.rst b/docs/examples/bubblesort.rst index 4224747..b838468 100644 --- a/docs/examples/bubblesort.rst +++ b/docs/examples/bubblesort.rst @@ -47,7 +47,8 @@ This generates a sequence of pseudo-random 8-bit values. ldi r25, 75 ; PRNG multiplier init_loop: - mul r18, r25 ; multiply seed by 75 + mul r18, r25 ; multiply seed by 75 (product in R1:R0) + mov r18, r0 ; transfer low byte of product inc r18 ; add 1 st r16, r18 ; store at RAM[base + index] ; ... @@ -107,6 +108,7 @@ Inner Loop ; compare and swap if A > B (for ascending order) cp r21, r24 brcs no_swap ; skip if A < B + breq no_swap ; skip if A == B st r20, r24 ; swap: RAM[addr_A] = B st r22, r21 ; swap: RAM[addr_B] = A @@ -119,7 +121,6 @@ For each j: 1. Load adjacent elements (j and j+1) 2. Compare them 3. Swap if first > second (for ascending order) -3. Swap if first > second 4. Advance to next pair Register Usage diff --git a/docs/examples/gcd.rst b/docs/examples/gcd.rst index 718fc67..621a605 100644 --- a/docs/examples/gcd.rst +++ b/docs/examples/gcd.rst @@ -7,4 +7,4 @@ Computes the GCD of two numbers using Euclidean algorithm. :language: asm :linenos: -Demonstrates division, modulo operation, and iterative algorithm. +Demonstrates subtraction-based Euclidean algorithm and conditional comparison. diff --git a/docs/examples/index.rst b/docs/examples/index.rst index dfd2fc3..98fa900 100644 --- a/docs/examples/index.rst +++ b/docs/examples/index.rst @@ -28,12 +28,6 @@ You can run any example with the interactive debugger: tiny8 examples/fibonacci.asm -Or generate an animation: - -.. code-block:: bash - - tiny8 examples/bubblesort.asm -m ani -o bubblesort.gif - Or use the Python API: .. code-block:: python @@ -83,6 +77,13 @@ Advanced Examples is_prime reverse +C Language Programs & Interactive Demos +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Tiny8 includes an embedded C subset compiler capable of compiling and running C programs directly on the simulated CPU: + +* **factorial.c**: Recursive factorial calculation demonstration. + Quick Reference --------------- @@ -92,52 +93,58 @@ Quick Reference * - Program - Concept - - Key Instructions + - Key Instructions / Language * - Hello World - - Basic structure - - LDI, JMP + - Basic memory writing + - LDI, ST, INC, JMP * - Fibonacci - - Loops, arithmetic + - Iterative sequence - ADD, MOV, DEC, BRNE - * - Factorial - - Multiplication + * - Factorial (ASM) + - Iterative multiplication - MUL, DEC, CPI, BRGE + * - Factorial (C) + - Recursive function calls + - C Compiler (CALL, RET, PUSH, POP) * - Sum 1 to N - - Accumulation - - ADD, INC, CP, BRLO + - Loop accumulation + - ADD, INC, CP, BRLT, BREQ * - Array Sum - - Memory access - - LDS, ADD, INC + - Pointer iteration + - LD, ST, ADD, INC, BRNE * - Find Max - - Comparison - - CP, BRLO, MOV + - Array scanning & comparison + - LD, ST, CP, BRGE, MOV * - Linear Search - - Sequential search - - LDS, CP, BREQ + - Target search & sentinel + - LD, ST, CP, BREQ, INC * - Memory Copy - - Data transfer - - LDS, STS, INC + - Block memory transfer + - LD, ST, INC, DEC, BRNE * - Bubble Sort - - Sorting algorithm - - LD, ST, CP, BRCC + - PRNG & in-place sort + - MUL, LD, ST, CP, BRCS * - GCD - Euclidean algorithm - - DIV, MUL, SUB, MOV + - DIV, MOV, CPI, BREQ * - Power - - Repeated multiplication - - MUL, DEC, BRNE + - Exponentiation + - MUL, INC, CP, BRLT * - Multiply by Shift - - Bit manipulation - - LSL, LSR, ADD + - Binary shift multiplication + - LSL, LSR, ANDI, ADD * - Count Bits - - Bit operations - - LSR, ANDI + - Bit testing & division + - AND, DIV, CPI, BRNE * - Is Prime - - Number theory - - DIV, MUL, CP + - Trial division + - DIV, MUL, CP, BRGE, BRLT * - Reverse Array - - Array manipulation - - LDS, STS, SWAP + - Two-pointer array reverse + - LD, ST, CP, BRGE, INC, DEC + * - MNIST Diffusion (ASM) + - Iterative reverse-diffusion synthesis + - ASM (diffusion_mnist8.asm) Learning Path ------------- diff --git a/docs/getting_started.rst b/docs/getting_started.rst index d124b1b..c763ded 100644 --- a/docs/getting_started.rst +++ b/docs/getting_started.rst @@ -94,44 +94,38 @@ Debugger Controls Use these keyboard shortcuts to control execution: -**Navigation:** +**Execution:** -* ``l`` or ``โ†’`` - Step forward one instruction -* ``h`` or ``โ†`` - Step backward one instruction -* ``w`` - Jump forward 10 steps -* ``b`` - Jump backward 10 steps -* ``0`` - Go to first step -* ``$`` - Go to last step +* ``Space`` - Play / pause automatic continuous execution +* ``Shift+Space`` - Reverse playback execution +* ``n`` - Step forward 1 instruction (+1 step) +* ``p`` - Step backward 1 instruction (-1 step, time-travel) +* ``c`` - Continue forward to next breakpoint +* ``C`` (``Shift+c``) - Reverse continue backward to previous breakpoint +* ``b`` - Toggle breakpoint at current PC +* ``+`` / ``-`` - Increase / decrease playback speed +* ``r`` - Reset execution back to Step 0 -**Playback:** +**Display & Navigation:** -* ``Space`` - Toggle play/pause -* ``[`` - Slower playback -* ``]`` - Faster playback +* ``j`` / ``k`` - Scroll memory view down / up by 32 bytes (1 row) +* ``J`` / ``K`` - Fast scroll memory view down / up by 128 bytes (4 rows) +* ``g`` - Toggle Grayscale / Viridis color palette +* ``x`` - Toggle Hexadecimal (02X) / Graphic Pixel blocks +* ``m`` - Cycle view modes +* ``i`` - Inspect details of currently executing instruction +* ``h`` or ``?`` - Open full help and keyboard guide modal +* ``e`` - Open built-in Vim modal editor -**Display:** +**Command Bar Prompt:** -* ``r`` - Toggle showing all registers -* ``M`` - Toggle showing all memory -* ``=`` - Show detailed step information -* ``j`` - Scroll memory view down -* ``k`` - Scroll memory view up - -**Marks:** - -* ``m`` + letter - Set a mark at current position -* ``'`` + letter - Jump to a saved mark - -**Search/Commands:** - -* ``/`` - Show help screen -* ``:`` - Enter command mode (for advanced navigation and search) +* ``:`` - Enter command prompt (e.g. ``:goto ``, ``:b ``, ``:q``) **Exit:** -* ``q`` or ``Esc`` - Quit +* ``q`` - Quit debugger -Try stepping through your program with ``l`` and watch how the registers change! +Try stepping through your program with ``n`` and watch how the registers change! Running from Python ------------------- diff --git a/docs/index.rst b/docs/index.rst index 3bc76f1..06a54a8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,53 +3,41 @@ Tiny8 Documentation =================== -**An educational 8-bit CPU simulator with interactive visualization** +**From bare-metal computer architecture to Generative AI โ€” an educational 8-bit AVR RISC CPU simulator with real-time 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. +Tiny8 is a lightweight educational toolkit that bridges bare-metal computer architecture and modern Generative AI. Designed for hands-on learning and experimentation, it guides you through the full stack of computing โ€” from 32 general-purpose registers, ALU operations, stack frames, and C compilation up to executing an iterative reverse-diffusion model synthesizing 28x28 MNIST digits directly on an AVR 8-bit RISC processor. With an interactive Vim-inspired terminal debugger, time-travel reverse execution, and a 32x32 TrueColor memory heatmap, Tiny8 lets you see, step through, and understand computation at every level. -.. image:: https://github.com/user-attachments/assets/6d4f07ba-21b3-483f-a5d4-7603334c40f4 - :alt: Animated bubble sort visualization +.. figure:: https://github.com/user-attachments/assets/bd3e88da-9bcb-4a41-bb9e-57d9d4e39bc6 + :alt: Real-time generative reverse-diffusion synthesis (MNIST 8) at x5,000 speed in Tiny8 TUI (Viridis Palette, HEX init -> PIXEL denoising) :align: center - :width: 600px + :width: 100% -.. centered:: *Real-time visualization of a bubble sort algorithm executing on Tiny8* + *Real-time generative reverse-diffusion synthesis (MNIST digit 8) executing at x5,000 speed in Tiny8 TUI (HEX mode for weight/LFSR init → PIXEL mode for reverse denoising trajectory)* Features -------- -๐ŸŽฏ Interactive Terminal Debugger -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. image:: https://github.com/user-attachments/assets/5317ebcd-53d5-4966-84be-be94b7830899 - :alt: CLI visualizer screenshot - :align: center - :width: 600px +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 -~~~~~~~~~~~~~~~~~~~~~~~ +* **Time-travel debugging**: Step forward and backward with sparse checkpoint restoration +* **32x32 TrueColor Heatmap**: VRAM memory matrix with Viridis/Grayscale visualization +* **Built-in Vim Editor**: Launch full-screen modal editor anytime with ``e`` -* 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 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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 +* **64KB address space** for unified memory and I/O * **Stack operations** with dedicated stack pointer -* **AVR-inspired instruction set** with 60+ instructions +* **AVR instruction set** with 67 instructions compliant with Microchip DS40002198A -๐Ÿ“š Educational Focus -~~~~~~~~~~~~~~~~~~~~ +Educational Focus +~~~~~~~~~~~~~~~~~ * Clean, readable Python implementation * Comprehensive examples (Fibonacci, bubble sort, factorial, and more) @@ -99,12 +87,6 @@ Run it with the interactive debugger: tiny8 fibonacci.asm -Or generate an animation: - -.. code-block:: bash - - tiny8 fibonacci.asm -m ani -o fibonacci.gif - Using the Python API ~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/locales/ja/LC_MESSAGES/api/modules.po b/docs/locales/ja/LC_MESSAGES/api/modules.po new file mode 100644 index 0000000..9f69380 --- /dev/null +++ b/docs/locales/ja/LC_MESSAGES/api/modules.po @@ -0,0 +1,25 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2025, sql-hkr +# This file is distributed under the same license as the Tiny8 package. +# FIRST AUTHOR , 2026. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tiny8 0.2.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-10-25 00:49+0900\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: ja\n" +"Language-Team: ja \n" +"Plural-Forms: nplurals=1; plural=0;\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 2.17.0\n" + +#: ../../api/modules.rst:2 +msgid "tiny8" +msgstr "" + diff --git a/docs/locales/ja/LC_MESSAGES/api/tiny8.po b/docs/locales/ja/LC_MESSAGES/api/tiny8.po new file mode 100644 index 0000000..70ad57f --- /dev/null +++ b/docs/locales/ja/LC_MESSAGES/api/tiny8.po @@ -0,0 +1,2564 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2025, sql-hkr +# This file is distributed under the same license as the Tiny8 package. +# FIRST AUTHOR , 2026. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Tiny8 0.2.0\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-10-25 01:27+0900\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: ja\n" +"Language-Team: ja \n" +"Plural-Forms: nplurals=1; plural=0;\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 2.17.0\n" + +#: ../../api/tiny8.rst:2 +msgid "tiny8 package" +msgstr "" + +#: ../../api/tiny8.rst:5 +msgid "Submodules" +msgstr "" + +#: ../../api/tiny8.rst:8 +msgid "tiny8.assembler module" +msgstr "" + +#: of tiny8.assembler:1 +msgid "Assembler for tiny8 converting assembly text into program listings." +msgstr "" + +#: of tiny8.assembler.AsmResult:1 tiny8.compiler.ASTNode:1 +#: tiny8.compiler.CodeGenerator:1 tiny8.compiler.Lexer:1 +#: tiny8.compiler.Parser:1 tiny8.compiler.Token:1 tiny8.cpu.CPU:1 +#: tiny8.memory.Memory:1 tiny8.tui.CheckpointManager:1 +#: tiny8.utils.ProgressBar:1 +msgid "Bases: :py:class:`object`" +msgstr "" + +#: of tiny8.assembler.AsmResult:1 +msgid "Result of assembling assembly source code." +msgstr "" + +#: ../../api/tiny8.rst of tiny8.compiler.CodeGenerator.gen_expr +#: tiny8.compiler.optimize_assembly tiny8.cpu.CPU.restore_snapshot +#: tiny8.memory.Memory.restore_ram tiny8.tui.CheckpointManager.detect_loop +#: tiny8.tui.CheckpointManager.invalidate_after +#: tiny8.tui.CheckpointManager.precompute tiny8.tui.CheckpointManager.record +#: tiny8.tui.CheckpointManager.record_if_interval +#: tiny8.tui.CheckpointManager.restore_exact_step +#: tiny8.tui.MemoryWidget.get_heatmap_bg +#: tiny8.tui.Tiny8App.action_exec_instruction +#: tiny8.tui.Tiny8App.on_input_submitted tiny8.tui.Tiny8App.watch_mem_start +#: tiny8.tui.eval_condition tiny8.tui.extract_call_frames +#: tiny8.tui.get_widget_available_lines +msgid "Parameters" +msgstr "" + +#: of tiny8.assembler.AsmResult:5 tiny8.cpu.CPU:47 tiny8.cpu.CPU:65 +msgid "List of instruction tuples in (mnemonic, operands) format." +msgstr "" + +#: of tiny8.assembler.AsmResult tiny8.cpu.CPU +msgid "type" +msgstr "" + +#: of tiny8.assembler.AsmResult:7 tiny8.cpu.CPU:67 +msgid "list[tuple[str, tuple]]" +msgstr "" + +#: of tiny8.assembler.AsmResult:11 +msgid "Mapping of label names to program counter addresses." +msgstr "" + +#: of tiny8.assembler.AsmResult:13 tiny8.cpu.CPU:73 +msgid "dict[str, int]" +msgstr "" + +#: of tiny8.assembler.AsmResult:17 tiny8.cpu.CPU:55 tiny8.cpu.CPU:77 +msgid "Mapping of program counter to source line numbers." +msgstr "" + +#: of tiny8.assembler.AsmResult:19 tiny8.cpu.CPU:79 +msgid "dict[int, int]" +msgstr "" + +#: of tiny8.assembler.AsmResult:23 +msgid "Original source lines for display and debugging." +msgstr "" + +#: of tiny8.assembler.AsmResult:25 tiny8.cpu.CPU:85 +msgid "list[str]" +msgstr "" + +#: ../../api/tiny8.rst of tiny8.compiler.CodeGenerator.gen_expr +#: tiny8.compiler.Lexer.tokenize tiny8.compiler.optimize_assembly +#: tiny8.cpu.CPU.clear_traces tiny8.cpu.CPU.restore_snapshot +#: tiny8.cpu.CPU.snapshot tiny8.memory.Memory.clear_changes +#: tiny8.memory.Memory.restore_ram tiny8.tui.CacheProgressModalScreen.compose +#: tiny8.tui.CheckpointManager.detect_loop +#: tiny8.tui.CheckpointManager.invalidate_after +#: tiny8.tui.CheckpointManager.precompute tiny8.tui.CheckpointManager.record +#: tiny8.tui.CheckpointManager.record_if_interval +#: tiny8.tui.CheckpointManager.restore_exact_step +#: tiny8.tui.InstructionDetailModalScreen.compose +#: tiny8.tui.InstructionReferenceScreen.compose +#: tiny8.tui.MemoryWidget.get_heatmap_bg tiny8.tui.TUIHelpScreen.compose +#: tiny8.tui.Tiny8App.action_cancel_command +#: tiny8.tui.Tiny8App.action_continue_run tiny8.tui.Tiny8App.action_cycle_mode +#: tiny8.tui.Tiny8App.action_exec_instruction tiny8.tui.Tiny8App.action_faster +#: tiny8.tui.Tiny8App.action_open_command tiny8.tui.Tiny8App.action_open_editor +#: tiny8.tui.Tiny8App.action_reverse_continue +#: tiny8.tui.Tiny8App.action_scroll_down +#: tiny8.tui.Tiny8App.action_scroll_page_down +#: tiny8.tui.Tiny8App.action_scroll_page_up tiny8.tui.Tiny8App.action_scroll_up +#: tiny8.tui.Tiny8App.action_show_help +#: tiny8.tui.Tiny8App.action_show_instruction_detail +#: tiny8.tui.Tiny8App.action_show_reference tiny8.tui.Tiny8App.action_slower +#: tiny8.tui.Tiny8App.action_toggle_breakpoint +#: tiny8.tui.Tiny8App.action_toggle_grayscale +#: tiny8.tui.Tiny8App.action_toggle_hex tiny8.tui.Tiny8App.action_toggle_play +#: tiny8.tui.Tiny8App.action_toggle_reverse_play tiny8.tui.Tiny8App.compose +#: tiny8.tui.Tiny8App.on_input_submitted tiny8.tui.Tiny8App.watch_mem_start +#: tiny8.tui.VimEditorScreen.compose tiny8.tui.eval_condition +#: tiny8.tui.extract_call_frames tiny8.tui.get_widget_available_lines +#: tiny8.tui.main tiny8.utils.ProgressBar.__enter__ +#: tiny8.utils.ProgressBar.__exit__ tiny8.utils.ProgressBar.close +#: tiny8.utils.ProgressBar.reset +msgid "Return type" +msgstr "" + +#: of tiny8.assembler.parse_asm:1 +msgid "Parse assembly source text into an AsmResult structure." +msgstr "" + +#: of tiny8.assembler.parse_asm:3 +msgid "Assembly source text." +msgstr "" + +#: ../../api/tiny8.rst +msgid "Returns" +msgstr "" + +#: of tiny8.assembler.assemble:5 tiny8.assembler.assemble_file:5 +#: tiny8.assembler.parse_asm:5 +msgid "AsmResult containing parsed program, labels, and line mappings." +msgstr "" + +#: of tiny8.assembler.assemble:1 +msgid "Assemble source text into program instructions and label mappings." +msgstr "" + +#: of tiny8.assembler.assemble:3 +msgid "Assembly source code string." +msgstr "" + +#: of tiny8.assembler.assemble_file:1 +msgid "Assemble source file into program instructions and label mappings." +msgstr "" + +#: of tiny8.assembler.assemble_file:3 +msgid "Path to the assembly source file." +msgstr "" + +#: ../../api/tiny8.rst +msgid "Raises" +msgstr "" + +#: of tiny8.assembler.assemble_file:7 +msgid "If the source file does not exist." +msgstr "" + +#: of tiny8.assembler.assemble_file:8 +msgid "If reading the file fails." +msgstr "" + +#: ../../api/tiny8.rst:16 +msgid "tiny8.cli module" +msgstr "" + +#: of tiny8.cli:1 +msgid "Backward-compatibility wrapper forwarding to tiny8.tui." +msgstr "" + +#: of tiny8.tui.main:1 +msgid "Entry point for tiny8 CLI supporting Assembly and C sources." +msgstr "" + +#: of tiny8.tui.run_cli:1 +msgid "" +"Launch modern Textual TUI debugger with OLED black theme and gradient " +"heatmaps." +msgstr "" + +#: of tiny8.tui.run_cli:3 +msgid "CPU emulator with execution history." +msgstr "" + +#: of tiny8.tui.run_cli:4 +msgid "Start address for memory viewer." +msgstr "" + +#: of tiny8.tui.run_cli:5 +msgid "End address for memory viewer." +msgstr "" + +#: of tiny8.tui.run_cli:6 +msgid "Playback interval in seconds." +msgstr "" + +#: of tiny8.tui.run_cli:7 +msgid "Source assembly or C lines." +msgstr "" + +#: of tiny8.tui.run_cli:8 +msgid "C variable metadata symbols." +msgstr "" + +#: ../../api/tiny8.rst:24 +msgid "tiny8.compiler module" +msgstr "" + +#: of tiny8.compiler:1 +msgid "Simple C compiler for Tiny8 converting a subset of C into Tiny8 assembly." +msgstr "" + +#: of tiny8.compiler:3 +msgid "" +"Features: - Variable declarations and assignments (int/char) - Arithmetic" +" (+, -, *, /, %), bitwise (&, |, ^, ~), logical (!), and relational (<, " +"<=, >, >=, ==, !=) - Control structures: if / else, while, return - " +"Functions with register-based parameter passing (R16..R19) and return " +"value in R16 - Hardware builtins: peek(addr), poke(addr, val), in(port), " +"out(port, val)" +msgstr "" + +#: of tiny8.compiler.Token:1 +msgid "Lexical token." +msgstr "" + +#: of tiny8.compiler.Lexer:1 +msgid "Tokenize C source code." +msgstr "" + +#: of tiny8.compiler.Lexer.tokenize:1 +msgid "Convert input source into tokens, ignoring whitespace and comments." +msgstr "" + +#: of tiny8.compiler.ASTNode:1 +msgid "Base AST node." +msgstr "" + +#: of tiny8.compiler.ArrayAccess:1 tiny8.compiler.ArrayAssign:1 +#: tiny8.compiler.ArrayDecl:1 tiny8.compiler.Assign:1 tiny8.compiler.BinaryOp:1 +#: tiny8.compiler.Block:1 tiny8.compiler.BreakStmt:1 tiny8.compiler.Call:1 +#: tiny8.compiler.ExprStmt:1 tiny8.compiler.ForStmt:1 +#: tiny8.compiler.FunctionDef:1 tiny8.compiler.IfStmt:1 +#: tiny8.compiler.Literal:1 tiny8.compiler.Program:1 +#: tiny8.compiler.ReturnStmt:1 tiny8.compiler.StringLiteral:1 +#: tiny8.compiler.UnaryOp:1 tiny8.compiler.Var:1 tiny8.compiler.VarDecl:1 +#: tiny8.compiler.WhileStmt:1 +msgid "Bases: :py:class:`~tiny8.compiler.ASTNode`" +msgstr "" + +#: of tiny8.compiler.Program:1 +msgid "Program root containing functions and global declarations." +msgstr "" + +#: of tiny8.compiler.VarDecl:1 +msgid "Variable declaration." +msgstr "" + +#: of tiny8.compiler.ArrayDecl:1 +msgid "Array variable declaration." +msgstr "" + +#: of tiny8.compiler.ArrayAccess:1 +msgid "Array indexing expression: name[index]." +msgstr "" + +#: of tiny8.compiler.ArrayAssign:1 +msgid "Array element assignment: name[index] = expr." +msgstr "" + +#: of tiny8.compiler.FunctionDef:1 +msgid "Function definition." +msgstr "" + +#: of tiny8.compiler.Block:1 +msgid "Block of statements." +msgstr "" + +#: of tiny8.compiler.Assign:1 +msgid "Assignment statement." +msgstr "" + +#: of tiny8.compiler.IfStmt:1 +msgid "If-else statement." +msgstr "" + +#: of tiny8.compiler.WhileStmt:1 +msgid "While loop." +msgstr "" + +#: of tiny8.compiler.ForStmt:1 +msgid "For loop." +msgstr "" + +#: of tiny8.compiler.BreakStmt:1 +msgid "Break statement." +msgstr "" + +#: of tiny8.compiler.ReturnStmt:1 +msgid "Return statement." +msgstr "" + +#: of tiny8.compiler.ExprStmt:1 +msgid "Expression statement." +msgstr "" + +#: of tiny8.compiler.BinaryOp:1 +msgid "Binary expression." +msgstr "" + +#: of tiny8.compiler.UnaryOp:1 +msgid "Unary expression." +msgstr "" + +#: of tiny8.compiler.Literal:1 +msgid "Literal integer value." +msgstr "" + +#: of tiny8.compiler.StringLiteral:1 +msgid "String literal value." +msgstr "" + +#: of tiny8.compiler.Var:1 +msgid "Variable reference." +msgstr "" + +#: of tiny8.compiler.Call:1 +msgid "Function call expression." +msgstr "" + +#: of tiny8.compiler.Parser:1 +msgid "Recursive descent parser." +msgstr "" + +#: of tiny8.compiler.optimize_assembly:1 +msgid "Perform peephole optimizations on generated assembly lines." +msgstr "" + +#: of tiny8.compiler.optimize_assembly:3 +msgid "" +"Optimizations include: - Removing redundant self register moves (MOV Rx, " +"Rx) - Simplifying PUSH Rx followed immediately by POP Ry into MOV Ry, Rx " +"(or eliminating if Rx == Ry) - Removing redundant LD R16, R30 immediately" +" after ST R30, R16 - Removing JMP