This commit was generated by cvs2svn to compensate for changes in r10,
[reactos.git] / reactos / doc / irq.txt
1 ** Introduction
2
3 This attempts to document the ReactOS irq handling. As of v0.0.8 this has
4 changed to be more nt like, I will attempt to summarize the new
5 implementation for those unavailable with nt device driver writing. Note,
6 ReactOS doesn't have an exact implementation but the omissions are, except
7 where noted, not user visible.
8
9 ** Steps in grabbing an irq vector
10
11 * Call HalConnectInterrupt
12
13 PROTOTYPE:
14
15 ULONG HalGetInterruptVector(INTERFACE_TYPE InterfaceType,
16 ULONG BusNumber,
17 ULONG BusInterruptLevel,
18 ULONG BusInterruptVector,
19 OUT PKIRQL Irql,
20 OUT PKAFFINITY Affinity)
21
22 PURPOSE:
23
24 Translates a bus dependant interrupt vector to a system vector
25
26 ARGUMENTS:
27
28 InterfaceType = Type of bus to which the device to receive interrupts
29 from is connected to. Currently only 'Internal' is
30 recognized
31 BusNumber = Number of the bus the device is connected to
32 (currently ignored)
33 BusInterruptLevel = Bus specific interrupt level (currently ignored)
34 BusInterruptVector = Bus specific vector. Currently this is the same
35 as the normal vector (09 is the keyboard vector
36 for example)
37 Irql = On return contains the DIRQL for the vector
38 Affinity = On return contains the affinity mask for the vector
39 (currently unimplemented)
40
41 RETURNS:
42 The system mapped vector
43
44 * Call IoConnectInterrupt
45
46 PROTOTYPE:
47
48 NTSTATUS IoConnectInterrupt(OUT PKINTERRUPT* InterruptObject,
49 PKSERVICE_ROUTINE ServiceRoutine,
50 PVOID ServiceContext,
51 PKSPIN_LOCK SpinLock,
52 ULONG Vector,
53 KIRQL Irql,
54 KIRQL SynchronizeIrql,
55 KINTERRUPT_MODE InterruptMode,
56 BOOLEAN ShareVector,
57 KAFFINITY ProcessorEnableMask,
58 BOOLEAN FloatingSave)
59
60 PURPOSE:
61
62 Connect a service routine to an interrupt vector
63
64 ARGUMENTS:
65
66 InterruptObject = Points to an object describes the interrupt on
67 return
68 ServiceRoutine = Function to be called when the device interrupts
69 ServiceContext = Parameters to be passed to the service routine
70 SpinLock = Should be NULL
71 Vector = System mapped vector returned from HalGetInterruptVector
72 Irql = DIRQL returned from HalGetInterruptVector
73 SynchronizeIrql = Should be the same as Irql
74 InterruptMode = Device interrupt type (currently ignored)
75 ShareVector = True if the interrupt vector can shared
76 ProcessorEnableMask = Currently ignored
77 FloatingSave = Should be false
78
79 RETURNS: Status
80
81 * Sample code for snarfing an interrupt vector
82
83
84 void grab_my_irq()
85 {
86 ULONG MappedIrq;
87 KIRQL Dirql;
88 KAFFINITY Affinity;
89 PKINTERRUPT IrqObject;
90
91 MappedIrq = HalGetInterruptVector(Internal,
92 0,
93 0,
94 MY_VECTOR,
95 &Dirql,
96 &Affinity);
97 IoConnectInterrupt(&IrqObject,
98 my_irq_service_routine,
99 my_context,
100 NULL,
101 MappedIrq,
102 Dirql,
103 Dirql,
104 0,
105 FALSE, // Not sharable
106 Affinity,
107 FALSE);
108 }
109
110 ** Designing an interrupt service routine
111
112 An interrupt service routine should have the following prototype
113
114 BOOLEAN my_irq_service_routine(PKINTERRUPT Interrupt,
115 PVOID ServiceContext);
116
117 ARGUMENTS:
118
119 Interrupt = The same as the object returned from the
120 IoConnectInterrupt
121 ServiceContext = A user defined parameters
122 (passed to IoConnectInterrupt)
123
124 RETURNS:
125
126 True if it handled the interrupt, false if it should be passed onto
127 other devices sharing the same vector
128
129 NOTES:
130
131 While an isr is executing all devices of a lower or equal priority
132 can't interrupt. For this reason it is important that an isr
133 should complete in a short an interval as possible. The set of
134 routines an isr can call is also restricted.
135