/share/man/man9/spl.9

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 228 lines · 221 code · 7 blank · 0 comment · 0 complexity · a2ccca56d0258db74b4ddd0c880d41fb MD5 · raw file

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