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,
DecodeError, allowing users to
?-unwrap decode results.
colors: enables (optional)
crossterm-based ANSI colorization. default coloring rules are defined by
ColorSettings, when enabled.
address-parse: enable a requirement that
yaxpeax_arch::Addressbe parsable from
&str. this is useful for use cases that, for example, read addresses from humans.
serdeserialization and deserialization bounds for types like
with all features disabled,
yaxpeax-arch’s only direct dependency is
num-traits, and is suitable for
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.
there are numerous architectures for which decoders are implemented, at varying levels of completion. now and in the future, they will be enumerated here:
|⚠️||“complete”, likely has gaps|
|yaxpeax-x86||🥳||🥳||❓||sse and sse2 support cannot be disabled|
|yaxpeax-x86||🥳||🥳||❓||instructions above the 8086 or 286 cannot be disabled|
|yaxpeax-ia64||🥳||⚠️||❓||lack of a good oracle has complicated testing|
|yaxpeax-arm||🚧||🚧||❓||NEON is not yet supported|
|yaxpeax-arm||🚧||🚧||❓||a32 decoding is not yet supported, NEON is not supported|
|yaxpeax-pic24||❓||❓||❓||exists, but only decodes |
|yaxpeax-avr||🥳||🚧||❓||contributed by @the6p4c!|
|yaxpeax-superh||🥳||🚧||❓||contributed by наб|
|yaxpeax-6502||⚠️||❓||❓||contributed by @cr1901|
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.
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.
traits (and convenient impls) for decoders that also produce descriptions of parsed bit fields.
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.
a struct for
Reader impls that can operate on units of
a minimal enum implementing
DecodeError. this is intended to be enough for a low effort,
low-fidelity error taxonomy, without boilerplate of a
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.
a collection of associated type parameters that constitute the definitions for an instruction
Arch provides an
Instruction and its associated
Operands, which is guaranteed to be
decodable by this
Arch::Decoder can always be constructed with a
implementation, and decodes from a
the minimum set of errors a
yaxpeax-arch disassembler may produce.
this is not a particularly interesting trait. it just exists to add a
instructions have lengths, and minimum possible sizes for advancing a decoder on error.
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
Address isn’t a multiple of
isn’t a multiple of 8 bits,
U8Reader won’t be sufficient.
a trait defining how to build a
Reader<Address, Item> from some data source (
ReaderBuilder are provided for
Word types that
yaxpeax_arch provides - external decoder implementations should also provide
impls if they use custom