gasm-sdk/asm/encode.go

// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
// SPDX-License-Identifier: BSD-3-Clause

package asm

import (
	"fmt"
	"math"
	"strconv"
	"strings"
)

// Encode encodes one Plan 9 instruction (mnemonic plus operands, in source
// order) into x86-64 machine code.
func Encode(mnemonic string, ops ...Operand) ([]byte, error) {
	e := &enc{}
	if err := e.encode(mnemonic, ops); err != nil {
		return nil, err
	}
	return e.out, nil
}

type enc struct {
	out     []byte
	patches []encPatch // disp32 fields awaiting static-symbol resolution

	// FloatPool collects the pooled constants the floating-point
	// immediates reference, in first-use order.
	floatPool     []floatPoolEntry
	floatPoolSeen map[string]bool
}

// floatPoolEntry is one pooled floating-point constant: the symbol name
// the emitted RIP-relative load refers to and its IEEE-754 bytes.
type floatPoolEntry struct {
	name string
	data []byte
}

// addFloatPool records a pooled constant, deduplicated by symbol name.
func (e *enc) addFloatPool(name string, bits uint64, width int) {
	if e.floatPoolSeen == nil {
		e.floatPoolSeen = map[string]bool{}
	}
	if e.floatPoolSeen[name] {
		return
	}
	e.floatPoolSeen[name] = true
	data := make([]byte, width)
	for i := range width {
		data[i] = byte(bits >> (8 * i))
	}
	e.floatPool = append(e.floatPool, floatPoolEntry{name: name, data: data})
}

// floatPoolList returns the pooled constants in first-use order.
func (e *enc) floatPoolList() []floatPoolEntry {
	return e.floatPool
}

// encPatch marks a 4-byte displacement field in enc.out that must receive the
// RIP-relative offset of a static symbol once the file layout is settled.
type encPatch struct {
	off    int
	name   string
	addend int64
	tls    bool // a TLS slot offset: the patch is R_TLSLE with no symbol
}

func (e *enc) encode(mnem string, ops []Operand) error {
	upper := strings.ToUpper(mnem)

	// The corpus families (x87, the system and string controls, XSAVE)
	// dispatch on the full name from the amd64 family files before the
	// fixed-name switch, the way their tables spell the mnemonics out.
	if handled, err := e.encodeAmd64Family(upper, ops); handled {
		return err
	}

	// Fixed-name instructions (no size suffix).
	switch {
	case upper == "RET":
		// RET sym(SB), the absolute return: the toolchain encodes it as a
		// tail jump, E9 rel32 with a call relocation against the symbol.
		if len(ops) == 1 {
			if m, ok := ops[0].(sbMem); ok {
				return e.emit(&instr{opcode: []byte{0xE9}, modrm: -1, sib: -1, disp: le32(0), sb: &sbRef{name: m.name, addend: m.addend}})
			}
			return fmt.Errorf("RET: unsupported operand")
		}
		if len(ops) != 0 {
			return fmt.Errorf("RET expects no operands, got %d", len(ops))
		}
		return e.encodeRet()
	case upper == "NOP":
		// The toolchain consumes every NOP statement as a pseudo and emits
		// nothing for it, operands included (a bare NOP, NOP AX and
		// NOP sym(SB) all vanish from the object).
		return nil
	case upper == "CALL" || upper == "JMP":
		// Through a register or memory: FF /2 (CALL) or FF /4 (JMP).
		// Anything else is a rel32 against a label resolved by the assembler.
		if len(ops) == 1 {
			switch ops[0].(type) {
			case Reg, Mem:
				return e.encodeIndirectBranch(upper, ops)
			}
		}
		opcode := []byte{0xE8}
		if upper == "JMP" {
			opcode = []byte{0xE9}
		}
		return e.encodeJmpRel(ops, opcode)
	}
	if cc, ok := condCode(upper); ok {
		return e.encodeJcc(cc, ops)
	}
	// No-operand system and string-control instructions (CPUID, RDTSC,
	// SYSCALL, the fences, UNDEF, …).
	if op, ok := noOperandTable[upper]; ok {
		if len(ops) != 0 {
			return fmt.Errorf("%s takes no operands, got %d", upper, len(ops))
		}
		return e.emit(&instr{opcode: op, modrm: -1, sib: -1})
	}
	// One-operand system instructions whose reg field is a fixed digit:
	// the cache and wait controls under 0F AE/0F 1C and the RDPID read.
	if m, ok := sysUnaryTable[upper]; ok {
		return e.encodeSysUnary(upper, m, ops)
	}
	// The store-only SSE moves (the non-temporal store).
	if m, ok := sseStoreOnly[upper]; ok {
		return e.encodeSSEStoreOnly(upper, m, ops)
	}
	// POPFQ/PUSHFQ are exact names: the bare POPF/PUSHF and the L spellings
	// are rejected by go tool asm in 64-bit mode, so they stay unsupported.
	switch upper {
	case "POPFQ":
		if len(ops) != 0 {
			return fmt.Errorf("POPFQ takes no operands, got %d", len(ops))
		}
		return e.emit(&instr{opcode: []byte{0x9D}, modrm: -1, sib: -1})
	case "PUSHFQ":
		if len(ops) != 0 {
			return fmt.Errorf("PUSHFQ takes no operands, got %d", len(ops))
		}
		return e.emit(&instr{opcode: []byte{0x9C}, modrm: -1, sib: -1})
	case "INT":
		return e.encodeInt(ops)
	// The LOOP family outside the assembler's label settlement: the operand
	// is the already-computed rel8 (E0-E2).
	case "LOOP", "LOOPE", "LOOPNE":
		if len(ops) != 1 {
			return fmt.Errorf("%s expects 1 operand, got %d", upper, len(ops))
		}
		imm, ok := ops[0].(Imm)
		if !ok || !fits8(int64(imm)) {
			return fmt.Errorf("%s: relative offset must be a signed byte", upper)
		}
		return e.emit(&instr{opcode: []byte{loopOpcode(upper)}, modrm: -1, sib: -1, imm: []byte{byte(int8(imm))}})
	case "LDMXCSR":
		return e.encodeMxcsr(2, ops)
	case "STMXCSR":
		return e.encodeMxcsr(3, ops)
	// CMPSD is the scalar double compare, whose predicate immediate comes
	// LAST in Plan 9 order (src, dst, $imm); the family shares the shape.
	case "CMPSD":
		return e.encodeSSECmp("CMPSD", 0xF2, ops)
	case "CMPSS":
		return e.encodeSSECmp("CMPSS", 0xF3, ops)
	case "CMPPS":
		return e.encodeSSECmp("CMPPS", 0x00, ops)
	case "CMPPD":
		return e.encodeSSECmp("CMPPD", 0x66, ops)
	// RETFL pops the immediate's worth of bytes after the far return
	// (LRET iw: CA imm16), the toolchain's RETF spelling with a stack
	// adjustment.
	case "RETFL":
		if len(ops) != 1 {
			return fmt.Errorf("RETFL expects 1 operand, got %d", len(ops))
		}
		imm, ok := ops[0].(Imm)
		if !ok {
			return fmt.Errorf("RETFL expects an immediate")
		}
		return e.emit(&instr{opcode: []byte{0xCA}, modrm: -1, sib: -1, imm: le16(int64(imm))})
	// MOVDQ2Q/MOVQ2DQ cross the MMX and XMM banks (F2 0F D6), the register
	// in the reg field, the other bank's in r/m.
	case "MOVDQ2Q", "MOVQ2DQ":
		if len(ops) != 2 {
			return fmt.Errorf("%s expects 2 operands, got %d", upper, len(ops))
		}
		srcReg, ok1 := ops[0].(Reg)
		dstReg, ok2 := ops[1].(Reg)
		if !ok1 || !ok2 {
			return fmt.Errorf("%s takes register operands alone", upper)
		}
		if upper == "MOVDQ2Q" && (!srcReg.isVec() || !dstReg.mmx) ||
			upper == "MOVQ2DQ" && (!srcReg.mmx || !dstReg.isVec()) {
			return fmt.Errorf("%s crosses the XMM and MMX banks in that order", upper)
		}
		i := &instr{prefix: 0xF2, opcode: []byte{0x0F, 0xD6}, modrm: -1, sib: -1}
		if err := setRM(i, dstReg, srcReg, 8); err != nil {
			return err
		}
		return e.emit(i)
	// SHA256RNDS2 carries the round constant in a literal X0 first operand.
	case "SHA256RNDS2":
		return e.encodeSha256rnds2(ops)
	// BYTE, WORD, LONG and QUAD write the immediate into the text stream
	// itself: 1, 2, 4 or 8 literal bytes, little-endian.  END is accepted
	// and ignored.  ADJSP adjusts SP by the immediate, sign-chosen between
	// the SUBQ and ADDQ forms.
	case "BYTE", "WORD", "LONG", "QUAD":
		return e.encodeData(upper, ops)
	case "END":
		return e.encodeEnd(ops)
	case "ADJSP":
		return e.encodeAdjsp(ops)
	// The runtime's bookkeeping statements carry no text bytes: go tool asm
	// records FUNCDATA and PCDATA in the program list only, so the encoded
	// body shows nothing, on every architecture.
	case "FUNCDATA", "PCDATA":
		return e.encodeFuncdata(upper, ops)
	}

	// VEX (AVX/AVX2) and EVEX (AVX-512) instructions: the trailing
	// B/W/L/Q/D is part of the mnemonic, not a size suffix, so dispatch
	// before splitSize.  EVEX suffixes (.Z, .SAE, rounding, .BCST) split
	// off the mnemonic too.
	base, sfx, err := parseEvexSuffix(upper)
	if err != nil {
		return err
	}
	if isVex(base) || isEvex(base) || isKOp(base) || isGather(base) || isScatter(base) ||
		isEvexPrefGather(base) ||
		base == "KMOVW" || base == "KMOVQ" || base == "KMOVB" || base == "KMOVD" {
		return e.encodeVec(base, ops, sfx)
	}
	if sfx.any() {
		return fmt.Errorf("%s: the suffix requires an EVEX instruction", mnem)
	}

	// CMOVcc and SETcc carry the condition in the mnemonic (CMOVLGT, SETNE).
	if strings.HasPrefix(upper, "CMOV") {
		return e.encodeCmov(upper, ops)
	}
	if strings.HasPrefix(upper, "SET") {
		return e.encodeSet(upper, ops)
	}

	base, size := splitSize(upper)
	if size == 0 {
		size = 8 // default operand size in 64-bit mode (e.g. PUSHQ)
	}
	// Legacy SSE imm8 shuffles whose names end in W/H (PSHUFLW,
	// PSHUFHW) must dispatch BEFORE the size-suffix split, and the
	// others ride along.
	if m, ok := sseShufTable[upper]; ok {
		return e.encodeSSEShuf(m, ops)
	}
	// Legacy SSE packed binaries dispatch on the full name: the packed
	// integer mnemonics carry real width suffixes (PADDB/PCMPGTW/...),
	// which the size split must not eat.  A floating-point immediate
	// rewrites into a pooled-constant read on the scalar members.
	if m, ok := sseBinTable[upper]; ok {
		if f, isFloat := floatImmOperand(ops); isFloat {
			return e.encodeSSEFloatBin(upper, m, f, ops)
		}
		return e.encodeSSEBin(m, ops)
	}
	if m, ok := sseBinTable[base]; ok {
		if f, isFloat := floatImmOperand(ops); isFloat {
			return e.encodeSSEFloatBin(upper, m, f, ops)
		}
		return e.encodeSSEBin(m, ops)
	}
	// The imm8-controlled legacy instructions, the lane extracts and inserts
	// and the packed integer shifts all dispatch on the full name: a trailing
	// width letter here belongs to the mnemonic, not to the size split.
	if m, ok := sseImm3Table[upper]; ok {
		return e.encodeSSEImm3(m, ops)
	}
	if m, ok := sseExtractTable[upper]; ok {
		return e.encodeSSEExtract(m, ops)
	}
	if m, ok := sseInsertTable[upper]; ok {
		return e.encodeSSEInsert(m, ops)
	}
	if _, ok := sseShiftImm[upper]; ok {
		return e.encodeSSEShift(upper, ops)
	}
	// PMOVMSKB ends in a width letter the size split would eat, so it
	// dispatches on the full name like the packed binaries above.
	if upper == "PMOVMSKB" {
		return e.encodePmovmskb(upper, ops)
	}
	switch base {
	case "MOV":
		return e.encodeMov(ops, size)
	// MOVD is the Go assembler's alias of MOVQ: the same byte forms, 64-bit
	// REX.W and all.
	case "MOVD":
		return e.encodeMov(ops, 8)
	case "ADD", "SUB", "AND", "OR", "XOR", "CMP", "ADC", "SBB":
		return e.encodeALU(aluOp[base], ops, size)
	case "TEST":
		return e.encodeTest(ops, size)
	case "LEA":
		return e.encodeLea(ops, size)
	case "INC", "DEC", "NEG", "NOT", "MUL", "DIV", "IDIV":
		return e.encodeUnary(unaryOp[base], ops, size)
	case "SHL", "SHR", "SAR", "SAL", "ROL", "ROR", "RCL", "RCR":
		return e.encodeShift(base, ops, size)
	case "BT", "BTS", "BTR", "BTC":
		return e.encodeBitTest(base, ops, size)
	case "XCHG":
		return e.encodeExchange(ops, size)
	case "CMPXCHG":
		return e.encodeRegRegOp(0xB0, 0xB1, base, ops, size)
	case "XADD":
		return e.encodeRegRegOp(0xC0, 0xC1, base, ops, size)
	case "CRC32":
		return e.encodeCrc32(ops, size)
	case "ADCX":
		return e.encodeCarryExt(0x66, ops, size)
	case "ADOX":
		return e.encodeCarryExt(0xF3, ops, size)
	case "MOVS", "STOS":
		return e.encodeStringOp(base, ops, size)
	case "IMUL", "IMUL3":
		return e.encodeImul(ops, size)
	case "PUSH":
		return e.encodePushPop(ops, size, true)
	case "POP":
		return e.encodePushPop(ops, size, false)
	case "BSF", "BSR", "LZCNT", "TZCNT", "POPCNT":
		return e.encodeCount(base, ops, size)
	case "BSWAP":
		return e.encodeBswap(ops, size)
	case "PREFETCHNTA", "PREFETCHT0", "PREFETCHT1", "PREFETCHT2":
		return e.encodePrefetch(base, ops)
	case "MOVBLZX", "MOVBQZX", "MOVWLZX", "MOVWQZX", "MOVWLSX", "MOVLQSX",
		"MOVBWZX", "MOVBWSX", "MOVBLSX", "MOVBQSX", "MOVWQSX", "MOVLQZX":
		return e.encodeMovExtend(base, ops)
	case "CVTSL2SD", "CVTSQ2SD":
		return e.encodeCvtsi2sd(base == "CVTSQ2SD", ops)
	case "CVTSD2S", "CVTTSD2S", "CVTSS2S", "CVTTSS2S":
		return e.encodeCvtInt(base, ops, size)
	case "FMOVD":
		return e.encodeFmov(ops)
	case "MOVSD", "MOVSS":
		if f, isFloat := floatImmOperand(ops); isFloat {
			return e.encodeSSEFloatMove(upper, f, ops)
		}
		return e.encodeSSEMove(sseMoveTable[base], ops)
	case "MOVOU", "MOVO", "MOVOA", "MOVUPS", "MOVAPS", "MOVUPD", "MOVAPD":
		return e.encodeSSEMove(sseMoveTable[base], ops)
	}
	return fmt.Errorf("unsupported instruction %q", mnem)
}

// encodePrefetch emits the 0F 18 /r prefetch hints: the reg field selects
// the locality (NTA=0, T0=1, T1=2, T2=3) and the single operand is memory.
func (e *enc) encodePrefetch(base string, ops []Operand) error {
	if len(ops) != 1 {
		return fmt.Errorf("%s expects one memory operand", base)
	}
	m, ok := ops[0].(Mem)
	if !ok {
		return fmt.Errorf("%s requires a memory operand", base)
	}
	i := newInstr(0, []byte{0x0F, 0x18})
	if err := setMem(i, prefetchVariant[base], m); err != nil {
		return err
	}
	return e.emit(i)
}

var prefetchVariant = map[string]int{
	"PREFETCHNTA": 0,
	"PREFETCHT0":  1,
	"PREFETCHT1":  2,
	"PREFETCHT2":  3,
}

// dataWidth is the literal byte count of each data-emission pseudo-op.
var dataWidth = map[string]int{
	"BYTE": 1,
	"WORD": 2,
	"LONG": 4,
	"QUAD": 8,
}

// encodeData emits the literal-data pseudo-ops: BYTE, WORD, LONG and QUAD
// write the immediate into the text stream as 1, 2, 4 or 8 bytes,
// little-endian, with no opcode lookup.  The value is truncated to the
// width rather than range-checked, exactly as go tool asm behaves (BYTE
// $0x1FF emits FF, WORD $0x12345 emits 45 23, both without an error), and
// exactly one immediate is accepted: the toolchain rejects a list such as
// BYTE $1, $2, $3.
func (e *enc) encodeData(mnem string, ops []Operand) error {
	if len(ops) != 1 {
		return fmt.Errorf("%s expects 1 immediate operand, got %d", mnem, len(ops))
	}
	imm, ok := ops[0].(Imm)
	if !ok {
		return fmt.Errorf("%s requires an integer immediate", mnem)
	}
	width := dataWidth[mnem]
	out := make([]byte, width)
	u := uint64(imm)
	for i := range width {
		out[i] = byte(u >> (8 * i))
	}
	e.out = append(e.out, out...)
	return nil
}

// encodeFuncdata accepts-and-ignores the runtime bookkeeping statements:
// FUNCDATA $n, sym(SB) and PCDATA $n, $m.  go tool asm emits no text bytes
// for either (the entries live in the object's ancillary tables, not the
// function body), and the operand shapes it takes are exactly these: an
// integer count first, then a symbol reference for FUNCDATA and an integer
// value for PCDATA.  The other architectures accept-and-ignore the same
// statements; amd64 now matches.
func (e *enc) encodeFuncdata(upper string, ops []Operand) error {
	if len(ops) != 2 {
		return fmt.Errorf("%s expects 2 operands, got %d", upper, len(ops))
	}
	if _, ok := ops[0].(Imm); !ok {
		return fmt.Errorf("%s: first operand must be an integer immediate", upper)
	}
	switch upper {
	case "FUNCDATA":
		if _, ok := ops[1].(sbMem); !ok {
			return fmt.Errorf("FUNCDATA: second operand must be a symbol reference")
		}
	case "PCDATA":
		if _, ok := ops[1].(Imm); !ok {
			return fmt.Errorf("PCDATA: second operand must be an integer immediate")
		}
	}
	return nil
}

// encodeEnd accepts-and-ignores END.  go tool asm drops the statement
// entirely: the AEND Prog is skipped when the program list is flushed, so
// the statements after an END still belong to the same function and the
// encoded body carries no trace of it, whatever operands follow the name
// (the toolchain takes END $0 and END AX alike).  Zero bytes, no effect.
func (e *enc) encodeEnd(ops []Operand) error {
	return nil
}

// encodeAdjsp emits ADJSP $imm: a positive value is SUBQ $imm, SP, a
// negative one ADDQ $-imm, SP, in the imm8 or imm32 form the magnitude
// picks (the same selection subSP and addSP make for the frame).  go tool
// asm refuses ADJSP $0 outright, so a zero value is an error here too; the
// statement's effect on the SP balance is checked by the function-level
// assembly (checkAdjspBalance), as the toolchain's push/pop walk does.
func (e *enc) encodeAdjsp(ops []Operand) error {
	if len(ops) != 1 {
		return fmt.Errorf("ADJSP expects 1 immediate operand, got %d", len(ops))
	}
	imm, ok := ops[0].(Imm)
	if !ok {
		return fmt.Errorf("ADJSP requires an integer immediate")
	}
	switch v := int(imm); {
	case v > 0:
		e.out = append(e.out, subSP(v)...)
	case v < 0:
		e.out = append(e.out, addSP(-v)...)
	default:
		return fmt.Errorf("ADJSP $0 has no encoding")
	}
	return nil
}

// --- floating-point immediates ----------------------------------------------

// sseFloatImm lists the mnemonics whose first operand may be a floating-point
// immediate, the set go tool asm rewrites into a pooled-constant read: the
// scalar moves, the four scalar arithmetic pairs and the scalar compares.
// The packed members and the uniform forms (MAXSD, MINSD, SQRTSD, CMPSD)
// reject the immediate in the toolchain and are absent here on purpose.
var sseFloatImm = map[string]bool{
	"MOVSD": true, "MOVSS": true,
	"ADDSD": true, "ADDSS": true,
	"SUBSD": true, "SUBSS": true,
	"MULSD": true, "MULSS": true,
	"DIVSD": true, "DIVSS": true,
	"COMISD": true, "COMISS": true,
	"UCOMISD": true, "UCOMISS": true,
}

// floatImmOperand reports whether the operand list opens with a
// floating-point immediate in the two-operand spelling (imm, dst).
func floatImmOperand(ops []Operand) (FloatImm, bool) {
	if len(ops) != 2 {
		return FloatImm{}, false
	}
	f, ok := ops[0].(FloatImm)
	return f, ok
}

// floatPoolValue evaluates a floating-point immediate at the width its
// mnemonic encodes and names the pool constant the toolchain synthesises:
// $f64.<16 hex> for the doubles, $f32.<8 hex> for the singles (the float32
// rounding of the parsed value).  The name carries the IEEE-754 bits; the
// section holds them little-endian.
func floatPoolValue(mnem string, f FloatImm) (bits uint64, name string, err error) {
	v, err := strconv.ParseFloat(f.Text, 64)
	if err != nil {
		return 0, "", fmt.Errorf("invalid floating-point immediate %q", f.Text)
	}
	if f.Neg {
		v = -v
	}
	if strings.HasSuffix(mnem, "D") {
		bits = math.Float64bits(v)
		return bits, fmt.Sprintf("$f64.%016x", bits), nil
	}
	bits = uint64(math.Float32bits(float32(v)))
	return bits, fmt.Sprintf("$f32.%08x", bits), nil
}

// encodeSSEFloatMove encodes MOVSD/MOVSS with a floating-point immediate
// source.  A positive zero needs no memory read: the toolchain emits
// XORPS dst, dst.  Anything else loads the pooled constant RIP-relative
// ($f64.<hex>(SB) / $f32.<hex>(SB)), the displacement a patch site the
// file-level layout or the linker resolves.
func (e *enc) encodeSSEFloatMove(mnem string, f FloatImm, ops []Operand) error {
	if !sseFloatImm[mnem] {
		return fmt.Errorf("%s does not take a floating-point immediate", mnem)
	}
	dst, ok := ops[1].(Reg)
	if !ok || !dst.isVec() {
		return fmt.Errorf("%s: destination must be a vector register", mnem)
	}
	bits, name, err := floatPoolValue(mnem, f)
	if err != nil {
		return err
	}
	e.addFloatPool(name, bits, mwidth(mnem))
	if bits == 0 {
		i := &instr{opcode: []byte{0x0F, 0x57}, modrm: -1, sib: -1} // XORPS
		if err := setRM(i, dst, dst, 8); err != nil {
			return err
		}
		return e.emit(i)
	}
	m := sseMoveTable[mnem]
	i := &instr{prefix: m.prefix, opcode: []byte{0x0F, m.load}, modrm: -1, sib: -1}
	if err := setRM(i, dst, sbMem{size: mwidth(mnem), name: name}, 8); err != nil {
		return err
	}
	return e.emit(i)
}

// encodeSSEFloatBin encodes the scalar arithmetic and compare mnemonics with
// a floating-point immediate source: the constant is read from the pool into
// the instruction's r/m side (reg = destination), the rewrite go tool asm
// performs at the source level.
func (e *enc) encodeSSEFloatBin(mnem string, m sseBin, f FloatImm, ops []Operand) error {
	if !sseFloatImm[mnem] {
		return fmt.Errorf("%s does not take a floating-point immediate", mnem)
	}
	dst, ok := ops[1].(Reg)
	if !ok || !dst.isVec() {
		return fmt.Errorf("%s: destination must be a vector register", mnem)
	}
	bits, name, err := floatPoolValue(mnem, f)
	if err != nil {
		return err
	}
	e.addFloatPool(name, bits, mwidth(mnem))
	i := &instr{prefix: m.prefix, opcode: []byte{0x0F, m.op}, modrm: -1, sib: -1}
	if err := setRM(i, dst, sbMem{size: mwidth(mnem), name: name}, 8); err != nil {
		return err
	}
	return e.emit(i)
}

// mwidth returns the operand width a scalar SSE mnemonic encodes: the double
// spellings end in D, the single spellings in S.
func mwidth(mnem string) int {
	if strings.HasSuffix(mnem, "D") {
		return 8
	}
	return 4
}

// splitSize separates a trailing B/W/L/Q size suffix from the mnemonic.
func splitSize(upper string) (base string, size int) {
	if upper == "" {
		return upper, 0
	}
	switch upper[len(upper)-1] {
	case 'B':
		return upper[:len(upper)-1], 1
	case 'W':
		return upper[:len(upper)-1], 2
	case 'L':
		return upper[:len(upper)-1], 4
	case 'Q':
		return upper[:len(upper)-1], 8
	}
	return upper, 0
}

// encodeVec dispatches a VEX/EVEX mnemonic to the right encoding: KMOVW has
// its own direction-dependent opcodes; KTESTW is always VEX; everything else
// takes EVEX when an operand demands it (a ZMM or K register, or an
// EVEX-only mnemonic) and VEX otherwise.
func (e *enc) encodeVec(upper string, ops []Operand, sfx evexSuffix) error {
	if gs, ok := gatherTable[upper]; ok {
		return e.encodeGather(upper, gs, ops, sfx)
	}
	if ss, ok := scatterTable[upper]; ok {
		return e.encodeScatter(upper, ss, ops, sfx)
	}
	if upper == "KMOVW" || upper == "KMOVQ" || upper == "KMOVB" || upper == "KMOVD" {
		if sfx.any() {
			return fmt.Errorf("%s takes no EVEX suffixes", upper)
		}
		return e.encodeKmov(upper, ops)
	}
	if isKOp(upper) {
		if sfx.any() {
			return fmt.Errorf("%s takes no EVEX suffixes", upper)
		}
		return e.encodeKOp(upper, ops)
	}
	if upper == "KTESTW" || (!evexRequired(upper, ops) && !sfx.evexOnly()) {
		if sfx.any() {
			return fmt.Errorf("%s: the .Z suffix requires an EVEX instruction", upper)
		}
		return e.encodeVex(upper, ops)
	}
	return e.encodeEvex(upper, ops, sfx)
}

// --- instruction components -------------------------------------------------

type instr struct {
	opSize16  bool
	rexW      bool
	rexR      bool
	rexX      bool
	rexB      bool
	rexForced bool // REX needed even with all bits zero (8-bit low registers)
	prefix    byte // legacy 0xF2/0xF3 prefix (0 = none); emitted after 0x66
	opcode    []byte
	modrm     int // -1 if absent
	sib       int // -1 if absent
	disp      []byte
	imm       []byte
	sb        *sbRef // static-symbol displacement in disp, awaiting resolution
	tls       bool   // the displacement is a TLS slot offset, patched R_TLSLE
}

// sbRef records that an instruction's displacement refers to a static symbol
// rather than holding a literal value.
type sbRef struct {
	name   string
	addend int64
}

func (e *enc) emit(i *instr) error {
	if i.opSize16 {
		e.out = append(e.out, 0x66)
	}
	if i.prefix != 0 {
		e.out = append(e.out, i.prefix)
	}
	rex := byte(0)
	if i.rexW {
		rex |= 0x08
	}
	if i.rexR {
		rex |= 0x04
	}
	if i.rexX {
		rex |= 0x02
	}
	if i.rexB {
		rex |= 0x01
	}
	if rex != 0 || i.rexForced {
		e.out = append(e.out, 0x40|rex)
	}
	e.out = append(e.out, i.opcode...)
	if i.modrm >= 0 {
		e.out = append(e.out, byte(i.modrm))
	}
	if i.sib >= 0 {
		e.out = append(e.out, byte(i.sib))
	}
	if i.sb != nil {
		e.patches = append(e.patches, encPatch{off: len(e.out), name: i.sb.name, addend: i.sb.addend})
	}
	if i.tls {
		e.patches = append(e.patches, encPatch{off: len(e.out), tls: true})
	}
	e.out = append(e.out, i.disp...)
	e.out = append(e.out, i.imm...)
	return nil
}

// newInstr starts an instruction with a size-derived REX.W and 0x66 prefix.
func newInstr(opSize int, opcode []byte) *instr {
	return &instr{
		opSize16: opSize == 2,
		rexW:     opSize == 8,
		opcode:   opcode,
		modrm:    -1,
		sib:      -1,
	}
}

// --- ModR/M, SIB, displacement ----------------------------------------------

// setRM fills in the ModR/M (and SIB, displacement, REX bits) for an
// instruction whose reg field holds a real register `reg` and whose r/m field
// holds `rm`.
func setRM(i *instr, reg Reg, rm Operand, opSize int) error {
	return setRMReg(i, reg.idx&7, reg.idx >= 8, reg.needsREX(opSize), rm, opSize)
}

// setRMDigit fills in the ModR/M for an instruction whose reg field is an
// opcode /digit extension (0-7), which carries none of the register REX rules.
func setRMDigit(i *instr, digit int, rm Operand, opSize int) error {
	return setRMReg(i, digit, false, false, rm, opSize)
}

func setRMReg(i *instr, regField int, rexR, regForced bool, rm Operand, opSize int) error {
	i.rexR = rexR
	if regForced {
		i.rexForced = true
	}

	switch r := rm.(type) {
	case Reg:
		i.rexB = r.idx >= 8
		if r.needsREX(opSize) {
			i.rexForced = true
		}
		i.modrm = 0xC0 | regField<<3 | (r.idx & 7)
		return nil
	case Mem:
		return setMem(i, regField, r)
	case sbMem:
		// RIP-relative reference; the displacement is patched once the static
		// symbol's address is known.
		i.modrm = regField<<3 | 0x05 // mod=00, rm=101 → (RIP)+disp32
		i.disp = le32(0)
		i.sb = &sbRef{name: r.name, addend: r.addend}
		return nil
	case TLSMem:
		// off(TLS): the segment-prefixed absolute access, mod=00 with the
		// SIB escape's disp32 absolute form.  The displacement is the TLS
		// slot offset, patched by the linker's TLS relocation.
		i.prefix = r.Seg
		i.modrm = 0x04 | regField<<3
		i.sib = 0x25
		i.disp = le32(r.Disp)
		i.tls = true
		return nil
	case SegAbs:
		// 0x30(GS): the segment override with the SIB escape's disp32
		// absolute form, no relocation.
		setSegAbs(i, regField, r)
		return nil
	default:
		return fmt.Errorf("invalid r/m operand %T", rm)
	}
}

func setMem(i *instr, regField int, m Mem) error {
	if m.Seg != 0 {
		i.prefix = m.Seg
	}
	modrm, sib, disp, xBit, bBit, err := memComponents(regField, m)
	if err != nil {
		return err
	}
	i.modrm = modrm
	i.sib = sib
	i.disp = disp
	i.rexX = xBit == 1
	i.rexB = bBit == 1
	return nil
}

// setSegAbs assembles a segment-absolute operand, 0x30(GS): the segment
// override with the mod=00 SIB escape's disp32 absolute form and no
// relocation.
func setSegAbs(i *instr, regField int, m SegAbs) {
	i.prefix = m.Seg
	i.modrm = 0x04 | regField<<3
	i.sib = 0x25
	i.disp = le32(m.Disp)
}

// memComponents computes the ModR/M byte (with the given reg field), the SIB
// byte (-1 if none), the displacement bytes, and the high index/base bits, for
// a memory operand.  It is shared by the REX (scalar) and VEX (vector) paths.
func memComponents(regField int, m Mem) (modrm, sib int, disp []byte, xBit, bBit int, err error) {
	sib = -1
	// A displacement wider than int32 fits no encoding form; truncating it
	// would address a different location, and go tool asm reports "offset
	// too large" for the same operand.
	if m.Disp < -(1<<31) || m.Disp > (1<<31)-1 {
		return 0, -1, nil, 0, 0, fmt.Errorf("displacement %d does not fit in 32 bits", m.Disp)
	}
	// RIP-relative: neither base nor index.
	if !m.HasBase && !m.HasIndex {
		return regField<<3 | 0x05, -1, le32(m.Disp), 0, 0, nil // mod=00, rm=101
	}

	// The SIB scale field only encodes 1/2/4/8; the Go assembler rejects
	// anything else ("bad scale: 16"), so a silent fallback to scale 1 here
	// would mis-assemble the operand instead of reporting it.
	if m.HasIndex && m.Scale != 1 && m.Scale != 2 && m.Scale != 4 && m.Scale != 8 {
		return 0, -1, nil, 0, 0, fmt.Errorf("bad scale: %d", m.Scale)
	}

	needSIB := m.HasIndex || (m.HasBase && m.Base.idx&7 == 4)

	var mod int
	switch {
	case !m.HasBase:
		mod = 0
		disp = le32(m.Disp)
	case m.Base.idx&7 == 5 && m.Disp == 0:
		mod = 1
		disp = []byte{0}
	case m.Disp == 0:
		mod = 0
	case fits8(m.Disp):
		mod = 1
		disp = []byte{byte(int8(m.Disp))}
	default:
		mod = 2
		disp = le32(m.Disp)
	}

	if needSIB {
		idxField := 4 // 100 = no index
		if m.HasIndex {
			idxField = m.Index.idx & 7
			if m.Index.idx >= 8 {
				xBit = 1
			}
		}
		baseField := 5 // 101 = no base (with mod=00 → disp32)
		if m.HasBase {
			baseField = m.Base.idx & 7
			if m.Base.idx >= 8 {
				bBit = 1
			}
		}
		return mod<<6 | regField<<3 | 0x04, scaleBits(m.Scale)<<6 | idxField<<3 | baseField, disp, xBit, bBit, nil
	}

	if m.Base.idx >= 8 {
		bBit = 1
	}
	return mod<<6 | regField<<3 | (m.Base.idx & 7), -1, disp, 0, bBit, nil
}

func scaleBits(scale int) int {
	switch scale {
	case 2:
		return 1
	case 4:
		return 2
	case 8:
		return 3
	default:
		return 0 // scale 1 (or unset)
	}
}

func fits8(v int64) bool { return v >= -128 && v <= 127 }

func le32(v int64) []byte {
	u := uint32(v)
	return []byte{byte(u), byte(u >> 8), byte(u >> 16), byte(u >> 24)}
}

func le16(v int64) []byte {
	u := uint16(v)
	return []byte{byte(u), byte(u >> 8)}
}

func le64(v int64) []byte {
	u := uint64(v)
	b := make([]byte, 8)
	for i := range 8 {
		b[i] = byte(u >> (8 * i))
	}
	return b
}