Page MenuHomeFreeBSD
Files F142548328

D51192.id158101.diff
No OneTemporary
Actions

D51192.id158101.diff
View Options

Index: share/man/man4/hwt.4
===================================================================
--- /dev/null
+++ share/man/man4/hwt.4
@@ -0,0 +1,153 @@
+.\" Copyright (c) 2025 Ruslan Bukin <br@bsdpad.com>
+.\"
+.\" 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
+When loaded into kernel, the
+.Nm
+framework provides
+.Cd /dev/hwt
+character device for tracing contexts (CTX) management.
+The only request it accepts is HWT_IOC_ALLOC.
+The HWT_IOC_ALLOC request allocates kernel tracing context (CTX) based on
+requested mode of operation, set of CPUs and/or pid.
+.Pp
+The HWT framework supports two methods 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
+.Pp
+Upon successfull CTX allocation request, the
+.Nm
+framework returns a CTX identification number (ident) that is needed for CTX
+management.
+.Pp
+Each CTX is managed using its own dedicated character device found at
+.Cd /dev/hwt_${ident}_${d},
+where d is either cpu_id (in HWT CPU mode) or process pid (in HWT Thread mode),
+ident is a unique identification number of tracing context.
+
+.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. The information of this events 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
+CTX management character devices 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 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

File Metadata

Mime Type
text/plain
Expires
Wed, Jan 21, 9:06 PM (1 h, 31 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
27820529
Default Alt Text
D51192.id158101.diff (5 KB)

Event Timeline