{"id":29148683,"url":"https://github.com/asmod-lang/asmodeus","last_synced_at":"2025-06-30T22:06:28.198Z","repository":{"id":301963006,"uuid":"1008601537","full_name":"asmod-lang/asmodeus","owner":"asmod-lang","description":"⚙️ Modern Assembly language and virtual machine for Machine W architecture. Build, debug, and execute 16-bit assembly programs with Polish assembler","archived":false,"fork":false,"pushed_at":"2025-06-30T18:52:36.000Z","size":328,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-30T19:33:32.693Z","etag":null,"topics":["assembler","assembly","assembly-language","compiler","debugger","education","emulator","machine-w","programming-language","rust","virtual-machine"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/asmod-lang.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-25T19:55:58.000Z","updated_at":"2025-06-30T18:52:39.000Z","dependencies_parsed_at":"2025-06-30T19:44:42.898Z","dependency_job_id":null,"html_url":"https://github.com/asmod-lang/asmodeus","commit_stats":null,"previous_names":["szymonwilczek/asmodeus","asmod-lang/asmodeus"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/asmod-lang/asmodeus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asmod-lang%2Fasmodeus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asmod-lang%2Fasmodeus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asmod-lang%2Fasmodeus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asmod-lang%2Fasmodeus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/asmod-lang","download_url":"https://codeload.github.com/asmod-lang/asmodeus/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asmod-lang%2Fasmodeus/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262857289,"owners_count":23375492,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["assembler","assembly","assembly-language","compiler","debugger","education","emulator","machine-w","programming-language","rust","virtual-machine"],"created_at":"2025-06-30T22:06:23.524Z","updated_at":"2025-06-30T22:06:28.125Z","avatar_url":"https://github.com/asmod-lang.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Asmodeus\n\n**Modern Assembly Language Inspired by Machine W Architecture**\n\n```\n ______                                  __                            \n/\\  _  \\                                /\\ \\                           \n\\ \\ \\_\\ \\    ____    ___ ___     ___    \\_\\ \\     __   __  __    ____  \n \\ \\  __ \\  /',__\\ /' __` __`\\  / __`\\  /'_` \\  /'__`\\/\\ \\/\\ \\  /',__\\ \n  \\ \\ \\/\\ \\/\\__, `\\/\\ \\/\\ \\/\\ \\/\\ \\_\\ \\/\\ \\_\\ \\/\\  __/\\ \\ \\_\\ \\/\\__, `\\\n   \\ \\_\\ \\_\\/\\____/\\ \\_\\ \\_\\ \\_\\ \\____/\\ \\___,_\\ \\____\\\\ \\____/\\/\\____/\n    \\/_/\\/_/\\/___/  \\/_/\\/_/\\/_/\\/___/  \\/__,_ /\\/____/ \\/___/  \\/___/ \n```\n\n[![Rust](https://img.shields.io/badge/rust-1.70+-orange.svg)](https://www.rust-lang.org)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Build](https://img.shields.io/badge/build-passing-brightgreen.svg)]()\n\nAsmodeus is a complete assembly language toolchain inspired by the legendary Machine W architecture. It features a full compiler pipeline from source code to executable machine code, with advanced debugging capabilities and an extensible instruction set.\n\n## 🚀 Features\n\n### Core Capabilities\n- **Complete Toolchain**: Lexer → Parser → Assembler → Virtual Machine\n- **Machine W Architecture**: 16-bit word size, 2048 words of memory\n- **Extended Instruction Set**: Advanced arithmetic operations (MNO, DZI, MOD)\n- **Interactive Debugger**: Bugseer - step-by-step execution with breakpoints\n- **Real-time I/O**: Character-based input/output for interactive programs\n- **Multiple Addressing Modes**: Direct, immediate, indirect, register-based\n\n### Advanced Features\n- **Macro System**: Define reusable code blocks with parameters\n- **Label Resolution**: Forward and backward references\n- **Error Diagnostics**: Comprehensive error reporting with line numbers\n- **Binary Disassembly**: Convert machine code back to readable assembly\n- **Verbose Debugging**: Detailed execution tracing and state inspection\n\n## 📦 Installation\n\n### Quick Install (Recommended)\n```bash\ncurl -sSL https://raw.githubusercontent.com/szymonwilczek/asmodeus/main/installers/install.sh | bash\n```\n\n### Manual Installation\n1. Clone the repository:\n```bash\ngit clone https://github.com/szymonwilczek/asmodeus.git\ncd asmodeus\n```\n\n2. Build and install:\n```bash\ncargo build --release\ncp target/release/asmodeus ~/.local/bin/asmod\n```\n\n3. Add to PATH (add to ~/.bashrc or ~/.zshrc):\n```bash\nexport PATH=\"$HOME/.local/bin:$PATH\"\n```\n\n### Development Setup\n```bash\ngit clone https://github.com/szymonwilczek/asmodeus.git\ncd asmodeus\ncargo build\n# Use cargo run -- [args] or ./installers/dev.sh [args] for development\n```\n\n## 🎯 Quick Start\n\n### Hello World\nCreate `hello.asmod`:\n```assembly\n; Simple hello world program\nstart:\n    POB message     ; Load message value into accumulator\n    WYJSCIE         ; Output the value\n    STP             ; Stop program\n\nmessage: RST 42     ; Our \"hello world\" message (42)\n```\n\nRun it:\n```bash\nasmod run hello.asmod\n```\n\n### Basic Arithmetic\n```assembly\n; Add two numbers\nstart:\n    POB first       ; Load first number\n    DOD second      ; Add second number  \n    WYJSCIE         ; Output result\n    STP             ; Stop\n\nfirst:  RST 25      ; First operand\nsecond: RST 17      ; Second operand\n```\n\n### Extended Instruction Set Example\n```assembly\n; Calculate (15 * 3) / 5 = 9\nstart:\n    POB #15         ; Load immediate value 15\n    MNO #3          ; Multiply by 3 (extended instruction)\n    DZI #5          ; Divide by 5 (extended instruction)\n    WYJSCIE         ; Output result (9)\n    STP\n\n; Run with: asmod run --extended program.asmod\n```\n\n## 🛠️ Usage\n\n### Command Line Interface\n\n```bash\n# Run assembly program (default mode)\nasmod run program.asmod\nasmod program.asmod                    # Same as above\n\n# Assemble to binary without running\nasmod assemble program.asmod -o program.bin\n\n# Disassemble binary back to assembly\nasmod disassemble program.bin\n\n# Interactive debugger with breakpoints\nasmod debug program.asmod\n\n# Real-time character I/O mode\nasmod interactive program.asmod\n\n# Enable extended instruction set\nasmod run --extended program.asmod\n\n# Verbose output for debugging\nasmod run --verbose --debug program.asmod\n```\n\n### Options\n- `-o, --output FILE`: Specify output file\n- `-v, --verbose`: Verbose output during compilation and execution\n- `--debug`: Enable debug output (tokens, AST, etc.)\n- `-e, --extended`: Enable extended instruction set (MNO, DZI, MOD)\n- `-h, --help`: Show help message\n\n## 📚 Language Reference\n\n### Machine W Architecture\n\nAsmodeus emulates the Machine W architecture with:\n- **Memory**: 2048 words of 16-bit memory (addresses 0-2047)\n- **Registers**:\n  - `AK` - Accumulator (16-bit)\n  - `L` - Instruction counter (11-bit, 0-2047) \n  - `AD` - Address register (11-bit)\n  - `KOD` - Opcode register (5-bit)\n  - `WS` - Stack pointer (11-bit, grows downward from 2047)\n  - `R0-R7` - General purpose registers (16-bit each)\n\n### Core Instruction Set\n\n#### Arithmetic Instructions\n- `DOD addr` - Add memory[addr] to AK\n- `ODE addr` - Subtract memory[addr] from AK\n- `DOD #value` - Add immediate value to AK\n- `ODE #value` - Subtract immediate value from AK\n\n#### Memory Instructions  \n- `ŁAD addr` / `LAD addr` - Store AK to memory[addr]\n- `POB addr` - Load memory[addr] to AK\n- `POB #value` - Load immediate value to AK\n\n#### Control Flow Instructions\n- `SOB addr` - Unconditional jump to addr\n- `SOM addr` - Jump to addr if AK \u003c 0\n- `SOZ addr` - Jump to addr if AK = 0\n- `STP` - Stop program execution\n\n#### Stack Instructions\n- `SDP` - Push AK to stack\n- `PZS` - Pop from stack to AK\n\n#### I/O Instructions\n- `WEJSCIE` / `WPR` - Read input to AK\n- `WYJSCIE` / `WYJ` - Output AK value\n\n#### Interrupt Instructions\n- `DNS` - Disable interrupts\n- `CZM` - Clear interrupt mask\n- `MSK` - Set interrupt mask\n- `PWR` - Return from interrupt\n\n### Extended Instruction Set\n\nEnable with `--extended` flag:\n- `MNO addr` - Multiply AK by memory[addr]\n- `DZI addr` - Divide AK by memory[addr]  \n- `MOD addr` - AK = AK % memory[addr]\n- `MNO #value` - Multiply AK by immediate value\n- `DZI #value` - Divide AK by immediate value\n- `MOD #value` - AK = AK % immediate value\n\n### Addressing Modes\n\n- **Direct**: `POB 100` - Use memory[100]\n- **Immediate**: `POB #42` - Use literal value 42\n- **Indirect**: `POB [100]` - Use memory[memory[100]]\n- **Register**: `POB R1` - Use register R1 value\n- **Register Indirect**: `POB [R1]` - Use memory[R1]\n\n### Directives\n\n- `RST value` - Reserve memory and initialize with value\n- `RPA` - Reserve memory without initialization (0)\n\n### Macros\n\n```assembly\nMAKRO macro_name param1 param2\n    ; macro body\n    DOD param1\n    SOB param2\nKONM\n\n; Usage\nstart:\n    macro_name 100 end_label\n```\n\n### Labels and Comments\n\n```assembly\n; Line comment\n// C-style comment\n\nlabel_name:     ; Define label\n    POB data    ; Reference label\n    SOB label_name\n\ndata: RST 42\n```\n\n## 🐛 Debugging with Bugseer\n\nAsmodeus includes **Bugseer**, a powerful interactive debugger:\n\n```bash\nasmod debug program.asmod\n```\n\n### Debugger Commands\n- `s` / `step` - Execute single instruction\n- `c` / `continue` - Continue execution until breakpoint or end\n- `d` / `display` - Show current machine state\n- `b ADDRESS` / `breakpoint ADDRESS` - Set breakpoint at address\n- `rb ADDRESS` - Remove breakpoint\n- `lb` - List all breakpoints\n- `m START [END]` - Dump memory range\n- `h` / `help` - Show all commands\n- `q` / `quit` - Exit debugger\n\n### Example Debug Session\n```\n(bugseer)\u003e b 5          # Set breakpoint at address 5\n(bugseer)\u003e c            # Continue until breakpoint\n(bugseer)\u003e d            # Display machine state\n(bugseer)\u003e m 0 10       # Show memory 0-10\n(bugseer)\u003e s            # Step one instruction\n```\n\n## 📁 Project Structure\n\nThe Asmodeus toolchain consists of several interconnected crates:\n\n```\nasmodeus/\n├── src/                    # Main CLI application\n├── lexariel/              # Lexical analyzer (tokenizer)\n├── parseid/               # Parser (tokens → AST)\n├── hephasm/               # Assembler (AST → machine code)\n├── asmachina/             # Virtual machine (Machine W emulator)\n├── dismael/               # Disassembler (machine code → assembly)\n├── shared/                # Shared types and utilities\n├── examples/              # Example programs\n│   ├── basic/            # Simple examples\n│   ├── arithmetic/       # Math operations\n│   ├── extended_set/     # Extended instruction examples\n│   ├── io/               # Input/output examples\n│   └── errors/           # Error demonstration\n└── tests/                # Integration tests\n```\n\n### Pipeline Flow\n```\nSource Code (.asmod)\n    ↓ [Lexariel]\nTokens\n    ↓ [Parseid] \nAbstract Syntax Tree (AST)\n    ↓ [Hephasm]\nMachine Code\n    ↓ [Asmachina]\nExecution Results\n```\n\n## 📖 Examples\n\n### Factorial Calculation\n```assembly\n; Calculate 5! = 120\nstart:\n    POB one         ; result = 1\n    LAD result\n    POB n           ; counter = 5  \n    LAD counter\n\nloop:\n    POB counter     ; if counter == 0, done\n    SOZ done\n    \n    POB result      ; result *= counter\n    MNO counter     ; (requires --extended)\n    LAD result\n    \n    POB counter     ; counter--\n    ODE one\n    LAD counter\n    \n    SOB loop\n\ndone:\n    POB result      ; output result\n    WYJSCIE\n    STP\n\nn:       RST 5\none:     RST 1  \nresult:  RPA\ncounter: RPA\n```\n\n### Character I/O Program  \n```assembly\n; Echo program with real-time I/O\nstart:\n    WEJSCIE         ; Read character\n    WYJSCIE         ; Echo it back\n    STP\n\n; Run with: asmod interactive echo.asmod\n```\n\n### Stack Operations\n```assembly\n; Demonstrate stack usage\nstart:\n    POB #10         ; Push 10 to stack\n    SDP\n    POB #20         ; Push 20 to stack  \n    SDP\n    \n    PZS             ; Pop 20 to AK\n    WYJSCIE         ; Output 20\n    PZS             ; Pop 10 to AK\n    WYJSCIE         ; Output 10\n    STP\n```\n\nFor more examples, checkout [examples directory](/examples/)\n\n## 🔧 Development\n\n### Building from Source\n```bash\ngit clone https://github.com/szymonwilczek/asmodeus.git\ncd asmodeus\ncargo build --release\n```\n\n### Running Tests\n```bash\n# Unit tests\ncargo test\n\n# Integration tests\ncargo test --test integration\n\n# Test specific crate\ncargo test -p lexariel\ncargo test -p asmachina\n```\n\n### Development Commands\n```bash\n# Use development wrapper\n./installers/dev.sh run examples/basic/hello.asmod\n\n# Or use cargo directly\ncargo run -- run examples/basic/hello.asmod\n```\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n### Code Structure Guidelines\n- `lexariel/` - Lexical analysis and tokenization\n- `parseid/` - Syntax analysis and AST generation  \n- `hephasm/` - Assembly and code generation\n- `asmachina/` - Virtual machine and execution\n- `dismael/` - Disassembly and reverse engineering\n- `shared/` - Common types and utilities\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n**Extended instructions not working**\n```bash\n# Make sure to use --extended flag\nasmod run --extended program.asmod\n```\n\n**File extension errors**\n```bash\n# Use .asmod for source files\nasmod run program.asmod\n\n# Use .bin for binary files (warning: binary files should contain valid Asmodeus syntax!) \nasmod disassemble program.bin\n```\n\n**Division by zero error**\n```bash\n# Check for DZI or MOD with zero operand\nDZI #0  ; This will cause runtime error\n```\n\n**Undefined symbol error**\n```bash\n# Make sure all labels are defined\nPOB undefined_label  ; Error: symbol not found\n```\n\n### Getting Help\n\n```bash\nasmod --help                    # Show all options\nasmod debug program.asmod       # Use interactive debugger\nasmod run --verbose program.asmod  # Verbose output\n```\n\n## 📜 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE.md) file for details.\n\n## 🙏 Acknowledgments\n\n- Inspired by the classic Machine W architecture\n- Built with modern Rust for performance and safety\n- Designed for educational purposes and assembly language learning\n\n## 🔗 Links\n\n- [Repository](https://github.com/szymonwilczek/asmodeus)\n- [Issues](https://github.com/szymonwilczek/asmodeus/issues)\n\n---\n\n**Made with ❤️ for assembly language enthusiasts**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasmod-lang%2Fasmodeus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fasmod-lang%2Fasmodeus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasmod-lang%2Fasmodeus/lists"}