pub struct Session { /* private fields */ }
Expand description
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<Mutex<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
sourceimpl Session
impl Session
sourcepub fn auto_attach(
target: impl Into<TargetSelector>,
permissions: Permissions
) -> Result<Session, Error>
pub fn auto_attach(
target: impl Into<TargetSelector>,
permissions: Permissions
) -> Result<Session, Error>
Automatically creates a session with the first connected probe found.
sourcepub fn list_cores(&self) -> Vec<(usize, CoreType)>
pub fn list_cores(&self) -> Vec<(usize, CoreType)>
Lists the available cores with their number and their type.
sourcepub fn core(&mut self, n: usize) -> Result<Core<'_>, Error>
pub fn core(&mut self, n: usize) -> Result<Core<'_>, Error>
Attaches to the core with the given number.
Usage
Everytime 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.
sourcepub fn read_swo(&mut self) -> Result<Vec<u8>, Error>
pub fn read_swo(&mut self) -> Result<Vec<u8>, Error>
Read available data from the SWO interface without waiting.
This method is only supported for ARM-based targets, and will return Error::ArchitectureRequired otherwise.
sourcepub fn swo_reader(&mut self) -> Result<SwoReader<'_>, Error>
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.
sourcepub fn get_arm_interface(
&mut self
) -> Result<&mut Box<dyn ArmProbeInterface>, Error>
pub fn get_arm_interface(
&mut self
) -> Result<&mut Box<dyn ArmProbeInterface>, Error>
Get the Arm probe interface.
sourcepub fn get_arm_components(&mut self) -> Result<Vec<CoresightComponent>, Error>
pub fn get_arm_components(&mut self) -> Result<Vec<CoresightComponent>, Error>
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.
sourcepub fn setup_swv(
&mut self,
core_index: usize,
config: &SwoConfig
) -> Result<(), Error>
pub fn setup_swv(
&mut self,
core_index: usize,
config: &SwoConfig
) -> Result<(), Error>
Configure the target and probe for serial wire view (SWV) tracing.
sourcepub fn disable_swv(&mut self, core_index: usize) -> Result<(), Error>
pub fn disable_swv(&mut self, core_index: usize) -> Result<(), Error>
Configure the target to stop emitting SWV trace data.
sourcepub fn add_swv_data_trace(
&mut self,
unit: usize,
address: u32
) -> Result<(), Error>
pub fn add_swv_data_trace(
&mut self,
unit: usize,
address: u32
) -> Result<(), Error>
Begin tracing a memory address over SWV.
sourcepub fn remove_swv_data_trace(&mut self, unit: usize) -> Result<(), Error>
pub fn remove_swv_data_trace(&mut self, unit: usize) -> Result<(), Error>
Stop tracing from a given SWV unit
sourcepub fn memory_map(&self) -> &[MemoryRegion]
👎 Deprecated: Use the Session::target function instead
pub fn memory_map(&self) -> &[MemoryRegion]
Use the Session::target function instead
Returns the memory map of the target.
sourcepub fn architecture(&self) -> Architecture
pub fn architecture(&self) -> Architecture
Return the Architecture
of the currently connected chip.
sourcepub fn clear_all_hw_breakpoints(&mut self) -> Result<(), Error>
pub fn clear_all_hw_breakpoints(&mut self) -> Result<(), Error>
Clears all hardware breakpoints on all cores
Trait Implementations
Auto Trait Implementations
impl !RefUnwindSafe for Session
impl Send for Session
impl !Sync for Session
impl Unpin for Session
impl !UnwindSafe for Session
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more