docs: Added All FreeBSD Manuals

1 files changed, 172 insertions, 0 deletions

diff --git a/static/freebsd/man4/kcov.4 3.html b/static/freebsd/man4/kcov.4 3.html
new file mode 100644
index 00000000..8a4abc0d
--- /dev/null
+++ b/static/freebsd/man4/kcov.4 3.html
@@ -0,0 +1,172 @@
+<table class="head">
+  <tr>
+    <td class="head-ltitle">KCOV(4)</td>
+    <td class="head-vol">Device Drivers Manual</td>
+    <td class="head-rtitle">KCOV(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">kcov</code> &#x2014; <span class="Nd">interface
+    for collecting kernel code coverage information</span></p>
+</section>
+<section class="Sh">
+<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
+<p class="Pp">To compile KCOV into the kernel, place the following lines in your
+    kernel configuration file:</p>
+<div class="Bd Pp Bd-indent"><code class="Cd">options COVERAGE</code>
+<br/>
+<code class="Cd">options KCOV</code></div>
+<p class="Pp">The following header file defines the application interface
+    provided by KCOV:</p>
+<p class="Pp">
+  <br/>
+  <code class="In">#include &lt;<a class="In">sys/kcov.h</a>&gt;</code></p>
+</section>
+<section class="Sh">
+<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
+<p class="Pp"><code class="Nm">kcov</code> is a module that enables collection
+    of code coverage information from the kernel. It relies on code
+    instrumentation enabled by the <code class="Dv">COVERAGE</code> kernel
+    option. When <code class="Nm">kcov</code> is enabled by a user-mode thread,
+    it collects coverage information only for that thread, excluding hard
+    interrupt handlers. As a result, <code class="Nm">kcov</code> is not suited
+    to collect comprehensive coverage data for the entire kernel; its main
+    purpose is to provide input for coverage-guided system call fuzzers.</p>
+<p class="Pp">In typical usage, a user-mode thread first allocates a chunk of
+    memory to be shared with <code class="Nm">kcov</code>. The thread then
+    enables coverage tracing, with coverage data being written by the kernel to
+    the shared memory region. When tracing is disabled, the kernel relinquishes
+    its access to the shared memory region, and the written coverage data may be
+    consumed.</p>
+<p class="Pp">The shared memory buffer can be treated as a 64-bit unsigned
+    integer followed by an array of records. The integer records the number of
+    valid records and is updated by the kernel as coverage information is
+    recorded. The state of the tracing buffer can be reset by writing the value
+    0 to this field. The record layout depends on the tracing mode set using the
+    <code class="Dv">KIOENABLE</code> ioctl.</p>
+<p class="Pp">Two tracing modes are implemented,
+    <code class="Dv">KCOV_MODE_TRACE_PC</code> and
+    <code class="Dv">KCOV_MODE_TRACE_CMP</code>. PC-tracing records a program
+    counter value for each basic block executed while tracing is enabled. In
+    this mode, each record is a single 64-bit unsigned integer containing the
+    program counter value. Comparison tracing provides information about data
+    flow; information about dynamic variable comparisons is recorded. Such
+    records provide information about the results of <a class="Xr">c(7)</a>
+    &#x2018;<code class="Li">if</code>&#x2019; or
+    &#x2018;<code class="Li">switch</code>&#x2019; statements, for example. In
+    this mode each record consists of four 64-bit unsigned integers. The first
+    integer is a bitmask defining attributes of the variables involved in the
+    comparison. <code class="Dv">KCOV_CMP_CONST</code> is set if one of the
+    variables has a constant value at compile-time, and
+    <code class="Dv">KCOV_CMP_SIZE(n)</code> specifies the width of the
+    variables:</p>
+<p class="Pp"></p>
+<dl class="Bl-inset Bd-indent Bl-compact">
+  <dt id="KCOV_CMP_SIZE(0)"><a class="permalink" href="#KCOV_CMP_SIZE(0)"><code class="Dv">KCOV_CMP_SIZE(0)</code></a>:</dt>
+  <dd>a comparison of 8-bit integers</dd>
+  <dt id="KCOV_CMP_SIZE(1)"><a class="permalink" href="#KCOV_CMP_SIZE(1)"><code class="Dv">KCOV_CMP_SIZE(1)</code></a>:</dt>
+  <dd>a comparison of 16-bit integers</dd>
+  <dt id="KCOV_CMP_SIZE(2)"><a class="permalink" href="#KCOV_CMP_SIZE(2)"><code class="Dv">KCOV_CMP_SIZE(2)</code></a>:</dt>
+  <dd>a comparison of 32-bit integers</dd>
+  <dt id="KCOV_CMP_SIZE(3)"><a class="permalink" href="#KCOV_CMP_SIZE(3)"><code class="Dv">KCOV_CMP_SIZE(3)</code></a>:</dt>
+  <dd>a comparison of 64-bit integers</dd>
+</dl>
+<p class="Pp">The second and third fields record the values of the two
+    variables, and the fourth and final field stores the program counter value
+    of the comparison.</p>
+</section>
+<section class="Sh">
+<h1 class="Sh" id="IOCTL_INTERFACE"><a class="permalink" href="#IOCTL_INTERFACE">IOCTL
+  INTERFACE</a></h1>
+<p class="Pp">Applications interact with <code class="Nm">kcov</code> using the
+    <a class="Xr">ioctl(2)</a> system call. Each thread making use of
+    <code class="Nm">kcov</code> must use a separate file descriptor for
+    <var class="Fa">/dev/kcov</var>. The following ioctls are defined:</p>
+<dl class="Bl-tag">
+  <dt id="KIOSETBUFSIZE"><a class="permalink" href="#KIOSETBUFSIZE"><code class="Dv">KIOSETBUFSIZE</code></a>
+    <var class="Fa">size_t entries</var></dt>
+  <dd>Set the size of the tracing buffer in units of
+      <code class="Dv">KCOV_ENTRY_SIZE</code>. The buffer may then be mapped
+      into the calling thread's address space by calling
+      <a class="Xr">mmap(2)</a> on the <code class="Nm">kcov</code> device
+    file.</dd>
+  <dt id="KIOENABLE"><a class="permalink" href="#KIOENABLE"><code class="Dv">KIOENABLE</code></a>
+    <var class="Fa">int mode</var></dt>
+  <dd>Enable coverage tracing for the calling thread. Valid modes are
+      <code class="Dv">KCOV_MODE_TRACE_PC</code> and
+      <code class="Dv">KCOV_MODE_TRACE_CMP</code>.</dd>
+  <dt id="KIODISABLE"><a class="permalink" href="#KIODISABLE"><code class="Dv">KIODISABLE</code></a></dt>
+  <dd>Disable coverage tracing for the calling thread.</dd>
+</dl>
+</section>
+<section class="Sh">
+<h1 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h1>
+<p class="Pp"><code class="Nm">kcov</code> creates the
+    <span class="Pa">/dev/kcov</span> device file.</p>
+</section>
+<section class="Sh">
+<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1>
+<p class="Pp">The following code sample collects information about basic block
+    coverage for kernel code executed while printing
+    &#x2018;<code class="Li">Hello, world</code>&#x2019;.</p>
+<div class="Bd Pp Li">
+<pre>size_t sz;
+uint64_t *buf;
+int fd;
+
+fd = open(&quot;/dev/kcov&quot;, O_RDWR);
+if (fd == -1)
+	err(1, &quot;open(/dev/kcov)&quot;);
+sz = 1ul &lt;&lt; 20; /* 1MB */
+if (ioctl(fd, KIOSETBUFSIZE, sz / KCOV_ENTRY_SIZE) != 0)
+	err(1, &quot;ioctl(KIOSETBUFSIZE)&quot;);
+buf = mmap(NULL, sz, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);
+if (buf == MAP_FAILED)
+	err(1, &quot;mmap&quot;);
+
+/* Enable PC tracing. */
+if (ioctl(fd, KIOENABLE, KCOV_MODE_TRACE_PC) != 0)
+	err(1, &quot;ioctl(KIOENABLE)&quot;);
+
+/* Clear trace records from the preceding ioctl() call. */
+buf[0] = 0;
+
+printf(&quot;Hello, world!\n&quot;);
+
+/* Disable PC tracing. */
+if (ioctl(fd, KIODISABLE, 0) != 0)
+	err(1, &quot;ioctl(KIODISABLE)&quot;);
+
+for (uint64_t i = 1; i &lt; buf[0]; i++)
+	printf(&quot;%#jx\n&quot;, (uintmax_t)buf[i]);</pre>
+</div>
+The output of this program can be approximately mapped to line numbers in kernel
+  source code:
+<div class="Bd Pp Li">
+<pre># ./kcov-test | sed 1d | addr2line -e /usr/lib/debug/boot/kernel/kernel.debug</pre>
+</div>
+</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">ioctl(2)</a>, <a class="Xr">mmap(2)</a></p>
+</section>
+<section class="Sh">
+<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
+<p class="Pp"><code class="Nm">kcov</code> first appeared in
+    <span class="Ux">FreeBSD 13.0</span>.</p>
+</section>
+<section class="Sh">
+<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1>
+<p class="Pp">The <span class="Ux">FreeBSD</span> implementation of
+    <code class="Nm">kcov</code> does not yet support remote tracing.</p>
+</section>
+</div>
+<table class="foot">
+  <tr>
+    <td class="foot-date">August 18, 2020</td>
+    <td class="foot-os">FreeBSD 15.0</td>
+  </tr>
+</table>