IntelFrameworkPkg/Include/Protocol/Legacy8259.h

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