//! Assembler parser pass.

use std::mem;

use std::fmt;

use std::lang::alloc;

use std::lang::strings;

use std::lang::parser;

use std::lang::gen;

use std::collections::dict;

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

use std::arch::rv64;

use super::emit;

use super::scanner;

/// Parsed memory operand with base register and signed byte offset.

record MemOperand: Copy {

    /// Base register inside the memory operand parentheses.

    base: gen::Reg,

    /// Signed byte offset preceding the base register.

    offset: i32,

}

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

export fn parseProgram(a: *mut super::Assembler) throws (super::Error) {

    advance(a);

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

        try parseItem(a);

    }

}

/// Align `value` upward to `alignment`, returning nil on u32 overflow.

fn checkedAlignUp(value: u32, alignment: u32) -> ?u32 {

    let padding = alignment - 1;

    if value > parser::U32_MAX - padding {

        return nil;

    }

    return mem::alignUp(value, alignment);

}

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

fn advance(a: *mut super::Assembler) {

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

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

}

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

fn consume(a: *mut super::Assembler, kind: scanner::TokenKind) -> bool {

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

        advance(a);

        return true;

    }

    return false;

}

/// Create an error at the current token.

fn fail(a: *super::Assembler, message: *[u8]) -> super::Error {

    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.

fn expectDataSection(a: *super::Assembler, tok: scanner::Token) throws (super::Error) {

    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.

fn expect(a: *mut super::Assembler, kind: scanner::TokenKind, message: *[u8]) throws (super::Error) {

    if not consume(a, kind) {

        throw fail(a, message);

    }

}

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

fn expectToken(a: *mut super::Assembler, kind: scanner::TokenKind, message: *[u8]) -> scanner::Token throws (super::Error) {

    try expect(a, kind, message);

    return a.scan.previous;

}

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

fn expectTerminator(a: *super::Assembler, message: *[u8]) throws (super::Error) {

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

        throw fail(a, message);

    }

}

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

fn expectI32Value(a: *super::Assembler, value: i64, message: *[u8]) -> i32 throws (super::Error) {

    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.

fn expectSmallImmValue(a: *super::Assembler, value: i64) -> i32 throws (super::Error) {

    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.

fn defineSymbol(a: *mut super::Assembler, name: *[u8], tok: scanner::Token) throws (super::Error) {

    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.

fn emitDataValue(a: *mut super::Assembler, value: i64, width: super::DataWidth) throws (super::Error) {

    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.

fn parseScopedName(

    a: *mut super::Assembler,

    kind: scanner::TokenKind,

    message: *[u8],

    trimPrefix: u32

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

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

    let start = first.offset + trimPrefix;

    let mut end = first.offset + first.source.len;

    while consume(a, scanner::TokenKind::ColonColon) {

        let segment = try expectToken(a, scanner::TokenKind::Ident, "expected identifier after `::`");

        set end = segment.offset + segment.source.len;

    }

    return strings::intern(a.scan.pool, &a.scan.source[start..end]);

}

/// Parse a bare symbol name.

fn parseSymbolName(a: *mut super::Assembler) -> *[u8] throws (super::Error) {

    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.

fn parseQuotedLabelName(a: *mut super::Assembler) -> *[u8] throws (super::Error) {

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

    } as *mut [u8];

    let len = fmt::unescapeString(raw, storage);

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

}

/// Parse a label reference or definition name.

fn parseLabelName(a: *mut super::Assembler) -> *[u8] throws (super::Error) {

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

fn parseDirectiveName(a: *mut super::Assembler) -> *[u8] throws (super::Error) {

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

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

}

/// Parse one top-level assembler item.

fn parseItem(a: *mut super::Assembler) throws (super::Error) {

    match a.scan.current.kind {

        case scanner::TokenKind::Ident => {

            let tok = a.scan.current;

            let name = try parseSymbolName(a);

            try parseInstruction(a, name, tok);

            try expect(a, scanner::TokenKind::Semicolon, "expected `;` after instruction");

        }

        case scanner::TokenKind::Number => {

            let tok = a.scan.current;

            advance(a);

            throw failOnToken(tok, "unexpected number at top level");

        }

        case scanner::TokenKind::Label, scanner::TokenKind::QuotedLabel => {

            let tok = a.scan.current;

            let name = try parseLabelName(a);

            try defineSymbol(a, name, tok);

        }

        case scanner::TokenKind::Directive => {

            let tok = a.scan.current;

            let name = try parseDirectiveName(a);

            try parseDirective(a, name, tok);

            try expect(a, scanner::TokenKind::Semicolon, "expected `;` after directive");

        }

        else => throw fail(a, "expected label, instruction, or directive"),

    }

}

/// Find `name` in a sorted descriptor table.

fn findSortedNameIndex(name: *[u8], len: u32, getName: fn(u32) -> *[u8]) -> ?u32 {

    let mut left: u32 = 0;

    let mut right: u32 = len;

    while left < right {

        let mid = left + ((right - left) / 2);

        let cmp = mem::cmp(name, getName(mid));

        match cmp {

            case -1 => set right = mid,

            case  1 => set left = mid + 1,

            else => return mid,

        }

    }

    return nil;

}

/// Adapter used by [`findSortedNameIndex`] to read an instruction mnemonic.

fn instructionNameAt(index: u32) -> *[u8] {

    return super::INSTRUCTIONS[index].name;

}

/// Adapter used by [`findSortedNameIndex`] to read a directive name.

fn directiveNameAt(index: u32) -> *[u8] {

    return super::DIRECTIVES[index].name;

}

/// Adapter used by [`findSortedNameIndex`] to read a register name.

fn registerNameAt(index: u32) -> *[u8] {

    return super::REGISTERS[index].name;

}

/// Adapter used by [`findSortedNameIndex`] to read a CSR name.

fn csrNameAt(index: u32) -> *[u8] {

    return super::CSRS[index].name;

}

/// Look up the operand parser and encoder for an instruction mnemonic.

fn lookupInstruction(name: *[u8]) -> ?super::InstructionEncoder {

    let index = findSortedNameIndex(name, super::INSTRUCTIONS.len, instructionNameAt) else {

        return nil;

    };

    return super::INSTRUCTIONS[index].encoder;

}

/// Classify a directive name.

fn classifyDirective(name: *[u8]) -> ?super::DirectiveKind {

    let index = findSortedNameIndex(name, super::DIRECTIVES.len, directiveNameAt) else {

        return nil;

    };

    return super::DIRECTIVES[index].kind;

}

/// Look up a percent-prefixed register name after the `%` has been removed.

fn lookupRegister(name: *[u8]) -> ?gen::Reg {

    let index = findSortedNameIndex(name, super::REGISTERS.len, registerNameAt) else {

        return nil;

    };

    return super::REGISTERS[index].reg;

}

/// Look up a CSR name.

fn lookupCsr(name: *[u8]) -> ?u32 {

    let index = findSortedNameIndex(name, super::CSRS.len, csrNameAt) else {

        return nil;

    };

    return super::CSRS[index].csr;

}

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

fn parseInstruction(a: *mut super::Assembler, name: *[u8], tok: scanner::Token) throws (super::Error) {

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

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

    }

    let form = lookupInstruction(name) else {

        throw failOnToken(tok, "unknown instruction");

    };

    match form {

        case super::InstructionEncoder::NoOperand { enc } => {

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

                throw fail(a, "unexpected operand");

            }

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

            return;

        }

        case super::InstructionEncoder::Fence => return try parseFence(a, tok),

        case super::InstructionEncoder::Li => return try parseLi(a),

        case super::InstructionEncoder::La => return try parseLa(a),

        case super::InstructionEncoder::RR { enc } => return try parseRR(a, enc),

        case super::InstructionEncoder::RRR { enc } => return try parseRRR(a, enc),

        case super::InstructionEncoder::RRI { enc } => return try parseRRI(a, enc),

        case super::InstructionEncoder::Shift { enc } =>

            return try parseShift(a, enc, super::SHIFT_LIMIT, "shift amount out of range"),

        case super::InstructionEncoder::WordShift { enc } =>

            return try parseShift(a, enc, super::WORD_SHIFT_LIMIT, "word shift amount out of range"),

        case super::InstructionEncoder::Load { enc } => return try parseLoad(a, enc),

        case super::InstructionEncoder::Store { enc } => return try parseStore(a, enc),

        case super::InstructionEncoder::Atomic { funct5 } => return try parseAtomic(a, tok, funct5),

        case super::InstructionEncoder::Branch { op } => return try parseBranch(a, op),

        case super::InstructionEncoder::BranchZero { op } => return try parseBranchZero(a, op),

        case super::InstructionEncoder::Jal => return try parseJal(a),

        case super::InstructionEncoder::Jump { rd } => return try parseJ(a, rd),

        case super::InstructionEncoder::RdCsr { enc } => return try parseRdCsr(a, enc),

        case super::InstructionEncoder::CsrRs1 { enc } => return try parseCsrRs1(a, enc),

        case super::InstructionEncoder::Csrrw => return try parseCsrrw(a),

        case super::InstructionEncoder::Csrsi => return try parseCsrsi(a),

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

    }

}

/// Parse a full memory/I/O fence or the adjacent `.i` instruction-cache suffix.

fn parseFence(a: *mut super::Assembler, mnemonic: scanner::Token) throws (super::Error) {

    let mut instruction = encode::fence();

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

        if a.scan.current.offset <> mnemonic.offset + mnemonic.source.len

            or not mem::eq(a.scan.current.source, ".i") {

            throw fail(a, "expected adjacent .i fence suffix");

        }

        advance(a);

        set instruction = encode::fenceI();

    }

    try expectTerminator(a, "unexpected fence operand");

    try emit::emitText(a, instruction);

}

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

fn parseLi(a: *mut super::Assembler) throws (super::Error) {

    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;

    }

    let imm = try expectI32Value(a, value, "li immediate out of range");

    let split = rv64::emit::splitImm(imm);

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

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

}

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

fn parseLa(a: *mut super::Assembler) throws (super::Error) {

    let rd = try parseRegister(a);

    let target = try parseLabelName(a);

    let index = a.text.len;

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

}

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

fn parseRdCsr(a: *mut super::Assembler, enc: fn(gen::Reg, u32) -> u32) throws (super::Error) {

    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.

fn parseCsrRs1(a: *mut super::Assembler, enc: fn(u32, gen::Reg) -> u32) throws (super::Error) {

    let csr = try parseCsr(a);

    let rs1 = try parseRegister(a);

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

}

/// Parse `csrrw`.

fn parseCsrrw(a: *mut super::Assembler) throws (super::Error) {

    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.

fn parseCsrsi(a: *mut super::Assembler) throws (super::Error) {

    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.

fn parseRR(a: *mut super::Assembler, enc: fn(gen::Reg, gen::Reg) -> u32) throws (super::Error) {

    let rd = try parseRegister(a);

    let rs = try parseRegister(a);

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

}

/// Parse a three-register instruction.

fn parseRRR(a: *mut super::Assembler, enc: fn(gen::Reg, gen::Reg, gen::Reg) -> u32) throws (super::Error) {

    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.

fn parseRRI(a: *mut super::Assembler, enc: fn(gen::Reg, gen::Reg, i32) -> u32) throws (super::Error) {

    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.

fn parseShift(

    a: *mut super::Assembler,

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

    limit: i32,

    message: *[u8]

) throws (super::Error) {

    let rd = try parseRegister(a);

    let rs1 = try parseRegister(a);

    let shamt64 = try parseValue(a);

    if shamt64 < 0 {

        throw fail(a, "shift amount must be non-negative");

    }

    if shamt64 >= limit as i64 {

        throw fail(a, message);

    }

    let shamt = shamt64 as i32;

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

}

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

fn parseLoad(a: *mut super::Assembler, enc: fn(gen::Reg, gen::Reg, i32) -> u32) throws (super::Error) {

    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.

fn parseStore(a: *mut super::Assembler, enc: fn(gen::Reg, gen::Reg, i32) -> u32) throws (super::Error) {

    let rs2 = try parseRegister(a);

    let memop = try parseMemory(a);

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

}

/// Parse the adjacent width/order suffixes and zero-offset RV64A operands.

fn parseAtomic(a: *mut super::Assembler, tok: scanner::Token, funct5: u32) throws (super::Error) {

    let widthToken = try expectToken(a, scanner::TokenKind::Directive, "expected atomic width suffix");

    if widthToken.offset <> tok.offset + tok.source.len {

        throw failOnToken(widthToken, "atomic width must adjoin mnemonic");

    }

    let mut width: u32 = encode::F3_WORD;

    if mem::eq(widthToken.source, ".d") {

        set width = encode::F3_DWORD;

    } else if not mem::eq(widthToken.source, ".w") {

        throw failOnToken(widthToken, "expected `.w` or `.d` atomic width");

    }

    let mut ordering: u32 = 0;

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

        let orderToken = a.scan.current;

        if orderToken.offset <> widthToken.offset + widthToken.source.len {

            throw failOnToken(orderToken, "atomic ordering must adjoin width");

        }

        if mem::eq(orderToken.source, ".aq") {

            set ordering = 2;

        } else if mem::eq(orderToken.source, ".rl") {

            set ordering = 1;

        } else if mem::eq(orderToken.source, ".aqrl") {

            set ordering = 3;

        } else {

            throw failOnToken(orderToken, "expected `.aq`, `.rl`, or `.aqrl` atomic ordering");

        }

        advance(a);

    }

    let rd = try parseRegister(a);

    // LR reserves rs2 = x0 and has no source register operand.

    let mut rs2 = rv64::ZERO;

    if funct5 <> encode::F5_LR {

        set rs2 = try parseRegister(a);

    }

    let memop = try parseMemory(a);

    if memop.offset <> 0 {

        throw fail(a, "atomic memory offset must be zero");

    }

    try expectTerminator(a, "unexpected atomic operand");

    try emit::emitText(a, encode::atomic(rd, memop.base, rs2, funct5, width, ordering));

}

/// Parse a two-register branch instruction.

fn parseBranch(a: *mut super::Assembler, op: super::BranchOp) throws (super::Error) {

    let rs1 = try parseRegister(a);

    let rs2 = try parseRegister(a);

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

}

/// Parse an optional label operand.

fn parseOptionalLabel(a: *mut super::Assembler) -> ?*[u8] throws (super::Error) {

    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.

fn parseBranchLabel(a: *mut super::Assembler, op: super::BranchOp, rs1: gen::Reg, rs2: gen::Reg) throws (super::Error) {

    let index = a.text.len;

    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.

fn parseBranchZero(a: *mut super::Assembler, op: super::BranchOp) throws (super::Error) {

    let rs = try parseRegister(a);

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

}

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

fn parseJal(a: *mut super::Assembler) throws (super::Error) {

    let rd = try parseRegister(a);

    try parseJ(a, rd);

}

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

fn parseJ(a: *mut super::Assembler, rd: gen::Reg) throws (super::Error) {

    let index = a.text.len;

    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.

fn parseUpper(a: *mut super::Assembler, enc: fn(gen::Reg, i32) -> u32) throws (super::Error) {

    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.

fn parseDirective(a: *mut super::Assembler, name: *[u8], tok: scanner::Token) throws (super::Error) {

    let directive = classifyDirective(name) else {

        throw failOnToken(tok, "unknown directive");

    };

    match directive {

        case super::DirectiveKind::Text => {

            try expectTerminator(a, "unexpected operand");

            set a.section = super::Section::Text;

            return;

        }

        case super::DirectiveKind::Data => {

            try expectTerminator(a, "unexpected operand");

            set a.section = super::Section::Data;

            return;

        }

        case super::DirectiveKind::Align =>

            return try parseAlignDirective(a),

        case super::DirectiveKind::Ascii => {

            try expectDataSection(a, tok);

            return try parseStringDirective(a);

        }

        case super::DirectiveKind::Byte => {

            try expectDataSection(a, tok);

            return try parseByteDirective(a);

        }

        case super::DirectiveKind::Constant =>

            return try parseConstantDirective(a),

        case super::DirectiveKind::Dword => {

            try expectDataSection(a, tok);

            return try parseIntDirective(a, super::DataWidth::Dword);

        }

        case super::DirectiveKind::Export =>

            return try parseExportDirective(a),

        case super::DirectiveKind::Space => {

            try expectDataSection(a, tok);

            return try parseSpaceDirective(a);

        }

        case super::DirectiveKind::Word => {

            try expectDataSection(a, tok);

            return try parseIntDirective(a, super::DataWidth::Word);

        }

    }

}

/// Parse a `.constant` directive.

fn parseConstantDirective(a: *mut super::Assembler) throws (super::Error) {

    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.

fn parseExportDirective(a: *mut super::Assembler) throws (super::Error) {

    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.

fn parseSpaceDirective(a: *mut super::Assembler) throws (super::Error) {

    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

    // represented as a section offset.

    if count > super::U32_MAX_VALUE - a.data.len as i64 {

        throw super::Error::DataOverflow;

    }

    for _ in 0..count as u32 {

        try emit::emitByte(a, 0);

    }

}

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

fn parseAlignDirective(a: *mut super::Assembler) throws (super::Error) {

    let amount64 = try parseValue(a);

    if amount64 <= 0 {

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

    }

    if amount64 > super::U32_MAX_VALUE {

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

    }

    let amount = amount64 as u32;

    if (amount & (amount - 1)) <> 0 {

        throw fail(a, "alignment must be a power of two");

    }

    match a.section {

        case super::Section::Text => {

            if amount % rv64::INSTR_SIZE as u32 <> 0 {

                throw fail(a, "text alignment must be a multiple of 4");

            }

            let bytes = a.text.len * rv64::INSTR_SIZE as u32;

            let aligned = checkedAlignUp(bytes, amount) else {

                throw super::Error::TextOverflow;

            };

            let words = (aligned - bytes) / rv64::INSTR_SIZE as u32;

            try emit::emitTextPadding(a, words);

        }

        case super::Section::Data => {

            let aligned = checkedAlignUp(a.data.len, amount) else {

                throw super::Error::DataOverflow;

            };

            for _ in a.data.len..aligned {

                try emit::emitByte(a, 0);

            }

        }

    }

}

/// Parse a `.byte` directive.

fn parseByteDirective(a: *mut super::Assembler) throws (super::Error) {

    loop {

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

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

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

            };

            try emit::emitByte(a, ch);

            advance(a);

        } else {

            let value = try parseValue(a);

            if value < 0 or value > super::U8_MAX_VALUE {

                throw fail(a, "byte literal out of range");

            }

            try emit::emitByte(a, value as u8);

        }

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

            return;

        }

    }

}

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

fn parseIntDirective(a: *mut super::Assembler, width: super::DataWidth) throws (super::Error) {

    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 {

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

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

            };

            advance(a);

            try emitDataValue(a, ch as i64, width);

        } else {

            try emitDataValue(a, try parseValue(a), width);

        }

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

            return;

        }

    }

}

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

fn parseStringDirective(a: *mut super::Assembler) throws (super::Error) {

    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.

fn parseRegister(a: *mut super::Assembler) -> gen::Reg throws (super::Error) {

    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;

}

/// Parse a simple signed immediate or constant value.

fn parseValue(a: *mut super::Assembler) -> i64 throws (super::Error) {

    if consume(a, scanner::TokenKind::Minus) {

        return -(try parseValuePrimary(a));

    }

    return try parseValuePrimary(a);

}

/// Parse the primary form used by simple immediate values.

fn parseValuePrimary(a: *mut super::Assembler) -> i64 throws (super::Error) {

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

        return try parseInteger(a);

    }

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

        return try parseConstantValue(a);

    }

    throw fail(a, "expected number or constant");

}

/// Parse an additive constant expression.

fn parseExpr(a: *mut super::Assembler) -> i64 throws (super::Error) {

    let mut value = try parseExprMul(a);

    while a.scan.current.kind == scanner::TokenKind::Plus or a.scan.current.kind == scanner::TokenKind::Minus {

        let op = a.scan.current.kind;

        advance(a);

        let rhs = try parseExprMul(a);

        if op == scanner::TokenKind::Plus {

            set value += rhs;

        } else {

            set value -= rhs;

        }

    }

    return value;

}

/// Parse multiplicative expression operators.

fn parseExprMul(a: *mut super::Assembler) -> i64 throws (super::Error) {

    let mut value = try parseExprUnary(a);

    while a.scan.current.kind == scanner::TokenKind::Star or a.scan.current.kind == scanner::TokenKind::Slash {

        let op = a.scan.current.kind;

        advance(a);

        let rhs = try parseExprUnary(a);

        if op == scanner::TokenKind::Star {

            set value *= rhs;

        } else {

            if rhs == 0 {

                throw fail(a, "division by zero");

            }

            set value /= rhs;

        }

    }

    return value;

}

/// Parse unary expression operators.

fn parseExprUnary(a: *mut super::Assembler) -> i64 throws (super::Error) {

    if consume(a, scanner::TokenKind::Minus) {

        return -(try parseExprUnary(a));

    }

    if consume(a, scanner::TokenKind::Plus) {

        return try parseExprUnary(a);

    }

    return try parseExprPrimary(a);

}

/// Parse expression atoms.

fn parseExprPrimary(a: *mut super::Assembler) -> i64 throws (super::Error) {

    if consume(a, scanner::TokenKind::LParen) {

        let value = try parseExpr(a);

        try expect(a, scanner::TokenKind::RParen, "expected `)`");

        return value;

    }

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

        return try parseInteger(a);

    }

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

        return try parseConstantValue(a);

    }

    throw fail(a, "expected expression");

}

/// Parse and resolve a named assembler constant.

fn parseConstantValue(a: *mut super::Assembler) -> i64 throws (super::Error) {

    let name = try parseSymbolName(a);

    let value = dict::get(&a.constMap, name) else {

        throw super::Error::Invalid { offset: a.scan.previous.offset, message: "undefined constant" };

    };

    return value as i64;

}

/// Parse and resolve a CSR operand.

fn parseCsr(a: *mut super::Assembler) -> u32 throws (super::Error) {

    let name = try parseSymbolName(a);

    let csr = lookupCsr(name) else {

        throw super::Error::Invalid { offset: a.scan.previous.offset, message: "unknown CSR" };

    };

    return csr;

}

/// Parse an offset(base) memory operand.

fn parseMemory(a: *mut super::Assembler) -> MemOperand throws (super::Error) {

    let mut offset: i32 = 0;

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

        set offset = try expectSmallImmValue(a, try parseValue(a));

    }

    try expect(a, scanner::TokenKind::LParen, "expected `(`");

    let base = try parseRegister(a);

    try expect(a, scanner::TokenKind::RParen, "expected `)`");

    return MemOperand { base, offset };

}

/// Parse an immediate value that fits in a signed 12-bit field.

fn parseSmallImm(a: *mut super::Assembler) -> i32 throws (super::Error) {

    return try expectSmallImmValue(a, try parseValue(a));

}