HWT(4)                 FreeBSD Kernel Interfaces Manual                 HWT(4)

NAME

     hwt - Hardware Trace Framework

SYNOPSIS

     options HWT_HOOKS
     device hwt

     At least one of:
     device intel_pt (amd64)
     device coresight (arm64)
     device spe (arm64)

     In rc.conf(5):
     kld_list="hwt"

DESCRIPTION

     The hwt framework provides infrastructure for hardware-assisted tracing.
     It collects detailed information about software execution and stores it
     as events in highly compressed format into DRAM.  The events cover
     information about control flow changes of a program, whether branches
     taken or not, exceptions taken, timing information, cycles elapsed and
     more.  The information collected allows to reconstruct entire program
     flow of a given application without noticeable performance impact.

HARDWARE

     The framework supports several tracing technologies found on arm64 and
     amd64 systems:

     o   ARM Coresight
     o   ARM Statistical Profiling Extension (SPE)
     o   Intel Processor Trace (PT)

     The hwt framework supports two modes of operation:

     CPU mode     Capture CPU activity in kernel mode.

     Thread mode  Capture activity of each of a process's threads in user
                  mode.

MANAGEMENT

     When loaded into kernel, the hwt framework provides /dev/hwt character
     device.  The only ioctl(2) request it accepts is HWT_IOC_ALLOC.  This
     request allocates kernel tracing context (CTX) based on requested mode of
     operation, set of CPUs and/or pid.

     Upon successful CTX allocation, the ioctl returns a CTX identification
     number (ident).

     Each CTX is then managed using its own dedicated character device found
     at /dev/hwt_${ident}_${d}, where ident is a unique identification number
     of tracing context, d is either cpu_id (in HWT CPU mode) or process pid
     (in HWT Thread mode).

HOOKS

     During tracing of a target process, HWT records runtime events such as
     threads creation, exec and mmap system calls.  These events are logged as
     "records" within a particular CTX associated with traced process.

     Additionally, HWT can suspend the target thread upon exec or mmap system
     calls if requested by the user.  This pause allows user-space tools to
     retrieve the records and adjust tracing settings before execution
     continues.  This feature is especially useful when address range
     filtering is enabled, allowing tracing of specific functions within the
     target executable or a dynamic library.

KERNEL OPTIONS

     The following options in the kernel configuration file are mandatory and
     related to hwt operation:

     HWT_HOOKS  Enable kernel hooks.

IOCTL INTERFACE

     Once a CTX is allocated, its management character device accepts several
     ioctl(2) requests:

     HWT_IOC_START       Start tracing.  In HWT CPU mode the tracing does
                         actually start with this ioctl(2) request.  In the
                         Thread mode, the tracing "running" flag set, but
                         tracing begins after scheduler switches the target
                         thread onto CPU and return to user mode.

     HWT_IOC_STOP        Stop tracing of the particular CTX.

     HWT_IOC_RECORD_GET  Copy all or part of records collected during hook
                         invocation and associated with this CTX to userspace.

     HWT_IOC_BUFPTR_GET  Get current pointer in buffer that is filled by
                         tracing units in real-time.

     HWT_IOC_SET_CONFIG  Set architecture-specific config (optional).

     HWT_IOC_WAKEUP      Wake up a thread that has been put to sleep by HWT
                         framework hooks.

     HWT_IOC_SVC_BUF     For SPE-only, the kernel is waiting for userspace to
                         notify that it has copied out a buffer to avoid data
                         loss/overwriting buffers.

SEE ALSO

     tracing(7), hwt(8)

HISTORY

     The hwt framework first appeared in FreeBSD 15.0.

AUTHORS

     Ruslan Bukin <br@FreeBSD.org>
     Bojan Novkovic <bnovkov@freebsd.org>
     Zachary Leaf <zachary.leaf@arm.com>

FreeBSD 15.1-STABLE-HBSD         July 12, 2025                          HWT(4)