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