1.\" $OpenBSD: evcount.9,v 1.5 2014/09/08 01:27:55 schwarze Exp $ 2.\" Written by Jared Yanovich 3.\" This file belongs to the public domain, 11/02/2004. 4.Dd $Mdocdate: September 8 2014 $ 5.Dt EVCOUNT 9 6.Os 7.Sh NAME 8.Nm evcount , 9.Nm evcount_attach , 10.Nm evcount_detach 11.Nd generic interrupt and event counter kernel API 12.Sh SYNOPSIS 13.In sys/evcount.h 14.Ft void 15.Fn evcount_attach "struct evcount *ec" "const char *name" "void *data" 16.Ft void 17.Fn evcount_detach "struct evcount *ec" 18.Sh DESCRIPTION 19The 20.Nm 21API provides an interface for generic event and interrupt counting, 22whose statistics are made available to machine-independent 23.Xr sysctl 3 24nodes. 25.Ss Overview 26With 27.Nm , 28an architecture can collect interrupt counting for any device. 29All registered counters will be made available under the 30.Va kern.evcount 31.Xr sysctl 3 32node as a flat list. 33The following is a sample list of counters provided by some 34common architectures: 35.Pp 36.Bl -tag -width 8n -offset indent -compact 37.It clock 38Interrupt counter for the system clock 39.It stat 40Second-level interrupt decrementer counter 41.It rtc 42Real-time clock counter 43.It prof 44System profiler counter 45.It pciide0 46PCI IDE controller counter (see 47.Xr pciide 4 ) 48.It uhci0 49USB 1.0 controller counter (see 50.Xr usb 4 ) 51.El 52.Pp 53See 54.Xr intro 4 55for a list of devices for any of which 56.Nm 57may track interrupt counting. 58.Pp 59The 60.Xr systat 1 61and 62.Xr vmstat 8 63utilities can be used to view interrupts collected by 64.Nm . 65.Ss The API 66The 67.Vt evcount 68structure has the following definition: 69.Bd -literal -offset indent 70struct evcount { 71 u_int64_t ec_count; /* main counter */ 72 int ec_id; /* counter ID */ 73 const char *ec_name; /* counter name */ 74 void *ec_data; /* user data */ 75 76 TAILQ_ENTRY(evcount) next; 77}; 78.Ed 79.Pp 80The 81.Fn evcount_attach ec name data 82function adds the given event counter to the system's counter list. 83.Fa name 84provides the counter name, which is modeled after a 85device, such as 86.Dq clock 87or 88.Dq pciide0 . 89.Fa data 90provides a chunk of data that will be made available through the 91.Xr sysctl 3 92call. 93.Pp 94The 95.Fn evcount_detach ec 96function removes the given event counter 97.Fa ec 98from the counter list. 99.Sh EXAMPLES 100The following is an outline of code that provides routines to register 101and de-register interrupt handlers for devices, plugging the counting of 102interrupts generated by them during system operation into the 103.Nm 104framework. 105.Bd -literal 106#include <sys/evcount.h> 107#include <machine/intr.h> 108 109/* 110 * machine/intr.h provides a structure, intrhand, which is 111 * machine-dependent but is usually similar to this: 112 * 113 * struct intrhand { 114 * int (*ih_fun)(void *); 115 * void *ih_arg; 116 * int ih_level; 117 * struct intrhand *ih_next; 118 * int ih_irq; 119 * struct evcount ih_count; 120 * } 121 */ 122 123/* 124 * Register an interrupt handler. 125 */ 126void * 127intr_establish(void *lcv, int irq, int type, int level, 128 int (*ih_fun)(void *), void *ih_arg, char *name) 129{ 130 struct intrhand *ih, **p; 131 132 /* 133 * Allocate memory for the handler, sanity-check incoming 134 * values (IRQ#, etc.), and link the handler into 135 * machine-dependent data structures. 136 */ 137 138 /* 139 * Fill out the handler. 140 */ 141 ih->ih_fun = ih_fun; 142 ih->ih_arg = ih_arg; 143 ih->ih_next = NULL; 144 ih->ih_level = level; 145 ih->ih_irq = irq; 146 147 /* 148 * Attach it. 149 */ 150 evcount_attach(&ih->ih_count, name, &ih->ih_irq); 151 152 return (ih); 153} 154 155/* 156 * Deregister an interrupt handler. 157 */ 158void 159intr_disestablish(void *lcp, void *arg) 160{ 161 struct intrhand *ih = arg; 162 163 /* 164 * Sanity-check incoming values (IRQ, etc.) and remove 165 * the interrupt handler from machine-dependent data 166 * structures. 167 */ 168 169 evcount_detach(&ih->ih_count); 170 171 /* 172 * Free up memory and install a null interrupt handler. 173 */ 174} 175.Ed 176.Pp 177An interrupt handler for a device will be registered during 178.Xr autoconf 9 179with a call to the above 180.Fn intr_establish . 181.Pp 182The main external interrupt handler, which handles all system 183interrupts, will select the appropriate handler for the device 184that created the interrupt when an interrupt is generated. 185In this case, the handler is the routine assigned to 186.Va ih_fun , 187and 188.Nm 189will be made aware of interrupt occurrence. 190.Sh SEE ALSO 191.Xr systat 1 , 192.Xr queue 3 , 193.Xr sysctl 3 , 194.Xr intro 4 , 195.Xr vmstat 8 , 196.Xr autoconf 9 197.Sh AUTHORS 198.An -nosplit 199The 200.Nm 201API was written by 202.An Artur Grabowski 203and 204.An Aaron Campbell 205for 206.Ox 3.6 . 207