.\"	$OpenBSD: evcount.9,v 1.3 2007/05/31 19:20:00 jmc Exp $
.\" Written by Jared Yanovich
.\" This file belongs to the public domain, 11/02/2004.
.Dd $Mdocdate: May 31 2007 $
.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 an 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
.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 */
	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 .