ffd184c150eaebebf757ab07d0b0c14659de745b
[mirror_edk2.git] / IntelFrameworkPkg / Include / Protocol / Legacy8259.h
1 /** @file
2 This protocol abstracts the 8259 interrupt controller. This includes
3 PCI IRQ routing need to program the PCI Interrupt Line register.
4
5 Copyright (c) 2007, Intel Corporation
6 All rights reserved. This program and the accompanying materials
7 are licensed and made available under the terms and conditions of the BSD License
8 which accompanies this distribution. The full text of the license may be found at
9 http://opensource.org/licenses/bsd-license.php
10
11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
13
14 Module Name: Legacy8259.h
15
16 @par Revision Reference:
17 This protocol is defined in Framework for EFI Compatibility Support Module spec
18 Version 0.96
19
20 **/
21
22 #ifndef _EFI_LEGACY_8259_H_
23 #define _EFI_LEGACY_8259_H_
24
25 #include <PiDxe.h>
26
27 #define EFI_LEGACY_8259_PROTOCOL_GUID \
28 { \
29 0x38321dba, 0x4fe0, 0x4e17, {0x8a, 0xec, 0x41, 0x30, 0x55, 0xea, 0xed, 0xc1 } \
30 }
31
32 typedef struct _EFI_LEGACY_8259_PROTOCOL EFI_LEGACY_8259_PROTOCOL;
33
34 typedef enum {
35 Efi8259Irq0,
36 Efi8259Irq1,
37 Efi8259Irq2,
38 Efi8259Irq3,
39 Efi8259Irq4,
40 Efi8259Irq5,
41 Efi8259Irq6,
42 Efi8259Irq7,
43 Efi8259Irq8,
44 Efi8259Irq9,
45 Efi8259Irq10,
46 Efi8259Irq11,
47 Efi8259Irq12,
48 Efi8259Irq13,
49 Efi8259Irq14,
50 Efi8259Irq15,
51 Efi8259IrqMax
52 } EFI_8259_IRQ;
53
54 typedef enum {
55 Efi8259LegacyMode,
56 Efi8259ProtectedMode,
57 Efi8259MaxMode
58 } EFI_8259_MODE;
59
60 /**
61 Get the 8259 interrupt masks for Irq0 - Irq15. A different mask exists for
62 the legacy mode mask and the protected mode mask. The base address for the 8259
63 is different for legacy and protected mode, so two masks are required.
64
65 @param This Protocol instance pointer.
66 @param MasterBase The base vector for the Master PIC in the 8259 controller
67 @param Slavebase The base vector for the Master PIC in the 8259 controller
68
69 @retval EFI_SUCCESS The new bases were programmed
70 @retval EFI_DEVICE_ERROR A device erro occured programming the vector bases
71
72 **/
73 typedef
74 EFI_STATUS
75 (EFIAPI *EFI_LEGACY_8259_SET_VECTOR_BASE) (
76 IN EFI_LEGACY_8259_PROTOCOL *This,
77 IN UINT8 MasterBase,
78 IN UINT8 SlaveBase
79 );
80
81 /**
82 Get the 8259 interrupt masks for Irq0 - Irq15. A different mask exists for
83 the legacy mode mask and the protected mode mask. The base address for the 8259
84 is different for legacy and protected mode, so two masks are required.
85
86 @param This Protocol instance pointer.
87 @param LegacyMask Bit 0 is Irq0 - Bit 15 is Irq15
88 @param LegacyEdgeLevel Bit 0 is Irq0 - Bit 15 is Irq15
89 @param ProtectedMask Bit 0 is Irq0 - Bit 15 is Irq15
90 @param ProtectedEdgeLevel Bit 0 is Irq0 - Bit 15 is Irq15
91
92 @retval EFI_SUCCESS 8259 status returned
93 @retval EFI_DEVICE_ERROR Error reading 8259
94
95 **/
96 typedef
97 EFI_STATUS
98 (EFIAPI *EFI_LEGACY_8259_GET_MASK) (
99 IN EFI_LEGACY_8259_PROTOCOL *This,
100 OUT UINT16 *LegacyMask, OPTIONAL
101 OUT UINT16 *LegacyEdgeLevel, OPTIONAL
102 OUT UINT16 *ProtectedMask, OPTIONAL
103 OUT UINT16 *ProtectedEdgeLevel OPTIONAL
104 );
105
106 /**
107 Set the 8259 interrupt masks for Irq0 - Irq15. A different mask exists for
108 the legacy mode mask and the protected mode mask. The base address for the 8259
109 is different for legacy and protected mode, so two masks are required.
110 Also set the edge/level masks.
111
112 @param This Protocol instance pointer.
113 @param LegacyMask Bit 0 is Irq0 - Bit 15 is Irq15
114 @param LegacyEdgeLevel Bit 0 is Irq0 - Bit 15 is Irq15
115 @param ProtectedMask Bit 0 is Irq0 - Bit 15 is Irq15
116 @param ProtectedEdgeLevel Bit 0 is Irq0 - Bit 15 is Irq15
117
118 @retval EFI_SUCCESS 8259 status returned
119 @retval EFI_DEVICE_ERROR Error reading 8259
120
121 **/
122 typedef
123 EFI_STATUS
124 (EFIAPI *EFI_LEGACY_8259_SET_MASK) (
125 IN EFI_LEGACY_8259_PROTOCOL *This,
126 IN UINT16 *LegacyMask, OPTIONAL
127 IN UINT16 *LegacyEdgeLevel, OPTIONAL
128 IN UINT16 *ProtectedMask, OPTIONAL
129 IN UINT16 *ProtectedEdgeLevel OPTIONAL
130 );
131
132 /**
133 Set the 8259 mode of operation. The base address for the 8259 is different for
134 legacy and protected mode. The legacy mode requires the master 8259 to have a
135 master base of 0x08 and the slave base of 0x70. The protected mode base locations
136 are not defined. Interrupts must be masked by the caller before this function
137 is called. The interrupt mask from the current mode is saved. The interrupt
138 mask for the new mode is Mask, or if Mask does not exist the previously saved
139 mask is used.
140
141 @param This Protocol instance pointer.
142 @param Mode Mode of operation. i.e. real mode or protected mode
143 @param Mask Optional interupt mask for the new mode.
144 @param EdgeLevel Optional trigger mask for the new mode.
145
146 @retval EFI_SUCCESS 8259 programmed
147 @retval EFI_DEVICE_ERROR Error writting to 8259
148
149 **/
150 typedef
151 EFI_STATUS
152 (EFIAPI *EFI_LEGACY_8259_SET_MODE) (
153 IN EFI_LEGACY_8259_PROTOCOL *This,
154 IN EFI_8259_MODE Mode,
155 IN UINT16 *Mask, OPTIONAL
156 IN UINT16 *EdgeLevel OPTIONAL
157 );
158
159 /**
160 Convert from IRQ to processor interrupt vector number.
161
162 @param This Protocol instance pointer.
163 @param Irq 8259 IRQ0 - IRQ15
164 @param Vector Processor vector number that matches Irq
165
166 @retval EFI_SUCCESS The Vector matching Irq is returned
167 @retval EFI_INVALID_PARAMETER Irq not valid
168
169 **/
170 typedef
171 EFI_STATUS
172 (EFIAPI *EFI_LEGACY_8259_GET_VECTOR) (
173 IN EFI_LEGACY_8259_PROTOCOL *This,
174 IN EFI_8259_IRQ Irq,
175 OUT UINT8 *Vector
176 );
177
178 /**
179 Enable Irq by unmasking interrupt in 8259
180
181 @param This Protocol instance pointer.
182 @param Irq 8259 IRQ0 - IRQ15
183 @param LevelTriggered TRUE if level triggered. FALSE if edge triggered.
184
185 @retval EFI_SUCCESS Irq enabled on 8259
186 @retval EFI_INVALID_PARAMETER Irq not valid
187
188 **/
189 typedef
190 EFI_STATUS
191 (EFIAPI *EFI_LEGACY_8259_ENABLE_IRQ) (
192 IN EFI_LEGACY_8259_PROTOCOL *This,
193 IN EFI_8259_IRQ Irq,
194 IN BOOLEAN LevelTriggered
195 );
196
197 /**
198 Disable Irq by masking interrupt in 8259
199
200 @param This Protocol instance pointer.
201 @param Irq 8259 IRQ0 - IRQ15
202
203 @retval EFI_SUCCESS Irq disabled on 8259
204 @retval EFI_INVALID_PARAMETER Irq not valid
205
206 **/
207 typedef
208 EFI_STATUS
209 (EFIAPI *EFI_LEGACY_8259_DISABLE_IRQ) (
210 IN EFI_LEGACY_8259_PROTOCOL *This,
211 IN EFI_8259_IRQ Irq
212 );
213
214 /**
215 PciHandle represents a PCI config space of a PCI function. Vector
216 represents Interrupt Pin (from PCI config space) and it is the data
217 that is programmed into the Interrupt Line (from the PCI config space)
218 register.
219
220 @param This Protocol instance pointer.
221 @param PciHandle PCI function to return vector for
222 @param Vector Vector for fucntion that matches
223
224 @retval EFI_SUCCESS A valid Vector is returned
225 @retval EFI_INVALID_PARAMETER PciHandle not valid
226
227 **/
228 typedef
229 EFI_STATUS
230 (EFIAPI *EFI_LEGACY_8259_GET_INTERRUPT_LINE) (
231 IN EFI_LEGACY_8259_PROTOCOL *This,
232 IN EFI_HANDLE PciHandle,
233 OUT UINT8 *Vector
234 );
235
236 /**
237 Send an EOI to 8259
238
239 @param This Protocol instance pointer.
240 @param Irq 8259 IRQ0 - IRQ15
241
242 @retval EFI_SUCCESS EOI successfully sent to 8259
243 @retval EFI_INVALID_PARAMETER Irq not valid
244
245 **/
246 typedef
247 EFI_STATUS
248 (EFIAPI *EFI_LEGACY_8259_END_OF_INTERRUPT) (
249 IN EFI_LEGACY_8259_PROTOCOL *This,
250 IN EFI_8259_IRQ Irq
251 );
252
253 /**
254 @par Protocol Description:
255 Abstracts the 8259 and APIC hardware control between EFI usage and
256 Compatibility16 usage.
257
258 @param SetVectorBase
259 Sets the vector bases for master and slave PICs.
260
261 @param GetMask
262 Gets IRQ and edge/level masks for 16-bit real mode and 32-bit protected mode.
263
264 @param SetMask
265 Sets the IRQ and edge\level masks for 16-bit real mode and 32-bit protected mode.
266
267 @param SetMode
268 Sets PIC mode to 16-bit real mode or 32-bit protected mode.
269
270 @param GetVector
271 Gets the base vector assigned to an IRQ.
272
273 @param EnableIrq
274 Enables an IRQ.
275
276 @param DisableIrq
277 Disables an IRQ.
278
279 @param GetInterruptLine
280 Gets an IRQ that is assigned to a PCI device.
281
282 @param EndOfInterrupt
283 Issues the end of interrupt command.
284
285 **/
286 struct _EFI_LEGACY_8259_PROTOCOL {
287 EFI_LEGACY_8259_SET_VECTOR_BASE SetVectorBase;
288 EFI_LEGACY_8259_GET_MASK GetMask;
289 EFI_LEGACY_8259_SET_MASK SetMask;
290 EFI_LEGACY_8259_SET_MODE SetMode;
291 EFI_LEGACY_8259_GET_VECTOR GetVector;
292 EFI_LEGACY_8259_ENABLE_IRQ EnableIrq;
293 EFI_LEGACY_8259_DISABLE_IRQ DisableIrq;
294 EFI_LEGACY_8259_GET_INTERRUPT_LINE GetInterruptLine;
295 EFI_LEGACY_8259_END_OF_INTERRUPT EndOfInterrupt;
296 };
297
298 extern EFI_GUID gEfiLegacy8259ProtocolGuid;
299
300 #endif