radiance · Radiance self-hosting compiler

compiler/ lib/ examples/ std/ arch/ rv64/ asm/ image/ shared/ asm.rad 24.8 KiB atomicTests.rad 5.0 KiB atomics.rad 3.6 KiB bounds.rad 33.4 KiB decode.rad 15.2 KiB emit.rad 33.2 KiB encode.rad 22.0 KiB image.rad 4.5 KiB isel.rad 52.6 KiB printer.rad 13.9 KiB shared.rad 16.8 KiB tests.rad 17.2 KiB rv64.rad 17.5 KiB char/ collections/ graph/ lang/ sys/ arch.rad 68 B char.rad 855 B collections.rad 39 B fmt.rad 8.3 KiB graph.rad 4.3 KiB intrinsics.rad 467 B io.rad 1.7 KiB lang.rad 276 B mem.rad 2.3 KiB sys.rad 179 B testing.rad 2.4 KiB tests.rad 15.7 KiB vec.rad 3.2 KiB std.rad 299 B scripts/ seed/ sublime/ test/ vim/ .gitignore 336 B .gitsigners 112 B CELL_PERMISSIONS 6.8 KiB CONTRIBUTING 2.1 KiB LICENSE 1.1 KiB Makefile 5.4 KiB README 2.5 KiB STYLE 2.5 KiB std.lib 1.5 KiB std.lib.test 808 B
lib/std/arch/rv64/encode.rad 22.0 KiB raw
//! RISC-V RV64I+M instruction encoding.
//!
//! Provides type-safe functions for encoding RV64 instructions.

use std::lang::gen;

//////////////////////
// Opcode Constants //
//////////////////////

export constant OP_LOAD:   u32 = 0x03;
export constant OP_STORE:  u32 = 0x23;
export constant OP_BRANCH: u32 = 0x63;
export constant OP_JALR:   u32 = 0x67;
export constant OP_JAL:    u32 = 0x6F;
export constant OP_OP:     u32 = 0x33;
export constant OP_IMM:    u32 = 0x13;
export constant OP_AUIPC:  u32 = 0x17;
export constant OP_LUI:    u32 = 0x37;
export constant OP_SYSTEM: u32 = 0x73;
export constant OP_OP32:   u32 = 0x3B;  // RV64: 32-bit operations
export constant OP_IMM32:  u32 = 0x1B;  // RV64: 32-bit immediate operations

//////////////////////
// Funct3 Constants //
//////////////////////

// Memory operations

export constant F3_BYTE:   u32 = 0x0;  // LB/SB
export constant F3_HALF:   u32 = 0x1;  // LH/SH
export constant F3_WORD:   u32 = 0x2;  // LW/SW
export constant F3_DWORD:  u32 = 0x3;  // LD/SD (RV64)
export constant F3_BYTE_U: u32 = 0x4;  // LBU
export constant F3_HALF_U: u32 = 0x5;  // LHU
export constant F3_WORD_U: u32 = 0x6;  // LWU (RV64)

// ALU operations

export constant F3_ADD:  u32 = 0x0;  // ADD/SUB/ADDI
export constant F3_SLL:  u32 = 0x1;  // SLL/SLLI
export constant F3_SLT:  u32 = 0x2;  // SLT/SLTI
export constant F3_SLTU: u32 = 0x3;  // SLTU/SLTIU
export constant F3_XOR:  u32 = 0x4;  // XOR/XORI
export constant F3_SRL:  u32 = 0x5;  // SRL/SRA/SRLI/SRAI
export constant F3_OR:   u32 = 0x6;  // OR/ORI
export constant F3_AND:  u32 = 0x7;  // AND/ANDI

// Branch operations

export constant F3_BEQ:  u32 = 0x0;
export constant F3_BNE:  u32 = 0x1;
export constant F3_BLT:  u32 = 0x4;
export constant F3_BGE:  u32 = 0x5;
export constant F3_BLTU: u32 = 0x6;
export constant F3_BGEU: u32 = 0x7;

// CSR/system operations

export constant F3_CSRRW: u32 = 0x1;
export constant F3_CSRRS: u32 = 0x2;
export constant F3_CSRRC: u32 = 0x3;
export constant F3_CSRRWI: u32 = 0x5;
export constant F3_CSRRSI: u32 = 0x6;
export constant F3_CSRRCI: u32 = 0x7;

//////////////////////
// Funct7 Constants //
//////////////////////

export constant F7_NORMAL: u32 = 0b0000000;
export constant F7_SUB:    u32 = 0b0100000;  // Bit 5 set
export constant F7_SRA:    u32 = 0b0100000;  // Bit 5 set
export constant F7_MUL:    u32 = 0b0000001;  // Bit 0 set

/////////////////////////
// Validation Helpers  //
/////////////////////////

/// Returns `true` if the value fits in a signed 12-bit immediate.
export fn isSmallImm(value: i32) -> bool {
    return value >= super::MIN_IMM and value <= super::MAX_IMM;
}

/// Returns `true` if a 64-bit value fits in a 12-bit signed immediate.
export fn isSmallImm64(value: i64) -> bool {
    return value >= (super::MIN_IMM as i64) and value <= (super::MAX_IMM as i64);
}

/// Returns `true` if the value is valid for branch immediates.
/// Branch immediates are 13-bit signed, even aligned.
export fn isBranchImm(value: i32) -> bool {
    return value >= -(1 << 12) and value <= ((1 << 12) - 2) and (value & 1) == 0;
}

/// Returns `true` if the value is valid for jump immediates (JAL).
/// Jump immediates are 21-bit signed, even aligned.
export fn isJumpImm(value: i32) -> bool {
    return value >= -(1 << 20) and value <= ((1 << 20) - 2) and (value & 1) == 0;
}

//////////////////////
// Format Encoders  //
//////////////////////

/// Encode an R-type instruction.
fn encodeR(opcode: u32, rd: gen::Reg, rs1: gen::Reg, rs2: gen::Reg, funct3: u32, funct7: u32) -> u32 {
    return (opcode        & 0x7F)
         | ((*rd  as u32  & 0x1F) << 7)
         | ((funct3       & 0x07) << 12)
         | ((*rs1 as u32  & 0x1F) << 15)
         | ((*rs2 as u32  & 0x1F) << 20)
         | ((funct7       & 0x7F) << 25);
}

/// Encode an I-type instruction.
fn encodeI(opcode: u32, rd: gen::Reg, rs1: gen::Reg, funct3: u32, imm: i32) -> u32 {
    assert isSmallImm(imm);

    return (opcode        & 0x7F)
         | ((*rd  as u32  & 0x1F)  << 7)
         | ((funct3       & 0x07)  << 12)
         | ((*rs1 as u32  & 0x1F)  << 15)
         | ((imm as u32   & 0xFFF) << 20);
}

/// Encode an S-type instruction.
fn encodeS(opcode: u32, rs1: gen::Reg, rs2: gen::Reg, funct3: u32, imm: i32) -> u32 {
    assert isSmallImm(imm);

    return (opcode  & 0x7F)
         | ((imm as u32       & 0x1F) << 7)
         | ((funct3           & 0x07) << 12)
         | ((*rs1 as u32      & 0x1F) << 15)
         | ((*rs2 as u32      & 0x1F) << 20)
         | ((imm as u32 >> 5  & 0x7F) << 25);
}

/// Encode a B-type (branch) instruction.
fn encodeB(opcode: u32, rs1: gen::Reg, rs2: gen::Reg, funct3: u32, imm: i32) -> u32 {
    assert isBranchImm(imm);

    let imm11   = (imm as u32 >> 11) & 0x1;
    let imm4_1  = (imm as u32 >> 1)  & 0xF;
    let imm10_5 = (imm as u32 >> 5)  & 0x3F;
    let imm12   = (imm as u32 >> 12) & 0x1;

    return (opcode        &  0x7F)
         | (imm11         << 7)
         | (imm4_1        << 8)
         | ((funct3       & 0x07) << 12)
         | ((*rs1 as u32  & 0x1F) << 15)
         | ((*rs2 as u32  & 0x1F) << 20)
         | (imm10_5       << 25)
         | (imm12         << 31);
}

/// Encode a U-type instruction.
fn encodeU(opcode: u32, rd: gen::Reg, imm: i32) -> u32 {
    return (opcode       & 0x7F)
         | ((*rd as u32  & 0x1F)    << 7)
         | ((imm as u32  & 0xFFFFF) << 12);
}

/// Encode a J-type (jump) instruction.
fn encodeJ(opcode: u32, rd: gen::Reg, imm: i32) -> u32 {
    assert isJumpImm(imm);

    let imm20    = (imm as u32 >> 20) & 0x1;
    let imm10_1  = (imm as u32 >> 1)  & 0x3FF;
    let imm11    = (imm as u32 >> 11) & 0x1;
    let imm19_12 = (imm as u32 >> 12) & 0xFF;

    return (opcode       & 0x7F)
         | ((*rd as u32  & 0x1F) << 7)
         | (imm19_12     << 12)
         | (imm11        << 20)
         | (imm10_1      << 21)
         | (imm20        << 31);
}

////////////////////////////
// ALU Immediate (I-type) //
////////////////////////////

/// Add immediate: `rd = rs1 + imm`.
export fn addi(rd: gen::Reg, rs1: gen::Reg, imm: i32) -> u32 {
    return encodeI(OP_IMM, rd, rs1, F3_ADD, imm);
}

/// Set less than immediate (signed): `rd = (rs1 < imm) ? 1 : 0`.
export fn slti(rd: gen::Reg, rs1: gen::Reg, imm: i32) -> u32 {
    return encodeI(OP_IMM, rd, rs1, F3_SLT, imm);
}

/// Set less than immediate unsigned: `rd = (rs1 < imm) ? 1 : 0`.
export fn sltiu(rd: gen::Reg, rs1: gen::Reg, imm: i32) -> u32 {
    return encodeI(OP_IMM, rd, rs1, F3_SLTU, imm);
}

/// XOR immediate: `rd = rs1 ^ imm`.
export fn xori(rd: gen::Reg, rs1: gen::Reg, imm: i32) -> u32 {
    return encodeI(OP_IMM, rd, rs1, F3_XOR, imm);
}

/// OR immediate: `rd = rs1 | imm`.
export fn ori(rd: gen::Reg, rs1: gen::Reg, imm: i32) -> u32 {
    return encodeI(OP_IMM, rd, rs1, F3_OR, imm);
}

/// AND immediate: `rd = rs1 & imm`.
export fn andi(rd: gen::Reg, rs1: gen::Reg, imm: i32) -> u32 {
    return encodeI(OP_IMM, rd, rs1, F3_AND, imm);
}

/// Shift left logical immediate: `rd = rs1 << shamt`.
export fn slli(rd: gen::Reg, rs1: gen::Reg, shamt: i32) -> u32 {
    assert shamt >= 0 and shamt < 64;
    return encodeI(OP_IMM, rd, rs1, F3_SLL, shamt & 0x3F);
}

/// Shift right logical immediate: `rd = rs1 >> shamt` (zero-extend).
export fn srli(rd: gen::Reg, rs1: gen::Reg, shamt: i32) -> u32 {
    assert shamt >= 0 and shamt < 64;
    return encodeI(OP_IMM, rd, rs1, F3_SRL, shamt & 0x3F);
}

/// Shift right arithmetic immediate: `rd = rs1 >> shamt` (sign-extend).
export fn srai(rd: gen::Reg, rs1: gen::Reg, shamt: i32) -> u32 {
    assert shamt >= 0 and shamt < 64;
    // SRAI has bit 10 set in immediate field (becomes bit 30 in instruction)
    return encodeI(OP_IMM, rd, rs1, F3_SRL, (shamt & 0x3F) | 0b10000000000);
}

///////////////////////////
// ALU Register (R-type) //
///////////////////////////

/// Add: `rd = rs1 + rs2`.
export fn add(rd: gen::Reg, rs1: gen::Reg, rs2: gen::Reg) -> u32 {
    return encodeR(OP_OP, rd, rs1, rs2, F3_ADD, F7_NORMAL);
}

/// Subtract: `rd = rs1 - rs2`.
export fn sub(rd: gen::Reg, rs1: gen::Reg, rs2: gen::Reg) -> u32 {
    return encodeR(OP_OP, rd, rs1, rs2, F3_ADD, F7_SUB);
}

/// Shift left logical: `rd = rs1 << rs2[5:0]`.
export fn sll(rd: gen::Reg, rs1: gen::Reg, rs2: gen::Reg) -> u32 {
    return encodeR(OP_OP, rd, rs1, rs2, F3_SLL, F7_NORMAL);
}

/// Set less than (signed): `rd = (rs1 < rs2) ? 1 : 0`.
export fn slt(rd: gen::Reg, rs1: gen::Reg, rs2: gen::Reg) -> u32 {
    return encodeR(OP_OP, rd, rs1, rs2, F3_SLT, F7_NORMAL);
}

/// Set less than unsigned: `rd = (rs1 < rs2) ? 1 : 0`.
export fn sltu(rd: gen::Reg, rs1: gen::Reg, rs2: gen::Reg) -> u32 {
    return encodeR(OP_OP, rd, rs1, rs2, F3_SLTU, F7_NORMAL);
}

/// XOR: `rd = rs1 ^ rs2`.
export fn xor(rd: gen::Reg, rs1: gen::Reg, rs2: gen::Reg) -> u32 {
    return encodeR(OP_OP, rd, rs1, rs2, F3_XOR, F7_NORMAL);
}

/// Shift right logical: `rd = rs1 >> rs2[5:0]` (zero-extend).
export fn srl(rd: gen::Reg, rs1: gen::Reg, rs2: gen::Reg) -> u32 {
    return encodeR(OP_OP, rd, rs1, rs2, F3_SRL, F7_NORMAL);
}

/// Shift right arithmetic: `rd = rs1 >> rs2[5:0]` (sign-extend).
export fn sra(rd: gen::Reg, rs1: gen::Reg, rs2: gen::Reg) -> u32 {
    return encodeR(OP_OP, rd, rs1, rs2, F3_SRL, F7_SRA);
}

/// OR: `rd = rs1 | rs2`.
export fn or_(rd: gen::Reg, rs1: gen::Reg, rs2: gen::Reg) -> u32 {
    return encodeR(OP_OP, rd, rs1, rs2, F3_OR, F7_NORMAL);
}

/// AND: `rd = rs1 & rs2`.
export fn and_(rd: gen::Reg, rs1: gen::Reg, rs2: gen::Reg) -> u32 {
    return encodeR(OP_OP, rd, rs1, rs2, F3_AND, F7_NORMAL);
}

/////////////////
// M Extension //
/////////////////

/// Multiply: `rd = (rs1 * rs2)[63:0]`.
export fn mul(rd: gen::Reg, rs1: gen::Reg, rs2: gen::Reg) -> u32 {
    return encodeR(OP_OP, rd, rs1, rs2, F3_ADD, F7_MUL);
}

/// Multiply high (signed x signed): `rd = (rs1 * rs2)[127:64]`.
export fn mulh(rd: gen::Reg, rs1: gen::Reg, rs2: gen::Reg) -> u32 {
    return encodeR(OP_OP, rd, rs1, rs2, F3_SLL, F7_MUL);
}

/// Multiply high (signed x unsigned): `rd = (rs1 * rs2)[127:64]`.
export fn mulhsu(rd: gen::Reg, rs1: gen::Reg, rs2: gen::Reg) -> u32 {
    return encodeR(OP_OP, rd, rs1, rs2, F3_SLT, F7_MUL);
}

/// Multiply high (unsigned x unsigned): `rd = (rs1 * rs2)[127:64]`.
export fn mulhu(rd: gen::Reg, rs1: gen::Reg, rs2: gen::Reg) -> u32 {
    return encodeR(OP_OP, rd, rs1, rs2, F3_SLTU, F7_MUL);
}

/// Divide (signed): `rd = rs1 / rs2`.
export fn div(rd: gen::Reg, rs1: gen::Reg, rs2: gen::Reg) -> u32 {
    return encodeR(OP_OP, rd, rs1, rs2, F3_XOR, F7_MUL);
}

/// Divide (unsigned): `rd = rs1 / rs2`.
export fn divu(rd: gen::Reg, rs1: gen::Reg, rs2: gen::Reg) -> u32 {
    return encodeR(OP_OP, rd, rs1, rs2, F3_SRL, F7_MUL);
}

/// Remainder (signed): `rd = rs1 % rs2`.
export fn rem(rd: gen::Reg, rs1: gen::Reg, rs2: gen::Reg) -> u32 {
    return encodeR(OP_OP, rd, rs1, rs2, F3_OR, F7_MUL);
}

/// Remainder (unsigned): `rd = rs1 % rs2`.
export fn remu(rd: gen::Reg, rs1: gen::Reg, rs2: gen::Reg) -> u32 {
    return encodeR(OP_OP, rd, rs1, rs2, F3_AND, F7_MUL);
}

//////////////////////////
// RV64 Word Operations //
//////////////////////////

/// Add immediate word (32-bit, sign-extended): `rd = sign_ext((rs1 + imm)[31:0])`.
export fn addiw(rd: gen::Reg, rs1: gen::Reg, imm: i32) -> u32 {
    return encodeI(OP_IMM32, rd, rs1, F3_ADD, imm);
}

/// Shift left logical immediate word: `rd = sign_ext((rs1 << shamt)[31:0])`.
export fn slliw(rd: gen::Reg, rs1: gen::Reg, shamt: i32) -> u32 {
    assert shamt >= 0 and shamt < 32;
    return encodeI(OP_IMM32, rd, rs1, F3_SLL, shamt & 0x1F);
}

/// Shift right logical immediate word: `rd = sign_ext((rs1[31:0] >> shamt))`.
export fn srliw(rd: gen::Reg, rs1: gen::Reg, shamt: i32) -> u32 {
    assert shamt >= 0 and shamt < 32;
    return encodeI(OP_IMM32, rd, rs1, F3_SRL, shamt & 0x1F);
}

/// Shift right arithmetic immediate word: `rd = sign_ext((rs1[31:0] >> shamt))` (sign-extended).
export fn sraiw(rd: gen::Reg, rs1: gen::Reg, shamt: i32) -> u32 {
    assert shamt >= 0 and shamt < 32;
    return encodeI(OP_IMM32, rd, rs1, F3_SRL, (shamt & 0x1F) | 0b10000000000);
}

/// Add word: `rd = sign_ext((rs1 + rs2)[31:0])`.
export fn addw(rd: gen::Reg, rs1: gen::Reg, rs2: gen::Reg) -> u32 {
    return encodeR(OP_OP32, rd, rs1, rs2, F3_ADD, F7_NORMAL);
}

/// Subtract word: `rd = sign_ext((rs1 - rs2)[31:0])`.
export fn subw(rd: gen::Reg, rs1: gen::Reg, rs2: gen::Reg) -> u32 {
    return encodeR(OP_OP32, rd, rs1, rs2, F3_ADD, F7_SUB);
}

/// Shift left logical word: `rd = sign_ext((rs1 << rs2[4:0])[31:0])`.
export fn sllw(rd: gen::Reg, rs1: gen::Reg, rs2: gen::Reg) -> u32 {
    return encodeR(OP_OP32, rd, rs1, rs2, F3_SLL, F7_NORMAL);
}

/// Shift right logical word: `rd = sign_ext((rs1[31:0] >> rs2[4:0]))`.
export fn srlw(rd: gen::Reg, rs1: gen::Reg, rs2: gen::Reg) -> u32 {
    return encodeR(OP_OP32, rd, rs1, rs2, F3_SRL, F7_NORMAL);
}

/// Shift right arithmetic word: `rd = sign_ext((rs1[31:0] >> rs2[4:0]))` (sign-extended).
export fn sraw(rd: gen::Reg, rs1: gen::Reg, rs2: gen::Reg) -> u32 {
    return encodeR(OP_OP32, rd, rs1, rs2, F3_SRL, F7_SRA);
}

/// Multiply word: `rd = sign_ext((rs1 * rs2)[31:0])`.
export fn mulw(rd: gen::Reg, rs1: gen::Reg, rs2: gen::Reg) -> u32 {
    return encodeR(OP_OP32, rd, rs1, rs2, F3_ADD, F7_MUL);
}

/// Divide word (signed): `rd = sign_ext(rs1[31:0] / rs2[31:0])`.
export fn divw(rd: gen::Reg, rs1: gen::Reg, rs2: gen::Reg) -> u32 {
    return encodeR(OP_OP32, rd, rs1, rs2, F3_XOR, F7_MUL);
}

/// Divide word (unsigned): `rd = sign_ext(rs1[31:0] / rs2[31:0])`.
export fn divuw(rd: gen::Reg, rs1: gen::Reg, rs2: gen::Reg) -> u32 {
    return encodeR(OP_OP32, rd, rs1, rs2, F3_SRL, F7_MUL);
}

/// Remainder word (signed): `rd = sign_ext(rs1[31:0] % rs2[31:0])`.
export fn remw(rd: gen::Reg, rs1: gen::Reg, rs2: gen::Reg) -> u32 {
    return encodeR(OP_OP32, rd, rs1, rs2, F3_OR, F7_MUL);
}

/// Remainder word (unsigned): `rd = sign_ext(rs1[31:0] % rs2[31:0])`.
export fn remuw(rd: gen::Reg, rs1: gen::Reg, rs2: gen::Reg) -> u32 {
    return encodeR(OP_OP32, rd, rs1, rs2, F3_AND, F7_MUL);
}

///////////////////
// Load (I-type) //
///////////////////

/// Load byte (sign-extend): `rd = mem[rs1 + imm][7:0]`.
export fn lb(rd: gen::Reg, rs1: gen::Reg, imm: i32) -> u32 {
    return encodeI(OP_LOAD, rd, rs1, F3_BYTE, imm);
}

/// Load halfword (sign-extend): `rd = mem[rs1 + imm][15:0]`.
export fn lh(rd: gen::Reg, rs1: gen::Reg, imm: i32) -> u32 {
    return encodeI(OP_LOAD, rd, rs1, F3_HALF, imm);
}

/// Load word (sign-extend to 64-bit): `rd = sign_ext(mem[rs1 + imm][31:0])`.
export fn lw(rd: gen::Reg, rs1: gen::Reg, imm: i32) -> u32 {
    return encodeI(OP_LOAD, rd, rs1, F3_WORD, imm);
}

/// Load byte unsigned (zero-extend): `rd = mem[rs1 + imm][7:0]`.
export fn lbu(rd: gen::Reg, rs1: gen::Reg, imm: i32) -> u32 {
    return encodeI(OP_LOAD, rd, rs1, F3_BYTE_U, imm);
}

/// Load halfword unsigned (zero-extend): `rd = mem[rs1 + imm][15:0]`.
export fn lhu(rd: gen::Reg, rs1: gen::Reg, imm: i32) -> u32 {
    return encodeI(OP_LOAD, rd, rs1, F3_HALF_U, imm);
}

/// Load word unsigned (zero-extend to 64-bit): `rd = mem[rs1 + imm][31:0]`.
export fn lwu(rd: gen::Reg, rs1: gen::Reg, imm: i32) -> u32 {
    return encodeI(OP_LOAD, rd, rs1, F3_WORD_U, imm);
}

/// Load doubleword: `rd = mem[rs1 + imm][63:0]`.
export fn ld(rd: gen::Reg, rs1: gen::Reg, imm: i32) -> u32 {
    return encodeI(OP_LOAD, rd, rs1, F3_DWORD, imm);
}

////////////////////
// Store (S-type) //
////////////////////

/// Store byte: `mem[rs1 + imm] = rs2[7:0]`.
export fn sb(rs2: gen::Reg, rs1: gen::Reg, imm: i32) -> u32 {
    return encodeS(OP_STORE, rs1, rs2, F3_BYTE, imm);
}

/// Store halfword: `mem[rs1 + imm] = rs2[15:0]`.
export fn sh(rs2: gen::Reg, rs1: gen::Reg, imm: i32) -> u32 {
    return encodeS(OP_STORE, rs1, rs2, F3_HALF, imm);
}

/// Store word: `mem[rs1 + imm] = rs2[31:0]`.
export fn sw(rs2: gen::Reg, rs1: gen::Reg, imm: i32) -> u32 {
    return encodeS(OP_STORE, rs1, rs2, F3_WORD, imm);
}

/// Store doubleword: `mem[rs1 + imm] = rs2[63:0]`.
export fn sd(rs2: gen::Reg, rs1: gen::Reg, imm: i32) -> u32 {
    return encodeS(OP_STORE, rs1, rs2, F3_DWORD, imm);
}

/////////////////////
// Branch (B-type) //
/////////////////////

/// Branch if equal: `if (rs1 == rs2) pc += imm`.
export fn beq(rs1: gen::Reg, rs2: gen::Reg, imm: i32) -> u32 {
    return encodeB(OP_BRANCH, rs1, rs2, F3_BEQ, imm);
}

/// Branch if not equal: `if (rs1 <> rs2) pc += imm`.
export fn bne(rs1: gen::Reg, rs2: gen::Reg, imm: i32) -> u32 {
    return encodeB(OP_BRANCH, rs1, rs2, F3_BNE, imm);
}

/// Branch if less than (signed): `if (rs1 < rs2) pc += imm`.
export fn blt(rs1: gen::Reg, rs2: gen::Reg, imm: i32) -> u32 {
    return encodeB(OP_BRANCH, rs1, rs2, F3_BLT, imm);
}

/// Branch if greater or equal (signed): `if (rs1 >= rs2) pc += imm`.
export fn bge(rs1: gen::Reg, rs2: gen::Reg, imm: i32) -> u32 {
    return encodeB(OP_BRANCH, rs1, rs2, F3_BGE, imm);
}

/// Branch if less than unsigned: `if (rs1 < rs2) pc += imm`.
export fn bltu(rs1: gen::Reg, rs2: gen::Reg, imm: i32) -> u32 {
    return encodeB(OP_BRANCH, rs1, rs2, F3_BLTU, imm);
}

/// Branch if greater or equal unsigned: `if (rs1 >= rs2) pc += imm`.
export fn bgeu(rs1: gen::Reg, rs2: gen::Reg, imm: i32) -> u32 {
    return encodeB(OP_BRANCH, rs1, rs2, F3_BGEU, imm);
}

//////////
// Jump //
//////////

/// Jump and link: `rd = pc + 4; pc += imm`.
export fn jal(rd: gen::Reg, imm: i32) -> u32 {
    return encodeJ(OP_JAL, rd, imm);
}

/// Jump and link register: `rd = pc + 4; pc = rs1 + imm`.
export fn jalr(rd: gen::Reg, rs1: gen::Reg, imm: i32) -> u32 {
    return encodeI(OP_JALR, rd, rs1, 0, imm);
}

/////////////////////
// Upper Immediate //
/////////////////////

/// Load upper immediate: `rd = imm << 12`.
export fn lui(rd: gen::Reg, imm: i32) -> u32 {
    return encodeU(OP_LUI, rd, imm);
}

/// Add upper immediate to PC: `rd = pc + (imm << 12)`.
export fn auipc(rd: gen::Reg, imm: i32) -> u32 {
    return encodeU(OP_AUIPC, rd, imm);
}

////////////
// System //
////////////

/// Environment call (system call).
export fn ecall() -> u32 {
    return encodeI(OP_SYSTEM, super::ZERO, super::ZERO, 0, 0);
}

/// Environment break (debugger breakpoint).
export fn ebreak() -> u32 {
    return encodeI(OP_SYSTEM, super::ZERO, super::ZERO, 0, 1);
}

/// Full predecessor/successor memory fence (`fence rw, rw`).
export fn fence() -> u32 {
    return fenceOrder(3, 3);
}

/// Encode a CSR instruction with a register source.
fn encodeCsr(op: u32, rd: gen::Reg, csr: u32, funct3: u32, rs1: gen::Reg) -> u32 {
    return (op             & 0x7F)
         | ((*rd as u32    & 0x1F) << 7)
         | ((funct3        & 0x07) << 12)
         | ((*rs1 as u32   & 0x1F) << 15)
         | ((csr           & 0xFFF) << 20);
}

/// Encode a CSR instruction with an immediate source.
fn encodeCsrImm(op: u32, rd: gen::Reg, csr: u32, funct3: u32, imm: u32) -> u32 {
    assert imm < 32;
    return (op             & 0x7F)
         | ((*rd as u32    & 0x1F) << 7)
         | ((funct3        & 0x07) << 12)
         | ((imm           & 0x1F) << 15)
         | ((csr           & 0xFFF) << 20);
}

/// Read CSR into `rd`.
export fn csrr(rd: gen::Reg, csr: u32) -> u32 {
    return encodeCsr(OP_SYSTEM, rd, csr, F3_CSRRS, super::ZERO);
}

/// Read/write CSR: old CSR to `rd`, write `rs1`.
export fn csrrw(rd: gen::Reg, csr: u32, rs1: gen::Reg) -> u32 {
    return encodeCsr(OP_SYSTEM, rd, csr, F3_CSRRW, rs1);
}

/// Write `rs1` into CSR and discard old value.
export fn csrw(csr: u32, rs1: gen::Reg) -> u32 {
    return encodeCsr(OP_SYSTEM, super::ZERO, csr, F3_CSRRW, rs1);
}

/// Clear CSR bits from `rs1` and discard old value.
export fn csrc(csr: u32, rs1: gen::Reg) -> u32 {
    return encodeCsr(OP_SYSTEM, super::ZERO, csr, F3_CSRRC, rs1);
}

/// Set CSR bits from a 5-bit immediate and discard old value.
export fn csrsi(csr: u32, imm: u32) -> u32 {
    return encodeCsrImm(OP_SYSTEM, super::ZERO, csr, F3_CSRRSI, imm);
}

/// Wait for interrupt.
export fn wfi() -> u32 {
    return 0x10500073;
}

/// Return from machine mode trap.
export fn mret() -> u32 {
    return 0x30200073;
}

/////////////////////////
// Pseudo-instructions //
/////////////////////////

/// No operation: `addi zero, zero, 0`.
export fn nop() -> u32 {
    return addi(super::ZERO, super::ZERO, 0);
}

/// Move: `rd = rs` (`addi rd, rs, 0`).
export fn mv(rd: gen::Reg, rs: gen::Reg) -> u32 {
    return addi(rd, rs, 0);
}

/// Bitwise NOT: `rd = ~rs` (`xori rd, rs, -1`).
export fn not_(rd: gen::Reg, rs: gen::Reg) -> u32 {
    return xori(rd, rs, -1);
}

/// Negate: `rd = -rs` (`sub rd, zero, rs`).
export fn neg(rd: gen::Reg, rs: gen::Reg) -> u32 {
    return sub(rd, super::ZERO, rs);
}

/// Return: `jalr zero, ra, 0`.
export fn ret() -> u32 {
    return jalr(super::ZERO, super::RA, 0);
}

/// Jump (unconditional): `jal zero, imm`.
export fn j(imm: i32) -> u32 {
    return jal(super::ZERO, imm);
}

/// Branch if less than or equal (signed): `if (rs1 <= rs2) pc += imm`.
/// Implemented as `bge rs2, rs1, imm` (swap operands).
export fn ble(rs1: gen::Reg, rs2: gen::Reg, imm: i32) -> u32 {
    return bge(rs2, rs1, imm);
}

/// Branch if greater than (signed): `if (rs1 > rs2) pc += imm`.
/// Implemented as `blt rs2, rs1, imm` (swap operands).
export fn bgt(rs1: gen::Reg, rs2: gen::Reg, imm: i32) -> u32 {
    return blt(rs2, rs1, imm);
}

/// Set if equal to zero: `rd = (rs == 0) ? 1 : 0`.
/// Implemented as `sltiu rd, rs, 1`.
export fn seqz(rd: gen::Reg, rs: gen::Reg) -> u32 {
    return sltiu(rd, rs, 1);
}

/// Set if not equal to zero: `rd = (rs <> 0) ? 1 : 0`.
/// Implemented as `sltu rd, zero, rs`.
export fn snez(rd: gen::Reg, rs: gen::Reg) -> u32 {
    return sltu(rd, super::ZERO, rs);
}

/// Branch if equal to zero: `if (rs == 0) pc += imm`.
export fn beqz(rs: gen::Reg, imm: i32) -> u32 {
    return beq(rs, super::ZERO, imm);
}

/// Branch if not equal to zero: `if (rs <> 0) pc += imm`.
export fn bnez(rs: gen::Reg, imm: i32) -> u32 {
    return bne(rs, super::ZERO, imm);
}

/// Call: `jal ra, imm`.
export fn call(imm: i32) -> u32 {
    return jal(super::RA, imm);
}

/// Order the specified predecessor and successor memory or I/O access classes.
/// Each mask uses I=8, O=4, R=2, W=1.
export fn fenceOrder(predecessor: u32, successor: u32) -> u32 {
    assert predecessor <= 15 and successor <= 15;
    return 0x0f | (predecessor << 24) | (successor << 20);
}

/// Synchronize subsequent instruction fetch on the executing hart.
export fn fenceI() -> u32 { return 0x0000100f; }