1.\" $NetBSD: softintr.9,v 1.18 2008/10/06 13:51:38 pooka Exp $ 2.\" 3.\" Copyright (c) 2007, 2008 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Andrew Doran. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.\" Copyright (c) 2000 Christopher G. Demetriou. 31.\" All rights reserved. 32.\" 33.\" Redistribution and use in source and binary forms, with or without 34.\" modification, are permitted provided that the following conditions 35.\" are met: 36.\" 1. Redistributions of source code must retain the above copyright 37.\" notice, this list of conditions and the following disclaimer. 38.\" 2. Redistributions in binary form must reproduce the above copyright 39.\" notice, this list of conditions and the following disclaimer in the 40.\" documentation and/or other materials provided with the distribution. 41.\" 3. All advertising materials mentioning features or use of this software 42.\" must display the following acknowledgement: 43.\" This product includes software developed for the 44.\" NetBSD Project. See http://www.NetBSD.org/ for 45.\" information about NetBSD. 46.\" 4. The name of the author may not be used to endorse or promote products 47.\" derived from this software without specific prior written permission. 48.\" 49.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 50.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 51.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 52.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 53.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 54.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 55.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 56.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 57.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 58.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 59.\" 60.\" --(license Id: LICENSE.proto,v 1.1 2000/06/13 21:40:26 cgd Exp )-- 61.\" 62.Dd October 6, 2008 63.Dt SOFTINT 9 64.Os 65.Sh NAME 66.Nm softint , 67.Nm softint_establish , 68.Nm softint_disestablish , 69.Nm softint_schedule 70.Nd machine-independent software interrupt framework 71.Sh SYNOPSIS 72.In sys/intr.h 73.Ft void * 74.Fn softint_establish "u_int flags" "void (*func)(void *)" "void *arg" 75.Ft void 76.Fn softint_disestablish "void *cookie" 77.Ft void 78.Fn softint_schedule "void *cookie" 79.Sh DESCRIPTION 80The software interrupt framework is designed to provide 81a generic software interrupt mechanism which can be used any time a 82low-priority callback is needed. 83.Pp 84It allows dynamic registration of software interrupts for loadable 85drivers and protocol stacks, prioritization and fair queueing of software 86interrupts, and allows machine-dependent optimizations to reduce cost. 87.Pp 88Four priority levels are provided. 89In order of priority (lowest to highest) the levels are: clock, bio, 90net, serial. 91The names are symbolic and in isolation do not have any direct 92connection with a particular kind of device activity: they are 93only meant as a guide. 94.Pp 95The four priority levels map directly to scheduler priority 96levels, and where the architecture implements 'fast' software 97interrupts, they also map onto interrupt priorities. 98The interrupt priorities are intended to be hidden from machine 99independent code, which should in general use thread-safe mechanisms 100to synchronize with software interrupts (for example: mutexes). 101.Pp 102Software interrupts run with limited machine context. 103In particular, they do not possess any address space context. 104They should not try to operate on user space addresses, or to use 105virtual memory facilities other than those noted as interrupt 106safe. 107Unlike hardware interrupts, software interrupts do have thread 108context. 109They may block on synchronization objects, sleep, and resume 110execution at a later time. 111.Pp 112Since software interrupts are a limited resource and run with 113higher priority than most other LWPs in the system, all 114block-and-resume activity by a software interrupt must be kept 115short to allow further processing at that level to continue. 116By extension, code running with process context must take care to 117ensure that any lock that may be taken from a software interrupt 118can not be held for more than a short period of time. 119.Pp 120The kernel does not allow software interrupts to use facilities 121or perform actions that are likely to block for a significant 122amount of time. 123This means that it's not valid for a software interrupt to 124sleep on condition variables or to wait for resources to 125become available (for example, memory). 126.Pp 127The following is a brief description of each function in the framework: 128.Bl -tag -width abcxdcc 129.It Fn softint_establish flags func arg 130.Pp 131Register a software interrupt. 132The 133.Fa flags 134value must contain one of the following constants, specifing 135the priority level for the soft interrupt: 136.Pp 137.Dv SOFTINT_CLOCK , 138.Dv SOFTINT_BIO , 139.Dv SOFTINT_NET , 140.Dv SOFTINT_SERIAL 141.Pp 142If the constant 143.Dv SOFTINT_MPSAFE 144is not logically ORed into 145.Fa flags , 146the global 147.Dv kernel_lock 148will automatically be acquired before the soft interrupt handler 149is called. 150.Pp 151The constant 152.Fa func 153specifies the function to call when the soft interrupt is 154executed. 155The argument 156.Fa arg 157will be passed to this function. 158.Pp 159.Fn softint_establish 160may block in order to allocate memory. 161If successful, it returns a 162.Pf non- Dv NULL 163opaque value to be used as an argument to 164.Fn softint_schedule 165and/or 166.Fn softint_disestablish . 167If for some reason it does not succeed, it returns 168.Dv NULL . 169.It Fn softint_disestablish cookie 170.Pp 171Deallocate a software interrupt previously allocated 172by a call to 173.Fn softint_establish . 174.\" XXX What happens to pending scheduled calls? 175.It Fn softint_schedule cookie 176.Pp 177Schedule a software interrupt previously allocated 178by a call to 179.Fn softint_establish 180to be executed as soon as that software interrupt is unblocked. 181.Fn softint_schedule 182can safely be called multiple times before the 183callback routine is invoked. 184.Pp 185Soft interrupt scheduling is CPU-local. 186A request to dispatch a soft interrupt will only be serviced on 187the same CPU where the request was made. 188The LWPs (light weight processes) dedicated to soft interrupt 189processing are bound to their home CPUs, so if a soft interrupt 190handler sleeps and later resumes, it will always resume on the 191same CPU. 192.Pp 193On a system with multiple processors, multiple instances of 194the same soft interrupt handler can be in flight simultaneously 195(at most one per-CPU). 196.El 197.Sh SEE ALSO 198.Xr mutex 9 , 199.Xr rwlock 9 , 200.Xr spl 9 201.Sh HISTORY 202The 203.Nx 204machine-independent software interrupt framework was designed in 1997 205and was implemented by one port in 206.Nx 1.3 . 207However, it did not gain wider implementation until 208.Nx 1.5 . 209Between 210.Nx 4.0 211and 212.Nx 5.0 213the framework was re-implemented in a machine-independant way to 214provide software interrupts with thread context. 215