Calcite Assembler

A high-level assembly language compiler for the Coral CPU ISA, featuring Lua-like syntax with first-class support for capabilities, continuations, and algebraic effects.

Overview

Calcite is a novel assembly language designed specifically for the Coral ISA - a capability-based CPU architecture with built-in support for:

• Capabilities: Fine-grained memory safety with unforgeable pointers
• Algebraic Effects: First-class effect handlers for flexible control flow
• Continuations: Delimited continuations for advanced control patterns
• Unified Register Architecture: Seamless integration of scalars, capabilities, and continuations

Features

• Lua-like Syntax: Familiar, readable syntax with minimal punctuation
• Type-Aware: Leverages the Coral ISA's element type system
• Zero Boilerplate: Automatic bounds checking and permission management
• Comprehensive: Full support for all Coral ISA instructions and features

Architecture

The Calcite assembler is implemented in Go with a clean, modular architecture:

calcite/
├── cmd/calcite/          # CLI tool
├── internal/
│   ├── token/           # Token definitions
│   ├── lexer/           # Lexical analyzer
│   ├── ast/             # Abstract syntax tree
│   ├── parser/          # Recursive descent parser
│   ├── encoder/         # Instruction encoder
│   └── codegen/         # Code generator
├── examples/            # Example programs
└── docs/                # Documentation

Compilation Pipeline

1. Lexer → Tokenizes source code into lexical tokens
2. Parser → Builds an Abstract Syntax Tree (AST)
3. CodeGen → Generates Coral ISA instructions from AST
4. Encoder → Encodes instructions to 32-bit machine code

Building

go build ./cmd/calcite

Usage

# Compile a Calcite source file
./calcite input.calc output.bin

# Default output is 'out.bin' if not specified
./calcite input.calc

Language Reference

Basic Syntax

-- Comments start with --
--[[ Multi-line comments
     can span multiple lines ]]

-- Register assignment
r5 = 42
r6 = r5 + 10

-- Memory operations
[r10 + 16] = r5
r7 = [r10]

-- Sized loads/stores
byte [ptr] = value
r8 = word [buffer + 4]

Capabilities

-- Create a bounded capability
buffer = capability(0x10000, 4096, "rw")

-- Split into regions
header, payload = split(buffer, 64)

-- Narrow permissions
readonly = narrow(payload, "r")

-- Capability metadata
base = getbase(buffer)
len = getlen(buffer)

Control Flow

-- If statement
if r5 > 0 then
    r6 = r5 * 2
else
    r6 = 0
end

-- While loop
while r5 < 100 do
    r5 = r5 + 1
end

-- For loop
for i = 1, 10 do
    r5 = r5 + i
end

Functions

function add(a, b)
    result = a + b
    return result
end

r10 = add(5, 7)

Effects

-- Raise an effect
effect.console_write('H')
ch = effect.console_read()

-- Custom effects
result = effect.custom(0x40000001, arg: 42)

Continuations

-- Capture continuation
cont = capture()

-- Clone and resume
cont2 = clone(cont)
resume(cont)

Example Programs

Simple Arithmetic

.code

function main()
    r1 = 42
    r2 = 10

    r3 = r1 + r2    -- Addition
    r4 = r1 - r2    -- Subtraction
    r5 = r1 * r2    -- Multiplication

    return r3
end

Capability-Safe Memory Access

.code

function process_buffer()
    -- Create bounded buffer capability
    buf = capability(0x10000, 1024, "rw")

    -- Safe memory access (bounds checked)
    [buf] = 42
    value = [buf]

    -- Split for different regions
    header, data = split(buf, 64)

    return value
end

Instruction Set Support

The assembler supports all Coral ISA instruction categories:

• ✅ ALU Operations: ADD, SUB, MUL, DIV, AND, OR, XOR, shifts
• ✅ Memory Operations: Load/Store with multiple sizes (byte, half, word, dword)
• ✅ Branches: Conditional branches (signed/unsigned comparisons)
• ✅ Jumps: Unconditional jumps and function calls
• ✅ Capabilities: Create, split, merge, seal, narrow, move
• ✅ Continuations: Capture, resume, clone, seal
• ✅ Effects: Raise, handle, unhandle
• ✅ Memory Management: Allocate, free, resize
• ⚠️ Control Flow: Partial implementation (basic structures work)

Current Limitations

This is an initial implementation with some limitations:

• Control Flow: Basic if/while/for work, but complex nested structures need testing
• Large Immediates: Values outside 12-bit range need synthesis (not yet implemented)
• Function Calls: Calling convention not fully implemented
• Effect Handlers: Handler registration syntax parsed but not fully codegen'd
• Relocations: Label resolution for branches/jumps is basic
• Optimization: No optimization passes yet

Roadmap

• Complete control flow code generation
• Implement full function calling convention
• Add large immediate value synthesis
• Complete effect handler code generation
• Implement relocation and linking
• Add optimization passes (constant folding, dead code elimination)
• Create comprehensive test suite
• Add debugging symbol generation
• Implement macro system
• Add preprocessor directives (#include, #if, etc.)

Documentation

• calcite.md - Complete language specification
• coral.md - Coral ISA reference manual

Contributing

This is a novel architecture project. Contributions are welcome! Please ensure:

• Code follows Go best practices
• All functions are thoroughly documented (see CLAUDE.md)
• Use single tab indentation
• Use // for comments (Go standard)

License

See LICENSE file for details.

Authors

Built for the Coral ISA capability-based architecture project.