Skip to main content

exarmo_core/
decode.rs

1//! The result of a decode in either runtime.
2
3use core::fmt;
4
5use crate::branch::Branch;
6use crate::flags::FlagEffect;
7use crate::tokens::TokenSink;
8
9/// A decoded instruction, whichever instruction set read it.
10///
11/// This lets a consumer of both instruction sets be written once, without
12/// naming either runtime's `Instruction`. It holds only what both instruction
13/// sets share. Register files, arrangements and data types belong to each
14/// runtime's own types.
15///
16/// [`decoded!`](crate::decoded) implements it for both runtimes.
17pub trait Decoded: fmt::Debug {
18    /// Write the instruction as tokens, as it reads at this address.
19    fn write_tokens_at(&self, address: u64, sink: &mut dyn TokenSink) -> fmt::Result;
20
21    /// The instruction's length in bytes. This is four in A64 and A32, and
22    /// two or four in T32.
23    fn length(&self) -> u8;
24
25    /// What the instruction does with the condition flags, as its Execute
26    /// pseudocode says.
27    fn flags(&self) -> FlagEffect;
28
29    /// What the instruction does to the flow of control, with any label
30    /// resolved against this address.
31    fn branch_at(&self, address: u64) -> Branch;
32
33    /// The encoding's name as the encoding index writes it, such as
34    /// `AddAddsubImm` or `ADC_r_A1`.
35    fn encoding_name(&self) -> &'static str;
36
37    /// Whether the word is CONSTRAINED UNPREDICTABLE, and still decodes as
38    /// the instruction.
39    fn unpredictable(&self) -> bool;
40}
41
42/// The suffix appended to the text of a CONSTRAINED UNPREDICTABLE instruction.
43pub const UNPREDICTABLE_MARK: &str = " (unpredictable)";
44
45/// Implements [`Decoded`] for a runtime's generated `Instruction`.
46#[macro_export]
47macro_rules! decoded {
48    ($instruction:ty) => {
49        impl $crate::decode::Decoded for $instruction {
50            fn write_tokens_at(
51                &self,
52                address: u64,
53                sink: &mut dyn $crate::tokens::TokenSink,
54            ) -> ::core::fmt::Result {
55                self.at(address).write_tokens(sink)
56            }
57
58            fn length(&self) -> u8 {
59                self.encoding().length()
60            }
61
62            fn flags(&self) -> $crate::flags::FlagEffect {
63                <$instruction>::flags(self)
64            }
65
66            fn branch_at(&self, address: u64) -> $crate::branch::Branch {
67                self.at(address).branch()
68            }
69
70            fn encoding_name(&self) -> &'static str {
71                self.encoding().name()
72            }
73
74            fn unpredictable(&self) -> bool {
75                <$instruction>::unpredictable(self)
76            }
77        }
78    };
79}
80
81/// Why a word decoded to no instruction, or why bytes held none.
82///
83/// Only the AArch32 encoding index marks rows UNPREDICTABLE or as reserved
84/// hints. The A64 index does not, so such words decode as `Unallocated`.
85#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
86pub enum DecodeError {
87    /// The architecture defines the encoding as UNDEFINED, which its own decode
88    /// pseudocode says by reaching `Undefined()`.
89    UNDEF,
90    /// The architecture defines the encoding as a NOP, which its own decode
91    /// pseudocode says by reaching `ExecuteAsNOP()`.
92    NOP,
93    /// The encoding is allocated to no instruction, either because no row of
94    /// the index claims it or because a field holds a value its value table
95    /// reserves.
96    Unallocated,
97    /// The index marks the encoding UNPREDICTABLE.
98    Unpredictable,
99    /// The index marks the encoding a reserved hint, which behaves as a NOP
100    /// and may be allocated later.
101    ReservedHint,
102    /// The bytes ended before the instruction did. Only a decode from bytes
103    /// returns this.
104    Truncated,
105}
106
107impl fmt::Display for DecodeError {
108    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
109        match self {
110            Self::UNDEF => f.write_str("UNDEFINED"),
111            Self::NOP => f.write_str("NOP"),
112            Self::Unallocated => f.write_str("UNALLOCATED"),
113            Self::Unpredictable => f.write_str("UNPREDICTABLE"),
114            Self::ReservedHint => f.write_str("reserved hint"),
115            Self::Truncated => f.write_str("truncated"),
116        }
117    }
118}
119
120impl core::error::Error for DecodeError {}