Index: share/man/man4/hwt.4 =================================================================== --- /dev/null +++ share/man/man4/hwt.4 @@ -0,0 +1,157 @@ +.\" Copyright (c) 2025 Ruslan Bukin +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd July 7, 2025 +.Dt HWT 4 +.Os +.Sh NAME +.Nm hwt +.Nd "Hardware Trace Framework" +.Sh SYNOPSIS +The following option must be present in the kernel configuration file: +.Bd -ragged -offset indent +.Cd "options HWT_HOOKS" +.Ed +.Pp +To load the driver as a module at boot time: +.Bd -literal -offset indent +sysrc kld_list+=hwt +.Ed +.Pp +Alternatively, to compile the driver into the kernel: +.Bd -ragged -offset indent +.Cd "device hwt" +.Ed +.Pp +Additionally, at least one of these drivers has to be loaded into kernel via +module or compiled in via kernel configuration file: +.Pp +On arm64 systems: +.Bd -ragged -offset indent +.Cd "coresight" +.Cd "spe" +.Ed +.Pp +On amd64 systems: +.Bd -ragged -offset indent +.Cd "pt" +.Ed +.Sh DESCRIPTION +The +.Nm +framework provides a set of kernel interfaces to manage hardware tracing units +of a CPU (if provided by an architecture). The HW trace units collect +information about software execution and store 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 restore the entire program flow of a given +application without noticeable performance impact. +.Pp +The framework supports several tracing technologies found on +.Cd arm64 +and +.Cd amd64 +systems: +.Bl -bullet -compact +.It +ARM Coresight +.It +ARM Statistical Profiling Extension (SPE) +.It +Intel Processor Trace (PT) +.El +.Pp +The HWT framework supports two modes of operation: +.Bl -tag -width ".Em Thread mode" +.It Em CPU mode +In this mode HWT captures whatever CPU activity in kernel mode. +.It Em Thread mode +In this mode HWT captures activity of a process (each of its threads) in user +mode. +.El +.Sh FILES +When loaded into kernel, the +.Nm +framework provides +.Cd /dev/hwt +character device. +The only IOC 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. +.Pp +Upon successfull CTX allocation request, the ioctl returns a CTX identification +number (ident). +.Pp +Each CTX is then managed using its own dedicated character device found at +.Cd /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). +.Sh HOOKS +During operation (when tracing for a particular process is started), HWT +collects information about threads creation, as well as calls to exec or +mmap by the target process. +This information is stored as "records" to a particular CTX. +.Pp +Additionally, HWT could put a thread to sleep if requested by user on exec/mmap +event, so that user has time to copy the records to userspace and reconfigure +tracing as needed. +This is particulary useful if address range filtering feature is configured, +allowing user to trace particular function of a target executable or dynamic +library. +.Sh IOCTLS +Once a CTX is allocated, it's management character device accept several IOC +requests: +.Bl -tag -width 01234567890123aaabbb +.It HWT_IOC_START +Start tracing. +In HWT CPU mode the tracing does actually start with this IOCTL 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. +.It HWT_IOC_STOP +Stop tracing of the particular CTX. +.It HWT_IOC_RECORD_GET +Copy all or part of records collected during hook invocation and associated +with this CTX to userspace. +.It HWT_IOC_BUFPTR_GET +Get current pointer in buffer that is filled by tracing units in real-time. +.It HWT_IOC_SET_CONFIG +Set achitecture-specific config (optional). +.It HWT_IOC_WAKEUP +Wake up a thread that has been put to sleep by HWT framework hooks. +.It HWT_IOC_SVC_BUF +For SPE-only, kernel is waiting for userspace to notify that it's copied out +a buffer to avoid data loss/overwriting buffers. +.El +.Sh SEE ALSO +.Xr hwt 8 +.Sh HISTORY +The +.Nm +framework first appeared in +.Fx 15.0 . +.Sh AUTHORS +.An Ruslan Bukin Aq Mt br@FreeBSD.org +.An Bojan Novković Aq Mt bnovkov@freebsd.org +.An Zachary Leaf Aq Mt zachary.leaf@arm.com