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 .Fd #include <sys/types.h>
  47 .Fd #include <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.  This is used in the
  86 .Dq synchronous
  87 part of a driver (the part that runs on behalf of the user process) to
  88 examine or modify data areas that might be examined or modified by
  89 interrupt handlers.
  90 .Pp
  91 Each driver that uses interrupts is normally assigned to an interrupt
  92 priority group by a keyword in its config line.
  93 For example:
  94 .Bd -literal -offset indent
  95 device foo0 at isa? port 0x0815 irq 12 tty
  96 .Ed
  97 .Pp
  98 assigns interrupt 12 to the
  99 .Dq tty
 100 priority group.  The system automatically arranges for interrupts in
 101 the
 102 .Em xxx
 103 group to be called at a priority >=
 104 .Ns spl Ns Em xxx
 105 \&().
 106 .Pp
 107 The function
 108 .Fn splx
 109 sets the interrupt priority to an absolute value.  The intent is that
 110 the value returned by the other functions should be saved in a local
 111 variable, and later passed to
 112 .Fn splx
 113 in order to restore the previous priority.
 114 .Pp
 115 The function
 116 .Fn spl0
 117 lowers the priority to a value where all interrupt handlers are
 118 unblocked, but ASTs (asynchronous system traps) remain blocked until
 119 the system is about to return to user mode.
 120 .Pp
 121 The traditional assignment of the various device drivers to the
 122 interrupt priority groups can be roughly classified as:
 123 .Bl -tag -width Fn
 124 .It Fn splnet
 125 All network interface drivers.
 126 .It Fn splbio
 127 All
 128 .Em buffered IO
 129 (i.e., disk and the like) drivers.
 130 .It Fn spltty
 131 Basically, all non-network communications devices, but effectively
 132 used for all drivers that are neither network nor disks.
 133 .El
 134 .Sh RETURN VALUES
 135 All functions except
 136 .Fn splx
 137 and
 138 .Fn spl0
 139 return the previous priority value.
 140 .Sh EXAMPLES
 141 This is a typical example demonstrating the usage:
 142 .Bd -literal
 143 struct foo_softc {
 144         ...
 145         int flags;
 146 #define FOO_ASLEEP      1
 147 #define FOO_READY       2
 148
 149 } foo_softc[NFOO];
 150
 151 int
 152 foowrite(...)
 153 {
 154         struct foo_softc *sc;
 155         int s, error;
 156
 157         ...
 158         s = spltty();
 159         if (!(sc->flags & FOO_READY)) {
 160                 /* Not ready, must sleep on resource. */
 161                 sc->flags |= FOO_ASLEEP;
 162                 error = tsleep(sc, PZERO, "foordy", 0);
 163                 sc->flags &= ~FOO_ASLEEP;
 164         }
 165         sc->flags &= ~FOO_READY;
 166         splx(s);
 167
 168         ...
 169 }
 170
 171 void
 172 foointr(...)
 173 {
 174         struct foo_softc *sc;
 175
 176         ...
 177         sc->flags |= FOO_READY;
 178         if (sc->flags & FOO_ASLEEP)
 179                 /* Somebody was waiting for us, awake him. */
 180                 wakeup(sc);
 181         ...
 182 }
 183
 184 .Ed
 185 Note that the interrupt handler should
 186 .Em never
 187 reduce the priority level.  It is automatically called as it had
 188 raised the interrupt priority to its own level, i.e. further interrupts
 189 of the same group are being blocked.
 190 .Sh HISTORY
 191 The interrupt priority levels appeared in a very early version of
 192 Unix.  They have been traditionally known by number instead of by
 193 names, and were inclusive up to higher priority levels (i.e., priority
 194 5 has been blocking everything up to level 5).  This is no longer the
 195 case in
 196 .Fx .
 197 The traditional name
 198 .Ql level
 199 for them is still reflected in the letter
 200 .Ql l
 201 of the respective functions and variables, although they are not
 202 really levels anymore, but rather different (partially inclusive)
 203 sets of functions to be blocked during some periods of the life of
 204 the system.  The historical number scheme can be considered as a
 205 simple linearly ordered set of interrupt priority groups.
 206 .Sh AUTHORS
 207 This man page was written by
 208 .An J\(:org Wunsch .