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