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