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}