1.\" $NetBSD: softintr.9,v 1.20 2009/08/03 23:29:19 rmind 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 August 3, 2009 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 97.Dq fast 98software interrupts, they also map onto interrupt priorities. 99The interrupt priorities are intended to be hidden from machine 100independent code, which should in general use thread-safe mechanisms 101to synchronize with software interrupts (for example: mutexes). 102.Pp 103Software interrupts run with limited machine context. 104In particular, they do not possess any address space context. 105They should not try to operate on user space addresses, or to use 106virtual memory facilities other than those noted as interrupt 107safe. 108Unlike hardware interrupts, software interrupts do have thread 109context. 110They may block on synchronization objects, sleep, and resume 111execution at a later time. 112.Pp 113Since software interrupts are a limited resource and run with 114higher priority than most other LWPs in the system, all 115block-and-resume activity by a software interrupt must be kept 116short to allow further processing at that level to continue. 117By extension, code running with process context must take care to 118ensure that any lock that may be taken from a software interrupt 119can not be held for more than a short period of time. 120.Pp 121The kernel does not allow software interrupts to use facilities 122or perform actions that are likely to block for a significant 123amount of time. 124This means that it's not valid for a software interrupt to 125sleep on condition variables or to wait for resources to 126become available (for example, memory). 127.Pp 128The following is a brief description of each function in the framework: 129.Bl -tag -width abcxdcc 130.It Fn softint_establish flags func arg 131.Pp 132Register a software interrupt. 133The 134.Fa flags 135value must contain one of the following constants, specifing 136the priority level for the soft interrupt: 137.Pp 138.Dv SOFTINT_CLOCK , 139.Dv SOFTINT_BIO , 140.Dv SOFTINT_NET , 141.Dv SOFTINT_SERIAL 142.Pp 143If the constant 144.Dv SOFTINT_MPSAFE 145is not logically ORed into 146.Fa flags , 147the global 148.Dv kernel_lock 149will automatically be acquired before the soft interrupt handler 150is called. 151.Pp 152The constant 153.Fa func 154specifies the function to call when the soft interrupt is 155executed. 156The argument 157.Fa arg 158will be passed to this function. 159.Pp 160.Fn softint_establish 161may block in order to allocate memory. 162If successful, it returns a 163.Pf non- Dv NULL 164opaque value to be used as an argument to 165.Fn softint_schedule 166and/or 167.Fn softint_disestablish . 168If for some reason it does not succeed, it returns 169.Dv NULL . 170.It Fn softint_disestablish cookie 171.Pp 172Deallocate a software interrupt previously allocated 173by a call to 174.Fn softint_establish . 175.\" XXX What happens to pending scheduled calls? 176.It Fn softint_schedule cookie 177.Pp 178Schedule a software interrupt previously allocated 179by a call to 180.Fn softint_establish 181to be executed as soon as that software interrupt is unblocked. 182.Fn softint_schedule 183can safely be called multiple times before the 184callback routine is invoked. 185.Pp 186Soft interrupt scheduling is CPU-local. 187A request to dispatch a soft interrupt will only be serviced on 188the same CPU where the request was made. 189The LWPs (light weight processes) dedicated to soft interrupt 190processing are bound to their home CPUs, so if a soft interrupt 191handler sleeps and later resumes, it will always resume on the 192same CPU. 193.Pp 194On a system with multiple processors, multiple instances of 195the same soft interrupt handler can be in flight simultaneously 196(at most one per-CPU). 197.El 198.Sh SEE ALSO 199.Xr callout 9 , 200.Xr condvar 9 , 201.Xr kthread 9 , 202.Xr mutex 9 , 203.Xr rwlock 9 , 204.Xr spl 9 , 205.Xr workqueue 9 206.Sh HISTORY 207The 208.Nx 209machine-independent software interrupt framework was designed in 1997 210and was implemented by one port in 211.Nx 1.3 . 212However, it did not gain wider implementation until 213.Nx 1.5 . 214Between 215.Nx 4.0 216and 217.Nx 5.0 218the framework was re-implemented in a machine-independant way to 219provide software interrupts with thread context. 220