Asmodeus

Modern Assembly Language Inspired by Machine W Architecture

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

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

Clone the repository:

git clone https://github.com/szymonwilczek/asmodeus.git
cd asmodeus

Build and install:

cargo build --release
cp target/release/asmodeus ~/.local/bin/asmod

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

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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

Name		Name	Last commit message	Last commit date
Latest commit History 296 Commits
.github/workflows		.github/workflows
asmachina		asmachina
dismael		dismael
examples		examples
hephasm		hephasm
installers		installers
lexariel		lexariel
parseid		parseid
shared		shared
src		src
templates		templates
tests		tests
.gitattributes		.gitattributes
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE.md		LICENSE.md
README.md		README.md

License

asmod-lang/asmodeus

Folders and files

Latest commit

History

Repository files navigation