diff options
Diffstat (limited to 'static/freebsd/man4/hwt.4 3.html')
| -rw-r--r-- | static/freebsd/man4/hwt.4 3.html | 156 |
1 files changed, 156 insertions, 0 deletions
diff --git a/static/freebsd/man4/hwt.4 3.html b/static/freebsd/man4/hwt.4 3.html new file mode 100644 index 00000000..0fceef39 --- /dev/null +++ b/static/freebsd/man4/hwt.4 3.html @@ -0,0 +1,156 @@ +<table class="head"> + <tr> + <td class="head-ltitle">HWT(4)</td> + <td class="head-vol">Device Drivers Manual</td> + <td class="head-rtitle">HWT(4)</td> + </tr> +</table> +<div class="manual-text"> +<section class="Sh"> +<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> +<p class="Pp"><code class="Nm">hwt</code> — <span class="Nd">Hardware + Trace Framework</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<p class="Pp"><code class="Cd">options HWT_HOOKS</code> + <br/> + <code class="Cd">device hwt</code></p> +<p class="Pp">At least one of: + <br/> + <code class="Cd">device intel_pt</code> (amd64) + <br/> + <code class="Cd">device coresight</code> (arm64) + <br/> + <code class="Cd">device spe</code> (arm64)</p> +<p class="Pp">In <a class="Xr">rc.conf(5)</a>: + <br/> + <code class="Cd">kld_list="hwt"</code></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <code class="Nm">hwt</code> 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.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HARDWARE"><a class="permalink" href="#HARDWARE">HARDWARE</a></h1> +<p class="Pp">The framework supports several tracing technologies found on + <code class="Cd">arm64</code> and <code class="Cd">amd64</code> systems:</p> +<p class="Pp"></p> +<ul class="Bl-bullet Bl-compact"> + <li>ARM Coresight</li> + <li>ARM Statistical Profiling Extension (SPE)</li> + <li>Intel Processor Trace (PT)</li> +</ul> +<p class="Pp">The <code class="Nm">hwt</code> framework supports two modes of + operation:</p> +<dl class="Bl-tag"> + <dt id="CPU"><a class="permalink" href="#CPU"><i class="Em">CPU + mode</i></a></dt> + <dd>Capture CPU activity in kernel mode.</dd> + <dt id="Thread"><a class="permalink" href="#Thread"><i class="Em">Thread + mode</i></a></dt> + <dd>Capture activity of each of a process's threads in user mode.</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="MANAGEMENT"><a class="permalink" href="#MANAGEMENT">MANAGEMENT</a></h1> +<p class="Pp">When loaded into kernel, the <code class="Nm">hwt</code> framework + provides <span class="Pa">/dev/hwt</span> character device. The only + <a class="Xr">ioctl(2)</a> request it accepts is + <code class="Dv">HWT_IOC_ALLOC</code>. This request allocates kernel tracing + context (CTX) based on requested mode of operation, set of CPUs and/or + pid.</p> +<p class="Pp">Upon successful CTX allocation, the ioctl returns a CTX + identification number (ident).</p> +<p class="Pp">Each CTX is then managed using its own dedicated character device + found at <span class="Pa">/dev/hwt_${ident}_${d}</span>, 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).</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HOOKS"><a class="permalink" href="#HOOKS">HOOKS</a></h1> +<p class="Pp">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.</p> +<p class="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.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="KERNEL_OPTIONS"><a class="permalink" href="#KERNEL_OPTIONS">KERNEL + OPTIONS</a></h1> +<p class="Pp">The following options in the kernel configuration file are + mandatory and related to <code class="Nm">hwt</code> operation:</p> +<p class="Pp"></p> +<dl class="Bl-tag Bl-compact"> + <dt id="HWT_HOOKS"><a class="permalink" href="#HWT_HOOKS"><code class="Dv">HWT_HOOKS</code></a></dt> + <dd>Enable kernel hooks.</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="IOCTL_INTERFACE"><a class="permalink" href="#IOCTL_INTERFACE">IOCTL + INTERFACE</a></h1> +<p class="Pp">Once a CTX is allocated, its management character device accepts + several <a class="Xr">ioctl(2)</a> requests:</p> +<dl class="Bl-tag"> + <dt id="HWT_IOC_START"><a class="permalink" href="#HWT_IOC_START"><code class="Dv">HWT_IOC_START</code></a></dt> + <dd>Start tracing. In HWT CPU mode the tracing does actually start with this + <a class="Xr">ioctl(2)</a> 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.</dd> + <dt id="HWT_IOC_STOP"><a class="permalink" href="#HWT_IOC_STOP"><code class="Dv">HWT_IOC_STOP</code></a></dt> + <dd>Stop tracing of the particular CTX.</dd> + <dt id="HWT_IOC_RECORD_GET"><a class="permalink" href="#HWT_IOC_RECORD_GET"><code class="Dv">HWT_IOC_RECORD_GET</code></a></dt> + <dd>Copy all or part of records collected during hook invocation and + associated with this CTX to userspace.</dd> + <dt id="HWT_IOC_BUFPTR_GET"><a class="permalink" href="#HWT_IOC_BUFPTR_GET"><code class="Dv">HWT_IOC_BUFPTR_GET</code></a></dt> + <dd>Get current pointer in buffer that is filled by tracing units in + real-time.</dd> + <dt id="HWT_IOC_SET_CONFIG"><a class="permalink" href="#HWT_IOC_SET_CONFIG"><code class="Dv">HWT_IOC_SET_CONFIG</code></a></dt> + <dd>Set architecture-specific config (optional).</dd> + <dt id="HWT_IOC_WAKEUP"><a class="permalink" href="#HWT_IOC_WAKEUP"><code class="Dv">HWT_IOC_WAKEUP</code></a></dt> + <dd>Wake up a thread that has been put to sleep by HWT framework hooks.</dd> + <dt id="HWT_IOC_SVC_BUF"><a class="permalink" href="#HWT_IOC_SVC_BUF"><code class="Dv">HWT_IOC_SVC_BUF</code></a></dt> + <dd>For SPE-only, the kernel is waiting for userspace to notify that it has + copied out a buffer to avoid data loss/overwriting buffers.</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<p class="Pp"><a class="Xr">tracing(7)</a>, <a class="Xr">hwt(8)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The <code class="Nm">hwt</code> framework first appeared in + <span class="Ux">FreeBSD 15.0</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp"><span class="An">Ruslan Bukin</span> + <<a class="Mt" href="mailto:br@FreeBSD.org">br@FreeBSD.org</a>> + <br/> + <span class="An">Bojan Novković</span> + <<a class="Mt" href="mailto:bnovkov@freebsd.org">bnovkov@freebsd.org</a>> + <br/> + <span class="An">Zachary Leaf</span> + <<a class="Mt" href="mailto:zachary.leaf@arm.com">zachary.leaf@arm.com</a>></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">July 12, 2025</td> + <td class="foot-os">FreeBSD 15.0</td> + </tr> +</table> |