share/man/man9/spl.9

   1 .\"
   2 .\" Copyright (c) 1996 Joerg Wunsch
   3 .\"
   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 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
  16 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  17 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  18 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
  19 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  20 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  21 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  22 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  23 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  24 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd July 21, 1996
  29 .Os
  30 .Dt SPL 9
  31 .Sh NAME
  32 .Nm splbio ,
  33 .Nm splclock ,
  34 .Nm splhigh ,
  35 .Nm splimp ,
  36 .Nm splnet ,
  37 .Nm splsoftclock ,
  38 .Nm splsofttty ,
  39 .Nm splstatclock ,
  40 .Nm spltty ,
  41 .Nm splvm ,
  42 .Nm spl0 ,
  43 .Nm splx
  44 .Nd manipulate interrupt priorities
  45 .Sh SYNOPSIS
  46 .In sys/types.h
  47 .In sys/systm.h
  48 .Ft intrmask_t
  49 .Fn splbio "void"
  50 .Ft intrmask_t
  51 .Fn splclock "void"
  52 .Ft intrmask_t
  53 .Fn splhigh "void"
  54 .Ft intrmask_t
  55 .Fn splimp "void"
  56 .Ft intrmask_t
  57 .Fn splnet "void"
  58 .Ft intrmask_t
  59 .Fn splsoftclock "void"
  60 .Ft intrmask_t
  61 .Fn splsofttty "void"
  62 .Ft intrmask_t
  63 .Fn splstatclock "void"
  64 .Ft intrmask_t
  65 .Fn spltty "void"
  66 .Ft void
  67 .Fn spl0 "void"
  68 .Ft void
  69 .Fn splx "intrmask_t ipl"
  70 .Sh DESCRIPTION
  71 .Bf -symbolic
  72 This API is deprecated.
  73 Use mutexes to protect data structures instead.
  74 See
  75 .Xr mutex 9
  76 for more information.
  77 .Ef
  78 .Pp
  79 The
  80 .Fn spl
  81 function family sets the interrupt priority
  82 .Dq level
  83 of the CPU.
  84 This prevents interrupt handlers of the blocked priority level from
  85 being run.
  86 This is used in the
  87 .Dq synchronous
  88 part of a driver (the part that runs on behalf of the user process) to
  89 examine or modify data areas that might be examined or modified by
  90 interrupt handlers.
  91 .Pp
  92 Each driver that uses interrupts is normally assigned to an interrupt
  93 priority group by a keyword in its config line.
  94 For example:
  95 .Bd -literal -offset indent
  96 device foo0 at isa? port 0x0815 irq 12 tty
  97 .Ed
  98 .Pp
  99 assigns interrupt 12 to the
 100 .Dq tty
 101 priority group.
 102 The system automatically arranges for interrupts in
 103 the
 104 .Em xxx
 105 group to be called at a priority >=
 106 .Ns spl Ns Em xxx
 107 \&().
 108 .Pp
 109 The function
 110 .Fn splx
 111 sets the interrupt priority to an absolute value.
 112 The intent is that
 113 the value returned by the other functions should be saved in a local
 114 variable, and later passed to
 115 .Fn splx
 116 in order to restore the previous priority.
 117 .Pp
 118 The function
 119 .Fn spl0
 120 lowers the priority to a value where all interrupt handlers are
 121 unblocked, but ASTs (asynchronous system traps) remain blocked until
 122 the system is about to return to user mode.
 123 .Pp
 124 The traditional assignment of the various device drivers to the
 125 interrupt priority groups can be roughly classified as:
 126 .Bl -tag -width Fn
 127 .It Fn splnet
 128 Software part of the network interface drivers.
 129 .It Fn splimp
 130 All network interface drivers.
 131 .It Fn splbio
 132 All
 133 .Em buffered IO
 134 (i.e., disk and the like) drivers.
 135 .It Fn spltty
 136 Basically, all non-network communications devices, but effectively
 137 used for all drivers that are neither network nor disks.
 138 .El
 139 .Sh RETURN VALUES
 140 All functions except
 141 .Fn splx
 142 and
 143 .Fn spl0
 144 return the previous priority value.
 145 .Sh EXAMPLES
 146 This is a typical example demonstrating the usage:
 147 .Bd -literal
 148 struct foo_softc {
 149         ...
 150         int flags;
 151 #define FOO_ASLEEP      1
 152 #define FOO_READY       2
 153
 154 } foo_softc[NFOO];
 155
 156 int
 157 foowrite(...)
 158 {
 159         struct foo_softc *sc;
 160         int s, error;
 161
 162         ...
 163         s = spltty();
 164         if (!(sc->flags & FOO_READY)) {
 165                 /* Not ready, must sleep on resource. */
 166                 sc->flags |= FOO_ASLEEP;
 167                 error = tsleep(sc, PZERO, "foordy", 0);
 168                 sc->flags &= ~FOO_ASLEEP;
 169         }
 170         sc->flags &= ~FOO_READY;
 171         splx(s);
 172
 173         ...
 174 }
 175
 176 void
 177 foointr(...)
 178 {
 179         struct foo_softc *sc;
 180
 181         ...
 182         sc->flags |= FOO_READY;
 183         if (sc->flags & FOO_ASLEEP)
 184                 /* Somebody was waiting for us, awake him. */
 185                 wakeup(sc);
 186         ...
 187 }
 188
 189 .Ed
 190 Note that the interrupt handler should
 191 .Em never
 192 reduce the priority level.
 193 It is automatically called as it had
 194 raised the interrupt priority to its own level, i.e., further interrupts
 195 of the same group are being blocked.
 196 .Sh HISTORY
 197 The interrupt priority levels appeared in a very early version of
 198 .Ux .
 199 They have been traditionally known by number instead of by
 200 names, and were inclusive up to higher priority levels (i.e., priority
 201 5 has been blocking everything up to level 5).
 202 This is no longer the case in
 203 .Fx .
 204 The traditional name
 205 .Ql level
 206 for them is still reflected in the letter
 207 .Ql l
 208 of the respective functions and variables, although they are not
 209 really levels anymore, but rather different (partially inclusive)
 210 sets of functions to be blocked during some periods of the life of
 211 the system.
 212 The historical number scheme can be considered as a
 213 simple linearly ordered set of interrupt priority groups.
 214 .Sh AUTHORS
 215 This manual page was written by
 216 .An J\(:org Wunsch .