Struct Rtt

pub struct Rtt {
    pub up_channels: Vec<UpChannel>,
    pub down_channels: Vec<DownChannel>,
    /* private fields */
}

The RTT interface.

Use Rtt::attach or Rtt::attach_region to attach to a probe-rs Core and detect the channels, as they were configured on the target. The timing of when this is called is really important, or else unexpected results can be expected.

Examples of how timing between host and target effects the results

1. Scenario: Ideal configuration: The host RTT interface is created AFTER the target program has successfully executing the RTT initialization, by calling an api such as rtt_target::rtt_init_print!().

   At this point, both the RTT Control Block and the RTT Channel configurations are present in the target memory, and this RTT interface can be expected to work as expected.

2. Scenario: Failure to detect RTT Control Block: The target has been configured correctly, BUT the host creates this interface BEFORE the target program has initialized RTT.

   This most commonly occurs when the target halts processing before initializing RTT. For example, this could happen …

   • During debugging, if the user sets a breakpoint in the code before the RTT initialization.
   • After flashing, if the user has configured probe-rs to reset_after_flashing AND halt_after_reset. On most targets, this will result in the target halting with reason Exception and will delay the subsequent RTT initialization.
   • If RTT initialization on the target is delayed because of time consuming processing or excessive interrupt handling. This can usually be prevented by moving the RTT initialization code to the very beginning of the target program logic.

   The result of such a timing issue is that probe-rs will fail to initialize RTT with an Error::ControlBlockNotFound

3. Scenario: Incorrect Channel names and incorrect Channel buffer sizes: This scenario usually occurs when two conditions coincide. Firstly, the same timing mismatch as described in point #2 above, and secondly, the target memory has NOT been cleared since a previous version of the binary program has been flashed to the target.

   What happens here is that the RTT Control Block is validated by reading a previously initialized RTT ID from the target memory. The next step in the logic is then to read the Channel configuration from the RTT Control block which is usually contains unreliable data at this point. The symptoms will appear as:

   • RTT Channel names are incorrect and/or contain unprintable characters.
   • RTT Channel names are correct, but no data, or corrupted data, will be reported from RTT, because the buffer sizes are incorrect.

Fields

up_channels: Vec<UpChannel>

The detected up (target to host) channels.

down_channels: Vec<DownChannel>

The detected down (host to target) channels.

Implementations

impl Rtt

pub fn attach(core: &mut Core<'_>) -> Result<Rtt, Error>

Attempts to detect an RTT control block anywhere in the target RAM and returns an instance if a valid control block was found.

core can be e.g. an owned Core or a shared Rc<Core>.

pub fn attach_region( core: &mut Core<'_>, region: &ScanRegion, ) -> Result<Rtt, Error>

Attempts to detect an RTT control block in the specified RAM region(s) and returns an instance if a valid control block was found.

core can be e.g. an owned Core or a shared Rc<Core>.

pub fn ptr(&self) -> u64

Returns the memory address of the control block in target memory.

pub fn up_channels(&mut self) -> &mut [UpChannel]

Returns a reference to the detected up channels.

pub fn down_channels(&mut self) -> &mut [DownChannel]

Returns a reference to the detected down channels.

pub fn up_channel(&mut self, channel: usize) -> Option<&mut UpChannel>

Returns a particular up channel.

pub fn down_channel(&mut self, channel: usize) -> Option<&mut DownChannel>

Returns a particular down channel.

pub fn control_block_size(core: &Core<'_>) -> usize

Returns the size of the RTT control block.

Trait Implementations

impl Debug for Rtt

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

Formats the value using the given formatter.