asmodeus 0.1.0

Complete assembler and emulator for Asmodeus architecture
asmodeus-0.1.0 is not a library.

Asmodeus

Modern Assembly Language Inspired by Machine W Architecture

 ______                                  __                            
/\  _  \                                /\ \                           
\ \ \_\ \    ____    ___ ___     ___    \_\ \     __   __  __    ____  
 \ \  __ \  /',__\ /' __` __`\  / __`\  /'_` \  /'__`\/\ \/\ \  /',__\ 
  \ \ \/\ \/\__, `\/\ \/\ \/\ \/\ \_\ \/\ \_\ \/\  __/\ \ \_\ \/\__, `\
   \ \_\ \_\/\____/\ \_\ \_\ \_\ \____/\ \___,_\ \____\\ \____/\/\____/
    \/_/\/_/\/___/  \/_/\/_/\/_/\/___/  \/__,_ /\/____/ \/___/  \/___/

Rust License Build

Asmodeus 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.

🚀 Features

Core Capabilities

  • Complete Toolchain: Lexer → Parser → Assembler → Virtual Machine
  • Machine W Architecture: 16-bit word size, 2048 words of memory
  • Extended Instruction Set: Advanced arithmetic operations (MNO, DZI, MOD)
  • Interactive Debugger: Bugseer - step-by-step execution with breakpoints
  • Real-time I/O: Character-based input/output for interactive programs
  • Multiple Addressing Modes: Direct, immediate, indirect, register-based

Advanced Features

  • Macro System: Define reusable code blocks with parameters
  • Label Resolution: Forward and backward references
  • Error Diagnostics: Comprehensive error reporting with line numbers
  • Binary Disassembly: Convert machine code back to readable assembly
  • Verbose Debugging: Detailed execution tracing and state inspection

📦 Installation

Quick Install (Recommended)

curl -sSL https://raw.githubusercontent.com/szymonwilczek/asmodeus/main/installers/install.sh | bash

Manual Installation

  1. Clone the repository:
git clone https://github.com/szymonwilczek/asmodeus.git
cd asmodeus
  1. Build and install:
cargo build --release
cp target/release/asmodeus ~/.local/bin/asmod
  1. Add to PATH (add to ~/.bashrc or ~/.zshrc):
export PATH="$HOME/.local/bin:$PATH"

Development Setup

git clone https://github.com/szymonwilczek/asmodeus.git
cd asmodeus
cargo build
# Use cargo run -- [args] or ./installers/dev.sh [args] for development

🎯 Quick Start

Hello World

Create hello.asmod:

; Simple hello world program
start:
    POB message     ; Load message value into accumulator
    WYJSCIE         ; Output the value
    STP             ; Stop program

message: RST 42     ; Our "hello world" message (42)

Run it:

asmod run hello.asmod

Basic Arithmetic

; Add two numbers
start:
    POB first       ; Load first number
    DOD second      ; Add second number  
    WYJSCIE         ; Output result
    STP             ; Stop

first:  RST 25      ; First operand
second: RST 17      ; Second operand

Extended Instruction Set Example

; Calculate (15 * 3) / 5 = 9
start:
    POB #15         ; Load immediate value 15
    MNO #3          ; Multiply by 3 (extended instruction)
    DZI #5          ; Divide by 5 (extended instruction)
    WYJSCIE         ; Output result (9)
    STP

; Run with: asmod run --extended program.asmod

🛠️ Usage

Command Line Interface

# Run assembly program (default mode)
asmod run program.asmod
asmod program.asmod                    # Same as above

# Assemble to binary without running
asmod assemble program.asmod -o program.bin

# Disassemble binary back to assembly
asmod disassemble program.bin

# Interactive debugger with breakpoints
asmod debug program.asmod

# Real-time character I/O mode
asmod interactive program.asmod

# Enable extended instruction set
asmod run --extended program.asmod

# Verbose output for debugging
asmod run --verbose --debug program.asmod

Options

  • -o, --output FILE: Specify output file
  • -v, --verbose: Verbose output during compilation and execution
  • --debug: Enable debug output (tokens, AST, etc.)
  • -e, --extended: Enable extended instruction set (MNO, DZI, MOD)
  • -h, --help: Show help message

📚 Language Reference

Machine W Architecture

Asmodeus emulates the Machine W architecture with:

  • Memory: 2048 words of 16-bit memory (addresses 0-2047)
  • Registers:
    • AK - Accumulator (16-bit)
    • L - Instruction counter (11-bit, 0-2047)
    • AD - Address register (11-bit)
    • KOD - Opcode register (5-bit)
    • WS - Stack pointer (11-bit, grows downward from 2047)
    • R0-R7 - General purpose registers (16-bit each)

Core Instruction Set

Arithmetic Instructions

  • DOD addr - Add memory[addr] to AK
  • ODE addr - Subtract memory[addr] from AK
  • DOD #value - Add immediate value to AK
  • ODE #value - Subtract immediate value from AK

Memory Instructions

  • ŁAD addr / LAD addr - Store AK to memory[addr]
  • POB addr - Load memory[addr] to AK
  • POB #value - Load immediate value to AK

Control Flow Instructions

  • SOB addr - Unconditional jump to addr
  • SOM addr - Jump to addr if AK < 0
  • SOZ addr - Jump to addr if AK = 0
  • STP - Stop program execution

Stack Instructions

  • SDP - Push AK to stack
  • PZS - Pop from stack to AK

I/O Instructions

  • WEJSCIE / WPR - Read input to AK
  • WYJSCIE / WYJ - Output AK value

Interrupt Instructions

  • DNS - Disable interrupts
  • CZM - Clear interrupt mask
  • MSK - Set interrupt mask
  • PWR - Return from interrupt

Extended Instruction Set

Enable with --extended flag:

  • MNO addr - Multiply AK by memory[addr]
  • DZI addr - Divide AK by memory[addr]
  • MOD addr - AK = AK % memory[addr]
  • MNO #value - Multiply AK by immediate value
  • DZI #value - Divide AK by immediate value
  • MOD #value - AK = AK % immediate value

Addressing Modes

  • Direct: POB 100 - Use memory[100]
  • Immediate: POB #42 - Use literal value 42
  • Indirect: POB [100] - Use memory[memory[100]]
  • Register: POB R1 - Use register R1 value
  • Register Indirect: POB [R1] - Use memory[R1]

Directives

  • RST value - Reserve memory and initialize with value
  • RPA - Reserve memory without initialization (0)

Macros

MAKRO macro_name param1 param2
    ; macro body
    DOD param1
    SOB param2
KONM

; Usage
start:
    macro_name 100 end_label

Labels and Comments

; Line comment
// C-style comment

label_name:     ; Define label
    POB data    ; Reference label
    SOB label_name

data: RST 42

🐛 Debugging with Bugseer

Asmodeus includes Bugseer, a powerful interactive debugger:

asmod debug program.asmod

Debugger Commands

  • s / step - Execute single instruction
  • c / continue - Continue execution until breakpoint or end
  • d / display - Show current machine state
  • b ADDRESS / breakpoint ADDRESS - Set breakpoint at address
  • rb ADDRESS - Remove breakpoint
  • lb - List all breakpoints
  • m START [END] - Dump memory range
  • h / help - Show all commands
  • q / quit - Exit debugger

Example Debug Session

(bugseer)> b 5          # Set breakpoint at address 5
(bugseer)> c            # Continue until breakpoint
(bugseer)> d            # Display machine state
(bugseer)> m 0 10       # Show memory 0-10
(bugseer)> s            # Step one instruction

📁 Project Structure

The Asmodeus toolchain consists of several interconnected crates:

asmodeus/
├── src/                    # Main CLI application
├── lexariel/              # Lexical analyzer (tokenizer)
├── parseid/               # Parser (tokens → AST)
├── hephasm/               # Assembler (AST → machine code)
├── asmachina/             # Virtual machine (Machine W emulator)
├── dismael/               # Disassembler (machine code → assembly)
├── shared/                # Shared types and utilities
├── examples/              # Example programs
│   ├── basic/            # Simple examples
│   ├── arithmetic/       # Math operations
│   ├── extended_set/     # Extended instruction examples
│   ├── io/               # Input/output examples
│   └── errors/           # Error demonstration
└── tests/                # Integration tests

Pipeline Flow

Source Code (.asmod)
    ↓ [Lexariel]
Tokens
    ↓ [Parseid] 
Abstract Syntax Tree (AST)
    ↓ [Hephasm]
Machine Code
    ↓ [Asmachina]
Execution Results

📖 Examples

Factorial Calculation

; Calculate 5! = 120
start:
    POB one         ; result = 1
    LAD result
    POB n           ; counter = 5  
    LAD counter

loop:
    POB counter     ; if counter == 0, done
    SOZ done
    
    POB result      ; result *= counter
    MNO counter     ; (requires --extended)
    LAD result
    
    POB counter     ; counter--
    ODE one
    LAD counter
    
    SOB loop

done:
    POB result      ; output result
    WYJSCIE
    STP

n:       RST 5
one:     RST 1  
result:  RPA
counter: RPA

Character I/O Program

; Echo program with real-time I/O
start:
    WEJSCIE         ; Read character
    WYJSCIE         ; Echo it back
    STP

; Run with: asmod interactive echo.asmod

Stack Operations

; Demonstrate stack usage
start:
    POB #10         ; Push 10 to stack
    SDP
    POB #20         ; Push 20 to stack  
    SDP
    
    PZS             ; Pop 20 to AK
    WYJSCIE         ; Output 20
    PZS             ; Pop 10 to AK
    WYJSCIE         ; Output 10
    STP

For more examples, checkout examples directory

🔧 Development

Building from Source

git clone https://github.com/szymonwilczek/asmodeus.git
cd asmodeus
cargo build --release

Running Tests

# Unit tests
cargo test

# Integration tests
cargo test --test integration

# Test specific crate
cargo test -p lexariel
cargo test -p asmachina

Development Commands

# Use development wrapper
./installers/dev.sh run examples/basic/hello.asmod

# Or use cargo directly
cargo run -- run examples/basic/hello.asmod

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Code Structure Guidelines

  • lexariel/ - Lexical analysis and tokenization
  • parseid/ - Syntax analysis and AST generation
  • hephasm/ - Assembly and code generation
  • asmachina/ - Virtual machine and execution
  • dismael/ - Disassembly and reverse engineering
  • shared/ - Common types and utilities

🐛 Troubleshooting

Common Issues

Extended instructions not working

# Make sure to use --extended flag
asmod run --extended program.asmod

File extension errors

# Use .asmod for source files
asmod run program.asmod

# Use .bin for binary files (warning: binary files should contain valid Asmodeus syntax!) 
asmod disassemble program.bin

Division by zero error

# Check for DZI or MOD with zero operand
DZI #0  ; This will cause runtime error

Undefined symbol error

# Make sure all labels are defined
POB undefined_label  ; Error: symbol not found

Getting Help

asmod --help                    # Show all options
asmod debug program.asmod       # Use interactive debugger
asmod run --verbose program.asmod  # Verbose output

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

  • Inspired by the classic Machine W architecture
  • Built with modern Rust for performance and safety
  • Designed for educational purposes and assembly language learning

🔗 Links

Made with ❤️ for assembly language enthusiasts