[mirror_edk2.git] / DynamicTablesPkg / Include / Library / AmlLib / AmlLib.h

/** @file\r
  AML Lib.\r
\r
  Copyright (c) 2019 - 2021, Arm Limited. All rights reserved.<BR>\r
\r
  SPDX-License-Identifier: BSD-2-Clause-Patent\r
**/\r
\r
#ifndef AML_LIB_H_\r
#define AML_LIB_H_\r
\r
/**\r
  @mainpage Dynamic AML Generation\r
  @{\r
    @par Summary\r
    @{\r
    ACPI tables are categorized as data tables and definition block\r
    tables. Dynamic Tables Framework currently supports generation of ACPI\r
    data tables. Generation of definition block tables is difficult as these\r
    tables are encoded in ACPI Machine Language (AML), which has a complex\r
    grammar.\r
\r
    Dynamic AML Generation is an extension to the Dynamic tables Framework.\r
    One of the techniques used to simplify definition block generation is to\r
    fixup a template SSDT table.\r
\r
    Dynamic AML aims to provide a framework that allows fixing up of an ACPI\r
    SSDT template with appropriate information about the hardware.\r
\r
    This framework consists of an:\r
    - AMLLib core that implements a rich set of interfaces to parse, traverse\r
      and update AML data.\r
    - AMLLib library APIs that provides interfaces to search and updates nodes\r
      in the AML namespace.\r
    @}\r
  @}\r
*/\r
\r
#include <IndustryStandard/Acpi.h>\r
\r
#ifndef AML_HANDLE\r
\r
/** Node handle.\r
*/\r
typedef void* AML_NODE_HANDLE;\r
\r
/** Root Node handle.\r
*/\r
typedef void* AML_ROOT_NODE_HANDLE;\r
\r
/** Object Node handle.\r
*/\r
typedef void* AML_OBJECT_NODE_HANDLE;\r
\r
/** Data Node handle.\r
*/\r
typedef void* AML_DATA_NODE_HANDLE;\r
\r
#endif // AML_HANDLE\r
\r
/** Parse the definition block.\r
\r
  The function parses the whole AML blob. It starts with the ACPI DSDT/SSDT\r
  header and then parses the AML bytestream.\r
  A tree structure is returned via the RootPtr.\r
  The tree must be deleted with the AmlDeleteTree function.\r
\r
  @ingroup UserApis\r
\r
  @param  [in]  DefinitionBlock   Pointer to the definition block.\r
  @param  [out] RootPtr           Pointer to the root node of the AML tree.\r
\r
  @retval EFI_SUCCESS             The function completed successfully.\r
  @retval EFI_BUFFER_TOO_SMALL    No space left in the buffer.\r
  @retval EFI_INVALID_PARAMETER   Invalid parameter.\r
  @retval EFI_OUT_OF_RESOURCES    Could not allocate memory.\r
**/\r
EFI_STATUS\r
EFIAPI\r
AmlParseDefinitionBlock (\r
  IN  CONST EFI_ACPI_DESCRIPTION_HEADER   * DefinitionBlock,\r
  OUT       AML_ROOT_NODE_HANDLE          * RootPtr\r
  );\r
\r
/** Serialize an AML definition block.\r
\r
  This functions allocates memory with the "AllocateZeroPool ()"\r
  function. This memory is used to serialize the AML tree and is\r
  returned in the Table.\r
\r
  @ingroup UserApis\r
\r
  @param [in]  RootNode         Root node of the tree.\r
  @param [out] Table            On return, hold the serialized\r
                                definition block.\r
\r
  @retval EFI_SUCCESS            The function completed successfully.\r
  @retval EFI_INVALID_PARAMETER  Invalid parameter.\r
  @retval EFI_OUT_OF_RESOURCES   Could not allocate memory.\r
**/\r
EFI_STATUS\r
EFIAPI\r
AmlSerializeDefinitionBlock (\r
  IN  AML_ROOT_NODE_HANDLE              RootNode,\r
  OUT EFI_ACPI_DESCRIPTION_HEADER    ** Table\r
  );\r
\r
/** Clone a node and its children (clone a tree branch).\r
\r
  The cloned branch returned is not attached to any tree.\r
\r
  @ingroup UserApis\r
\r
  @param  [in]  Node        Pointer to a node.\r
                            Node is the head of the branch to clone.\r
  @param  [out] ClonedNode  Pointer holding the head of the created cloned\r
                            branch.\r
\r
  @retval EFI_SUCCESS             The function completed successfully.\r
  @retval EFI_INVALID_PARAMETER   Invalid parameter.\r
  @retval EFI_OUT_OF_RESOURCES    Could not allocate memory.\r
**/\r
EFI_STATUS\r
EFIAPI\r
AmlCloneTree (\r
  IN  AML_NODE_HANDLE   Node,\r
  OUT AML_NODE_HANDLE * ClonedNode\r
  );\r
\r
/** Delete a Node and its children.\r
\r
  The Node must be removed from the tree first,\r
  or must be the root node.\r
\r
  @ingroup UserApis\r
\r
  @param  [in]  Node  Pointer to the node to delete.\r
\r
  @retval EFI_SUCCESS             The function completed successfully.\r
  @retval EFI_INVALID_PARAMETER   Invalid parameter.\r
**/\r
EFI_STATUS\r
EFIAPI\r
AmlDeleteTree (\r
  IN  AML_NODE_HANDLE   Node\r
  );\r
\r
/** Detach the Node from the tree.\r
\r
  The function will fail if the Node is in its parent's fixed\r
  argument list.\r
  The Node is not deleted. The deletion is done separately\r
  from the removal.\r
\r
  @ingroup UserApis\r
\r
  @param  [in]  Node  Pointer to a Node.\r
                      Must be a data node or an object node.\r
\r
  @retval EFI_SUCCESS             The function completed successfully.\r
  @retval EFI_INVALID_PARAMETER   Invalid parameter.\r
**/\r
EFI_STATUS\r
EFIAPI\r
AmlDetachNode (\r
  IN  AML_NODE_HANDLE   Node\r
  );\r
\r
/** Find a node in the AML namespace, given an ASL path and a reference Node.\r
\r
   - The AslPath can be an absolute path, or a relative path from the\r
     reference Node;\r
   - Node must be a root node or a namespace node;\r
   - A root node is expected to be at the top of the tree.\r
\r
  E.g.:\r
  For the following AML namespace, with the ReferenceNode being the node with\r
  the name "AAAA":\r
   - the node with the name "BBBB" can be found by looking for the ASL\r
     path "BBBB";\r
   - the root node can be found by looking for the ASL relative path "^",\r
      or the absolute path "\\".\r
\r
  AML namespace:\r
  \\r
  \-AAAA      <- ReferenceNode\r
    \-BBBB\r
\r
  @ingroup NameSpaceApis\r
\r
  @param  [in]  ReferenceNode   Reference node.\r
                                If a relative path is given, the\r
                                search is done from this node. If\r
                                an absolute path is given, the\r
                                search is done from the root node.\r
                                Must be a root node or an object\r
                                node which is part of the\r
                                namespace.\r
  @param  [in]  AslPath         ASL path to the searched node in\r
                                the namespace. An ASL path name is\r
                                NULL terminated. Can be a relative\r
                                or absolute path.\r
                                E.g.: "\\_SB.CLU0.CPU0" or "^CPU0"\r
  @param  [out] OutNode         Pointer to the found node.\r
                                Contains NULL if not found.\r
\r
  @retval EFI_SUCCESS             The function completed successfully.\r
  @retval EFI_BUFFER_TOO_SMALL    No space left in the buffer.\r
  @retval EFI_INVALID_PARAMETER   Invalid parameter.\r
  @retval EFI_OUT_OF_RESOURCES    Out of memory.\r
**/\r
EFI_STATUS\r
EFIAPI\r
AmlFindNode (\r
  IN  AML_NODE_HANDLE       ReferenceNode,\r
  IN  CHAR8               * AslPath,\r
  OUT AML_NODE_HANDLE     * OutNode\r
  );\r
\r
/**\r
  @defgroup UserApis User APIs\r
  @{\r
    User APIs are implemented to ease most common actions that might be done\r
    using the AmlLib. They allow to find specific objects like "_UID" or\r
    "_CRS" and to update their value. It also shows what can be done using\r
    AmlLib functions.\r
  @}\r
*/\r
\r
/** Update the name of a DeviceOp object node.\r
\r
  @ingroup UserApis\r
\r
  @param  [in] DeviceOpNode   Object node representing a Device.\r
                              Must have an OpCode=AML_NAME_OP, SubOpCode=0.\r
                              OpCode/SubOpCode.\r
                              DeviceOp object nodes are defined in ASL\r
                              using the "Device ()" function.\r
  @param  [in] NewNameString  The new Device's name.\r
                              Must be a NULL-terminated ASL NameString\r
                              e.g.: "DEV0", "DV15.DEV0", etc.\r
                              The input string is copied.\r
\r
  @retval EFI_SUCCESS             The function completed successfully.\r
  @retval EFI_INVALID_PARAMETER   Invalid parameter.\r
**/\r
EFI_STATUS\r
EFIAPI\r
AmlDeviceOpUpdateName (\r
  IN  AML_OBJECT_NODE_HANDLE    DeviceOpNode,\r
  IN  CHAR8                   * NewNameString\r
  );\r
\r
/** Update an integer value defined by a NameOp object node.\r
\r
  For compatibility reasons, the NameOpNode must initially\r
  contain an integer.\r
\r
  @ingroup UserApis\r
\r
  @param  [in] NameOpNode   NameOp object node.\r
                            Must have an OpCode=AML_NAME_OP, SubOpCode=0.\r
                            NameOp object nodes are defined in ASL\r
                            using the "Name ()" function.\r
  @param  [in] NewInt       New Integer value to assign.\r
                            Must be a UINT64.\r
\r
  @retval EFI_SUCCESS             The function completed successfully.\r
  @retval EFI_INVALID_PARAMETER   Invalid parameter.\r
**/\r
EFI_STATUS\r
EFIAPI\r
AmlNameOpUpdateInteger (\r
  IN  AML_OBJECT_NODE_HANDLE  NameOpNode,\r
  IN  UINT64                  NewInt\r
  );\r
\r
/** Update a string value defined by a NameOp object node.\r
\r
  The NameOpNode must initially contain a string.\r
  The EISAID ASL macro converts a string to an integer. This, it is\r
  not accepted.\r
\r
  @ingroup UserApis\r
\r
  @param  [in] NameOpNode   NameOp object node.\r
                            Must have an OpCode=AML_NAME_OP, SubOpCode=0.\r
                            NameOp object nodes are defined in ASL\r
                            using the "Name ()" function.\r
  @param  [in] NewName      New NULL terminated string to assign to\r
                            the NameOpNode.\r
                            The input string is copied.\r
\r
  @retval EFI_SUCCESS             The function completed successfully.\r
  @retval EFI_INVALID_PARAMETER   Invalid parameter.\r
**/\r
EFI_STATUS\r
EFIAPI\r
AmlNameOpUpdateString (\r
  IN        AML_OBJECT_NODE_HANDLE    NameOpNode,\r
  IN  CONST CHAR8                   * NewName\r
  );\r
\r
/** Get the first Resource Data element contained in a named object.\r
\r
  In the following ASL code, the function will return the Resource Data\r
  node corresponding to the "QWordMemory ()" ASL macro.\r
  Name (_CRS, ResourceTemplate() {\r
      QWordMemory (...) {...},\r
      Interrupt (...) {...}\r
    }\r
  )\r
\r
  Note:\r
  "_CRS" names defined as methods are not handled by this function.\r
  They must be defined as names, using the "Name ()" statement.\r
\r
  @ingroup UserApis\r
\r
  @param  [in] NameOpNode   NameOp object node defining a named object.\r
                            Must have an OpCode=AML_NAME_OP, SubOpCode=0.\r
                            NameOp object nodes are defined in ASL\r
                            using the "Name ()" function.\r
  @param  [out] OutRdNode   Pointer to the first Resource Data element of\r
                            the named object. A Resource Data element\r
                            is stored in a data node.\r
\r
  @retval EFI_SUCCESS             The function completed successfully.\r
  @retval EFI_INVALID_PARAMETER   Invalid parameter.\r
**/\r
EFI_STATUS\r
EFIAPI\r
AmlNameOpGetFirstRdNode (\r
  IN  AML_OBJECT_NODE_HANDLE   NameOpNode,\r
  OUT AML_DATA_NODE_HANDLE   * OutRdNode\r
  );\r
\r
/** Get the Resource Data element following the CurrRdNode Resource Data.\r
\r
  In the following ASL code, if CurrRdNode corresponds to the first\r
  "QWordMemory ()" ASL macro, the function will return the Resource Data\r
  node corresponding to the "Interrupt ()" ASL macro.\r
  Name (_CRS, ResourceTemplate() {\r
      QwordMemory (...) {...},\r
      Interrupt (...) {...}\r
    }\r
  )\r
\r
  Note:\r
  "_CRS" names defined as methods are not handled by this function.\r
  They must be defined as names, using the "Name ()" statement.\r
\r
  @ingroup UserApis\r
\r
  @param  [in]  CurrRdNode   Pointer to the current Resource Data element of\r
                             the named object.\r
  @param  [out] OutRdNode    Pointer to the Resource Data element following\r
                             the CurrRdNode.\r
                             Contain a NULL pointer if CurrRdNode is the\r
                             last Resource Data element in the list.\r
                             The "End Tag" is not considered as a resource\r
                             data element and is not returned.\r
\r
  @retval EFI_SUCCESS             The function completed successfully.\r
  @retval EFI_INVALID_PARAMETER   Invalid parameter.\r
**/\r
EFI_STATUS\r
EFIAPI\r
AmlNameOpGetNextRdNode (\r
  IN  AML_DATA_NODE_HANDLE    CurrRdNode,\r
  OUT AML_DATA_NODE_HANDLE  * OutRdNode\r
  );\r
\r
/** Update the first interrupt of an Interrupt resource data node.\r
\r
  The flags of the Interrupt resource data are left unchanged.\r
\r
  The InterruptRdNode corresponds to the Resource Data created by the\r
  "Interrupt ()" ASL macro. It is an Extended Interrupt Resource Data.\r
  See ACPI 6.3 specification, s6.4.3.6 "Extended Interrupt Descriptor"\r
  for more information about Extended Interrupt Resource Data.\r
\r
  @ingroup UserApis\r
\r
  @param  [in]  InterruptRdNode   Pointer to the an extended interrupt\r
                                  resource data node.\r
  @param  [in]  Irq               Interrupt value to update.\r
\r
  @retval  EFI_SUCCESS            The function completed successfully.\r
  @retval  EFI_INVALID_PARAMETER  Invalid parameter.\r
  @retval  EFI_OUT_OF_RESOURCES   Out of resources.\r
**/\r
EFI_STATUS\r
EFIAPI\r
AmlUpdateRdInterrupt (\r
  IN  AML_DATA_NODE_HANDLE    InterruptRdNode,\r
  IN  UINT32                  Irq\r
  );\r
\r
/** Update the base address and length of a QWord resource data node.\r
\r
  @ingroup UserApis\r
\r
  @param  [in] QWordRdNode         Pointer a QWord resource data\r
                                   node.\r
  @param  [in] BaseAddress         Base address.\r
  @param  [in] BaseAddressLength   Base address length.\r
\r
  @retval  EFI_SUCCESS            The function completed successfully.\r
  @retval  EFI_INVALID_PARAMETER  Invalid parameter.\r
  @retval  EFI_OUT_OF_RESOURCES   Out of resources.\r
**/\r
EFI_STATUS\r
EFIAPI\r
AmlUpdateRdQWord (\r
  IN  AML_DATA_NODE_HANDLE  QWordRdNode,\r
  IN  UINT64                BaseAddress,\r
  IN  UINT64                BaseAddressLength\r
  );\r
\r
/** Code generation for the "Interrupt ()" ASL function.\r
\r
  The Resource Data effectively created is an Extended Interrupt Resource\r
  Data. Cf ACPI 6.4:\r
   - s6.4.3.6 "Extended Interrupt Descriptor"\r
   - s19.6.64 "Interrupt (Interrupt Resource Descriptor Macro)"\r
\r
  The created resource data node can be:\r
   - appended to the list of resource data elements of the NameOpNode.\r
     In such case NameOpNode must be defined by a the "Name ()" ASL statement\r
     and initially contain a "ResourceTemplate ()".\r
   - returned through the NewRdNode parameter.\r
\r
  @ingroup CodeGenApis\r
\r
  @param  [in]  ResourceConsumer The device consumes the specified interrupt\r
                                 or produces it for use by a child device.\r
  @param  [in]  EdgeTriggered    The interrupt is edge triggered or\r
                                 level triggered.\r
  @param  [in]  ActiveLow        The interrupt is active-high or active-low.\r
  @param  [in]  Shared           The interrupt can be shared with other\r
                                 devices or not (Exclusive).\r
  @param  [in]  IrqList          Interrupt list. Must be non-NULL.\r
  @param  [in]  IrqCount         Interrupt count. Must be non-zero.\r
  @param  [in]  NameOpNode       NameOp object node defining a named object.\r
                                 If provided, append the new resource data node\r
                                 to the list of resource data elements of this\r
                                 node.\r
  @param  [out] NewRdNode        If provided and success,\r
                                 contain the created node.\r
\r
  @retval EFI_SUCCESS             The function completed successfully.\r
  @retval EFI_INVALID_PARAMETER   Invalid parameter.\r
  @retval EFI_OUT_OF_RESOURCES    Could not allocate memory.\r
**/\r
EFI_STATUS\r
EFIAPI\r
AmlCodeGenRdInterrupt (\r
  IN  BOOLEAN                 ResourceConsumer,\r
  IN  BOOLEAN                 EdgeTriggered,\r
  IN  BOOLEAN                 ActiveLow,\r
  IN  BOOLEAN                 Shared,\r
  IN  UINT32                  *IrqList,\r
  IN  UINT8                   IrqCount,\r
  IN  AML_OBJECT_NODE_HANDLE  NameOpNode  OPTIONAL,\r
  OUT AML_DATA_NODE_HANDLE    *NewRdNode  OPTIONAL\r
  );\r
\r
/** AML code generation for DefinitionBlock.\r
\r
  Create a Root Node handle.\r
  It is the caller's responsibility to free the allocated memory\r
  with the AmlDeleteTree function.\r
\r
  AmlCodeGenDefinitionBlock (TableSignature, OemId, TableID, OEMRevision) is\r
  equivalent to the following ASL code:\r
    DefinitionBlock (AMLFileName, TableSignature, ComplianceRevision,\r
      OemId, TableID, OEMRevision) {}\r
  with the ComplianceRevision set to 2 and the AMLFileName is ignored.\r
\r
  @ingroup CodeGenApis\r
\r
  @param[in]  TableSignature       4-character ACPI signature.\r
                                   Must be 'DSDT' or 'SSDT'.\r
  @param[in]  OemId                6-character string OEM identifier.\r
  @param[in]  OemTableId           8-character string OEM table identifier.\r
  @param[in]  OemRevision          OEM revision number.\r
  @param[out] DefinitionBlockTerm  The ASL Term handle representing a\r
                                   Definition Block.\r
\r
  @retval EFI_SUCCESS             Success.\r
  @retval EFI_INVALID_PARAMETER   Invalid parameter.\r
  @retval EFI_OUT_OF_RESOURCES    Failed to allocate memory.\r
**/\r
EFI_STATUS\r
EFIAPI\r
AmlCodeGenDefinitionBlock (\r
  IN  CONST CHAR8                 * TableSignature,\r
  IN  CONST CHAR8                 * OemId,\r
  IN  CONST CHAR8                 * OemTableId,\r
  IN        UINT32                  OemRevision,\r
  OUT       AML_ROOT_NODE_HANDLE  * NewRootNode\r
  );\r
\r
/** AML code generation for a Name object node, containing a String.\r
\r
  AmlCodeGenNameString ("_HID", "HID0000", ParentNode, NewObjectNode) is\r
  equivalent of the following ASL code:\r
    Name(_HID, "HID0000")\r
\r
  @ingroup CodeGenApis\r
\r
  @param  [in] NameString     The new variable name.\r
                              Must be a NULL-terminated ASL NameString\r
                              e.g.: "DEV0", "DV15.DEV0", etc.\r
                              The input string is copied.\r
  @param [in]  String         NULL terminated String to associate to the\r
                              NameString.\r
  @param [in]  ParentNode     If provided, set ParentNode as the parent\r
                              of the node created.\r
  @param [out] NewObjectNode  If success, contains the created node.\r
\r
  @retval EFI_SUCCESS             Success.\r
  @retval EFI_INVALID_PARAMETER   Invalid parameter.\r
  @retval EFI_OUT_OF_RESOURCES    Failed to allocate memory.\r
**/\r
EFI_STATUS\r
EFIAPI\r
AmlCodeGenNameString (\r
  IN  CONST CHAR8                   * NameString,\r
  IN        CHAR8                   * String,\r
  IN        AML_NODE_HANDLE           ParentNode      OPTIONAL,\r
  OUT       AML_OBJECT_NODE_HANDLE  * NewObjectNode   OPTIONAL\r
  );\r
\r
/** AML code generation for a Name object node, containing an Integer.\r
\r
  AmlCodeGenNameInteger ("_UID", 1, ParentNode, NewObjectNode) is\r
  equivalent of the following ASL code:\r
    Name(_UID, One)\r
\r
  @ingroup CodeGenApis\r
\r
  @param  [in] NameString     The new variable name.\r
                              Must be a NULL-terminated ASL NameString\r
                              e.g.: "DEV0", "DV15.DEV0", etc.\r
                              The input string is copied.\r
  @param [in]  Integer        Integer to associate to the NameString.\r
  @param [in]  ParentNode     If provided, set ParentNode as the parent\r
                              of the node created.\r
  @param [out] NewObjectNode  If success, contains the created node.\r
\r
  @retval EFI_SUCCESS             Success.\r
  @retval EFI_INVALID_PARAMETER   Invalid parameter.\r
  @retval EFI_OUT_OF_RESOURCES    Failed to allocate memory.\r
**/\r
EFI_STATUS\r
EFIAPI\r
AmlCodeGenNameInteger (\r
  IN  CONST CHAR8                   * NameString,\r
  IN        UINT64                    Integer,\r
  IN        AML_NODE_HANDLE           ParentNode      OPTIONAL,\r
  OUT       AML_OBJECT_NODE_HANDLE  * NewObjectNode   OPTIONAL\r
  );\r
\r
/** AML code generation for a Device object node.\r
\r
  AmlCodeGenDevice ("COM0", ParentNode, NewObjectNode) is\r
  equivalent of the following ASL code:\r
    Device(COM0) {}\r
\r
  @ingroup CodeGenApis\r
\r
  @param  [in] NameString     The new Device's name.\r
                              Must be a NULL-terminated ASL NameString\r
                              e.g.: "DEV0", "DV15.DEV0", etc.\r
                              The input string is copied.\r
  @param [in]  ParentNode     If provided, set ParentNode as the parent\r
                              of the node created.\r
  @param [out] NewObjectNode  If success, contains the created node.\r
\r
  @retval EFI_SUCCESS             Success.\r
  @retval EFI_INVALID_PARAMETER   Invalid parameter.\r
  @retval EFI_OUT_OF_RESOURCES    Failed to allocate memory.\r
**/\r
EFI_STATUS\r
EFIAPI\r
AmlCodeGenDevice (\r
  IN  CONST CHAR8                   * NameString,\r
  IN        AML_NODE_HANDLE           ParentNode      OPTIONAL,\r
  OUT       AML_OBJECT_NODE_HANDLE  * NewObjectNode   OPTIONAL\r
  );\r
\r
/** AML code generation for a Scope object node.\r
\r
  AmlCodeGenScope ("_SB", ParentNode, NewObjectNode) is\r
  equivalent of the following ASL code:\r
    Scope(_SB) {}\r
\r
  @ingroup CodeGenApis\r
\r
  @param  [in] NameString     The new Scope's name.\r
                              Must be a NULL-terminated ASL NameString\r
                              e.g.: "DEV0", "DV15.DEV0", etc.\r
                              The input string is copied.\r
  @param [in]  ParentNode     If provided, set ParentNode as the parent\r
                              of the node created.\r
  @param [out] NewObjectNode  If success, contains the created node.\r
\r
  @retval EFI_SUCCESS             Success.\r
  @retval EFI_INVALID_PARAMETER   Invalid parameter.\r
  @retval EFI_OUT_OF_RESOURCES    Failed to allocate memory.\r
**/\r
EFI_STATUS\r
EFIAPI\r
AmlCodeGenScope (\r
  IN  CONST CHAR8                   * NameString,\r
  IN        AML_NODE_HANDLE           ParentNode      OPTIONAL,\r
  OUT       AML_OBJECT_NODE_HANDLE  * NewObjectNode   OPTIONAL\r
  );\r
\r
/** AML code generation for a method returning a NameString.\r
\r
  AmlCodeGenMethodRetNameString (\r
    "MET0", "_CRS", 1, TRUE, 3, ParentNode, NewObjectNode\r
    );\r
  is equivalent of the following ASL code:\r
    Method(MET0, 1, Serialized, 3) {\r
      Return (_CRS)\r
    }\r
\r
  The ASL parameters "ReturnType" and "ParameterTypes" are not asked\r
  in this function. They are optional parameters in ASL.\r
\r
  @ingroup CodeGenApis\r
\r
  @param [in]  MethodNameString     The new Method's name.\r
                                    Must be a NULL-terminated ASL NameString\r
                                    e.g.: "MET0", "_SB.MET0", etc.\r
                                    The input string is copied.\r
  @param [in]  ReturnedNameString   The name of the object returned by the\r
                                    method. Optional parameter, can be:\r
                                     - NULL (ignored).\r
                                     - A NULL-terminated ASL NameString.\r
                                       e.g.: "MET0", "_SB.MET0", etc.\r
                                       The input string is copied.\r
  @param [in]  NumArgs              Number of arguments.\r
                                    Must be 0 <= NumArgs <= 6.\r
  @param [in]  IsSerialized         TRUE is equivalent to Serialized.\r
                                    FALSE is equivalent to NotSerialized.\r
                                    Default is NotSerialized in ASL spec.\r
  @param [in]  SyncLevel            Synchronization level for the method.\r
                                    Must be 0 <= SyncLevel <= 15.\r
                                    Default is 0 in ASL.\r
  @param [in]  ParentNode           If provided, set ParentNode as the parent\r
                                    of the node created.\r
  @param [out] NewObjectNode        If success, contains the created node.\r
\r
  @retval EFI_SUCCESS             Success.\r
  @retval EFI_INVALID_PARAMETER   Invalid parameter.\r
  @retval EFI_OUT_OF_RESOURCES    Failed to allocate memory.\r
**/\r
EFI_STATUS\r
EFIAPI\r
AmlCodeGenMethodRetNameString (\r
  IN  CONST CHAR8                   * MethodNameString,\r
  IN  CONST CHAR8                   * ReturnedNameString   OPTIONAL,\r
  IN        UINT8                     NumArgs,\r
  IN        BOOLEAN                   IsSerialized,\r
  IN        UINT8                     SyncLevel,\r
  IN        AML_NODE_HANDLE           ParentNode           OPTIONAL,\r
  OUT       AML_OBJECT_NODE_HANDLE  * NewObjectNode        OPTIONAL\r
  );\r
\r
/** Create a _LPI name.\r
\r
  AmlCreateLpiNode ("_LPI", 0, 1, ParentNode, &LpiNode) is\r
  equivalent of the following ASL code:\r
    Name (_LPI, Package (\r
                  0,  // Revision\r
                  1,  // LevelId\r
                  0   // Count\r
                  ))\r
\r
  This function doesn't define any LPI state. As shown above, the count\r
  of _LPI state is set to 0.\r
  The AmlAddLpiState () function must be used to add LPI states.\r
\r
  Cf ACPI 6.3 specification, s8.4.4 "Lower Power Idle States".\r
\r
  @ingroup CodeGenApis\r
\r
  @param [in]  LpiNameString  The new LPI 's object name.\r
                              Must be a NULL-terminated ASL NameString\r
                              e.g.: "_LPI", "DEV0.PLPI", etc.\r
                              The input string is copied.\r
  @param [in]  Revision       Revision number of the _LPI states.\r
  @param [in]  LevelId        A platform defined number that identifies the\r
                              level of hierarchy of the processor node to\r
                              which the LPI states apply.\r
  @param [in]  ParentNode     If provided, set ParentNode as the parent\r
                              of the node created.\r
  @param [out] NewLpiNode     If success, contains the created node.\r
\r
  @retval EFI_SUCCESS             The function completed successfully.\r
  @retval EFI_INVALID_PARAMETER   Invalid parameter.\r
  @retval EFI_OUT_OF_RESOURCES    Failed to allocate memory.\r
**/\r
EFI_STATUS\r
EFIAPI\r
AmlCreateLpiNode (\r
  IN  CONST CHAR8                   * LpiNameString,\r
  IN        UINT16                    Revision,\r
  IN        UINT64                    LevelId,\r
  IN        AML_NODE_HANDLE           ParentNode   OPTIONAL,\r
  OUT       AML_OBJECT_NODE_HANDLE  * NewLpiNode   OPTIONAL\r
  );\r
\r
/** Add an _LPI state to a LPI node created using AmlCreateLpiNode ().\r
\r
  AmlAddLpiState () increments the Count of LPI states in the LPI node by one,\r
  and adds the following package:\r
    Package() {\r
      MinResidency,\r
      WorstCaseWakeLatency,\r
      Flags,\r
      ArchFlags,\r
      ResCntFreq,\r
      EnableParentState,\r
      (GenericRegisterDescriptor != NULL) ?           // Entry method. If a\r
        ResourceTemplate(GenericRegisterDescriptor) : // Register is given,\r
        Integer,                                      // use it. Use the\r
                                                      // Integer otherwise.\r
      ResourceTemplate() {                            // NULL Residency Counter\r
        Register (SystemMemory, 0, 0, 0, 0)\r
      },\r
      ResourceTemplate() {                            // NULL Usage Counter\r
        Register (SystemMemory, 0, 0, 0, 0)\r
      },\r
      ""                                              // NULL State Name\r
    },\r
\r
  Cf ACPI 6.3 specification, s8.4.4 "Lower Power Idle States".\r
\r
  @ingroup CodeGenApis\r
\r
  @param [in]  MinResidency               Minimum Residency.\r
  @param [in]  WorstCaseWakeLatency       Worst case wake-up latency.\r
  @param [in]  Flags                      Flags.\r
  @param [in]  ArchFlags                  Architectural flags.\r
  @param [in]  ResCntFreq                 Residency Counter Frequency.\r
  @param [in]  EnableParentState          Enabled Parent State.\r
  @param [in]  GenericRegisterDescriptor  Entry Method.\r
                                          If not NULL, use this Register to\r
                                          describe the entry method address.\r
  @param [in]  Integer                    Entry Method.\r
                                          If GenericRegisterDescriptor is NULL,\r
                                          take this value.\r
  @param [in]  ResidencyCounterRegister   If not NULL, use it to populate the\r
                                          residency counter register.\r
  @param [in]  UsageCounterRegister       If not NULL, use it to populate the\r
                                          usage counter register.\r
  @param [in]  StateName                  If not NULL, use it to populate the\r
                                          state name.\r
  @param [in]  LpiNode                    Lpi node created with the function\r
                                          AmlCreateLpiNode to which the new LPI\r
                                          state is appended.\r
\r
  @retval EFI_SUCCESS             The function completed successfully.\r
  @retval EFI_INVALID_PARAMETER   Invalid parameter.\r
  @retval EFI_OUT_OF_RESOURCES    Failed to allocate memory.\r
**/\r
EFI_STATUS\r
EFIAPI\r
AmlAddLpiState (\r
  IN  UINT32                                    MinResidency,\r
  IN  UINT32                                    WorstCaseWakeLatency,\r
  IN  UINT32                                    Flags,\r
  IN  UINT32                                    ArchFlags,\r
  IN  UINT32                                    ResCntFreq,\r
  IN  UINT32                                    EnableParentState,\r
  IN  EFI_ACPI_6_3_GENERIC_ADDRESS_STRUCTURE  * GenericRegisterDescriptor   OPTIONAL,\r
  IN  UINT64                                    Integer                     OPTIONAL,\r
  IN  EFI_ACPI_6_3_GENERIC_ADDRESS_STRUCTURE  * ResidencyCounterRegister    OPTIONAL,\r
  IN  EFI_ACPI_6_3_GENERIC_ADDRESS_STRUCTURE  * UsageCounterRegister        OPTIONAL,\r
  IN  CHAR8                                   * StateName                   OPTIONAL,\r
  IN  AML_OBJECT_NODE_HANDLE                    LpiNode\r
  );\r
\r
// DEPRECATED APIS\r
#ifndef DISABLE_NEW_DEPRECATED_INTERFACES\r
\r
/** DEPRECATED API\r
\r
  Get the first Resource Data element contained in a "_CRS" object.\r
\r
  In the following ASL code, the function will return the Resource Data\r
  node corresponding to the "QWordMemory ()" ASL macro.\r
  Name (_CRS, ResourceTemplate() {\r
      QWordMemory (...) {...},\r
      Interrupt (...) {...}\r
    }\r
  )\r
\r
  Note:\r
   - The "_CRS" object must be declared using ASL "Name (Declare Named Object)".\r
   - "_CRS" declared using ASL "Method (Declare Control Method)" is not\r
     supported.\r
\r
  @ingroup UserApis\r
\r
  @param  [in] NameOpCrsNode  NameOp object node defining a "_CRS" object.\r
                              Must have an OpCode=AML_NAME_OP, SubOpCode=0.\r
                              NameOp object nodes are defined in ASL\r
                              using the "Name ()" function.\r
  @param  [out] OutRdNode     Pointer to the first Resource Data element of\r
                              the "_CRS" object. A Resource Data element\r
                              is stored in a data node.\r
\r
  @retval EFI_SUCCESS             The function completed successfully.\r
  @retval EFI_INVALID_PARAMETER   Invalid parameter.\r
**/\r
EFI_STATUS\r
EFIAPI\r
AmlNameOpCrsGetFirstRdNode (\r
  IN  AML_OBJECT_NODE_HANDLE   NameOpCrsNode,\r
  OUT AML_DATA_NODE_HANDLE   * OutRdNode\r
  );\r
\r
/** DEPRECATED API\r
\r
  Get the Resource Data element following the CurrRdNode Resource Data.\r
\r
  In the following ASL code, if CurrRdNode corresponds to the first\r
  "QWordMemory ()" ASL macro, the function will return the Resource Data\r
  node corresponding to the "Interrupt ()" ASL macro.\r
  Name (_CRS, ResourceTemplate() {\r
      QwordMemory (...) {...},\r
      Interrupt (...) {...}\r
    }\r
  )\r
\r
  The CurrRdNode Resource Data node must be defined in an object named "_CRS"\r
  and defined by a "Name ()" ASL function.\r
\r
  @ingroup UserApis\r
\r
  @param  [in]  CurrRdNode   Pointer to the current Resource Data element of\r
                             the "_CRS" variable.\r
  @param  [out] OutRdNode    Pointer to the Resource Data element following\r
                             the CurrRdNode.\r
                             Contain a NULL pointer if CurrRdNode is the\r
                             last Resource Data element in the list.\r
                             The "End Tag" is not considered as a resource\r
                             data element and is not returned.\r
\r
  @retval EFI_SUCCESS             The function completed successfully.\r
  @retval EFI_INVALID_PARAMETER   Invalid parameter.\r
**/\r
EFI_STATUS\r
EFIAPI\r
AmlNameOpCrsGetNextRdNode (\r
  IN  AML_DATA_NODE_HANDLE    CurrRdNode,\r
  OUT AML_DATA_NODE_HANDLE  * OutRdNode\r
  );\r
\r
/** DEPRECATED API\r
\r
  Add an Interrupt Resource Data node.\r
\r
  This function creates a Resource Data element corresponding to the\r
  "Interrupt ()" ASL function, stores it in an AML Data Node.\r
\r
  It then adds it after the input CurrRdNode in the list of resource data\r
  element.\r
\r
  The Resource Data effectively created is an Extended Interrupt Resource\r
  Data. See ACPI 6.3 specification, s6.4.3.6 "Extended Interrupt Descriptor"\r
  for more information about Extended Interrupt Resource Data.\r
\r
  The Extended Interrupt contains one single interrupt.\r
\r
  This function allocates memory to create a data node. It is the caller's\r
  responsibility to either:\r
   - attach this node to an AML tree;\r
   - delete this node.\r
\r
  Note: The _CRS node must be defined using the ASL Name () function.\r
        e.g. Name (_CRS, ResourceTemplate () {\r
               ...\r
             }\r
\r
  @ingroup CodeGenApis\r
\r
  @param  [in]  NameOpCrsNode    NameOp object node defining a "_CRS" object.\r
                                 Must have an OpCode=AML_NAME_OP, SubOpCode=0.\r
                                 NameOp object nodes are defined in ASL\r
                                 using the "Name ()" function.\r
  @param  [in]  ResourceConsumer The device consumes the specified interrupt\r
                                 or produces it for use by a child device.\r
  @param  [in]  EdgeTriggered    The interrupt is edge triggered or\r
                                 level triggered.\r
  @param  [in]  ActiveLow        The interrupt is active-high or active-low.\r
  @param  [in]  Shared           The interrupt can be shared with other\r
                                 devices or not (Exclusive).\r
  @param  [in]  IrqList          Interrupt list. Must be non-NULL.\r
  @param  [in]  IrqCount         Interrupt count. Must be non-zero.\r
\r
\r
  @retval EFI_SUCCESS             The function completed successfully.\r
  @retval EFI_INVALID_PARAMETER   Invalid parameter.\r
  @retval EFI_OUT_OF_RESOURCES    Could not allocate memory.\r
**/\r
EFI_STATUS\r
EFIAPI\r
AmlCodeGenCrsAddRdInterrupt (\r
  IN  AML_OBJECT_NODE_HANDLE  NameOpCrsNode,\r
  IN  BOOLEAN                 ResourceConsumer,\r
  IN  BOOLEAN                 EdgeTriggered,\r
  IN  BOOLEAN                 ActiveLow,\r
  IN  BOOLEAN                 Shared,\r
  IN  UINT32                * IrqList,\r
  IN  UINT8                   IrqCount\r
  );\r
\r
#endif // DISABLE_NEW_DEPRECATED_INTERFACES\r
\r
#endif // AML_LIB_H_\r