Page MenuHomeFreeBSD
Files F142587323

D51192.id158104.diff
No OneTemporary
Actions

D51192.id158104.diff
View Options

Index: share/man/man4/hwt.4
===================================================================
--- /dev/null
+++ share/man/man4/hwt.4
@@ -0,0 +1,159 @@
+.\" 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 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
+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
+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

File Metadata

Mime Type
text/plain
Expires
Thu, Jan 22, 7:24 AM (16 h, 28 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
27834392
Default Alt Text
D51192.id158104.diff (5 KB)

Event Timeline