Tools/Source/TianoTools/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) 2006, 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 /**
  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 /**
 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 reading 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 /**
 134   Set the 8259 mode of operation. The base address for the 8259 is different for
 135   legacy and protected mode. The legacy mode requires the master 8259 to have a
 136   master base of 0x08 and the slave base of 0x70. The protected mode base locations
 137   are not defined. Interrupts must be masked by the caller before this function
 138   is called. The interrupt mask from the current mode is saved. The interrupt
 139   mask for the new mode is Mask, or if Mask does not exist the previously saved
 140   mask is used.
 141
 142   @param  This Protocol instance pointer.
 143   @param  Mode Mode of operation. i.e. real mode or protected mode
 144   @param  Mask Optional interupt mask for the new mode.
 145   @param  EdgeLevel Optional trigger mask for the new mode.
 146
 147   @retval  EFI_SUCCESS 8259 programmed
 148   @retval  EFI_DEVICE_ERROR Error writting to 8259
 149
 150 **/
 151 typedef
 152 EFI_STATUS
 153 (EFIAPI *EFI_LEGACY_8259_SET_MODE) (
 154   IN EFI_LEGACY_8259_PROTOCOL         *This,
 155   IN  EFI_8259_MODE                   Mode,
 156   IN  UINT16                          *Mask, OPTIONAL
 157   IN  UINT16                          *EdgeLevel OPTIONAL
 158   )
 159 ;
 160
 161 /**
 162   Convert from IRQ to processor interrupt vector number.
 163
 164   @param  This Protocol instance pointer.
 165   @param  Irq 8259 IRQ0 - IRQ15
 166   @param  Vector Processor vector number that matches Irq
 167
 168   @retval  EFI_SUCCESS The Vector matching Irq is returned
 169   @retval  EFI_INVALID_PARAMETER Irq not valid
 170
 171 **/
 172 typedef
 173 EFI_STATUS
 174 (EFIAPI *EFI_LEGACY_8259_GET_VECTOR) (
 175   IN EFI_LEGACY_8259_PROTOCOL           *This,
 176   IN  EFI_8259_IRQ                      Irq,
 177   OUT UINT8                             *Vector
 178   )
 179 ;
 180
 181 /**
 182   Enable Irq by unmasking interrupt in 8259
 183
 184   @param  This Protocol instance pointer.
 185   @param  Irq 8259 IRQ0 - IRQ15
 186   @param  LevelTriggered TRUE if level triggered.  FALSE if edge triggered.
 187
 188   @retval  EFI_SUCCESS Irq enabled on 8259
 189   @retval  EFI_INVALID_PARAMETER Irq not valid
 190
 191 **/
 192 typedef
 193 EFI_STATUS
 194 (EFIAPI *EFI_LEGACY_8259_ENABLE_IRQ) (
 195   IN EFI_LEGACY_8259_PROTOCOL           *This,
 196   IN  EFI_8259_IRQ                      Irq,
 197   IN  BOOLEAN                           LevelTriggered
 198   )
 199 ;
 200
 201 /**
 202   Disable Irq by masking interrupt in 8259
 203
 204   @param  This Protocol instance pointer.
 205   @param  Irq 8259 IRQ0 - IRQ15
 206
 207   @retval  EFI_SUCCESS Irq disabled on 8259
 208   @retval  EFI_INVALID_PARAMETER Irq not valid
 209
 210 **/
 211 typedef
 212 EFI_STATUS
 213 (EFIAPI *EFI_LEGACY_8259_DISABLE_IRQ) (
 214   IN EFI_LEGACY_8259_PROTOCOL           *This,
 215   IN  EFI_8259_IRQ                      Irq
 216   )
 217 ;
 218
 219 /**
 220   PciHandle represents a PCI config space of a PCI function. Vector
 221   represents Interrupt Pin (from PCI config space) and it is the data
 222   that is programmed into the Interrupt Line (from the PCI config space)
 223   register.
 224
 225   @param  This Protocol instance pointer.
 226   @param  PciHandle PCI function to return vector for
 227   @param  Vector Vector for fucntion that matches
 228
 229   @retval  EFI_SUCCESS A valid Vector is returned
 230   @retval  EFI_INVALID_PARAMETER PciHandle not valid
 231
 232 **/
 233 typedef
 234 EFI_STATUS
 235 (EFIAPI *EFI_LEGACY_8259_GET_INTERRUPT_LINE) (
 236   IN EFI_LEGACY_8259_PROTOCOL           *This,
 237   IN  EFI_HANDLE                        PciHandle,
 238   OUT UINT8                             *Vector
 239   )
 240 ;
 241
 242 /**
 243   Send an EOI to 8259
 244
 245   @param  This Protocol instance pointer.
 246   @param  Irq 8259 IRQ0 - IRQ15
 247
 248   @retval  EFI_SUCCESS EOI successfully sent to 8259
 249   @retval  EFI_INVALID_PARAMETER Irq not valid
 250
 251 **/
 252 typedef
 253 EFI_STATUS
 254 (EFIAPI *EFI_LEGACY_8259_END_OF_INTERRUPT) (
 255   IN EFI_LEGACY_8259_PROTOCOL           *This,
 256   IN  EFI_8259_IRQ                      Irq
 257   )
 258 ;
 259
 260 /**
 261   @par Protocol Description:
 262   Abstracts the 8259 and APIC hardware control between EFI usage and
 263   Compatibility16 usage.
 264
 265   @param SetVectorBase
 266   Sets the vector bases for master and slave PICs.
 267
 268   @param GetMask
 269   Gets IRQ and edge/level masks for 16-bit real mode and 32-bit protected mode.
 270
 271   @param SetMask
 272   Sets the IRQ and edge\level masks for 16-bit real mode and 32-bit protected mode.
 273
 274   @param SetMode
 275   Sets PIC mode to 16-bit real mode or 32-bit protected mode.
 276
 277   @param GetVector
 278   Gets the base vector assigned to an IRQ.
 279
 280   @param EnableIrq
 281   Enables an IRQ.
 282
 283   @param DisableIrq
 284   Disables an IRQ.
 285
 286   @param GetInterruptLine
 287   Gets an IRQ that is assigned to a PCI device.
 288
 289   @param EndOfInterrupt
 290   Issues the end of interrupt command.
 291
 292 **/
 293 struct _EFI_LEGACY_8259_PROTOCOL {
 294   EFI_LEGACY_8259_SET_VECTOR_BASE     SetVectorBase;
 295   EFI_LEGACY_8259_GET_MASK            GetMask;
 296   EFI_LEGACY_8259_SET_MASK            SetMask;
 297   EFI_LEGACY_8259_SET_MODE            SetMode;
 298   EFI_LEGACY_8259_GET_VECTOR          GetVector;
 299   EFI_LEGACY_8259_ENABLE_IRQ          EnableIrq;
 300   EFI_LEGACY_8259_DISABLE_IRQ         DisableIrq;
 301   EFI_LEGACY_8259_GET_INTERRUPT_LINE  GetInterruptLine;
 302   EFI_LEGACY_8259_END_OF_INTERRUPT    EndOfInterrupt;
 303 };
 304
 305 extern EFI_GUID gEfiLegacy8259ProtocolGuid;
 306
 307 #endif