asmkit_core/
lib.rs

1//! The core behind AsmKit.
2
3use entity::LabelRef;
4
5pub mod entity;
6
7/// The output of an instruction stream.  Keeps tracks of any relocations.
8/// 
9/// TODO: implement relocations.
10#[derive(Clone, Debug, PartialEq)]
11pub struct Product {
12    /// The bytes produce by an instruction stream.
13    bytes: Vec<u8>,
14}
15
16impl Product {
17    /// Creates a new product initialized with the provided bytes.
18    pub fn new(bytes: Vec<u8>) -> Self {
19        Self { bytes }
20    }
21
22    /// Finalizes the instruction stream output and returns the produced bytes.
23    pub fn emit(self) -> Vec<u8> {
24        self.bytes
25    }
26}
27
28/// A target-specific stream of instructions.
29/// 
30/// An instruction stream inputs instructions and immediately encodes them into machine code for its respective target architecture.  Relocation is performed later.
31pub trait InstructionStream {
32    /// Creates a new label.
33    /// 
34    /// The label will be created without being attached to any index.  If the label is used before it is attached, it will be used as a relocation rather than
35    /// pre-calculating the offset.
36    fn create_label(&mut self) -> LabelRef;
37
38    /// Creates a new label and attaches it to the current index.
39    /// 
40    /// When the label is used, AsmKit will automatically calculate the offset of the label instead of creating a relocation.
41    fn create_label_attached(&mut self) -> LabelRef;
42
43    /// Attaches a label to the current index.
44    /// 
45    /// After attaching, AsmKit will automatically calculate the offset of the label instead of creating an unnecessary relocation for it.
46    /// 
47    /// This will overwrite any previous label at the provided reference.
48    fn attach_label(&mut self, label: LabelRef);
49
50    /// Writes a raw byte into the instruction stream at the current index.
51    fn write_byte(&mut self, byte: u8);
52
53    /// Writes a raw word into the instruction stream at the current index.
54    /// 
55    /// The value will be swapped into the endianness of the target, by the implementor of [`InstructionStream`].
56    fn write_word(&mut self, word: u16);
57
58    /// Writes a raw double word into the instruction stream at the current index.
59    /// 
60    /// The value will be swapped into the endianness of the target, by the implementor of [`InstructionStream`].
61    fn write_double_word(&mut self, word: u32);
62
63    /// Writes a raw quadruple word into the instruction stream at the current index.
64    /// 
65    /// The value will be swapped into the endianness of the target, by the implementor of [`InstructionStream`].
66    fn write_quad_word(&mut self, word: u64);
67
68    /// Writes a raw double quadruple word into the instruction stream at the current index.
69    /// 
70    /// The value will be swapped into the endianness of the target, by the implementor of [`InstructionStream`].
71    fn write_double_quad_word(&mut self, word: u128);
72
73    /// Finishes writing to the instruction stream and returns the produced bytes.
74    fn finish(self) -> Product;
75}
asmkit_core/lib.rs

asmkit_core/
lib.rs
