FreeBSD Manual Pages
HWT(4) 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, ex- ceptions taken, timing information, cycles elapsed and more. The informa- tion collected allows to reconstruct entire program flow of a given appli- cation without noticeable performance impact. HARDWARE The framework supports several tracing technologies found on arm64 and amd64 systems: * ARM Coresight * ARM Statistical Profiling Extension (SPE) * 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 de- vice. The only ioctl(2) request it accepts is HWT_IOC_ALLOC. This request allocates kernel tracing context (CTX) based on requested mode of opera- tion, set of CPUs and/or pid. Upon successful CTX allocation, the ioctl returns a CTX identification num- ber (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 re- trieve 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 actu- ally start with this ioctl(2) request. In the Thread mode, the tracing "running" flag set, but tracing be- gins 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 invo- cation 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 NovkoviA <bnovkov@freebsd.org> Zachary Leaf <zachary.leaf@arm.com> FreeBSD ports 15.quarterly July 12, 2025 HWT(4)
NAME | SYNOPSIS | DESCRIPTION | HARDWARE | MANAGEMENT | HOOKS | KERNEL OPTIONS | IOCTL INTERFACE | SEE ALSO | HISTORY | AUTHORS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=hwt&sektion=4&manpath=FreeBSD+15.1-RELEASE+and+Ports.quarterly>