lucia-lasm 1.0.2

LASM - Lucia Assembly Language
Documentation

LASM - Lucia Assembly Language

LASM (Lucia Assembly) is a Rust crate that provides JIT (Just-In-Time) compilation of a custom assembly language to native machine code via Cranelift. Its key features are high-performance JIT execution and seamless variable interaction between Rust and LASM code.

Why LASM?

JIT Compilation: Unlike interpreted languages, LASM compiles to native machine code at runtime using Cranelift, providing near-native performance with minimal overhead.

Variable Bridge: Seamlessly pass data between high-level Rust code and low-level assembly, enabling performance-critical sections while maintaining safety.

Modern Assembly: Register-based architecture with convenient syscalls, eliminating the boilerplate of traditional assembly programming.

Rust Integration: Drop LASM code anywhere in your Rust application for instant performance boosts.

Purpose: LASM was developed as the low-level execution backend for the Lucia Programming Language. It powers the lasm module, allowing performance-critical sections of an otherwise interpreted language to execute at near-native speed through JIT compilation.

Installation

As a Cargo Crate

Add to your Cargo.toml:

[dependencies]

lasm = { version = "1", package = "lucia-lasm" }

Or use the latest version from crates.io:

cargo add lucia-lasm

Building from Source

git clone https://github.com/SirPigari/lasm

cd lasm

cargo build --release

Usage

As a Library

use lasm::{compile, call, Target};
use std::collections::HashMap;

fn main() {
    let code = r#"
        mov 42, r0
        syscall print_int
        mov "\n", r1
        mov 1, r0
        mov 1, r2
        syscall write
        mov 0, r0
        syscall exit
    "#;
    
    let target = Target::Native;
    let compiled = compile(code, target).expect("Compilation failed");
    
    let variables = HashMap::new();
    let (exit_code, _) = call(&compiled, &variables).expect("Execution failed");
    
    assert_eq!(exit_code, 0);
}

Command Line Tool

The crate includes a CLI binary for testing and development:

cargo run --bin lasm -- examples/hello.lasm

Or after building:

./target/release/lasm examples/hello.lasm

Library API

Basic Usage

use lasm::{compile, call, Target};
use std::collections::HashMap;

fn main() {
    let code = r#"
        mov 42, r0
        syscall print_int
        mov "\n", r1
        mov 1, r0
        mov 1, r2
        syscall write
        mov 0, r0
        syscall exit
    "#;
    
    let target = Target::Native;
    let compiled = compile(code, target).expect("Compilation failed");
    
    let variables = HashMap::new();
    let (exit_code, _) = call(&compiled, &variables).expect("Execution failed");
    
    assert_eq!(exit_code, 0);
}

Variable Interaction

One of LASM's most powerful features is seamless variable passing between Rust and LASM code:

use lasm::{compile, call, Target, Value};
use std::collections::HashMap;

fn main() {
    let code = r#"
        ; Load input variables
        load input, r0    ; Load 'input' variable into r0
        add r0, 10        ; Add 10 to it
        push r0, output   ; Store result in 'output' variable
        
        mov 0, r0
        syscall exit
    "#;
    
    let target = Target::Native;
    let compiled = compile(code, target).expect("Compiling failed");
    
    let mut variables = HashMap::new();
    variables.insert("input".to_string(), Value::Int(42));
    
    let (exit_code, updated_vars) = call(&compiled, &variables).expect("Execution failed");
    
    if let Some(Value::Int(result)) = updated_vars.get("output") {
        assert_eq!(*result, 52);
    }
}

Variable Instructions

  • load "var_name", reg - Load a variable from Rust into a register
  • push reg, "var_name" - Store a register value back to a Rust variable

Variables can be of type Int, Float, String, Ptr, or Null.

Architecture

Registers

  • General Purpose: r0-r15 (64-bit)
  • Stack Pointer: rsp
  • Base Pointer: rbp

Instructions

Data Movement

  • mov <src>, <dst> - Move value from source to destination
  • ldr <reg>, [<reg>] - Load from memory address in register
  • str <reg>, [<reg>] - Store to memory address in register
  • load "var", <reg> - Load Rust variable into register
  • push <reg>, "var" - Store register value to Rust variable

Arithmetic

  • add <dst>, <src> - Add
  • sub <dst>, <src> - Subtract
  • mul <dst>, <src> - Multiply
  • div <dst>, <src> - Divide
  • mod <dst>, <src> - Modulo

Floating Point Arithmetic

  • fadd <dst>, <src> - Add floats
  • fsub <dst>, <src> - Subtract floats
  • fmul <dst>, <src> - Multiply floats
  • fdiv <dst>, <src> - Divide floats
  • fmod <dst>, <src> - Modulo floats

Logic

  • and <dst>, <src> - Bitwise AND
  • or <dst>, <src> - Bitwise OR
  • xor <dst>, <src> - Bitwise XOR
  • not <dst> - Bitwise NOT
  • shl <dst>, <src> - Shift left
  • shr <dst>, <src> - Shift right

Control Flow

  • cmp <left>, <right> - Compare registers/values
  • beq <label> - Branch if equal
  • bne <label> - Branch if not equal
  • blt <label> - Branch if less than
  • bgt <label> - Branch if greater than
  • ble <label> - Branch if less or equal
  • bge <label> - Branch if greater or equal
  • jmp <label> - Unconditional jump
  • call <label> - Call subroutine
  • ret - Return from subroutine

Stack Operations

  • pushr <reg> - Push register onto stack
  • popr <reg> - Pop from stack into register

Operands

Instructions can take:

  • Immediate values: Numbers like 42 or strings like "hello"
  • Registers: r0, r1, etc.
  • Labels: For jumps and calls

Syscalls

LASM provides high-level syscalls that abstract away low-level system calls:

I/O

  • syscall write - Write to file descriptor (fd in r0, buffer in r1, count in r2)
  • syscall read - Read from file descriptor
  • syscall print_int - Print integer (value in r0)
  • syscall print_float - Print float (bits in r0)
  • syscall print_str - Print null-terminated string (pointer in r0)
  • syscall flush - Flush output stream (fd in r0)

Memory

  • syscall malloc - Allocate memory (size in r0, returns pointer in r0)
  • syscall free - Free memory (pointer in r0)
  • syscall memcpy - Copy memory (dst in r0, src in r1, len in r2)
  • syscall memset - Set memory (dst in r0, val in r1, len in r2)

Strings

  • syscall strcmp - Compare strings (str1 in r0, str2 in r1, returns comparison in r0)
  • syscall strcpy - Copy string (dst in r0, src in r1, returns dst in r0)
  • syscall strlen - Get string length (str in r0, returns length in r0)
  • syscall starts_with - Check if string starts with prefix (str in r0, prefix in r1, returns 1/0 in r0)
  • syscall streq - Check if strings are equal (str1 in r0, str2 in r1, returns 1/0 in r0)
  • syscall ends_with - Check if string ends with suffix (str in r0, suffix in r1, returns 1/0 in r0)
  • syscall trim - Trim whitespace (str in r0, out in r1, returns length in r0)
  • syscall trim_start - Trim leading whitespace (str in r0, out in r1, returns length in r0)
  • syscall trim_end - Trim trailing whitespace (str in r0, out in r1, returns length in r0)
  • syscall isws - Check if string is all whitespace (str in r0, returns 1/0 in r0)

Conversion

  • syscall atoi - String to integer (str in r0, returns int in r0)
  • syscall atof - String to float (str in r0, returns float bits in r0)
  • syscall itoa - Integer to string (int in r0, buffer in r1, size in r2, returns length in r0)
  • syscall ftoa - Float to string (bits in r0, buffer in r1, size in r2, returns length in r0)
  • syscall itof - Integer to float (int in r0, returns float bits in r0)
  • syscall ftoi - Float to integer (bits in r0, returns int in r0)

Math

  • syscall fadd - Add floats (a bits in r0, b bits in r1, returns result bits in r0)
  • syscall fsub - Subtract floats
  • syscall fmul - Multiply floats
  • syscall fdiv - Divide floats
  • syscall fmod - Modulo floats

Time & Random

  • syscall time - Get current time (returns nanoseconds in r0)
  • syscall fmt_time - Format time (total_nanos in r0, format in r1, buffer in r2, returns length in r0)
  • syscall rand - Generate random float (seed in r0, returns float bits in r0)

Utilities

  • syscall sleep - Sleep for milliseconds (ms in r0)
  • syscall system - Execute system command (cmd in r0, returns exit code in r0)

System

  • syscall exit - Exit program (status in r0)

Examples

Hello World

; Hello World
mov "Hello, World!\n", r1
mov 1, r0
mov 14, r2
syscall write

mov 0, r0
syscall exit

Calculator

; Simple calculator
mov 10, r0
mov 20, r1
add r0, r1  ; r0 = 30

syscall print_int
mov "\n", r1
mov 1, r0
mov 1, r2
syscall write

mov 0, r0
syscall exit

Running Examples

The repository includes example LASM programs in the examples/ directory:

# Hello World

cargo run -- examples/hello.lasm


# Calculator

cargo run -- examples/calculator.lasm


# Time display

cargo run -- examples/time.lasm


# Interactive shell

cargo run -- examples/shell.lasm

Or after building the release binary:

./target/release/lasm examples/hello.lasm

Syntax Details

  • Comments: Start with ; and continue to end of line
  • Labels: End with : and can be jumped to
  • Strings: Enclosed in double quotes, null-terminated automatically
  • Numbers: Decimal integers, can be used as immediates
  • Case Sensitive: All keywords and register names are case sensitive

Error Handling

LASM provides clear error messages for:

  • Syntax errors
  • Undefined labels
  • Invalid register names
  • Unsupported syscalls
  • File I/O errors

Performance

LASM's JIT compilation provides significant performance advantages for compute-intensive tasks:

use lasm::{compile, call, Target, Value};
use std::collections::HashMap;

fn main() {
    // Simple variable manipulation example
    let simple_lasm = r#"
        load "input", r0     ; Load input value
        add r0, 100          ; Add 100
        push r0, "output"    ; Store result
        mov 0, r0
        syscall exit
    "#;
    
    // Compile once, reuse for multiple runs
    let target = Target::Native;
    let compiled = compile(simple_lasm, target).expect("Compile failed");
    
    // Execute with different inputs
    for input in 0..10 {
        let mut vars = HashMap::new();
        vars.insert("input".to_string(), Value::Int(input));
        
        let (exit_code, result_vars) = call(&compiled, &vars).expect("Execution failed");
        
        if let Some(Value::Int(result)) = result_vars.get("output") {
            println!("Input: {}, Output: {}", input, result);
        }
    }
}

JIT compilation enables dynamic code generation while maintaining high performance.

Limitations

  • 64-bit architecture only (x86_64, AArch64)
  • No floating point registers (floats stored as bits in general registers)
  • No direct hardware access
  • Stack operations are simulated

Testing

Run the test suite:

cargo test

The tests include various LASM programs demonstrating different features and syscalls.

Contributing

Contributions are welcome! This is a Rust crate that can be extended in several ways:

  • Additional Syscalls: Add new high-level operations
  • Optimization: Improve code generation and performance
  • Error Handling: Better error messages and recovery
  • Documentation: More examples and tutorials
  • Cross-Platform: Support for additional operating systems
  • Features: New instructions or language constructs

Development Setup

git clone https://github.com/SirPigari/lasm

cd lasm

cargo build

cargo test

Publishing

To publish to crates.io:

cargo publish

Make sure to update the version in Cargo.toml and tag the release.

License

MIT LICENSE