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

   1 .\" -*- nroff -*-
   2 .TH PROBE_IRQ_ON 9 "1997/08/14 07:53:32" "Linux DDI 2.1.47" "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 probe_irq_on, probe_irq_off \- safe probing for IRQs
  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 .B "unsigned\ long\ probe_irq_on(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 "int\ probe_irq_off(unsigned\ long " irqs ");"
  45 .\" And set it back to normal now
  46 .PD 1
  47 .\" Back to standard adjustment
  48 .ad
  49 .\" Allow hypenation, omit if you want no hyphenation in the man page
  50 .hlm 1
  51 .SH DESCRIPTION
  52 .SS Usage
  53 .PP
  54 .B probe_irq_on()
  55 turns on IRQ detection.  It operates by enabling all interrupts which have
  56 no handlers, while keeping the handlers for those interrupts NULL.  The
  57 kernel's generic interrupt handling routine will disable these IRQs when
  58 an interrupt is received on them.
  59 .B probe_irq_on()
  60 adds each of these IRQ numbers to a vector which it will return.  It waits
  61 approximately 100ms for any spurious interrupts that may occur, and masks
  62 these from its vector; it then returns this vector to its caller.
  63 .PP
  64 .B probe_irq_off()
  65 tests an internal list of enabled IRQs against its
  66 .I irqs
  67 parameter, which should be the value returned by the last
  68 .BR probe_irq_on() .
  69 This function basically detects which IRQs have been switched off, and thus
  70 which ones have received interrupts.
  71 .SS Example
  72 This explanation may seem a bit confusing, so here is an example of code
  73 the mythical FUBAR 2000 driver could use to probe for IRQs:
  74 .RS
  75 .PP
  76 unsigned long irqs;
  77 .br
  78 int irq;
  79 .sp
  80 irqs = probe_irq_on();
  81 .sp
  82 outb(FB2K_GIVE_ME_AN_INTERRUPT_OR_GIVE_ME_DEATH,
  83      FB2K_CONTROL_PORT);
  84 .br
  85   /* the interrupt could take a while to occur */
  86 .br
  87 udelay(1000);
  88 .sp
  89 irq = probe_irq_off(irqs);
  90 .sp
  91 if (irq == 0) {
  92 .br
  93         printk("fb2k: could not detect IRQ.\en");
  94 .br
  95         printk("fb2k: Installation failed.\en");
  96 .br
  97 } else if (irq == -1) {
  98 .br
  99         printk("fb2k: multiple IRQs detected.\en");
 100 .br
 101         printk("fb2k: Installation failed.\en");
 102 .br
 103 } else {
 104 .br
 105         fb2k_dev->irq = irq;
 106 .br
 107         printk("fb2k: using probed IRQ %d.\en", irq);
 108 .br
 109 }
 110 .br
 111 .SH "RETURN VALUE"
 112 .B probe_irq_on()
 113 returns a bitmap of all unhandled IRQs (except those which are receiving
 114 spurious interrupts).  This value should only be used as a parameter to
 115 the next call to
 116 .BR probe_irq_off() .
 117 .PP
 118 .B probe_irq_off()
 119 returns the IRQ number of whichever unhandled interrupt has occurred since
 120 the last
 121 .BR probe_irq_on() .
 122 If no interrupts have occurred on any of the marked IRQs, 0 is returned;
 123 if interrupts have occurred on more than one of these IRQs, -1 is returned.
 124 .SH AVAILABILITY
 125 Linux 1.2+.  These functions are not available on m68k-based machines.
 126 .SH "SEE ALSO"
 127 .BR request_irq "(9)"
 128 .PP
 129 .I arch/*/kernel/irq.c
 130 .SH AUTHOR
 131 .RI "Neil Moore <" amethyst@maxwell.ml.org ">"
 132 .SH BUGS
 133 As mentioned above, these functions are not available on m68k-based machines.
 134 .PP
 135 This manpage is way too confusing.
 136 .\"
 137 .\" probe_irq_on.9,v
 138 .\" Revision 1.2  1997/08/14 07:53:32  amethyst
 139 .\" Formatting changes.
 140 .\"
 141 .\" Revision 1.1  1997/07/28 10:28:34  amethyst
 142 .\" Initial revision
 143 .\"
 144 .\"