1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77
#![deny(missing_docs)] //! This crate provides the `InstructionSet`-trait and corresponding error types, as well as //! a procedural macro automatically derive the trait for `enum`s. A type implementing //! `InstructionSet` provides `fn InstructionSet::decode(...) -> {...}` to decode instructions from a `&[u8]` //! and `fn InstructionSet::encode(...) -> {...}` to encode and write an instruction into a `&[u8]`. //!```rust //! use imperative_rs::InstructionSet; //! //!#[derive(InstructionSet, PartialEq, Debug)] //!enum Is { //! //constant opcode //! #[opcode = "0x0000"] //! Nop, //! //hex opcode with split variable x //! #[opcode = "0x1x0x"] //! Inc{x:u8}, //! //hex opcode with three renamed variables //! #[ opcode = "0x2xxyyzz" ] //! Add{ //! #[variable = "x"] //! reg:u8, //! #[variable = "y"] //! lhs:u8, //! #[variable = "z"] //! rhs:u8}, //! //bin opcode with two variables and underscores for readability //! #[ opcode = "0b100000000_xxxxyyyy_xyxyxyxy" ] //! Mov{x:u8, y:i8}, //!} //! //!fn main() { //! let mut mem = [0u8; 1024]; //! let (num_bytes, instr) = Is::decode(&mem).unwrap(); //! assert_eq!(num_bytes, 2); //! assert_eq!(instr, Is::Nop); //! let instruction = Is::Add{reg:0xab, lhs:0xcd, rhs:0xef}; //! assert_eq!(4, instruction.encode(&mut mem[100..]).unwrap()); //! assert_eq!([0x2a, 0xbc, 0xde, 0xf0], mem[100..104]) //!} //!``` #[doc(hidden)] pub use imperative_rs_derive::*; /// This type is returned by `fn InstructionSet::decode(...)` in case no instruction could be /// decoded. #[derive(Debug, PartialEq, PartialOrd)] pub enum DecodeError { /// This variant is emitted if the slice contains no known opcode. UnknownOpcode, /// Is emitted if the slice ended before a complete opcode could be found. Extending the end /// of the slice could lead to successful decoding. UnexpectedEOF, /// Is emitted when the target variable overflows during decoding. /// Overflows should be caught at compiletime so encountering this error is currently a bug. /// This might change in the future. Overflow, } /// This Type is returned by `fn InstructionSet::encode(...) -> {...}` when the instruction could not /// be encoded. #[derive(Debug, PartialEq, PartialOrd)] pub enum EncodeError { /// Instruction couldn't be encoded because the provided buffer was too short. UnexpectedEOF, } /// This `trait` defines an instruction set. It provides functionality to decode from or encode to /// opcodes. It can be autoderived for suitable `enum`s by a procedual macro provided by this crate. pub trait InstructionSet: std::marker::Sized { /// Used to decode an instruction (i.e. `Self`) from a byte buffer. The buffer needs to be /// provided as a `&[u8]` and the function returns a result containing either a tuple containing /// the number of bytes written and the resulting instruction or an `DecodeError`. fn decode(mem: &[u8]) -> Result<(usize, Self), DecodeError>; /// Used to encode instructions into a byte buffer. The buffer needs to be provided as a /// `&mut [u8]`. The function returns a result containing either the number of bytes read or an /// `EncodeError` fn encode(&self, buf: &mut [u8]) -> Result<usize, EncodeError>; }