disc_v/
instruction.rs

1// Copyright (c) 2026 Christopher Swenson
2// Licensed under the Apache-2.0 license.
3//
4// Derived from riscv-disassembler, Copyright (c) 2016-2017 Michael Clark
5// and Copyright (c) 2017-2018 SiFive, Inc., under the MIT license; see NOTICE.
6
7//! The decoded instruction type.
8
9use crate::Isa;
10use crate::format::Operands;
11use crate::opcodes::c::C_UNIMP;
12use crate::opcodes::{Codec, Opcode};
13
14/// A decoded instruction.
15///
16/// Create one with [`decode`](fn@crate::decode),
17/// [`decode_bytes`](crate::decode_bytes), or by iterating over
18/// [`disassemble`](crate::disassemble). Its [`Display`](core::fmt::Display)
19/// output follows GNU objdump's for a raw binary, such as `addi gp,gp,256`
20/// or `beqz a0,0x1040`.
21#[derive(Clone, Copy, Debug, PartialEq, Eq)]
22pub struct Instruction {
23    pub(crate) isa: Isa,
24    pub(crate) pc: u64,
25    pub(crate) inst: u64,
26    pub(crate) len: u8,
27    /// The opcode to show: expanded if compressed, and aliased if a
28    /// pseudoinstruction applies.
29    pub(crate) op: &'static Opcode,
30    /// The opcode as encoded, before expansion and aliasing.
31    pub(crate) decoded: &'static Opcode,
32    pub(crate) rd: u8,
33    pub(crate) rs1: u8,
34    pub(crate) rs2: u8,
35    pub(crate) rs3: u8,
36    pub(crate) rm: u8,
37    pub(crate) pred: u8,
38    pub(crate) succ: u8,
39    pub(crate) aq: bool,
40    pub(crate) rl: bool,
41    pub(crate) imm: i32,
42    /// For vector instructions, whether the operation is masked by `v0`.
43    pub(crate) masked: bool,
44    /// Whether floating-point operands are in the integer registers (Zfinx).
45    pub(crate) fp_in_x: bool,
46}
47
48impl Instruction {
49    pub(crate) fn new(isa: Isa, pc: u64, inst: u64, op: &'static Opcode) -> Self {
50        // Reserved lengths are shown one 16-bit parcel at a time so that
51        // disassembly can continue.
52        let len = crate::inst_length(inst as u16).unwrap_or(2) as u8;
53        Instruction {
54            isa,
55            pc,
56            inst,
57            len,
58            op,
59            decoded: op,
60            rd: 0,
61            rs1: 0,
62            rs2: 0,
63            rs3: 0,
64            rm: 0,
65            pred: 0,
66            succ: 0,
67            aq: false,
68            rl: false,
69            imm: 0,
70            masked: false,
71            fp_in_x: false,
72        }
73    }
74
75    /// The base ISA the instruction was decoded for.
76    pub fn isa(&self) -> Isa {
77        self.isa
78    }
79
80    /// The address of the instruction.
81    pub fn pc(&self) -> u64 {
82        self.pc
83    }
84
85    /// The instruction encoding, in the low [`length`](Self::length) bytes.
86    pub fn raw(&self) -> u64 {
87        self.inst
88    }
89
90    /// The length of the encoding in bytes: 2, 4, 6 or 8.
91    ///
92    /// Encodings with a reserved length (10 bytes or more) are decoded as a
93    /// 2-byte illegal instruction.
94    pub fn length(&self) -> usize {
95        self.len as usize
96    }
97
98    /// The mnemonic, such as `"addi"`, `"li"` or `"amoadd.w"`.
99    ///
100    /// An encoding that is not a valid instruction is shown as objdump shows
101    /// it, as an `.insn` directive (`.insn 4, 0x0911003b`), or as a `.2byte`
102    /// directive for a parcel of a reserved-length encoding. Use
103    /// [`is_illegal`](Self::is_illegal) to check for these.
104    ///
105    /// Compressed instructions are shown as the instruction they expand to,
106    /// and aliases (pseudoinstructions) are used where objdump uses them.
107    /// [`without_aliases`](Self::without_aliases) gives the instruction as
108    /// encoded. The mnemonic does not include the `.aq`/`.rl` ordering
109    /// suffixes of atomic instructions, which [`Display`](core::fmt::Display)
110    /// adds.
111    pub fn mnemonic(&self) -> &'static str {
112        self.op.name
113    }
114
115    /// The operands, without the mnemonic, such as `a0,8(sp)`.
116    pub fn operands(&self) -> Operands<'_> {
117        Operands(self)
118    }
119
120    /// Whether the encoding is not a valid instruction. This includes the
121    /// all-zeros 16-bit encoding, which the ISA defines to be illegal and
122    /// which is shown as `unimp`.
123    pub fn is_illegal(&self) -> bool {
124        self.op.codec == Codec::Illegal || *self.decoded == C_UNIMP
125    }
126
127    /// The same instruction, shown as encoded: compressed instructions keep
128    /// their `c.` names and pseudoinstructions are not used. This matches
129    /// `objdump -M no-aliases`.
130    pub fn without_aliases(&self) -> Instruction {
131        Instruction {
132            op: self.decoded,
133            ..*self
134        }
135    }
136
137    /// The target address of a PC-relative operand, wrapped to the
138    /// register width on RV32. Addresses are 64 bits, so on RV128 it is the
139    /// low 64 bits of the target.
140    pub(crate) fn target(&self) -> u64 {
141        let target = self.pc.wrapping_add(self.imm as i64 as u64);
142        match self.isa {
143            Isa::Rv32 => target & 0xffff_ffff,
144            Isa::Rv64 | Isa::Rv128 => target,
145        }
146    }
147}
disc_v/instruction.rs

disc_v/
instruction.rs
