Crate yaxpeax_arch

Source
Expand description

§yaxpeax-arch

crate documentation

shared traits for architecture definitions, instruction decoders, and related interfaces for instruction decoders from the yaxpeax project.

typically this crate is only interesting if you’re writing code to operate on multiple architectures that all implement yaxpeax-arch traits. for example, yaxpeax-dis implements disassembly and display logic generic over the traits defined here, so adding a new decoder is usually only a one or two line addition.

yaxpeax-arch has several crate features, which implementers are encouraged to also support:

  • std: opt-in for std-specific support - in this crate, std enables a std::error::Error requirement on DecodeError, allowing users to ?-unwrap decode results.
  • color_new: enables traits and structs to stylize formatted instructions, including ANSI colorization.
  • colors: DEPRECATED. enables (optional) crossterm-based ANSI colorization. default coloring rules are defined by ColorSettings, when enabled.
  • address-parse: enable a requirement that yaxpeax_arch::Address be parsable from &str. this is useful for use cases that, for example, read addresses from humans.
  • use-serde: enable serde serialization and deserialization bounds for types like Address.

with all features disabled, yaxpeax-arch’s only direct dependency is num-traits, and is suitable for #![no_std] usage.

§design

yaxpeax-arch has backwards-incompatible changes from time to time, but there’s not much to make incompatible. the main benefit of this crate is the Arch trait, for other libraries to build architecture-agnostic functionality.

nontrivial additions to yaxpeax-arch should include some discussion summarized by an addition to the crate docs/. you may ask, “where does discussion happen?”, and the answer currently is in my (iximeow’s) head, or various discord/irc/discord/email conversations. if there’s need in the future, yaxpeax may develop a more consistent process.

yaxpeax-arch intends to support ad-hoc development of architecture support. maintainers of various architectures’ crates may not want to implement all available interfaces to a complete level of detail, and must not be required to. incomplete implementations may be an issue for downstream users, but library quality is mediated by human conversation, not yaxpeax-arch interfaces. extensions to these fundamental definitions should be considerate of partial and incomplete implementations.

§implementations

there are numerous architectures for which decoders are implemented, at varying levels of completion. now and in the future, they will be enumerated here:

symbolmeaning
🥳complete, reliable
⚠️“complete”, likely has gaps
🚧incomplete
❓unimplemented
architecturelibrarydecodetestsbenchmarksnote
x86_64yaxpeax-x86🥳🥳🥳
x86:32yaxpeax-x86🥳🥳❓sse and sse2 support cannot be disabled
x86:16yaxpeax-x86🥳🥳❓instructions above the 8086 or 286 cannot be disabled
ia64yaxpeax-ia64🥳⚠️❓lack of a good oracle has complicated testing
armv7yaxpeax-arm🚧🚧❓NEON is not yet supported
armv8yaxpeax-arm🚧🚧❓a32 decoding is not yet supported, NEON is not supported
m16cyaxpeax-m16c⚠️🚧❓
mipsyaxpeax-mips🚧🚧❓
msp430yaxpeax-msp430🚧🚧❓
pic17yaxpeax-pic17🚧🚧❓
pic18yaxpeax-pic18🚧🚧❓
pic24yaxpeax-pic24❓❓❓exists, but only decodes NOP
sm83yaxpeax-sm83🥳🚧❓
avryaxpeax-avr🥳🚧❓contributed by @the6p4c!
sh/sh2/j2/sh3/sh4yaxpeax-superh🥳🚧❓contributed by наб
MOS 6502yaxpeax-6502⚠️❓❓contributed by @cr1901
lc87yaxpeax-lc87🥳⚠️❓
§feature support

yaxpeax-arch defines a few typically-optional features that decoders can also implement, in addition to simple (bytes) -> instruction decoding. these are yaxpeax-arch traits (or collections thereof) which architectures implement, not crate features.

description_spans: implementation of AnnotatingDecoder, to decode instructions with bit-level details of what incoming bitstreams mean. contextualize: implementation of ShowContextual, to display instructions with user-defined information in place of default instruction data. typically expected to show label names instead of relative branch addresses. i do not recommend implementing this trait, it needs significant reconsideration.

architecturedescription_spanscontextualize
x86_64🥳❓
ia64⚠️❓
msp430🥳❓

§mirrors

the canonical copy of yaxpeax-arch is at https://git.iximeow.net/yaxpeax-arch.

yaxpeax-arch is also mirrored on GitHub at https://www.github.com/iximeow/yaxpeax-arch.

Modules§

annotation
traits (and convenient impls) for decoders that also produce descriptions of parsed bit fields.
color_new
display
safer_unchecked
tools to help validate correct use of unchecked functions.
testkit
utilities to validate that implementations of traits in yaxpeax-arch uphold requirements described in this crate.

Structs§

AddressDiff
a struct describing the differece between some pair of A: Address. this is primarily useful in describing the size of an instruction, or the relative offset of a branch.
AddressDisplayU16
AddressDisplayU32
AddressDisplayU64
AddressDisplayUsize
NoColorsDeprecated
U8Reader
a struct for Reader impls that can operate on units of u8.
U16be
U16le
U32be
U32le
U64be
U64le

Enums§

ReadError
StandardDecodeError
a minimal enum implementing DecodeError. this is intended to be enough for a low effort, low-fidelity error taxonomy, without boilerplate of a DecodeError implementation.
StandardPartialDecoderError
a slightly less minimal enum DecodeError. similar to StandardDecodeError, this is an anti-boilerplate measure. it additionally provides IncompleteDecoder, making it suitable to represent error kinds for decoders that are … not yet complete.

Traits§

AddrParse
Address
AddressBase
AddressBounds
AddressDiffAmount
AddressDisplay
Arch
a collection of associated type parameters that constitute the definitions for an instruction set. Arch provides an Instruction and its associated Operands, which is guaranteed to be decodable by this Arch::Decoder. Arch::Decoder can always be constructed with a Default implementation, and decodes from a Reader<Arch::Address, Arch::Word>.
ColorizeDeprecated
DecodeError
the minimum set of errors a yaxpeax-arch disassembler may produce.
DecodeErrorBounds
this is not a particularly interesting trait. it just exists to add a std::error::Error bound onto DecodeError for std builds.
Decoder
an interface to decode Arch::Instruction words from a reader of Arch::Words. errors are the architecture-defined DecodeError implemention.
Instruction
LengthedInstruction
instructions have lengths, and minimum possible sizes for advancing a decoder on error.
Reader
a trait defining how Item-sized words are read at Address-positioned offsets into some stream of data. for most uses, crate::U8Reader probably is sufficient. when reading from data sources that aren’t &[u8], Address isn’t a multiple of u8, or Item isn’t a multiple of 8 bits, U8Reader won’t be sufficient.
ReaderBuilder
a trait defining how to build a Reader<Address, Item> from some data source (Self). definitions of ReaderBuilder are provided for U8Reader on Address and Word types that yaxpeax_arch provides - external decoder implementations should also provide ReaderBuilder impls if they use custom Reader types.
ShowContextualDeprecated
YaxColorsDeprecated