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