diff options
Diffstat (limited to 'static/netbsd/man9/evcnt.9 3.html')
| -rw-r--r-- | static/netbsd/man9/evcnt.9 3.html | 257 |
1 files changed, 0 insertions, 257 deletions
diff --git a/static/netbsd/man9/evcnt.9 3.html b/static/netbsd/man9/evcnt.9 3.html deleted file mode 100644 index 5fbf24af..00000000 --- a/static/netbsd/man9/evcnt.9 3.html +++ /dev/null @@ -1,257 +0,0 @@ -<table class="head"> - <tr> - <td class="head-ltitle">EVCNT(9)</td> - <td class="head-vol">Kernel Developer's Manual</td> - <td class="head-rtitle">EVCNT(9)</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">evcnt</code>, - <code class="Nm">evcnt_attach_dynamic</code>, - <code class="Nm">evcnt_attach_static</code>, - <code class="Nm">evcnt_detach</code> — <span class="Nd">generic event - counter 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="In">#include - <<a class="In">sys/evcnt.h</a>></code></p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">evcnt_attach_dynamic</code>(<var class="Fa" style="white-space: nowrap;">struct - evcnt *ev</var>, <var class="Fa" style="white-space: nowrap;">int - type</var>, <var class="Fa" style="white-space: nowrap;">const struct evcnt - *parent</var>, <var class="Fa" style="white-space: nowrap;">const char - *group</var>, <var class="Fa" style="white-space: nowrap;">const char - *name</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">evcnt_attach_static</code>(<var class="Fa" style="white-space: nowrap;">struct - evcnt *ev</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">evcnt_detach</code>(<var class="Fa" style="white-space: nowrap;">struct - evcnt *ev</var>);</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> -<p class="Pp">The <span class="Ux">NetBSD</span> generic event counter framework - is designed to provide a flexible and hierarchical event counting facility, - which is useful for tracking system events (including device - interrupts).</p> -<p class="Pp" id="evcnt">The fundamental component of this framework is the - <a class="permalink" href="#evcnt"><i class="Em">evcnt</i></a> structure. - Its user-accessible fields are:</p> -<div class="Bd Pp Li"> -<pre>struct evcnt { - uint64_t ev_count; /* how many have occurred */ - TAILQ_ENTRY(evcnt) ev_list; /* entry on list of all counters */ - unsigned char ev_type; /* counter type; see below */ - unsigned char ev_grouplen; /* 'group' len, excluding NUL */ - unsigned char ev_namelen; /* 'name' len, excluding NUL */ - const struct evcnt *ev_parent; /* parent, for hierarchical ctrs */ - const char *ev_group; /* name of group */ - const char *ev_name; /* name of specific event */ -};</pre> -</div> -<p class="Pp">The system maintains a global linked list of all active event - counters. This list, called <code class="Nm">allevents</code>, may grow or - shrink over time as event counters are dynamically added to and removed from - the system.</p> -<p class="Pp">Each event counter is marked (in the <var class="Fa">ev_type</var> - field) with the type of event being counted. The following types are - currently defined:</p> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="EVCNT_TYPE_MISC"><a class="permalink" href="#EVCNT_TYPE_MISC"><code class="Ev">EVCNT_TYPE_MISC</code></a></dt> - <dd>Miscellaneous; doesn't fit into one of the other types.</dd> - <dt id="EVCNT_TYPE_INTR"><a class="permalink" href="#EVCNT_TYPE_INTR"><code class="Ev">EVCNT_TYPE_INTR</code></a></dt> - <dd>Interrupt counter, reported by <code class="Ic">vmstat -i</code>.</dd> - <dt id="EVCNT_TYPE_TRAP"><a class="permalink" href="#EVCNT_TYPE_TRAP"><code class="Ev">EVCNT_TYPE_TRAP</code></a></dt> - <dd>Processor trap style events.</dd> -</dl> -</div> -<p class="Pp">Each event counter also has a group name - (<var class="Fa">ev_group</var>) and an event name - (<var class="Fa">ev_name</var>) which are used to identify the counter. The - group name may be shared by a set of counters. For example, device interrupt - counters would use the name of the device whose interrupts are being counted - as the group name. The counter name is meant to distinguish the counter from - others in its group (and need not be unique across groups). Both names - should be understandable by users, since they are printed by commands like - <a class="Xr">vmstat(1)</a>. The constant - <code class="Dv">EVCNT_STRING_MAX</code> is defined to be the maximum group - or event name length in bytes (including the trailing - <code class="Dv">NUL</code>). In the current implementation it is 256.</p> -<p class="Pp">To support hierarchical tracking of events, each event counter can - name a “parent” event counter. For instance, interrupt - dispatch code could have an event counter per interrupt line, and devices - could each have counters for the number of interrupts that they were - responsible for causing. In that case, the counter for a device on a given - interrupt line would have the line's counter as its parent. The value - <code class="Dv">NULL</code> is used to indicate that a counter has no - parent. A counter's parent must be attached before the counter is attached, - and detached after the counter is detached.</p> -<p class="Pp" id="EVCNT_INITIALIZER">The - <a class="permalink" href="#EVCNT_INITIALIZER"><code class="Fn">EVCNT_INITIALIZER</code></a>() - macro can be used to provide a static initializer for an event counter - structure. It is invoked as - <code class="Fn">EVCNT_INITIALIZER</code>(<var class="Fa">type</var>, - <var class="Fa">parent</var>, <var class="Fa">group</var>, - <var class="Fa">name</var>), and its arguments will be placed into the - corresponding fields of the event counter structure it is initializing. The - <var class="Fa">group</var> and <var class="Fa">name</var> arguments must be - constant strings.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="FUNCTIONS"><a class="permalink" href="#FUNCTIONS">FUNCTIONS</a></h1> -<p class="Pp">The following is a brief description of each function in the - framework:</p> -<dl class="Bl-tag"> - <dt id="evcnt_attach_dynamic"><a class="permalink" href="#evcnt_attach_dynamic"><code class="Fn">evcnt_attach_dynamic</code></a>(<var class="Fa">ev</var>, - <var class="Fa">type</var>, <var class="Fa">parent</var>, - <var class="Fa">group</var>, <var class="Fa">name</var>)</dt> - <dd>Attach the event counter structure pointed to by <var class="Fa">ev</var> - to the system event list. The event counter is cleared and its fields - initialized using the arguments to the function call. The contents of the - remaining elements in the structure (e.g., the name lengths) are - calculated, and the counter is added to the system event list. - <p class="Pp">The strings specified as the group and counter names must - persist (with the same value) throughout the life of the event counter; - they are referenced by, not copied into, the counter.</p> - </dd> - <dt id="evcnt_attach_static"><a class="permalink" href="#evcnt_attach_static"><code class="Fn">evcnt_attach_static</code></a>(<var class="Fa">ev</var>)</dt> - <dd>Attach the statically-initialized event counter structure pointed to by - <var class="Fa">ev</var> to the system event list. The event counter is - assumed to be statically initialized using the - <code class="Fn">EVCNT_INITIALIZER</code>() macro. This function simply - calculates structure elements' values as appropriate (e.g., the string - lengths), and adds the counter to the system event list.</dd> - <dt id="evcnt_detach"><a class="permalink" href="#evcnt_detach"><code class="Fn">evcnt_detach</code></a>(<var class="Fa">ev</var>)</dt> - <dd>Detach the event counter structure pointed to by <var class="Fa">ev</var> - from the system event list.</dd> -</dl> -<p class="Pp">Note that no method is provided to increment the value of an event - counter. Code incrementing an event counter should do so by directly - accessing its <var class="Fa">ev_count</var> field in a manner that is known - to be safe. For instance, additions to a device's event counters in the - interrupt handler for that device will often be safe without additional - protection (because interrupt handler entries for a given device have to be - serialized). However, for other uses of event counters, additional locking - or use of machine-dependent atomic operation may be appropriate. (The - overhead of using a mechanism that is guaranteed to be safe to increment - every counter, regardless of actual need for such a mechanism where the - counter is being incremented, would be too great. On some systems, it might - involve a global lock and several function calls.)</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> -<p class="Pp">This section includes a description on basic use of the framework - and example usage of its functions.</p> -<p class="Pp">Device drivers can use the - <code class="Fn">evcnt_attach_dynamic</code>() and - <code class="Fn">evcnt_detach</code>() functions to manage device-specific - event counters. Statically configured system modules can use - <code class="Fn">evcnt_attach_static</code>() to configure global event - counters. Similarly, loadable modules can use - <code class="Fn">evcnt_attach_static</code>() to configure their global - event counters, <code class="Fn">evcnt_attach_dynamic</code>() to attach - device-specific event counters, and <code class="Fn">evcnt_detach</code>() - to detach all counters when being unloaded.</p> -<p class="Pp">Device drivers that wish to use the generic event counter - framework should place event counter structures in their - “softc” structures. For example, to keep track of the number - of interrupts for a given device (broken down further into “device - readable” and “device writable” interrupts) a device - driver might use:</p> -<div class="Bd Pp Li"> -<pre>struct foo_softc { - [ . . . ] - struct evcnt sc_ev_intr; /* interrupt count */ - struct evcnt sc_ev_intr_rd; /* 'readable' interrupt count */ - struct evcnt sc_ev_intr_wr; /* 'writable' interrupt count */ - [ . . . ] -};</pre> -</div> -<p class="Pp">In the device attach function, those counters would be registered - with the system using the <code class="Fn">evcnt_attach_dynamic</code>() - function, using code like:</p> -<div class="Bd Pp Li"> -<pre>void -fooattach(device_t parent, device_t self, void *aux) -{ - struct foo_softc *sc = device_private(self); - - [ . . . ] - - /* Initialize and attach event counters. */ - evcnt_attach_dynamic(&sc->sc_ev, EVCNT_TYPE_INTR, - NULL, device_xname(self), "intr"); - evcnt_attach_dynamic(&sc->sc_ev_rd, EVCNT_TYPE_INTR, - &sc->sc_ev, device_xname(self), "intr rd"); - evcnt_attach_dynamic(&sc->sc_ev_wr, EVCNT_TYPE_INTR, - &sc->sc_ev, device_xname(self), "intr wr"); - - [ . . . ] -}</pre> -</div> -<p class="Pp">If the device can be detached from the system, its detach function - should invoke <code class="Fn">evcnt_detach</code>() on each attached - counter (making sure to detach any “parent” counters only - after detaching all children).</p> -<p class="Pp">Code like the following might be used to initialize a static event - counter (in this example, one used to track CPU alignment traps):</p> -<div class="Bd Pp Li"> -<pre> struct evcnt aligntrap_ev = EVCNT_INITIALIZER(EVCNT_TYPE_MISC, - NULL, "cpu", "aligntrap")</pre> -</div> -<p class="Pp">To attach this event counter, code like the following could be - used:</p> -<div class="Bd Pp Li"> -<pre> evcnt_attach_static(&aligntrap_ev);</pre> -</div> -</section> -<section class="Sh"> -<h1 class="Sh" id="CODE_REFERENCES"><a class="permalink" href="#CODE_REFERENCES">CODE - REFERENCES</a></h1> -<p class="Pp">The event counter framework itself is implemented within the file - <span class="Pa">sys/kern/subr_evcnt.c</span>. Data structures and function - prototypes for the framework are located in - <span class="Pa">sys/sys/device.h</span>.</p> -<p class="Pp">Event counters are used throughout the system.</p> -<p class="Pp">The <a class="Xr">vmstat(1)</a> source file - <span class="Pa">usr.bin/vmstat/vmstat.c</span> shows an example of how to - access event counters from user programs.</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">vmstat(1)</a></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> -<p class="Pp">A set of interrupt counter interfaces with similar names to the - interfaces in the <span class="Ux">NetBSD</span> generic event counter - framework appeared as part of the new autoconfiguration system in - <span class="Ux">4.4BSD</span>. Those interfaces were never widely adopted - in <span class="Ux">NetBSD</span> because of limitations in their - applicability. (Their use was limited to non-hierarchical, dynamically - attached device interrupt counters.) The <span class="Ux">NetBSD</span> - generic event counter framework first appeared in <span class="Ux">NetBSD - 1.5</span>.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> -<p class="Pp">The <span class="Ux">NetBSD</span> generic event counter framework - was designed and implemented by <span class="An">Chris Demetriou</span> - ⟨cgd@NetBSD.org⟩.</p> -</section> -</div> -<table class="foot"> - <tr> - <td class="foot-date">January 14, 2011</td> - <td class="foot-os">NetBSD 10.1</td> - </tr> -</table> |