//! Minimal RV64 assembler.

//!

//! This module assembles `.ras` source files into RV64 text words plus a raw

//! data prefix that can be linked into a compiler-generated program. It exists

//! so the Radiance driver can mix hand-written RV64 assembly with generated IL

//! output without invoking an external assembler or linker.

//!

//! Assembly is intentionally direct and buffer-oriented. The caller provides a

//! text buffer, a data buffer, an arena, and the runtime base address where the

//! data buffer will be loaded. The parser writes encoded instructions into the

//! text buffer as it reads them and writes directive bytes into the data buffer

//! while in `.data`. The returned [`Program`] only contains slices into those

//! caller-provided buffers, so no ownership transfer or late copy is needed.

//!

//! The scanner is assembly-specific. It produces tokens for registers (`%a0`),

//! labels (`@name`), directives, strings, characters, numbers, and

//! punctuation. The parser consumes those tokens as a small line-oriented

//! language: *directives* declare sections or emit data, *labels* define

//! symbols at the current section offset, and *instructions* are validated

//! against RV64 operand forms before being encoded.

//!

//! Labels are defined at the current text instruction index or data byte

//! offset. The parser is single-pass because it keeps assembly cheap and lets

//! instructions and data be emitted immediately, but forward references mean

//! some operands cannot be encoded when first seen. Branches, jumps,

//! load-address operands, and data directives that reference labels therefore

//! record fixups. After parsing reaches EOF, the emitter resolves the final

//! symbol table and patches every recorded use with the correct PC-relative

//! offset, absolute data address, or encoded data value.

//!

//! Data labels are resolved relative to the data base address. The compiler

//! driver accumulates all assembly data in a RO data prefix, passes

//! [`RO_DATA_BASE`] + `currentPrefixLen` for each input, then appends the

//! input's emitted data to that prefix. Global text symbols are exported for

//! call resolution when the assembled text is appended to the RV64 generator,

//! shifted by the generator's current code length so disassembly/debug output

//! can name those instruction addresses correctly. Non-global text labels

//! remain local to their assembly fragment.

use std::lang::alloc;

use std::lang::strings;

use std::lang::gen;

use std::collections::dict;

use std::arch::rv64::encode;

use std::arch::rv64;

/// Assembler scanner module.

export mod scanner;

/// Assembler parser module.

export mod parser;

/// Assembler emission and fixup module.

export mod emit;

/// Tests.

@test mod tests;

/// In-memory result of assembling one RV64 assembly fragment.

///

/// [`Program`] is the boundary between the textual assembler and the rest of

/// the compiler. The assembler reads an assembly source file, encodes all

/// instructions, lays out all data bytes, resolves fixups that can be resolved

/// inside the fragment, and returns these three slices as the assembled

/// program.

///

/// The value is intentionally not a standalone object file or linked

/// executable. It carries only the sections and symbol table needed by the

/// compiler driver. The slices point at caller-owned storage: `text` and

/// `data` are backed by the buffers passed to [`assemble`], while symbol names

/// are interned in the assembler's string pool.

///

/// Symbol offsets are section-local byte offsets. Text symbols name positions

/// in `text`; data symbols name positions in `data`. When the compiler

/// consumes the program, [`rv64::addAssembly`] appends the text words to the

/// generated text stream and registers text labels at their relocated offsets.

/// The driver copies `data` into the final read-only data prefix; the data

/// base supplied to [`assemble`] lets the assembler resolve data addresses as

/// they will appear in that final layout.

export record Program: Copy {

    /// Encoded instructions in the text section.

    text: *[u32],

    /// Raw bytes in the data section.

    data: *[u8],

    /// Symbols defined by the source.

    symbols: *[Symbol],

    /// Text references resolved by the whole-program emitter.

    externalFixups: *[Fixup],

}

/// Errors reported while assembling source text.

export union Error: Copy {

    /// Invalid syntax or operand form at a source offset.

    Invalid { offset: u32, message: *[u8] },

    /// The source emitted more text words than the caller-provided buffer holds.

    TextOverflow,

    /// The source emitted more data bytes than the caller-provided buffer holds.

    DataOverflow,

}

/// Active output section.

export union Section: Copy {

    /// Instruction section.

    Text,

    /// Data byte section.

    Data,

}

/// Branch opcode that needs fixup.

export union BranchOp: Copy {

    /// Branch if equal.

    Beq,

    /// Branch if not equal.

    Bne,

    /// Branch if less than, signed.

    Blt,

    /// Branch if greater than or equal, signed.

    Bge,

    /// Branch if less than, unsigned.

    Bltu,

    /// Branch if greater than or equal, unsigned.

    Bgeu,

    /// Branch if less than or equal, signed pseudo-instruction.

    Ble,

    /// Branch if greater than, signed pseudo-instruction.

    Bgt,

}

/// Parser and encoder behavior for one instruction mnemonic.

export union InstructionEncoder: Copy {

    /// No-operand instruction encoded by a fixed encoder.

    NoOperand { enc: fn() -> u32 },

    /// Load-immediate pseudo-instruction.

    Li,

    /// Load-address pseudo-instruction.

    La,

    /// Two-register instruction or pseudo-instruction.

    RR { enc: fn(gen::Reg, gen::Reg) -> u32 },

    /// Three-register instruction.

    RRR { enc: fn(gen::Reg, gen::Reg, gen::Reg) -> u32 },

    /// Register, register, immediate instruction.

    RRI { enc: fn(gen::Reg, gen::Reg, i32) -> u32 },

    /// Shift-immediate instruction with RV64 shift bounds.

    Shift { enc: fn(gen::Reg, gen::Reg, i32) -> u32 },

    /// Shift-immediate instruction with RV64 W-mode shift bounds.

    WordShift { enc: fn(gen::Reg, gen::Reg, i32) -> u32 },

    /// Load instruction with memory operand syntax.

    Load { enc: fn(gen::Reg, gen::Reg, i32) -> u32 },

    /// Store instruction with memory operand syntax.

    Store { enc: fn(gen::Reg, gen::Reg, i32) -> u32 },

    /// Two-register branch instruction.

    Branch { op: BranchOp },

    /// One-register branch-to-zero pseudo-instruction.

    BranchZero { op: BranchOp },

    /// Memory fence with optional predecessor and successor masks.

    Fence,

    /// `jal` instruction with explicit destination register.

    Jal,

    /// Jump pseudo-instruction with fixed destination register.

    Jump { rd: gen::Reg },

    /// CSR read-style operand form.

    RdCsr { enc: fn(gen::Reg, u32) -> u32 },

    /// CSR write-style operand form.

    CsrRs1 { enc: fn(u32, gen::Reg) -> u32 },

    /// CSR read/write operand form.

    Csrrw,

    /// CSR immediate operand form.

    Csrsi,

    /// Upper-immediate operand form.

    Upper { enc: fn(gen::Reg, i32) -> u32 },

}

/// Classified directive name.

export union DirectiveKind: Copy {

    /// `.align` directive.

    Align,

    /// `.ascii` directive.

    Ascii,

    /// `.byte` directive.

    Byte,

    /// `.constant` directive.

    Constant,

    /// `.data` directive.

    Data,

    /// `.dword` directive.

    Dword,

    /// `.export` directive.

    Export,

    /// `.space` directive.

    Space,

    /// `.text` directive.

    Text,

    /// `.word` directive.

    Word,

}

/// Instruction descriptor table row.

record InstructionEntry: Copy {

    /// Assembly mnemonic text.

    name: *[u8],

    /// Operand parser and encoder behavior.

    encoder: InstructionEncoder,

}

/// Directive descriptor table row.

record DirectiveEntry: Copy {

    /// Directive name without the leading `.`.

    name: *[u8],

    /// Parser behavior for the directive.

    kind: DirectiveKind,

}

/// Register descriptor table row.

record RegisterEntry: Copy {

    /// Register alias text without the leading `%`.

    name: *[u8],

    /// Numeric register selected by the alias.

    reg: gen::Reg,

}

/// CSR descriptor table row.

record CsrEntry: Copy {

    /// CSR name text.

    name: *[u8],

    /// Numeric CSR address.

    csr: u32,

}

/// Width of an integer data directive.

export union DataWidth: Copy {

    /// 32-bit data value.

    Word,

    /// 64-bit data value.

    Dword,

}

/// Extra slot used when sizing source-derived symbol and fixup buffers.

export constant SOURCE_CAP_PADDING: u32 = 1;

/// Scale factor used to keep assembler hash tables sparse.

export constant TABLE_CAPACITY_SCALE: u32 = 4;

/// Minimum hash-table capacity used by the assembler.

export constant MIN_TABLE_CAPACITY: u32 = 8;

/// `@label` names exclude the leading sigil byte when interned.

export constant LABEL_SIGIL_LEN: u32 = 1;

/// `.directive` names exclude the leading sigil byte when matched.

export constant DIRECTIVE_SIGIL_LEN: u32 = 1;

/// String and character literals are delimited by one byte on each side.

export constant QUOTE_DELIM_LEN: u32 = 1;

/// Number of bits in one byte.

export constant BITS_PER_BYTE: u64 = 8;

/// Mask for extracting one encoded byte.

export constant BYTE_MASK: u64 = 0xFF;

/// Largest signed 32-bit assembler value.

export constant I32_MAX_VALUE: i64 = 2147483647;

/// Magnitude of the smallest signed 32-bit assembler value.

export constant I32_MIN_MAGNITUDE: i64 = 2147483648;

/// Largest unsigned 32-bit assembler value.

export constant U32_MAX_VALUE: i64 = 4294967295;

/// Largest unsigned 8-bit assembler value.

export constant U8_MAX_VALUE: i64 = 255;

/// Upper bound for CSR immediate operands.

export constant CSR_IMM_LIMIT: i64 = 32;

/// Upper bound for RV64 W-mode shift immediates.

export constant WORD_SHIFT_LIMIT: i32 = 32;

/// Upper bound for RV64 shift immediates.

export constant SHIFT_LIMIT: i32 = 64;

/// Largest `lui` or `auipc` immediate.

export constant UPPER_IMM_MAX_VALUE: i64 = 0xFFFFF;

/// Sorted instruction descriptor table used by the assembler parser.

export constant INSTRUCTIONS: [InstructionEntry; 89] = [

    { name: "add",    encoder: InstructionEncoder::RRR { enc: encode::add } },

    { name: "addi",   encoder: InstructionEncoder::RRI { enc: encode::addi } },

    { name: "addiw",  encoder: InstructionEncoder::RRI { enc: encode::addiw } },

    { name: "addw",   encoder: InstructionEncoder::RRR { enc: encode::addw } },

    { name: "and",    encoder: InstructionEncoder::RRR { enc: encode::and_ } },

    { name: "andi",   encoder: InstructionEncoder::RRI { enc: encode::andi } },

    { name: "auipc",  encoder: InstructionEncoder::Upper { enc: encode::auipc } },

    { name: "beq",    encoder: InstructionEncoder::Branch { op: BranchOp::Beq } },

    { name: "beqz",   encoder: InstructionEncoder::BranchZero { op: BranchOp::Beq } },

    { name: "bge",    encoder: InstructionEncoder::Branch { op: BranchOp::Bge } },

    { name: "bgeu",   encoder: InstructionEncoder::Branch { op: BranchOp::Bgeu } },

    { name: "bgt",    encoder: InstructionEncoder::Branch { op: BranchOp::Bgt } },

    { name: "ble",    encoder: InstructionEncoder::Branch { op: BranchOp::Ble } },

    { name: "blt",    encoder: InstructionEncoder::Branch { op: BranchOp::Blt } },

    { name: "bltu",   encoder: InstructionEncoder::Branch { op: BranchOp::Bltu } },

    { name: "bne",    encoder: InstructionEncoder::Branch { op: BranchOp::Bne } },

    { name: "bnez",   encoder: InstructionEncoder::BranchZero { op: BranchOp::Bne } },

    { name: "call",   encoder: InstructionEncoder::Jump { rd: rv64::RA } },

    { name: "csrc",   encoder: InstructionEncoder::CsrRs1 { enc: encode::csrc } },

    { name: "csrr",   encoder: InstructionEncoder::RdCsr { enc: encode::csrr } },

    { name: "csrrw",  encoder: InstructionEncoder::Csrrw },

    { name: "csrsi",  encoder: InstructionEncoder::Csrsi },

    { name: "csrw",   encoder: InstructionEncoder::CsrRs1 { enc: encode::csrw } },

    { name: "div",    encoder: InstructionEncoder::RRR { enc: encode::div } },

    { name: "divu",   encoder: InstructionEncoder::RRR { enc: encode::divu } },

    { name: "divuw",  encoder: InstructionEncoder::RRR { enc: encode::divuw } },

    { name: "divw",   encoder: InstructionEncoder::RRR { enc: encode::divw } },

    { name: "ebreak", encoder: InstructionEncoder::NoOperand { enc: encode::ebreak } },

    { name: "ecall",  encoder: InstructionEncoder::NoOperand { enc: encode::ecall } },

    { name: "fence",  encoder: InstructionEncoder::Fence },

    { name: "fence.i", encoder: InstructionEncoder::NoOperand { enc: encode::fenceI } },

    { name: "j",      encoder: InstructionEncoder::Jump { rd: rv64::ZERO } },

    { name: "jal",    encoder: InstructionEncoder::Jal },

    { name: "jalr",   encoder: InstructionEncoder::RRI { enc: encode::jalr } },

    { name: "la",     encoder: InstructionEncoder::La },

    { name: "lb",     encoder: InstructionEncoder::Load { enc: encode::lb } },

    { name: "lbu",    encoder: InstructionEncoder::Load { enc: encode::lbu } },

    { name: "ld",     encoder: InstructionEncoder::Load { enc: encode::ld } },

    { name: "lh",     encoder: InstructionEncoder::Load { enc: encode::lh } },

    { name: "lhu",    encoder: InstructionEncoder::Load { enc: encode::lhu } },

    { name: "li",     encoder: InstructionEncoder::Li },

    { name: "lui",    encoder: InstructionEncoder::Upper { enc: encode::lui } },

    { name: "lw",     encoder: InstructionEncoder::Load { enc: encode::lw } },

    { name: "lwu",    encoder: InstructionEncoder::Load { enc: encode::lwu } },

    { name: "mret",   encoder: InstructionEncoder::NoOperand { enc: encode::mret } },

    { name: "mul",    encoder: InstructionEncoder::RRR { enc: encode::mul } },

    { name: "mulh",   encoder: InstructionEncoder::RRR { enc: encode::mulh } },

    { name: "mulhsu", encoder: InstructionEncoder::RRR { enc: encode::mulhsu } },

    { name: "mulhu",  encoder: InstructionEncoder::RRR { enc: encode::mulhu } },

    { name: "mulw",   encoder: InstructionEncoder::RRR { enc: encode::mulw } },

    { name: "mv",     encoder: InstructionEncoder::RR { enc: encode::mv } },

    { name: "neg",    encoder: InstructionEncoder::RR { enc: encode::neg } },

    { name: "nop",    encoder: InstructionEncoder::NoOperand { enc: encode::nop } },

    { name: "not",    encoder: InstructionEncoder::RR { enc: encode::not_ } },

    { name: "or",     encoder: InstructionEncoder::RRR { enc: encode::or_ } },

    { name: "ori",    encoder: InstructionEncoder::RRI { enc: encode::ori } },

    { name: "rem",    encoder: InstructionEncoder::RRR { enc: encode::rem } },

    { name: "remu",   encoder: InstructionEncoder::RRR { enc: encode::remu } },

    { name: "remuw",  encoder: InstructionEncoder::RRR { enc: encode::remuw } },

    { name: "remw",   encoder: InstructionEncoder::RRR { enc: encode::remw } },

    { name: "ret",    encoder: InstructionEncoder::NoOperand { enc: encode::ret } },

    { name: "sb",     encoder: InstructionEncoder::Store { enc: encode::sb } },

    { name: "sd",     encoder: InstructionEncoder::Store { enc: encode::sd } },

    { name: "seqz",   encoder: InstructionEncoder::RR { enc: encode::seqz } },

    { name: "sh",     encoder: InstructionEncoder::Store { enc: encode::sh } },

    { name: "sll",    encoder: InstructionEncoder::RRR { enc: encode::sll } },

    { name: "slli",   encoder: InstructionEncoder::Shift { enc: encode::slli } },

    { name: "slliw",  encoder: InstructionEncoder::WordShift { enc: encode::slliw } },

    { name: "sllw",   encoder: InstructionEncoder::RRR { enc: encode::sllw } },

    { name: "slt",    encoder: InstructionEncoder::RRR { enc: encode::slt } },

    { name: "slti",   encoder: InstructionEncoder::RRI { enc: encode::slti } },

    { name: "sltiu",  encoder: InstructionEncoder::RRI { enc: encode::sltiu } },

    { name: "sltu",   encoder: InstructionEncoder::RRR { enc: encode::sltu } },

    { name: "snez",   encoder: InstructionEncoder::RR { enc: encode::snez } },

    { name: "sra",    encoder: InstructionEncoder::RRR { enc: encode::sra } },

    { name: "srai",   encoder: InstructionEncoder::Shift { enc: encode::srai } },

    { name: "sraiw",  encoder: InstructionEncoder::WordShift { enc: encode::sraiw } },

    { name: "sraw",   encoder: InstructionEncoder::RRR { enc: encode::sraw } },

    { name: "srl",    encoder: InstructionEncoder::RRR { enc: encode::srl } },

    { name: "srli",   encoder: InstructionEncoder::Shift { enc: encode::srli } },

    { name: "srliw",  encoder: InstructionEncoder::WordShift { enc: encode::srliw } },

    { name: "srlw",   encoder: InstructionEncoder::RRR { enc: encode::srlw } },

    { name: "sub",    encoder: InstructionEncoder::RRR { enc: encode::sub } },

    { name: "subw",   encoder: InstructionEncoder::RRR { enc: encode::subw } },

    { name: "sw",     encoder: InstructionEncoder::Store { enc: encode::sw } },

    { name: "tail",   encoder: InstructionEncoder::Jump { rd: rv64::ZERO } },

    { name: "wfi",    encoder: InstructionEncoder::NoOperand { enc: encode::wfi } },

    { name: "xor",    encoder: InstructionEncoder::RRR { enc: encode::xor } },

    { name: "xori",   encoder: InstructionEncoder::RRI { enc: encode::xori } },

];

/// Sorted directive lookup table used by the assembler parser.

export constant DIRECTIVES: [DirectiveEntry; 10] = [

    { name: "align",    kind: DirectiveKind::Align },

    { name: "ascii",    kind: DirectiveKind::Ascii },

    { name: "byte",     kind: DirectiveKind::Byte },

    { name: "constant", kind: DirectiveKind::Constant },

    { name: "data",     kind: DirectiveKind::Data },

    { name: "dword",    kind: DirectiveKind::Dword },

    { name: "export",   kind: DirectiveKind::Export },

    { name: "space",    kind: DirectiveKind::Space },

    { name: "text",     kind: DirectiveKind::Text },

    { name: "word",     kind: DirectiveKind::Word },

];

/// Sorted register-name lookup table used by the assembler parser.

export constant REGISTERS: [RegisterEntry; 33] = [

    { name: "a0",   reg: rv64::A0 },

    { name: "a1",   reg: rv64::A1 },

    { name: "a2",   reg: rv64::A2 },

    { name: "a3",   reg: rv64::A3 },

    { name: "a4",   reg: rv64::A4 },

    { name: "a5",   reg: rv64::A5 },

    { name: "a6",   reg: rv64::A6 },

    { name: "a7",   reg: rv64::A7 },

    { name: "fp",   reg: rv64::FP },

    { name: "gp",   reg: rv64::GP },

    { name: "ra",   reg: rv64::RA },

    { name: "s0",   reg: rv64::S0 },

    { name: "s1",   reg: rv64::S1 },

    { name: "s10",  reg: rv64::S10 },

    { name: "s11",  reg: rv64::S11 },

    { name: "s2",   reg: rv64::S2 },

    { name: "s3",   reg: rv64::S3 },

    { name: "s4",   reg: rv64::S4 },

    { name: "s5",   reg: rv64::S5 },

    { name: "s6",   reg: rv64::S6 },

    { name: "s7",   reg: rv64::S7 },

    { name: "s8",   reg: rv64::S8 },

    { name: "s9",   reg: rv64::S9 },

    { name: "sp",   reg: rv64::SP },

    { name: "t0",   reg: rv64::T0 },

    { name: "t1",   reg: rv64::T1 },

    { name: "t2",   reg: rv64::T2 },

    { name: "t3",   reg: rv64::T3 },

    { name: "t4",   reg: rv64::T4 },

    { name: "t5",   reg: rv64::T5 },

    { name: "t6",   reg: rv64::T6 },

    { name: "tp",   reg: rv64::TP },

    { name: "zero", reg: rv64::ZERO },

];

/// Sorted CSR-name lookup table used by the assembler parser.

export constant CSRS: [CsrEntry; 10] = [

    { name: "instret",  csr: 0xC02 },

    { name: "mcause",   csr: 0x342 },

    { name: "mepc",     csr: 0x341 },

    { name: "mhartid",  csr: 0xF14 },

    { name: "mie",      csr: 0x304 },

    { name: "mip",      csr: 0x344 },

    { name: "mscratch", csr: 0x340 },

    { name: "mstatus",  csr: 0x300 },

    { name: "mtval",    csr: 0x343 },

    { name: "mtvec",    csr: 0x305 },

];

/// Recorded symbol definition.

export record Symbol: Copy {

    /// Symbol name.

    name: *[u8],

    /// Section the symbol belongs to.

    section: Section,

    /// Byte offset within the section.

    offset: i32,

    /// Whether `.export` exported this symbol outside its assembly fragment.

    isExported: bool,

}

/// Information needed to resolve a pending symbol reference.

export union FixupInfo: Copy {

    /// Branch to a text label.

    Branch { op: BranchOp, rs1: gen::Reg, rs2: gen::Reg, index: u32 },

    /// JAL-like jump to a text label.

    Jal { rd: gen::Reg, index: u32 },

    /// Absolute address materialization into a register.

    Addr { rd: gen::Reg, index: u32 },

    /// A 32-bit data word referring to a symbol offset.

    Word { offset: u32 },

    /// A 64-bit data word referring to a symbol offset.

    Dword { offset: u32 },

}

/// Pending symbol reference.

export record Fixup: Copy {

    /// Referenced symbol.

    symbol: *[u8],

    /// Fixup payload.

    info: FixupInfo,

}

/// Parser and emission state.

export record Assembler {

    /// Allocation arena for temporary assembler state.

    arena: *unsafe mut alloc::Arena,

    /// Assembler lexical scanner.

    scan: scanner::Scanner,

    /// Output text buffer.

    text: *mut [u32],

    /// Number of emitted text words.

    textLen: u32,

    /// Output data buffer.

    data: *mut [u8],

    /// Number of emitted data bytes.

    dataLen: u32,

    /// Current output section.

    section: Section,

    /// Defined symbols.

    symbols: *mut [Symbol],

    /// Number of defined symbols.

    symbolsLen: u32,

    /// Name-to-symbol index map.

    symbolMap: dict::Dict,

    /// Name-to-integer map.

    constMap: dict::Dict,

    /// Names marked by `.export`.

    exportMap: dict::Dict,

    /// Pending fixups.

    fixups: *mut [Fixup],

    /// Number of pending fixups.

    fixupsLen: u32,

    /// Fixups that reference text outside this assembly fragment.

    externalFixups: *mut [Fixup],

    /// Number of external fixups.

    externalFixupsLen: u32,

    /// Absolute runtime address of data-section offset zero.

    dataBase: u32,

}

/// Assemble source using `dataBase` as the runtime address of the data-section.

export unsafe fn assemble(

    sourceKind: scanner::SourceKind,

    source: *[u8],

    textBuf: *mut [u32],

    dataBuf: *mut [u8],

    arena: &mut alloc::Arena,

    pool: *unsafe mut strings::Pool,

    dataBase: u32

) -> Program throws (Error) {

    let slotCap = tokenCapacity(sourceKind, source, pool);

    let tableCap = nextPowerOfTwo(slotCap * TABLE_CAPACITY_SCALE);

    let symbols = try! alloc::allocSlice(arena, @sizeOf(Symbol), @alignOf(Symbol), slotCap);

    let fixups = try! alloc::allocSlice(arena, @sizeOf(Fixup), @alignOf(Fixup), slotCap);

    let externalFixups = try! alloc::allocSlice(arena, @sizeOf(Fixup), @alignOf(Fixup), slotCap);

    let entries = try! alloc::allocSlice(arena, @sizeOf(dict::Entry), @alignOf(dict::Entry), tableCap);

    let constEntries = try! alloc::allocSlice(arena, @sizeOf(dict::Entry), @alignOf(dict::Entry), tableCap);

    let exportEntries = try! alloc::allocSlice(arena, @sizeOf(dict::Entry), @alignOf(dict::Entry), tableCap);

    let symbolBuf = symbols as *mut [Symbol];

    let fixupBuf = fixups as *mut [Fixup];

    let externalBuf = externalFixups as *mut [Fixup];

    let mut a = Assembler {

        arena: arena as *unsafe mut alloc::Arena,

        scan: scanner::scanner(sourceKind, source, pool),

        text: textBuf,

        textLen: 0,

        data: dataBuf,

        dataLen: 0,

        section: Section::Text,

        symbols: symbolBuf,

        symbolsLen: 0,

        symbolMap: dict::init(entries as *mut [dict::Entry]),

        constMap: dict::init(constEntries as *mut [dict::Entry]),

        exportMap: dict::init(exportEntries as *mut [dict::Entry]),

        fixups: fixupBuf,

        fixupsLen: 0,

        externalFixups: externalBuf,

        externalFixupsLen: 0,

        dataBase,

    };

    // Parse assembly source and emit instructions.

    try parser::parseProgram(&mut a);

    // Resolve fixups and finalize program.

    try emit::finishProgram(&mut a);

    let case Assembler {

        text, textLen, data, dataLen, symbols: definedSymbols, symbolsLen,

        externalFixups: pendingFixups, externalFixupsLen, ..

    } = a

        else panic "expected assembler state";

    return Program {

        text: &text[..textLen],

        data: &data[..dataLen],

        symbols: &definedSymbols[..symbolsLen],

        externalFixups: &pendingFixups[..externalFixupsLen],

    };

}

/// Bound symbol and fixup counts by lexical tokens, including one spare slot.

unsafe fn tokenCapacity(kind: scanner::SourceKind, source: *[u8], pool: *unsafe mut strings::Pool) -> u32 {

    let mut scan = scanner::scanner(kind, source, pool);

    let mut count = SOURCE_CAP_PADDING;

    while true {

        let token = scanner::next(&mut scan);

        if token.kind == scanner::TokenKind::Eof {

            break;

        }

        set count += 1;

        if token.kind == scanner::TokenKind::Invalid {

            break;

        }

    }

    return count;

}

/// Return the next power of two at least as large as `value`.

fn nextPowerOfTwo(value: u32) -> u32 {

    let mut n: u32 = MIN_TABLE_CAPACITY;

    while n < value {

        set n <<= 1;

    }

    return n;

}