/// Fixup payload.

    info: FixupInfo,

}

/// Parser and emission state.

    /// 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.

    sourceKind: scanner::SourceKind,

    source: *[u8],

    textBuf: *mut [u32],

    dataBuf: *mut [u8],

    arena: &mut alloc::Arena,

    dataBase: u32

) -> Program throws (Error) {

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

    let tableCap = nextPowerOfTwo(slotCap * TABLE_CAPACITY_SCALE);

    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];

}

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

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

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

use std::collections::dict;

use std::lang::gen;

/// Define a symbol at the current text or data offset.

    let idx = a.symbolsLen;

    let offset: i32 = a.dataLen as i32

        if a.section == super::Section::Data

        else a.textLen as i32 * rv64::INSTR_SIZE;

    set a.symbolsLen += 1;

    dict::insert(&mut a.symbolMap, name, idx as i32);

}

/// Append one encoded instruction word to the text section.

    if a.textLen >= a.text.len {

        throw super::Error::TextOverflow;

    }

    set a.text[a.textLen] = word;

    set a.textLen += 1;

}

/// Append `words` no-op instructions to the text section.

    for _ in 0..words {

        try emitText(a, encode::nop());

    }

}

/// Append one byte to the data section.

    if a.dataLen >= a.data.len {

        throw super::Error::DataOverflow;

    }

    set a.data[a.dataLen] = byte;

    set a.dataLen += 1;

}

/// Emit a little-endian integer with `bytes` bytes.

    for i in 0..bytes {

        try emitByte(a, ((bits >> ((i as u64) * super::BITS_PER_BYTE)) & super::BYTE_MASK) as u8);

    }

}

/// Patch a little-endian integer with `bytes` bytes.

    for i in 0..bytes {

        set a.data[offset + i] = ((bits >> ((i as u64) * super::BITS_PER_BYTE)) & super::BYTE_MASK) as u8;

    }

}

/// Emit an integer data directive value.

    match width {

        case super::DataWidth::Word => try emitDataInt(a, value as u64, rv64::WORD_SIZE as u32),

        case super::DataWidth::Dword => try emitDataInt(a, value as u64, rv64::DWORD_SIZE as u32),

    }

}

/// Record a data-section symbol fixup and reserve its bytes.

    let offset = a.dataLen;

    match width {

        case super::DataWidth::Word => {

            recordFixup(a, target, super::FixupInfo::Word { offset });

            try emitDataInt(a, 0, rv64::WORD_SIZE as u32);

        }

    }

}

/// Record a pending symbol fixup.

    assert a.fixupsLen < a.fixups.len, "recordFixup: fixup buffer full";

    set a.fixups[a.fixupsLen] = super::Fixup { symbol, info };

    set a.fixupsLen += 1;

}

/// Record a text fixup that must be resolved after all program text is known.

    assert a.externalFixupsLen < a.externalFixups.len, "recordExternalFixup: fixup buffer full";

    set a.externalFixups[a.externalFixupsLen] = fixup;

    set a.externalFixupsLen += 1;

}

/// Record a text-section symbol fixup and reserve its instruction words.

    recordFixup(a, symbol, info);

    try emitTextPadding(a, words);

}

/// Find a previously defined symbol by name.

    let idx = dict::get(&a.symbolMap, name)

        else return nil;

    return a.symbols[idx as u32];

}

/// Return the final address for a data symbol.

    if symbol.section <> super::Section::Data {

        throw super::Error::Invalid { offset: 0, message: "data address target must be in data section" };

    }

    return symbol.offset + (a.dataBase as i32);

}

/// Resolve final symbol references and patch all delayed output.

    for i in 0..a.fixupsLen {

        let fixup = a.fixups[i];

        let symbol = findSymbol(a, fixup.symbol) else {

            match fixup.info {

                case super::FixupInfo::Jal { .. }, super::FixupInfo::Addr { .. } => {

        case super::BranchOp::Bgt  => return encode::bgt(rs1, rs2, imm),

    }

}

/// Decode string literal escapes and emit the resulting data bytes.

    let raw = &literal[super::QUOTE_DELIM_LEN..literal.len - super::QUOTE_DELIM_LEN];

    let mut i: u32 = 0;

    while i < raw.len {

        if raw[i] == '\\' and i + 1 < raw.len {

    /// Signed byte offset preceding the base register.

    offset: i32,

}

/// Parse assembler source into the supplied assembler state.

    advance(a);

    while a.scan.current.kind <> scanner::TokenKind::Eof {

        try parseItem(a);

    }

    }

    return mem::alignUp(value, alignment);

}

/// Advance the parser by one token, preserving the previous token.

    set a.scan.previous = a.scan.current;

    set a.scan.current = scanner::next(&mut a.scan, a.pool);

}

/// Consume the current token when it has `kind`.

    if a.scan.current.kind == kind {

        advance(a);

        return true;

    }

    return false;

}

/// Create an error at the current token.

    return super::Error::Invalid { offset: a.scan.current.offset, message };

}

/// Create an error at `tok`.

fn failOnToken(tok: scanner::Token, message: *[u8]) -> super::Error {

    return super::Error::Invalid { offset: tok.offset, message };

}

/// Require that a data directive appears while assembling the data section.

    if a.section <> super::Section::Data {

        throw failOnToken(tok, "data directive is only valid in the data section");

    }

}

/// Consume `kind` or throw `message` at the current token.

    if not consume(a, kind) {

        throw fail(a, message);

    }

}

/// Consume `kind` and return the consumed token.

    try expect(a, kind, message);

    return a.scan.previous;

}

/// Require that the current item has reached its semicolon terminator.

    if a.scan.current.kind <> scanner::TokenKind::Semicolon {

        throw fail(a, message);

    }

}

/// Require that `value` fits in i32.

    if value < -super::I32_MIN_MAGNITUDE or value > super::I32_MAX_VALUE {

        throw fail(a, message);

    }

    return value as i32;

}

/// Require that `value` fits in a signed 12-bit immediate field.

    if not encode::isSmallImm64(value) {

        throw fail(a, "immediate out of range");

    }

    return value as i32;

}

/// Define a label at the current text or data offset.

    if dict::get(&a.symbolMap, name) <> nil {

        throw failOnToken(tok, "duplicate label");

    }

    emit::defineSymbol(a, name);

}

/// Emit a parsed integer data value after applying source-level range checks.

    match width {

        case super::DataWidth::Word =>

            try emit::emitDataValue(a, (try expectI32Value(a, value, "word literal out of range")) as i64, width),

        case super::DataWidth::Dword =>

            try emit::emitDataValue(a, value, width),

    }

}

/// Parse a possibly scoped name from one or more `::`-separated segments.

    kind: scanner::TokenKind,

    message: *[u8],

    trimPrefix: u32

) -> *[u8] throws (super::Error) {

    let first = try expectToken(a, kind, message);

    let source = &a.scan.source[start..end];

    return strings::intern(a.pool, source);

}

/// Parse a bare symbol name.

    return try parseScopedName(a, scanner::TokenKind::Ident, "expected symbol name", 0);

}

/// Return `true` when [`tok`] is any label token form.

fn isLabel(tok: scanner::TokenKind) -> bool {

    return tok == scanner::TokenKind::Label or tok == scanner::TokenKind::QuotedLabel;

}

/// Parse the contents of a quoted label token, decoding escapes as needed.

    let tok = try expectToken(a, scanner::TokenKind::QuotedLabel, "expected label name");

    let rawStart = super::LABEL_SIGIL_LEN + super::QUOTE_DELIM_LEN;

    let raw = &tok.source[rawStart..tok.source.len - super::QUOTE_DELIM_LEN];

    let storage = try alloc::allocSlice(a.arena, 1, 1, raw.len) catch {

        panic "asm: out of memory allocating quoted label";

    return strings::intern(a.pool, &storage[..len]);

}

/// Parse a label reference or definition name.

    if a.scan.current.kind == scanner::TokenKind::QuotedLabel {

        return try parseQuotedLabelName(a);

    }

    return try parseScopedName(a, scanner::TokenKind::Label, "expected label name", super::LABEL_SIGIL_LEN);

}

/// Parse a directive name without its leading `.`.

    let name = try expectToken(a, scanner::TokenKind::Directive, "expected directive name");

    return &name.source[super::DIRECTIVE_SIGIL_LEN..];

}

/// Parse one top-level assembler item.

    match a.scan.current.kind {

        case scanner::TokenKind::Ident => {

            let tok = a.scan.current;

            let name = try parseSymbolName(a);

            try parseInstruction(a, name, tok);

    };

    return super::CSRS[index].csr;

}

/// Parse an instruction after its mnemonic has already been consumed.

    if a.section <> super::Section::Text {

        throw failOnToken(tok, "instructions are only valid in the text section");

    }

    if let format = atomics::parse(name) {

        let rd = try parseRegister(a);

        case super::InstructionEncoder::Upper { enc } => return try parseUpper(a, enc),

    }

}

/// Parse the `li` pseudo-instruction.

    let rd = try parseRegister(a);

    let value = try parseValue(a);

    if encode::isSmallImm64(value) {

        try emit::emitText(a, encode::addi(rd, rv64::ZERO, value as i32));

        return;

    try emit::emitText(a, encode::lui(rd, split.hi));

    try emit::emitText(a, encode::addi(rd, rd, split.lo));

}

/// Parse the `la` pseudo-instruction.

    let rd = try parseRegister(a);

    let target = try parseLabelName(a);

    let index = a.textLen;

    try emit::recordTextFixup(a, target, super::FixupInfo::Addr { rd, index }, 2);

}

/// Parse a CSR read-like instruction with destination register then CSR.

    let rd = try parseRegister(a);

    let csr = try parseCsr(a);

    try emit::emitText(a, enc(rd, csr));

}

/// Parse a CSR write-like instruction with CSR then source register.

    let csr = try parseCsr(a);

    let rs1 = try parseRegister(a);

    try emit::emitText(a, enc(csr, rs1));

}

/// Parse `csrrw`.

    let rd = try parseRegister(a);

    let csr = try parseCsr(a);

    let rs1 = try parseRegister(a);

    try emit::emitText(a, encode::csrrw(rd, csr, rs1));

}

/// Parse a CSR immediate instruction.

    let csr = try parseCsr(a);

    let imm = try parseValue(a);

    if imm < 0 or imm >= super::CSR_IMM_LIMIT {

        throw fail(a, "CSR immediate out of range");

    }

    try emit::emitText(a, encode::csrsi(csr, imm as u32));

}

/// Parse a two-register instruction.

    let rd = try parseRegister(a);

    let rs = try parseRegister(a);

    try emit::emitText(a, enc(rd, rs));

}

/// Parse a three-register instruction.

    let rd = try parseRegister(a);

    let rs1 = try parseRegister(a);

    let rs2 = try parseRegister(a);

    try emit::emitText(a, enc(rd, rs1, rs2));

}

/// Parse a register-register-immediate instruction.

    let rd = try parseRegister(a);

    let rs1 = try parseRegister(a);

    let imm = try parseSmallImm(a);

    try emit::emitText(a, enc(rd, rs1, imm));

}

/// Parse a shift-immediate instruction and enforce its RV64 shift bound.

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

    limit: i32,

    message: *[u8]

) throws (super::Error) {

    let rd = try parseRegister(a);

    try emit::emitText(a, enc(rd, rs1, shamt));

}

/// Parse a load instruction with a memory operand.

    let rd = try parseRegister(a);

    let memop = try parseMemory(a);

    try emit::emitText(a, enc(rd, memop.base, memop.offset));

}

/// Parse a store instruction with a memory operand.

    let rs2 = try parseRegister(a);

    let memop = try parseMemory(a);

    try emit::emitText(a, enc(rs2, memop.base, memop.offset));

}

/// Parse a two-register branch instruction.

    let rs1 = try parseRegister(a);

    let rs2 = try parseRegister(a);

    try parseBranchLabel(a, op, rs1, rs2);

}

/// Parse an optional label operand.

    if not isLabel(a.scan.current.kind) {

        return nil;

    }

    return try parseLabelName(a);

}

/// Parse a branch target as either a label fixup or immediate offset.

    let index = a.textLen;

    if let target = try parseOptionalLabel(a) {

        try emit::recordTextFixup(a, target, super::FixupInfo::Branch { op, rs1, rs2, index }, 1);

        return;

    }

    let imm = try parseBranchImm(a);

    try emit::emitText(a, emit::encodeBranch(op, rs1, rs2, imm));

}

/// Parse a branch-to-zero pseudo-instruction.

    let rs = try parseRegister(a);

    try parseBranchLabel(a, op, rs, rv64::ZERO);

}

/// Parse `jal` with an explicit destination register.

    let rd = try parseRegister(a);

    try parseJ(a, rd);

}

/// Parse a jump target for `jal` or a jump pseudo-instruction.

    let index = a.textLen;

    if let target = try parseOptionalLabel(a) {

        try emit::recordTextFixup(a, target, super::FixupInfo::Jal { rd, index }, 1);

        return;

    }

    let imm = try parseJumpImm(a);

    try emit::emitText(a, encode::jal(rd, imm));

}

/// Parse an upper-immediate instruction.

    let rd = try parseRegister(a);

    let imm64 = try parseValue(a);

    if imm64 < 0 or imm64 > super::UPPER_IMM_MAX_VALUE {

        throw fail(a, "upper immediate out of range");

    }

    try emit::emitText(a, enc(rd, imm64 as i32));

}

/// Parse a directive after its name has already been consumed.

    let directive = classifyDirective(name) else {

        throw failOnToken(tok, "unknown directive");

    };

    match directive {

        case super::DirectiveKind::Text => {

        }

    }

}

/// Parse a `.constant` directive.

    let name = try parseSymbolName(a);

    let value = try expectI32Value(a, try parseExpr(a), "constant out of range");

    dict::insert(&mut a.constMap, name, value);

}

/// Parse a `.export` directive.

    let name = try parseLabelName(a);

    dict::insert(&mut a.exportMap, name, 1);

    if let idx = dict::get(&a.symbolMap, name) {

        set a.symbols[idx as u32].isExported = true;

    }

}

/// Parse a `.space` directive.

    let count = try parseValue(a);

    if count < 0 {

        throw fail(a, "space size must be non-negative");

    }

    // The data section grows on demand; only reject sizes that cannot be

        try emit::emitByte(a, 0);

    }

}

/// Parse an `.align` directive for the current section.

    let amount64 = try parseValue(a);

    if amount64 <= 0 {

        throw fail(a, "alignment must be positive");

    }

    if amount64 > super::U32_MAX_VALUE {

        }

    }

}

/// Parse a `.byte` directive.

    loop {

        if a.scan.current.kind == scanner::TokenKind::Char {

            let ch = parseCharLiteral(a.scan.current) else {

                throw fail(a, "invalid char literal");

            };

        }

    }

}

/// Parse a fixed-width integer data directive.

    loop {

        if isLabel(a.scan.current.kind) {

            let target = try parseLabelName(a);

            try emit::recordDataFixup(a, target, width);

        } else if a.scan.current.kind == scanner::TokenKind::Char {

        }

    }

}

/// Parse a `.ascii` string literal list.

    loop {

        let literal = try expectToken(a, scanner::TokenKind::String, "expected string literal");

        try emit::emitDecodedString(a, literal.source);

        if not consume(a, scanner::TokenKind::Comma) {

            return;

        }

    }

}

/// Parse and resolve a register operand.

    let tok = try expectToken(a, scanner::TokenKind::Register, "expected register");

    let reg = lookupRegister(&tok.source[1..]) else {

        throw super::Error::Invalid { offset: tok.offset, message: "unknown register" };

    };

    return reg;

}