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: src/share/man/man9/spl.9,v 1.8.2.5 2001/12/17 11:30:19 ru Exp $
  27 .\" $DragonFly: src/share/man/man9/Attic/spl.9,v 1.4 2004/03/11 12:28:57 hmp Exp $
  28 .\"
  29 .Dd July 21, 1996
  30 .Os
  31 .Dt SPL 9
  32 .Sh NAME
  33 .Nm splbio ,
  34 .Nm splclock ,
  35 .Nm splhigh ,
  36 .Nm splimp ,
  37 .Nm splnet ,
  38 .Nm splsoftclock ,
  39 .Nm splsofttty ,
  40 .Nm splstatclock ,
  41 .Nm spltty ,
  42 .Nm splvm ,
  43 .Nm spl0 ,
  44 .Nm splx
  45 .Nd manipulate interrupt priorities
  46 .Sh SYNOPSIS
  47 .In sys/types.h
  48 .In sys/systm.h
  49 .Ft intrmask_t
  50 .Fn splbio "void"
  51 .Ft intrmask_t
  52 .Fn splclock "void"
  53 .Ft intrmask_t
  54 .Fn splhigh "void"
  55 .Ft intrmask_t
  56 .Fn splimp "void"
  57 .Ft intrmask_t
  58 .Fn splnet "void"
  59 .Ft intrmask_t
  60 .Fn splsoftclock "void"
  61 .Ft intrmask_t
  62 .Fn splsofttty "void"
  63 .Ft intrmask_t
  64 .Fn splstatclock "void"
  65 .Ft intrmask_t
  66 .Fn spltty "void"
  67 .Ft void
  68 .Fn spl0 "void"
  69 .Ft void
  70 .Fn splx "intrmask_t ipl"
  71 .Sh DESCRIPTION
  72 The
  73 .Fn spl
  74 function family sets the interrupt priority
  75 .Dq level
  76 of the CPU.
  77 This prevents interrupt handlers of the blocked priority level from
  78 being run.  This is used in the
  79 .Dq synchronous
  80 part of a driver (the part that runs on behalf of the user process) to
  81 examine or modify data areas that might be examined or modified by
  82 interrupt handlers.
  83 .Pp
  84 Each driver that uses interrupts is normally assigned to an interrupt
  85 priority group by a keyword in its config line.
  86 For example:
  87 .Bd -literal -offset indent
  88 device foo0 at isa? port 0x0815 irq 12 tty
  89 .Ed
  90 .Pp
  91 assigns interrupt 12 to the
  92 .Dq tty
  93 priority group.  The system automatically arranges for interrupts in
  94 the
  95 .Em xxx
  96 group to be called at a priority >=
  97 .Ns spl Ns Em xxx
  98 \&().
  99 .Pp
 100 The function
 101 .Fn splx
 102 sets the interrupt priority to an absolute value.  The intent is that
 103 the value returned by the other functions should be saved in a local
 104 variable, and later passed to
 105 .Fn splx
 106 in order to restore the previous priority.
 107 .Pp
 108 The function
 109 .Fn spl0
 110 lowers the priority to a value where all interrupt handlers are
 111 unblocked, but ASTs (asynchronous system traps) remain blocked until
 112 the system is about to return to user mode.
 113 .Pp
 114 The traditional assignment of the various device drivers to the
 115 interrupt priority groups can be roughly classified as:
 116 .Bl -tag -width Fn
 117 .It Fn splnet
 118 All network interface drivers.
 119 .It Fn splbio
 120 All
 121 .Em buffered IO
 122 (i.e., disk and the like) drivers.
 123 .It Fn spltty
 124 Basically, all non-network communications devices, but effectively
 125 used for all drivers that are neither network nor disks.
 126 .El
 127 .Sh RETURN VALUES
 128 All functions except
 129 .Fn splx
 130 and
 131 .Fn spl0
 132 return the previous priority value.
 133 .Sh EXAMPLES
 134 This is a typical example demonstrating the usage:
 135 .Bd -literal
 136 struct foo_softc {
 137         ...
 138         int flags;
 139 #define FOO_ASLEEP      1
 140 #define FOO_READY       2
 141
 142 } foo_softc[NFOO];
 143
 144 int
 145 foowrite(...)
 146 {
 147         struct foo_softc *sc;
 148         int s, error;
 149
 150         ...
 151         s = spltty();
 152         if (!(sc->flags & FOO_READY)) {
 153                 /* Not ready, must sleep on resource. */
 154                 sc->flags |= FOO_ASLEEP;
 155                 error = tsleep(sc, 0, "foordy", 0);
 156                 sc->flags &= ~FOO_ASLEEP;
 157         }
 158         sc->flags &= ~FOO_READY;
 159         splx(s);
 160
 161         ...
 162 }
 163
 164 void
 165 foointr(...)
 166 {
 167         struct foo_softc *sc;
 168
 169         ...
 170         sc->flags |= FOO_READY;
 171         if (sc->flags & FOO_ASLEEP)
 172                 /* Somebody was waiting for us, awake him. */
 173                 wakeup(sc);
 174         ...
 175 }
 176
 177 .Ed
 178 Note that the interrupt handler should
 179 .Em never
 180 reduce the priority level.  It is automatically called as it had
 181 raised the interrupt priority to its own level, i.e. further interrupts
 182 of the same group are being blocked.
 183 .Sh HISTORY
 184 The interrupt priority levels appeared in a very early version of
 185 Unix.  They have been traditionally known by number instead of by
 186 names, and were inclusive up to higher priority levels (i.e., priority
 187 5 has been blocking everything up to level 5).  This is no longer the
 188 case in
 189 .Dx .
 190 The traditional name
 191 .Ql level
 192 for them is still reflected in the letter
 193 .Ql l
 194 of the respective functions and variables, although they are not
 195 really levels anymore, but rather different (partially inclusive)
 196 sets of functions to be blocked during some periods of the life of
 197 the system.  The historical number scheme can be considered as a
 198 simple linearly ordered set of interrupt priority groups.
 199 .Sh AUTHORS
 200 This man page was written by
 201 .An J\(:org Wunsch .