diff options
Diffstat (limited to 'static/freebsd/man4/dtrace_lockstat.4 3.html')
| -rw-r--r-- | static/freebsd/man4/dtrace_lockstat.4 3.html | 254 |
1 files changed, 254 insertions, 0 deletions
diff --git a/static/freebsd/man4/dtrace_lockstat.4 3.html b/static/freebsd/man4/dtrace_lockstat.4 3.html new file mode 100644 index 00000000..61bc1ce2 --- /dev/null +++ b/static/freebsd/man4/dtrace_lockstat.4 3.html @@ -0,0 +1,254 @@ +<table class="head"> + <tr> + <td class="head-ltitle">DTRACE_LOCKSTAT(4)</td> + <td class="head-vol">Device Drivers Manual</td> + <td class="head-rtitle">DTRACE_LOCKSTAT(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">dtrace_lockstat</code> — + <span class="Nd">a DTrace provider for tracing kernel locking + events</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<p class="Pp"><code class="Fn">lockstat:::adaptive-acquire</code>(<var class="Fa" style="white-space: nowrap;">struct + mtx *</var>);</p> +<p class="Pp"><code class="Fn">lockstat:::adaptive-release</code>(<var class="Fa" style="white-space: nowrap;">struct + mtx *</var>);</p> +<p class="Pp"><code class="Fn">lockstat:::adaptive-spin</code>(<var class="Fa" style="white-space: nowrap;">struct + mtx *</var>, + <var class="Fa" style="white-space: nowrap;">uint64_t</var>);</p> +<p class="Pp"><code class="Fn">lockstat:::adaptive-block</code>(<var class="Fa" style="white-space: nowrap;">struct + mtx *</var>, + <var class="Fa" style="white-space: nowrap;">uint64_t</var>);</p> +<p class="Pp"><code class="Fn">lockstat:::spin-acquire</code>(<var class="Fa" style="white-space: nowrap;">struct + mtx *</var>);</p> +<p class="Pp"><code class="Fn">lockstat:::spin-release</code>(<var class="Fa" style="white-space: nowrap;">struct + mtx *</var>);</p> +<p class="Pp"><code class="Fn">lockstat:::spin-spin</code>(<var class="Fa" style="white-space: nowrap;">struct + mtx *</var>, + <var class="Fa" style="white-space: nowrap;">uint64_t</var>);</p> +<p class="Pp"><code class="Fn">lockstat:::rw-acquire</code>(<var class="Fa" style="white-space: nowrap;">struct + rwlock *</var>, <var class="Fa" style="white-space: nowrap;">int</var>);</p> +<p class="Pp"><code class="Fn">lockstat:::rw-release</code>(<var class="Fa" style="white-space: nowrap;">struct + rwlock *</var>, <var class="Fa" style="white-space: nowrap;">int</var>);</p> +<p class="Pp"><code class="Fn">lockstat:::rw-block</code>(<var class="Fa" style="white-space: nowrap;">struct + rwlock *</var>, <var class="Fa" style="white-space: nowrap;">uint64_t</var>, + <var class="Fa" style="white-space: nowrap;">int</var>, + <var class="Fa" style="white-space: nowrap;">int</var>, + <var class="Fa" style="white-space: nowrap;">int</var>);</p> +<p class="Pp"><code class="Fn">lockstat:::rw-spin</code>(<var class="Fa" style="white-space: nowrap;">struct + rwlock *</var>, + <var class="Fa" style="white-space: nowrap;">uint64_t</var>);</p> +<p class="Pp"><code class="Fn">lockstat:::rw-upgrade</code>(<var class="Fa" style="white-space: nowrap;">struct + rwlock *</var>);</p> +<p class="Pp"><code class="Fn">lockstat:::rw-downgrade</code>(<var class="Fa" style="white-space: nowrap;">struct + rwlock *</var>);</p> +<p class="Pp"><code class="Fn">lockstat:::sx-acquire</code>(<var class="Fa" style="white-space: nowrap;">struct + sx *</var>, <var class="Fa" style="white-space: nowrap;">int</var>);</p> +<p class="Pp"><code class="Fn">lockstat:::sx-release</code>(<var class="Fa" style="white-space: nowrap;">struct + sx *</var>, <var class="Fa" style="white-space: nowrap;">int</var>);</p> +<p class="Pp"><code class="Fn">lockstat:::sx-block</code>(<var class="Fa" style="white-space: nowrap;">struct + sx *</var>, <var class="Fa" style="white-space: nowrap;">uint64_t</var>, + <var class="Fa" style="white-space: nowrap;">int</var>, + <var class="Fa" style="white-space: nowrap;">int</var>, + <var class="Fa" style="white-space: nowrap;">int</var>);</p> +<p class="Pp"><code class="Fn">lockstat:::sx-spin</code>(<var class="Fa" style="white-space: nowrap;">struct + sx *</var>, + <var class="Fa" style="white-space: nowrap;">uint64_t</var>);</p> +<p class="Pp"><code class="Fn">lockstat:::sx-upgrade</code>(<var class="Fa" style="white-space: nowrap;">struct + sx *</var>);</p> +<p class="Pp"><code class="Fn">lockstat:::sx-downgrade</code>(<var class="Fa" style="white-space: nowrap;">struct + sx *</var>);</p> +<p class="Pp"><code class="Fn">lockstat:::lockmgr-acquire</code>(<var class="Fa" style="white-space: nowrap;">struct + lock *</var>, <var class="Fa" style="white-space: nowrap;">int</var>);</p> +<p class="Pp"><code class="Fn">lockstat:::lockmgr-release</code>(<var class="Fa" style="white-space: nowrap;">struct + lock *</var>, <var class="Fa" style="white-space: nowrap;">int</var>);</p> +<p class="Pp"><code class="Fn">lockstat:::lockmgr-disown</code>(<var class="Fa" style="white-space: nowrap;">struct + lock *</var>, <var class="Fa" style="white-space: nowrap;">int</var>);</p> +<p class="Pp"><code class="Fn">lockstat:::lockmgr-block</code>(<var class="Fa" style="white-space: nowrap;">struct + lock *</var>, <var class="Fa" style="white-space: nowrap;">uint64_t</var>, + <var class="Fa" style="white-space: nowrap;">int</var>, + <var class="Fa" style="white-space: nowrap;">int</var>, + <var class="Fa" style="white-space: nowrap;">int</var>);</p> +<p class="Pp"><code class="Fn">lockstat:::lockmgr-upgrade</code>(<var class="Fa" style="white-space: nowrap;">struct + lock *</var>);</p> +<p class="Pp"><code class="Fn">lockstat:::lockmgr-downgrade</code>(<var class="Fa" style="white-space: nowrap;">struct + lock *</var>);</p> +<p class="Pp"><code class="Fn">lockstat:::thread-spin</code>(<var class="Fa" style="white-space: nowrap;">struct + mtx *</var>, <var class="Fa" style="white-space: nowrap;">uint64</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The DTrace <code class="Nm">lockstat</code> provider allows the + tracing of events related to locking on <span class="Ux">FreeBSD</span>.</p> +<p class="Pp" id="acquire">The <code class="Nm">dtrace_lockstat</code> provider + contains DTrace probes for inspecting kernel lock state transitions. Probes + exist for the <a class="Xr">lockmgr(9)</a>, <a class="Xr">mutex(9)</a>, + <a class="Xr">rwlock(9)</a>, and <a class="Xr">sx(9)</a> lock types. The + <a class="Xr">lockstat(1)</a> utility can be used to collect and display + data collected from the <code class="Nm">dtrace_lockstat</code> provider. + Each type of lock has + <a class="permalink" href="#acquire"><code class="Fn">acquire</code></a>() + and + <a class="permalink" href="#release"><code class="Fn" id="release">release</code></a>() + probes which expose the lock structure being operated upon, as well as + probes which fire when a thread contends with other threads for ownership of + a lock.</p> +<p class="Pp" id="lockstat:::adaptive-acquire">The + <a class="permalink" href="#lockstat:::adaptive-acquire"><code class="Fn">lockstat:::adaptive-acquire</code></a>() + and + <a class="permalink" href="#lockstat:::adaptive-release"><code class="Fn" id="lockstat:::adaptive-release">lockstat:::adaptive-release</code></a>() + probes fire when an <code class="Dv">MTX_DEF</code> + <a class="Xr">mutex(9)</a> is acquired and released, respectively. The only + argument is a pointer to the lock structure which describes the lock being + acquired or released.</p> +<p class="Pp" id="lockstat:::adaptive-spin">The + <a class="permalink" href="#lockstat:::adaptive-spin"><code class="Fn">lockstat:::adaptive-spin</code></a>() + probe fires when a thread spins while waiting for a + <code class="Dv">MTX_DEF</code> <a class="Xr">mutex(9)</a> to be released by + another thread. The first argument is a pointer to the lock structure that + describes the lock and the second argument is the amount of time, in + nanoseconds, that the mutex spent spinning. The + <a class="permalink" href="#lockstat:::adaptive-block"><code class="Fn" id="lockstat:::adaptive-block">lockstat:::adaptive-block</code></a>() + probe fires when a thread takes itself off the CPU while trying to acquire + an <code class="Dv">MTX_DEF</code> <a class="Xr">mutex(9)</a> that is owned + by another thread. The first argument is a pointer to the lock structure + that describes the lock and the second argument is the length of time, in + nanoseconds, that the waiting thread was blocked. The + <code class="Fn">lockstat:::adaptive-block</code>() and + <code class="Fn">lockstat:::adaptive-spin</code>() probes fire only after + the lock has been successfully acquired, and in particular, after the + <code class="Fn">lockstat:::adaptive-acquire</code>() probe fires.</p> +<p class="Pp" id="lockstat:::spin-acquire">The + <a class="permalink" href="#lockstat:::spin-acquire"><code class="Fn">lockstat:::spin-acquire</code></a>() + and + <a class="permalink" href="#lockstat:::spin-release"><code class="Fn" id="lockstat:::spin-release">lockstat:::spin-release</code></a>() + probes fire when a <code class="Dv">MTX_SPIN</code> + <a class="Xr">mutex(9)</a> is acquired or released, respectively. The only + argument is a pointer to the lock structure which describes the lock being + acquired or released.</p> +<p class="Pp" id="lockstat:::spin-spin">The + <a class="permalink" href="#lockstat:::spin-spin"><code class="Fn">lockstat:::spin-spin</code></a>() + probe fires when a thread spins while waiting for a + <code class="Dv">MTX_SPIN</code> <a class="Xr">mutex(9)</a> to be released + by another thread. The first argument is a pointer to the lock structure + that describes the lock and the second argument is the length of the time + spent spinning, in nanoseconds. The + <code class="Fn">lockstat:::spin-spin</code>() probe fires only after the + lock has been successfully acquired, and in particular, after the + <code class="Fn">lockstat:::spin-acquire</code>() probe fires.</p> +<p class="Pp" id="lockstat:::rw-acquire">The + <a class="permalink" href="#lockstat:::rw-acquire"><code class="Fn">lockstat:::rw-acquire</code></a>() + and + <a class="permalink" href="#lockstat:::rw-release"><code class="Fn" id="lockstat:::rw-release">lockstat:::rw-release</code></a>() + probes fire when a <a class="Xr">rwlock(9)</a> is acquired or released, + respectively. The first argument is a pointer to the structure which + describes the lock being acquired. The second argument is + <code class="Dv">0</code> if the lock is being acquired or released as a + writer, and <code class="Dv">1</code> if it is being acquired or released as + a reader. The + <a class="permalink" href="#lockstat:::sx-acquire"><code class="Fn" id="lockstat:::sx-acquire">lockstat:::sx-acquire</code></a>() + and + <a class="permalink" href="#lockstat:::sx-release"><code class="Fn" id="lockstat:::sx-release">lockstat:::sx-release</code></a>(), + and + <a class="permalink" href="#lockstat:::lockmgr-acquire"><code class="Fn" id="lockstat:::lockmgr-acquire">lockstat:::lockmgr-acquire</code></a>() + and + <a class="permalink" href="#lockstat:::lockmgr-release"><code class="Fn" id="lockstat:::lockmgr-release">lockstat:::lockmgr-release</code></a>() + probes fire upon the corresponding events for <a class="Xr">sx(9)</a> and + <a class="Xr">lockmgr(9)</a> locks, respectively. The + <a class="permalink" href="#lockstat:::lockmgr-disown"><code class="Fn" id="lockstat:::lockmgr-disown">lockstat:::lockmgr-disown</code></a>() + probe fires when a <a class="Xr">lockmgr(9)</a> exclusive lock is disowned. + In this state, the lock remains exclusively held, but may be released by a + different thread. The <code class="Fn">lockstat:::lockmgr-release</code>() + probe does not fire when releasing a disowned lock. The first argument is a + pointer to the structure which describes the lock being disowned. The second + argument is <code class="Dv">0</code>, for compatibility with + <code class="Fn">lockstat:::lockmgr-release</code>().</p> +<p class="Pp" id="lockstat:::rw-block">The + <a class="permalink" href="#lockstat:::rw-block"><code class="Fn">lockstat:::rw-block</code></a>(), + <a class="permalink" href="#lockstat:::sx-block"><code class="Fn" id="lockstat:::sx-block">lockstat:::sx-block</code></a>(), + and + <a class="permalink" href="#lockstat:::lockmgr-block"><code class="Fn" id="lockstat:::lockmgr-block">lockstat:::lockmgr-block</code></a>() + probes fire when a thread removes itself from the CPU while waiting to + acquire a lock of the corresponding type. The + <a class="permalink" href="#lockstat:::rw-spin"><code class="Fn" id="lockstat:::rw-spin">lockstat:::rw-spin</code></a>() + and + <a class="permalink" href="#lockstat:::sx-spin"><code class="Fn" id="lockstat:::sx-spin">lockstat:::sx-spin</code></a>() + probes fire when a thread spins while waiting to acquire a lock of the + corresponding type. All probes take the same set of arguments. The first + argument is a pointer to the lock structure that describes the lock. The + second argument is the length of time, in nanoseconds, that the waiting + thread was off the CPU or spinning for the lock. The third argument is + <code class="Dv">0</code> if the thread is attempting to acquire the lock as + a writer, and <code class="Dv">1</code> if the thread is attempting to + acquire the lock as a reader. The fourth argument is + <code class="Dv">0</code> if the thread is waiting for a reader to release + the lock, and <code class="Dv">1</code> if the thread is waiting for a + writer to release the lock. The fifth argument is the number of readers that + held the lock when the thread first attempted to acquire the lock. This + argument will be <code class="Dv">0</code> if the fourth argument is + <code class="Dv">1</code>.</p> +<p class="Pp" id="lockstat:::lockmgr-upgrade">The + <a class="permalink" href="#lockstat:::lockmgr-upgrade"><code class="Fn">lockstat:::lockmgr-upgrade</code></a>(), + <a class="permalink" href="#lockstat:::rw-upgrade"><code class="Fn" id="lockstat:::rw-upgrade">lockstat:::rw-upgrade</code></a>(), + and + <a class="permalink" href="#lockstat:::sx-upgrade"><code class="Fn" id="lockstat:::sx-upgrade">lockstat:::sx-upgrade</code></a>() + probes fire when a thread successfully upgrades a held + <a class="Xr">lockmgr(9)</a>, <a class="Xr">rwlock(9)</a>, or + <a class="Xr">sx(9)</a> shared/reader lock to an exclusive/writer lock. The + only argument is a pointer to the structure which describes the lock being + acquired. The + <a class="permalink" href="#lockstat:::lockmgr-downgrade"><code class="Fn" id="lockstat:::lockmgr-downgrade">lockstat:::lockmgr-downgrade</code></a>(), + <a class="permalink" href="#lockstat:::rw-downgrade"><code class="Fn" id="lockstat:::rw-downgrade">lockstat:::rw-downgrade</code></a>(), + and + <a class="permalink" href="#lockstat:::sx-downgrade"><code class="Fn" id="lockstat:::sx-downgrade">lockstat:::sx-downgrade</code></a>() + probes fire when a thread downgrades a held <a class="Xr">lockmgr(9)</a>, + <a class="Xr">rwlock(9)</a>, or <a class="Xr">sx(9)</a> exclusive/writer + lock to a shared/reader lock.</p> +<p class="Pp" id="lockstat:::thread-spin">The + <a class="permalink" href="#lockstat:::thread-spin"><code class="Fn">lockstat:::thread-spin</code></a>() + probe fires when a thread spins on a thread lock, which is a specialized + <code class="Dv">MTX_SPIN</code> <a class="Xr">mutex(9)</a>. The first + argument is a pointer to the structure that describes the lock and the + second argument is the length of time, in nanoseconds, that the thread was + spinning.</p> +</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">dtrace(1)</a>, <a class="Xr">lockstat(1)</a>, + <a class="Xr">locking(9)</a>, <a class="Xr">mutex(9)</a>, + <a class="Xr">rwlock(9)</a>, <a class="Xr">SDT(9)</a>, + <a class="Xr">sx(9)</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">dtrace_lockstat</code> provider first + appeared in Solaris. The <span class="Ux">FreeBSD</span> implementation of + the <code class="Nm">dtrace_lockstat</code> provider first appeared in + <span class="Ux">FreeBSD 9</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp">This manual page was written by <span class="An">George V. + Neville-Neil</span> + <<a class="Mt" href="mailto:gnn@FreeBSD.org">gnn@FreeBSD.org</a>> and + <span class="An">Mark Johnston</span> + <<a class="Mt" href="mailto:markj@FreeBSD.org">markj@FreeBSD.org</a>>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1> +<p class="Pp">Probes for <a class="Xr">rmlock(9)</a> locks have not yet been + added.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">September 3, 2025</td> + <td class="foot-os">FreeBSD 15.0</td> + </tr> +</table> |