OvmfPkg/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 #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