Skip to main content

ax_tracepoint/
lib.rs

1//! A Rust library for defining and managing tracepoints in a no_std environment.
2//! It provides macros and structures to create tracepoints, manage their state,
3//! and handle trace events efficiently.
4//! The library is designed to be lightweight and suitable for embedded systems or
5//! kernel-level programming where the standard library is not available.
6//! It leverages Rust's powerful macro system to simplify the creation and management of tracepoints.
7//! The macros provided by this library allow for easy insertion of tracepoints into code with minimal overhead.
8#![deny(missing_docs)]
9#![no_std]
10#![allow(clippy::new_without_default)]
11extern crate alloc;
12
13mod basic_macro;
14mod point;
15pub mod ptr;
16mod trace_pipe;
17
18use alloc::{
19    boxed::Box,
20    collections::BTreeMap,
21    format,
22    string::{String, ToString},
23    sync::Arc,
24    vec::Vec,
25};
26use core::mem::{align_of, size_of};
27
28#[doc(hidden)]
29pub use basic_macro::TraceRecord;
30pub use paste;
31pub use point::{
32    CommonTracePointMeta, ExtTracePoint, RawTraceEventFunc, TraceCallbackType, TraceDefaultFunc,
33    TraceEntry, TraceEventFunc, TraceField, TracePoint,
34};
35pub use tp_lexer;
36use tp_lexer::compile_with_schema;
37pub use trace_pipe::{
38    TraceCmdLineCache, TraceCmdLineCacheSnapshot, TraceEntryParser, TraceParseError, TracePipeOps,
39    TracePipeRaw, TracePipeRecord, TracePipeSnapshot,
40};
41
42/// KernelTraceOps trait provides kernel-level operations for tracing.
43pub trait KernelTraceOps: Send + Sync + 'static {
44    /// Get the current process ID.
45    fn current_pid() -> u32;
46    /// Push a raw record to the trace pipe.
47    fn trace_pipe_push_raw_record(buf: &[u8]);
48    /// Cache the process name for a given PID.
49    fn trace_cmdline_push(pid: u32);
50    /// Access runtime state for a tracepoint ID.
51    ///
52    /// Implementations may hold a read-side lock while executing `f`. The
53    /// tracing fast path may call user callbacks from inside this closure, so
54    /// callbacks must not call APIs that need `write_tracepoint_state`, such as
55    /// callback registration, callback unregistration, or filter updates.
56    ///
57    /// If the read-side implementation is non-reentrant, callbacks must also
58    /// avoid recursively triggering tracepoints backed by the same state
59    /// registry. Violating these restrictions may deadlock.
60    ///
61    /// Implementations based on RCU, snapshots, or another non-blocking
62    /// read-side mechanism may relax these restrictions.
63    fn read_tracepoint_state<R>(id: u32, f: impl FnOnce(&ExtTracePoint<Self>) -> R) -> R;
64    /// Mutably access runtime state for a tracepoint ID.
65    ///
66    /// This is a management-path API. If `read_tracepoint_state` can execute
67    /// callbacks while holding a read-side lock, this method must not be called
68    /// from those callbacks. The update closure must not recursively invoke
69    /// `write_tracepoint_state` for the same state unless the implementation
70    /// explicitly provides a reentrant writer.
71    fn write_tracepoint_state<R>(id: u32, f: impl FnOnce(&mut ExtTracePoint<Self>) -> R) -> R;
72}
73
74/// TracePointMap is a mapping from tracepoint IDs to TracePoint references.
75#[derive(Debug)]
76pub struct TracePointMap<K: KernelTraceOps>(BTreeMap<u32, &'static TracePoint<K>>);
77
78impl<K: KernelTraceOps> TracePointMap<K> {
79    /// Create a new TracePointMap
80    pub const fn new() -> Self {
81        Self(BTreeMap::new())
82    }
83
84    /// Returns the tracepoint registered for `id`.
85    pub fn get(&self, id: &u32) -> Option<&'static TracePoint<K>> {
86        self.0.get(id).copied()
87    }
88
89    /// Iterates over tracepoint IDs and descriptors in ID order.
90    pub fn iter(&self) -> impl Iterator<Item = (&u32, &'static TracePoint<K>)> + '_ {
91        self.0.iter().map(|(id, tracepoint)| (id, *tracepoint))
92    }
93
94    /// Iterates over tracepoint descriptors in ID order.
95    pub fn values(&self) -> impl Iterator<Item = &'static TracePoint<K>> + '_ {
96        self.0.values().copied()
97    }
98
99    /// Returns the number of registered tracepoints.
100    pub fn len(&self) -> usize {
101        self.0.len()
102    }
103
104    /// Returns whether the map contains no tracepoints.
105    pub fn is_empty(&self) -> bool {
106        self.0.is_empty()
107    }
108
109    fn insert(&mut self, id: u32, tracepoint: &'static TracePoint<K>) {
110        self.0.insert(id, tracepoint);
111    }
112}
113
114/// TracePointFormatFile provides a way to get the format of the tracepoint.
115#[derive(Debug, Clone)]
116pub struct TracePointFormatFile<K: KernelTraceOps> {
117    tracepoint: &'static TracePoint<K>,
118}
119
120impl<K: KernelTraceOps> TracePointFormatFile<K> {
121    /// Create a new TracePointFormatFile for the given tracepoint.
122    pub fn new(tracepoint: &'static TracePoint<K>) -> Self {
123        Self { tracepoint }
124    }
125
126    /// Read the tracepoint format
127    ///
128    /// Returns the format string of the tracepoint.
129    pub fn read(&self) -> String {
130        self.tracepoint.print_fmt()
131    }
132}
133
134/// TracePointEnableFile provides a way to enable or disable the default trace pipe callback.
135#[derive(Debug, Clone)]
136pub struct TracePointEnableFile;
137
138impl TracePointEnableFile {
139    /// Create a new TracePointEnableFile
140    pub fn new() -> Self {
141        Self {}
142    }
143
144    /// Read whether callback dispatch is enabled.
145    ///
146    /// Returns true if the tracepoint is enabled, false otherwise.
147    pub fn read<K: KernelTraceOps>(&self, tracepoint: &'static TracePoint<K>) -> &'static str {
148        if tracepoint.key_is_enabled() {
149            "1\n"
150        } else {
151            "0\n"
152        }
153    }
154    /// Register or unregister the default trace pipe callback.
155    ///
156    /// The runtime-state publisher is responsible for making the resulting
157    /// callback gate agree with the newly published callback set.
158    pub fn write<K: KernelTraceOps>(&self, ext_tracepoint: &mut ExtTracePoint<K>, enable: char) {
159        match enable {
160            '1' => {
161                let default_callback = ext_tracepoint.default_callback();
162                ext_tracepoint.register(TraceCallbackType::Default(default_callback));
163            }
164            '0' => {
165                let default_callback = ext_tracepoint.default_callback();
166                ext_tracepoint.unregister(TraceCallbackType::Default(default_callback));
167            }
168            _ => {
169                log::warn!("Invalid value for tracepoint enable: {enable}");
170            }
171        }
172    }
173}
174
175/// TracePointIdFile provides a way to read the tracepoint ID.
176#[derive(Debug, Clone)]
177pub struct TracePointIdFile<K: KernelTraceOps> {
178    tracepoint: &'static TracePoint<K>,
179}
180
181impl<K: KernelTraceOps> TracePointIdFile<K> {
182    /// Create a new TracePointIdFile with the given tracepoint.
183    pub fn new(tracepoint: &'static TracePoint<K>) -> Self {
184        Self { tracepoint }
185    }
186
187    /// Read the tracepoint ID
188    ///
189    /// Returns the ID of the tracepoint.
190    pub fn read(&self) -> String {
191        format!("{}\n", self.tracepoint.id())
192    }
193}
194
195/// An error produced while updating a tracepoint filter.
196#[derive(Clone, Copy, Debug, Eq, PartialEq, thiserror::Error)]
197pub enum TraceFilterError {
198    /// The supplied filter expression was empty.
199    #[error("filter expression is empty")]
200    EmptyExpression,
201    /// The supplied filter expression could not be compiled against the event schema.
202    #[error("filter expression failed to compile")]
203    CompileExpression,
204}
205
206/// TraceFilterFile provides a way to set filters on the tracepoint.
207#[derive(Debug)]
208pub struct TraceFilterFile {
209    filter_expr: Option<String>,
210    pre_error: Option<String>,
211}
212
213impl TraceFilterFile {
214    /// Create a new TraceFilterFile with no filter expression and no pre-error.
215    pub fn new() -> Self {
216        Self {
217            filter_expr: None,
218            pre_error: None,
219        }
220    }
221
222    /// Read the tracepoint filter.
223    ///
224    /// Returns the current filter expression or an error message if there was a pre-error.
225    pub fn read(&self) -> String {
226        if let Some(err) = self.pre_error.as_ref() {
227            return err.clone();
228        }
229        if let Some(filter) = self.filter_expr.as_ref() {
230            filter.clone()
231        } else {
232            "none\n".to_string()
233        }
234    }
235
236    /// Write a new filter expression to the tracepoint.
237    pub fn write<K: KernelTraceOps>(
238        &mut self,
239        ext_tracepoint: &mut ExtTracePoint<K>,
240        filter: &str,
241    ) -> Result<(), TraceFilterError> {
242        let filter = filter.trim();
243        if filter.is_empty() {
244            self.pre_error = Some("filter expression is empty\n".to_string());
245            return Err(TraceFilterError::EmptyExpression);
246        }
247
248        if filter == "0" {
249            // clear the filter and pre-error
250            self.filter_expr = None;
251            self.pre_error = None;
252            ext_tracepoint.set_compiled_expr(None);
253            Ok(())
254        } else {
255            let schema = ext_tracepoint.trace_point().schema();
256            let res = compile_with_schema(filter, *schema);
257            match res {
258                Ok(compiled_expr) => {
259                    self.filter_expr = Some(filter.to_string());
260                    self.pre_error = None;
261                    ext_tracepoint.set_compiled_expr(Some(compiled_expr));
262                    Ok(())
263                }
264                Err(mut e) => {
265                    e.message.push('\n');
266                    self.pre_error = Some(e.message);
267                    Err(TraceFilterError::CompileExpression)
268                }
269            }
270        }
271    }
272}
273
274/// An error produced while discovering linker-collected tracepoints.
275#[derive(Clone, Copy, Debug, Eq, PartialEq, thiserror::Error)]
276pub enum TraceInitError {
277    /// The linker exported the section end before its start.
278    #[error("tracepoint section end precedes its start")]
279    InvalidSectionBounds,
280    /// The linker section start does not satisfy the metadata alignment.
281    #[error("tracepoint section start {address:#x} is not aligned to {alignment} bytes")]
282    MisalignedSection {
283        /// Address exported as `__start_tracepoint`.
284        address: usize,
285        /// Required metadata alignment.
286        alignment: usize,
287    },
288    /// The linker section byte length is not a whole metadata entry count.
289    #[error("tracepoint section size {bytes} is not divisible by entry size {entry_size}")]
290    InvalidSectionSize {
291        /// Section size in bytes.
292        bytes: usize,
293        /// Size of one metadata entry.
294        entry_size: usize,
295    },
296    /// More tracepoints were linked than the 32-bit event ID can represent.
297    #[error("too many tracepoints for a 32-bit event ID")]
298    TooManyTracepoints,
299}
300
301unsafe extern "C" {
302    fn __start_tracepoint();
303    fn __stop_tracepoint();
304}
305
306/// Initialize the tracing events
307///
308/// The K type parameter is the kernel trace operations type used for performing kernel-level operations.
309///
310/// Returns the static tracepoint map and runtime tracepoint states.
311///
312/// The returned [`TracePointMap`] maps tracepoint IDs to static tracepoint
313/// metadata. The returned [`ExtTracePoint`] values contain runtime callback and
314/// filter state. The caller must install these runtime states into the
315/// [`KernelTraceOps::read_tracepoint_state`] and
316/// [`KernelTraceOps::write_tracepoint_state`] backing registry before enabling
317/// or triggering tracepoints.
318///
319/// The final linker script must define `__start_tracepoint` and
320/// `__stop_tracepoint`, keep all `.tracepoint` input sections between them,
321/// and align the start for [`CommonTracePointMeta`]. The supplied
322/// `my_section.ld` is a reference fragment.
323pub fn global_init_events<K: KernelTraceOps>()
324-> Result<(TracePointMap<K>, Vec<ExtTracePoint<K>>), TraceInitError> {
325    let tracepoint_data_start = __start_tracepoint as *const () as usize;
326    let tracepoint_data_end = __stop_tracepoint as *const () as usize;
327    log::info!(
328        "tracepoint_data_start: {:#x}, tracepoint_data_end: {:#x}",
329        tracepoint_data_start,
330        tracepoint_data_end
331    );
332    let section_bytes = tracepoint_data_end
333        .checked_sub(tracepoint_data_start)
334        .ok_or(TraceInitError::InvalidSectionBounds)?;
335    let metadata_alignment = align_of::<CommonTracePointMeta>();
336    if !tracepoint_data_start.is_multiple_of(metadata_alignment) {
337        return Err(TraceInitError::MisalignedSection {
338            address: tracepoint_data_start,
339            alignment: metadata_alignment,
340        });
341    }
342    let metadata_size = size_of::<CommonTracePointMeta>();
343    if !section_bytes.is_multiple_of(metadata_size) {
344        return Err(TraceInitError::InvalidSectionSize {
345            bytes: section_bytes,
346            entry_size: metadata_size,
347        });
348    }
349    let tracepoint_data_len = section_bytes / metadata_size;
350    // SAFETY: the bounds, alignment, and whole-entry length are checked above.
351    // The macro emits this exact `repr(C)` metadata type into `.tracepoint`,
352    // and the linker contract keeps those entries in the exported range.
353    let linked_metadata = unsafe {
354        core::slice::from_raw_parts(
355            tracepoint_data_start as *const CommonTracePointMeta,
356            tracepoint_data_len,
357        )
358    };
359    let mut tracepoint_data = linked_metadata
360        .iter()
361        .filter(|metadata| metadata.belongs_to::<K>())
362        .collect::<Vec<_>>();
363    tracepoint_data.sort_by(|a, b| {
364        // SAFETY: the iterator above retained only metadata tagged with `K`.
365        let a = unsafe { a.trace_point::<K>() };
366        // SAFETY: the iterator above retained only metadata tagged with `K`.
367        let b = unsafe { b.trace_point::<K>() };
368        a.name().cmp(b.name()).then(a.system().cmp(b.system()))
369    });
370    log::info!("tracepoint_data_len: {tracepoint_data_len}");
371
372    let mut tp_map = TracePointMap::new();
373    let mut ext_tps = Vec::with_capacity(tracepoint_data_len);
374
375    for (index, tracepoint_meta) in tracepoint_data.into_iter().enumerate() {
376        // SAFETY: `tracepoint_data` contains only metadata tagged with `K`.
377        let tracepoint = unsafe { tracepoint_meta.trace_point::<K>() };
378        let id = u32::try_from(index).map_err(|_| TraceInitError::TooManyTracepoints)?;
379        tracepoint.set_id(id);
380
381        // SAFETY: `CommonTracePointMeta::new` accepts only the erased default
382        // callback paired with this exact generated tracepoint.
383        let default_callback = Arc::new(unsafe {
384            TraceDefaultFunc::from_erased(tracepoint_meta.print_func(), Box::new(()))
385        });
386
387        let ext_tracepoint = ExtTracePoint::new(tracepoint, default_callback);
388
389        log::info!(
390            "tracepoint registered: {}:{}",
391            tracepoint.system(),
392            tracepoint.name(),
393        );
394
395        tp_map.insert(id, tracepoint);
396        ext_tps.push(ext_tracepoint);
397    }
398
399    Ok((tp_map, ext_tps))
400}