probe_rs/core/
dump.rs

1use crate::architecture::arm::core::registers::aarch32::{
2    AARCH32_CORE_REGISTERS, AARCH32_WITH_FP_16_CORE_REGISTERS, AARCH32_WITH_FP_32_CORE_REGISTERS,
3};
4use crate::architecture::arm::core::registers::aarch64::AARCH64_CORE_REGISTERS;
5use crate::architecture::arm::core::registers::cortex_m::{
6    CORTEX_M_CORE_REGISTERS, CORTEX_M_WITH_FP_CORE_REGISTERS,
7};
8use crate::architecture::riscv::registers::{RISCV_CORE_REGISTERS, RISCV_WITH_FP_CORE_REGISTERS};
9use crate::architecture::xtensa::arch::{Register as XtensaRegister, SpecialRegister};
10use crate::architecture::xtensa::registers::XTENSA_CORE_REGISTERS;
11use crate::{Core, CoreRegisters, CoreType, Error, InstructionSet, MemoryInterface};
12use crate::{RegisterId, RegisterValue};
13use object::elf::PT_NOTE;
14use object::read::elf::ProgramHeader;
15use object::{Object, ObjectSegment};
16use probe_rs_target::MemoryRange;
17use scroll::Cread;
18use serde::{Deserialize, Serialize};
19use std::array;
20use std::sync::LazyLock;
21use std::{
22    collections::HashMap,
23    fs::OpenOptions,
24    ops::Range,
25    path::{Path, PathBuf},
26};
27
28trait Processor {
29    /// Returns the instruction set of the processor.
30    fn instruction_set(&self) -> InstructionSet;
31
32    /// Returns the core type of the processor.
33    fn core_type(&self) -> CoreType;
34
35    /// Returns whether the processor supports native 64 bit access.
36    fn supports_native_64bit_access(&self) -> bool {
37        false
38    }
39
40    /// Returns the length of the register data in bytes.
41    fn register_data_len(&self) -> usize;
42
43    /// Returns the core registers and their positions in the register data.
44    ///
45    /// The positions are in register indexes, not byte offsets.
46    fn register_map(&self) -> &[(usize, RegisterId)];
47
48    /// Reads the registers from the .elf note data and stores them in the provided map.
49    fn read_registers(
50        &self,
51        note_data: &[u8],
52        registers: &mut HashMap<RegisterId, RegisterValue>,
53    ) -> Result<(), CoreDumpError> {
54        for (offset, reg_id) in self.register_map().iter().copied() {
55            let value = self.read_register(note_data, offset)?;
56            registers.insert(reg_id, value);
57        }
58
59        Ok(())
60    }
61
62    /// Reads a single register value from the note data. The register is addressed by its
63    /// position in the .elf note data.
64    fn read_register(&self, note_data: &[u8], idx: usize) -> Result<RegisterValue, CoreDumpError> {
65        let value = u32::from_le_bytes(note_data[idx * 4..][..4].try_into().unwrap());
66        Ok(RegisterValue::U32(value))
67    }
68}
69
70struct XtensaProcessor;
71impl Processor for XtensaProcessor {
72    fn instruction_set(&self) -> InstructionSet {
73        InstructionSet::Xtensa
74    }
75    fn core_type(&self) -> CoreType {
76        CoreType::Xtensa
77    }
78    fn register_data_len(&self) -> usize {
79        128 * 4
80    }
81    fn register_map(&self) -> &[(usize, RegisterId)] {
82        static REGS: LazyLock<[(usize, RegisterId); 24]> = LazyLock::new(|| {
83            let core_regs = &XTENSA_CORE_REGISTERS;
84
85            array::from_fn(|idx| {
86                match idx {
87                    // First 8 registers are special registers.
88                    0 => (idx, RegisterId::from(XtensaRegister::CurrentPc)),
89                    1 => (idx, RegisterId::from(SpecialRegister::Ps)),
90                    2 => (idx, RegisterId::from(SpecialRegister::Lbeg)),
91                    3 => (idx, RegisterId::from(SpecialRegister::Lend)),
92                    4 => (idx, RegisterId::from(SpecialRegister::Lcount)),
93                    5 => (idx, RegisterId::from(SpecialRegister::Sar)),
94                    6 => (idx, RegisterId::from(SpecialRegister::Windowstart)),
95                    7 => (idx, RegisterId::from(SpecialRegister::Windowbase)),
96                    // There are 56 reserved registers before the core registers.
97                    8..24 => {
98                        // The coredump contains all 64 AR registers but we don't define them yet,
99                        // so let's just use the 16 of the visible window.
100                        let ar_idx = idx - 8;
101                        (ar_idx + 64, core_regs.core_register(ar_idx).id())
102                    }
103                    _ => unreachable!(),
104                }
105            })
106        });
107
108        &*REGS
109    }
110}
111
112struct RiscvProcessor;
113impl Processor for RiscvProcessor {
114    fn instruction_set(&self) -> InstructionSet {
115        InstructionSet::RV32
116    }
117    fn core_type(&self) -> CoreType {
118        CoreType::Riscv
119    }
120    fn register_data_len(&self) -> usize {
121        32 * 4
122    }
123    fn register_map(&self) -> &[(usize, RegisterId)] {
124        static REGS: LazyLock<[(usize, RegisterId); 32]> = LazyLock::new(|| {
125            let core_regs = &RISCV_CORE_REGISTERS;
126
127            array::from_fn(|idx| {
128                // Core register 0 is the "zero" register. Coredumps place the PC there instead.
129                let regid = if idx == 0 {
130                    core_regs.pc().unwrap().id()
131                } else {
132                    core_regs.core_register(idx).id()
133                };
134                (idx, regid)
135            })
136        });
137        &*REGS
138    }
139}
140
141/// A snapshot representation of a core state.
142#[derive(Debug, Clone, Serialize, Deserialize)]
143pub struct CoreDump {
144    /// The registers we dumped from the core.
145    pub registers: HashMap<RegisterId, RegisterValue>,
146    /// The memory we dumped from the core.
147    pub data: Vec<(Range<u64>, Vec<u8>)>,
148    /// The instruction set of the dumped core.
149    pub instruction_set: InstructionSet,
150    /// Whether or not the target supports native 64 bit support (64bit architectures)
151    pub supports_native_64bit_access: bool,
152    /// The type of core we have at hand.
153    pub core_type: CoreType,
154    /// Whether this core supports floating point.
155    pub fpu_support: bool,
156    /// The number of floating point registers.
157    pub floating_point_register_count: Option<usize>,
158}
159
160impl CoreDump {
161    /// Dump the core info with the current state.
162    ///
163    /// # Arguments
164    /// * `core`: The core to dump.
165    /// * `ranges`: Memory ranges that should be dumped.
166    pub fn dump_core(core: &mut Core, ranges: Vec<Range<u64>>) -> Result<Self, Error> {
167        let mut registers = HashMap::new();
168        for register in core.registers().all_registers() {
169            let value = core.read_core_reg(register.id())?;
170            registers.insert(register.id(), value);
171        }
172
173        let mut data = Vec::new();
174        for range in ranges {
175            let mut values = vec![0; (range.end - range.start) as usize];
176            core.read(range.start, &mut values)?;
177            data.push((range, values));
178        }
179
180        Ok(CoreDump {
181            registers,
182            data,
183            instruction_set: core.instruction_set()?,
184            supports_native_64bit_access: core.supports_native_64bit_access(),
185            core_type: core.core_type(),
186            fpu_support: core.fpu_support()?,
187            floating_point_register_count: Some(core.floating_point_register_count()?),
188        })
189    }
190
191    /// Store the dumped core to a file.
192    pub fn store(&self, path: &Path) -> Result<(), CoreDumpError> {
193        let mut file = OpenOptions::new()
194            .create(true)
195            .write(true)
196            .truncate(true)
197            .open(path)
198            .map_err(|e| {
199                CoreDumpError::CoreDumpFileWrite(e, dunce::canonicalize(path).unwrap_or_default())
200            })?;
201        rmp_serde::encode::write_named(&mut file, self).map_err(CoreDumpError::EncodingCoreDump)?;
202        Ok(())
203    }
204
205    /// Load the dumped core from a file.
206    pub fn load(path: &Path) -> Result<Self, CoreDumpError> {
207        let file_contents = std::fs::read(path).map_err(|e| {
208            CoreDumpError::CoreDumpFileRead(e, dunce::canonicalize(path).unwrap_or_default())
209        })?;
210        Self::load_raw(&file_contents)
211    }
212
213    /// Load the dumped core from a file.
214    pub fn load_raw(data: &[u8]) -> Result<Self, CoreDumpError> {
215        if let Ok(elf) = object::read::elf::ElfFile32::parse(data) {
216            Self::load_elf(elf)
217        } else if let Ok(elf) = object::read::elf::ElfFile64::parse(data) {
218            Self::load_elf(elf)
219        } else {
220            rmp_serde::from_slice(data).map_err(CoreDumpError::DecodingCoreDump)
221        }
222    }
223
224    fn load_elf<Elf: object::read::elf::FileHeader<Endian = object::Endianness>>(
225        elf: object::read::elf::ElfFile<'_, Elf>,
226    ) -> Result<Self, CoreDumpError> {
227        let endianness = elf.endianness();
228        let elf_data = elf.data();
229
230        let processor: Box<dyn Processor> = match elf.architecture() {
231            object::Architecture::Riscv32 => Box::new(RiscvProcessor),
232            object::Architecture::Xtensa => Box::new(XtensaProcessor),
233            other => {
234                return Err(CoreDumpError::DecodingElfCoreDump(format!(
235                    "Unsupported architecture: {other:?}",
236                )));
237            }
238        };
239
240        // The memory is in a Load segment.
241        let mut data = Vec::new();
242        // `elf.segments()` returns PT_LOAD segments only.
243        for segment in elf.segments() {
244            let address: u64 = segment.elf_program_header().p_vaddr(endianness).into();
245            let size: u64 = segment.elf_program_header().p_memsz(endianness).into();
246            let memory = segment.data()?;
247            tracing::debug!(
248                "Adding memory segment: {:#x} - {:#x}",
249                address,
250                address + size
251            );
252            data.push((address..address + size, memory.to_vec()));
253        }
254
255        // Registers are in a Note segment.
256        let Some(register_note) = elf
257            .elf_program_headers()
258            .iter()
259            .find(|s| s.p_type(endianness) == PT_NOTE)
260        else {
261            return Err(CoreDumpError::DecodingElfCoreDump(
262                "No note segment found".to_string(),
263            ));
264        };
265
266        let mut registers = HashMap::new();
267        for note in register_note
268            .notes(endianness, elf_data)?
269            .expect("Failed to read notes from a PT_NOTE segment. This is a bug, please report it.")
270        {
271            let note = note?;
272            if note.name() != b"CORE" {
273                continue;
274            }
275
276            // The CORE note contains some thread-specific information before/after the registers.
277            // We only care about the registers, so let's cut off the rest. If we decide to use
278            // the other information, we can do that later, most likely without
279            // architecture-specific processing code.
280            const CORE_NOTE_HEADER_SIZE: usize = 72;
281            let note_length = processor.register_data_len();
282
283            if note.desc().len() < CORE_NOTE_HEADER_SIZE + note_length {
284                return Err(CoreDumpError::DecodingElfCoreDump(format!(
285                    "Note segment is too small: {} bytes instead of at least {}",
286                    note.desc().len(),
287                    CORE_NOTE_HEADER_SIZE + note_length
288                )));
289            }
290
291            let note_data = &note.desc()[CORE_NOTE_HEADER_SIZE..][..note_length];
292            processor.read_registers(note_data, &mut registers)?;
293        }
294
295        Ok(Self {
296            registers,
297            data,
298            instruction_set: processor.instruction_set(),
299            supports_native_64bit_access: processor.supports_native_64bit_access(),
300            core_type: processor.core_type(),
301            fpu_support: false,
302            floating_point_register_count: None,
303        })
304    }
305
306    /// Returns the type of the core.
307    pub fn core_type(&self) -> CoreType {
308        self.core_type
309    }
310
311    /// Returns the currently active instruction-set
312    pub fn instruction_set(&self) -> InstructionSet {
313        self.instruction_set
314    }
315
316    /// Retrieve a memory range that contains the requested address and size, from the coredump.
317    fn get_memory_from_coredump(
318        &self,
319        address: u64,
320        size_in_bytes: u64,
321    ) -> Result<&[u8], crate::Error> {
322        for (range, memory) in &self.data {
323            if range.contains_range(&(address..(address + size_in_bytes))) {
324                let offset = (address - range.start) as usize;
325
326                return Ok(&memory[offset..][..size_in_bytes as usize]);
327            }
328        }
329        // If we get here, then no range with the requested memory address and size was found.
330        Err(crate::Error::Other(format!(
331            "The coredump does not include the memory for address {address:#x} of size {size_in_bytes:#x}"
332        )))
333    }
334
335    /// Read the requested memory range from the coredump, and return the data in the requested buffer.
336    /// The word-size of the read is determined by the size of the items in the `data` buffer.
337    fn read_memory_range<T>(&self, address: u64, data: &mut [T]) -> Result<(), crate::Error>
338    where
339        T: scroll::ctx::FromCtx<scroll::Endian>,
340    {
341        let memory =
342            self.get_memory_from_coredump(address, (std::mem::size_of_val(data)) as u64)?;
343
344        let value_size = std::mem::size_of::<T>();
345
346        for (n, data) in data.iter_mut().enumerate() {
347            *data = memory.cread_with::<T>(n * value_size, scroll::LE);
348        }
349        Ok(())
350    }
351
352    /// Returns the register map for the core type.
353    pub fn registers(&self) -> &'static CoreRegisters {
354        match self.core_type {
355            CoreType::Armv6m => &CORTEX_M_CORE_REGISTERS,
356            CoreType::Armv7a => match self.floating_point_register_count {
357                Some(16) => &AARCH32_WITH_FP_16_CORE_REGISTERS,
358                Some(32) => &AARCH32_WITH_FP_32_CORE_REGISTERS,
359                _ => &AARCH32_CORE_REGISTERS,
360            },
361            CoreType::Armv7m => {
362                if self.fpu_support {
363                    &CORTEX_M_WITH_FP_CORE_REGISTERS
364                } else {
365                    &CORTEX_M_CORE_REGISTERS
366                }
367            }
368            CoreType::Armv7em => {
369                if self.fpu_support {
370                    &CORTEX_M_WITH_FP_CORE_REGISTERS
371                } else {
372                    &CORTEX_M_CORE_REGISTERS
373                }
374            }
375            // TODO: This can be wrong if the CPU is 32 bit. For lack of better design at the time
376            // of writing this code this differentiation has been omitted.
377            CoreType::Armv8a => &AARCH64_CORE_REGISTERS,
378            CoreType::Armv8m => {
379                if self.fpu_support {
380                    &CORTEX_M_WITH_FP_CORE_REGISTERS
381                } else {
382                    &CORTEX_M_CORE_REGISTERS
383                }
384            }
385            CoreType::Riscv => {
386                if self.fpu_support {
387                    &RISCV_WITH_FP_CORE_REGISTERS
388                } else {
389                    &RISCV_CORE_REGISTERS
390                }
391            }
392            CoreType::Xtensa => &XTENSA_CORE_REGISTERS,
393        }
394    }
395}
396
397impl MemoryInterface for CoreDump {
398    fn supports_native_64bit_access(&mut self) -> bool {
399        self.supports_native_64bit_access
400    }
401
402    fn read_word_64(&mut self, address: u64) -> Result<u64, crate::Error> {
403        let mut data = [0u64; 1];
404        self.read_memory_range(address, &mut data)?;
405        Ok(data[0])
406    }
407
408    fn read_word_32(&mut self, address: u64) -> Result<u32, crate::Error> {
409        let mut data = [0u32; 1];
410        self.read_memory_range(address, &mut data)?;
411        Ok(data[0])
412    }
413
414    fn read_word_16(&mut self, address: u64) -> Result<u16, crate::Error> {
415        let mut data = [0u16; 1];
416        self.read_memory_range(address, &mut data)?;
417        Ok(data[0])
418    }
419
420    fn read_word_8(&mut self, address: u64) -> Result<u8, crate::Error> {
421        let mut data = [0u8; 1];
422        self.read_memory_range(address, &mut data)?;
423        Ok(data[0])
424    }
425
426    fn read_64(&mut self, address: u64, data: &mut [u64]) -> Result<(), crate::Error> {
427        self.read_memory_range(address, data)?;
428        Ok(())
429    }
430
431    fn read_32(&mut self, address: u64, data: &mut [u32]) -> Result<(), crate::Error> {
432        self.read_memory_range(address, data)?;
433        Ok(())
434    }
435
436    fn read_16(&mut self, address: u64, data: &mut [u16]) -> Result<(), crate::Error> {
437        self.read_memory_range(address, data)?;
438        Ok(())
439    }
440
441    fn read_8(&mut self, address: u64, data: &mut [u8]) -> Result<(), crate::Error> {
442        self.read_memory_range(address, data)?;
443        Ok(())
444    }
445
446    fn write_word_64(&mut self, _address: u64, _data: u64) -> Result<(), crate::Error> {
447        todo!()
448    }
449
450    fn write_word_32(&mut self, _address: u64, _data: u32) -> Result<(), crate::Error> {
451        todo!()
452    }
453
454    fn write_word_16(&mut self, _address: u64, _data: u16) -> Result<(), crate::Error> {
455        todo!()
456    }
457
458    fn write_word_8(&mut self, _address: u64, _data: u8) -> Result<(), crate::Error> {
459        todo!()
460    }
461
462    fn write_64(&mut self, _address: u64, _data: &[u64]) -> Result<(), crate::Error> {
463        todo!()
464    }
465
466    fn write_32(&mut self, _address: u64, _data: &[u32]) -> Result<(), crate::Error> {
467        todo!()
468    }
469
470    fn write_16(&mut self, _address: u64, _data: &[u16]) -> Result<(), crate::Error> {
471        todo!()
472    }
473
474    fn write_8(&mut self, _address: u64, _data: &[u8]) -> Result<(), crate::Error> {
475        todo!()
476    }
477
478    fn supports_8bit_transfers(&self) -> Result<bool, crate::Error> {
479        todo!()
480    }
481
482    fn flush(&mut self) -> Result<(), crate::Error> {
483        todo!()
484    }
485}
486
487/// The overarching error type which contains all possible errors as variants.
488#[derive(thiserror::Error, Debug)]
489pub enum CoreDumpError {
490    /// Opening the file for writing the core dump failed.
491    #[error("Opening {1} for writing the core dump failed.")]
492    CoreDumpFileWrite(std::io::Error, PathBuf),
493    /// Opening the file for reading the core dump failed.
494    #[error("Opening {1} for reading the core dump failed.")]
495    CoreDumpFileRead(std::io::Error, PathBuf),
496    /// Encoding the coredump MessagePack failed.
497    #[error("Encoding the coredump MessagePack failed.")]
498    EncodingCoreDump(rmp_serde::encode::Error),
499    /// Decoding the coredump MessagePack failed.
500    #[error("Decoding the coredump MessagePack failed.")]
501    DecodingCoreDump(rmp_serde::decode::Error),
502    /// Decoding the coredump .elf failed.
503    #[error("Decoding the coredump .elf failed.")]
504    DecodingElfCoreDump(String),
505    /// Invalid ELF file.
506    #[error("Invalid ELF file.")]
507    ElfCoreDumpFormat(#[from] object::read::Error),
508}
probe_rs/core/dump.rs

probe_rs/core/
dump.rs
