Struct probe_rs::Core

pub struct Core<'probe> { /* private fields */ }

Generic core handle representing a physical core on an MCU.

This should be considered as a temporary view of the core which locks the debug probe driver to as single consumer by borrowing it.

As soon as you did your atomic task (e.g. halt the core, read the core state and all other debug relevant info) you should drop this object, to allow potential other shareholders of the session struct to grab a core handle too.

Implementations

impl<'probe> Core<'probe>

pub fn inner_mut(&mut self) -> &mut Box<dyn CoreInterface + 'probe>

Borrow the boxed CoreInterface mutable.

pub fn memory_regions(&self) -> impl Iterator<Item = &MemoryRegion>

Return the memory regions associated with this core.

pub fn id(&self) -> usize

Returns the ID of this core.

pub fn wait_for_core_halted(&mut self, timeout: Duration) -> Result<(), Error>

Wait until the core is halted. If the core does not halt on its own, a DebugProbeError::Timeout error will be returned.

pub fn core_halted(&mut self) -> Result<bool, Error>

Check if the core is halted. If the core does not halt on its own, a DebugProbeError::Timeout error will be returned.

pub fn halt(&mut self, timeout: Duration) -> Result<CoreInformation, Error>

Try to halt the core. This function ensures the core is actually halted, and returns a DebugProbeError::Timeout otherwise.

pub fn run(&mut self) -> Result<(), Error>

Continue to execute instructions.

pub fn reset(&mut self) -> Result<(), Error>

Reset the core, and then continue to execute instructions. If the core should be halted after reset, use the reset_and_halt function.

pub fn reset_and_halt( &mut self, timeout: Duration ) -> Result<CoreInformation, Error>

Reset the core, and then immediately halt. To continue execution after reset, use the reset function.

pub fn step(&mut self) -> Result<CoreInformation, Error>

Steps one instruction and then enters halted state again.

pub fn status(&mut self) -> Result<CoreStatus, Error>

Returns the current status of the core.

pub fn read_core_reg<T>( &mut self, address: impl Into<RegisterId> ) -> Result<T, Error>

where RegisterValue: TryInto<T>, Result<T, <RegisterValue as TryInto<T>>::Error>: RegisterValueResultExt<T>,

Read the value of a core register.

Remarks

T can be an unsigned integer type, such as u32 or u64, or it can be RegisterValue to allow the caller to support arbitrary length registers.

To add support to convert to a custom type implement TryInto<CustomType> for RegisterValue.

Errors

If T isn’t large enough to hold the register value an error will be raised.

pub fn write_core_reg<T>( &mut self, address: impl Into<RegisterId>, value: T ) -> Result<(), Error>

where T: Into<RegisterValue>,

Write the value of a core register.

Errors

If T is too large to write to the target register an error will be raised.

pub fn available_breakpoint_units(&mut self) -> Result<u32, Error>

Returns all the available breakpoint units of the core.

pub fn debug_on_sw_breakpoint(&mut self, enabled: bool) -> Result<(), Error>

Configure the debug module to ensure software breakpoints will enter Debug Mode.

pub fn registers(&self) -> &'static CoreRegisters

Returns a list of all the registers of this core.

pub fn program_counter(&self) -> &'static CoreRegister

Returns the program counter register.

pub fn frame_pointer(&self) -> &'static CoreRegister

Returns the stack pointer register.

pub fn stack_pointer(&self) -> &'static CoreRegister

Returns the frame pointer register.

pub fn return_address(&self) -> &'static CoreRegister

Returns the return address register, a.k.a. link register.

pub fn set_hw_breakpoint(&mut self, address: u64) -> Result<(), Error>

Set a hardware breakpoint

This function will try to set a hardware breakpoint att address.

The amount of hardware breakpoints which are supported is chip specific, and can be queried using the get_available_breakpoint_units function.

pub fn clear_hw_breakpoint(&mut self, address: u64) -> Result<(), Error>

Set a hardware breakpoint

This function will try to clear a hardware breakpoint at address if there exists a breakpoint at that address.

pub fn clear_all_hw_breakpoints(&mut self) -> Result<(), Error>

Clear all hardware breakpoints

This function will clear all HW breakpoints which are configured on the target, regardless if they are set by probe-rs, AND regardless if they are enabled or not. Also used as a helper function in Session::drop.

pub fn architecture(&self) -> Architecture

Returns the architecture of the core.

pub fn core_type(&self) -> CoreType

Returns the core type of the core

pub fn instruction_set(&mut self) -> Result<InstructionSet, Error>

Determine the instruction set the core is operating in This must be queried while halted as this is a runtime decision for some core types

pub fn fpu_support(&mut self) -> Result<bool, Error>

Determine if an FPU is present. This must be queried while halted as this is a runtime decision for some core types.

pub fn floating_point_register_count(&mut self) -> Result<usize, Error>

Determine the number of floating point registers. This must be queried while halted as this is a runtime decision for some core types.

pub fn enable_vector_catch( &mut self, condition: VectorCatchCondition ) -> Result<(), Error>

Enables vector catching for the given condition

pub fn disable_vector_catch( &mut self, condition: VectorCatchCondition ) -> Result<(), Error>

Disables vector catching for the given condition

pub fn dump(&mut self, ranges: Vec<Range<u64>>) -> Result<CoreDump, Error>

Dumps core info with the current state.

Arguments

• ranges: Memory ranges that should be dumped.

pub fn is_64_bit(&self) -> bool

Check if the integer size is 64-bit

Trait Implementations

impl<'probe> CoreInterface for Core<'probe>

fn wait_for_core_halted(&mut self, timeout: Duration) -> Result<(), Error>

Wait until the core is halted. If the core does not halt on its own, a DebugProbeError::Timeout error will be returned.

fn core_halted(&mut self) -> Result<bool, Error>

Check if the core is halted. If the core does not halt on its own, a DebugProbeError::Timeout error will be returned.

fn status(&mut self) -> Result<CoreStatus, Error>

Returns the current status of the core.

fn halt(&mut self, timeout: Duration) -> Result<CoreInformation, Error>

Try to halt the core. This function ensures the core is actually halted, and returns a DebugProbeError::Timeout otherwise.

fn run(&mut self) -> Result<(), Error>

Continue to execute instructions.

fn reset(&mut self) -> Result<(), Error>

Reset the core, and then continue to execute instructions. If the core should be halted after reset, use the reset_and_halt function.

fn reset_and_halt( &mut self, timeout: Duration ) -> Result<CoreInformation, Error>

Reset the core, and then immediately halt. To continue execution after reset, use the reset function.

fn step(&mut self) -> Result<CoreInformation, Error>

Steps one instruction and then enters halted state again.

fn read_core_reg(&mut self, address: RegisterId) -> Result<RegisterValue, Error>

Read the value of a core register.

fn write_core_reg( &mut self, address: RegisterId, value: RegisterValue ) -> Result<(), Error>

Write the value of a core register.

fn available_breakpoint_units(&mut self) -> Result<u32, Error>

Returns all the available breakpoint units of the core.

fn hw_breakpoints(&mut self) -> Result<Vec<Option<u64>>, Error>

Read the hardware breakpoints from FpComp registers, and adds them to the Result Vector. A value of None in any position of the Vector indicates that the position is unset/available. We intentionally return all breakpoints, irrespective of whether they are enabled or not.

fn enable_breakpoints(&mut self, state: bool) -> Result<(), Error>

Enables breakpoints on this core. If a breakpoint is set, it will halt as soon as it is hit.

fn set_hw_breakpoint( &mut self, _unit_index: usize, addr: u64 ) -> Result<(), Error>

Sets a breakpoint at addr. It does so by using unit bp_unit_index.

fn clear_hw_breakpoint(&mut self, _unit_index: usize) -> Result<(), Error>

Clears the breakpoint configured in unit unit_index.

fn registers(&self) -> &'static CoreRegisters

Returns a list of all the registers of this core.

fn program_counter(&self) -> &'static CoreRegister

Returns the program counter register.

fn frame_pointer(&self) -> &'static CoreRegister

Returns the stack pointer register.

fn stack_pointer(&self) -> &'static CoreRegister

Returns the frame pointer register.

fn return_address(&self) -> &'static CoreRegister

Returns the return address register, a.k.a. link register.

fn hw_breakpoints_enabled(&self) -> bool

Returns true if hardware breakpoints are enabled, false otherwise.

fn architecture(&self) -> Architecture

Get the Architecture of the Core.

fn core_type(&self) -> CoreType

Get the CoreType of the Core

fn instruction_set(&mut self) -> Result<InstructionSet, Error>

Determine the instruction set the core is operating in This must be queried while halted as this is a runtime decision for some core types

fn fpu_support(&mut self) -> Result<bool, Error>

Determine if an FPU is present. This must be queried while halted as this is a runtime decision for some core types.

fn floating_point_register_count(&mut self) -> Result<usize, Error>

Determine the number of floating point registers. This must be queried while halted as this is a runtime decision for some core types.

fn reset_catch_set(&mut self) -> Result<(), Error>

Set the reset catch setting.

fn reset_catch_clear(&mut self) -> Result<(), Error>

Clear the reset catch setting.

fn debug_core_stop(&mut self) -> Result<(), Error>

Called when we stop debugging a core.

fn is_64_bit(&self) -> bool

Check if the integer size is 64-bit

fn debug_on_sw_breakpoint(&mut self, _enabled: bool) -> Result<(), Error>

Configure the target to ensure software breakpoints will enter Debug Mode.

fn on_session_stop(&mut self) -> Result<(), Error>

Called during session stop to do any pending cleanup

fn enable_vector_catch( &mut self, _condition: VectorCatchCondition ) -> Result<(), Error>

Enables vector catching for the given condition

fn disable_vector_catch( &mut self, _condition: VectorCatchCondition ) -> Result<(), Error>

Disables vector catching for the given condition

impl<'probe> MemoryInterface for Core<'probe>

fn supports_native_64bit_access(&mut self) -> bool

Does this interface support native 64-bit wide accesses

fn read_word_64(&mut self, address: u64) -> Result<u64, Error>

Read a 64bit word of at address.

fn read_word_32(&mut self, address: u64) -> Result<u32, Error>

Read a 32bit word of at address.

fn read_word_16(&mut self, address: u64) -> Result<u16, Error>

Read a 16bit word of at address.

fn read_word_8(&mut self, address: u64) -> Result<u8, Error>

Read an 8bit word of at address.

fn read_64(&mut self, address: u64, data: &mut [u64]) -> Result<(), Error>

Read a block of 64bit words at address.

fn read_32(&mut self, address: u64, data: &mut [u32]) -> Result<(), Error>

Read a block of 32bit words at address.

fn read_16(&mut self, address: u64, data: &mut [u16]) -> Result<(), Error>

Read a block of 16bit words at address.

fn read_8(&mut self, address: u64, data: &mut [u8]) -> Result<(), Error>

Read a block of 8bit words at address.

fn read(&mut self, address: u64, data: &mut [u8]) -> Result<(), Error>

Read data from address.

fn write_word_64(&mut self, addr: u64, data: u64) -> Result<(), Error>

Write a 64bit word at address.

fn write_word_32(&mut self, addr: u64, data: u32) -> Result<(), Error>

Write a 32bit word at address.

fn write_word_16(&mut self, addr: u64, data: u16) -> Result<(), Error>

Write a 16bit word at address.

fn write_word_8(&mut self, addr: u64, data: u8) -> Result<(), Error>

Write an 8bit word at address.

fn write_64(&mut self, addr: u64, data: &[u64]) -> Result<(), Error>

Write a block of 64bit words at address.

fn write_32(&mut self, addr: u64, data: &[u32]) -> Result<(), Error>

Write a block of 32bit words at address.

fn write_16(&mut self, addr: u64, data: &[u16]) -> Result<(), Error>

Write a block of 16bit words at address.

fn write_8(&mut self, addr: u64, data: &[u8]) -> Result<(), Error>

Write a block of 8bit words at address.

fn write(&mut self, addr: u64, data: &[u8]) -> Result<(), Error>

Write a block of 8bit words at address. May use 64 bit memory access, so should only be used if reading memory locations that don’t have side effects. Generally faster than MemoryInterface::write_8.

fn supports_8bit_transfers(&self) -> Result<bool, Error>

Returns whether the current platform supports native 8bit transfers.

fn flush(&mut self) -> Result<(), Error>

Flush any outstanding operations.

fn read_mem_64bit(&mut self, address: u64, data: &mut [u8]) -> Result<(), Error>

Reads bytes using 64 bit memory access.

fn read_mem_32bit(&mut self, address: u64, data: &mut [u8]) -> Result<(), Error>

Reads bytes using 32 bit memory access.

fn write_mem_64bit(&mut self, address: u64, data: &[u8]) -> Result<(), Error>

Writes bytes using 64 bit memory access. Address must be 64 bit aligned and data must be an exact multiple of 8.

fn write_mem_32bit(&mut self, address: u64, data: &[u8]) -> Result<(), Error>

Writes bytes using 32 bit memory access. Address must be 32 bit aligned and data must be an exact multiple of 8.