docs: OpenBSD Man Pages Added

1 files changed, 230 insertions, 0 deletions

diff --git a/static/openbsd/man9/evcount.9 b/static/openbsd/man9/evcount.9
new file mode 100644
index 00000000..e30fa494
--- /dev/null
+++ b/static/openbsd/man9/evcount.9
@@ -0,0 +1,230 @@
+.\"	$OpenBSD: evcount.9,v 1.8 2022/11/10 07:05:41 jmatthew Exp $
+.\" Written by Jared Yanovich
+.\" This file belongs to the public domain, 11/02/2004.
+.Dd $Mdocdate: November 10 2022 $
+.Dt EVCOUNT 9
+.Os
+.Sh NAME
+.Nm evcount ,
+.Nm evcount_attach ,
+.Nm evcount_detach ,
+.Nm evcount_percpu ,
+.Nm evcount_inc
+.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"
+.Ft void
+.Fn evcount_percpu "struct evcount *ec"
+.Ft void
+.Fn evcount_inc "struct evcount *ec"
+.Ft void
+.Fn evcount_detach "struct evcount *ec"
+.Sh DESCRIPTION
+The
+.Nm
+API provides an interface for generic event and interrupt counting,
+whose statistics are made available to machine-independent
+.Xr sysctl 2
+nodes.
+.Ss Overview
+With
+.Nm ,
+an architecture can collect interrupt counting for any device.
+All registered counters will be made available under the
+.Va kern.evcount
+.Xr sysctl 2
+node as a flat list.
+The following is a sample list of 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
+See
+.Xr intro 4
+for a list of devices for any of which
+.Nm
+may 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 */
+	void			*ec_data;	/* user data */
+	struct cpumem		*ec_cpumem;	/* per-cpu counter */
+
+	TAILQ_ENTRY(evcount)	next;
+};
+.Ed
+.Pp
+The
+.Fn evcount_attach ec name data
+function adds the given event counter to the system's counter list.
+.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 2
+call.
+.Pp
+The
+.Fn evcount_percpu ec
+function configures
+.Fa ec
+with one counter for each CPU in the system.
+It should be used when
+.Fa ec Ns 's
+corresponding interrupt can occur simultaneously on multiple CPUs.
+It must be called immediately after
+.Fn evcount_attach
+is called for a given counter.
+.Pp
+The
+.Fn evcount_inc ec
+function increments the given counter.
+.Pp
+The
+.Fn evcount_detach ec
+function removes the given event counter
+.Fa ec
+from the counter list.
+.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.
+	 */
+	evcount_attach(&ih->ih_count, name, &ih->ih_irq);
+
+	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 sysctl 2 ,
+.Xr queue 3 ,
+.Xr intro 4 ,
+.Xr vmstat 8 ,
+.Xr autoconf 9 ,
+.Xr counters_alloc 9
+.Sh AUTHORS
+.An -nosplit
+The
+.Nm
+API was written by
+.An Artur Grabowski
+and
+.An Aaron Campbell
+for
+.Ox 3.6 .