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 {}