1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
use std::ops::Range;
use probe_rs::{
CoreDump, CoreInterface, CoreRegister, CoreRegisters, Error, RegisterDataType, RegisterId,
RegisterRole, RegisterValue,
};
use serde::Serialize;
/// Stores the relevant information from [`crate::core::CoreRegister`] for use in debug operations,
/// as well as additional information required during debug.
#[derive(Debug, Clone, PartialEq, Serialize)]
pub struct DebugRegister {
/// To lookup platform specific details of core register definitions.
pub core_register: &'static CoreRegister,
/// [DWARF](https://dwarfstd.org) specification, section 2.6.1.1.3.1 "... operations encode the names of up to 32 registers, numbered from 0 through 31, inclusive ..."
pub dwarf_id: Option<u16>,
/// The value of the register is read from the target memory and updated as needed.
pub value: Option<RegisterValue>,
}
impl DebugRegister {
/// Test if this register role suggests that the value is a reference to an address in memory.
pub(crate) fn is_pointer(&self) -> bool {
for role in self.core_register.roles.iter() {
if matches!(
role,
RegisterRole::ProgramCounter
| RegisterRole::FramePointer
| RegisterRole::StackPointer
| RegisterRole::ReturnAddress
| RegisterRole::MainStackPointer
| RegisterRole::ProcessStackPointer
) {
return true;
}
}
false
}
/// Return the memory range required to read the register value.
pub fn memory_range(&self) -> Result<Option<Range<u64>>, Error> {
if self.is_pointer()
&& let Some(mut register_value) = self.value
{
let start_address: u64 = register_value.try_into()?;
register_value.increment_address(self.core_register.size_in_bytes())?;
let end_address: u64 = register_value.try_into()?;
return Ok(Some(Range {
start: start_address,
end: end_address,
}));
}
Ok(None)
}
/// A helper function to determine if the contained register value is equal to the maximum value that can be stored in that datatype.
/// Will return false if the value is `None`
pub(crate) fn is_max_value(&self) -> bool {
match self.value {
Some(register_value) => register_value.is_max_value(),
None => false,
}
}
/// A helper function to determine if the contained register value is zero.
/// Will return false if the value is `None`
pub(crate) fn is_zero(&self) -> bool {
match self.value {
Some(register_value) => register_value.is_zero(),
None => false,
}
}
/// Retrieve the name of the [`CoreRegister`] role if it exists, else the name.
pub fn get_register_name(&self) -> String {
self.core_register.to_string()
}
}
/// All the registers required for debug related operations.
#[derive(Debug, Clone, Default, PartialEq, Serialize)]
pub struct DebugRegisters(pub Vec<DebugRegister>);
impl DebugRegisters {
/// Read all registers defined in [`probe_rs::core::CoreRegisters`] from the given core.
pub fn from_core(core: &mut impl CoreInterface) -> Self {
if let Err(error) = core.spill_registers() {
tracing::warn!("Failed to spill registers: {error}");
};
Self::from_core_registers(core.registers(), |register_id| {
core.read_core_reg(*register_id)
.inspect_err(|error| {
tracing::warn!(
"Failed to read value for register {:?}: {error}",
register_id
)
})
.ok()
})
}
/// Read all registers captured in the given [`CoreDump`].
pub fn from_coredump(core: &CoreDump) -> Self {
Self::from_core_registers(core.registers(), |register_id| {
let value = core.registers.get(register_id).cloned();
if value.is_none() {
tracing::warn!("Failed to read value for register {:?}", register_id);
}
value
})
}
fn from_core_registers(
regs: &'static CoreRegisters,
mut reg_value: impl FnMut(&RegisterId) -> Option<RegisterValue>,
) -> Self {
let mut debug_registers = Vec::<DebugRegister>::new();
for (dwarf_id, core_register) in regs.core_registers().enumerate() {
// Check to ensure the register type is compatible with u64.
if matches!(core_register.data_type(), RegisterDataType::UnsignedInteger(size_in_bits) if size_in_bits <= 64)
{
debug_registers.push(DebugRegister {
core_register,
// The DWARF register ID is only valid for the first 32 registers.
dwarf_id: if dwarf_id < 32 {
Some(dwarf_id as u16)
} else {
None
},
value: reg_value(&core_register.id()),
});
} else {
tracing::trace!(
"Unwind will use the default rule for this register : {:?}",
core_register
);
}
}
DebugRegisters(debug_registers)
}
/// Gets the address size for this target, in bytes
pub fn get_address_size_bytes(&self) -> usize {
self.get_program_counter()
.map(|debug_register| debug_register.core_register.size_in_bits().div_ceil(8))
.unwrap_or(0)
}
/// Wraps a program address in a [`RegisterValue`] of the target's address size, so that its
/// printed width is consistent across all stack frames. A plain `RegisterValue::from(u64)`
/// would always yield a `U64`, printing 16 hex digits on 32-bit targets.
pub fn address_to_register_value(&self, address: u64) -> RegisterValue {
match self.get_address_size_bytes() {
4 => RegisterValue::U32(address as u32),
8 => RegisterValue::U64(address),
_ => RegisterValue::from(address),
}
}
/// Get the canonical frame address, as specified in the [DWARF](https://dwarfstd.org) specification, section 6.4.
/// [DWARF](https://dwarfstd.org)
///
/// This is not always available
pub fn get_frame_pointer(&self) -> Option<&DebugRegister> {
self.0.iter().find(|debug_register| {
debug_register
.core_register
.register_has_role(RegisterRole::FramePointer)
})
}
/// Get the program counter.
pub fn get_program_counter<'b, 'c: 'b>(&'c self) -> Option<&'b DebugRegister> {
self.0.iter().find(|debug_register| {
debug_register
.core_register
.register_has_role(RegisterRole::ProgramCounter)
})
}
/// Get a mutable reference to the program counter.
pub fn get_program_counter_mut<'b, 'c: 'b>(&'c mut self) -> Option<&'b mut DebugRegister> {
self.0.iter_mut().find(|debug_register| {
debug_register
.core_register
.register_has_role(RegisterRole::ProgramCounter)
})
}
/// Get the stack pointer.
pub fn get_stack_pointer(&self) -> Option<&DebugRegister> {
self.0.iter().find(|debug_register| {
debug_register
.core_register
.register_has_role(RegisterRole::StackPointer)
})
}
/// Get the return address.
pub fn get_return_address(&self) -> Option<&DebugRegister> {
self.0.iter().find(|debug_register| {
debug_register
.core_register
.register_has_role(RegisterRole::ReturnAddress)
})
}
/// Get a register by [`RegisterId`]
pub fn get_register(&self, register_id: RegisterId) -> Option<&DebugRegister> {
self.0
.iter()
.find(|debug_register| debug_register.core_register.id == register_id)
}
/// Get a mutable reference register by [`RegisterId`]
pub fn get_register_mut(&mut self, register_id: RegisterId) -> Option<&mut DebugRegister> {
self.0
.iter_mut()
.find(|debug_register| debug_register.core_register.id == register_id)
}
/// Get the register value using the positional index into core registers.
/// [DWARF](https://dwarfstd.org) specification, section 2.6.1.1.3.1 "... operations encode the names of up to 32 registers, numbered from 0 through 31, inclusive ..."
pub fn get_register_by_dwarf_id(&self, dwarf_id: u16) -> Option<&DebugRegister> {
self.0
.iter()
.find(|debug_register| debug_register.dwarf_id == Some(dwarf_id))
}
/// Retrieve the role name if it exists, else the actual name using the [`RegisterId`] as an identifier.
pub fn get_register_name(&self, register_id: RegisterId) -> String {
self.0
.iter()
.find(|debug_register| debug_register.core_register.id == register_id)
.map(|debug_register| debug_register.get_register_name())
.unwrap_or_else(|| "unknown register".to_string())
}
/// Retrieve a reference to a register by searching against an exact match of the [`RegisterRole`].
pub fn get_register_by_role(
&self,
register_role: &RegisterRole,
) -> Result<&DebugRegister, Error> {
let qualifying_registers = self
.0
.iter()
.filter(|debug_register| {
debug_register
.core_register
.roles
.iter()
.any(|role| role == register_role)
})
.collect::<Vec<&DebugRegister>>();
if qualifying_registers.is_empty() {
Err(Error::Register(format!(
"No {register_role:?} registers. Please report this as a bug."
)))
} else if qualifying_registers.len() == 1 {
qualifying_registers.first().cloned().ok_or_else(|| {
Error::Register(format!(
"No {register_role:?} registers. Please report this as a bug."
))
})
} else {
Err(Error::Register(format!(
"Multiple {register_role:?} registers. Please report this as a bug."
)))
}
}
/// Retrieve the stored value of a register by searching against an exact match of the [`RegisterRole`].
pub fn get_register_value_by_role(&self, register_role: &RegisterRole) -> Result<u64, Error> {
self.get_register_by_role(register_role)?
.value
.ok_or_else(|| {
Error::Register(format!(
"No value for {register_role:?} register. Please report this as a bug."
))
})?
.try_into()
}
/// Retrieve a mutable reference to a register by searching against an exact match of the [`RegisterRole`].
pub fn get_register_mut_by_role(
&mut self,
register_role: &RegisterRole,
) -> Result<&mut DebugRegister, Error> {
self.get_register_mut(self.get_register_by_role(register_role)?.core_register.id)
.ok_or_else(|| {
Error::Register(format!(
"No {register_role:?} registers. Please report this as a bug."
))
})
}
/// Retrieve a register by searching against either the name or the role name.
/// Use this for registers that have platform specific names like "t1", or "s9", etc.,
/// and cannot efficiently be accessed through any of the other methods.
pub fn get_register_by_name(&self, register_name: &str) -> Option<DebugRegister> {
self.0
.iter()
.find(|&debug_register| {
for role in debug_register.core_register.roles {
if matches!(role, RegisterRole::Core(role_name) | RegisterRole::Argument(role_name) | RegisterRole::Return(role_name) | RegisterRole::Other(role_name) if *role_name == register_name) {
return true;
}
}
false
})
.cloned()
}
}