1.\" $NetBSD: softintr.9,v 1.9 2002/02/13 08:18:51 ross 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 \*[Lt]machine/intr.h\*[Gt] 46.Ft void * 47.Fn softintr_establish "int level" "void (*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/types.h 65must define the 66.Dv __HAVE_GENERIC_SOFT_INTERRUPTS 67symbol (without a value), 68furthermore, the machine-dependent 69.Aq Pa machine/intr.h 70include file must provide prototypes for the 71.Nm 72functions and must provide definitions of 73several constants which define software interrupt priority levels 74(IPLs): 75.Bl -tag -width "IPL_SOFTSERIAL" 76.It Dv IPL_SOFTCLOCK 77The software IPL for software clock interrupts 78.Pq i.e., Fn softclock . 79.It Dv IPL_SOFTNET 80The software IPL for network callbacks. 81.It Dv IPL_SOFTSERIAL 82The software IPL for serial driver callbacks. 83.El 84.Pp 85Other constants of the form 86.Dv IPL_SOFT* 87are reserved for future use by this framework. 88.Pp 89The following is a brief description of each function in the framework: 90.Bl -tag -width "softintr_disestablish()" 91.It Fn softintr_establish 92Register a software interrupt at level 93.Fa level , 94which will call the function 95.Fa fun 96with one 97argument, 98.Fa arg . 99It may allocate a machine-specific data structure. 100If successful, 101.Fn softintr_establish 102returns a 103.Pf non- Dv NULL 104opaque cookie which can be used as an argument to 105.Fn softintr_schedule 106or 107.Fn softintr_disestablish . 108If for some reason it does not succeed, it returns 109.Dv NULL . 110.It Fn softintr_disestablish 111Deallocate a software interrupt previously allocated 112by a call to 113.Fn softintr_establish . 114.\" XXX What happens to pending scheduled calls? 115.It Fn softintr_schedule 116Schedule a software interrupt previously allocated 117by a call to 118.Fn softintr_establish 119to be executed as soon as that software interrupt is unblocked. 120This function may assume that the interrupt is currently blocked, 121so it need not check to see if the interrupt needs to be executed 122immediately. 123.Fn softintr_schedule 124can safely be called multiple times before the 125callback routine is invoked. 126.El 127.Sh SEE ALSO 128.Xr spl 9 129.Sh HISTORY 130The 131.Nx 132machine-independent software interrupt framework was designed in 1997 133and was implemented by one port in 134.Nx 1.3 . 135However, it did not gain wider implementation until 136.Nx 1.5 . 137.Sh AUTHORS 138The 139.Nx 140machine-independent software interrupt framework was designed by 141Charles Hannum \*[Lt]mycroft@NetBSD.ORG\*[Gt]. 142