package core:rexcode/isa/arm64

Source

Address_Mode :: enum u8 {
	OFFSET,         // [Xn, #imm]   (imm may be 0)
	PRE_INDEXED,    // [Xn, #imm]!
	POST_INDEXED,   // [Xn], #imm
	REG_OFFSET,     // [Xn, Xm{, LSL #s}]
	EXT_REG_OFFSET, // [Xn, Wm, SXTW|UXTW|SXTX #s]
	LITERAL,        // PC-rel target (LDR literal)
}

Clobber :: struct {
	written:      Operand_Set,
	// operand slots whose register/SIMD reg is written
	read:         Operand_Set,
	// operand slots whose register / mem-base is read
	implicit_wr:  Clobber_Regs,
	// implicit reg writes (LR on BL/BLR)
	implicit_rd:  Clobber_Regs,
	// implicit reg reads (LR on RET, SP on PAC*SP)
	nzcv_wr:      NZCV_Flags,
	// condition flags written (ADDS/SUBS/ANDS, CMP, FCMP, CCMP...)
	nzcv_undef:   NZCV_Flags,
	// condition flags left UNKNOWN — rare in A64, usually empty
	nzcv_rd:      NZCV_Flags,
	// condition flags read (B.cond, CSEL, ADC/SBC, CCMP...)
	fpsr_wr:      FPSR_Flags,
	// FP cumulative exception/saturation flags this op may raise
	reads_fpcr:   bool,
	// consumes the rounding mode / FP control from FPCR
	writes_mem:   bool,
	reads_mem:    bool,
	side_effects: Side_Effects,
}

Clobber_Reg :: enum u8 {
	LR,  // x30, implicit link written by BL/BLR, implicitly read by RET
	SP,  // sp,  implicit base on PACIASP/AUTIASP (and stack-relative forms)
	X16, // implicit modifier register for PAC*1716 / AUT*1716
	X17, // implicit pointer register (read-modify-write) for PAC*1716 / AUT*1716
}

Clobber_Regs :: distinct bit_set[Clobber_Reg; u8]

Cond :: enum u8 {
	EQ = 0x0, 
	NE = 0x1, 
	CS = 0x2, // unsigned higher or same (alias HS)
	CC = 0x3, // unsigned lower (alias LO)
	MI = 0x4, 
	PL = 0x5, 
	VS = 0x6, 
	VC = 0x7, 
	HI = 0x8, 
	LS = 0x9, 
	GE = 0xA, 
	LT = 0xB, 
	GT = 0xC, 
	LE = 0xD, 
	AL = 0xE, 
	NV = 0xF, 
}

Decode_Entry :: struct #packed {
	mnemonic: Mnemonic,
	// 2
	ops:      [5]Operand_Type,
	// 4
	enc:      [5]Operand_Encoding,
	// 4
	bits:     u32,
	// 4
	mask:     u32,
	// 4
	feature:  Feature,
	// 1
	flags:    Encoding_Flags,
}

Decode_Index :: struct #packed {
	start: u16,
	count: u16,
}

Encode_Run :: struct {
	start: u32,
	count: u32,
}

Encoding :: struct #packed {
	mnemonic: Mnemonic,
	// 2
	ops:      [5]Operand_Type,
	// 4
	enc:      [5]Operand_Encoding,
	// 4
	bits:     u32,
	// 4
	mask:     u32,
	// 4
	feature:  Feature,
	// 1
	flags:    Encoding_Flags,
}

Encoding_Flags :: distinct bit_field u8 {
	branch:         bool | 1,
	cond_branch:    bool | 1,
	writes_pc:      bool | 1,
	sets_flags:     bool | 1,
	is_64:          bool | 1,
	explicit_count: u8 | 3,
}

Endianness :: enum u8 {
	LITTLE = 0, 
	BIG    = 1, 
}

Error :: rexcode_isa.Error

Error_Code :: rexcode_isa.Error_Code

Extend :: enum u8 {
	UXTB = 0, 
	UXTH = 1, 
	UXTW = 2, 
	UXTX = 3, 
	SXTB = 4, 
	SXTH = 5, 
	SXTW = 6, 
	SXTX = 7, 
}

Extended_Reg :: struct #packed {
	reg:    Register,
	// 4
	extend: Extend,
	// 1
	amount: u8,
}

FPSR_Flag :: enum u8 {
	IOC, // invalid operation
	DZC, // divide by zero
	OFC, // overflow
	UFC, // underflow
	IXC, // inexact
	IDC, // input denormal
	QC,  // cumulative saturation (Advanced SIMD saturating ops)
}

FPSR_Flags :: distinct bit_set[FPSR_Flag; u8]

Feature :: enum u8 {
	BASE,   // AArch64 base integer ISA
	FP,     // scalar FP (FPSCR-using; FADD/FCMP/FCVT/etc.)
	NEON,   // Advanced SIMD vector ops
	CRYPTO, // AES, SHA1, SHA2, SHA3, SM3, SM4
	CRC32,  // CRC32B/H/W/X + CRC32CB/H/W/X
	LSE,    // Large System Extensions (atomic LDADD/LDCLR/...)
	LSE2,   // single-copy-atomicity load/store
	FP16,   // half-precision FP arithmetic
	BF16,   // BFloat16
	DOT,    // SDOT/UDOT integer dot product
	PAC,    // Pointer Authentication
	BTI,    // Branch Target Indicator
	MTE,    // Memory Tagging
	SVE,    // Scalable Vector Extension
	SVE2, 
	SME,    // Scalable Matrix Extension
	AMX,    // Apple Matrix Extension (undocumented A13+/M1+ coprocessor)
}

Instruction :: struct #align (64) {
	ops:           [5]Operand `fmt:"v,operand_count"`,
	// 5 * size_of(Operand) = 55
	mnemonic:      Mnemonic,
	// 2
	operand_count: u8,
	// 1
	flags:         Instruction_Flags,
	// 1
	length:        u8,
	// 55 is odd, so mnemonic's alignment costs a byte here; 3 more reach 64.
	_:             [3]u8,
}

Instruction_Flags :: distinct bit_field u8 {
	_: u8 | 8,
}

Instruction_Info :: struct {
	offset:       u32,
	decode_entry: u16,
	_:            u16,
}

Label_Definition :: rexcode_isa.Label_Definition

Label_Map :: rexcode_isa.Label_Map

Label_Names :: map[rexcode_isa.Label_Offset]string

Label_Offset :: rexcode_isa.Label_Offset

Memory :: distinct bit_field u64 {
	base:   Register | 16,
	index:  Register | 16,
	disp:   i32 | 23,
	extend: Extend | 3,
	shift:  u8 | 3,
	mode:   Address_Mode | 3,
}

Mnemonic :: enum u16 {
	INVALID        = 0, 
	ADD, 
	ADDS, 
	SUB, 
	SUBS,               // optional LSL #12 carried in shift field
	MOVZ, 
	MOVN, 
	MOVK,               // 16-bit imm + 2-bit hw
	ADR, 
	ADRP,               // PC-relative address
	AND, 
	ANDS, 
	ORR, 
	EOR, 
	BIC, 
	BICS, 
	ORN, 
	EON, 
	LSL, 
	LSR, 
	ASR, 
	ROR,                // register and immediate forms both
	UDIV, 
	SDIV, 
	MADD, 
	MSUB,               // 64x64+64 -> 64 (or 32 variant)
	SMADDL, 
	SMSUBL, 
	UMADDL, 
	UMSUBL,             // 32x32+64 -> 64
	SMULH, 
	UMULH,              // 64x64 -> high 64
	CLZ, 
	CLS, 
	RBIT, 
	REV, 
	REV16, 
	REV32, 
	CSEL, 
	CSINC, 
	CSINV, 
	CSNEG, 
	CCMP, 
	CCMN, 
	// Aliases of the above with the condition inverted; every assembler both
	// accepts and prefers these spellings.
	CSET, 
	CSETM,              // CSINC/CSINV with Rn = Rm = ZR
	CINC, 
	CINV, 
	CNEG,               // CSINC/CSINV/CSNEG with Rn = Rm
	EXTR, 
	B, 
	BL,                 // 26-bit PC-rel
	BR, 
	BLR, 
	RET,                // register indirect
	// One member per condition, the way an assembler spells them and the way
	// x86 does its Jcc. The condition is not an operand: it is four bits of
	// the opcode, and splitting it lets each entry record the flags it
	// actually reads -- b.eq consults Z alone, b.le consults N, Z and V --
	// where a single B_COND had to claim all four for every condition.
	B_EQ, 
	B_NE, 
	B_CS, 
	B_CC,               // B.cond -- 19-bit PC-rel
	B_MI, 
	B_PL, 
	B_VS, 
	B_VC, 
	B_HI, 
	B_LS, 
	B_GE, 
	B_LT, 
	B_GT, 
	B_LE, 
	B_AL, 
	B_NV, 
	CBZ, 
	CBNZ,               // 19-bit PC-rel + Rt
	TBZ, 
	TBNZ,               // 14-bit PC-rel + bit position
	// Plain (unsigned offset / signed unscaled / pre / post)
	LDR, 
	STR,                // X/W variants (matched by reg width)
	LDRB, 
	STRB, 
	LDRSB, 
	LDRH, 
	STRH, 
	LDRSH, 
	LDRSW, 
	// Pair
	LDP, 
	STP, 
	LDPSW, 
	// Acquire / release
	LDAR, 
	STLR, 
	LDARB, 
	STLRB, 
	LDARH, 
	STLRH, 
	// Exclusive (load-linked / store-conditional)
	LDXR, 
	STXR, 
	LDAXR, 
	STLXR, 
	NOP, 
	YIELD, 
	WFE, 
	WFI, 
	SEV, 
	SEVL, 
	HINT, 
	MRS, 
	MSR, 
	ISB, 
	DSB, 
	DMB, 
	SVC, 
	HVC, 
	SMC, 
	BRK, 
	HLT, 
	ERET, 
	FMOV,               // reg-reg / imm / between int/FP
	FABS, 
	FNEG, 
	FSQRT, 
	FADD, 
	FSUB, 
	FMUL, 
	FDIV, 
	FNMUL, 
	FMADD, 
	FMSUB, 
	FNMADD, 
	FNMSUB, 
	FCMP, 
	FCMPE, 
	FCSEL, 
	FMAX, 
	FMIN, 
	FMAXNM, 
	FMINNM, 
	FCVT,               // between single/double/half
	SCVTF, 
	UCVTF, 
	FCVTZS, 
	FCVTZU, 
	FCVTAS, 
	FCVTAU, 
	FCVTNS, 
	FCVTNU, 
	FCVTPS, 
	FCVTPU, 
	FCVTMS, 
	FCVTMU, 
	FRINTA, 
	FRINTI, 
	FRINTM, 
	FRINTN, 
	FRINTP, 
	FRINTX, 
	FRINTZ, 
	// -------------------------------------------------------------------------
	// Logical immediate (bitmask-encoded; N:imms:immr)
	// -------------------------------------------------------------------------
	TST,                // ANDS with Rd=ZR
	// -------------------------------------------------------------------------
	// Additional load/store addressing modes
	// -------------------------------------------------------------------------
	LDUR, 
	STUR, 
	LDURB, 
	STURB, 
	LDURSB, 
	LDURH, 
	STURH, 
	LDURSH, 
	LDURSW, 
	LDNP, 
	STNP,               // non-temporal pair
	LDXP, 
	STXP, 
	LDAXP, 
	STLXP,              // exclusive pair
	LDXRB, 
	STXRB, 
	LDAXRB, 
	STLXRB,             // exclusive byte
	LDXRH, 
	STXRH, 
	LDAXRH, 
	STLXRH,             // exclusive halfword
	LDAPR, 
	LDAPRB, 
	LDAPRH,             // load-acquire RCpc
	// -------------------------------------------------------------------------
	// LSE atomics (8 ops x 4 acq/rel x 2 width = 64 forms, named by op only;
	// size and acq/rel encoded in the bits + flags)
	// -------------------------------------------------------------------------
	LDADD, 
	LDADDA, 
	LDADDL, 
	LDADDAL, 
	LDCLR, 
	LDCLRA, 
	LDCLRL, 
	LDCLRAL, 
	LDEOR, 
	LDEORA, 
	LDEORL, 
	LDEORAL, 
	LDSET, 
	LDSETA, 
	LDSETL, 
	LDSETAL, 
	LDSMAX, 
	LDSMAXA, 
	LDSMAXL, 
	LDSMAXAL, 
	LDSMIN, 
	LDSMINA, 
	LDSMINL, 
	LDSMINAL, 
	LDUMAX, 
	LDUMAXA, 
	LDUMAXL, 
	LDUMAXAL, 
	LDUMIN, 
	LDUMINA, 
	LDUMINL, 
	LDUMINAL, 
	SWP, 
	SWPA, 
	SWPL, 
	SWPAL, 
	CAS, 
	CASA, 
	CASL, 
	CASAL,              // 32/64
	CASB, 
	CASAB, 
	CASLB, 
	CASALB,             // byte
	CASH, 
	CASAH, 
	CASLH, 
	CASALH,             // half
	CASP, 
	CASPA, 
	CASPL, 
	CASPAL,             // pair (W,W)/(X,X)
	// -------------------------------------------------------------------------
	// Pointer Authentication (PAC v8.3-A)
	// -------------------------------------------------------------------------
	PACIA, 
	PACIB, 
	PACDA, 
	PACDB, 
	PACIZA, 
	PACIZB, 
	PACDZA, 
	PACDZB,             // implicit-zero variants
	AUTIA, 
	AUTIB, 
	AUTDA, 
	AUTDB, 
	AUTIZA, 
	AUTIZB, 
	AUTDZA, 
	AUTDZB, 
	PACIASP, 
	PACIBSP, 
	AUTIASP, 
	AUTIBSP,            // hint-encoded SP variants
	PACIA1716, 
	PACIB1716, 
	AUTIA1716, 
	AUTIB1716, 
	PACGA, 
	XPACI, 
	XPACD, 
	XPACLRI, 
	RETAA, 
	RETAB, 
	BRAA, 
	BRAB, 
	BRAAZ, 
	BRABZ, 
	BLRAA, 
	BLRAB, 
	BLRAAZ, 
	BLRABZ, 
	ERETAA, 
	ERETAB, 
	// -------------------------------------------------------------------------
	// Branch Target Identification (BTI v8.5-A)
	// -------------------------------------------------------------------------
	BTI,                // single mnemonic; modifier (c/j/jc) in operand
	// -------------------------------------------------------------------------
	// Memory Tagging Extension (MTE v8.5-A)
	// -------------------------------------------------------------------------
	IRG, 
	ADDG, 
	SUBG, 
	GMI, 
	SUBP, 
	SUBPS, 
	LDG, 
	STG, 
	ST2G, 
	STZG, 
	STZ2G, 
	STGP, 
	LDGM, 
	STGM, 
	STZGM, 
	// -------------------------------------------------------------------------
	// CRC32 (v8.0-A optional, mandatory v8.1+)
	// -------------------------------------------------------------------------
	CRC32B, 
	CRC32H, 
	CRC32W, 
	CRC32X, 
	CRC32CB, 
	CRC32CH, 
	CRC32CW, 
	CRC32CX, 
	// -------------------------------------------------------------------------
	// Crypto: AES / SHA / SM3 / SM4 / polynomial multiply
	// -------------------------------------------------------------------------
	AESE, 
	AESD, 
	AESMC, 
	AESIMC, 
	SHA1H, 
	SHA1C, 
	SHA1P, 
	SHA1M, 
	SHA1SU0, 
	SHA1SU1, 
	SHA256H, 
	SHA256H2, 
	SHA256SU0, 
	SHA256SU1, 
	SHA512H, 
	SHA512H2, 
	SHA512SU0, 
	SHA512SU1,          // v8.2-A
	EOR3, 
	BCAX, 
	RAX1, 
	XAR,                // SHA3 v8.2-A
	SM3PARTW1, 
	SM3PARTW2, 
	SM3SS1, 
	SM3TT1A, 
	SM3TT1B, 
	SM3TT2A, 
	SM3TT2B, 
	SM4E, 
	SM4EKEY, 
	PMULL, 
	PMULL2, 
	// -------------------------------------------------------------------------
	// BFloat16 (BF16; v8.6-A)
	// -------------------------------------------------------------------------
	BFCVT,              // BFloat16 from single
	BFDOT, 
	BFMMLA, 
	BFMLALB, 
	BFMLALT, 
	BFCVTN, 
	BFCVTN2, 
	// 3-same arithmetic
	MUL, 
	MLA, 
	MLS, 
	NEG, 
	ABS, 
	SHADD, 
	UHADD, 
	SHSUB, 
	UHSUB, 
	SRHADD, 
	URHADD, 
	SQADD, 
	UQADD, 
	SQSUB, 
	UQSUB, 
	SMAX, 
	UMAX, 
	SMIN, 
	UMIN, 
	SABD, 
	UABD, 
	SABA, 
	UABA, 
	ADDP, 
	ADDV, 
	SADDLP, 
	UADDLP, 
	SADALP, 
	UADALP, 
	SADDLV, 
	UADDLV, 
	SMAXV, 
	UMAXV, 
	SMINV, 
	UMINV, 
	SMAXP, 
	UMAXP, 
	SMINP, 
	UMINP, 
	// long / wide / narrowing
	SADDL, 
	SADDL2, 
	UADDL, 
	UADDL2, 
	SSUBL, 
	SSUBL2, 
	USUBL, 
	USUBL2, 
	SADDW, 
	SADDW2, 
	UADDW, 
	UADDW2, 
	SSUBW, 
	SSUBW2, 
	USUBW, 
	USUBW2, 
	RADDHN, 
	RADDHN2, 
	RSUBHN, 
	RSUBHN2, 
	ADDHN, 
	ADDHN2, 
	SUBHN, 
	SUBHN2, 
	XTN, 
	XTN2, 
	SQXTN, 
	SQXTN2, 
	UQXTN, 
	UQXTN2, 
	SQXTUN, 
	SQXTUN2, 
	// multiply long / multiply-accumulate long
	SMULL, 
	SMULL2, 
	UMULL, 
	UMULL2, 
	SMLAL, 
	SMLAL2, 
	UMLAL, 
	UMLAL2, 
	SMLSL, 
	SMLSL2, 
	UMLSL, 
	UMLSL2, 
	SQDMULL, 
	SQDMULL2, 
	SQDMLAL, 
	SQDMLAL2, 
	SQDMLSL, 
	SQDMLSL2, 
	SQDMULH, 
	SQRDMULH, 
	// dot product
	SDOT, 
	UDOT, 
	USDOT, 
	// FP vector
	FMLA, 
	FMLS, 
	FMULX, 
	FMAXP, 
	FMINP, 
	FMAXNMP, 
	FMINNMP, 
	FMAXV, 
	FMINV, 
	FMAXNMV, 
	FMINNMV, 
	FRECPE, 
	FRSQRTE, 
	FRECPS, 
	FRSQRTS, 
	FRECPX, 
	FADDP, 
	FCVTL, 
	FCVTL2, 
	FCVTN, 
	FCVTN2, 
	FCVTXN, 
	FCVTXN2, 
	// FP compare (vector)
	FCMEQ, 
	FCMGE, 
	FCMGT, 
	FCMLE, 
	FCMLT, 
	FACGE, 
	FACGT, 
	// Integer compare (vector)
	CMEQ, 
	CMGE, 
	CMGT, 
	CMHI, 
	CMHS, 
	CMLE, 
	CMLT, 
	CMTST, 
	// Logical (vector)
	MVN, 
	BIT, 
	BIF, 
	BSL, 
	// Shifts
	SHL, 
	SQSHL, 
	SQSHLU, 
	SRSHL, 
	URSHL, 
	SSHR, 
	USHR, 
	SSRA, 
	USRA, 
	SRSHR, 
	URSHR, 
	SRSRA, 
	URSRA, 
	SSHL, 
	USHL, 
	SLI, 
	SRI, 
	SSHLL, 
	SSHLL2, 
	USHLL, 
	USHLL2, 
	SXTL, 
	SXTL2, 
	UXTL, 
	UXTL2,              // aliases of SSHLL/USHLL with imm=0
	SHRN, 
	SHRN2, 
	RSHRN, 
	RSHRN2, 
	SQSHRN, 
	SQSHRN2, 
	UQSHRN, 
	UQSHRN2, 
	SQRSHRN, 
	SQRSHRN2, 
	UQRSHRN, 
	UQRSHRN2, 
	SQSHRUN, 
	SQSHRUN2, 
	SQRSHRUN, 
	SQRSHRUN2, 
	// Misc / permute / bit
	DUP, 
	INS, 
	MOV, 
	EXT, 
	TBL, 
	TBX, 
	ZIP1, 
	ZIP2, 
	UZP1, 
	UZP2, 
	TRN1, 
	TRN2, 
	NOT, 
	REV64, 
	CNT, 
	URECPE, 
	URSQRTE, 
	// Vector immediate
	MOVI, 
	MVNI, 
	// NEON load/store
	LD1, 
	LD2, 
	LD3, 
	LD4,                // multiple structures
	ST1, 
	ST2, 
	ST3, 
	ST4, 
	LD1R, 
	LD2R, 
	LD3R, 
	LD4R,               // load-and-replicate to all lanes
	// Integer arithmetic (predicated, destructive merging)
	SUBR, 
	ASRR, 
	LSLR, 
	LSRR, 
	// FP arithmetic (unpredicated)
	FTSMUL, 
	// FP arithmetic (predicated, destructive merging)
	FSUBR, 
	FDIVR, 
	FNMLA, 
	FNMLS, 
	// Predicate logical / move
	NAND, 
	NOR, 
	SEL, 
	ORRS, 
	EORS, 
	NANDS, 
	NORS, 
	ORNS, 
	MOVS, 
	PTRUE, 
	PTRUES, 
	PFALSE, 
	PFIRST, 
	PNEXT, 
	BRKA, 
	BRKB, 
	BRKAS, 
	BRKBS, 
	BRKPA, 
	BRKPB, 
	BRKN, 
	RDFFR, 
	WRFFR, 
	SETFFR, 
	// Integer compare and set predicate
	CMPEQ, 
	CMPNE, 
	CMPGE, 
	CMPGT, 
	CMPLE, 
	CMPLT, 
	CMPHI, 
	CMPHS, 
	CMPLO, 
	CMPLS, 
	// FP compare and set predicate
	FCMNE, 
	FCMUO, 
	// Permute / move / replicate
	INSR, 
	CPY, 
	COMPACT, 
	// Loads / stores (contiguous)
	LD1B, 
	LD1H, 
	LD1W, 
	LD1D, 
	LD1SB, 
	LD1SH, 
	LD1SW, 
	ST1B, 
	ST1H, 
	ST1W, 
	ST1D, 
	LDFF1B, 
	LDFF1H, 
	LDFF1W, 
	LDFF1D,             // first-faulting
	// SVE2 additions
	WHILEGE, 
	WHILEGT, 
	WHILELE, 
	WHILELT, 
	WHILEHI, 
	WHILEHS, 
	WHILELO, 
	WHILELS, 
	SQRDMLAH, 
	SQRDMLSH, 
	ADCLB, 
	ADCLT, 
	SBCLB, 
	SBCLT, 
	MATCH, 
	NMATCH, 
	HISTCNT, 
	HISTSEG, 
	// -------------------------------------------------------------------------
	// SME (Scalable Matrix Extension)
	// -------------------------------------------------------------------------
	SMSTART, 
	SMSTOP, 
	RDSVL, 
	ADDHA, 
	ADDVA, 
	ZERO, 
	FMOPA, 
	FMOPS, 
	BFMOPA, 
	BFMOPS, 
	SMOPA, 
	SMOPS, 
	UMOPA, 
	UMOPS, 
	USMOPA, 
	SUMOPA, 
	CNTB, 
	CNTH, 
	CNTW, 
	CNTD, 
	INCB, 
	INCH, 
	INCW, 
	INCD, 
	DECB, 
	DECH, 
	DECW, 
	DECD, 
	SQINCB, 
	SQINCH, 
	SQINCW, 
	SQINCD, 
	SQDECB, 
	SQDECH, 
	SQDECW, 
	SQDECD, 
	UQINCB, 
	UQINCH, 
	UQINCW, 
	UQINCD, 
	UQDECB, 
	UQDECH, 
	UQDECW, 
	UQDECD, 
	CNTP, 
	INCP, 
	DECP, 
	SQINCP, 
	SQDECP, 
	UQINCP, 
	UQDECP, 
	// -------------------------------------------------------------------------
	// SME tile slice load/store (LD1B/H/W/D/Q to ZA tile slice; ST1 reverse)
	// -------------------------------------------------------------------------
	LD1Q, 
	ST1Q, 
	// MOVA between Z register and tile slice (both directions)
	MOVA, 
	// -------------------------------------------------------------------------
	// NEON complex FP multiply-add (v8.3-A FCMA extension)
	// -------------------------------------------------------------------------
	FCMLA, 
	FCADD, 
	// -------------------------------------------------------------------------
	// SVE prefetch, non-temporal load/store, EXT/SPLICE/INDEX
	// -------------------------------------------------------------------------
	PRFB, 
	PRFH, 
	PRFW, 
	PRFD, 
	LDNT1B, 
	LDNT1H, 
	LDNT1W, 
	LDNT1D, 
	STNT1B, 
	STNT1H, 
	STNT1W, 
	STNT1D, 
	SPLICE, 
	INDEX, 
	// -------------------------------------------------------------------------
	// SVE2 bitwise select family + polynomial multiply
	// -------------------------------------------------------------------------
	BSL1N, 
	BSL2N, 
	NBSL, 
	PMUL, 
	PMULLB, 
	PMULLT, 
	// -------------------------------------------------------------------------
	// SVE BF16 conversions (BFCVT in SVE form)
	// -------------------------------------------------------------------------
	BFCVTNT, 
	// -------------------------------------------------------------------------
	// PAC-authenticated loads (v8.3-A)
	// -------------------------------------------------------------------------
	LDRAA, 
	LDRAB, 
	// -------------------------------------------------------------------------
	// Transactional Memory Extension (TME, v9.0-A)
	// -------------------------------------------------------------------------
	TSTART, 
	TCOMMIT, 
	TCANCEL, 
	TTEST, 
	// -------------------------------------------------------------------------
	// Wait with timeout (v8.7-A)
	// -------------------------------------------------------------------------
	WFET, 
	WFIT, 
	// -------------------------------------------------------------------------
	// Branch consistency hint (v8.8-A BC.cond)
	// -------------------------------------------------------------------------
	// BC.cond: the consistent-branch form, same 16 conditions.
	BC_EQ, 
	BC_NE, 
	BC_CS, 
	BC_CC, 
	BC_MI, 
	BC_PL, 
	BC_VS, 
	BC_VC, 
	BC_HI, 
	BC_LS, 
	BC_GE, 
	BC_LT, 
	BC_GT, 
	BC_LE, 
	BC_AL, 
	BC_NV, 
	// -------------------------------------------------------------------------
	// Sign/zero extend aliases (canonical names for SBFM/UBFM specific cases)
	// -------------------------------------------------------------------------
	UXTB, 
	UXTH, 
	UXTW,               // unsigned extends (UBFM aliases)
	SXTB, 
	SXTH, 
	SXTW,               // signed extends (SBFM aliases)
	// -------------------------------------------------------------------------
	// Carry arithmetic (add/sub with carry)
	// -------------------------------------------------------------------------
	ADC, 
	ADCS, 
	SBC, 
	SBCS, 
	NGC, 
	NGCS,               // NGC Rd, Rm = SBC Rd, ZR, Rm; NGCS similar
	// -------------------------------------------------------------------------
	// RCpc / LDAPUR / STLUR (v8.4-A unscaled release-consistency loads/stores)
	// -------------------------------------------------------------------------
	LDAPUR, 
	STLUR,              // 32/64-bit word
	LDAPURB, 
	STLURB, 
	LDAPURH, 
	STLURH,             // byte / half
	LDAPURSB, 
	LDAPURSH, 
	LDAPURSW,           // signed extending
	// -------------------------------------------------------------------------
	// SVE BF16 predicated arithmetic (3-same)
	// -------------------------------------------------------------------------
	BFADD, 
	BFSUB, 
	BFMUL, 
	BFMLA, 
	BFMLS, 
	// -------------------------------------------------------------------------
	// Speculation / profiling barriers + speculation hints
	// -------------------------------------------------------------------------
	SB,                 // Speculation Barrier (v8.0)
	CSDB,               // Consumption of Speculative Data Barrier
	DGH,                // Data Gathering Hint (v8.5-A)
	PSB_CSYNC,          // Profile Synchronization Barrier
	TSB_CSYNC,          // Trace Synchronization Barrier
	BTI_J, 
	BTI_C, 
	BTI_JC,             // explicit BTI variants
	// -------------------------------------------------------------------------
	// SVE2.1 / SME2 -- BF16 unpredicated + clamp/min/max + multi-vector
	// -------------------------------------------------------------------------
	BFCLAMP,            // BFCLAMP Zd.H, Zn.H, Zm.H
	BFMAXNM, 
	BFMINNM,            // BF16 min/max-num predicated
	// SME2 multi-vector: contiguous LD/ST and select-table lookup
	LUTI2, 
	LUTI4,              // LUTI2/4 table lookup (byte)
	// SME2 ZIP / UZP multi-way (3-vector and 4-vector forms)
	ZIP, 
	UZP, 
	// -------------------------------------------------------------------------
	// RME (Realm Management Extension, ARMv9-A)
	// -------------------------------------------------------------------------
	TLBI_RPALOS, 
	TLBI_RPAOS,         // Realm physical address space
	AT_S1E1A,           // stage-1 translate with implicit authority
	DC_CIPAPA, 
	DC_CIGDPAPA,        // physical-address cache mgmt
	TLBI_PAALL, 
	TLBI_PAALLOS, 
	// -------------------------------------------------------------------------
	// Apple AMX (undocumented vendor coprocessor; A13+/M1+)
	// -------------------------------------------------------------------------
	// 
	// All AMX instructions share the encoding 0x00201000 | (op << 5) | xn,
	// where xn is a 5-bit operand (typically a GPR holding pointer +
	// control word). The reserved bit pattern lives in the system-
	// instruction space (op0 = 0b0000) so it doesn't collide with any
	// standard A64 mnemonic. Reverse-engineered ops:
	// 
	//   00 LDX     load X register set (16 input rows)
	//   01 LDY     load Y register set (16 input rows)
	//   02 STX     store X
	//   03 STY     store Y
	//   04 LDZ     load Z accumulator (64 rows)
	//   05 STZ     store Z
	//   06 LDZI    load Z interleaved
	//   07 STZI    store Z interleaved
	//   08 EXTRX   extract from X
	//   09 EXTRY   extract from Y
	//   10 FMA64   FP64 fused multiply-add
	//   11 FMS64   FP64 fused multiply-subtract
	//   12 FMA32   FP32 fused multiply-add
	//   13 FMS32   FP32 fused multiply-subtract
	//   14 MAC16   int16 multiply-accumulate
	//   15 FMA16   FP16 fused multiply-add
	//   16 FMS16   FP16 fused multiply-subtract
	//   17 SET     enable AMX (operand=0)
	//   18 CLR     disable AMX
	//   19 VECINT  integer vector ops
	//   20 VECFP   FP vector ops
	//   21 MATINT  integer matrix ops
	//   22 MATFP   FP matrix ops
	//   23 GENLUT  general lookup table (A14+)
	AMX_LDX, 
	AMX_LDY, 
	AMX_STX, 
	AMX_STY, 
	AMX_LDZ, 
	AMX_STZ, 
	AMX_LDZI, 
	AMX_STZI, 
	AMX_EXTRX, 
	AMX_EXTRY, 
	AMX_FMA64, 
	AMX_FMS64, 
	AMX_FMA32, 
	AMX_FMS32, 
	AMX_MAC16, 
	AMX_FMA16, 
	AMX_FMS16, 
	AMX_SET, 
	AMX_CLR, 
	AMX_VECINT, 
	AMX_VECFP, 
	AMX_MATINT, 
	AMX_MATFP, 
	AMX_GENLUT, 
	// -------------------------------------------------------------------------
	// MOPS (Memory Operations, v8.8-A)
	// -------------------------------------------------------------------------
	// 
	// Each operation is split into a 3-instruction Prologue/Main/Epilogue
	// sequence that all share the same {Xd, Xs, Xn} destructive operands.
	//   CPY*  : general memcpy (may overlap)
	//   CPYF* : forward-only memcpy
	//   SET*  : memset (Xs holds the byte value)
	CPYP, 
	CPYM, 
	CPYE, 
	CPYFP, 
	CPYFM, 
	CPYFE, 
	SETP, 
	SETM, 
	SETE, 
	// -------------------------------------------------------------------------
	// Cache management (SYS-encoded under op0=3 or op0=0)
	// -------------------------------------------------------------------------
	// 
	// Data cache:
	DC_IVAC, 
	DC_ISW, 
	DC_CSW, 
	DC_CISW, 
	DC_ZVA, 
	DC_CVAC, 
	DC_CVAU, 
	DC_CIVAC, 
	// Instruction cache:
	IC_IALLUIS, 
	IC_IALLU, 
	IC_IVAU, 
	// Address translate (PE current EL):
	AT_S1E1R, 
	AT_S1E1W, 
	AT_S1E0R, 
	AT_S1E0W, 
	AT_S1E2R, 
	AT_S1E2W, 
	AT_S1E3R, 
	AT_S1E3W, 
	AT_S12E1R, 
	AT_S12E1W, 
	AT_S12E0R, 
	AT_S12E0W, 
	// TLB invalidate (the practical subset):
	TLBI_VMALLE1, 
	TLBI_VMALLE1IS, 
	TLBI_VAE1, 
	TLBI_VAE1IS, 
	TLBI_ASIDE1, 
	TLBI_ASIDE1IS, 
	TLBI_VAAE1, 
	TLBI_VAAE1IS, 
	TLBI_VALE1, 
	TLBI_VALE1IS, 
	TLBI_VAALE1, 
	TLBI_VAALE1IS, 
	TLBI_ALLE1, 
	TLBI_ALLE1IS, 
	TLBI_ALLE2, 
	TLBI_ALLE2IS, 
	TLBI_ALLE3, 
	TLBI_ALLE3IS, 
	// -------------------------------------------------------------------------
	// Prefetch
	// -------------------------------------------------------------------------
	PRFM, 
	PRFUM, 
	// -------------------------------------------------------------------------
	// Aliases (printed canonically; encode the underlying operation with
	// Rd=ZR or Rn=ZR fixed).
	// -------------------------------------------------------------------------
	NEGS,               // NEGS Rd, Rm{,shift} =  SUBS Rd, ZR, Rm{,shift}
	CMP,                // CMP Rn, Rm{,shift}  =  SUBS ZR, Rn, Rm{,shift}
	CMN,                // CMN Rn, Rm{,shift}  =  ADDS ZR, Rn, Rm{,shift}
}

NZCV_Flag :: enum u8 {
	N, // negative result
	Z, // zero result
	C, // carry-out / no-borrow (unsigned sense)
	V, // signed overflow
}

NZCV_Flags :: distinct bit_set[NZCV_Flag; u8]

Operand :: struct #packed {
	using _:    struct #packed #raw_union {
		reg:       Register,
		// 4
		mem:       Memory,
		// 8
		immediate: i64,
		// 8
		relative:  i64,
		// 8
		shifted:   Shifted_Reg,
		// 6
		extended:  Extended_Reg,
		// 6
		cond:      u8,
		// 1
		za:        ZA_Slice,
	},
	// 8 total -- the largest member wins
	kind:       Operand_Kind,
	// 1
	size:       u8,
	// How many consecutive registers the syntax writes as a list, starting at
	// `reg`: `{v0.16b, v1.16b}` is 2. Zero means the operand is a plain
	// register. The count belongs to the instruction form rather than to the
	// caller -- LD2 always names two -- so it comes from the encoding.
	list_count: u8,
}

Operand_Encoding :: enum u8 {
	NONE, 
	IMPL,                    // implicit; no bits emitted
	// ---- Register slots (5-bit hw fields) ----
	RD,                      // bits 0-4
	RT,                      // bits 0-4 (alias of RD used in loads)
	RN,                      // bits 5-9
	RT2,                     // bits 10-14
	RA,                      // bits 10-14 (alias of RT2 used in MADD/MSUB)
	RM,                      // bits 16-20
	RN_RM,                   // bits 5-9 AND 16-20 -- one register into both source
	// ---- Immediates ----
	IMM12,                   // bits 10-21
	IMM16,                   // bits 5-20
	IMM6,                    // bits 10-15  (shift amount; SHAMT)
	IMM9,                    // bits 12-20  (signed 9-bit; LDUR/pre/post)
	IMM_HW,                  // bits 21-22  (MOVZ/MOVN/MOVK hw field; value is shift/16)
	// LSR/ASR by immediate are UBFM/SBFM Rd, Rn, #shift, #(31|63): the shift
	// goes to immr and imms is a constant already fixed in the form's bits,
	// so unlike LSL (ENC_LSL_IMM_*) only one field is operand-driven.
	ENC_SHIFT_IMMR,          // bits 16-21  (immr; LSR/ASR immediate aliases)
	// RDSVL / the RDVL family put their signed 6-bit immediate at bits 10:5,
	// not where IMM6 (bits 15:10) writes it.
	ENC_IMM6_LO,             // bits  5-10  (signed 6-bit; RDSVL)
	IMM_SH12,                // bit  22     (ADD/SUB imm: LSL #12 flag)
	SHIFT_TYPE,              // bits 22-23  (LSL/LSR/ASR/ROR for shifted-register)
	EXT_OPT,                 // bits 13-15  (extend type for extended-register)
	EXT_IMM3,                // bits 10-12  (extend amount)
	COND_HI,                 // bits 12-15  (CSEL/CSINC/CSINV/CSNEG, FCSEL, CCMP)
	COND_HI_INV,             // bits 12-15, stored inverted -- the cset/cinc aliases
	// read as `cset Wd, eq` but encode CSINC's cond as NE
	COND_LO,                 // bits  0-3   (B.cond)
	NZCV_FIELD,              // bits  0-3   (CCMP/CCMN immediate NZCV)
	SYS_FIELD,               // bits 5-19   (MRS/MSR: op0/op1/CRn/CRm/op2)
	HINT_FIELD,              // bits 5-11   (HINT type)
	BARRIER_FIELD,           // bits 8-11   (DMB/DSB/ISB barrier type)
	// ---- Memory operand composites ----
	OFFSET_BASE_U12,         // [Xn, #imm * size] with imm12 scaled by data size
	OFFSET_BASE_S9,          // [Xn, #imm] signed-9 unscaled (LDUR/STUR)
	OFFSET_BASE_PRE,         // [Xn, #imm]!   signed-9 pre-index
	OFFSET_BASE_POST,        // [Xn], #imm    signed-9 post-index
	OFFSET_BASE_A,           // [Xn]          no displacement (exclusives, acquire/release, LSE)
	// LDP/STP family. Nothing like the single-register modes above: the
	// displacement is a signed 7-bit value SCALED by the transfer size at
	// bits 21:15 (single-register forms use an unscaled 9-bit at 20:12), and
	// bits 11:10 are part of Rt2 here, so the pre/post markers the
	// single-register encodings OR in would corrupt the second register.
	// The scale cannot be read off the register type -- LDPSW pairs X
	// registers but loads words (scale 4), STGP pairs X registers and scales
	// by 16 -- so it is spelled out per encoding. The addressing mode lives
	// in the form's bits[24:23] (01 post, 10 signed offset, 11 pre), which
	// is where the decoder reads it back from.
	OFFSET_PAIR_4,           // [Xn{, #imm}] / [Xn, #imm]! / [Xn], #imm -- imm7 x 4
	OFFSET_PAIR_8,           //                                            imm7 x 8
	OFFSET_PAIR_16,          //                                            imm7 x 16
	OFFSET_REG,              // [Xn, Xm{, LSL #s}] or [Xn, Wm|Xm, <extend> {#s}];
	//   option (15:13) comes from the operand's mode/extend
	OFFSET_EXT,              // subsumed by OFFSET_REG; kept because these values are
	// ---- PC-relative ----
	BRANCH_26,               // B / BL  (operand-driven 26-bit field, scaled ×4)
	BRANCH_19,               // B.cond / CBZ / LDR literal
	BRANCH_14,               // TBZ / TBNZ
	BRANCH_PG21,             // ADR / ADRP: imm21 split as immlo[29-30] + immhi[5-23]
	// ---- TBZ/TBNZ bit position (split field b5 + b40) ----
	TBZ_BIT,                 // b5 at bit 31, b40 at bits 19-23
	// ---- NEON / SIMD specific ---------------------------------------------
	VD, 
	VN, 
	VM,                      // 5-bit V regs at bits 0-4 / 5-9 / 16-20 (alias of RD/RN/RM)
	VA,                      // R4-type 3rd source (FMLA-ish) at bits 10-14
	NEON_IMM8_FMOV,          // 8-bit imm split (abc at 18-16, defgh at 9-5)
	NEON_INDEX_H,            // 2-bit H lane index
	NEON_INDEX_S,            // S lane index
	NEON_INDEX_D,            // D lane index
	// ---- NEON shift-by-immediate (immh:immb at bits 22:16) ----
	// The element-size marker bit is fixed in the entry's `bits`; the operand
	// drives only the low bits. Left: low = shift. Right: low = esize - shift.
	NEON_SHL_IMM, 
	NEON_SHR_IMM, 
	// ---- NEON copy/permute index fields ----
	// The element-size marker bit lives in the entry `bits`; the lane index
	// operand drives the bits above it (DUP/INS imm5, INS imm4) or the plain
	// imm4 (EXT). The decoder recovers the element size from imm5's marker.
	VN_VM_DUP,               // one V reg packed into BOTH Vn (9:5) and Vm (20:16) (MOV = ORR alias)
	NEON_IDX5,               // element lane index in imm5 (20:16); index << (markerbit+1)
	NEON_IDX4,               // INS source lane index in imm4 (14:11); index << markerbit
	NEON_EXT_IDX,            // EXT byte index in imm4 (14:11)
	// ---- MSR (immediate to PSTATE): pstate field selector op1:op2 ----
	// User passes the combined 6-bit selector (op1<<3 | op2); op1 lands at
	// bits 18:16, op2 at bits 7:5. The #imm goes to CRm (bits 11:8) via
	// BARRIER_FIELD, which it shares with the DMB/DSB barrier encoding.
	IMM5_HI,                 // generic 5-bit immediate at bits 20:16 (CCMP/CCMN immediate)
	MSR_PSTATE,              // PSTATE field selector: op1 at 18:16, op2 at 7:5
	FMOV_SCALAR_IMM,         // scalar FMOV 8-bit float immediate at bits 20:13
	// ---- SVE alias duplicated predicate/Z fields + EXT byte index ----
	// MOV/NOT/MOVS predicate aliases are EOR/ORR/AND with a duplicated field;
	// MOV (predicated) is SEL with Zm = Zd. The source register is packed into
	// every slot it occupies so the alias round-trips to the canonical bytes.
	PG4_PM_DUP,              // Pg at 10:13 AND Pm at 16:19 (NOT = EOR Pd,Pg/z,Pn,Pg)
	PN_PM_DUP,               // Pn at 5:8 AND Pm at 16:19 (MOVS/MOV-pred: Pm = Pn)
	PN_PG_PM_DUP,            // Pn at 5:8, Pg at 10:13, Pm at 16:19 (MOV Pd,Pn)
	ZD_ZM_DUP,               // Zd at 0:4 AND Zm at 16:20 (MOV Zd,Pg/m,Zn = SEL ...,Zd)
	SVE_EXT_IMM,             // SVE EXT byte index: imm8h at 20:16, imm8l at 12:10
	ZA_TILE_LOW,             // SME ZA accumulator tile number at bits 2:0 (ADDHA/ADDVA)
	// ---- NEON single-structure lane index (LD1..4_LANE / ST1..4_LANE) ----
	// The lane index is split across Q (bit 30), S (bit 12) and size (bits
	// 11:10) in an element-size-dependent way; the structure-size/count opcode
	// bits stay fixed in the entry `bits`.
	NEON_LANE_B,             // .B[i]: Q<<3 | S<<2 | size  (i in 0..15)
	NEON_LANE_H,             // .H[i]: Q<<2 | S<<1 | bit11 (i in 0..7)
	NEON_LANE_S,             // .S[i]: Q<<1 | S            (i in 0..3)
	NEON_LANE_D,             // .D[i]: Q                   (i in 0..1)
	// ---- SVE2 XAR rotate amount (tszh:tszl:imm3 split) ----
	// V = 2*esize - amount placed as tszh(23:22):tszl(20:19):imm3(18:16);
	// esize comes from the form's Z register (highest set bit of tszh:tszl).
	SVE_XAR_SHIFT, 
	// ---- LSE atomics ------------------------------------------------------
	ATOMIC_RS,               // Rs (source / compare) at bits 16-20
	ATOMIC_RT,               // Rt (target) at bits 0-4
	ATOMIC_RN,               // Rn (address) at bits 5-9
	// ---- Bitmask logical immediate (N:imms:immr at bits 22 / 15:10 / 21:16) ----
	BITMASK_FIELD, 
	// ---- Predicate (SVE) --------------------------------------------------
	PD, 
	PN, 
	PM,                      // P-reg positions (bits 0-3 / 5-8 / 16-19 in many SVE forms)
	PG,                      // governing predicate (3-bit at bits 10-12)
	PG4,                     // governing predicate (4-bit at bits 10-13, e.g. predicate logical)
	PM3,                     // 3-bit Pm at bits 15:13 (SME outer products / a few SVE forms)
	// ---- SVE immediates ---------------------------------------------------
	SVE_IMM8,                // signed 8-bit at bits 12-5 (DUP/CPY/ADD imm)
	SVE_IMM5,                // 5-bit at bits 20-16 (INDEX imm, etc.)
	SVE_SHIFT_TSZ_IMM,       // tsz:imm3 at bits 22:16, encodes element-size + shift amount
	SVE_PATTERN,             // 5-bit pattern (POW2/VL1.../ALL) at bits 9-5 (PTRUE)
	IMM_MUL4, 
	// ---- SVE memory operands ---------------------------------------------
	SVE_OFFSET_BASE_SS,      // [Xn, Xm, LSL #s] -- scalar+scalar contiguous
	SVE_OFFSET_BASE_SI,      // [Xn, #imm, MUL VL] -- scalar+imm (signed 4-bit times VL)
	SVE_OFFSET_BASE_VEC,     // [Xn, Zm.S/D, UXTW|SXTW|LSL #s] -- scalar base + vec offset
	SVE_OFFSET_VEC_BASE,     // [Zn.S/D, #imm5] -- vector base + scalar imm
	// ---- SVE indexed lane field (FMLA Zda.T, Zn.T, Zm.T[i]) -----------
	SVE_FMLA_IDX_H,          // .H index: i3 split as (bit 22, bits 20:19), Zm@18:16
	SVE_FMLA_IDX_S,          // .S index: i2 at bits 20:19, Zm@18:16
	SVE_FMLA_IDX_D,          // .D index: i1 at bit 20, Zm@19:16
	// ---- SME ZA tile + slice fields --------------------------------------
	ZA_TILE_NUM_B,           // single-tile (ZA0.B): no field (implicit)
	ZA_TILE_NUM_H,           // tile number bit at bit 22 (ZA0.H..ZA1.H)
	ZA_TILE_NUM_S,           // tile number bits 23:22 (ZA0.S..ZA3.S)
	ZA_TILE_NUM_D,           // tile number bits 23:21 (ZA0.D..ZA7.D)
	SME_PATTERN_FIELD,       // 5-bit SME pattern (for ZERO list / SMSTART/SMSTOP)
	// ---- SME tile-slice descriptor field (LD1B/LD1H/LD1W/LD1D/LD1Q) ------
	// 
	// User passes a packed immediate carrying the full slice descriptor:
	//   bits  3:0  = imm offset within tile (0..15 for .B, 0..7 for .H, ...)
	//   bit  4     = direction (0=H, 1=V)
	//   bits  6:5  = Ws index (Ws is W12+this, range 0..3)
	//   bits 10:7  = tile number (only the low bits relevant per element size)
	// 
	// The encoder unpacks and places the bits per element-size layout.
	SME_SLICE_B,             // byte tile (single tile, imm 0..15)
	SME_SLICE_H,             // half tile (2 tiles, imm 0..7)
	SME_SLICE_W,             // word tile (4 tiles, imm 0..3)
	SME_SLICE_D,             // double tile (8 tiles, imm 0..1)
	SME_SLICE_Q,             // quad tile (16 tiles, imm 0)
	// ---- Misc new operand-encoding values (batch 3) ----
	ENC_FCMLA_ROT,           // 2-bit rotation at bits 13:12 (FCMLA)
	NEON_IDX2,               // 2-bit lane index at bits 13:12 (SM3TT)
	// A register the syntax writes as a list of N consecutive registers,
	// `{v0.16b, v1.16b}`. Same bits as VD / VN; N is fixed by the form (LD2
	// always names two), so it rides on the encoding rather than the operand
	// type -- otherwise every count would need its own type per arrangement.
	VD_LIST1, 
	VD_LIST2, 
	VD_LIST3, 
	VD_LIST4, 
	PNG,                     // bits 10-12, predicate-as-counter (SME2)
	ENC_ZT0,                 // no bits at all; there is only one ZT register
	LUTI_IDX,                // bits 15-16, LUTI2/LUTI4 table index
	SME_ZA_ARRAY,            // `za[w12, 0]` -- a vector of the ZA array, not a tile
	SME_ZA_MASK,             // bits 0-7, ZERO's per-tile mask
	// SVE scalar+scalar addressing scales the index by the access size, and the
	// assembler wants that written out (`[x0, x0, lsl #2]`). The amount is a
	// property of the form, so it rides on the encoding.
	SVE_OFFSET_BASE_SS1, 
	SVE_OFFSET_BASE_SS2, 
	SVE_OFFSET_BASE_SS3, 
	SVE_OFFSET_BASE_SS4, 
	// SVE gather/scatter: the index is a vector, and the syntax names its
	// element size and how the base extends it. A 32-bit index is written
	// `uxtw`/`sxtw` (bit 22 says which); a 64-bit one needs neither.
	SVE_OFFSET_BASE_VEC_S, 
	SVE_OFFSET_BASE_VEC_D, 
	// A scatter lays the same information out differently: bit 22 is the
	// index's width and bit 14 is the extend, where a gather has the extend at
	// 22 and takes the width from its opcode.
	SVE_OFFSET_BASE_VECST_S, 
	SVE_OFFSET_BASE_VECST_D, 
	SVE_IMM5A,               // 5-bit at bits 5-9 (INDEX first operand)
	// A Z register whose element size is not in the static pattern but in the
	// instruction's own tsz field, so decode has to read it out of the word
	// rather than take it from the form (SVE2 XAR).
	VD_TSZ,                  // bits 0-4
	VN_TSZ,                  // bits 5-9
	VN_LIST1, 
	VN_LIST2, 
	VN_LIST3, 
	VN_LIST4, 
	ENC_FCADD_ROT,           // 1-bit rotation at bit 12 (FCADD)
	ENC_SVE_PRFOP,           // 4-bit prefetch op at bits 3:0 (SVE PRFB/H/W/D)
	ENC_LDRAA_IMM10,         // signed 10-bit imm10 at bits 21:12, scaled by 8 (LDRAA/B)
	// ---- Batch 5 composite-packed encodings ----
	// 
	// LSL_IMM Wd, Wn, #imm = UBFM Wd, Wn, #(-imm % 32), #(31-imm).
	// The single user-passed shift amount drives BOTH immr (21:16) and
	// imms (15:10). Width 32 (W) vs 64 (X) selects the modulus and N bit.
	ENC_LSL_IMM_W,           // W-form: immr = (-imm) & 31, imms = 31 - imm
	ENC_LSL_IMM_X,           // X-form: immr = (-imm) & 63, imms = 63 - imm
	// ROR_IMM Rd, Rn, #imm = EXTR Rd, Rn, Rn, #imm. The Rn register is
	// packed at BOTH the Rn slot (9:5) AND the Rm slot (20:16). The shift
	// amount goes to imms (15:10).
	ENC_DUAL_RN_RM,          // packs op.reg at both bits 9:5 AND bits 20:16
	ENC_ROR_SHIFT,           // 6-bit shift amount at bits 15:10 (imms slot)
	// SME2 multi-vector lists at the Vd/Vn/Vm slots. The user passes the
	// first register of the list; the matcher validates alignment.
	// Encoding just packs the first register's hardware number into the
	// standard slot (the implicit pair/quad is encoded by mnemonic).
	ENC_Z_PAIR_VD, 
	ENC_Z_PAIR_VN, 
	ENC_Z_PAIR_VM, 
	ENC_Z_QUAD_VD, 
	ENC_Z_QUAD_VN, 
	ENC_Z_QUAD_VM, 
}

Operand_Kind :: enum u8 {
	NONE, 
	REGISTER, 
	IMMEDIATE, 
	MEMORY, 
	RELATIVE, 
	SHIFTED_REG,  // X reg + shift type + shift amount
	EXTENDED_REG, // X/W reg + extend + amount
	COND,         // 4-bit condition code (EQ/NE/.../AL/NV)
	ZA_SLICE,     // `za0h.b[w12, 0]` -- a row or column of an SME tile
}

Operand_Set :: distinct bit_set[int; u8]

Operand_Type :: enum u8 {
	NONE, 
	// ---- Integer registers ----
	W_REG,        // W0..W30 or WZR (hw=31 means ZR)
	X_REG,        // X0..X30 or XZR
	WSP_REG,      // W0..W30 or WSP (hw=31 means stack pointer)
	XSP_REG,      // X0..X30 or SP
	W_SHIFTED,    // W reg + shift type + 5-bit amount
	X_SHIFTED,    // X reg + shift type + 6-bit amount
	W_EXTENDED,   // W reg + extend + 3-bit amount
	X_EXTENDED,   // X reg + extend + 3-bit amount
	// ---- SIMD/FP scalar register views ----
	B_REG, 
	H_REG, 
	S_REG, 
	D_REG, 
	Q_REG, 
	// ---- Vector register (NEON full V) ----
	V_REG, 
	// NEON vector with explicit arrangement
	V_8B, 
	V_16B, 
	V_4H, 
	V_8H, 
	V_2S, 
	V_4S, 
	V_1D, 
	V_2D, 
	V_4H_FP16, 
	V_8H_FP16,    // FP16 vector forms
	// Element-indexed vector (V0.B[i] / .H[i] / .S[i] / .D[i])
	V_ELEM_B, 
	V_ELEM_H, 
	V_ELEM_S, 
	V_ELEM_D, 
	// ---- SVE register operands ----
	Z_REG_B, 
	Z_REG_H, 
	Z_REG_S, 
	Z_REG_D, 
	P_REG,        // P0..P15 (predicate)
	P_REG_MERGE, 
	P_REG_ZERO,   // predicated execution modes
	P_REG_GOV,    // governing predicate slot (3-bit P0..P7)
	// ---- SME register operands ----
	ZA_TILE_B, 
	ZA_TILE_H, 
	ZA_TILE_S, 
	ZA_TILE_D, 
	ZA_TILE_Q,    // ZA tile by element size
	SME_PATTERN,  // SME pattern/tile-list mask selector
	SVE_PATTERN,  // SVE predicate pattern (POW2, VL1.., ALL)
	// ---- SME tile-slice operand (packed immediate descriptor) ----
	//   bits  3:0 = imm offset within tile (range varies by element size)
	//   bit  4    = direction (0=H, 1=V)
	//   bits 6:5  = Ws index (Ws is W12 + this, range 0..3)
	//   bits 10:7 = tile number (relevant bits per element size)
	SME_SLICE_B, 
	SME_SLICE_H, 
	SME_SLICE_W, 
	SME_SLICE_D, 
	SME_SLICE_Q, 
	// ---- Misc new operand-type aliases ----
	FCMLA_ROT,    // 2-bit complex rotation index (0/90/180/270 deg) at bits 13:12
	FCADD_ROT,    // 1-bit complex rotation index (0=90, 1=270 deg) at bit 12
	SVE_PRFOP,    // 4-bit SVE prefetch op selector at bits 3:0
	LDRAA_IMM10,  // signed 10-bit imm10 scaled by 8 (LDRAA / LDRAB)
	LSL_SHIFT_W,  // shift amount 0..31 for LSL Wd, Wn, #imm (32-bit)
	LSL_SHIFT_X,  // shift amount 0..63 for LSL Xd, Xn, #imm (64-bit)
	ROR_SHIFT,    // shift amount for ROR (alias of EXTR), goes to imms
	// ---- Immediates ----
	IMM_12,       // 12-bit unsigned (ADD/SUB imm; carries optional LSL #12 in size byte)
	IMM_16,       // 16-bit unsigned (MOVZ/MOVN/MOVK)
	IMM_8,        // 8-bit unsigned (NEON MOVI, BTI/CRC32 immediate-like)
	IMM_6,        // 6-bit unsigned (data-proc shift amount)
	IMM_5,        // 5-bit unsigned (TBZ/TBNZ bit position; FP rounding lane)
	IMM_3,        // 3-bit (shift amount for EXTEND, NZCV, system register field)
	IMM_4,        // 4-bit (HINT, DMB/DSB barrier types, NZCV flags)
	IMM_2,        // 2-bit (FP rounding mode / NEON cmode bits 14:13 etc.)
	NZCV_IMM,     // 4-bit NZCV for CCMP/CCMN immediate forms
	SYS_REG,      // MRS/MSR target system register
	PSTATE_FIELD, // MSR immediate form: a PSTATE field selector,
	// a different namespace from the system registers
	HW_SHIFT,     // 2-bit LSL hw (0/16/32/48) for MOV-immediate
	BITMASK_IMM,  // Logical immediate (bitmask-encoded N:imms:immr)
	LSE_SIZE,     // 2-bit size selector for LSE atomics (00=B 01=H 10=W 11=X)
	IMM_MUL4, 
	// ---- PC-relative ----
	REL_26,       // B / BL (signed 26-bit << 2)
	REL_19,       // B.cond / CBZ / CBNZ / LDR literal (signed 19-bit << 2)
	REL_14,       // TBZ / TBNZ (signed 14-bit << 2)
	REL_PG21,     // ADR / ADRP (signed 21-bit; ADRP scales by 4096)
	// ---- Memory ----
	// 
	// One operand type per addressing mode. The mode has to be part of the
	// operand TYPE, not just the operand encoding, because it is a matching
	// criterion: `LDR Xt, [Xn, #imm]`, `[Xn, #imm]!`, `[Xn], #imm` and
	// `[Xn, Xm]` are all the mnemonic LDR, and the matcher picks between
	// their forms on the addressing mode alone. (Same reason W_REG /
	// W_SHIFTED / W_EXTENDED are distinct types over one register class.)
	// Each maps to exactly one Address_Mode; the form's Operand_Encoding
	// then says how the fields are packed.
	MEM_OFFSET,   // [Xn{, #imm}]                    -> Address_Mode.OFFSET
	MEM_PRE,      // [Xn, #imm]!                     -> PRE_INDEXED
	MEM_POST,     // [Xn], #imm                      -> POST_INDEXED
	MEM_REG,      // [Xn, Xm{, LSL #s}] or [Xn, Wm|Xm, <extend> {#s}]
	//   -> REG_OFFSET or EXT_REG_OFFSET; one word, option picks
	MEM_EXT,      // subsumed by MEM_REG; kept because these values are baked
	//   into the table blobs
	// SVE addressing. Kept distinct from the plain modes above: a gather
	// load has both a scalar+scalar and a scalar+vector form under the one
	// mnemonic, and those two differ only in the index register's class.
	MEM_SVE_SS,   // [Xn, Xm, LSL #s]                -> REG_OFFSET, X index
	MEM_SVE_SI,   // [Xn, #imm, MUL VL]              -> OFFSET
	MEM_SVE_VEC,  // [Xn, Zm.S/D, UXTW|SXTW|LSL #s]  -> REG_OFFSET, Z index
	MEM_SVE_VB,   // [Zn.S/D, #imm5]                 -> OFFSET, Z base
	// ---- Condition code ----
	COND, 
	// Condition with AL/NV excluded. The cset/cinc alias family is only the
	// preferred spelling when cond != 111x -- with AL or NV the underlying
	// CSINC/CSINV/CSNEG is what an assembler writes.
	COND_NOT_AL, 
	// SME2 vector pairs and quads. The element size cannot come from the
	// encoding the way the list length does, because the operand is written
	// with it (`{z0.b, z1.b}`) and it is what separates LD1B from LD1H.
	// A Z register of any element size, for the forms where the size is not in
	// the static pattern and so cannot select between forms (SVE2 XAR).
	Z_REG_ANY, 
	Z_PAIR_B, 
	Z_PAIR_H, 
	Z_PAIR_S, 
	Z_PAIR_D, 
	Z_QUAD_B, 
	Z_QUAD_H, 
	Z_QUAD_S, 
	Z_QUAD_D, 
	// SME2 predicate-as-counter (PN8..PN15). `_ZERO` prints the `/z` a load
	// needs; a store writes it bare.
	PN_REG, 
	PN_REG_ZERO, 
	ZT_REG,       // ZT0 -- SME2's lookup table, and the only one of its kind
	ZA_ARRAY,     // a ZA array vector, addressed by Wn plus an offset
	// A Z register written as a table list. SVE's TBL takes one table or two,
	// and unlike LD2 the caller chooses which, so the count has to be in the
	// operand type for the matcher to tell the two forms apart.
	Z_LIST1_B, 
	Z_LIST1_H, 
	Z_LIST1_S, 
	Z_LIST1_D, 
	Z_LIST2_B, 
	// A predicate that is written with an element size because it is the
	// instruction's destination (`cmpge p0.b, p1/z, ...`).
	P_REG_B, 
	P_REG_H, 
	P_REG_S, 
	P_REG_D, 
	// ---- NEON shift-by-immediate amount (encoded into immh:immb together
	//      with the element size: left = esize+shift, right = 2*esize-shift) ----
	VEC_SHIFT, 
	// ---- NEON element lane index (DUP/INS/EXT). The element-size marker
	//      lives in the entry `bits`; the operand drives only the index bits. ----
	VEC_INDEX, 
	V_1Q,         // NEON .1q -- one 128-bit lane (PMULL's destination). Not
}

Print_Options :: rexcode_isa.Print_Options

Print_Result :: rexcode_isa.Print_Result

Register :: distinct u32

Relocation :: struct #packed {
	offset:   u32,
	label_id: u32,
	addend:   i32,
	type:     Relocation_Type,
	size:     u8,
	inst_idx: u16,
}

Relocation_Type :: enum u8 {
	NONE          = 0, 
	// PC-relative branches
	B26,               // 26-bit signed offset (×4) -- B / BL
	B_COND19,          // 19-bit signed offset (×4) -- B.cond, CBZ/CBNZ
	TBZ14,             // 14-bit signed offset (×4) -- TBZ / TBNZ
	// PC-relative addressing
	ADR_PCREL21,       // ±1MB signed offset -- ADR
	ADRP_PCREL21,      // ±4GB signed offset on 4K page boundary -- ADRP
	PCREL_LO12_I,      // low 12 of (sym - page_of(ADRP)) -- ADD/LDR/STR after ADRP
	PCREL_LO12_S,      // S-form variant if needed for store-pair-style ops
	// Load-literal (PC-relative 19-bit signed, scaled by 4)
	LDR_LITERAL19, 
	// Absolute (filled by linker)
	ABS64, 
	ABS32, 
	ABS16, 
}

Shift_Type :: enum u8 {
	LSL = 0, 
	LSR = 1, 
	ASR = 2, 
	ROR = 3, 
}

Shifted_Reg :: struct #packed {
	reg:    Register,
	// 4
	type:   Shift_Type,
	// 1
	amount: u8,
}

Side_Effect :: enum u8 {
	CONTROL,          // writes pc: B/BL/BR/BLR/RET, B.cond, CBZ/CBNZ, TBZ/TBNZ
	EXCEPTION,        // exception-generating call: SVC / HVC / SMC
	TRAP,             // deliberately faults: BRK (breakpoint), UDF (undefined)
	FENCE,            // memory-ordering barrier: DMB/DSB, and acquire/release accesses
	ISYNC,            // instruction-stream / context synchronization: ISB
	ATOMIC,           // indivisible RMW: LDXR/STXR pair, LSE (LDADD/SWP/CAS...)
	RESERVATION,      // sets/tests/clears the local exclusive monitor: LDXR/STXR, CLREX
	CACHE,            // cache maintenance with coherence effects: DC, IC
	HINT,             // architecturally-inert hint: NOP/YIELD/PRFM/SEV/ESB/CSDB
	BTI,              // branch-target-identification landing pad (control-flow integrity)
	PAC,              // pointer authentication: reads an implicit key, may fault (FEAT_FPAC)
	WAIT,             // suspends execution until an event/interrupt: WFI/WFE
	PRIVILEGED,       // reads/writes system state: MSR/MRS, ERET, TLBI, AT, DAIF
	FFR,              // reads/writes the SVE first-fault register: SETFFR/RDFFR/WRFFR, LDFF*
	NONDETERMINISTIC, // RNDR/RNDRRS, counter/timer reads (CNTVCT), TSTART
}

Side_Effects :: distinct bit_set[Side_Effect; u16]

Sysreg_Name :: struct {
	value: u16,
	// the bare 15-bit MRS/MSR field (what sysreg_bits returns)
	name:  string,
}

Token :: rexcode_isa.Token

Token_Kind :: rexcode_isa.Token_Kind

ZA_Slice :: distinct bit_field u32 {
	tile:     u8 | 4,
	vertical: bool | 1,
	ws:       u8 | 2,
	offset:   u8 | 4,
	elem:     u8 | 5,
}

@(rodata)
CLOBBER_FORMS: []Clobber = …

@(rodata)
DECODE_ENTRIES: []Decode_Entry = …

@(rodata)
DECODE_INDEX_OP0: []Decode_Index = …

@(rodata)
ENCODE_FORMS: []Encoding = …

@(rodata)
ENCODE_RUNS: []Encode_Run = …

@(rodata)
SVE_PATTERN_NAMES: [32]string = …

@(rodata)
SYSREG_NAMES: [230]Sysreg_Name = …