Lamina

High-Performance Compiler Backend

Lamina is a compiler infrastructure for the Lamina Intermediate Representation (IR), a statically-typed, SSA-based language designed to bridge the gap between high-level languages and low-level backends like LLVM and Cranelift.

Overview

Lamina IR serves as a mid-level intermediate representation with the following design principles:

• Human-readable and structurally clean
• Block-based control flow with explicit typing
• SSA (Static Single Assignment) form for all variables
• Strong type system with both primitive and composite types
• Explicit memory model distinguishing between stack and heap
• Designed for easy lowering to machine code

Features

Core Features

• Type System: Primitive and composite types
• Memory Model: Stack and heap allocations
• Control Flow: Basic blocks and branching
• SSA Representation: Single assignment form
• Function System: Typed parameters and returns

Advanced Capabilities

• Multi-Architecture: x86_64 and AArch64 support
• Direct Code Generation: Native assembly output
• Comprehensive Testing: 20+ test cases with automation
• IRBuilder API: Programmatic construction
• Performance Benchmarks: Competitive with systems languages

Direct Code Generation

Unlike many IR systems that rely on external backends like LLVM or Cranelift, Lamina directly generates machine code for multiple target architectures. This approach offers:

• Complete Control: Full control over code generation and optimization
• Multi-Architecture: Native support for x86_64 and AArch64 (ARM64)
• Reduced Dependencies: No external backend dependencies
• Customized Optimizations: IR-specific optimizations and patterns
• Faster Compilation: Direct assembly generation for certain workloads
• Cross-Platform: macOS, Linux, and Windows support

Current Status

Working Features

• Basic Arithmetic: All arithmetic operations work correctly

• Control Flow: Conditionals, loops, and branching

• Function Calls: Non-recursive function calls and returns

• Memory Operations: Stack and heap allocations

• Print Statements: Correct printf integration for both x86_64 and AArch64

• Performance: Competitive with systems languages in benchmarks

Building Compilers with Lamina

Lamina provides a powerful IRBuilder API that makes it straightforward to build compilers for other languages. A typical compiler using Lamina would:

1. Parse source language into an AST
2. Use the IRBuilder to transform the AST into Lamina IR
3. Let Lamina handle optimization and code generation

The IRBuilder API provides methods for:

• Creating modules, functions, and basic blocks
• Inserting instructions with proper SSA form
• Defining and manipulating types
• Managing memory allocations
• Setting up control flow

Here's a simple example of creating a basic arithmetic function using the Lamina IRBuilder:

use lamina::ir::*;

fn create_add_function() -> Result<Module, Error> {
    // Create a new module
    let mut builder = IRBuilder::new();
    let module = builder.create_module("math_example");
    
    // Define function signature: fn add(a: i32, b: i32) -> i32
    let params = vec![
        FunctionParameter { ty: Type::I32, name: "a".to_string() },
        FunctionParameter { ty: Type::I32, name: "b".to_string() },
    ];
    
    // Create the function
    let function = builder.create_function("add", params, Type::I32);
    
    // Create entry block
    let entry_block = builder.create_block("entry");
    builder.set_current_block(entry_block);
    
    // Get function parameters
    let param_a = builder.get_parameter(0);
    let param_b = builder.get_parameter(1);
    
    // Add the two parameters
    let result = builder.add_instruction(
        Instruction::BinaryOp {
            op: BinaryOperator::Add,
            ty: Type::I32,
            left: param_a,
            right: param_b,
        }
    );
    
    // Return the result
    builder.add_return(result);
    
    Ok(module)
}

// Usage example:
fn main() {
    let module = create_add_function().unwrap();
    let compiled = module.compile_to_assembly().unwrap();
    println!("Generated assembly:\n{}", compiled);
}

This generates the equivalent Lamina IR:

fn @add(i32 %a, i32 %b) -> i32 {
  entry:
    %result = add.i32 %a, %b
    ret.i32 %result
}

Performance Benchmarks

Lamina demonstrates competitive performance in computational tasks. The following results are from our comprehensive 256×256 2D matrix multiplication benchmark (500 runs with statistical analysis):

Benchmark Results (AMD Ryzen 9 9900X)

Notes:

• Lower ratios indicate better performance relative to Lamina
• Statistical outliers were removed using IQR method
• Memory measurements include peak RSS during execution
• Results show median values from 500 runs for compiled languages

Key Insights

• Competitive Performance: Lamina achieves performance comparable to established systems languages
• Memory Efficiency: Low memory footprint similar to C and Rust
• Consistent Results: Statistical analysis ensures reliable performance measurements
• Modern Language Integration: Competitive with Go, Rust, and C# in practical scenarios

Getting Started

Prerequisites

• Rust 1.70+ (2024 edition)

• Clang/GCC for linking generated assembly

• macOS, Linux, or Windows

Available Targets

• x86_64_linux: Linux x86_64

• x86_64_macos: macOS x86_64

• aarch64_macos: macOS ARM64 (Apple Silicon)

• aarch64_linux: Linux ARM64

Lamina IR Syntax

Lamina IR files consist of type declarations, global definitions, and function declarations:

# Type declaration
type @Vec2 = struct { x: f32, y: f32 }

# Global value
global @message: [5 x i8] = "hello"

# Function with annotations
@export
fn @add(i32 %a, i32 %b) -> i32 {
  entry:
    %sum = add.i32 %a, %b
    ret.i32 %sum
}

# Function with control flow
fn @conditional(i32 %x) -> i32 {
  entry:
    %is_pos = gt.i32 %x, 0
    br %is_pos, positive, negative
  
  positive:
    ret.i32 1
    
  negative:
    ret.i32 -1
}

Memory Operations

# Stack allocation
%ptr = alloc.ptr.stack i32

# Heap allocation
%hptr = alloc.ptr.heap i32

# Load and store
store.i32 %ptr, %val
%loaded = load.i32 %ptr

# Optional heap deallocation
dealloc.heap %hptr

Composite Type Operations

# Struct field access
%field_ptr = getfield.ptr %struct, 0
%value = load.f32 %field_ptr

# Array element access
%elem_ptr = getelem.ptr %array, %index
%value = load.i32 %elem_ptr

Advanced Example: Matrix Multiplication

# Matrix multiplication simulation
fn @compute_cell(i64 %row, i64 %col, i64 %size, i64 %matrix_value) -> i64 {
  entry:
    %row_plus_1 = add.i64 %row, 1
    %col_plus_1 = add.i64 %col, 1
    %factor1 = mul.i64 %matrix_value, %size
    %factor2 = mul.i64 %row_plus_1, %col_plus_1
    %result = mul.i64 %factor1, %factor2
    
    ret.i64 %result
}

@export
fn @main() -> i64 {
  entry:
    %matrix_size = add.i64 262144, 0
    %matrix_value = add.i64 2, 0
    
    print %matrix_size
    %_ = call @simulate_matmul(%matrix_size, %matrix_value)
    
    ret.i64 0
}

Future Directions

• Enhanced Optimizations: Loop analysis, auto-vectorization, and register allocation

• Additional Architectures: RISC-V and other ARM variants

• Language Integration: C, Rust, and custom language frontends

• JIT Compilation: Dynamic code execution support

• Debugging Tools: Enhanced debugging information and tooling

• Performance Improvements: Advanced optimization passes

• GPU Acceleration: support for generating code targeting GPU architectures (e.g., CUDA, Vulkan compute shaders) to enable parallel execution of compute-intensive workloads

Please feel free to submit pull requests or open issues for bugs and feature requests.