diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/annotation/mod.rs | 131 | ||||
| -rw-r--r-- | src/color.rs | 5 | ||||
| -rw-r--r-- | src/lib.rs | 16 | ||||
| -rw-r--r-- | src/reader.rs | 10 |
4 files changed, 155 insertions, 7 deletions
diff --git a/src/annotation/mod.rs b/src/annotation/mod.rs new file mode 100644 index 0000000..0248b94 --- /dev/null +++ b/src/annotation/mod.rs @@ -0,0 +1,131 @@ +//! traits (and convenient impls) for decoders that also produce descriptions of parsed bit fields. +//! +//! the design of this API is discussed in [`yaxpeax-arch` +//! documentation](https://github.com/iximeow/yaxpeax-arch/blob/no-gods-no-/docs/0001-AnnotatingDecoder.md#descriptionsink). +//! +//! ## usage +//! +//! [`AnnotatingDecoder::decode_with_annotation`] decodes an instruction much like +//! [`crate::Decoder::decode_into`], but also reports descriptions of bit fields to a provided +//! [`DescriptionSink`]. [`VecSink`] is likely the `DescriptionSink` of interest to retain fields; +//! decoders are not required to make any guarantees about the order of descriptions, either by the +//! description's associated [`FieldDescription::id`], or with respect to the bits a +//! `FieldDescription` is reported against. fields may be described by multiple `FieldDescription` +//! with matching `id` and `desc` -- this is to describe data in an instruction where +//! non-contiguous bits are taken together for a single detail. for these cases, the various +//! `FieldDescription` must compare equal, and users of `yaxpeax-arch` can rely on this equivalence +//! for grouping bit ranges. +//! +//! in a generic setting, there isn't much to do with a `FieldDescription` other than display it. a +//! typical use might look something like: +//! ``` +//! use core::fmt; +//! +//! use yaxpeax_arch::annotation::{AnnotatingDecoder, VecSink}; +//! use yaxpeax_arch::{Arch, Reader, U8Reader}; +//! +//! fn show_field_descriptions<A: Arch>(decoder: A::Decoder, buf: &[u8]) +//! where +//! A::Decoder: AnnotatingDecoder<A>, +//! A::Instruction: fmt::Display, for<'data> U8Reader<'data>: Reader<A::Address, A::Word>, +//! { +//! let mut inst = A::Instruction::default(); +//! let mut reader = U8Reader::new(buf); +//! let mut sink: VecSink<<A::Decoder as AnnotatingDecoder<A>>::FieldDescription> = VecSink::new(); +//! +//! decoder.decode_with_annotation(&mut inst, &mut reader, &mut sink).unwrap(); +//! +//! println!("decoded instruction {}", inst); +//! for (start, end, desc) in sink.records.iter() { +//! println!(" bits [{}, {}]: {}", start, end, desc); +//! } +//! } +//! ``` +//! +//! note that the range `[start, end]` for a reported span is _inclusive_. the `end`-th bit of a +//! an instruction's bit stream is described by the description. +//! +//! ## implementation guidance +//! +//! the typical implementation pattern is that an architecture's `Decoder` implements [`crate::Decoder`] +//! _and_ [`AnnotatingDecoder`], then callers are free to choose which style of decoding they want. +//! [`NullSink`] has a blanket impl of [`DescriptionSink`] for all possible descriptions, and +//! discards reported field descriptions. `decode_with_annotation` with annotations reported to a +//! `NullSink` must be functionally identical to a call to `Decoder::decode_into`. +//! +//! the important points: +//! +//! * `AnnotatingDecoder` is an **optional** implementation for decoders. +//! * `FieldDescription` in general is oriented towards human-directed output, but implementations +//! can be as precise as they want. +//! * since bit/byte order varies from architecture to architecture, a field's `start` and `end` +//! are defined with some ordering from the corresponding decoder crate. crates should describe the +//! bit ordering they select, and where possible, the bit ordering they describe should match +//! relevant ISA mauals. +//! * `FieldDescription` that return true for [`FieldDescription::is_separator`] are an exception +//! to bit span inclusivity: for these descriptions, the bit range should be `[b, b]` where `b` is +//! the last bit before the boundary being delimited. unlike other descriptions, `is_separator` +//! descriptions describe the space between bits `b` and `b+1`. +//! * if a description is to cover multiple bit fields, the reported `FieldDescription` must +//! be identical on `id` and `desc` for all involved bit fields. + +use crate::{Arch, Reader}; + +use core::fmt::Display; + +/// implementors of `DescriptionSink` receive descriptions of an instruction's disassembly process +/// and relevant offsets in the bitstream being decoded. descriptions are archtecture-specific, and +/// architectures are expected to be able to turn the bit-level `start` and `width` values into a +/// meaningful description of bits in the original instruction stream. +pub trait DescriptionSink<Descriptor> { + /// inform this `DescriptionSink` of a `description` that was informed by bits `start` to + /// `end` from the start of an instruction's decoding. `start` and `end` are only relative the + /// instruction being decoded when this sink `DescriptionSink` provided, so they will have no + /// relation to the position in an underlying data stream used for past or future instructions. + fn record(&mut self, start: u32, end: u32, description: Descriptor); +} + +pub struct NullSink; + +impl<T> DescriptionSink<T> for NullSink { + fn record(&mut self, _start: u32, _end: u32, _description: T) { } +} + +#[cfg(feature = "std")] +pub struct VecSink<T: Clone + Display> { + pub records: std::vec::Vec<(u32, u32, T)> +} + +#[cfg(feature = "std")] +impl<T: Clone + Display> VecSink<T> { + pub fn new() -> Self { + VecSink { records: std::vec::Vec::new() } + } +} + +#[cfg(feature = "std")] +impl<T: Clone + Display> DescriptionSink<T> for VecSink<T> { + fn record(&mut self, start: u32, end: u32, description: T) { + self.records.push((start, end, description)); + } +} + +pub trait FieldDescription { + fn id(&self) -> u32; + fn is_separator(&self) -> bool; +} + +/// an interface to decode [`Arch::Instruction`] words from a reader of [`Arch::Word`]s, with the +/// decoder able to report descriptions of bits or fields in the instruction to a sink implementing +/// [`DescriptionSink`]. the sink may be [`NullSink`] to discard provided data. decoding with a +/// `NullSink` should behave identically to `Decoder::decode_into`. implementors are recommended to +/// implement `Decoder::decode_into` as a call to `AnnotatingDecoder::decode_with_annotation` if +/// implementing both traits. +pub trait AnnotatingDecoder<A: Arch + ?Sized> { + type FieldDescription: FieldDescription + Clone + Display + PartialEq; + + fn decode_with_annotation< + T: Reader<A::Address, A::Word>, + S: DescriptionSink<Self::FieldDescription> + >(&self, inst: &mut A::Instruction, words: &mut T, sink: &mut S) -> Result<(), A::DecodeError>; +} diff --git a/src/color.rs b/src/color.rs index c35f482..e7cb60c 100644 --- a/src/color.rs +++ b/src/color.rs @@ -13,6 +13,7 @@ impl <T: Display> Display for Colored<T> { fn fmt(&self, fmt: &mut Formatter) -> fmt::Result { match self { Colored::Color(t, before) => { + use crossterm::style::Stylize; write!(fmt, "{}", style::style(t).with(*before)) }, Colored::Just(t) => { @@ -136,12 +137,10 @@ mod termion_color { use crossterm::style; - use serde::Serialize; - use crate::color::{Colored, YaxColors}; #[cfg(feature="use-serde")] - impl Serialize for ColorSettings { + impl serde::Serialize for ColorSettings { fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> { use serde::ser::SerializeStruct; let s = serializer.serialize_struct("ColorSettings", 0)?; @@ -1,4 +1,5 @@ #![no_std] +#![doc = include_str!("../README.md")] use core::fmt::{self, Debug, Display}; use core::hash::Hash; @@ -15,6 +16,8 @@ pub use address::{AddressDisplayUsize, AddressDisplayU64, AddressDisplayU32, Add #[cfg(feature="address-parse")] pub use address::AddrParse; +pub mod annotation; + mod color; pub use color::{Colorize, NoColors, YaxColors}; @@ -124,17 +127,26 @@ impl DecodeError for StandardPartialDecoderError { } } +#[derive(Copy, Clone)] +struct NoDescription {} + +impl fmt::Display for NoDescription { + fn fmt(&self, _: &mut fmt::Formatter) -> fmt::Result { + Ok(()) + } +} + /// an interface to decode [`Arch::Instruction`] words from a reader of [`Arch::Word`]s. errors are /// the architecture-defined [`DecodeError`] implemention. pub trait Decoder<A: Arch + ?Sized> { - /// decode one instruction for this architecture from the [`yaxpeax_arch::Reader`] of this + /// decode one instruction for this architecture from the [`crate::Reader`] of this /// architecture's `Word`. fn decode<T: Reader<A::Address, A::Word>>(&self, words: &mut T) -> Result<A::Instruction, A::DecodeError> { let mut inst = A::Instruction::default(); self.decode_into(&mut inst, words).map(|_: ()| inst) } - /// decode one instruction for this architecture from the [`yaxpeax_arch::Reader`] of this + /// decode one instruction for this architecture from the [`crate::Reader`] of this /// architecture's `Word`, writing into the provided `inst`. /// /// SAFETY: diff --git a/src/reader.rs b/src/reader.rs index acb0146..028d835 100644 --- a/src/reader.rs +++ b/src/reader.rs @@ -1,4 +1,4 @@ -use crate::StandardDecodeError; +use crate::{StandardDecodeError, StandardPartialDecoderError}; impl From<ReadError> for StandardDecodeError { fn from(_: ReadError) -> StandardDecodeError { @@ -6,6 +6,12 @@ impl From<ReadError> for StandardDecodeError { } } +impl From<ReadError> for StandardPartialDecoderError { + fn from(_: ReadError) -> StandardPartialDecoderError { + StandardPartialDecoderError::ExhaustedInput + } +} + #[derive(Debug, PartialEq, Eq, Copy, Clone)] pub enum ReadError { ExhaustedInput, @@ -13,7 +19,7 @@ pub enum ReadError { } /// a trait defining how `Item`-sized words are read at `Address`-positioned offsets into some -/// stream of data. for *most* uses, [`yaxpeax_arch::U8Reader`] probably is sufficient. when +/// 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. pub trait Reader<Address, Item> { |