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