kit

isa.h (61761B)

---

 #ifndef KIT_ARCH_AA64_ISA_H
 #define KIT_ARCH_AA64_ISA_H
 
 /* AArch64 ISA descriptors — single source of truth for every instruction
  * the encoder, decoder, and disassembler all need to agree on.
  *
  * Each format declares:
  *   - A field struct naming every encoded bitfield.
  *   - {pack, unpack} pure functions that round-trip through a u32 word.
  *   - A {family_match, family_mask} pair identifying the format.
  *   - Per-instruction inline wrappers that bake in the opc bits and
  *     return the encoded word; callers emit it via MCEmitter.
  *
  * A descriptor table at the bottom (aa64_insn_table) maps mnemonic →
  * (match, mask, AA64Format), so the disassembler matches a raw word with
  *   for (i=0; i<N; ++i) if ((word & desc[i].mask) == desc[i].match) ...
  * and then calls the format's unpack to recover the operand fields.
  *
  * Conventions:
  *   - sf = 0 selects the 32-bit (W) form, sf = 1 selects 64-bit (X).
  *   - Reg values are the raw 5-bit encoding (0..30 + 31 for ZR/SP).
  *   - All wrappers take Rd first, then Rn, Rm, Ra to match the AAPCS
  *     "destination first" convention used in the AArch64 manual.
  *
  * New instructions land as one entry in the table and (typically) one
  * inline wrapper in the relevant format section. */
 
 #include "core/core.h"
 #include "core/slice.h"
 #include "core/strbuf.h"
 
 /* ---- common register names ---- */
 #define AA64_ZR 31u /* WZR / XZR */
 #define AA64_SP 31u /* SP at Rd/Rn slot */
 #define AA64_LR 30u /* X30 / link register */
 
 /* ---- format kinds ---- */
 typedef enum AA64Format {
   AA64_FMT_MOVEWIDE,
   AA64_FMT_LOG_SR,      /* logical, shifted register */
   AA64_FMT_ADDSUB_SR,   /* add/sub, shifted register */
   AA64_FMT_DP3,         /* data-processing, 3 source */
   AA64_FMT_DP2,         /* data-processing, 2 source */
   AA64_FMT_CONDSEL,     /* conditional select (CSEL / CSINC / aliases) */
   AA64_FMT_BR_REG,      /* unconditional branch (register) */
   AA64_FMT_PCREL_ADR,   /* PC-relative ADR / ADRP */
   AA64_FMT_ADDSUB_IMM,  /* add/sub, immediate */
   AA64_FMT_LDST_UIMM,   /* load/store, unsigned 12-bit immediate offset */
   AA64_FMT_LDSTP_PRE,   /* load/store pair, pre-indexed */
   AA64_FMT_LDSTP_SOFF,  /* load/store pair, signed-offset */
   AA64_FMT_LDSTP_POST,  /* load/store pair, post-indexed */
   AA64_FMT_LDST_SIMM9,  /* load/store, unscaled 9-bit signed offset
                            (LDUR / STUR, V=0 and V=1) */
   AA64_FMT_BR_IMM,      /* unconditional branch (immediate) — B / BL */
   AA64_FMT_BR_COND,     /* B.cond (imm19) */
   AA64_FMT_CB,          /* compare-and-branch (CBZ / CBNZ) */
   AA64_FMT_EXCEPT,      /* exception generation (BRK / SVC / HVC / ...) */
   AA64_FMT_HINT,        /* hint (NOP / YIELD / ...) */
   AA64_FMT_BARRIER,     /* memory barrier (DMB / DSB / ISB / CLREX) */
   AA64_FMT_DP1,         /* data-processing, 1 source (RBIT/REV/REV16/CLZ) */
   AA64_FMT_BITFIELD,    /* bitfield move (SBFM / UBFM): Rd, Rn, #immr, #imms */
   AA64_FMT_LDST_REGOFF, /* load/store, register offset [Xn, Xm{, LSL #s}] */
   AA64_FMT_FP_DP2,      /* FP data-processing 2-source (FADD/FSUB/FMUL/FDIV) */
   AA64_FMT_FP_DP1,      /* FP data-processing 1-source (FMOV/FNEG/FABS/FSQRT) */
   AA64_FMT_FP_CMP,      /* FP compare (FCMP) */
   AA64_FMT_FP_CVT,      /* FP precision convert (FCVT single<->double) */
   AA64_FMT_FP_INT_CVT,  /* FP<->int convert + FMOV gpr<->fp
                          * (SCVTF/UCVTF/FCVTZS/FCVTZU/FMOV) */
   AA64_FMT_LDST_EXCL,   /* load/store exclusive + acquire/release ordered
                          * (LDXR/LDAXR/STXR/STLXR/LDAR/STLR + b/h) */
   AA64_FMT_LOG_IMM,     /* logical, immediate (AND/ORR/EOR/ANDS #bitmask) */
   AA64_FMT_SYSREG,      /* system-register move (MRS Xt,<reg> / MSR <reg>,Xt) */
 } AA64Format;
 
 /* ---- AsmFlags column on AA64InsnDesc ----
  *
  * Per-row metadata that varies across same-format members.  Most rows
  * carry 0.  When the disassembler matches a row whose ALIAS bit is set,
  * that's the spelling it prints; the assembler also accepts both the
  * alias and the canonical form because both rows live in the table. */
 #define AA64_ASMFL_ALIAS                                                      \
   0x01u                      /* row is an alias (e.g. MOV → ORR Rd, ZR, Rm) \
                               */
 #define AA64_ASMFL_SF1 0x02u /* 64-bit form only (sf hard-wired) */
 #define AA64_ASMFL_NORN \
   0x04u /* hide Rn operand in print (e.g. RET when Rn=30) */
 
 /* ====================================================================
  * Move-wide immediate (MOVN / MOVZ / MOVK)
  *   sf  opc(2)  100101  hw(2)  imm16(16)  Rd(5)
  *   31  30..29  28..23  22..21 20..5      4..0
  * ==================================================================== */
 
 #define AA64_MOVN_OPC 0u
 #define AA64_MOVZ_OPC 2u
 #define AA64_MOVK_OPC 3u
 
 #define AA64_MOVEWIDE_FAMILY_MATCH 0x12800000u
 #define AA64_MOVEWIDE_FAMILY_MASK 0x1F800000u /* bits 28:23 */
 
 typedef struct AA64MoveWide {
   u32 sf, opc, hw, imm16, Rd;
 } AA64MoveWide;
 
 static inline u32 aa64_movewide_pack(AA64MoveWide f) {
   return ((f.sf & 1u) << 31) | ((f.opc & 3u) << 29) |
          AA64_MOVEWIDE_FAMILY_MATCH | ((f.hw & 3u) << 21) |
          ((f.imm16 & 0xffffu) << 5) | (f.Rd & 0x1fu);
 }
 
 static inline AA64MoveWide aa64_movewide_unpack(u32 w) {
   AA64MoveWide f;
   f.sf = (w >> 31) & 1u;
   f.opc = (w >> 29) & 3u;
   f.hw = (w >> 21) & 3u;
   f.imm16 = (w >> 5) & 0xffffu;
   f.Rd = w & 0x1fu;
   return f;
 }
 
 static inline u32 aa64_movz(u32 sf, u32 Rd, u32 imm16, u32 hw) {
   return aa64_movewide_pack((AA64MoveWide){
       .sf = sf, .opc = AA64_MOVZ_OPC, .hw = hw, .imm16 = imm16, .Rd = Rd});
 }
 static inline u32 aa64_movn(u32 sf, u32 Rd, u32 imm16, u32 hw) {
   return aa64_movewide_pack((AA64MoveWide){
       .sf = sf, .opc = AA64_MOVN_OPC, .hw = hw, .imm16 = imm16, .Rd = Rd});
 }
 static inline u32 aa64_movk(u32 sf, u32 Rd, u32 imm16, u32 hw) {
   return aa64_movewide_pack((AA64MoveWide){
       .sf = sf, .opc = AA64_MOVK_OPC, .hw = hw, .imm16 = imm16, .Rd = Rd});
 }
 
 /* ====================================================================
  * Logical, shifted register (AND / ORR / EOR / ANDS, with N inverting
  * Rm to BIC / ORN / EON / BICS).
  *   sf  opc(2)  01010  shift(2)  N(1)  Rm(5)  imm6(6)  Rn(5)  Rd(5)
  *   31  30..29  28..24 23..22    21    20..16 15..10   9..5   4..0
  * ==================================================================== */
 
 #define AA64_LOG_AND_OPC 0u
 #define AA64_LOG_ORR_OPC 1u
 #define AA64_LOG_EOR_OPC 2u
 #define AA64_LOG_ANDS_OPC 3u
 
 #define AA64_LOGSR_FAMILY_MATCH 0x0A000000u
 #define AA64_LOGSR_FAMILY_MASK 0x1F000000u /* bits 28:24 */
 
 typedef struct AA64LogSR {
   u32 sf, opc, shift, N, Rm, imm6, Rn, Rd;
 } AA64LogSR;
 
 static inline u32 aa64_logsr_pack(AA64LogSR f) {
   return ((f.sf & 1u) << 31) | ((f.opc & 3u) << 29) | AA64_LOGSR_FAMILY_MATCH |
          ((f.shift & 3u) << 22) | ((f.N & 1u) << 21) | ((f.Rm & 0x1fu) << 16) |
          ((f.imm6 & 0x3fu) << 10) | ((f.Rn & 0x1fu) << 5) | (f.Rd & 0x1fu);
 }
 
 static inline AA64LogSR aa64_logsr_unpack(u32 w) {
   AA64LogSR f;
   f.sf = (w >> 31) & 1u;
   f.opc = (w >> 29) & 3u;
   f.shift = (w >> 22) & 3u;
   f.N = (w >> 21) & 1u;
   f.Rm = (w >> 16) & 0x1fu;
   f.imm6 = (w >> 10) & 0x3fu;
   f.Rn = (w >> 5) & 0x1fu;
   f.Rd = w & 0x1fu;
   return f;
 }
 
 static inline u32 aa64_and(u32 sf, u32 Rd, u32 Rn, u32 Rm) {
   return aa64_logsr_pack((AA64LogSR){
       .sf = sf, .opc = AA64_LOG_AND_OPC, .Rm = Rm, .Rn = Rn, .Rd = Rd});
 }
 static inline u32 aa64_orr(u32 sf, u32 Rd, u32 Rn, u32 Rm) {
   return aa64_logsr_pack((AA64LogSR){
       .sf = sf, .opc = AA64_LOG_ORR_OPC, .Rm = Rm, .Rn = Rn, .Rd = Rd});
 }
 static inline u32 aa64_eor(u32 sf, u32 Rd, u32 Rn, u32 Rm) {
   return aa64_logsr_pack((AA64LogSR){
       .sf = sf, .opc = AA64_LOG_EOR_OPC, .Rm = Rm, .Rn = Rn, .Rd = Rd});
 }
 static inline u32 aa64_orn(u32 sf, u32 Rd, u32 Rn, u32 Rm) {
   return aa64_logsr_pack((AA64LogSR){
       .sf = sf, .opc = AA64_LOG_ORR_OPC, .N = 1, .Rm = Rm, .Rn = Rn, .Rd = Rd});
 }
 
 /* MOV Wd, Wm  ≡  ORR Wd, WZR, Wm */
 static inline u32 aa64_mov_reg(u32 sf, u32 Rd, u32 Rm) {
   return aa64_orr(sf, Rd, AA64_ZR, Rm);
 }
 /* MVN Wd, Wm  ≡  ORN Wd, WZR, Wm */
 static inline u32 aa64_mvn(u32 sf, u32 Rd, u32 Rm) {
   return aa64_orn(sf, Rd, AA64_ZR, Rm);
 }
 
 /* ====================================================================
  * Logical, immediate (AND / ORR / EOR / ANDS, bitmask-imm form)
  *   sf  opc(2)  100100  N(1)  immr(6)  imms(6)  Rn(5)  Rd(5)
  *   31  30..29  28..23  22    21..16   15..10   9..5   4..0
  *
  * N:immr:imms encodes a repeated-pattern bitmask. The encoder
  * aa64_logimm_encode below computes those fields from a literal value;
  * this pack just lays the bits out. For 32-bit ops (sf=0), N must be 0;
  * for 64-bit ops N can be 0 or 1 and selects whether the pattern
  * element is 64 bits (N=1) or 2..32 bits (N=0).
  * ==================================================================== */
 
 #define AA64_LOGIMM_FAMILY_MATCH 0x12000000u
 #define AA64_LOGIMM_FAMILY_MASK 0x1F800000u /* bits 28:23 */
 
 typedef struct AA64LogImm {
   u32 sf, opc, N, immr, imms, Rn, Rd;
 } AA64LogImm;
 
 static inline u32 aa64_logimm_pack(AA64LogImm f) {
   return ((f.sf & 1u) << 31) | ((f.opc & 3u) << 29) | AA64_LOGIMM_FAMILY_MATCH |
          ((f.N & 1u) << 22) | ((f.immr & 0x3fu) << 16) |
          ((f.imms & 0x3fu) << 10) | ((f.Rn & 0x1fu) << 5) | (f.Rd & 0x1fu);
 }
 
 static inline u32 aa64_and_imm(u32 sf, u32 Rd, u32 Rn, u32 N, u32 immr,
                                u32 imms) {
   return aa64_logimm_pack((AA64LogImm){.sf = sf,
                                        .opc = AA64_LOG_AND_OPC,
                                        .N = N,
                                        .immr = immr,
                                        .imms = imms,
                                        .Rn = Rn,
                                        .Rd = Rd});
 }
 static inline u32 aa64_orr_imm(u32 sf, u32 Rd, u32 Rn, u32 N, u32 immr,
                                u32 imms) {
   return aa64_logimm_pack((AA64LogImm){.sf = sf,
                                        .opc = AA64_LOG_ORR_OPC,
                                        .N = N,
                                        .immr = immr,
                                        .imms = imms,
                                        .Rn = Rn,
                                        .Rd = Rd});
 }
 static inline u32 aa64_eor_imm(u32 sf, u32 Rd, u32 Rn, u32 N, u32 immr,
                                u32 imms) {
   return aa64_logimm_pack((AA64LogImm){.sf = sf,
                                        .opc = AA64_LOG_EOR_OPC,
                                        .N = N,
                                        .immr = immr,
                                        .imms = imms,
                                        .Rn = Rn,
                                        .Rd = Rd});
 }
 
 /* Bitmask-immediate predicate + encoder. Returns 1 and writes N/immr/imms
  * if `imm` is encodable as an AArch64 logical immediate of width
  * (sf ? 64 : 32); returns 0 otherwise (caller materializes into a
  * scratch and uses the shifted-register form).
  *
  * Algorithm (inverse of ARM ARM "DecodeBitMasks"): an encodable value
  * is a non-zero, non-all-ones bitmask made of a repeated `size`-bit
  * element (size ∈ {2,4,8,16,32,64}); within one element the pattern is
  * a rotation of (0…0 1…1). Find size by detecting the smallest
  * repeating period; find the rotation that places the 1-run at the
  * LSB; encode size and ones-count into imms per the standard scheme
  * (top bits of imms inverted-encode size, low bits are ones-count-1). */
 static inline int aa64_logimm_encode(u64 imm, u32 sf, u32* N_out, u32* immr_out,
                                      u32* imms_out) {
   if (!sf) {
     u64 lo = imm & 0xFFFFFFFFu;
     u64 hi = imm >> 32;
     if (hi != 0 && hi != lo) return 0;
     imm = lo | (lo << 32);
   }
   if (imm == 0 || imm == ~(u64)0) return 0;
 
   u32 size = 64;
   for (u32 s = 32; s >= 2; s >>= 1) {
     u64 mask = ((u64)1 << s) - 1u;
     if ((imm & mask) != ((imm >> s) & mask)) break;
     size = s;
   }
   u64 elt_mask = (size == 64) ? ~(u64)0 : (((u64)1 << size) - 1u);
   u64 elt = imm & elt_mask;
   if (elt == 0 || elt == elt_mask) return 0;
 
   u32 ones = 0;
   for (u64 x = elt; x; x >>= 1) ones += (u32)(x & 1u);
   if (ones == 0 || ones >= size) return 0;
 
   u64 aligned = ((u64)1 << ones) - 1u;
   u32 rotation = 0xFFFFFFFFu;
   for (u32 r = 0; r < size; r++) {
     u64 rotated =
         r == 0 ? elt : (((elt >> r) | (elt << (size - r))) & elt_mask);
     if (rotated == aligned) {
       rotation = r;
       break;
     }
   }
   if (rotation == 0xFFFFFFFFu) return 0;
 
   if (size == 64) {
     *N_out = 1u;
     *imms_out = (ones - 1u) & 0x3Fu;
   } else {
     *N_out = 0u;
     u32 neg_size_shl1 = ((u32)(-(i32)size) << 1) & 0x3Fu;
     *imms_out = neg_size_shl1 | ((ones - 1u) & 0x3Fu);
   }
   *immr_out = rotation ? (size - rotation) & (size - 1u) : 0u;
   return 1;
 }
 
 /* Shift-by-immediate field generators for LSL/LSR/ASR (encoded via
  * UBFM/SBFM). Predicate: shift < width. The aa64_ubfm / aa64_sbfm
  * encoders live in aarch64.c; callers pair these (immr, imms) with the
  * matching pack. */
 static inline int aa64_lsl_imm_fields(u32 shift, u32 sf, u32* immr_out,
                                       u32* imms_out) {
   u32 width = sf ? 64u : 32u;
   if (shift >= width) return 0;
   *immr_out = (width - shift) & (width - 1u);
   *imms_out = width - 1u - shift;
   return 1;
 }
 static inline int aa64_lsr_imm_fields(u32 shift, u32 sf, u32* immr_out,
                                       u32* imms_out) {
   u32 width = sf ? 64u : 32u;
   if (shift >= width) return 0;
   *immr_out = shift;
   *imms_out = width - 1u;
   return 1;
 }
 static inline int aa64_asr_imm_fields(u32 shift, u32 sf, u32* immr_out,
                                       u32* imms_out) {
   u32 width = sf ? 64u : 32u;
   if (shift >= width) return 0;
   *immr_out = shift;
   *imms_out = width - 1u;
   return 1;
 }
 
 /* ====================================================================
  * Add/Sub, shifted register (ADD / SUB / ADDS / SUBS)
  *   sf  op(1)  S(1)  01011  shift(2)  0  Rm(5)  imm6(6)  Rn(5)  Rd(5)
  *   31  30     29    28..24 23..22    21 20..16 15..10   9..5   4..0
  * ==================================================================== */
 
 #define AA64_ADDSUBSR_FAMILY_MATCH 0x0B000000u
 #define AA64_ADDSUBSR_FAMILY_MASK 0x1F200000u /* bits 28:24 + bit 21 */
 
 typedef struct AA64AddSubSR {
   u32 sf, op, S, shift, Rm, imm6, Rn, Rd;
 } AA64AddSubSR;
 
 static inline u32 aa64_addsubsr_pack(AA64AddSubSR f) {
   return ((f.sf & 1u) << 31) | ((f.op & 1u) << 30) | ((f.S & 1u) << 29) |
          AA64_ADDSUBSR_FAMILY_MATCH | ((f.shift & 3u) << 22) |
          ((f.Rm & 0x1fu) << 16) | ((f.imm6 & 0x3fu) << 10) |
          ((f.Rn & 0x1fu) << 5) | (f.Rd & 0x1fu);
 }
 
 static inline AA64AddSubSR aa64_addsubsr_unpack(u32 w) {
   AA64AddSubSR f;
   f.sf = (w >> 31) & 1u;
   f.op = (w >> 30) & 1u;
   f.S = (w >> 29) & 1u;
   f.shift = (w >> 22) & 3u;
   f.Rm = (w >> 16) & 0x1fu;
   f.imm6 = (w >> 10) & 0x3fu;
   f.Rn = (w >> 5) & 0x1fu;
   f.Rd = w & 0x1fu;
   return f;
 }
 
 static inline u32 aa64_add(u32 sf, u32 Rd, u32 Rn, u32 Rm) {
   return aa64_addsubsr_pack(
       (AA64AddSubSR){.sf = sf, .op = 0, .Rm = Rm, .Rn = Rn, .Rd = Rd});
 }
 static inline u32 aa64_sub(u32 sf, u32 Rd, u32 Rn, u32 Rm) {
   return aa64_addsubsr_pack(
       (AA64AddSubSR){.sf = sf, .op = 1, .Rm = Rm, .Rn = Rn, .Rd = Rd});
 }
 
 /* NEG Wd, Wm  ≡  SUB Wd, WZR, Wm */
 static inline u32 aa64_neg(u32 sf, u32 Rd, u32 Rm) {
   return aa64_sub(sf, Rd, AA64_ZR, Rm);
 }
 
 /* ====================================================================
  * Data-processing, 3-source (MADD / MSUB / SMULL / UMULL / ...)
  *   sf  op54(2)  11011  op31(3)  Rm(5)  o0(1)  Ra(5)  Rn(5)  Rd(5)
  *   31  30..29   28..24 23..21   20..16 15     14..10 9..5   4..0
  * ==================================================================== */
 
 #define AA64_DP3_FAMILY_MATCH 0x1B000000u
 #define AA64_DP3_FAMILY_MASK 0x1F000000u /* bits 28:24 */
 
 typedef struct AA64DP3 {
   u32 sf, op54, op31, Rm, o0, Ra, Rn, Rd;
 } AA64DP3;
 
 static inline u32 aa64_dp3_pack(AA64DP3 f) {
   return ((f.sf & 1u) << 31) | ((f.op54 & 3u) << 29) | AA64_DP3_FAMILY_MATCH |
          ((f.op31 & 7u) << 21) | ((f.Rm & 0x1fu) << 16) | ((f.o0 & 1u) << 15) |
          ((f.Ra & 0x1fu) << 10) | ((f.Rn & 0x1fu) << 5) | (f.Rd & 0x1fu);
 }
 
 static inline AA64DP3 aa64_dp3_unpack(u32 w) {
   AA64DP3 f;
   f.sf = (w >> 31) & 1u;
   f.op54 = (w >> 29) & 3u;
   f.op31 = (w >> 21) & 7u;
   f.Rm = (w >> 16) & 0x1fu;
   f.o0 = (w >> 15) & 1u;
   f.Ra = (w >> 10) & 0x1fu;
   f.Rn = (w >> 5) & 0x1fu;
   f.Rd = w & 0x1fu;
   return f;
 }
 
 static inline u32 aa64_madd(u32 sf, u32 Rd, u32 Rn, u32 Rm, u32 Ra) {
   return aa64_dp3_pack((AA64DP3){
       .sf = sf, .op31 = 0, .o0 = 0, .Rm = Rm, .Ra = Ra, .Rn = Rn, .Rd = Rd});
 }
 static inline u32 aa64_msub(u32 sf, u32 Rd, u32 Rn, u32 Rm, u32 Ra) {
   return aa64_dp3_pack((AA64DP3){
       .sf = sf, .op31 = 0, .o0 = 1, .Rm = Rm, .Ra = Ra, .Rn = Rn, .Rd = Rd});
 }
 /* MUL Wd, Wn, Wm  ≡  MADD Wd, Wn, Wm, WZR */
 static inline u32 aa64_mul(u32 sf, u32 Rd, u32 Rn, u32 Rm) {
   return aa64_madd(sf, Rd, Rn, Rm, AA64_ZR);
 }
 
 /* ====================================================================
  * Data-processing, 2-source (UDIV / SDIV / LSLV / LSRV / ASRV / RORV)
  *   sf  0  S(1)  11010110  Rm(5)  opcode(6)  Rn(5)  Rd(5)
  *   31  30 29    28..21    20..16 15..10     9..5   4..0
  * ==================================================================== */
 
 #define AA64_DP2_UDIV_OP 0x02u
 #define AA64_DP2_SDIV_OP 0x03u
 #define AA64_DP2_LSLV_OP 0x08u
 #define AA64_DP2_LSRV_OP 0x09u
 #define AA64_DP2_ASRV_OP 0x0Au
 #define AA64_DP2_RORV_OP 0x0Bu
 
 #define AA64_DP2_FAMILY_MATCH 0x1AC00000u
 #define AA64_DP2_FAMILY_MASK 0x5FE00000u /* bit 30 + bits 28:21 */
 
 typedef struct AA64DP2 {
   u32 sf, S, opcode, Rm, Rn, Rd;
 } AA64DP2;
 
 static inline u32 aa64_dp2_pack(AA64DP2 f) {
   return ((f.sf & 1u) << 31) | ((f.S & 1u) << 29) | AA64_DP2_FAMILY_MATCH |
          ((f.Rm & 0x1fu) << 16) | ((f.opcode & 0x3fu) << 10) |
          ((f.Rn & 0x1fu) << 5) | (f.Rd & 0x1fu);
 }
 
 static inline AA64DP2 aa64_dp2_unpack(u32 w) {
   AA64DP2 f;
   f.sf = (w >> 31) & 1u;
   f.S = (w >> 29) & 1u;
   f.Rm = (w >> 16) & 0x1fu;
   f.opcode = (w >> 10) & 0x3fu;
   f.Rn = (w >> 5) & 0x1fu;
   f.Rd = w & 0x1fu;
   return f;
 }
 
 static inline u32 aa64_udiv(u32 sf, u32 Rd, u32 Rn, u32 Rm) {
   return aa64_dp2_pack((AA64DP2){
       .sf = sf, .opcode = AA64_DP2_UDIV_OP, .Rm = Rm, .Rn = Rn, .Rd = Rd});
 }
 static inline u32 aa64_sdiv(u32 sf, u32 Rd, u32 Rn, u32 Rm) {
   return aa64_dp2_pack((AA64DP2){
       .sf = sf, .opcode = AA64_DP2_SDIV_OP, .Rm = Rm, .Rn = Rn, .Rd = Rd});
 }
 static inline u32 aa64_lslv(u32 sf, u32 Rd, u32 Rn, u32 Rm) {
   return aa64_dp2_pack((AA64DP2){
       .sf = sf, .opcode = AA64_DP2_LSLV_OP, .Rm = Rm, .Rn = Rn, .Rd = Rd});
 }
 static inline u32 aa64_lsrv(u32 sf, u32 Rd, u32 Rn, u32 Rm) {
   return aa64_dp2_pack((AA64DP2){
       .sf = sf, .opcode = AA64_DP2_LSRV_OP, .Rm = Rm, .Rn = Rn, .Rd = Rd});
 }
 static inline u32 aa64_asrv(u32 sf, u32 Rd, u32 Rn, u32 Rm) {
   return aa64_dp2_pack((AA64DP2){
       .sf = sf, .opcode = AA64_DP2_ASRV_OP, .Rm = Rm, .Rn = Rn, .Rd = Rd});
 }
 static inline u32 aa64_rorv(u32 sf, u32 Rd, u32 Rn, u32 Rm) {
   return aa64_dp2_pack((AA64DP2){
       .sf = sf, .opcode = AA64_DP2_RORV_OP, .Rm = Rm, .Rn = Rn, .Rd = Rd});
 }
 
 /* ====================================================================
  * Conditional select (CSEL / CSINC / CSINV / CSNEG)
  *   sf  op  S  11010100  Rm(5)  cond(4)  op2(2)  Rn(5)  Rd(5)
  *   31  30  29 28..21    20..16 15..12   11..10  9..5   4..0
  *
  * The integer forms this backend emits keep S=0.  Aliases such as CSET
  * are descriptor-table rows over this same encoding family. */
 
 #define AA64_CONDSEL_FAMILY_MATCH 0x1A800000u
 #define AA64_CONDSEL_FAMILY_MASK 0x1FE00000u /* bits 28:21 fixed */
 
 typedef struct AA64CondSel {
   u32 sf, op, S, Rm, cond, op2, Rn, Rd;
 } AA64CondSel;
 
 static inline u32 aa64_condsel_pack(AA64CondSel f) {
   return ((f.sf & 1u) << 31) | ((f.op & 1u) << 30) | ((f.S & 1u) << 29) |
          AA64_CONDSEL_FAMILY_MATCH | ((f.Rm & 0x1fu) << 16) |
          ((f.cond & 0xfu) << 12) | ((f.op2 & 3u) << 10) |
          ((f.Rn & 0x1fu) << 5) | (f.Rd & 0x1fu);
 }
 
 static inline AA64CondSel aa64_condsel_unpack(u32 w) {
   AA64CondSel f;
   f.sf = (w >> 31) & 1u;
   f.op = (w >> 30) & 1u;
   f.S = (w >> 29) & 1u;
   f.Rm = (w >> 16) & 0x1fu;
   f.cond = (w >> 12) & 0xfu;
   f.op2 = (w >> 10) & 3u;
   f.Rn = (w >> 5) & 0x1fu;
   f.Rd = w & 0x1fu;
   return f;
 }
 
 static inline u32 aa64_csel_enc(u32 sf, u32 Rd, u32 Rn, u32 Rm, u32 cond) {
   return aa64_condsel_pack((AA64CondSel){.sf = sf,
                                          .op = 0,
                                          .S = 0,
                                          .Rm = Rm,
                                          .cond = cond,
                                          .op2 = 0,
                                          .Rn = Rn,
                                          .Rd = Rd});
 }
 static inline u32 aa64_csinc_enc(u32 sf, u32 Rd, u32 Rn, u32 Rm, u32 cond) {
   return aa64_condsel_pack((AA64CondSel){.sf = sf,
                                          .op = 0,
                                          .S = 0,
                                          .Rm = Rm,
                                          .cond = cond,
                                          .op2 = 1,
                                          .Rn = Rn,
                                          .Rd = Rd});
 }
 static inline u32 aa64_csinv_enc(u32 sf, u32 Rd, u32 Rn, u32 Rm, u32 cond) {
   return aa64_condsel_pack((AA64CondSel){.sf = sf,
                                          .op = 1,
                                          .S = 0,
                                          .Rm = Rm,
                                          .cond = cond,
                                          .op2 = 0,
                                          .Rn = Rn,
                                          .Rd = Rd});
 }
 static inline u32 aa64_csneg_enc(u32 sf, u32 Rd, u32 Rn, u32 Rm, u32 cond) {
   return aa64_condsel_pack((AA64CondSel){.sf = sf,
                                          .op = 1,
                                          .S = 0,
                                          .Rm = Rm,
                                          .cond = cond,
                                          .op2 = 1,
                                          .Rn = Rn,
                                          .Rd = Rd});
 }
 
 /* ====================================================================
  * Unconditional branch (register) — BR / BLR / RET
  *   1101011  opc(4)  op2(5)=11111  op3(6)=000000  Rn(5)  op4(5)=00000
  *   31..25   24..21  20..16        15..10         9..5   4..0
  * ==================================================================== */
 
 #define AA64_BR_OP_BR 0u
 #define AA64_BR_OP_BLR 1u
 #define AA64_BR_OP_RET 2u
 
 #define AA64_BR_REG_FAMILY_MATCH 0xD61F0000u
 #define AA64_BR_REG_FAMILY_MASK \
   0xFE1FFC1Fu /* everything fixed except opc + Rn */
 
 typedef struct AA64BrReg {
   u32 opc, Rn;
 } AA64BrReg;
 
 static inline u32 aa64_brreg_pack(AA64BrReg f) {
   return AA64_BR_REG_FAMILY_MATCH | ((f.opc & 0xfu) << 21) |
          ((f.Rn & 0x1fu) << 5);
 }
 
 static inline AA64BrReg aa64_brreg_unpack(u32 w) {
   AA64BrReg f;
   f.opc = (w >> 21) & 0xfu;
   f.Rn = (w >> 5) & 0x1fu;
   return f;
 }
 
 static inline u32 aa64_br(u32 Rn) {
   return aa64_brreg_pack((AA64BrReg){.opc = AA64_BR_OP_BR, .Rn = Rn});
 }
 static inline u32 aa64_blr(u32 Rn) {
   return aa64_brreg_pack((AA64BrReg){.opc = AA64_BR_OP_BLR, .Rn = Rn});
 }
 static inline u32 aa64_ret(u32 Rn) {
   return aa64_brreg_pack((AA64BrReg){.opc = AA64_BR_OP_RET, .Rn = Rn});
 }
 
 /* ====================================================================
  * PC-relative addressing (ADR / ADRP)
  *   op(1)  immlo(2)  10000  immhi(19)  Rd(5)
  *   31     30..29    28..24 23..5      4..0
  *
  * op = 0 → ADR  (PC + sign_extend(immhi:immlo))
  * op = 1 → ADRP (page(PC) + sign_extend(immhi:immlo) << 12)
  *
  * The two immediate halves stay split because the linker's
  * R_AARCH64_ADR_PREL_PG_HI21 reloc patches them in place; keeping the
  * field layout symmetric with the encoded word lets reloc-apply code
  * reuse the same pack/unpack helpers.
  * ==================================================================== */
 
 #define AA64_ADR_OP_ADR 0u
 #define AA64_ADR_OP_ADRP 1u
 
 #define AA64_PCREL_ADR_FAMILY_MATCH 0x10000000u
 #define AA64_PCREL_ADR_FAMILY_MASK 0x1F000000u /* bits 28:24 */
 
 typedef struct AA64PCRelAdr {
   u32 op, immlo, immhi, Rd;
 } AA64PCRelAdr;
 
 static inline u32 aa64_pcrel_adr_pack(AA64PCRelAdr f) {
   return ((f.op & 1u) << 31) | ((f.immlo & 3u) << 29) |
          AA64_PCREL_ADR_FAMILY_MATCH | ((f.immhi & 0x7ffffu) << 5) |
          (f.Rd & 0x1fu);
 }
 
 static inline AA64PCRelAdr aa64_pcrel_adr_unpack(u32 w) {
   AA64PCRelAdr f;
   f.op = (w >> 31) & 1u;
   f.immlo = (w >> 29) & 3u;
   f.immhi = (w >> 5) & 0x7ffffu;
   f.Rd = w & 0x1fu;
   return f;
 }
 
 static inline u32 aa64_adrp(u32 Rd, u32 immlo, u32 immhi) {
   return aa64_pcrel_adr_pack((AA64PCRelAdr){
       .op = AA64_ADR_OP_ADRP, .immlo = immlo, .immhi = immhi, .Rd = Rd});
 }
 static inline u32 aa64_adr(u32 Rd, u32 immlo, u32 immhi) {
   return aa64_pcrel_adr_pack((AA64PCRelAdr){
       .op = AA64_ADR_OP_ADR, .immlo = immlo, .immhi = immhi, .Rd = Rd});
 }
 
 /* ====================================================================
  * Add/Sub, immediate (ADD / SUB / ADDS / SUBS, 12-bit imm with shift)
  *   sf  op(1)  S(1)  100010  sh(1)  imm12(12)  Rn(5)  Rd(5)
  *   31  30     29    28..23  22     21..10     9..5   4..0
  *
  * sh selects whether imm12 is left-shifted by 12.  Used by PLT entries
  * for `add x16, x16, #lo12(slot)` where sh=0 and imm12 = slot & 0xfff.
  * ==================================================================== */
 
 #define AA64_ADDSUBIMM_FAMILY_MATCH 0x11000000u
 #define AA64_ADDSUBIMM_FAMILY_MASK 0x1F000000u /* bits 28:24 */
 
 typedef struct AA64AddSubImm {
   u32 sf, op, S, sh, imm12, Rn, Rd;
 } AA64AddSubImm;
 
 static inline u32 aa64_addsubimm_pack(AA64AddSubImm f) {
   return ((f.sf & 1u) << 31) | ((f.op & 1u) << 30) | ((f.S & 1u) << 29) |
          AA64_ADDSUBIMM_FAMILY_MATCH | ((f.sh & 1u) << 22) |
          ((f.imm12 & 0xfffu) << 10) | ((f.Rn & 0x1fu) << 5) | (f.Rd & 0x1fu);
 }
 
 static inline AA64AddSubImm aa64_addsubimm_unpack(u32 w) {
   AA64AddSubImm f;
   f.sf = (w >> 31) & 1u;
   f.op = (w >> 30) & 1u;
   f.S = (w >> 29) & 1u;
   f.sh = (w >> 22) & 1u;
   f.imm12 = (w >> 10) & 0xfffu;
   f.Rn = (w >> 5) & 0x1fu;
   f.Rd = w & 0x1fu;
   return f;
 }
 
 static inline u32 aa64_add_imm(u32 sf, u32 Rd, u32 Rn, u32 imm12, u32 sh) {
   return aa64_addsubimm_pack((AA64AddSubImm){
       .sf = sf, .op = 0, .sh = sh, .imm12 = imm12, .Rn = Rn, .Rd = Rd});
 }
 static inline u32 aa64_sub_imm(u32 sf, u32 Rd, u32 Rn, u32 imm12, u32 sh) {
   return aa64_addsubimm_pack((AA64AddSubImm){
       .sf = sf, .op = 1, .sh = sh, .imm12 = imm12, .Rn = Rn, .Rd = Rd});
 }
 /* SUBS imm — sets flags. Used for CMP imm (Rd=ZR) and for branchless
  * compares that feed CSET. The 12-bit-shifted form covers 0..0xFFFFF000
  * stepped by 0x1000; cg_fold collapses literal-only compares upstream,
  * so this encoder is reached for `x cmp const` and `if (x)` patterns. */
 static inline u32 aa64_subs_imm12(u32 sf, u32 Rd, u32 Rn, u32 imm12, u32 sh) {
   return aa64_addsubimm_pack((AA64AddSubImm){
       .sf = sf, .op = 1, .S = 1, .sh = sh, .imm12 = imm12, .Rn = Rn, .Rd = Rd});
 }
 
 /* Predicate: does `imm` fit ADD/SUB/CMP's 12-bit immediate (optionally
  * left-shifted by 12)? On success writes the encoded imm12 and sh and
  * returns 1; on failure returns 0 and leaves outputs untouched.
  *
  * The encoding admits 0..4095 directly (sh=0) and multiples of 4096 up
  * to 0xFFF000 (sh=1). Negative literals are rejected here — the caller
  * (e.g. opt's machinize, or a smarter cg) is free to swap ADD ↔ SUB and
  * retry with the negated literal; the bare predicate keeps the contract
  * narrow. */
 static inline int aa64_addsub_imm_fits(i64 imm, u32* imm12_out, u32* sh_out) {
   if (imm < 0) return 0;
   u64 u = (u64)imm;
   if (u <= 0xFFFu) {
     *imm12_out = (u32)u;
     *sh_out = 0;
     return 1;
   }
   if ((u & 0xFFFu) == 0 && (u >> 12) <= 0xFFFu) {
     *imm12_out = (u32)(u >> 12);
     *sh_out = 1;
     return 1;
   }
   return 0;
 }
 
 /* ====================================================================
  * Load/store, unsigned 12-bit immediate offset (LDR / STR, scaled)
  *   size(2)  111  V(1)  01  opc(2)  imm12(12)  Rn(5)  Rt(5)
  *   31..30   29..27 26   25..24 23..22 21..10  9..5   4..0
  *
  * size=11, V=0, opc=01 → LDR (64-bit, integer).  imm12 is the byte
  * offset divided by the access size (8 for LDR Xt), giving a 0..32760
  * byte range.
  *
  * Only the LDR Xt form is needed by the linker today (PLT loads through
  * x16/x17); the family encoders cover STR and the smaller widths so
  * future callers can drop in without touching this header.
  * ==================================================================== */
 
 #define AA64_LDST_SIZE_64 3u
 #define AA64_LDST_OPC_STR 0u
 #define AA64_LDST_OPC_LDR 1u
 
 #define AA64_LDST_UIMM_FAMILY_MATCH 0x39000000u
 #define AA64_LDST_UIMM_FAMILY_MASK 0x3B000000u /* bits 29:27 + bits 25:24 */
 
 typedef struct AA64LdStUimm {
   u32 size, V, opc, imm12, Rn, Rt;
 } AA64LdStUimm;
 
 static inline u32 aa64_ldst_uimm_pack(AA64LdStUimm f) {
   return ((f.size & 3u) << 30) | AA64_LDST_UIMM_FAMILY_MATCH |
          ((f.V & 1u) << 26) | ((f.opc & 3u) << 22) |
          ((f.imm12 & 0xfffu) << 10) | ((f.Rn & 0x1fu) << 5) | (f.Rt & 0x1fu);
 }
 
 static inline AA64LdStUimm aa64_ldst_uimm_unpack(u32 w) {
   AA64LdStUimm f;
   f.size = (w >> 30) & 3u;
   f.V = (w >> 26) & 1u;
   f.opc = (w >> 22) & 3u;
   f.imm12 = (w >> 10) & 0xfffu;
   f.Rn = (w >> 5) & 0x1fu;
   f.Rt = w & 0x1fu;
   return f;
 }
 
 /* LDR Xt, [Xn, #imm12_scaled].  imm12_scaled is the encoded field —
  * callers pass `byte_offset >> 3` for the 64-bit form. */
 static inline u32 aa64_ldr64_uimm12(u32 Rt, u32 Rn, u32 imm12_scaled) {
   return aa64_ldst_uimm_pack((AA64LdStUimm){.size = AA64_LDST_SIZE_64,
                                             .V = 0,
                                             .opc = AA64_LDST_OPC_LDR,
                                             .imm12 = imm12_scaled,
                                             .Rn = Rn,
                                             .Rt = Rt});
 }
 static inline u32 aa64_str64_uimm12(u32 Rt, u32 Rn, u32 imm12_scaled) {
   return aa64_ldst_uimm_pack((AA64LdStUimm){.size = AA64_LDST_SIZE_64,
                                             .V = 0,
                                             .opc = AA64_LDST_OPC_STR,
                                             .imm12 = imm12_scaled,
                                             .Rn = Rn,
                                             .Rt = Rt});
 }
 
 /* ---- Scalar floating-point encoders ----
  * ftype: 0=single (Sn), 1=double (Dn), 3=half (Hn). The bit layouts match the
  * FP_* decode rows in isa.c and the aa_* encoders in native.c, so encode and
  * decode round-trip. The DP2/DP1 `op` and the FP_INT_CVT `opcode` are the
  * named field values below. */
 #define AA64_FP_DP2_FMUL 0x0800u
 #define AA64_FP_DP2_FDIV 0x1800u
 #define AA64_FP_DP2_FADD 0x2800u
 #define AA64_FP_DP2_FSUB 0x3800u
 #define AA64_FP_DP2_FMAX 0x4800u
 #define AA64_FP_DP2_FMIN 0x5800u
 #define AA64_FP_DP2_FNMUL 0x8800u
 #define AA64_FP_DP1_FMOV 0x4000u
 #define AA64_FP_DP1_FABS 0xC000u
 #define AA64_FP_DP1_FNEG 0x14000u
 #define AA64_FP_DP1_FSQRT 0x1C000u
 #define AA64_FP_ICVT_SCVTF 0x02u
 #define AA64_FP_ICVT_UCVTF 0x03u
 #define AA64_FP_ICVT_FCVTZS 0x18u
 #define AA64_FP_ICVT_FCVTZU 0x19u
 #define AA64_FP_ICVT_FMOV_TO_GPR 0x06u /* fmov Rd, Vn */
 #define AA64_FP_ICVT_FMOV_TO_FP 0x07u  /* fmov Vd, Rn */
 
 static inline u32 aa64_fp_dp2(u32 ftype, u32 op, u32 Rd, u32 Rn, u32 Rm) {
   return 0x1E200000u | ((ftype & 3u) << 22) | op | ((Rm & 0x1fu) << 16) |
          ((Rn & 0x1fu) << 5) | (Rd & 0x1fu);
 }
 static inline u32 aa64_fp_dp1(u32 ftype, u32 op, u32 Rd, u32 Rn) {
   return 0x1E200000u | ((ftype & 3u) << 22) | op | ((Rn & 0x1fu) << 5) |
          (Rd & 0x1fu);
 }
 static inline u32 aa64_fcmp_reg(u32 ftype, u32 Rn, u32 Rm) {
   return 0x1E202000u | ((ftype & 3u) << 22) | ((Rm & 0x1fu) << 16) |
          ((Rn & 0x1fu) << 5);
 }
 static inline u32 aa64_fcvt_prec(u32 src_ftype, u32 dst_ftype, u32 Rd, u32 Rn) {
   return 0x1E204000u | ((src_ftype & 3u) << 22) | (1u << 17) |
          ((dst_ftype & 3u) << 15) | ((Rn & 0x1fu) << 5) | (Rd & 0x1fu);
 }
 static inline u32 aa64_fp_int_cvt(u32 sf, u32 ftype, u32 opcode, u32 Rd,
                                   u32 Rn) {
   return ((sf & 1u) << 31) | 0x1E200000u | ((ftype & 3u) << 22) |
          ((opcode & 0x1fu) << 16) | ((Rn & 0x1fu) << 5) | (Rd & 0x1fu);
 }
 
 /* Bitfield move (opc: 0=SBFM, 1=BFM, 2=UBFM). The N bit tracks sf for the
  * 32-/64-bit forms. Matches native.c aa_sbfm/aa_ubfm and the BITFIELD row. */
 static inline u32 aa64_bitfield(u32 sf, u32 opc, u32 immr, u32 imms, u32 Rd,
                                 u32 Rn) {
   return ((sf & 1u) << 31) | ((opc & 3u) << 29) | 0x13000000u |
          ((sf & 1u) << 22) | ((immr & 0x3fu) << 16) | ((imms & 0x3fu) << 10) |
          ((Rn & 0x1fu) << 5) | (Rd & 0x1fu);
 }
 
 /* Data-processing (1 source). opcode2 (bits[15:10]): RBIT=0, REV16=1,
  * REV(32)=2, REV(64)=3, CLZ=4. Matches native.c aa_clz/aa_rbit/aa_rev. */
 #define AA64_DP1_RBIT 0x00u
 #define AA64_DP1_REV16 0x01u
 #define AA64_DP1_REV32 0x02u
 #define AA64_DP1_REV64 0x03u
 #define AA64_DP1_CLZ 0x04u
 static inline u32 aa64_dp1(u32 sf, u32 opcode2, u32 Rd, u32 Rn) {
   return ((sf & 1u) << 31) | 0x5AC00000u | ((opcode2 & 0x3fu) << 10) |
          ((Rn & 0x1fu) << 5) | (Rd & 0x1fu);
 }
 
 /* ====================================================================
  * Load/store register pair, pre-indexed (STP / LDP, 64-bit form)
  *   opc(2)  101  V(1)  010  L(1)  imm7(7)  Rt2(5)  Rn(5)  Rt(5)
  *   31..30  29..27 26   25..23 22  21..15   14..10  9..5   4..0
  *
  * 64-bit integer form fixes opc=10, V=0.  L=0 → STP, L=1 → LDP.
  * imm7 is a signed 7-bit value scaled by 8 (for the 64-bit form): the
  * encoded field equals `byte_offset / 8`.  Callers pass the scaled
  * value already; the helper masks to 7 bits to handle negative inputs
  * sign-extended in i32.
  * ==================================================================== */
 
 #define AA64_LDSTP_PRE_FAMILY_MATCH 0x29800000u
 #define AA64_LDSTP_PRE_FAMILY_MASK 0x7FC00000u /* bits 30:23 */
 
 typedef struct AA64LdStPPre {
   u32 opc, V, L, imm7, Rt2, Rn, Rt;
 } AA64LdStPPre;
 
 static inline u32 aa64_ldstp_pre_pack(AA64LdStPPre f) {
   return ((f.opc & 3u) << 30) | AA64_LDSTP_PRE_FAMILY_MATCH |
          ((f.V & 1u) << 26) | ((f.L & 1u) << 22) | ((f.imm7 & 0x7fu) << 15) |
          ((f.Rt2 & 0x1fu) << 10) | ((f.Rn & 0x1fu) << 5) | (f.Rt & 0x1fu);
 }
 
 static inline AA64LdStPPre aa64_ldstp_pre_unpack(u32 w) {
   AA64LdStPPre f;
   f.opc = (w >> 30) & 3u;
   f.V = (w >> 26) & 1u;
   f.L = (w >> 22) & 1u;
   f.imm7 = (w >> 15) & 0x7fu;
   f.Rt2 = (w >> 10) & 0x1fu;
   f.Rn = (w >> 5) & 0x1fu;
   f.Rt = w & 0x1fu;
   return f;
 }
 
 /* STP Xt, Xt2, [Xn, #imm7_scaled]!  — opc=10 selects the 64-bit form.
  * imm7_scaled is `byte_offset / 8`; callers pass it pre-scaled (e.g.
  * -2 for [sp, #-16]!). */
 static inline u32 aa64_stp64_pre(u32 Rt, u32 Rt2, u32 Rn, i32 imm7_scaled) {
   return aa64_ldstp_pre_pack((AA64LdStPPre){.opc = 2,
                                             .V = 0,
                                             .L = 0,
                                             .imm7 = (u32)imm7_scaled & 0x7fu,
                                             .Rt2 = Rt2,
                                             .Rn = Rn,
                                             .Rt = Rt});
 }
 static inline u32 aa64_ldp64_pre(u32 Rt, u32 Rt2, u32 Rn, i32 imm7_scaled) {
   return aa64_ldstp_pre_pack((AA64LdStPPre){.opc = 2,
                                             .V = 0,
                                             .L = 1,
                                             .imm7 = (u32)imm7_scaled & 0x7fu,
                                             .Rt2 = Rt2,
                                             .Rn = Rn,
                                             .Rt = Rt});
 }
 
 /* Post-indexed STP/LDP — same field layout as the pre-indexed form, only
  * bits[25:23] differ (001 vs 011); reuse AA64LdStPPre. Used for the slim
  * prologue's epilogue restore: `ldp x29,x30,[sp],#16`. */
 #define AA64_LDSTP_POST_FAMILY_MATCH 0x28800000u
 #define AA64_LDSTP_POST_FAMILY_MASK 0x7FC00000u /* bits 30:23 */
 
 static inline u32 aa64_ldstp_post_pack(AA64LdStPPre f) {
   return ((f.opc & 3u) << 30) | AA64_LDSTP_POST_FAMILY_MATCH |
          ((f.V & 1u) << 26) | ((f.L & 1u) << 22) | ((f.imm7 & 0x7fu) << 15) |
          ((f.Rt2 & 0x1fu) << 10) | ((f.Rn & 0x1fu) << 5) | (f.Rt & 0x1fu);
 }
 
 static inline u32 aa64_stp64_post(u32 Rt, u32 Rt2, u32 Rn, i32 imm7_scaled) {
   return aa64_ldstp_post_pack((AA64LdStPPre){.opc = 2,
                                              .V = 0,
                                              .L = 0,
                                              .imm7 = (u32)imm7_scaled & 0x7fu,
                                              .Rt2 = Rt2,
                                              .Rn = Rn,
                                              .Rt = Rt});
 }
 static inline u32 aa64_ldp64_post(u32 Rt, u32 Rt2, u32 Rn, i32 imm7_scaled) {
   return aa64_ldstp_post_pack((AA64LdStPPre){.opc = 2,
                                              .V = 0,
                                              .L = 1,
                                              .imm7 = (u32)imm7_scaled & 0x7fu,
                                              .Rt2 = Rt2,
                                              .Rn = Rn,
                                              .Rt = Rt});
 }
 
 /* ====================================================================
  * Hint instructions (NOP / YIELD / WFE / WFI / SEV / SEVL)
  *   1101 0101 0000 0011 0010 CRm(4) op2(3) 11111
  *   31..16             15..12 11..8 7..5    4..0
  *
  * NOP encodes CRm=0, op2=0 → 0xD503201F.  The full hint family lives
  * inside the system-instruction space; we only expose NOP today since
  * that's the only slot the linker fills.
  * ==================================================================== */
 
 #define AA64_HINT_FAMILY_MATCH 0xD503201Fu
 #define AA64_HINT_FAMILY_MASK 0xFFFFF01Fu /* CRm + op2 vary */
 
 /* HINT #N with CRm=0: op2 selects the variant. */
 #define AA64_HINT_OP_NOP 0u   /* CRm=0, op2=0 */
 #define AA64_HINT_OP_YIELD 1u /* CRm=0, op2=1 */
 #define AA64_HINT_OP_WFE 2u   /* CRm=0, op2=2 */
 #define AA64_HINT_OP_WFI 3u   /* CRm=0, op2=3 */
 #define AA64_HINT_OP_SEV 4u   /* CRm=0, op2=4 */
 #define AA64_HINT_OP_SEVL 5u  /* CRm=0, op2=5 */
 
 typedef struct AA64Hint {
   u32 CRm, op2;
 } AA64Hint;
 
 static inline u32 aa64_hint_pack(AA64Hint f) {
   return AA64_HINT_FAMILY_MATCH | ((f.CRm & 0xfu) << 8) | ((f.op2 & 7u) << 5);
 }
 
 static inline u32 aa64_hint(u32 op2) {
   return aa64_hint_pack((AA64Hint){.CRm = 0, .op2 = op2});
 }
 
 static inline AA64Hint aa64_hint_unpack(u32 w) {
   AA64Hint f;
   f.CRm = (w >> 8) & 0xfu;
   f.op2 = (w >> 5) & 7u;
   return f;
 }
 
 static inline u32 aa64_nop(void) {
   return aa64_hint_pack((AA64Hint){.CRm = 0, .op2 = AA64_HINT_OP_NOP});
 }
 
 /* ====================================================================
  * Memory barriers (DMB / DSB / ISB / CLREX)
  *   1101 0101 0000 0011 0011 CRm(4) op2(3) 11111
  *   31..16             15..12 11..8 7..5    4..0
  *
  * Shared encoding family with HINT (which uses bits[15:12]=0010);
  * barriers use bits[15:12]=0011. op2 selects the specific instruction:
  *   CLREX=010  DSB=100  DMB=101  ISB=110
  * CRm is the option / domain (SY=15, ISH=11, NSH=7, OSH=3, ...).
  * ==================================================================== */
 
 #define AA64_BARRIER_FAMILY_MATCH 0xD503301Fu
 #define AA64_BARRIER_FAMILY_MASK 0xFFFFF01Fu /* CRm + op2 vary */
 
 #define AA64_BARRIER_OP2_CLREX 2u
 #define AA64_BARRIER_OP2_DSB 4u
 #define AA64_BARRIER_OP2_DMB 5u
 #define AA64_BARRIER_OP2_ISB 6u
 
 /* Common CRm option encodings (ARM ARM C5.1.42). */
 #define AA64_BARRIER_OPT_OSHLD 1u
 #define AA64_BARRIER_OPT_OSHST 2u
 #define AA64_BARRIER_OPT_OSH 3u
 #define AA64_BARRIER_OPT_NSHLD 5u
 #define AA64_BARRIER_OPT_NSHST 6u
 #define AA64_BARRIER_OPT_NSH 7u
 #define AA64_BARRIER_OPT_ISHLD 9u
 #define AA64_BARRIER_OPT_ISHST 10u
 #define AA64_BARRIER_OPT_ISH 11u
 #define AA64_BARRIER_OPT_LD 13u
 #define AA64_BARRIER_OPT_ST 14u
 #define AA64_BARRIER_OPT_SY 15u
 
 typedef struct AA64Barrier {
   u32 CRm, op2;
 } AA64Barrier;
 
 static inline u32 aa64_barrier_pack(AA64Barrier f) {
   return AA64_BARRIER_FAMILY_MATCH | ((f.CRm & 0xfu) << 8) |
          ((f.op2 & 7u) << 5);
 }
 
 static inline AA64Barrier aa64_barrier_unpack(u32 w) {
   AA64Barrier f;
   f.CRm = (w >> 8) & 0xfu;
   f.op2 = (w >> 5) & 7u;
   return f;
 }
 
 static inline u32 aa64_dmb(u32 opt) {
   return aa64_barrier_pack(
       (AA64Barrier){.CRm = opt, .op2 = AA64_BARRIER_OP2_DMB});
 }
 static inline u32 aa64_dsb(u32 opt) {
   return aa64_barrier_pack(
       (AA64Barrier){.CRm = opt, .op2 = AA64_BARRIER_OP2_DSB});
 }
 static inline u32 aa64_isb(u32 opt) {
   return aa64_barrier_pack(
       (AA64Barrier){.CRm = opt, .op2 = AA64_BARRIER_OP2_ISB});
 }
 static inline u32 aa64_clrex(u32 opt) {
   return aa64_barrier_pack(
       (AA64Barrier){.CRm = opt, .op2 = AA64_BARRIER_OP2_CLREX});
 }
 
 /* ====================================================================
  * Interrupt-mask (DAIF) system register access. Used by the IRQ-control
  * intrinsics; privileged at EL0. Only the encodings the backend emits live
  * here (they are not registered in the disassembler's mnemonic table).
  *   MRS Xt, DAIF       : 1101 0101 0011 1011 0100 0010 000 Rt -> 0xD53B4200|Rt
  *   MSR DAIF, Xt       : 1101 0101 0001 1011 0100 0010 000 Rt -> 0xD51B4200|Rt
  *   MSR DAIFSet, #imm4 : op1=011, op2=110 -> 0xD50340DF | (imm4 << 8)
  *   MSR DAIFClr, #imm4 : op1=011, op2=111 -> 0xD50340FF | (imm4 << 8)
  * imm4 = 0xF masks/unmasks D,A,I,F together. ==================== */
 #define AA64_DAIF_ALL 0xfu
 
 static inline u32 aa64_mrs_daif(u32 rt) { return 0xD53B4200u | (rt & 0x1fu); }
 static inline u32 aa64_msr_daif(u32 rt) { return 0xD51B4200u | (rt & 0x1fu); }
 static inline u32 aa64_msr_daifset(u32 imm4) {
   return 0xD50340DFu | ((imm4 & 0xfu) << 8);
 }
 static inline u32 aa64_msr_daifclr(u32 imm4) {
   return 0xD50340FFu | ((imm4 & 0xfu) << 8);
 }
 
 /* ====================================================================
  * Generic system-register move (MRS/MSR register form). A named system
  * register is the 15-bit selector op0:op1:CRn:CRm:op2 (op0's high bit is
  * fixed by the encoding, so only its low bit is a field).
  *   MRS Xt, <sysreg> : 1101 0101 0 0 1 op0lo op1 CRn CRm op2 Rt  (read,  L=1)
  *   MSR <sysreg>, Xt : 1101 0101 0 0 0 op0lo op1 CRn CRm op2 Rt  (write, L=0)
  * e.g. TPIDR_EL0 = (op0=3,op1=3,CRn=13,CRm=0,op2=2):
  *   MSR TPIDR_EL0, X0 -> 0xd51bd040 ; MRS X0, TPIDR_EL0 -> 0xd53bd040. */
 static inline u32 aa64_sysreg_move(int is_read, u32 op0, u32 op1, u32 crn,
                                    u32 crm, u32 op2, u32 rt) {
   return 0xd5000000u | (is_read ? (1u << 21) : 0u) | ((op0 & 3u) << 19) |
          ((op1 & 7u) << 16) | ((crn & 0xfu) << 12) | ((crm & 0xfu) << 8) |
          ((op2 & 7u) << 5) | (rt & 0x1fu);
 }
 
 /* System-register move encoding family: MRS (read, L=1) and MSR (write,
  * L=0). The disassembler matches these; the register selector op0:op1:CRn:
  * CRm:op2 and Rt are decoded from the word. op0's high bit is fixed (bit
  * 20), so the mask pins bits[31:20] and leaves op0lo/op1/CRn/CRm/op2/Rt. */
 #define AA64_MRS_MATCH 0xd5300000u
 #define AA64_MSR_MATCH 0xd5100000u
 #define AA64_SYSREG_MOVE_MASK 0xfff00000u
 
 /* Shared system-register name table (single source for the assembler's
  * name->selector parse and the disassembler's selector->name print). */
 typedef struct AA64SysRegName {
   const char* name;
   u8 op0, op1, crn, crm, op2;
 } AA64SysRegName;
 
 /* Resolve a system-register name (case-insensitive, length n) to its five
  * selector fields. Returns 1 on a hit, 0 otherwise. */
 int aa64_sysreg_by_name(const char* s, size_t n, u32* op0, u32* op1, u32* crn,
                         u32* crm, u32* op2);
 
 /* Reverse lookup: canonical lowercase name for a selector, or NULL when the
  * selector is not in the table (the caller prints the generic Sx_x_Cx_Cx_x
  * spelling instead). */
 const char* aa64_sysreg_name(u32 op0, u32 op1, u32 crn, u32 crm, u32 op2);
 
 /* ====================================================================
  * Load/store pair, signed-offset (STP / LDP, no pre/post-increment).
  *   opc(2) 101 V(1) 010 L(1) imm7 Rt2 Rn Rt          (bit 23 = 0)
  *
  * Mirrors the LDSTP_PRE format with bit 23 cleared; the field layout is
  * otherwise identical and the pack/unpack helpers above are reused for
  * pre/post/sign-offset via different family-match constants.  Codegen
  * emits both X (opc=10) and FP-D (opc=01, V=1) variants for callee-save
  * spill/reload (`stp x29,x30,[sp,#16]`, `stp d8,d9,[sp,#32]`). */
 
 #define AA64_LDSTP_SOFF_FAMILY_MATCH 0x29000000u
 #define AA64_LDSTP_SOFF_FAMILY_MASK 0x7FC00000u /* bits 30:23 (bit 23 = 0) */
 
 typedef AA64LdStPPre AA64LdStPSOff;
 
 static inline u32 aa64_ldstp_soff_pack(AA64LdStPSOff f) {
   return ((f.opc & 3u) << 30) | AA64_LDSTP_SOFF_FAMILY_MATCH |
          ((f.V & 1u) << 26) | ((f.L & 1u) << 22) | ((f.imm7 & 0x7fu) << 15) |
          ((f.Rt2 & 0x1fu) << 10) | ((f.Rn & 0x1fu) << 5) | (f.Rt & 0x1fu);
 }
 
 static inline AA64LdStPSOff aa64_ldstp_soff_unpack(u32 w) {
   AA64LdStPSOff f;
   f.opc = (w >> 30) & 3u;
   f.V = (w >> 26) & 1u;
   f.L = (w >> 22) & 1u;
   f.imm7 = (w >> 15) & 0x7fu;
   f.Rt2 = (w >> 10) & 0x1fu;
   f.Rn = (w >> 5) & 0x1fu;
   f.Rt = w & 0x1fu;
   return f;
 }
 
 /* 64-bit integer STP/LDP, signed offset (no writeback). imm7_scaled is
  * byte_offset / 8. Used for the prologue/epilogue frame record and callee-save
  * pairs, which address off a fixed base (x17 / fp). */
 static inline u32 aa64_stp64_soff(u32 Rt, u32 Rt2, u32 Rn, i32 imm7_scaled) {
   return aa64_ldstp_soff_pack((AA64LdStPSOff){.opc = 2,
                                               .V = 0,
                                               .L = 0,
                                               .imm7 = (u32)imm7_scaled & 0x7fu,
                                               .Rt2 = Rt2,
                                               .Rn = Rn,
                                               .Rt = Rt});
 }
 static inline u32 aa64_ldp64_soff(u32 Rt, u32 Rt2, u32 Rn, i32 imm7_scaled) {
   return aa64_ldstp_soff_pack((AA64LdStPSOff){.opc = 2,
                                               .V = 0,
                                               .L = 1,
                                               .imm7 = (u32)imm7_scaled & 0x7fu,
                                               .Rt2 = Rt2,
                                               .Rn = Rn,
                                               .Rt = Rt});
 }
 
 /* ====================================================================
  * Load/store, unscaled 9-bit signed offset (LDUR / STUR, V=0 and V=1).
  *   size(2) 111 V(1) 00 opc(2) 0 imm9(9) 00 Rn(5) Rt(5)
  *   31..30  29..27 26  25..24 23..22 21  20..12  11..10 9..5 4..0
  *
  * size: 00=B, 01=H, 10=W, 11=X (V=0) — D when V=1 selects FP/SIMD.
  * opc: 00=STR, 01=LDR (sign-extension variants set opc bit 1 for the
  *      smaller widths; not used by codegen today). */
 
 #define AA64_LDST_SIMM9_FAMILY_MATCH 0x38000000u
 /* bits 29:27 (=111) + bits 25:24 (=00) + bits 11:10 (=00). size, V, opc,
  * imm9, Rn, Rt all vary; bit 21 is fixed 0 for this variant. */
 #define AA64_LDST_SIMM9_FAMILY_MASK 0x3B200C00u
 
 typedef struct AA64LdStSimm9 {
   u32 size, V, opc, imm9, Rn, Rt;
 } AA64LdStSimm9;
 
 static inline u32 aa64_ldst_simm9_pack(AA64LdStSimm9 f) {
   return ((f.size & 3u) << 30) | AA64_LDST_SIMM9_FAMILY_MATCH |
          ((f.V & 1u) << 26) | ((f.opc & 3u) << 22) | ((f.imm9 & 0x1ffu) << 12) |
          ((f.Rn & 0x1fu) << 5) | (f.Rt & 0x1fu);
 }
 
 static inline AA64LdStSimm9 aa64_ldst_simm9_unpack(u32 w) {
   AA64LdStSimm9 f;
   f.size = (w >> 30) & 3u;
   f.V = (w >> 26) & 1u;
   f.opc = (w >> 22) & 3u;
   f.imm9 = (w >> 12) & 0x1ffu;
   f.Rn = (w >> 5) & 0x1fu;
   f.Rt = w & 0x1fu;
   return f;
 }
 
 /* ====================================================================
  * Load/store, register offset (LDR/STR Rt,[Xn,Rm{,extend{#s}}]).
  *   size(2) 111 V(1) 00 opc(2) 1 Rm(5) option(3) S(1) 10 Rn(5) Rt(5)
  *   31..30  29..27 26 25..24 23..22 21 20..16 15..13  12  11..10 9..5 4..0
  *
  * option selects the index extend: 010=UXTW, 011=LSL/UXTX, 110=SXTW,
  * 111=SXTX. S=1 scales the index by the access size (log2 = size); S=0
  * leaves it unscaled. opc/size match the uimm12 form. */
 
 #define AA64_LDST_REGOFF_FAMILY_MATCH 0x38200800u
 /* bits 29:27 (=111), 25:24 (=00), 21 (=1), 11:10 (=10). */
 #define AA64_LDST_REGOFF_FAMILY_MASK 0x3B200C00u
 
 /* Index-extend option encodings. */
 #define AA64_LDST_OPTION_UXTW 2u
 #define AA64_LDST_OPTION_LSL 3u /* a.k.a. UXTX for 64-bit index */
 #define AA64_LDST_OPTION_SXTW 6u
 #define AA64_LDST_OPTION_SXTX 7u
 
 typedef struct AA64LdStRegOff {
   u32 size, V, opc, Rm, option, S, Rn, Rt;
 } AA64LdStRegOff;
 
 static inline u32 aa64_ldst_regoff_pack(AA64LdStRegOff f) {
   return ((f.size & 3u) << 30) | AA64_LDST_REGOFF_FAMILY_MATCH |
          ((f.V & 1u) << 26) | ((f.opc & 3u) << 22) | ((f.Rm & 0x1fu) << 16) |
          ((f.option & 7u) << 13) | ((f.S & 1u) << 12) | ((f.Rn & 0x1fu) << 5) |
          (f.Rt & 0x1fu);
 }
 
 static inline AA64LdStRegOff aa64_ldst_regoff_unpack(u32 w) {
   AA64LdStRegOff f;
   f.size = (w >> 30) & 3u;
   f.V = (w >> 26) & 1u;
   f.opc = (w >> 22) & 3u;
   f.Rm = (w >> 16) & 0x1fu;
   f.option = (w >> 13) & 7u;
   f.S = (w >> 12) & 1u;
   f.Rn = (w >> 5) & 0x1fu;
   f.Rt = w & 0x1fu;
   return f;
 }
 
 /* ====================================================================
  * Load/store, immediate pre/post-index (writeback).
  *   size(2) 111 V(1) 00 opc(2) 0 imm9(9) idx(2) Rn(5) Rt(5)
  *   31..30  29..27 26 25..24 23..22 21 20..12 11..10 9..5 4..0
  *
  * idx (bits[11:10]) selects: 00=unscaled (LDUR, no writeback — see the
  * SIMM9 helpers above), 01=post-index, 11=pre-index. imm9 is the
  * unscaled signed byte offset (-256..255). */
 
 #define AA64_LDST_IDX_POST 1u
 #define AA64_LDST_IDX_PRE 3u
 
 typedef struct AA64LdStWBack {
   u32 size, V, opc, imm9, idx, Rn, Rt;
 } AA64LdStWBack;
 
 static inline u32 aa64_ldst_wback_pack(AA64LdStWBack f) {
   return ((f.size & 3u) << 30) | AA64_LDST_SIMM9_FAMILY_MATCH |
          ((f.V & 1u) << 26) | ((f.opc & 3u) << 22) | ((f.imm9 & 0x1ffu) << 12) |
          ((f.idx & 3u) << 10) | ((f.Rn & 0x1fu) << 5) | (f.Rt & 0x1fu);
 }
 
 static inline AA64LdStWBack aa64_ldst_wback_unpack(u32 w) {
   AA64LdStWBack f;
   f.size = (w >> 30) & 3u;
   f.V = (w >> 26) & 1u;
   f.opc = (w >> 22) & 3u;
   f.imm9 = (w >> 12) & 0x1ffu;
   f.idx = (w >> 10) & 3u;
   f.Rn = (w >> 5) & 0x1fu;
   f.Rt = w & 0x1fu;
   return f;
 }
 
 /* ====================================================================
  * Load/store exclusive (LDXR/STXR + acquire/release variants).
  *   size(2) 001000 o2(1) L(1) o1(1) Rs(5) o0(1) Rt2(5) Rn(5) Rt(5)
  *   31..30  29..24  23    22   21   20..16 15   14..10 9..5  4..0
  *
  * size: 00=byte,01=half,10=word,11=dword.  o1=0 for the LDXR/STXR
  * single-register family (CAS sets o1=1 via the CAS pack below).
  *   LDXR:  L=1 o0=0 o2=0      STXR:  L=0 o0=0 o2=0
  *   LDAXR: L=1 o0=1 o2=0      STLXR: L=0 o0=1 o2=0
  *   LDAR:  L=1 o0=1 o2=1      STLR:  L=0 o0=1 o2=1
  * For LDXR/LDAXR/LDAR/STLR, Rs and Rt2 are unused (encode 11111). */
 
 #define AA64_LDSTEX_FAMILY_MATCH 0x08000000u
 /* bits 29:24 (=001000). */
 #define AA64_LDSTEX_FAMILY_MASK 0x3F000000u
 
 typedef struct AA64LdStEx {
   u32 size, o2, L, o1, Rs, o0, Rt2, Rn, Rt;
 } AA64LdStEx;
 
 static inline u32 aa64_ldstex_pack(AA64LdStEx f) {
   return ((f.size & 3u) << 30) | AA64_LDSTEX_FAMILY_MATCH |
          ((f.o2 & 1u) << 23) | ((f.L & 1u) << 22) | ((f.o1 & 1u) << 21) |
          ((f.Rs & 0x1fu) << 16) | ((f.o0 & 1u) << 15) |
          ((f.Rt2 & 0x1fu) << 10) | ((f.Rn & 0x1fu) << 5) | (f.Rt & 0x1fu);
 }
 
 static inline AA64LdStEx aa64_ldstex_unpack(u32 w) {
   AA64LdStEx f;
   f.size = (w >> 30) & 3u;
   f.o2 = (w >> 23) & 1u;
   f.L = (w >> 22) & 1u;
   f.o1 = (w >> 21) & 1u;
   f.Rs = (w >> 16) & 0x1fu;
   f.o0 = (w >> 15) & 1u;
   f.Rt2 = (w >> 10) & 0x1fu;
   f.Rn = (w >> 5) & 0x1fu;
   f.Rt = w & 0x1fu;
   return f;
 }
 
 /* ====================================================================
  * Compare and swap (CAS / CASA / CASL / CASAL + b/h variants, LSE).
  *   size(2) 001000 1 L(1) 1 Rs(5) o0(1) 11111 Rn(5) Rt(5)
  *   31..30  29..23 . 22  . 20..16 15    14..10 9..5  4..0
  *
  *   CAS:  L=0 o0=0    CASA:  L=1 o0=0
  *   CASL: L=0 o0=1    CASAL: L=1 o0=1
  * Rt2 (bits[14:10]) is fixed at 11111. */
 
 #define AA64_CAS_FAMILY_MATCH 0x08a07c00u
 /* bits 29:24 (=001000), 23 (=1), 21 (=1), 14:10 (=11111). */
 #define AA64_CAS_FAMILY_MASK 0x3Fa0fc00u
 
 typedef struct AA64Cas {
   u32 size, L, Rs, o0, Rn, Rt;
 } AA64Cas;
 
 static inline u32 aa64_cas_pack(AA64Cas f) {
   return ((f.size & 3u) << 30) | AA64_CAS_FAMILY_MATCH | ((f.L & 1u) << 22) |
          ((f.Rs & 0x1fu) << 16) | ((f.o0 & 1u) << 15) | ((f.Rn & 0x1fu) << 5) |
          (f.Rt & 0x1fu);
 }
 
 static inline AA64Cas aa64_cas_unpack(u32 w) {
   AA64Cas f;
   f.size = (w >> 30) & 3u;
   f.L = (w >> 22) & 1u;
   f.Rs = (w >> 16) & 0x1fu;
   f.o0 = (w >> 15) & 1u;
   f.Rn = (w >> 5) & 0x1fu;
   f.Rt = w & 0x1fu;
   return f;
 }
 
 /* ====================================================================
  * LSE atomic memory operations (SWP / LDADD / LDCLR / LDEOR / LDSET +
  * acquire/release variants and b/h widths).
  *   size(2) 111 V(1) 00 A(1) R(1) 1 Rs(5) o3(1) opc(3) 00 Rn(5) Rt(5)
  *   31..30  29..27 26 25..24 23  22  21 20..16 15   14..12 11..10 9..5 4..0
  *
  * A=acquire (a-suffix), R=release (l-suffix).  o3=1 selects SWP (opc=000);
  * o3=0 with opc in {000=LDADD,001=LDCLR,010=LDEOR,011=LDSET}. */
 
 #define AA64_LSE_ATOMIC_FAMILY_MATCH 0x38200000u
 /* bits 29:27 (=111), 25:24 (=00), 21 (=1), 11:10 (=00). */
 #define AA64_LSE_ATOMIC_FAMILY_MASK 0x3B200C00u
 
 #define AA64_LSE_OPC_LDADD 0u
 #define AA64_LSE_OPC_LDCLR 1u
 #define AA64_LSE_OPC_LDEOR 2u
 #define AA64_LSE_OPC_LDSET 3u
 #define AA64_LSE_OPC_SWP 0u /* paired with o3=1 */
 
 typedef struct AA64LseAtomic {
   u32 size, A, R, Rs, o3, opc, Rn, Rt;
 } AA64LseAtomic;
 
 static inline u32 aa64_lse_atomic_pack(AA64LseAtomic f) {
   return ((f.size & 3u) << 30) | AA64_LSE_ATOMIC_FAMILY_MATCH |
          ((f.A & 1u) << 23) | ((f.R & 1u) << 22) | ((f.Rs & 0x1fu) << 16) |
          ((f.o3 & 1u) << 15) | ((f.opc & 7u) << 12) | ((f.Rn & 0x1fu) << 5) |
          (f.Rt & 0x1fu);
 }
 
 static inline AA64LseAtomic aa64_lse_atomic_unpack(u32 w) {
   AA64LseAtomic f;
   f.size = (w >> 30) & 3u;
   f.A = (w >> 23) & 1u;
   f.R = (w >> 22) & 1u;
   f.Rs = (w >> 16) & 0x1fu;
   f.o3 = (w >> 15) & 1u;
   f.opc = (w >> 12) & 7u;
   f.Rn = (w >> 5) & 0x1fu;
   f.Rt = w & 0x1fu;
   return f;
 }
 
 /* ====================================================================
  * Unconditional branch (immediate) — B / BL
  *   op(1) 00101 imm26(26)
  *   31    30..26 25..0
  *
  * op=0 → B, op=1 → BL.  imm26 is a signed 26-bit word displacement
  * (multiply by 4 to get byte offset).  Codegen emits with imm26=0 paired
  * with a JUMP26 / CALL26 relocation. */
 
 #define AA64_BR_IMM_FAMILY_MATCH 0x14000000u
 #define AA64_BR_IMM_FAMILY_MASK 0x7C000000u /* bits 30:26 (=00101) */
 
 typedef struct AA64BrImm {
   u32 op, imm26;
 } AA64BrImm;
 
 static inline u32 aa64_brimm_pack(AA64BrImm f) {
   return ((f.op & 1u) << 31) | AA64_BR_IMM_FAMILY_MATCH |
          (f.imm26 & 0x3ffffffu);
 }
 
 static inline AA64BrImm aa64_brimm_unpack(u32 w) {
   AA64BrImm f;
   f.op = (w >> 31) & 1u;
   f.imm26 = w & 0x3ffffffu;
   return f;
 }
 
 static inline u32 aa64_b(u32 imm26) {
   return aa64_brimm_pack((AA64BrImm){.op = 0, .imm26 = imm26});
 }
 static inline u32 aa64_bl(u32 imm26) {
   return aa64_brimm_pack((AA64BrImm){.op = 1, .imm26 = imm26});
 }
 
 /* ====================================================================
  * Conditional branch (immediate) — B.cond
  *   0101 0100 imm19(19) 0 cond(4)
  *   31..24    23..5     4 3..0
  *
  * imm19 is a signed 19-bit word displacement; cond is the 4-bit ARM
  * condition code (EQ=0, NE=1, ...). */
 
 #define AA64_BR_COND_FAMILY_MATCH 0x54000000u
 #define AA64_BR_COND_FAMILY_MASK              \
   0xFF000010u /* bits 31:24 fixed + bit 4 = 0 \
                */
 
 typedef struct AA64BrCond {
   u32 imm19, cond;
 } AA64BrCond;
 
 static inline u32 aa64_brcond_pack(AA64BrCond f) {
   return AA64_BR_COND_FAMILY_MATCH | ((f.imm19 & 0x7ffffu) << 5) |
          (f.cond & 0xfu);
 }
 
 static inline AA64BrCond aa64_brcond_unpack(u32 w) {
   AA64BrCond f;
   f.imm19 = (w >> 5) & 0x7ffffu;
   f.cond = w & 0xfu;
   return f;
 }
 
 /* ====================================================================
  * Compare-and-branch — CBZ / CBNZ
  *   sf 011010 op(1) imm19(19) Rt(5)
  *   31 30..25 24    23..5     4..0
  *
  * op=0 → CBZ (branch if zero), op=1 → CBNZ. */
 
 #define AA64_CB_FAMILY_MATCH 0x34000000u
 #define AA64_CB_FAMILY_MASK 0x7E000000u /* bits 30:25 (=011010) */
 
 typedef struct AA64CB {
   u32 sf, op, imm19, Rt;
 } AA64CB;
 
 static inline u32 aa64_cb_pack(AA64CB f) {
   return ((f.sf & 1u) << 31) | AA64_CB_FAMILY_MATCH | ((f.op & 1u) << 24) |
          ((f.imm19 & 0x7ffffu) << 5) | (f.Rt & 0x1fu);
 }
 
 static inline AA64CB aa64_cb_unpack(u32 w) {
   AA64CB f;
   f.sf = (w >> 31) & 1u;
   f.op = (w >> 24) & 1u;
   f.imm19 = (w >> 5) & 0x7ffffu;
   f.Rt = w & 0x1fu;
   return f;
 }
 
 static inline u32 aa64_cbz(u32 sf, u32 Rt, u32 imm19) {
   return aa64_cb_pack((AA64CB){.sf = sf, .op = 0, .imm19 = imm19, .Rt = Rt});
 }
 static inline u32 aa64_cbnz_imm(u32 sf, u32 Rt, u32 imm19) {
   return aa64_cb_pack((AA64CB){.sf = sf, .op = 1, .imm19 = imm19, .Rt = Rt});
 }
 
 /* ====================================================================
  * Exception generation — BRK / SVC / HVC / SMC / HLT / UDF aliases.
  *   1101 0100 opc(3) imm16(16) op2(3) LL(2)
  *   31..24    23..21 20..5     4..2   1..0
  *
  * SVC: opc=000, LL=01.  BRK: opc=001, LL=00.  HVC/SMC/HLT/...: other
  * combos.  Codegen emits BRK today. */
 
 #define AA64_EXCEPT_FAMILY_MATCH 0xD4000000u
 #define AA64_EXCEPT_FAMILY_MASK 0xFF000000u /* bits 31:24 */
 
 typedef struct AA64Except {
   u32 opc, imm16, op2, LL;
 } AA64Except;
 
 static inline u32 aa64_except_pack(AA64Except f) {
   return AA64_EXCEPT_FAMILY_MATCH | ((f.opc & 7u) << 21) |
          ((f.imm16 & 0xffffu) << 5) | ((f.op2 & 7u) << 2) | (f.LL & 3u);
 }
 
 static inline AA64Except aa64_except_unpack(u32 w) {
   AA64Except f;
   f.opc = (w >> 21) & 7u;
   f.imm16 = (w >> 5) & 0xffffu;
   f.op2 = (w >> 2) & 7u;
   f.LL = w & 3u;
   return f;
 }
 
 static inline u32 aa64_brk(u32 imm16) {
   return aa64_except_pack(
       (AA64Except){.opc = 1, .imm16 = imm16, .op2 = 0, .LL = 0});
 }
 static inline u32 aa64_svc(u32 imm16) {
   return aa64_except_pack(
       (AA64Except){.opc = 0, .imm16 = imm16, .op2 = 0, .LL = 1});
 }
 
 /* ====================================================================
  * Disassembler descriptor table.
  * ==================================================================== */
 
 typedef struct AA64InsnDesc {
   Slice mnemonic;
   u32 match;
   u32 mask;
   u8 fmt;   /* AA64Format */
   u8 flags; /* AA64_ASMFL_* */
   u8 pad[2];
 } AA64InsnDesc;
 
 extern const AA64InsnDesc aa64_insn_table[];
 extern const u32 aa64_insn_table_n;
 
 /* Linear-scan lookup. Returns the matching descriptor or NULL. First
  * match wins; ordering in aa64_insn_table.c puts more-specific entries
  * before broader ones (so aliases like MOV/MUL/NEG win over their
  * canonical ORR/MADD/SUB forms). */
 const AA64InsnDesc* aa64_disasm_find(u32 word);
 
 /* ====================================================================
  * Operand print / parse — one entry per AA64Format.
  *
  * aa64_print_operands renders the operand text (everything after the
  * mnemonic) for `word` into `sb`, using `desc->fmt` to dispatch.
  * Mnemonic itself is in `desc->mnemonic`; the caller writes it before
  * calling this helper.  `vaddr` is the instruction's virtual address
  * for PC-relative formats; pass 0 if not known.
  *
  * aa64_parse_operands is the dual: read the operand grammar for the
  * format from `tok` (opaque to phase 2 — declared but unimplemented)
  * and fill `fields_out` (a pointer to the format's field struct).
  * Phase 3 wires `tok` up; for now the function is a forward declaration
  * the assembler can resolve once it's in place. */
 
 struct AA64AsmTok; /* opaque, defined by the phase-3 asm parser */
 
 void aa64_print_operands(StrBuf* sb, const AA64InsnDesc* desc, u32 word,
                          u64 vaddr);
 
 /* If `word` is an SBFM/UBFM that has a preferred shift-alias disassembly,
  * return its mnemonic ("lsl"/"lsr"/"asr") and write the shift amount to
  * *shift; return NULL otherwise. Shared by the disassembler's mnemonic and
  * operand printers so the alias decision lives in one place. */
 const char* aa64_bitfield_shift_alias(u32 word, u32* shift);
 
 /* Preferred SBFM/UBFM extension aliases: sxtb/sxth/sxtw/uxtb/uxth.
  * Returns NULL when the bitfield does not match one of those forms. */
 const char* aa64_bitfield_extend_alias(u32 word);
 
 /* Preferred SBFM/UBFM extract aliases: sbfx/ubfx. Writes the least-significant
  * source bit and extracted width when an alias is available. */
 const char* aa64_bitfield_extract_alias(u32 word, u32* lsb, u32* width);
 
 /* Returns 1 on success, 0 on parse error.  Phase 2 stub returns 0 for
  * every format; phase 3 fills in the bodies. */
 int aa64_parse_operands(struct AA64AsmTok* tok, const AA64InsnDesc* desc,
                         void* fields_out);
 
 #endif