1.\" $NetBSD: softintr.9,v 1.3 2000/06/13 22:36:17 cgd Exp $ 2.\" 3.\" Copyright (c) 2000 Christopher G. Demetriou. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed for the 17.\" NetBSD Project. See http://www.netbsd.org/ for 18.\" information about NetBSD. 19.\" 4. The name of the author may not be used to endorse or promote products 20.\" derived from this software without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 23.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 24.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 25.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 26.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 27.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 28.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 29.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 30.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 31.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 32.\" 33.\" --(license Id: LICENSE.proto,v 1.1 2000/06/13 21:40:26 cgd Exp )-- 34.\" 35.Dd May 30, 2000 36.Dt SOFTINTR 9 37.Os 38.Sh NAME 39.Nm softintr , 40.Nm softintr_establish , 41.Nm softintr_disestablish , 42.Nm softintr_schedule 43.Nd machine-independent software interrupt framework 44.Sh SYNOPSIS 45.Fd #include <machine/intr.h> 46.Ft void * 47.Fn softintr_establish "int level" "int (*fun)(void *)" "void *arg" 48.Ft void 49.Fn softintr_disestablish "void *cookie" 50.Ft void 51.Fn softintr_schedule "void *cookie" 52.Sh DESCRIPTION 53The 54.Nx 55machine-independent software interrupt framework is designed to provide 56a generic software interrupt mechanism which can be used any time a 57low-priority callback is needed. It allows dynamic registration of 58software interrupts for loadable drivers and protocol stacks, 59prioritization and fair queueing of software interrupts, and 60allows machine-dependent optimizations to reduce cost and code 61complexity. 62.Pp 63In order to provide this framework, the machine-dependent 64.Aq Pa machine/intr.h 65include file must provide prototypes for the 66.Nm 67functions, must define the 68.Dv __GENERIC_SOFT_INTERRUPTS 69symbol (without a value), and must provide definitions of 70several constants which define software interrupt priority levels 71(IPLs): 72.Bl -tag -width "IPL_SOFTSERIAL" 73.It Dv IPL_SOFTCLOCK 74The software IPL for software clock interrupts 75.Pq i.e., Fn softclock . 76.It Dv IPL_SOFTNET 77The software IPL for network callbacks. 78.It Dv IPL_SOFTSERIAL 79The software IPL for serial driver callbacks. 80.El 81.Pp 82Other constants of the form 83.Dv IPL_SOFT* 84are reserved for future use by this framework. 85.Pp 86The following is a brief description of each function in the framework: 87.Bl -tag -width "softintr_disestablish()" 88.It Fn softintr_establish 89Register a software interrupt at level 90.Fa level , 91which will call the function 92.Fa fun 93with one 94argument, 95.Fa arg . 96It may allocate a machine-specific data structure. 97If successful, 98.Fn softintr_establish 99returns a 100.Pf non- Dv NULL 101opaque cookie which can be used as an argument to 102.Fn softintr_schedule 103or 104.Fn softintr_disestablish . 105If for some reason it does not succeed, it returns 106.Dv NULL . 107.It Fn softintr_disestablish 108Deallocate a software interrupt previously allocated 109by a call to 110.Fn softintr_establish . 111.\" XXX What happens to pending scheduled calls? 112.It Fn softintr_schedule 113Schedule a software interrupt previously allocated 114by a call to 115.Fn softintr_establish 116to be executed as soon as that software interrupt is unblocked. 117This function may assume that the interrupt is currently blocked, 118so it need not check to see if the interrupt needs to be executed 119immediately. 120.Fn softintr_schedule 121can safely be called multiple times before the 122callback routine is invoked. 123.El 124.Sh AUTHOR 125The 126.Nx 127machine-independent software interrupt framework was designed by 128Charles Hannum <mycroft@NetBSD.ORG>. 129.Sh SEE ALSO 130.Xr spl 9 131.Sh HISTORY 132The 133.Nx 134machine-independent software interrupt framework was designed in 1997 135and was implemented by one port in 136.Nx 1.3 . 137However, it did not gain wider implementation until 138.Nx 1.5 . 139