EmbeddedPkg/Include/Protocol/HardwareInterrupt.h

   1 /** @file
   2   Abstraction for hardware based interrupt routine
   3
   4   On non IA-32 systems it is common to have a single hardware interrupt vector
   5   and a 2nd layer of software that routes the interrupt handlers based on the
   6   interrupt source. This protocol enables this routing. The driver implementing
   7   this protocol is responsible for clearing the pending interrupt in the
   8   interrupt routing hardware. The HARDWARE_INTERRUPT_HANDLER is responsible
   9   for clearing interrupt sources from individual devices.
  10
  11
  12   Copyright (c) 2008 - 2009, Apple Inc. All rights reserved.<BR>
  13
  14   SPDX-License-Identifier: BSD-2-Clause-Patent
  15
  16 **/
  17
  18 #ifndef __HARDWARE_INTERRUPT_H__
  19 #define __HARDWARE_INTERRUPT_H__
  20
  21 #include <Protocol/DebugSupport.h>
  22
  23 //
  24 // Protocol GUID
  25 //
  26 // EAB39028-3D05-4316-AD0C-D64808DA3FF1
  27
  28 #define EFI_HARDWARE_INTERRUPT_PROTOCOL_GGUID \
  29   { 0x2890B3EA, 0x053D, 0x1643, { 0xAD, 0x0C, 0xD6, 0x48, 0x08, 0xDA, 0x3F, 0xF1 } }
  30
  31 typedef struct _EFI_HARDWARE_INTERRUPT_PROTOCOL EFI_HARDWARE_INTERRUPT_PROTOCOL;
  32
  33 typedef UINTN HARDWARE_INTERRUPT_SOURCE;
  34
  35 /**
  36   C Interrupt Handler calledin the interrupt context when Source interrupt is active.
  37
  38   @param Source         Source of the interrupt. Hardware routing off a specific platform defines
  39                         what source means.
  40   @param SystemContext  Pointer to system register context. Mostly used by debuggers and will
  41                         update the system context after the return from the interrupt if
  42                         modified. Don't change these values unless you know what you are doing
  43
  44 **/
  45 typedef
  46 VOID
  47 (EFIAPI *HARDWARE_INTERRUPT_HANDLER)(
  48   IN  HARDWARE_INTERRUPT_SOURCE   Source,
  49   IN  EFI_SYSTEM_CONTEXT          SystemContext
  50   );
  51
  52 /**
  53   Register Handler for the specified interrupt source.
  54
  55   @param This     Instance pointer for this protocol
  56   @param Source   Hardware source of the interrupt
  57   @param Handler  Callback for interrupt. NULL to unregister
  58
  59   @retval EFI_SUCCESS Source was updated to support Handler.
  60   @retval EFI_DEVICE_ERROR  Hardware could not be programmed.
  61
  62 **/
  63 typedef
  64 EFI_STATUS
  65 (EFIAPI *HARDWARE_INTERRUPT_REGISTER)(
  66   IN EFI_HARDWARE_INTERRUPT_PROTOCOL    *This,
  67   IN HARDWARE_INTERRUPT_SOURCE          Source,
  68   IN HARDWARE_INTERRUPT_HANDLER         Handler
  69   );
  70
  71 /**
  72   Enable interrupt source Source.
  73
  74   @param This     Instance pointer for this protocol
  75   @param Source   Hardware source of the interrupt
  76
  77   @retval EFI_SUCCESS       Source interrupt enabled.
  78   @retval EFI_DEVICE_ERROR  Hardware could not be programmed.
  79
  80 **/
  81 typedef
  82 EFI_STATUS
  83 (EFIAPI *HARDWARE_INTERRUPT_ENABLE)(
  84   IN EFI_HARDWARE_INTERRUPT_PROTOCOL    *This,
  85   IN HARDWARE_INTERRUPT_SOURCE          Source
  86   );
  87
  88 /**
  89   Disable interrupt source Source.
  90
  91   @param This     Instance pointer for this protocol
  92   @param Source   Hardware source of the interrupt
  93
  94   @retval EFI_SUCCESS       Source interrupt disabled.
  95   @retval EFI_DEVICE_ERROR  Hardware could not be programmed.
  96
  97 **/
  98 typedef
  99 EFI_STATUS
 100 (EFIAPI *HARDWARE_INTERRUPT_DISABLE)(
 101   IN EFI_HARDWARE_INTERRUPT_PROTOCOL    *This,
 102   IN HARDWARE_INTERRUPT_SOURCE          Source
 103   );
 104
 105 /**
 106   Return current state of interrupt source Source.
 107
 108   @param This     Instance pointer for this protocol
 109   @param Source   Hardware source of the interrupt
 110   @param InterruptState  TRUE: source enabled, FALSE: source disabled.
 111
 112   @retval EFI_SUCCESS       InterruptState is valid
 113   @retval EFI_DEVICE_ERROR  InterruptState is not valid
 114
 115 **/
 116 typedef
 117 EFI_STATUS
 118 (EFIAPI *HARDWARE_INTERRUPT_INTERRUPT_STATE)(
 119   IN EFI_HARDWARE_INTERRUPT_PROTOCOL    *This,
 120   IN HARDWARE_INTERRUPT_SOURCE          Source,
 121   IN BOOLEAN                            *InterruptState
 122   );
 123
 124 /**
 125   Signal to the hardware that the End Of Interrupt state
 126   has been reached.
 127
 128   @param This     Instance pointer for this protocol
 129   @param Source   Hardware source of the interrupt
 130
 131   @retval EFI_SUCCESS       Source interrupt EOI'ed.
 132   @retval EFI_DEVICE_ERROR  Hardware could not be programmed.
 133
 134 **/
 135 typedef
 136 EFI_STATUS
 137 (EFIAPI *HARDWARE_INTERRUPT_END_OF_INTERRUPT)(
 138   IN EFI_HARDWARE_INTERRUPT_PROTOCOL    *This,
 139   IN HARDWARE_INTERRUPT_SOURCE          Source
 140   );
 141
 142 struct _EFI_HARDWARE_INTERRUPT_PROTOCOL {
 143   HARDWARE_INTERRUPT_REGISTER            RegisterInterruptSource;
 144   HARDWARE_INTERRUPT_ENABLE              EnableInterruptSource;
 145   HARDWARE_INTERRUPT_DISABLE             DisableInterruptSource;
 146   HARDWARE_INTERRUPT_INTERRUPT_STATE     GetInterruptSourceState;
 147   HARDWARE_INTERRUPT_END_OF_INTERRUPT    EndOfInterrupt;
 148 };
 149
 150 extern EFI_GUID  gHardwareInterruptProtocolGuid;
 151
 152 #endif