aboutsummaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authoriximeow <me@iximeow.net>2021-08-22 14:43:52 -0700
committeriximeow <me@iximeow.net>2021-08-22 14:43:52 -0700
commit02aead5a03b165930748e6a835a7da0e29d9538e (patch)
treecd602ef6e397736467bb01a16db3c6b6984239de /README.md
parent83f07b4e70efc45b2495d66a58f5d6ff0e5b7221 (diff)
document a bit of what yaxpeax-arch is all about, add README as crate docs
Diffstat (limited to 'README.md')
-rw-r--r--README.md24
1 files changed, 21 insertions, 3 deletions
diff --git a/README.md b/README.md
index c331f02..0304607 100644
--- a/README.md
+++ b/README.md
@@ -5,6 +5,24 @@
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](https://crates.io/crates/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`](https://doc.rust-lang.org/std/error/trait.Error.html) requirement on `DecodeError`, allowing users to `?`-unwrap decode results.
+* `colors`: enables (optional) [`crossterm`](https://docs.rs/crossterm/latest/crossterm/)-based ANSI colorization. default coloring rules are defined by [`ColorSettings`](https://docs.rs/yaxpeax-arch/latest/yaxpeax_arch/struct.ColorSettings.html), 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`](https://docs.rs/serde/latest/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`](https://docs.rs/yaxpeax-arch/latest/yaxpeax_arch/trait.Arch.html) 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/`](https://github.com/iximeow/yaxpeax-arch/tree/no-gods-no-/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:
@@ -37,9 +55,9 @@ there are numerous architectures for which decoders are implemented, at varying
| `MOS 6502` | [yaxpeax-6502](https://github.com/cr1901/yaxpeax-6502) | ⚠️ | ❓ | ❓ | contributed by [@cr1901](https://www.twitter.com/cr1901) |
| `lc87` | [yaxpeax-lc87](https://www.github.com/iximeow/yaxpeax-lc87) | 🥳 | ⚠️ | ❓ | |
-#### features
+#### feature support
-`yaxpeax-arch` defines a few typically-optional features that decoders can also implement, in addition to simple `(bytes) -> instruction` decoding. these are not crate features, but `yaxpeax-arch` trait impls or collections thereof.
+`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`](https://docs.rs/yaxpeax-arch/latest/yaxpeax_arch/trait.AnnotatingDecoder.html), to decode instructions with bit-level details of what incoming bitstreams mean.
`contextualize`: implementation of [`ShowContextual`](https://docs.rs/yaxpeax-arch/latest/yaxpeax_arch/trait.ShowContextual.html), 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.
@@ -47,7 +65,7 @@ there are numerous architectures for which decoders are implemented, at varying
| architecture | `description_spans` | `contextualize` |
| ------------ | ------------------- | --------------- |
| `x86_64` | 🥳 | ❓ |
-| `ia64` | 🥳 | ❓ |
+| `ia64` | ⚠️ | ❓ |
| `msp430` | 🥳 | ❓ |
### mirrors