path: root/static/freebsd/man4/dtrace_lockstat.4 3.html

<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> &#x2014;
    <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>
    &lt;<a class="Mt" href="mailto:gnn@FreeBSD.org">gnn@FreeBSD.org</a>&gt; and
    <span class="An">Mark Johnston</span>
    &lt;<a class="Mt" href="mailto:markj@FreeBSD.org">markj@FreeBSD.org</a>&gt;.</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>