The branch main has been updated by br:
URL:
https://cgit.FreeBSD.org/src/commit/?id=bc2e3360107af28fed7157d18605bd038f07e16c
commit bc2e3360107af28fed7157d18605bd038f07e16c
Author: Ruslan Bukin <b...@freebsd.org>
AuthorDate: 2025-07-09 15:41:51 +0000
Commit: Ruslan Bukin <b...@freebsd.org>
CommitDate: 2025-07-09 15:57:07 +0000
hwt(4): Add initial man page.
Reviewed by: ziaee
Sponsored by: UKRI
Differential Revision: https://reviews.freebsd.org/D51192
---
share/man/man4/Makefile | 12 ++++
share/man/man4/hwt.4 | 142 ++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 154 insertions(+)
diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile
index 4f12e70f2ae4..7c8a8f3afc45 100644
--- a/share/man/man4/Makefile
+++ b/share/man/man4/Makefile
@@ -213,6 +213,7 @@ MAN= aac.4 \
${_hv_vmbus.4} \
${_hv_vss.4} \
hwpmc.4 \
+ ${_hwt.4} \
${_hwpstate_intel.4} \
i2ctinyusb.4 \
iavf.4 \
@@ -926,6 +927,17 @@ _vmm.4= vmm.4
.endif
.endif
+.if ${MACHINE_CPUARCH} == "amd64" || ${MACHINE_CPUARCH} == "aarch64"
+_hwt.4= hwt.4
+.if ${MACHINE_CPUARCH} == "amd64"
+MLINKS+=hwt.4 intel_pt.4
+.endif
+.if ${MACHINE_CPUARCH} == "aarch64"
+MLINKS+=hwt.4 coresight.4
+MLINKS+=hwt.4 spe.4
+.endif
+.endif
+
.if ${MACHINE_CPUARCH} == "amd64" || ${MACHINE_CPUARCH} == "i386" || \
${MACHINE_CPUARCH} == "aarch64"
_gve.4= gve.4
diff --git a/share/man/man4/hwt.4 b/share/man/man4/hwt.4
new file mode 100644
index 000000000000..7bc8ed4b396d
--- /dev/null
+++ b/share/man/man4/hwt.4
@@ -0,0 +1,142 @@
+.\"
+.\" Copyright (c) 2025 Ruslan Bukin <b...@bsdpad.com>
+.\"
+.\" SPDX-License-Identifier: BSD-2-Clause
+.\"
+.Dd July 7, 2025
+.Dt HWT 4
+.Os
+.Sh NAME
+.Nm hwt
+.Nd Hardware Trace Framework
+.Sh SYNOPSIS
+.Cd "options HWT_HOOKS"
+.Cd "device hwt"
+.Pp
+At least one of:
+.Cd "device intel_pt"
+.Pq amd64
+.Cd "device coresight"
+.Pq arm64
+.Cd "device spe"
+.Pq arm64
+.Pp
+In
+.Xr rc.conf 5 :
+.Cd kld_list="hwt"
+.Sh DESCRIPTION
+The
+.Nm
+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.
+.Sh HARDWARE
+The framework supports several tracing technologies found on
+.Cd arm64
+and
+.Cd amd64
+systems:
+.Pp
+.Bl -bullet -compact
+.It
+ARM Coresight
+.It
+ARM Statistical Profiling Extension (SPE)
+.It
+Intel Processor Trace (PT)
+.El
+.Pp
+The
+.Nm
+framework supports two modes of operation:
+.Bl -tag -width "Thread mode"
+.It Em CPU mode
+Capture CPU activity in kernel mode.
+.It Em Thread mode
+Capture activity of each of a process's threads in user mode.
+.El
+.Sh MANAGEMENT
+When loaded into kernel, the
+.Nm
+framework provides
+.Pa /dev/hwt
+character device.
+The only
+.Xr ioctl 2
+request it accepts is
+.Dv 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, the ioctl returns a CTX identification
+number (ident).
+.Pp
+Each CTX is then managed using its own dedicated character device found at
+.Pa "/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 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.
+.Pp
+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.
+.Sh KERNEL OPTIONS
+The following options in the kernel configuration file are mandatory and
+related to
+.Nm
+operation:
+.Pp
+.Bl -tag -width ".Dv HWT_HOOKS" -compact
+.It Dv HWT_HOOKS
+Enable kernel hooks.
+.El
+.Sh IOCTL INTERFACE
+Once a CTX is allocated, it's management character device accepts several IOC
+requests:
+.Bl -tag -width "HWT_IOC_RECORD_GET"
+.It Dv HWT_IOC_START
+Start tracing.
+In HWT CPU mode the tracing does actually start with this
+.Xr 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.
+.It Dv HWT_IOC_STOP
+Stop tracing of the particular CTX.
+.It Dv HWT_IOC_RECORD_GET
+Copy all or part of records collected during hook invocation and associated
+with this CTX to userspace.
+.It Dv HWT_IOC_BUFPTR_GET
+Get current pointer in buffer that is filled by tracing units in real-time.
+.It Dv HWT_IOC_SET_CONFIG
+Set achitecture-specific config (optional).
+.It Dv HWT_IOC_WAKEUP
+Wake up a thread that has been put to sleep by HWT framework hooks.
+.It Dv HWT_IOC_SVC_BUF
+For SPE-only, the 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 b...@freebsd.org
+.An Bojan Novković Aq Mt bnov...@freebsd.org
+.An Zachary Leaf Aq Mt zachary.l...@arm.com
