1.\" 2.\" Copyright (c) 2025 Ruslan Bukin <br@bsdpad.com> 3.\" 4.\" SPDX-License-Identifier: BSD-2-Clause 5.\" 6.Dd July 12, 2025 7.Dt HWT 4 8.Os 9.Sh NAME 10.Nm hwt 11.Nd Hardware Trace Framework 12.Sh SYNOPSIS 13.Cd "options HWT_HOOKS" 14.Cd "device hwt" 15.Pp 16At least one of: 17.Cd "device intel_pt" 18.Pq amd64 19.Cd "device coresight" 20.Pq arm64 21.Cd "device spe" 22.Pq arm64 23.Pp 24In 25.Xr rc.conf 5 : 26.Cd kld_list="hwt" 27.Sh DESCRIPTION 28The 29.Nm 30framework provides infrastructure for hardware-assisted tracing. 31It collects detailed information about software execution and stores it as 32events in highly compressed format into DRAM. 33The events cover information about control flow changes of a program, whether 34branches taken or not, exceptions taken, timing information, cycles elapsed and 35more. 36The information collected allows to reconstruct entire program flow of a given 37application without noticeable performance impact. 38.Sh HARDWARE 39The framework supports several tracing technologies found on 40.Cd arm64 41and 42.Cd amd64 43systems: 44.Pp 45.Bl -bullet -compact 46.It 47ARM Coresight 48.It 49ARM Statistical Profiling Extension (SPE) 50.It 51Intel Processor Trace (PT) 52.El 53.Pp 54The 55.Nm 56framework supports two modes of operation: 57.Bl -tag -width "Thread mode" 58.It Em CPU mode 59Capture CPU activity in kernel mode. 60.It Em Thread mode 61Capture activity of each of a process's threads in user mode. 62.El 63.Sh MANAGEMENT 64When loaded into kernel, the 65.Nm 66framework provides 67.Pa /dev/hwt 68character device. 69The only 70.Xr ioctl 2 71request it accepts is 72.Dv HWT_IOC_ALLOC . 73This request allocates kernel tracing context (CTX) based on requested mode of 74operation, set of CPUs and/or pid. 75.Pp 76Upon successful CTX allocation, the ioctl returns a CTX identification 77number (ident). 78.Pp 79Each CTX is then managed using its own dedicated character device found at 80.Pa "/dev/hwt_${ident}_${d}", 81where ident is a unique identification number of tracing context, d is either 82cpu_id (in HWT CPU mode) or process pid (in HWT Thread mode). 83.Sh HOOKS 84During tracing of a target process, HWT records runtime events such as threads 85creation, exec and mmap system calls. 86These events are logged as "records" within a particular CTX associated with 87traced process. 88.Pp 89Additionally, HWT can suspend the target thread upon exec or mmap system calls 90if requested by the user. 91This pause allows user-space tools to retrieve the records and adjust tracing 92settings before execution continues. 93This feature is especially useful when address range filtering is enabled, 94allowing tracing of specific functions within the target executable or a 95dynamic library. 96.Sh KERNEL OPTIONS 97The following options in the kernel configuration file are mandatory and 98related to 99.Nm 100operation: 101.Pp 102.Bl -tag -width ".Dv HWT_HOOKS" -compact 103.It Dv HWT_HOOKS 104Enable kernel hooks. 105.El 106.Sh IOCTL INTERFACE 107Once a CTX is allocated, its management character device accepts several 108.Xr ioctl 2 109requests: 110.Bl -tag -width "HWT_IOC_RECORD_GET" 111.It Dv HWT_IOC_START 112Start tracing. 113In HWT CPU mode the tracing does actually start with this 114.Xr ioctl 2 115request. 116In the Thread mode, the tracing "running" flag set, but tracing begins after 117scheduler switches the target thread onto CPU and return to user mode. 118.It Dv HWT_IOC_STOP 119Stop tracing of the particular CTX. 120.It Dv HWT_IOC_RECORD_GET 121Copy all or part of records collected during hook invocation and associated 122with this CTX to userspace. 123.It Dv HWT_IOC_BUFPTR_GET 124Get current pointer in buffer that is filled by tracing units in real-time. 125.It Dv HWT_IOC_SET_CONFIG 126Set architecture-specific config (optional). 127.It Dv HWT_IOC_WAKEUP 128Wake up a thread that has been put to sleep by HWT framework hooks. 129.It Dv HWT_IOC_SVC_BUF 130For SPE-only, the kernel is waiting for userspace to notify that it has copied 131out a buffer to avoid data loss/overwriting buffers. 132.El 133.Sh SEE ALSO 134.Xr tracing 7 , 135.Xr hwt 8 136.Sh HISTORY 137The 138.Nm 139framework first appeared in 140.Fx 15.0 . 141.Sh AUTHORS 142.An Ruslan Bukin Aq Mt br@FreeBSD.org 143.An Bojan Novković Aq Mt bnovkov@freebsd.org 144.An Zachary Leaf Aq Mt zachary.leaf@arm.com 145