---
name: "hwt"
section: "4"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["freebsd"]
url: "https://new.carta.tech/hwt"
---

# hwt(4)

Hardware Trace Framework

## NAME

**hwt** – Hardware Trace Framework

## SYNOPSIS

**options HWT\_HOOKS** **device hwt**

At least one of: **device intel\_pt** (amd64) **device coresight** (arm64) **device spe** (arm64)

In [rc.conf(5)](/rc.conf/5.md): **kld\_list="hwt"**

## DESCRIPTION

The **hwt** 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.

## HARDWARE

The framework supports several tracing technologies found on **arm64** and **amd64** systems:

- ARM Coresight

- ARM Statistical Profiling Extension (SPE)

- Intel Processor Trace (PT)

The **hwt** framework supports two modes of operation:

- *CPU* *mode*

  Capture CPU activity in kernel mode.

- *Thread* *mode*

  Capture activity of each of a process's threads in user mode.

## MANAGEMENT

When loaded into kernel, the **hwt** framework provides */dev/hwt* character device. The only [ioctl(2)](/ioctl/2.md) 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.

Upon successful CTX allocation, the ioctl returns a CTX identification number (ident).

Each CTX is then managed using its own dedicated character device found at */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).

## 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.

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.

## KERNEL OPTIONS

The following options in the kernel configuration file are mandatory and related to **hwt** operation:

- HWT\_HOOKS

  Enable kernel hooks.

## IOCTL INTERFACE

Once a CTX is allocated, its management character device accepts several [ioctl(2)](/ioctl/2.md) requests:

- HWT\_IOC\_START

  Start tracing. In HWT CPU mode the tracing does actually start with this [ioctl(2)](/ioctl/2.md) 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.

- HWT\_IOC\_STOP

  Stop tracing of the particular CTX.

- HWT\_IOC\_RECORD\_GET

  Copy all or part of records collected during hook invocation and associated with this CTX to userspace.

- HWT\_IOC\_BUFPTR\_GET

  Get current pointer in buffer that is filled by tracing units in real-time.

- HWT\_IOC\_SET\_CONFIG

  Set architecture-specific config (optional).

- HWT\_IOC\_WAKEUP

  Wake up a thread that has been put to sleep by HWT framework hooks.

- HWT\_IOC\_SVC\_BUF

  For SPE-only, the kernel is waiting for userspace to notify that it has copied out a buffer to avoid data loss/overwriting buffers.

## SEE ALSO

[tracing(7)](/tracing/7.md), hwt(8)

## HISTORY

The **hwt** framework first appeared in FreeBSD 15.0.

## AUTHORS

Ruslan Bukin ⟨*br@FreeBSD.org*⟩ Bojan Novković ⟨*bnovkov@FreeBSD.org*⟩ Zachary Leaf ⟨*zachary.leaf@arm.com*⟩