add initial manpage for the evcount API

1 files changed, 214 insertions, 0 deletions

diff --git a/share/man/man9/evcount.9 b/share/man/man9/evcount.9
new file mode 100644
index 00000000000..3775e755569
--- /dev/null
+++ b/share/man/man9/evcount.9
@@ -0,0 +1,214 @@
+.\"	$OpenBSD: evcount.9,v 1.1 2004/11/02 22:00:45 jaredy Exp $
+.\" Written by Jared Yanovich
+.\" This file belongs to the public domain, 11/02/2004.
+.Dd November 2, 2004
+.Dt EVCOUNT 9
+.Os
+.Sh NAME
+.Nm evcount ,
+.Nm evcount_attach ,
+.Nm evcount_detach
+.Nd generic interrupt and event counter kernel API
+.Sh SYNOPSIS
+.In sys/evcount.h
+.Ft void
+.Fn evcount_attach "struct evcount *ec" "const char *name" "void *data" \
+    "struct evcount *parent"
+.Ft void
+.Fn evcount_detach "struct evcount *ec"
+.Sh DESCRIPTION
+The
+.Nm
+API provides a interface for generic event and interrupt counting,
+whose statistics are made available to machine-independent
+.Xr sysctl 3
+nodes.
+.Ss Overview
+With
+.Nm ,
+an architecture can collect interrupt counting for any device and
+organize the counting hierarchy however it wants.
+All registered counters will be made available under the
+.Va kern.evcount
+.Xr sysctl 3
+node as a flat list.
+The following is a sample hierarchy for counters provided by some
+common architectures:
+.Pp
+.Bl -tag -width 8n -offset indent -compact
+.It clock
+Interrupt counter for the system clock
+.It stat
+Second-level interrupt decrementer counter
+.It rtc
+Real-time clock counter
+.It prof
+System profiler counter
+.It pciide0
+PCI IDE controller counter (see
+.Xr pciide 4 )
+.It uhci0
+USB 1.0 controller counter (see
+.Xr usb 4 )
+.El
+.Pp
+Event counters may be organized hierarchically, so a parent
+.Nm
+node that represents a bus may contain child nodes that represent
+devices attached to that bus.
+.Pp
+See
+.Xr intro 4
+for a list of devices for any of which may
+.Nm
+track interrupt counting.
+.Pp
+The
+.Xr systat 1
+and
+.Xr vmstat 8
+utilities can be used to view interrupts collected by
+.Nm .
+.Ss The API
+The
+.Vt evcount
+structure has the following definition:
+.Bd -literal -offset indent
+struct evcount {
+	u_int64_t		ec_count;	/* main counter */
+	int			ec_id;		/* counter ID */
+	const char		*ec_name;	/* counter name */
+	struct evcount		*ec_parent;	/* parent */
+	void			*ec_data;	/* user data */
+
+	TAILQ_ENTRY(evcount)	next;
+};
+.Ed
+.Pp
+The
+.Fn evcount_attach ec name data parent
+function inserts the given event counter
+.Fa ec
+into the given
+.Fa parent Ns 's
+list of counters.
+.Fa name
+provides the counter name, which is modeled after a
+device, such as
+.Dq clock
+or
+.Dq pciide0 .
+.Fa data
+provides a chunk of data that will be made available through the
+.Xr sysctl 3
+call.
+.Pp
+The
+.Fn evcount_detach ec
+function removes the given event counter
+.Fa ec
+from its parent.
+.Sh EXAMPLES
+The following is an outline of code that provides routines to register
+and de-register interrupt handlers for devices, plugging the counting of
+interrupts generated by them during system operation into the
+.Nm
+framework.
+.Bd -literal
+#include <sys/evcount.h>
+#include <machine/intr.h>
+
+/*
+ * machine/intr.h provides a structure, intrhand, which is
+ * machine-dependent but is usually similar to this:
+ *
+ *	struct intrhand {
+ *		int		(*ih_fun)(void *);
+ *		void		 *ih_arg;
+ *		int		  ih_level;
+ *		struct intrhand  *ih_next;
+ *		int		  ih_irq;
+ *		struct evcount    ih_count;
+ *	}
+ */
+
+/*
+ * Register an interrupt handler.
+ */
+void *
+intr_establish(void *lcv, int irq, int type, int level,
+	       int (*ih_fun)(void *), void *ih_arg, char *name)
+{
+	struct intrhand *ih, **p;
+
+	/*
+	 * Allocate memory for the handler, sanity-check incoming
+	 * values (IRQ#, etc.), and link the handler into
+	 * machine-dependent data structures.
+	 */
+
+	/*
+	 * Fill out the handler.
+	 */
+	ih->ih_fun = ih_fun;
+	ih->ih_arg = ih_arg;
+	ih->ih_next = NULL;
+	ih->ih_level = level;
+	ih->ih_irq = irq;
+
+	/*
+	 * Attach it under the root event counter, evcount_intr.
+	 */
+	evcount_attach(&ih->ih_count, name, (void *)&ih->ih_irq,
+	    &evcount_intr);
+
+	return (ih);
+}
+
+/*
+ * Deregister an interrupt handler.
+ */
+void
+intr_disestablish(void *lcp, void *arg)
+{
+	struct intrhand *ih = arg;
+
+	/*
+	 * Sanity-check incoming values (IRQ, etc.) and remove
+	 * the interrupt handler from machine-dependent data
+	 * structures.
+	 */
+
+	evcount_detach(&ih->ih_count);
+
+	/*
+	 * Free up memory and install a null interrupt handler.
+	 */
+}
+.Ed
+.Pp
+An interrupt handler for a device will be registered during
+.Xr autoconf 9
+with a call to the above
+.Fn intr_establish .
+.Pp
+The main external interrupt handler, which handles all system
+interrupts, will select the appropriate handler for the device
+that created the interrupt when an interrupt is generated.
+In this case, the handler is the routine assigned to
+.Va ih_fun ,
+and
+.Nm
+will be made aware of interrupt occurrence.
+.Sh SEE ALSO
+.Xr systat 1 ,
+.Xr queue 3 ,
+.Xr sysctl 3 ,
+.Xr intro 4 ,
+.Xr vmstat 8 ,
+.Xr autoconf 9
+.Sh AUTHORS
+The
+.Nm
+API was written by Artur Grabowski and Aaron Campbell for
+.Ox 3.6 .