Module trace

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.

Structs

ContextFaultEvent

Event data for memory faults.

ContextMapEvent

Event data for memory mapping operations.

FaultFlags

Flags describing memory fault characteristics.

PagerCommandResponded

Event data for pager command responses.

PagerCommandSent

Event data for pager commands sent to kernel.

PagerRequestCompleted

Event data for completed pager requests.

PagerRequestRecv

Event data for pager requests received.

SyscallEntryEvent

Event data for system call entry.

ThreadCtxSwitch

Event data for thread context switches.

ThreadEvent

Event data for thread operations.

ThreadMigrate

Event data for thread migration between CPUs.

ThreadSamplingEvent

Event data for thread sampling operations.

TraceBase

The base structure for a trace object.

TraceData

Header for additional data.

TraceEntryFlags

Trace entry flags.

TraceEntryHead

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.

TraceFlags

Enums

TraceKind

Kinds of tracing events.

Constants

CONTEXT_FAULT

Memory fault occurred.

CONTEXT_INVALIDATION

Memory invalidation occurred.

CONTEXT_MAP

Memory mapping operation occurred.

CONTEXT_SHOOTDOWN

TLB shootdown occurred.

CONTEXT_UNMAP

Memory unmapping operation occurred.

KERNEL_ALLOC

Kernel memory allocation occurred.

OBJECT_CREATE

Object was created.

OBJECT_CTRL

Object control operation occurred.

PAGER_COMMAND_RESPONDED

Pager command was responded to.

PAGER_COMMAND_SEND

Pager command was sent.

PAGER_REQUEST_COMPLETED

Pager request was completed.

PAGER_REQUEST_RECV

Pager request was received.

SECURITY_CTX_ENTRY

Entered a security context.

SECURITY_CTX_EXIT

Exited a security context.

SECURITY_VIOLATION

Security violation occurred.

THREAD_BLOCK

Thread was blocked.

THREAD_CONTEXT_SWITCH

Thread context switch occurred.

THREAD_EXIT

Thread has exited.

THREAD_MIGRATE

Thread migrated to a different CPU.

THREAD_RESUME

Thread was resumed from blocked state.

THREAD_SAMPLE

Thread sampling event occurred.

THREAD_SYSCALL_ENTRY

Thread made a system call.

Traits

TraceDataCast

Trait for types that can be cast from trace data based on event types.