Struct probe_rs::Session

pub struct Session { /* private fields */ }

The Session struct represents an active debug session.

Creating a session

The session can be created by calling the Session::auto_attach() function, which tries to automatically select a probe, and then connect to the target.

For more control, the Probe::attach() and Probe::attach_under_reset() methods can be used to open a Session from a specific Probe.

Usage

The Session is the common handle that gives a user exclusive access to an active probe. You can create and share a session between threads to enable multiple stakeholders (e.g. GDB and RTT) to access the target taking turns, by using Arc<FairMutex<Session>>.

If you do so, make sure that both threads sleep in between tasks such that other stakeholders may take their turn.

To get access to a single Core from the Session, the Session::core() method can be used. Please see the Session::core() method for more usage guidelines.

Implementations

impl Session

pub fn auto_attach( target: impl Into<TargetSelector>, permissions: Permissions ) -> Result<Session, Error>

Automatically creates a session with the first connected probe found.

pub fn list_cores(&self) -> Vec<(usize, CoreType)>

Lists the available cores with their number and their type.

pub fn core(&mut self, core_index: usize) -> Result<Core<'_>, Error>

Attaches to the core with the given number.

Usage

Every time you want to perform an operation on the chip, you need to get the Core handle with the Session::core() method. This Core handle is merely a view into the core and provides a convenient API surface.

All the state is stored in the Session handle.

The first time you call Session::core() for a specific core, it will run the attach/init sequences and return a handle to the Core.

Every subsequent call is a no-op. It simply returns the handle for the user to use in further operations without calling any int sequences again.

It is strongly advised to never store the Core handle for any significant duration! Free it as fast as possible such that other stakeholders can have access to the Core too.

The idea behind this is: You need the smallest common denominator which you can share between threads. Since you sometimes need the Core, sometimes the Probe or sometimes the Target, the Session is the only common ground and the only handle you should actively store in your code.

pub fn read_trace_data(&mut self) -> Result<Vec<u8>, ArmError>

Read available trace data from the specified data sink.

This method is only supported for ARM-based targets, and will return ArmError::ArchitectureRequired otherwise.

pub fn swo_reader(&mut self) -> Result<SwoReader<'_>, Error>

Returns an implementation of std::io::Read that wraps SwoAccess::read_swo.

The implementation buffers all available bytes from SwoAccess::read_swo on each std::io::Read::read, minimizing the chance of a target-side overflow event on which trace packets are lost.

pub fn get_arm_interface( &mut self ) -> Result<&mut dyn ArmProbeInterface, ArmError>

Get the Arm probe interface.

pub fn get_riscv_interface( &mut self, core_id: usize ) -> Result<RiscvCommunicationInterface<'_>, Error>

Get the RISC-V probe interface.

pub fn get_xtensa_interface( &mut self, core_id: usize ) -> Result<XtensaCommunicationInterface<'_>, Error>

Get the Xtensa probe interface.

pub fn has_sequence_erase_all(&self) -> bool

Check if the connected device has a debug erase sequence defined

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

Erase all flash memory using the Device’s Debug Erase Sequence if any

Returns

Ok(()) if the device provides a custom erase sequence and it succeeded.

Errors

NotImplemented if no custom erase sequence exists Err(e) if the custom erase sequence failed

pub fn get_arm_components( &mut self, dp: DpAddress ) -> Result<Vec<CoresightComponent>, ArmError>

Reads all the available ARM CoresightComponents of the currently attached target.

This will recursively parse the Romtable of the attached target and create a list of all the contained components.

pub fn target(&self) -> &Target

Get the target description of the connected target.

pub fn setup_tracing( &mut self, core_index: usize, destination: TraceSink ) -> Result<(), Error>

Configure the target and probe for serial wire view (SWV) tracing.

pub fn disable_swv(&mut self, core_index: usize) -> Result<(), Error>

Configure the target to stop emitting SWV trace data.

pub fn add_swv_data_trace( &mut self, unit: usize, address: u32 ) -> Result<(), ArmError>

Begin tracing a memory address over SWV.

pub fn remove_swv_data_trace(&mut self, unit: usize) -> Result<(), ArmError>

Stop tracing from a given SWV unit

pub fn architecture(&self) -> Architecture

Return the Architecture of the currently connected chip.

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

Clears all hardware breakpoints on all cores

Trait Implementations

impl Debug for Session

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for Session

fn drop(&mut self)

Executes the destructor for this type.