twizzler_abi/

trace.rs

//! Tracing data structures
//!
//! This module defines the object and data structures for tracing kernel, thread, etc. events.
//! Tracing is done via the sys_ktrace system call, which takes an object and a trace spec. This
//! object is the "prime" trace object for a sequence of trace objects. The kernel fills these
//! objects with a stream of trace events until they fill up (reach a maximum size defined by the
//! kernel). Once a trace object fills up, the kernel generates a new trace object with the same
//! CreateSpec as the prime object, and starts filling that object with data. It then appends a
//! 'next-object' entry to the object that just filled up, so readers know which object to continue
//! reading from.
//!
//! A single prime tracing object can be associated with multiple TraceSpec structures, enabling
//! that object (or its subsequent objects) to collect a wide variety of data with fine-grained
//! control over which events are collected.
//!
//! Streamed data is tracked via the TraceBase structure, located at the base address of any trace
//! object. The end field defines the current end-point of data within the object. This atomic field
//! is updated by the kernel when trace data is written, and any threads sleeping on this value will
//! wake up.
//!
//! Note that not all trace events are generated synchronously. Asynchronous events are generated by
//! the kernel when in critical states. These events are not guaranteed to be reported in a timely
//! manner, and may be dropped if the system is under heavy load.

use core::sync::atomic::AtomicU64;

use twizzler_rt_abi::object::ObjID;

use crate::{
    pager::{CompletionToKernel, CompletionToPager, KernelCommand, PagerRequest},
    syscall::{
        MapFlags, Syscall, ThreadSyncFlags, ThreadSyncOp, ThreadSyncReference, ThreadSyncSleep,
        TimeSpan,
    },
    thread::ExecutionState,
};

#[derive(Clone, Copy, Debug, Default)]
#[repr(C)]
/// Header for a trace entry. This is always present, and may be optionally followed by additional
/// data, if the `flags` field contains the `HAS_DATA` flag.
pub struct TraceEntryHead {
    /// The ID of the thread that generated this trace entry.
    pub thread: ObjID,
    /// The ID of the security context that generated this trace entry.
    pub sctx: ObjID,
    /// The ID of the memory context that generated this trace entry.
    pub mctx: ObjID,
    /// The ID of the CPU that generated this trace entry.
    pub cpuid: u64,
    /// The time at which this trace entry was generated.
    pub time: TimeSpan,
    /// The event that generated this trace entry.
    pub event: u64,
    /// The kind of trace entry.
    pub kind: TraceKind,
    /// Provided extra data from the [TraceSpec] that matched this entry, or if NEXT_OBJECT is set,
    /// the ID of the next object.
    pub extra_or_next: ObjID,
    /// Flags indicating the type of trace entry.
    pub flags: TraceEntryFlags,
}

impl TraceEntryHead {
    /// Create a new trace entry head with the NEXT_OBJECT flag set.
    pub fn new_next_object(id: ObjID) -> Self {
        Self {
            extra_or_next: id,
            flags: TraceEntryFlags::NEXT_OBJECT,
            ..Default::default()
        }
    }
}

#[derive(Clone, Copy, Debug)]
#[repr(C)]
/// Header for additional data.
pub struct TraceData<T: Copy> {
    /// Reserved for future use.
    pub resv: u64,
    /// Length of the data in bytes (including this header).
    pub len: u32,
    /// Flags for this extra data.
    pub flags: u32,
    /// Data associated with the trace entry.
    pub data: T,
}

impl<T: Copy> TraceData<T> {
    /// Try to cast the data into a concrete Trace Data type, if events match.
    pub fn try_cast<U: TraceDataCast + Copy>(&self, events: u64) -> Option<&TraceData<U>> {
        if events & U::EVENT != 0 {
            unsafe {
                Some(
                    (self as *const Self)
                        .cast::<TraceData<U>>()
                        .as_ref()
                        .unwrap(),
                )
            }
        } else {
            None
        }
    }
}

#[repr(C)]
/// The base structure for a trace object.
pub struct TraceBase {
    /// The end point for valid data. The kernel will update this and submit a thread_sync wakeup
    /// when writing trace data to this object.
    pub end: AtomicU64,
    /// The start point of valid data in this object. This is set by the kernel during
    /// initialization and then not updated again.
    pub start: u64,
}

impl TraceBase {
    /// Get a waiter for this tracing object based on how much data has thus-far been read.
    pub fn waiter(&self, pos: u64) -> ThreadSyncSleep {
        ThreadSyncSleep::new(
            ThreadSyncReference::Virtual(&self.end),
            pos,
            ThreadSyncOp::Equal,
            ThreadSyncFlags::empty(),
        )
    }
}

#[derive(Clone, Copy, Debug, PartialEq, Eq, Default, PartialOrd, Ord)]
#[repr(u16)]
/// Kinds of tracing events.
pub enum TraceKind {
    Kernel,
    Thread,
    Object,
    Context,
    Security,
    Pager,
    #[default]
    Other = 0xffff,
}

bitflags::bitflags! {
    #[derive(Clone, Copy, Debug)]
    pub struct TraceFlags: u16 {
        /// Include additional data.
        const DATA = 1;
        // TODO: support collecting thread registers.
        //const REGISTERS = 2;
    }
}

bitflags::bitflags! {
    #[derive(Clone, Copy, Debug, Default)]
    /// Trace entry flags.
    pub struct TraceEntryFlags: u16 {
        /// The kernel dropped a trace event when processing.
        const DROPPED = 1;
        /// This trace entry is followed by a TraceData entry.
        const HAS_DATA = 2;
        /// This trace entry is NOT a trace entry, and instead indicates that
        /// the kernel ran out of room in the current object. The extra_or_next field
        /// contains the object ID of the next trace object to read from.
        const NEXT_OBJECT = 4;
    }
}

// Thread events
/// Thread has exited.
pub const THREAD_EXIT: u64 = 1;
/// Thread context switch occurred.
pub const THREAD_CONTEXT_SWITCH: u64 = 2;
/// Thread sampling event occurred.
pub const THREAD_SAMPLE: u64 = 4;
/// Thread made a system call.
pub const THREAD_SYSCALL_ENTRY: u64 = 8;
/// Thread was blocked.
pub const THREAD_BLOCK: u64 = 0x10;
/// Thread was resumed from blocked state.
pub const THREAD_RESUME: u64 = 0x20;
/// Thread migrated to a different CPU.
pub const THREAD_MIGRATE: u64 = 0x40;

// Object events
/// Object control operation occurred.
pub const OBJECT_CTRL: u64 = 1;
/// Object was created.
pub const OBJECT_CREATE: u64 = 2;

// Context events
/// Memory mapping operation occurred.
pub const CONTEXT_MAP: u64 = 1;
/// Memory unmapping operation occurred.
pub const CONTEXT_UNMAP: u64 = 2;
/// Memory fault occurred.
pub const CONTEXT_FAULT: u64 = 4;
/// TLB shootdown occurred.
pub const CONTEXT_SHOOTDOWN: u64 = 8;
/// Memory invalidation occurred.
pub const CONTEXT_INVALIDATION: u64 = 0x10;

// Security events
/// Entered a security context.
pub const SECURITY_CTX_ENTRY: u64 = 1;
/// Exited a security context.
pub const SECURITY_CTX_EXIT: u64 = 2;
/// Security violation occurred.
pub const SECURITY_VIOLATION: u64 = 4;

// Kernel events
/// Kernel memory allocation occurred.
pub const KERNEL_ALLOC: u64 = 1;

// Pager events
/// Pager command was sent.
pub const PAGER_COMMAND_SEND: u64 = 1;
/// Pager command was responded to.
pub const PAGER_COMMAND_RESPONDED: u64 = 2;
/// Pager request was received.
pub const PAGER_REQUEST_RECV: u64 = 4;
/// Pager request was completed.
pub const PAGER_REQUEST_COMPLETED: u64 = 8;

/// Trait for types that can be cast from trace data based on event types.
pub trait TraceDataCast {
    /// The event constant associated with this trace data type.
    const EVENT: u64;
}

/// Event data for thread operations.
#[repr(C)]
#[derive(Clone, Copy, Debug)]
pub struct ThreadEvent {
    /// Generic value associated with the thread event.
    pub val: u64,
}

/// Event data for system call entry.
#[repr(C)]
#[derive(Clone, Copy, Debug)]
pub struct SyscallEntryEvent {
    /// Instruction pointer at syscall entry.
    pub ip: u64,
    /// The system call number.
    pub num: Syscall,
    /// Arguments.
    pub args: [u64; 6],
}

/// Event data for thread context switches.
#[repr(C)]
#[derive(Clone, Copy, Debug)]
pub struct ThreadCtxSwitch {
    /// ID of the thread being switched to, if any.
    pub to: Option<ObjID>,
}

/// Event data for thread migration between CPUs.
#[repr(C)]
#[derive(Clone, Copy, Debug)]
pub struct ThreadMigrate {
    /// ID of the CPU being migrated to.
    pub to: u64,
}

/// Event data for thread sampling operations.
#[repr(C)]
#[derive(Clone, Copy, Debug)]
pub struct ThreadSamplingEvent {
    /// Instruction pointer at sampling time.
    pub ip: u64,
    /// Thread execution state at sampling time.
    pub state: ExecutionState,
}

/// Event data for memory mapping operations.
#[repr(C)]
#[derive(Clone, Copy, Debug)]
pub struct ContextMapEvent {
    /// Virtual address being mapped.
    pub addr: u64,
    /// Length of the mapping in bytes.
    pub len: u64,
    /// Object being mapped.
    pub obj: ObjID,
    /// Mapping flags.
    pub flags: MapFlags,
}

bitflags::bitflags! {
    #[derive(Clone, Copy, Debug)]
    /// Flags describing memory fault characteristics.
    pub struct FaultFlags: u64 {
        /// Fault occurred on read access.
        const READ = 1;
        /// Fault occurred on write access.
        const WRITE = 2;
        /// Fault occurred on execute access.
        const EXEC = 4;
        /// Fault occurred in user mode.
        const USER = 8;
        /// Fault was handled by pager.
        const PAGER = 0x10;
        /// Fault involved large pages.
        const LARGE = 0x20;
    }
}

/// Event data for memory faults.
#[derive(Clone, Copy, Debug)]
pub struct ContextFaultEvent {
    /// Virtual address that faulted.
    pub addr: u64,
    /// Object associated with the fault.
    pub obj: ObjID,
    /// Flags describing the fault type.
    pub flags: FaultFlags,
    /// Time spent processing the fault.
    pub processing_time: TimeSpan,
}

/// Event data for pager commands sent to kernel.
#[derive(Clone, Copy, Debug)]
pub struct PagerCommandSent {
    /// The command that was sent.
    pub cmd: KernelCommand,
    /// Queue ID for the command.
    pub qid: u32,
}

/// Event data for pager command responses.
#[derive(Clone, Copy, Debug)]
pub struct PagerCommandResponded {
    /// Queue ID for the response.
    pub qid: u32,
    /// The response data.
    pub resp: CompletionToKernel,
}

/// Event data for pager requests received.
#[derive(Clone, Copy, Debug)]
pub struct PagerRequestRecv {
    /// The request that was received.
    pub req: PagerRequest,
    /// Queue ID for the request.
    pub qid: u32,
}

/// Event data for completed pager requests.
#[derive(Clone, Copy, Debug)]
pub struct PagerRequestCompleted {
    /// Queue ID for the completed request.
    pub qid: u32,
    /// The completion response.
    pub resp: CompletionToPager,
}

impl TraceDataCast for ContextMapEvent {
    const EVENT: u64 = CONTEXT_MAP;
}

impl TraceDataCast for ContextFaultEvent {
    const EVENT: u64 = CONTEXT_FAULT;
}

impl TraceDataCast for ThreadEvent {
    const EVENT: u64 = THREAD_EXIT;
}

impl TraceDataCast for ThreadCtxSwitch {
    const EVENT: u64 = THREAD_CONTEXT_SWITCH;
}

impl TraceDataCast for ThreadMigrate {
    const EVENT: u64 = THREAD_MIGRATE;
}

impl TraceDataCast for PagerCommandSent {
    const EVENT: u64 = PAGER_COMMAND_SEND;
}

impl TraceDataCast for PagerCommandResponded {
    const EVENT: u64 = PAGER_COMMAND_RESPONDED;
}

impl TraceDataCast for PagerRequestRecv {
    const EVENT: u64 = PAGER_REQUEST_RECV;
}

impl TraceDataCast for PagerRequestCompleted {
    const EVENT: u64 = PAGER_REQUEST_COMPLETED;
}

impl TraceDataCast for SyscallEntryEvent {
    const EVENT: u64 = THREAD_SYSCALL_ENTRY;
}

impl TraceDataCast for ThreadSamplingEvent {
    const EVENT: u64 = THREAD_SAMPLE;
}