diff options
Diffstat (limited to 'static/freebsd/man4/ktr.4 3.html')
| -rw-r--r-- | static/freebsd/man4/ktr.4 3.html | 161 |
1 files changed, 161 insertions, 0 deletions
diff --git a/static/freebsd/man4/ktr.4 3.html b/static/freebsd/man4/ktr.4 3.html new file mode 100644 index 00000000..9271fb74 --- /dev/null +++ b/static/freebsd/man4/ktr.4 3.html @@ -0,0 +1,161 @@ +<table class="head"> + <tr> + <td class="head-ltitle">KTR(4)</td> + <td class="head-vol">Device Drivers Manual</td> + <td class="head-rtitle">KTR(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">ktr</code> — <span class="Nd">kernel + tracing facility</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 KTR</code> + <br/> + <code class="Cd">options ALQ</code> + <br/> + <code class="Cd">options KTR_ALQ</code> + <br/> + <code class="Cd">options KTR_COMPILE=(KTR_LOCK|KTR_INTR|KTR_PROC)</code> + <br/> + <code class="Cd">options KTR_CPUMASK=0x3</code> + <br/> + <code class="Cd">options KTR_ENTRIES=8192</code> + <br/> + <code class="Cd">options KTR_MASK=(KTR_INTR|KTR_PROC)</code> + <br/> + <code class="Cd">options KTR_VERBOSE</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">ktr</code> facility allows kernel events to + be logged while the kernel executes so that they can be examined later when + debugging. The only mandatory option to enable <code class="Nm">ktr</code> + is “<code class="Li">options KTR</code>”.</p> +<p class="Pp">The <code class="Dv">KTR_ENTRIES</code> option sets the size of + the buffer of events. The size of the buffer in the currently running kernel + can be found via the sysctl <var class="Va">debug.ktr.entries</var>. By + default the buffer contains 1024 entries.</p> +<section class="Ss"> +<h2 class="Ss" id="Event_Masking"><a class="permalink" href="#Event_Masking">Event + Masking</a></h2> +<p class="Pp">Event levels can be enabled or disabled to trim excessive and + overly verbose logging. First, a mask of events is specified at compile time + via the <code class="Dv">KTR_COMPILE</code> option to limit which events are + actually compiled into the kernel. The default value for this option is for + all events to be enabled.</p> +<p class="Pp">Secondly, the actual events logged while the kernel runs can be + further masked via the run time event mask. The + <code class="Dv">KTR_MASK</code> option sets the default value of the run + time event mask. The runtime event mask can also be set by the + <a class="Xr">loader(8)</a> via the <var class="Va">debug.ktr.mask</var> + environment variable. It can also be examined and set after booting via the + <var class="Va">debug.ktr.mask</var> sysctl. By default the run time mask is + set to block any tracing. The definitions of the event mask bits can be + found in + <code class="In"><<a class="In">sys/ktr_class.h</a>></code>.</p> +<p class="Pp">Furthermore, there is a CPU event mask whose default value can be + changed via the <code class="Dv">KTR_CPUMASK</code> option. When two or more + parameters to <code class="Dv">KTR_CPUMASK</code>, are used, it is important + they are not separated by whitespace. A CPU must have the bit corresponding + to its logical id set in this bitmask for events that occur on it to be + logged. This mask can be set by the <a class="Xr">loader(8)</a> via the + <var class="Va">debug.ktr.cpumask</var> environment variable. It can also be + examined and set after booting via the + <var class="Va">debug.ktr.cpumask</var> sysctl. By default, only CPUs + specified in <code class="Dv">KTR_CPUMASK</code> will log events. See + <span class="Pa">sys/conf/NOTES</span> for more information.</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="Verbose_Mode"><a class="permalink" href="#Verbose_Mode">Verbose + Mode</a></h2> +<p class="Pp">By default, events are only logged to the internal buffer for + examination later, but if the verbose flag is set then they are dumped to + the kernel console as well. This flag can also be set from the loader via + the <var class="Va">debug.ktr.verbose</var> environment variable, or it can + be examined and set after booting via the + <var class="Va">debug.ktr.verbose</var> sysctl. If the flag is set to zero, + which is the default, then verbose output is disabled. If the flag is set to + one, then the contents of the log message and the CPU number are printed to + the kernel console. If the flag is greater than one, then the filename and + line number of the event are output to the console in addition to the log + message and the CPU number. The <code class="Dv">KTR_VERBOSE</code> option + sets the flag to one.</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="Examining_the_Events"><a class="permalink" href="#Examining_the_Events">Examining + the Events</a></h2> +<p class="Pp">The KTR buffer can be examined from within + <a class="Xr">ddb(4)</a> via the <code class="Ic">show ktr</code> + [<code class="Cm">/vV</code>] command. This command displays the contents of + the trace buffer one page at a time. At the + “<code class="Li">--more--</code>” prompt, the Enter key + displays one more entry and prompts again. The spacebar displays another + page of entries. Any other key quits. By default the timestamp, filename, + and line number are not displayed with each log entry. If the + <code class="Cm">/v</code> modifier is specified, then they are displayed in + addition to the normal output. If the <code class="Cm">/V</code> modifier is + specified, then just the timestamp is displayed in addition to the normal + output. Note that the events are displayed in reverse chronological order. + That is, the most recent events are displayed first.</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="Logging_ktr_to_Disk"><a class="permalink" href="#Logging_ktr_to_Disk">Logging + ktr to Disk</a></h2> +<p class="Pp">The <code class="Dv">KTR_ALQ</code> option can be used to log + <code class="Nm">ktr</code> entries to disk for post analysis using the + <a class="Xr">ktrdump(8)</a> utility. This option depends on the + <code class="Dv">ALQ</code> option. Due to the potentially high volume of + trace messages the trace mask should be selected carefully. This feature is + configured through a group of sysctls.</p> +<dl class="Bl-tag"> + <dt id="debug.ktr.alq_file"><var class="Va">debug.ktr.alq_file</var></dt> + <dd>displays or sets the file that <code class="Nm">ktr</code> will log to. By + default its value is <span class="Pa">/tmp/ktr.out</span>. If the file + name is changed while <code class="Nm">ktr</code> is enabled it will not + take effect until the next invocation.</dd> + <dt id="debug.ktr.alq_enable"><var class="Va">debug.ktr.alq_enable</var></dt> + <dd>enables logging of <code class="Nm">ktr</code> entries to disk if it is + set to one. Setting this to 0 will terminate logging to disk and revert to + logging to the normal ktr ring buffer. Data is not sent to the ring buffer + while logging to disk.</dd> + <dt id="debug.ktr.alq_max"><var class="Va">debug.ktr.alq_max</var></dt> + <dd>is the maximum number of entries that will be recorded to disk, or 0 for + infinite. This is helpful for limiting the number of particularly high + frequency entries that are recorded.</dd> + <dt id="debug.ktr.alq_depth"><var class="Va">debug.ktr.alq_depth</var></dt> + <dd>determines the number of entries in the write buffer. This is the buffer + that holds entries before they are written to disk and defaults to the + value of the <code class="Dv">KTR_ENTRIES</code> option.</dd> + <dt id="debug.ktr.alq_failed"><var class="Va">debug.ktr.alq_failed</var></dt> + <dd>records the number of times we failed to write an entry due to overflowing + the write buffer. This may happen if the frequency of the logged + <code class="Nm">ktr</code> messages outpaces the depth of the queue.</dd> + <dt id="debug.ktr.alq_cnt"><var class="Va">debug.ktr.alq_cnt</var></dt> + <dd>records the number of entries that have currently been written to + disk.</dd> +</dl> +</section> +</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">ktrdump(8)</a>, <a class="Xr">alq(9)</a>, + <a class="Xr">ktr(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The KTR kernel tracing facility first appeared in + <span class="Ux">BSD/OS 3.0</span> and was imported into + <span class="Ux">FreeBSD 5.0</span>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">March 26, 2021</td> + <td class="foot-os">FreeBSD 15.0</td> + </tr> +</table> |