asmcheck

Documentation

Overview

Package asmcheck validates hand-encoded ARM64 WORD directives against the instruction described in their comment. It decodes each 32-bit word with the same disassembler go tool objdump uses, so it runs on any architecture with no ARM hardware.

Index

• Constants
• func Decode(hex uint32) (string, error)
• func DisassembleWords(ctx context.Context, tool string, words []uint32) (map[uint32]string, error)
• func FindObjdump() string
• func Normalize(s string) string
• func ParseWordLine(line string) (hex uint32, comment string, ok bool)
• type CommentSource
• type Directive
  • func ScanSource(src string) []Directive
• type Result
  • func Verify(hex uint32, claimed string) Result
  • func VerifyDecoded(decoded, claimed string) Result
• type Status

Constants

const SIMDObjdumpEnv = "SIMD_OBJDUMP"

SIMDObjdumpEnv names an environment variable that, when set, overrides the objdump program used for the aarch64 cross-check (highest priority).

Functions

func Decode

func Decode(hex uint32) (string, error)

Decode returns the GNU-syntax disassembly of a 32-bit ARM64 instruction word.

func DisassembleWords

func DisassembleWords(ctx context.Context, tool string, words []uint32) (map[uint32]string, error)

DisassembleWords disassembles each 32-bit word with the given objdump, returning a map from instruction word to its GNU-syntax disassembly. Words are written little-endian (aarch64 byte order) and decoded with `-D -b binary -m aarch64`. Identical words collapse to a single map entry.

func FindObjdump

func FindObjdump() string

FindObjdump returns the path to an objdump that can disassemble aarch64 FP16 (.8H) instructions, or "" if none is usable. Each candidate is probed on a known instruction, so a wrong-architecture objdump (or a non-GNU one such as llvm-objdump that does not understand -m aarch64) is rejected rather than trusted.

func Normalize

func Normalize(s string) string

Normalize canonicalizes an instruction string for comparison: upper case, single-spaced, no space after commas, with aliased mnemonics folded.

func ParseWordLine

func ParseWordLine(line string) (hex uint32, comment string, ok bool)

ParseWordLine extracts the hex value and inline comment from a single assembly line. ok is false when the line is not a WORD $0x... directive.

Types

type CommentSource

type CommentSource int

CommentSource records where a directive's describing comment came from.

const (
	// NoComment means the WORD directive has no associated comment.
	NoComment CommentSource = iota
	// InlineComment means the comment is on the same line as the WORD.
	InlineComment
	// PrecedingComment means the comment is on the line directly above.
	PrecedingComment
)

type Directive

type Directive struct {
	Line    int    // 1-based line number
	Hex     uint32 // the 32-bit instruction word
	Comment string // the claimed instruction text, empty if NoComment
	Source  CommentSource
}

Directive is one parsed WORD $0x... line with its associated comment.

func ScanSource

func ScanSource(src string) []Directive

ScanSource parses every WORD $0x... directive in src, associating each with its inline comment, or the comment on the line directly above it.

type Result

type Result struct {
	Status  Status
	Decoded string // normalized decoded instruction (empty when Undecodable)
	Claimed string // normalized claimed instruction
	Err     error  // decode error when Undecodable
}

Result is the outcome of Verify.

func Verify

func Verify(hex uint32, claimed string) Result

Verify decodes hex and checks it against the claimed instruction text. The decoded instruction must equal the claim or be a token-boundary prefix of it, so comments may carry a trailing free-form annotation after the operands.

func VerifyDecoded

func VerifyDecoded(decoded, claimed string) Result

VerifyDecoded checks an already-decoded instruction string against the claimed instruction text, using the same normalization and token-boundary prefix rule as Verify. It lets callers supply a disassembly from a source other than arm64asm (for example aarch64 objdump, see objdump.go) while sharing one comparison policy. The status is never Undecodable: the input is already decoded, so the result is either Match or Mismatch.

type Status

type Status int

Status is the outcome of verifying one WORD directive.

const (
	// Match means the decoded instruction matches the comment.
	Match Status = iota + 1
	// Mismatch means the bytes decode to a different instruction than claimed.
	Mismatch
	// Undecodable means the disassembler could not decode the bytes.
	Undecodable
)