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//! ```ìgnore
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    /// A new task with `id` was created.
92    fn task_new(id: u32);
93    /// The task with `id` has `info` attributes.
94    fn task_send_info(id: u32, info: TaskInfo);
95    /// The task with `id` has been terminated.
96    fn task_terminate(id: u32);
97    /// The task with `id` will start to run on the CPU now.
98    fn task_exec_begin(id: u32);
99    /// Execution of the current task has ended.
100    fn task_exec_end();
101    /// The task with `id` is ready to run.
102    fn task_ready_begin(id: u32);
103    /// The task with `id` is being blocked/suspended.
104    fn task_ready_end(id: u32);
105
106    /// The RTOS enters idle mode.
107    fn system_idle();
108
109    /// Enter an ISR.
110    fn isr_enter();
111    /// Exit an ISR.
112    fn isr_exit();
113    /// Exit an ISR to the scheduler.
114    fn isr_exit_to_scheduler();
115
116    /// Create a new marker with `id`.
117    fn marker(id: u32);
118    /// Begin event of marker with `id`.
119    fn marker_begin(id: u32);
120    /// End event of marker with `id`.
121    fn marker_end(id: u32);
122}
123
124/// Callbacks to the OS invoked by the tracing system.
125/// This trait can be implemented in the RTOS.
126pub trait RtosTraceOSCallbacks {
127    /// Send a list of all tasks to the tracing system.
128    fn task_list();
129    /// Get system time in microseconds.
130    fn time() -> u64;
131}
132
133/// Callbacks to the application invoked by the tracing system.
134/// This trait can be implemented by user.
135pub trait RtosTraceApplicationCallbacks {
136    /// Send a system and application description to the tracing system.
137    fn system_description();
138    /// Get system clock in Hertz.
139    fn sysclock() -> u32;
140}
rtos_trace/lib.rs

rtos_trace/
lib.rs
