MdePkg/Include/Protocol/AcpiSystemDescriptionTable.h

   1 /** @file
   2   This protocol provides services for creating ACPI system description tables.
   3
   4   Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR>
   5   This program and the accompanying materials
   6   are licensed and made available under the terms and conditions of the BSD License
   7   which accompanies this distribution.  The full text of the license may be found at
   8   http://opensource.org/licenses/bsd-license.php
   9
  10   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13   This does not follow public spec.
  14
  15 **/
  16
  17 #ifndef __ACPI_SYSTEM_DESCRIPTION_TABLE_H___
  18 #define __ACPI_SYSTEM_DESCRIPTION_TABLE_H___
  19
  20 #define EFI_ACPI_SDT_PROTOCOL_GUID \
  21   { 0xeb97088e, 0xcfdf, 0x49c6, { 0xbe, 0x4b, 0xd9, 0x6, 0xa5, 0xb2, 0xe, 0x86 }}
  22
  23 typedef UINT32  EFI_ACPI_TABLE_VERSION;
  24 typedef VOID    *EFI_ACPI_HANDLE;
  25
  26 #define EFI_ACPI_TABLE_VERSION_NONE (1 << 0)
  27 #define EFI_ACPI_TABLE_VERSION_1_0B (1 << 1)
  28 #define EFI_ACPI_TABLE_VERSION_2_0  (1 << 2)
  29 #define EFI_ACPI_TABLE_VERSION_3_0  (1 << 3)
  30 #define EFI_ACPI_TABLE_VERSION_4_0  (1 << 4)
  31
  32 typedef UINT32 EFI_ACPI_DATA_TYPE;
  33 #define EFI_ACPI_DATA_TYPE_NONE         0
  34 #define EFI_ACPI_DATA_TYPE_OPCODE       1
  35 #define EFI_ACPI_DATA_TYPE_NAME_STRING  2
  36 #define EFI_ACPI_DATA_TYPE_OP           3
  37 #define EFI_ACPI_DATA_TYPE_UINT         4
  38 #define EFI_ACPI_DATA_TYPE_STRING       5
  39 #define EFI_ACPI_DATA_TYPE_CHILD        6
  40
  41 typedef struct {
  42   UINT32    Signature;
  43   UINT32    Length;
  44   UINT8     Revision;
  45   UINT8     Checksum;
  46   CHAR8     OemId[6];
  47   CHAR8     OemTableId[8];
  48   UINT32    OemRevision;
  49   UINT32    CreatorId;
  50   UINT32    CreatorRevision;
  51 } EFI_ACPI_SDT_HEADER;
  52
  53 typedef
  54 EFI_STATUS
  55 (EFIAPI *EFI_ACPI_NOTIFICATION_FN)(
  56   IN EFI_ACPI_SDT_HEADER    *Table,     ///< A pointer to the ACPI table header.
  57   IN EFI_ACPI_TABLE_VERSION Version,    ///< The ACPI table's version.
  58   IN UINTN                  TableKey    ///< The table key for this ACPI table.
  59 );
  60
  61 /**
  62   Returns a requested ACPI table.
  63
  64   The GetAcpiTable() function returns a pointer to a buffer containing the ACPI table associated
  65   with the Index that was input. The following structures are not considered elements in the list of
  66   ACPI tables:
  67   - Root System Description Pointer (RSD_PTR)
  68   - Root System Description Table (RSDT)
  69   - Extended System Description Table (XSDT)
  70   Version is updated with a bit map containing all the versions of ACPI of which the table is a
  71   member.
  72
  73   @param[in]    Index       The zero-based index of the table to retrieve.
  74   @param[out]   Table       Pointer for returning the table buffer.
  75   @param[out]   Version     On return, updated with the ACPI versions to which this table belongs. Type
  76                             EFI_ACPI_TABLE_VERSION is defined in "Related Definitions" in the
  77                             EFI_ACPI_SDT_PROTOCOL.
  78   @param[out]   TableKey    On return, points to the table key for the specified ACPI system definition table. This
  79                             is identical to the table key used in the EFI_ACPI_TABLE_PROTOCOL.
  80
  81   @retval EFI_SUCCESS       The function completed successfully.
  82   @retval EFI_NOT_FOUND     The requested index is too large and a table was not found.
  83 **/
  84 typedef
  85 EFI_STATUS
  86 (EFIAPI *EFI_ACPI_GET_ACPI_TABLE2)(
  87   IN    UINTN                   Index,
  88   OUT   EFI_ACPI_SDT_HEADER     **Table,
  89   OUT   EFI_ACPI_TABLE_VERSION  *Version,
  90   OUT   UINTN                   *TableKey
  91 );
  92
  93 /**
  94   Register or unregister a callback when an ACPI table is installed.
  95
  96   This function registers or unregisters a function which will be called whenever a new ACPI table is
  97   installed.
  98
  99   @param[in]    Register        If TRUE, then the specified function will be registered. If FALSE, then the specified
 100                                 function will be unregistered.
 101   @param[in]    Notification    Points to the callback function to be registered or unregistered.
 102
 103   @retval EFI_SUCCESS           Callback successfully registered or unregistered.
 104   @retval EFI_INVALID_PARAMETER Notification is NULL
 105   @retval EFI_INVALID_PARAMETER Register is FALSE and Notification does not match a known registration function.
 106 **/
 107 typedef
 108 EFI_STATUS
 109 (EFIAPI *EFI_ACPI_REGISTER_NOTIFY)(
 110   IN BOOLEAN                    Register,
 111   IN EFI_ACPI_NOTIFICATION_FN   Notification
 112 );
 113
 114 /**
 115   Create a handle from an ACPI opcode
 116
 117   @param[in]  Buffer                 Points to the ACPI opcode.
 118   @param[out] Handle                 Upon return, holds the handle.
 119
 120   @retval   EFI_SUCCESS             Success
 121   @retval   EFI_INVALID_PARAMETER   Buffer is NULL or Handle is NULL or Buffer points to an
 122                                     invalid opcode.
 123
 124 **/
 125 typedef
 126 EFI_STATUS
 127 (EFIAPI *EFI_ACPI_OPEN)(
 128   IN    VOID            *Buffer,
 129   OUT   EFI_ACPI_HANDLE *Handle
 130 );
 131
 132 /**
 133   Create a handle for the first ACPI opcode in an ACPI system description table.
 134
 135   @param[in]    TableKey    The table key for the ACPI table, as returned by GetTable().
 136   @param[out]   Handle      On return, points to the newly created ACPI handle.
 137
 138   @retval EFI_SUCCESS       Handle created successfully.
 139   @retval EFI_NOT_FOUND     TableKey does not refer to a valid ACPI table.
 140 **/
 141 typedef
 142 EFI_STATUS
 143 (EFIAPI *EFI_ACPI_OPEN_SDT)(
 144   IN    UINTN           TableKey,
 145   OUT   EFI_ACPI_HANDLE *Handle
 146 );
 147
 148 /**
 149   Close an ACPI handle.
 150
 151   @param[in] Handle Returns the handle.
 152
 153   @retval EFI_SUCCESS           Success
 154   @retval EFI_INVALID_PARAMETER Handle is NULL or does not refer to a valid ACPI object.
 155 **/
 156 typedef
 157 EFI_STATUS
 158 (EFIAPI *EFI_ACPI_CLOSE)(
 159   IN EFI_ACPI_HANDLE Handle
 160 );
 161
 162 /**
 163   Return the child ACPI objects.
 164
 165   @param[in]        ParentHandle    Parent handle.
 166   @param[in, out]   Handle          On entry, points to the previously returned handle or NULL to start with the first
 167                                     handle. On return, points to the next returned ACPI handle or NULL if there are no
 168                                     child objects.
 169
 170   @retval EFI_SUCCESS               Success
 171   @retval EFI_INVALID_PARAMETER     ParentHandle is NULL or does not refer to a valid ACPI object.
 172 **/
 173 typedef
 174 EFI_STATUS
 175 (EFIAPI *EFI_ACPI_GET_CHILD)(
 176   IN EFI_ACPI_HANDLE        ParentHandle,
 177   IN OUT EFI_ACPI_HANDLE    *Handle
 178 );
 179
 180 /**
 181   Retrieve information about an ACPI object.
 182
 183   @param[in]    Handle      ACPI object handle.
 184   @param[in]    Index       Index of the data to retrieve from the object. In general, indexes read from left-to-right
 185                             in the ACPI encoding, with index 0 always being the ACPI opcode.
 186   @param[out]   DataType    Points to the returned data type or EFI_ACPI_DATA_TYPE_NONE if no data exists
 187                             for the specified index.
 188   @param[out]   Data        Upon return, points to the pointer to the data.
 189   @param[out]   DataSize    Upon return, points to the size of Data.
 190
 191   @retval
 192 **/
 193 typedef
 194 EFI_STATUS
 195 (EFIAPI *EFI_ACPI_GET_OPTION)(
 196   IN        EFI_ACPI_HANDLE     Handle,
 197   IN        UINTN               Index,
 198   OUT       EFI_ACPI_DATA_TYPE  *DataType,
 199   OUT CONST VOID                **Data,
 200   OUT       UINTN               *DataSize
 201 );
 202
 203 /**
 204   Change information about an ACPI object.
 205
 206   @param[in]  Handle    ACPI object handle.
 207   @param[in]  Index     Index of the data to retrieve from the object. In general, indexes read from left-to-right
 208                         in the ACPI encoding, with index 0 always being the ACPI opcode.
 209   @param[in]  Data      Points to the data.
 210   @param[in]  DataSize  The size of the Data.
 211
 212   @retval EFI_SUCCESS           Success
 213   @retval EFI_INVALID_PARAMETER Handle is NULL or does not refer to a valid ACPI object.
 214   @retval EFI_BAD_BUFFER_SIZE   Data cannot be accommodated in the space occupied by
 215                                 the option.
 216
 217 **/
 218 typedef
 219 EFI_STATUS
 220 (EFIAPI *EFI_ACPI_SET_OPTION)(
 221   IN        EFI_ACPI_HANDLE Handle,
 222   IN        UINTN           Index,
 223   IN CONST  VOID            *Data,
 224   IN        UINTN           DataSize
 225 );
 226
 227 /**
 228   Returns the handle of the ACPI object representing the specified ACPI path
 229
 230   @param[in]    HandleIn    Points to the handle of the object representing the starting point for the path search.
 231   @param[in]    AcpiPath    Points to the ACPI path, which conforms to the ACPI encoded path format.
 232   @param[out]   HandleOut   On return, points to the ACPI object which represents AcpiPath, relative to
 233                             HandleIn.
 234
 235   @retval EFI_SUCCESS           Success
 236   @retval EFI_INVALID_PARAMETER HandleIn is NULL or does not refer to a valid ACPI object.
 237 **/
 238 typedef
 239 EFI_STATUS
 240 (EFIAPI *EFI_ACPI_FIND_PATH)(
 241   IN    EFI_ACPI_HANDLE HandleIn,
 242   IN    VOID            *AcpiPath,
 243   OUT   EFI_ACPI_HANDLE *HandleOut
 244 );
 245
 246 typedef struct _EFI_ACPI_SDT_PROTOCOL {
 247   ///
 248   /// Specifies the ACPI version supported by this protocol.
 249   ///
 250   EFI_ACPI_TABLE_VERSION    AcpiVersion;
 251   EFI_ACPI_GET_ACPI_TABLE2  GetAcpiTable;
 252   EFI_ACPI_REGISTER_NOTIFY  RegisterNotify;
 253   EFI_ACPI_OPEN             Open;
 254   EFI_ACPI_OPEN_SDT         OpenSdt;
 255   EFI_ACPI_CLOSE            Close;
 256   EFI_ACPI_GET_CHILD        GetChild;
 257   EFI_ACPI_GET_OPTION       GetOption;
 258   EFI_ACPI_SET_OPTION       SetOption;
 259   EFI_ACPI_FIND_PATH        FindPath;
 260 } EFI_ACPI_SDT_PROTOCOL;
 261
 262 extern EFI_GUID gEfiAcpiSdtProtocolGuid;
 263
 264 #endif // __ACPI_SYSTEM_DESCRIPTION_TABLE_H___