1.\" $NetBSD: spl.9,v 1.7 2000/06/08 06:45:24 cgd Exp $ 2.\" 3.\" Copyright (c) 1997 Michael Long. 4.\" Copyright (c) 1997 Jonathan Stone. 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. The name of the author may not be used to endorse or promote products 16.\" derived from this software without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 19.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 20.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 21.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 22.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 23.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 24.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 25.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 26.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 27.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 28.\" 29.Dd March 11, 1997 30.Dt SPL 9 31.Os 32.Sh NAME 33.Nm spl , 34.Nm spl0 , 35.Nm splbio , 36.Nm splclock , 37.Nm splhigh , 38.Nm splimp , 39.Nm spllowersoftclock , 40.Nm splnet , 41.Nm splsched , 42.Nm splserial , 43.Nm splsoftclock , 44.Nm splsoftnet , 45.Nm splsoftserial , 46.Nm splstatclock , 47.Nm spltty , 48.Nm splx 49.Nd modify system interrupt priority level 50.Sh SYNOPSIS 51.Fd #include <machine/intr.h> 52.Ft int 53.Fn splhigh void 54.Ft int 55.Fn splsched void 56.Ft int 57.Fn splserial void 58.Ft int 59.Fn splclock void 60.Ft int 61.Fn splstatclock void 62.Ft int 63.Fn splimp void 64.Ft int 65.Fn spltty void 66.Ft int 67.Fn splsoftserial void 68.Ft int 69.Fn splnet void 70.Ft int 71.Fn splbio void 72.Ft int 73.Fn splsoftnet void 74.Ft int 75.Fn splsoftclock void 76.Ft void 77.Fn spllowersoftclock void 78.Ft void 79.Fn spl0 void 80.Ft void 81.Fn splx "int s" 82.Sh DESCRIPTION 83These functions raise and lower the system priority level. 84They are used by kernel code to block interrupts with priority less 85than or equal to the named level (e.g. 86.Fn spltty 87blocks interrupts of priority less than or equal to 88.Dv IPL_TTY Ns ). 89The code may then safely access variables or data structures which are 90read or modified by interrupt service routines that run at the named 91level. 92.Pp 93A 94.Nm 95function exists for each distinct priority level which can exist in 96the system. These functions and the corresponding priority levels are 97used for various defined purposes, and may be divided into two main 98types: hard and soft. Hard interrupts are generated by hardware 99devices. Soft interrupts are generated by callouts, and are called 100from the kernel's periodic timer interrupt service routine. 101.Pp 102In order of highest to lowest priority, the priority-raising functions 103are: 104.Bl -tag -width splsoftserialXX 105.It Fn splhigh 106blocks all hard and soft interrupts. It is used for code that cannot 107tolerate any interrupts, like hardware context switching code and 108the 109.Xr ddb 4 110in-kernel debugger. 111.It Fn splserial 112blocks hard interrupts from serial interfaces. Code running at this 113level may not access the tty subsystem. 114.It Fn splsched 115blocks interrupts that may access scheduler data structures. Code 116running at or above this level may not call 117.Fn sleep , 118.Fn tsleep , 119or 120.Fn wakeup , 121nor may it post signals. 122.It Fn splclock 123blocks the hardware clock interrupt. It is used by 124.Fn hardclock 125to update kernel and process times, and must be used by any other code 126that accesses time-related data. 127.It Fn splstatclock 128blocks the hardware statistics clock interrupt. It is used by 129.Fn statclock 130to update kernel profiling and other statistics, and must be used by 131any code that accesses that data. 132This level is identical to 133.Fn splclock 134if there is no separate statistics clock. 135.It Fn splimp 136blocks hard interrupts from all devices that are allowed to use the 137kernel 138.Xr malloc 9 . 139That includes all disk, network, and tty device interrupts. 140.It Fn spltty 141blocks hard interrupts from TTY devices. 142.It Fn splsoftserial 143blocks soft interrupts generated by serial devices. 144.It Fn splnet 145blocks hard interrupts from network interfaces. 146.It Fn splbio 147blocks hard interrupts from disks and other mass-storage devices. 148.It Fn splsoftnet 149blocks soft network interrupts. 150.It Fn splsoftclock 151blocks soft clock interrupts. 152.El 153.Pp 154Two functions lower the system priority level. They are: 155.Bl -tag -width spllowersoftclockXX 156.It Fn spllowersoftclock 157unblocks all interrupts but the soft clock interrupt. 158.It Fn spl0 159unblocks all interrupts. 160.El 161.Pp 162The 163.Fn splx 164function restores the system priority level to the one encoded in 165.Fa s , 166which must be a value previously returned by one of the other 167.Nm 168functions. 169.Pp 170Note that the functions which lower the system priority level 171.Po 172.Fn spllowersoftclock , 173.Fn spl0 , 174and 175.Fn splx 176.Pc 177do not return a value. They should only be used 178in places where the system priority level is being decreased 179permanently. It is inappropriate to attempt to use them where the 180system priority level is being decreased temporarily, and would 181need to be restored to a previous value before continuing. 182.Pp 183.Sh HISTORY 184.Pp 185Originally, 186.Fn splsoftclock 187lowered the system priority level. 188During the 189.Nx 1.5 190development cycle, 191.Fn spllowersoftclock 192was introduced and the semantics of 193.Fn splsoftclock 194were changed. 195.Pp 196