MdePkg/Include/Protocol/AcpiTable.h

   1 /** @file
   2   The file provides the protocol to install or remove an ACPI
   3   table from a platform.
   4
   5   Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
   6   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   @par Revision Reference:
  15   This Protocol was introduced in UEFI Specification 2.3.
  16
  17 **/
  18
  19 #ifndef __ACPI_TABLE_H___
  20 #define __ACPI_TABLE_H___
  21
  22 #define EFI_ACPI_TABLE_PROTOCOL_GUID \
  23   { 0xffe06bdd, 0x6107, 0x46a6, { 0x7b, 0xb2, 0x5a, 0x9c, 0x7e, 0xc5, 0x27, 0x5c }}
  24
  25
  26 typedef struct _EFI_ACPI_TABLE_PROTOCOL EFI_ACPI_TABLE_PROTOCOL;
  27
  28 /**
  29
  30   The InstallAcpiTable() function allows a caller to install an
  31   ACPI table. When successful, the table will be linked by the
  32   RSDT/XSDT. AcpiTableBuffer specifies the table to be installed.
  33   InstallAcpiTable() will make a copy of the table and insert the
  34   copy into the RSDT/XSDT. InstallAcpiTable() must insert the new
  35   table at the end of the RSDT/XSDT. To prevent namespace
  36   collision, ACPI tables may be created using UEFI ACPI table
  37   format. If this protocol is used to install a table with a
  38   signature already present in the system, the new table will not
  39   replace the existing table. It is a platform implementation
  40   decision to add a new table with a signature matching an
  41   existing table or disallow duplicate table signatures and
  42   return EFI_ACCESS_DENIED. On successful output, TableKey is
  43   initialized with a unique key. Its value may be used in a
  44   subsequent call to UninstallAcpiTable to remove an ACPI table.
  45   If an EFI application is running at the time of this call, the
  46   relevant EFI_CONFIGURATION_TABLE pointer to the RSDT is no
  47   longer considered valid.
  48
  49
  50   @param This                 A pointer to a EFI_ACPI_TABLE_PROTOCOL.
  51
  52   @param AcpiTableBuffer      A pointer to a buffer containing the
  53                               ACPI table to be installed.
  54
  55   @param AcpiTableBufferSize  Specifies the size, in bytes, of
  56                               the AcpiTableBuffer buffer.
  57
  58
  59   @param TableKey             Returns a key to refer to the ACPI table.
  60
  61   @retval EFI_SUCCESS           The table was successfully inserted
  62
  63   @retval EFI_INVALID_PARAMETER Either AcpiTableBuffer is NULL,
  64                                 TableKey is NULL, or
  65                                 AcpiTableBufferSize and the size
  66                                 field embedded in the ACPI table
  67                                 pointed to by AcpiTableBuffer
  68                                 are not in sync.
  69
  70   @retval EFI_OUT_OF_RESOURCES  Insufficient resources exist to
  71                                 complete the request.
  72   @retval EFI_ACCESS_DENIED     The table signature matches a table already
  73                                 present in the system and platform policy
  74                                 does not allow duplicate tables of this type.
  75
  76 **/
  77 typedef
  78 EFI_STATUS
  79 (EFIAPI *EFI_ACPI_TABLE_INSTALL_ACPI_TABLE)(
  80   IN   EFI_ACPI_TABLE_PROTOCOL       *This,
  81   IN   VOID                          *AcpiTableBuffer,
  82   IN   UINTN                         AcpiTableBufferSize,
  83   OUT  UINTN                         *TableKey
  84 );
  85
  86
  87 /**
  88
  89   The UninstallAcpiTable() function allows a caller to remove an
  90   ACPI table. The routine will remove its reference from the
  91   RSDT/XSDT. A table is referenced by the TableKey parameter
  92   returned from a prior call to InstallAcpiTable(). If an EFI
  93   application is running at the time of this call, the relevant
  94   EFI_CONFIGURATION_TABLE pointer to the RSDT is no longer
  95   considered valid.
  96
  97   @param This                   A pointer to a EFI_ACPI_TABLE_PROTOCOL.
  98
  99   @param TableKey               Specifies the table to uninstall. The key was
 100                                 returned from InstallAcpiTable().
 101
 102   @retval EFI_SUCCESS           The table was successfully inserted
 103
 104   @retval EFI_NOT_FOUND         TableKey does not refer to a valid key
 105                                 for a table entry.
 106
 107   @retval EFI_OUT_OF_RESOURCES  Insufficient resources exist to
 108                                 complete the request.
 109
 110 **/
 111 typedef
 112 EFI_STATUS
 113 (EFIAPI *EFI_ACPI_TABLE_UNINSTALL_ACPI_TABLE)(
 114   IN  EFI_ACPI_TABLE_PROTOCOL       *This,
 115   IN  UINTN                         TableKey
 116 );
 117
 118 ///
 119 /// The EFI_ACPI_TABLE_PROTOCOL provides the ability for a component
 120 /// to install and uninstall ACPI tables from a platform.
 121 ///
 122 struct _EFI_ACPI_TABLE_PROTOCOL {
 123   EFI_ACPI_TABLE_INSTALL_ACPI_TABLE   InstallAcpiTable;
 124   EFI_ACPI_TABLE_UNINSTALL_ACPI_TABLE UninstallAcpiTable;
 125 };
 126
 127 extern EFI_GUID gEfiAcpiTableProtocolGuid;
 128
 129 #endif
 130