rtos_trace/
lib.rs

1//! Set of traits used to trace RTOS internals.
2//!
3//! # Features
4//!
5//! - `trace_impl`: Activates tracing function (on by default). Can be used by
6//!    the RTOS to deactivate tracing.
7//!
8//! # Implementation
9//!
10//! The backend is required implement [`RtosTrace`](crate::RtosTrace).
11//!
12//! Existing implementation:
13//! - [SEGGER SystemView](https://docs.rs/systemview-target/)
14//!
15//! # Usage
16//!
17//! ## RTOS
18//!
19//! The RTOS can implement [`RtosTraceOSCallbacks`](crate::RtosTraceOSCallbacks) to provide additional
20//! information upon request from the tracing software. For example:
21//! ```ignore
22//! rtos_trace::global_os_callbacks!{Scheduler}
23//!
24//! impl rtos_trace::RtosTraceOSCallbacks for Scheduler {
25//!     fn task_list() {
26//!         /*..*/
27//!         for task in tasks.iter() {
28//!             trace::task_send_info(task.id(), task.info());
29//!         }
30//!     }
31//!     /*..*/
32//! }
33//! ```
34//!
35//! Usage for the RTOS maintainer is simple:
36//! ```ignore
37//! use rtos_trace::{RtosTrace, trace}
38//!
39//! pub fn spawn_task(/*..*/) {
40//!     /*..*/
41//!     trace::task_new(task_id);
42//! }
43//! ```
44//!
45//! ## Application
46//!
47//! Similar to a global logger the user must provide a tracing backend, i.e.:
48//! ```ignore
49//! use systemview_target::SystemView;
50//! rtos_trace::global_trace!{SystemView}
51//! ```
52//!
53//! The user can implement [`RtosTraceApplicationCallbacks`] to provide
54//! additional information upon request from the tracing software. For example:
55//! ```ignore
56//! struct Application;
57//! rtos_trace::global_application_callbacks!{Application}
58//!
59//! impl rtos_trace::RtosTraceApplicationCallbacks for Application {
60//!     fn system_description() {
61//!         systemview_target::send_system_desc_app_name!("Espresso Machine");
62//!         systemview_target::send_system_desc_device!("STM32F769NI");
63//!         systemview_target::send_system_desc_core!("Cortex-M7");
64//!         systemview_target::send_system_desc_os!("Bern RTOS");
65//!         systemview_target::send_system_desc_interrupt!(15, "SysTick");
66//!     }
67//!     /*..*/
68//! }
69//!
70//! ```
71
72#![no_std]
73
74mod macros;
75pub mod trace;
76
77/// Task info block.
78pub struct TaskInfo {
79    /// Names as static string.
80    pub name: &'static str,
81    /// Task priority number.
82    pub priority: u32,
83    /// Start address of the stack.
84    pub stack_base: usize,
85    /// Size of the stack in bytes.
86    pub stack_size: usize,
87}
88
89/// Collection of tracing functions which are called by the RTOS.
90pub trait RtosTrace {
91    /// Start tracing.
92    fn start();
93    /// Stop tracing.
94    fn stop();
95
96    /// A new task with `id` was created.
97    fn task_new(id: u32);
98    /// The task with `id` has `info` attributes.
99    fn task_send_info(id: u32, info: TaskInfo);
100    /// Convenience function to create a new task with a name only.
101    fn task_new_stackless(id: u32, name: &'static str, priority: u32);
102    /// The task with `id` has been terminated.
103    fn task_terminate(id: u32);
104    /// The task with `id` will start to run on the CPU now.
105    fn task_exec_begin(id: u32);
106    /// Execution of the current task has ended.
107    fn task_exec_end();
108    /// The task with `id` is ready to run.
109    fn task_ready_begin(id: u32);
110    /// The task with `id` is being blocked/suspended.
111    fn task_ready_end(id: u32);
112
113    /// The RTOS enters idle mode.
114    fn system_idle();
115
116    /// Enter an ISR.
117    fn isr_enter();
118    /// Exit an ISR.
119    fn isr_exit();
120    /// Exit an ISR to the scheduler.
121    fn isr_exit_to_scheduler();
122
123    /// Create a new marker with `id`.
124    fn name_marker(id: u32, name: &'static str);
125    /// Create a new marker with `id`.
126    fn marker(id: u32);
127    /// Begin event of marker with `id`.
128    fn marker_begin(id: u32);
129    /// End event of marker with `id`.
130    fn marker_end(id: u32);
131}
132
133/// Callbacks to the OS invoked by the tracing system.
134/// This trait can be implemented in the RTOS.
135pub trait RtosTraceOSCallbacks {
136    /// Send a list of all tasks to the tracing system.
137    fn task_list();
138    /// Get system time in microseconds.
139    fn time() -> u64;
140}
141
142/// Callbacks to the application invoked by the tracing system.
143/// This trait can be implemented by user.
144pub trait RtosTraceApplicationCallbacks {
145    /// Send a system and application description to the tracing system.
146    fn system_description();
147    /// Get system clock in Hertz.
148    fn sysclock() -> u32;
149}
rtos_trace/lib.rs

rtos_trace/
lib.rs
