sys/man/9/intrenable

   1 .TH INTRENABLE 9
   2 .SH NAME
   3 intrenable, intrdisable \- enable (disable) an interrupt handler
   4 .SH SYNOPSIS
   5 .ta \w'\fLvoid* 'u
   6 .B
   7 void intrenable(int v, void (*f)(Ureg*, void*), void* a, int tbdf, char *name)
   8 .PP
   9 .B
  10 void intrdisable(int v, void (*f)(Ureg*, void*), void* a, int tbdf, char *name)
  11 .SH DESCRIPTION
  12 .I Intrenable
  13 registers
  14 .I f
  15 to be called by the kernel's interrupt controller driver each time
  16 an interrupt denoted by
  17 .I v
  18 occurs, and unmasks the corresponding interrupt in the interrupt controller.
  19 The encoding of
  20 .I v
  21 is platform-dependent; it is often an interrupt vector number, but
  22 can be more complex.
  23 .I Tbdf
  24 is a platform-dependent value that might further qualify
  25 .IR v .
  26 It might for instance
  27 denote the type of bus, bus instance, device number and function
  28 (following the PCI device indexing scheme), hence its name,
  29 but can have platform-dependent meaning.
  30 .I Name
  31 is a string that should uniquely identify the corresponding device (eg, \f5"uart0"\fP);
  32 again it is usually platform-dependent.
  33 .I Intrenable
  34 supports sharing of interrupt levels when the hardware does.
  35 .PP
  36 Almost invariably
  37 .I f
  38 is a function defined in a device driver to carry out the device-specific work associated with a given interrupt.
  39 The pointer
  40 .I a
  41 is passed to
  42 .IR f ;
  43 typically it points to the driver's data for a given device or controller.
  44 It also passes
  45 .I f
  46 a
  47 .B Ureg*
  48 value that
  49 contains the registers saved by the interrupt handler (the
  50 contents are platform specific;
  51 see the platform's include file
  52 .BR "ureg.h" ).
  53 .PP
  54 .I F
  55 is invoked by underlying code in the kernel that is invoked directly from the hardware vectors.
  56 It is therefore not running in any process (see
  57 .IR kproc (9);
  58 indeed, on many platforms
  59 the current process pointer
  60 .RB ( up )
  61 will be nil.
  62 There are many restrictions on kernel functions running outside a process, but a fundamental one is that
  63 they must not
  64 .IR sleep (9),
  65 although they often call
  66 .B wakeup
  67 to signal the occurrence of an event associated with the interrupt.
  68 .IR Qio (9)
  69 and other manual pages note which functions are safe for
  70 .I f
  71 to call.
  72 .PP
  73 The interrupt controller driver does whatever is
  74 required to acknowledge or dismiss the interrupt signal in the interrupt controller,
  75 before calling
  76 .IR f ,
  77 for edge-triggered interrupts,
  78 and after calling
  79 .I f
  80 for level-triggered ones.
  81 .I F
  82 is responsible for dealing with the cause of the interrupt in the device, including any
  83 acknowledgement required in the device, before it returns.
  84 .PP
  85 .I Intrdisable
  86 removes any registration previously made by
  87 .I intrenable
  88 with matching parameters, and if no other
  89 interrupt is active on
  90 .IR v ,
  91 it masks the interrupt in the controller.
  92 Device drivers that are not dynamically configured tend to call
  93 .I intrenable
  94 during reset or initialisation (see
  95 .IR dev (9)),
  96 but can call it at any appropriate time, and
  97 instead of calling
  98 .I intrdisable
  99 they can simply enable or disable interrupts in the device as required.
 100 .SH SOURCE
 101 .B /sys/src/9/*/trap.c
 102 .SH SEE ALSO
 103 .IR malloc (9),
 104 .IR qio (9),
 105 .IR sleep (9),
 106 .IR splhi (9)