manual/linux-man9/original/man9/init_bh.9

   1 .\" -*- nroff -*-
   2 .TH INIT_BH 9 "1997/08/14 07:53:12" "Linux DDI 2.1.48" "Linux Kernel Functions"
   3 .\" copyright (C) 1997 Neil Moore <amethyst@maxwell.ml.org>
   4 .\"
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24
  25 .\" Turn off hyphentation
  26 .hlm 0
  27 .\" Turn off adjustment
  28 .na
  29 .SH NAME
  30 init_bh, remove_bh, mark_bh, disable_bh, enable_bh \- split-half interrupt handling
  31 .SH SYNOPSIS
  32 .B #include <linux/interrupt.h>
  33 .\" To keep all components of a declaration together, escape all white
  34 .\" space except after a comma.  In case the proc name plus the first
  35 .\" declaration is too long for one line, allow a break after '(' by
  36 .\" adding '\%'.
  37 .HP
  38 .BI "void\ init_bh(int " nr ", void\ (*" routine ")(void));"
  39 .\" We don't want an inter-paragraph space between the two declarations,
  40 .\" but we have to end the paragraph to stop the hanging indent.  .PD 0
  41 .\" gets rid of inter-paragraph spacing
  42 .PD 0
  43 .HP
  44 .BI "void\ remove_bh(int\ " nr ");"
  45 .HP
  46 .BI "void\ mark_bh(int\ " nr ");"
  47 .HP
  48 .BI "void\ disable_bh(int\ " nr ");"
  49 .HP
  50 .BI "void\ enable_bh(int\ " nr ");"
  51 .\" And set it back to normal now
  52 .PD 1
  53 .\" Back to standard adjustment
  54 .ad
  55 .\" Allow hypenation, omit if you want no hyphenation in the man page
  56 .hlm 1
  57 .SH DESCRIPTION
  58 .SS Theory
  59 .PP
  60 Split-half handling is a means of dividing an interrupt handler into two
  61 sections, one of which (known as the \(oqtop half') is time-critical and
  62 one of which (the \(oqbottom half') is not.
  63 .PP
  64 The top half (the handler registered with
  65 .BR "request_irq" "(9))"
  66 normally moves data between the device and a memory buffer, ensures that the
  67 device is in a sane state, and little else.  While the top half of a handler
  68 is running, the IRQ is question is blocked; if it is a fast interrupt handler
  69 (i.e., it has
  70 .B SA_INTERRUPT
  71 set), all interrupts are disabled.
  72 .PP
  73 The bottom half does whatever remains to be done.  Bottom halves run with
  74 interrupts enabled, although a locking mechanism ensures that only one
  75 bottom half will be running at a given time.  Bottom halves are run by
  76 .BR do_bottom_half() ,
  77 which is called from
  78 .B schedule()
  79 and
  80 .BR ret_from_sys_call() ". "
  81 .SS Usage
  82 .PP
  83 .B init_bh()
  84 installs
  85 .I routine()
  86 as bottom half number
  87 .IR nr ". "
  88 It operates by adding an entry to the
  89 .B bh_base[]
  90 table, and setting the appropriate bit of the
  91 .B bh_mask
  92 vector.  Rather than specifying a number explicitly, one should add an entry
  93 to the anonymous enum in
  94 .IR "include/linux/interrupt.h" ". "
  95 .PP
  96 .B remove_bh()
  97 removes bottom half number
  98 .I nr
  99 from the list of bottom halves.  It removes the entry from
 100 .B bh_base[]
 101 and clears the appropriate bit of
 102 .BR bh_mask ". "
 103 .PP
 104 .B mark_bh()
 105 requests that the kernel run the specified bottom half at the first available
 106 opportunity.  This function is normally called from the top half of an interrupt
 107 handler.  It operates by setting the appropriate bit of the
 108 .B bh_active
 109 vector.
 110 .PP
 111 .B disable_bh()
 112 disables bottom half number
 113 .I nr
 114 by clearing the appropriate bit of
 115 .BR bh_mask .
 116 This function also increments
 117 .BI bh_mask_count[ nr ]\fR,
 118 which is used to ensure that nested calls to
 119 .B disable_bh()
 120 must be matched by an equal number of calls to
 121 .BR enable_bh() .
 122 .PP
 123 .B enable_bh()
 124 enables a bottom half previously disabled by
 125 .BR disable_bh() .
 126 This function decrements
 127 .BI bh_mask_count[ nr ]\fR.
 128 Then, if that value is zero, the specified bottom half is enabled
 129 by setting the appropriate bit of
 130 .BR bh_mask .
 131 .SH "RETURN VALUE"
 132 No value is returned.
 133 .SH AVAILABILITY
 134 Linux 2.0+.
 135 .B init_bh()
 136 and
 137 .B remove_bh()
 138 were not present in older versions on Linux.  Under those versions,
 139 .B bh_base[]
 140 and
 141 .B bh_mask
 142 must be modified by hand.
 143 .SH "SEE ALSO"
 144 .BR request_irq "(9), " queue_task "(9)"
 145 .PP
 146 .IR include/asm*/softirq.h ", " include/linux/interrupt.h ", " kernel/softirq.c
 147 .PP
 148 \(lqKernel Korner\(rq in issue 26 of
 149 .I The Linux Journal
 150 includes a discussion of split-half interrupts under Linux.  An online copy of
 151 this article can be found at
 152 .BR http://www.ssc.com/lj/issue26/interrupt.html .
 153 .SH AUTHOR
 154 .RI "Neil Moore <" amethyst@maxwell.ml.org ">"
 155 .SH BUGS
 156 Only 32 bottom halves are allowed.  Increasing this number requires changing
 157 the size of
 158 .B bh_base[]
 159 and
 160 .BI bh_mask_count[]
 161 in
 162 .IR kernel/softirq.c,
 163 and changing
 164 .B bh_active
 165 and
 166 .B bh_mask
 167 (in the same file) to a larger type.  A better solution, however, would be to
 168 consolidate multiple bottom halves into a single one by using task queues.
 169 See
 170 .BR queue_task (9)
 171 for details.
 172 .\"
 173 .\" init_bh.9,v
 174 .\" Revision 1.4  1997/08/14 07:53:12  amethyst
 175 .\" Formatting changes.
 176 .\"
 177 .\" Revision 1.3  1997/08/08 16:40:50  amethyst
 178 .\" Updated for 2.1.48 -- init_bh() and friends are now available again on the PPC.
 179 .\"
 180 .\" Revision 1.2  1997/07/27 09:39:45  amethyst
 181 .\" Changed some wording.
 182 .\" Fixed a few typographical warts.
 183 .\" Added email address to copyright notice.
 184 .\"
 185 .\" Revision 1.1  1997/07/27 09:27:17  amethyst
 186 .\" Initial revision
 187 .\"
 188 .\"