disasm

Documentation

Overview

Package disasm wraps golang.org/x/arch to provide a uniform decoder across x86, x86-64, ARM64, RISC-V 64, 32-bit ARM, PowerPC (32- and 64-bit, both endians), s390x and LoongArch 64.

Index

• Constants
• func FindAddrOperand(text string, from int) (addr uint64, start, end int, ok bool)
• func HasExact(insts []Inst, addr uint64) bool
• func IndexAtOrAfter(insts []Inst, addr uint64) int
• func IndexForAddr(insts []Inst, addr uint64) (idx int, ok bool)
• func IsAddrLoad(op string) bool
• func MaxInstLen(a Arch) int
• func Mnemonic(text string) string
• func RangeFunc(d Disassembler, code []byte, addr uint64, fn func(Inst) bool)
• type Arch
• type Disassembler
  • func For(a Arch) (Disassembler, error)
• type Inst
  • func Range(d Disassembler, code []byte, addr uint64, maxInst int) []Inst
• type InstClass
  • func Classify(text string) InstClass

Constants

const (
	ArchUnknown = arch.ArchUnknown
	ArchX86     = arch.ArchX86
	ArchAMD64   = arch.ArchAMD64
	ArchARM64   = arch.ArchARM64
	ArchRISCV64 = arch.ArchRISCV64
	ArchARM     = arch.ArchARM
	ArchPPC64   = arch.ArchPPC64
	ArchPPC64LE = arch.ArchPPC64LE
	ArchS390X   = arch.ArchS390X
	ArchLoong64 = arch.ArchLoong64
	ArchPPC     = arch.ArchPPC
	ArchPPCLE   = arch.ArchPPCLE
)

Functions

func FindAddrOperand

func FindAddrOperand(text string, from int) (addr uint64, start, end int, ok bool)

FindAddrOperand finds the first 0x-prefixed hex literal in an instruction's operand text at or after `from`, returning its value and the byte range it occupies. It is the primitive under address highlighting, target annotation, branch following and the xref scan, all of which then ask the binary whether the value is actually mapped.

A "0x…" immediately preceded by '#' is an ARM immediate ("[sp,#0x8]", "mov x0,#0x10"), never an address, and is skipped. Nothing else is filtered here: an x86 AT&T immediate is written "$0x401000" and genuinely can be an address load, so the caller's mapped-address check is what separates the two.

func HasExact

func HasExact(insts []Inst, addr uint64) bool

HasExact reports whether an instruction starts exactly at addr. It is stricter than IndexForAddr's ok, which also accepts an address inside an instruction's bytes.

func IndexAtOrAfter

func IndexAtOrAfter(insts []Inst, addr uint64) int

IndexAtOrAfter returns the first instruction at or after addr, falling back to the last preceding instruction when there is no later one — so a caller scrolling to an address past the decoded window still lands on real code.

func IndexForAddr

func IndexForAddr(insts []Inst, addr uint64) (idx int, ok bool)

IndexForAddr finds the instruction covering addr, or the nearest one at a lower address. ok reports whether addr actually falls within the returned instruction's bytes (or is exactly its start).

When addr precedes every instruction, it returns (0, false).

func IsAddrLoad

func IsAddrLoad(op string) bool

IsAddrLoad reports whether op materialises an address (so its operand is worth annotating with the symbol/section it points at).

func MaxInstLen

func MaxInstLen(a Arch) int

MaxInstLen returns the longest instruction encoding (in bytes) for an architecture, used to size the byte column in disassembly views. Fixed-length RISC ISAs need only their word size, so their column is much narrower than the variable-length x86 cap; an unknown arch falls back to the x86 cap.

func Mnemonic

func Mnemonic(text string) string

Mnemonic returns the instruction's first whitespace-delimited token, lowered.

func RangeFunc

func RangeFunc(d Disassembler, code []byte, addr uint64, fn func(Inst) bool)

RangeFunc walks the buffer and decodes instructions, calling fn for each (a "(bad)" placeholder of Step() bytes on a decode error). It stops early when fn returns false, so callers can stream output without buffering every decoded instruction (used by the whole-binary disassembly dump).

Types

type Arch

type Arch = arch.Arch

Arch aliases the shared architecture selector used by binary loaders.

type Disassembler

type Disassembler interface {
	Decode(code []byte, addr uint64) (Inst, error)
	// Step is the minimum sane re-sync stride when decode fails.
	Step() int
	// Name is a short identifier ("x86-64", "arm64", ...).
	Name() string
}

Disassembler decodes a single instruction at code[0] for VM address addr. On failure the caller should advance by Step() bytes and try again.

func For

func For(a Arch) (Disassembler, error)

For returns a single-instruction decoder for a supported architecture.

type Inst

type Inst struct {
	Addr  uint64
	Bytes []byte
	Text  string
	Class InstClass
}

Inst is one decoded instruction.

func Range

func Range(d Disassembler, code []byte, addr uint64, maxInst int) []Inst

Range walks the buffer and decodes instructions until it's exhausted (or maxInst is reached, when > 0). On a decode error, it emits a "(bad)" placeholder of Step() bytes and continues.

type InstClass

type InstClass uint8

InstClass classifies an instruction's high-level role so the UI can colour it appropriately. Classification is done from the rendered mnemonic, which keeps the logic uniform across architectures (and means GAS pseudos like `ret` and `j` on RISC-V get picked up correctly).

const (
	ClassOther InstClass = iota
	ClassCall
	ClassRet
	ClassJumpCond
	ClassJumpUnc
	ClassSyscall
	ClassNop
	ClassMove
	ClassArithmetic
)

func Classify

func Classify(text string) InstClass

Classify maps a rendered instruction's mnemonic to an InstClass. Exported so callers that already hold an Inst.Text (e.g. after Range) can re-classify.