burst/
lib.rs

1// Licensed under the 2-Clause BSD license <LICENSE or
2// https://opensource.org/licenses/BSD-2-Clause>. This
3// file may not be copied, modified, or distributed
4// except according to those terms.
5
6//! # Burst
7//!
8//! Burst is a library supporting decomposing binary code
9//! into instructions, while maintaining detailed information
10//! about the instructions, their flags, and the operands. The
11//! result is a structure rather than textual strings.
12//!
13//! While Burst currently only supports x86 and x86_64 code,
14//! this will change in the near future and we anticipate adding
15//! many additional architectures.
16//!
17//! ## Goals of Burst:
18//!
19//! * Regular releases without waiting for long periods of time.
20//! * Uses fuzz testing to avoid crashes.
21//! * Well tested.
22//! * Fast. Few allocations and little data copying should be required.
23//!
24//! ## Installation
25//!
26//! This crate works with Cargo and is on
27//! [crates.io](https://crates.io/crates/burst).
28//! Add it to your `Cargo.toml` like so:
29//!
30//! ```toml
31//! [dependencies]
32//! burst = "0.0.3"
33//! ```
34//!
35//! Then, let `rustc` know that you're going to use this crate at the
36//! top of your own crate:
37//!
38//! ```
39//! extern crate burst;
40//! # fn main() {}
41//! ```
42//!
43//! ## Contributions
44//!
45//! Contributions are welcome.
46//!
47
48#![warn(missing_docs)]
49#![deny(trivial_numeric_casts, unstable_features,
50        unused_import_braces, unused_qualifications)]
51
52pub mod x86;
53
54/// An instruction operation.
55///
56/// This is description of the actual CPU operation that the
57/// instruction carries out.
58pub trait Operation {
59    /// The mnemonic for this instruction.
60    fn mnemonic(&self) -> &str;
61}
62
63/// An operand for an `Instruction`.
64pub trait Operand {}
65
66/// An decoded instruction, including an `Operation` and its
67/// `Operand`s.
68///
69/// An instruction represents the full amount of information that
70/// we have about the instruction that has been disassembled from
71/// the binary opcode data.
72pub trait Instruction {
73    /// The type of the operation for this instruction.
74    type Operation: Operation;
75
76    /// The type of the operands for this instruction.
77    type Operand: Operand;
78
79    /// The operation carried out by this instruction.
80    fn operation(&self) -> Self::Operation;
81
82    /// The mnemonic for this instruction.
83    fn mnemonic(&self) -> &str;
84
85    /// The operands for this instruction.
86    fn operands(&self) -> &[Self::Operand];
87
88    /// How many bytes in the binary opcode data are used by this
89    /// instruction.
90    ///
91    /// This can be used to continue disassembling at the next
92    /// instruction. An invalid instruction may have a value of
93    /// `0` here.
94    fn length(&self) -> usize;
95}
burst/lib.rs

burst/
lib.rs
