imperative_rs/
lib.rs

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