init_bh, remove_bh, mark_bh, disable_bh, enable_bh

       init_bh, remove_bh, mark_bh, disable_bh, enable_bh -

       split-half interrupt handling

SYNOPSIS

       #include <linux/interrupt.h>


       void init_bh(int nr, void (*routine)(void));

       void remove_bh(int nr);

       void mark_bh(int nr);

       void disable_bh(int nr);

       void enable_bh(int nr);

DESCRIPTION

   Theory

       Split-half handling is a means of  dividing  an  interrupt

       handler into two sections, one of which (known as the `top

       half') is time-critical and  one  of  which  (the  `bottom

       half') is not.


       The  top half (the handler registered with request_irq(9))

       normally moves  data  between  the  device  and  a  memory

       buffer,  ensures  that  the device is in a sane state, and

       little else.  While the top half of a handler is  running,

       the  IRQ is question is blocked; if it is a fast interrupt

       handler (i.e., it has SA_INTERRUPT  set),  all  interrupts

       are disabled.


       The  bottom half does whatever remains to be done.  Bottom

       halves run with interrupts  enabled,  although  a  locking

       mechanism  ensures  that only one bottom half will be run�

       ning  at  a  given  time.   Bottom  halves  are   run   by

       do_bottom_half(),  which  is  called  from  schedule() and

       ret_from_sys_call().


   Usage

       init_bh() installs routine() as bottom half number nr.  It

       operates  by  adding  an entry to the bh_base[] table, and

       setting the appropriate bit of the bh_mask vector.  Rather

       than  specifying  a  number  explicitly, one should add an

       entry to the anonymous enum in  include/linux/interrupt.h.


       remove_bh() removes bottom half number nr from the list of

       bottom halves.  It removes the entry  from  bh_base[]  and

       clears the appropriate bit of bh_mask.


       mark_bh()  requests that the kernel run the specified bot�

       tom  half  at  the  first  available  opportunity.    This

       function is normally called from the top half of an inter�

       rupt handler.  It operates by setting the appropriate  bit

       of the bh_active vector.


       disable_bh()  disables  bottom  half number nr by clearing

       nested calls to disable_bh() must be matched by  an  equal

       number of calls to enable_bh().


       enable_bh()  enables  a bottom half previously disabled by

       disable_bh().  This function decrements bh_mask_count[nr].

       Then,  if that value is zero, the specified bottom half is

       enabled by setting the appropriate bit of bh_mask.

RETURN VALUE

       No value is returned.

AVAILABILITY

       Linux 2.0+.  init_bh() and remove_bh() were not present in

       older  versions on Linux.  Under those versions, bh_base[]

       and bh_mask must be modified by hand.

SEE ALSO

       request_irq(9), queue_task(9)


       include/asm*/softirq.h,  include/linux/interrupt.h,   ker�

       nel/softirq.c


       "Kernel  Korner" in issue 26 of The Linux Journal includes

       a discussion of split-half  interrupts  under  Linux.   An

       online   copy   of   this   article   can   be   found  at

       http://www.ssc.com/lj/issue26/interrupt.html.

AUTHOR

       Neil Moore <amethyst@maxwell.ml.org>

BUGS

       Only 32 bottom halves are allowed.  Increasing this number

       requires    changing    the    size   of   bh_base[]   and

       bh_mask_count[]   in   kernel/softirq.c,   and    changing

       bh_active and bh_mask (in the same file) to a larger type.

       A better solution, however, would be to consolidate multi�

       ple  bottom halves into a single one by using task queues.

       See queue_task(9) for details.