probe_rs_rtt/
lib.rs

1//! Host side implementation of the RTT (Real-Time Transfer) I/O protocol over probe-rs
2//!
3//! RTT implements input and output to/from a microcontroller using in-memory ring buffers and
4//! memory polling. This enables debug logging from the microcontroller with minimal delays and no
5//! blocking, making it usable even in real-time applications where e.g. semihosting delays cannot
6//! be tolerated.
7//!
8//! This crate enables you to read and write via RTT channels. It's also used as a building-block
9//! for probe-rs debugging tools.
10//!
11//! ## Example
12//!
13//! ```no_run
14//! use std::sync::{Arc, Mutex};
15//! use probe_rs::{Probe, Permissions};
16//! use probe_rs_rtt::Rtt;
17//!
18//! // First obtain a probe-rs session (see probe-rs documentation for details)
19//! let probe = Probe::list_all()[0].open()?;
20//! let mut session = probe.attach("somechip", Permissions::default())?;
21//! let memory_map = session.target().memory_map.clone();
22//! // Select a core.
23//! let mut core = session.core(0)?;
24//!
25//! // Attach to RTT
26//! let mut rtt = Rtt::attach(&mut core, &memory_map)?;
27//!
28//! // Read from a channel
29//! if let Some(input) = rtt.up_channels().take(0) {
30//!     let mut buf = [0u8; 1024];
31//!     let count = input.read(&mut core, &mut buf[..])?;
32//!
33//!     println!("Read data: {:?}", &buf[..count]);
34//! }
35//!
36//! // Write to a channel
37//! if let Some(output) = rtt.down_channels().take(0) {
38//!     output.write(&mut core, b"Hello, computer!\n")?;
39//! }
40//!
41//! # Ok::<(), Box<dyn std::error::Error>>(())
42//! ```
43
44use thiserror::Error;
45
46mod channel;
47pub use channel::*;
48
49pub mod channels;
50pub use channels::Channels;
51
52mod rtt;
53pub use rtt::*;
54
55/// Error type for RTT operations.
56#[derive(Error, Debug)]
57pub enum Error {
58    /// RTT control block not found in target memory. Make sure RTT is initialized on the target.
59    #[error(
60        "RTT control block not found in target memory.\n\
61        - Make sure RTT is initialized on the target, AND that there are NO target breakpoints before RTT initalization.\n\
62        - For VSCode and probe-rs-debugger users, using `halt_after_reset:true` in your `launch.json` file will prevent RTT \n\
63        \tinitialization from happening on time.\n\
64        - Depending on the target, sleep modes can interfere with RTT."
65    )]
66    ControlBlockNotFound,
67
68    /// Multiple control blocks found in target memory. The data contains the control block addresses (up to 5).
69    #[error("Multiple control blocks found in target memory.")]
70    MultipleControlBlocksFound(Vec<u32>),
71
72    /// The control block has been corrupted. The data contains a detailed error.
73    #[error("Control block corrupted: {0}")]
74    ControlBlockCorrupted(String),
75
76    /// Attempted an RTT read/write operation against a Core number that is different from the Core number against which RTT was initialized
77    #[error("Incorrect Core number specified for this operation. Expected {0}, and found {1}")]
78    IncorrectCoreSpecified(usize, usize),
79
80    /// Wraps errors propagated up from probe-rs.
81    #[error("Error communicating with probe: {0}")]
82    Probe(#[from] probe_rs::Error),
83
84    /// Wraps errors propagated up from reading memory on the target.
85    #[error("Unexpected error while reading {0} from target memory. Please report this as a bug.")]
86    MemoryRead(String),
87}
probe_rs_rtt/lib.rs

probe_rs_rtt/
lib.rs
