[mirror_edk2.git] / DynamicTablesPkg / Library / Common / AmlLib / CodeGen / AmlCodeGen.c

/** @file\r
  AML Code Generation.\r
\r
  Copyright (c) 2020 - 2021, Arm Limited. All rights reserved.<BR>\r
\r
  SPDX-License-Identifier: BSD-2-Clause-Patent\r
**/\r
\r
#include <AmlNodeDefines.h>\r
\r
#include <AcpiTableGenerator.h>\r
\r
#include <AmlCoreInterface.h>\r
#include <AmlEncoding/Aml.h>\r
#include <CodeGen/AmlResourceDataCodeGen.h>\r
#include <Tree/AmlNode.h>\r
#include <Tree/AmlTree.h>\r
#include <String/AmlString.h>\r
#include <Utils/AmlUtility.h>\r
\r
/** Utility function to link a node when returning from a CodeGen function.\r
\r
  @param [in]  Node           Newly created node.\r
  @param [in]  ParentNode     If provided, set ParentNode as the parent\r
                              of the node created.\r
  @param [out] NewObjectNode  If not NULL:\r
                               - and Success, contains the created Node.\r
                               - and Error, reset to NULL.\r
\r
  @retval  EFI_SUCCESS            The function completed successfully.\r
  @retval  EFI_INVALID_PARAMETER  Invalid parameter.\r
**/\r
STATIC\r
EFI_STATUS\r
EFIAPI\r
LinkNode (\r
  IN  AML_OBJECT_NODE    * Node,\r
  IN  AML_NODE_HEADER    * ParentNode,\r
  OUT AML_OBJECT_NODE   ** NewObjectNode\r
  )\r
{\r
  EFI_STATUS    Status;\r
\r
  if (NewObjectNode != NULL) {\r
    *NewObjectNode = NULL;\r
  }\r
\r
  // Add RdNode as the last element.\r
  if (ParentNode != NULL) {\r
    Status = AmlVarListAddTail (ParentNode, (AML_NODE_HEADER*)Node);\r
    if (EFI_ERROR (Status)) {\r
      ASSERT (0);\r
      return Status;\r
    }\r
  }\r
\r
  if (NewObjectNode != NULL) {\r
    *NewObjectNode = Node;\r
  }\r
\r
  return EFI_SUCCESS;\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
  @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] NewRootNode          Pointer to the root node 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    ** NewRootNode\r
  )\r
{\r
  EFI_STATUS                      Status;\r
  EFI_ACPI_DESCRIPTION_HEADER     AcpiHeader;\r
\r
  if ((TableSignature == NULL)  ||\r
      (OemId == NULL)           ||\r
      (OemTableId == NULL)      ||\r
      (NewRootNode == NULL)) {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  CopyMem (&AcpiHeader.Signature, TableSignature, 4);\r
  AcpiHeader.Length = sizeof (EFI_ACPI_DESCRIPTION_HEADER);\r
  AcpiHeader.Revision = 2;\r
  CopyMem (&AcpiHeader.OemId, OemId, 6);\r
  CopyMem (&AcpiHeader.OemTableId, OemTableId, 8);\r
  AcpiHeader.OemRevision = OemRevision;\r
  AcpiHeader.CreatorId = TABLE_GENERATOR_CREATOR_ID_ARM;\r
  AcpiHeader.CreatorRevision = CREATE_REVISION (1, 0);\r
\r
  Status = AmlCreateRootNode (&AcpiHeader, NewRootNode);\r
  ASSERT_EFI_ERROR (Status);\r
\r
  return Status;\r
}\r
\r
/** AML code generation for a String object node.\r
\r
  @param [in]  String          Pointer to a NULL terminated string.\r
  @param [out] NewObjectNode   If success, contains the created\r
                               String object 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
STATIC\r
EFI_STATUS\r
EFIAPI\r
AmlCodeGenString (\r
  IN  CHAR8               * String,\r
  OUT AML_OBJECT_NODE    ** NewObjectNode\r
  )\r
{\r
  EFI_STATUS          Status;\r
  AML_OBJECT_NODE   * ObjectNode;\r
  AML_DATA_NODE     * DataNode;\r
\r
  if ((String == NULL)  ||\r
      (NewObjectNode == NULL)) {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  DataNode = NULL;\r
\r
  Status = AmlCreateObjectNode (\r
             AmlGetByteEncodingByOpCode (AML_STRING_PREFIX, 0),\r
             0,\r
             &ObjectNode\r
             );\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    return Status;\r
  }\r
\r
  Status = AmlCreateDataNode (\r
             EAmlNodeDataTypeString,\r
             (UINT8*)String,\r
             (UINT32)AsciiStrLen (String) + 1,\r
             &DataNode\r
             );\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    goto error_handler;\r
  }\r
\r
  Status = AmlSetFixedArgument (\r
             ObjectNode,\r
             EAmlParseIndexTerm0,\r
             (AML_NODE_HEADER*)DataNode\r
             );\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    AmlDeleteTree ((AML_NODE_HEADER*)DataNode);\r
    goto error_handler;\r
  }\r
\r
  *NewObjectNode = ObjectNode;\r
  return Status;\r
\r
error_handler:\r
  AmlDeleteTree ((AML_NODE_HEADER*)ObjectNode);\r
  return Status;\r
}\r
\r
/** AML code generation for an Integer object node.\r
\r
  @param [in]  Integer         Integer of the Integer object node.\r
  @param [out] NewObjectNode   If success, contains the created\r
                               Integer object 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
STATIC\r
EFI_STATUS\r
EFIAPI\r
AmlCodeGenInteger (\r
  IN  UINT64                Integer,\r
  OUT AML_OBJECT_NODE    ** NewObjectNode\r
  )\r
{\r
  EFI_STATUS          Status;\r
  INT8                ValueWidthDiff;\r
\r
  if (NewObjectNode == NULL) {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
   // Create an object node containing Zero.\r
   Status = AmlCreateObjectNode (\r
             AmlGetByteEncodingByOpCode (AML_ZERO_OP, 0),\r
             0,\r
             NewObjectNode\r
             );\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    return Status;\r
  }\r
\r
  // Update the object node with integer value.\r
  Status = AmlNodeSetIntegerValue (*NewObjectNode, Integer, &ValueWidthDiff);\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    AmlDeleteTree ((AML_NODE_HEADER*)*NewObjectNode);\r
  }\r
\r
  return Status;\r
}\r
\r
/** AML code generation for a Package object node.\r
\r
  The package generated is empty. New elements can be added via its\r
  list of variable arguments.\r
\r
  @param [out] NewObjectNode   If success, contains the created\r
                               Package object 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
STATIC\r
EFI_STATUS\r
EFIAPI\r
AmlCodeGenPackage (\r
  OUT AML_OBJECT_NODE    ** NewObjectNode\r
  )\r
{\r
  EFI_STATUS        Status;\r
  AML_DATA_NODE   * DataNode;\r
  UINT8             NodeCount;\r
\r
  if (NewObjectNode == NULL) {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  NodeCount = 0;\r
\r
  // Create an object node.\r
  // PkgLen is 2:\r
  //  - one byte to store the PkgLength\r
  //  - one byte for the NumElements.\r
  // Cf ACPI6.3, s20.2.5 "Term Objects Encoding"\r
  // DefPackage  := PackageOp PkgLength NumElements PackageElementList\r
  // NumElements := ByteData\r
  Status = AmlCreateObjectNode (\r
             AmlGetByteEncodingByOpCode (AML_PACKAGE_OP, 0),\r
             2,\r
             NewObjectNode\r
             );\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    return Status;\r
  }\r
\r
  // NumElements is a ByteData.\r
  Status = AmlCreateDataNode (\r
             EAmlNodeDataTypeUInt,\r
             &NodeCount,\r
             sizeof (NodeCount),\r
             &DataNode\r
             );\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    goto error_handler;\r
  }\r
\r
  Status = AmlSetFixedArgument (\r
             *NewObjectNode,\r
             EAmlParseIndexTerm0,\r
             (AML_NODE_HEADER*)DataNode\r
             );\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    goto error_handler;\r
  }\r
\r
  return Status;\r
\r
error_handler:\r
  AmlDeleteTree ((AML_NODE_HEADER*)*NewObjectNode);\r
  if (DataNode != NULL) {\r
    AmlDeleteTree ((AML_NODE_HEADER*)DataNode);\r
  }\r
  return Status;\r
}\r
\r
/** AML code generation for a Buffer object node.\r
\r
  To create a Buffer object node with an empty buffer,\r
  call the function with (Buffer=NULL, BufferSize=0).\r
\r
  @param [in]  Buffer          Buffer to set for the created Buffer\r
                               object node. The Buffer's content is copied.\r
                               NULL if there is no buffer to set for\r
                               the Buffer node.\r
  @param [in]  BufferSize      Size of the Buffer.\r
                               0 if there is no buffer to set for\r
                               the Buffer node.\r
  @param [out] NewObjectNode   If success, contains the created\r
                               Buffer object 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
STATIC\r
EFI_STATUS\r
EFIAPI\r
AmlCodeGenBuffer (\r
  IN  CONST UINT8             * Buffer,       OPTIONAL\r
  IN        UINT32              BufferSize,   OPTIONAL\r
  OUT       AML_OBJECT_NODE  ** NewObjectNode\r
  )\r
{\r
  EFI_STATUS        Status;\r
  AML_OBJECT_NODE * BufferNode;\r
  AML_OBJECT_NODE * BufferSizeNode;\r
  UINT32            BufferSizeNodeSize;\r
  AML_DATA_NODE   * DataNode;\r
  UINT32            PkgLen;\r
\r
  // Buffer and BufferSize must be either both set, or both clear.\r
  if ((NewObjectNode == NULL)                 ||\r
      ((Buffer == NULL) != (BufferSize == 0))) {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  BufferNode = NULL;\r
  DataNode = NULL;\r
\r
  // Cf ACPI 6.3 specification, s20.2.5.4 "Type 2 Opcodes Encoding"\r
  // DefBuffer := BufferOp PkgLength BufferSize ByteList\r
  // BufferOp  := 0x11\r
  // BufferSize := TermArg => Integer\r
\r
  Status = AmlCodeGenInteger (BufferSize, &BufferSizeNode);\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    return Status;\r
  }\r
\r
  // Get the number of bytes required to encode the BufferSizeNode.\r
  Status = AmlComputeSize (\r
             (AML_NODE_HEADER*)BufferSizeNode,\r
             &BufferSizeNodeSize\r
             );\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    goto error_handler;\r
  }\r
\r
  // Compute the size to write in the PkgLen.\r
  Status = AmlComputePkgLength (BufferSizeNodeSize + BufferSize, &PkgLen);\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    goto error_handler;\r
  }\r
\r
  // Create an object node for the buffer.\r
  Status = AmlCreateObjectNode (\r
             AmlGetByteEncodingByOpCode (AML_BUFFER_OP, 0),\r
             PkgLen,\r
             &BufferNode\r
             );\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    goto error_handler;\r
  }\r
\r
  // Set the BufferSizeNode as a fixed argument of the BufferNode.\r
  Status = AmlSetFixedArgument (\r
             BufferNode,\r
             EAmlParseIndexTerm0,\r
             (AML_NODE_HEADER*)BufferSizeNode\r
             );\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    goto error_handler;\r
  }\r
\r
  // BufferSizeNode is now attached.\r
  BufferSizeNode = NULL;\r
\r
  // If there is a buffer, create a DataNode and attach it to the BufferNode.\r
  if (Buffer != NULL) {\r
    Status = AmlCreateDataNode (\r
               EAmlNodeDataTypeRaw,\r
               Buffer,\r
               BufferSize,\r
               &DataNode\r
               );\r
    if (EFI_ERROR (Status)) {\r
      ASSERT (0);\r
      goto error_handler;\r
    }\r
\r
    Status = AmlVarListAddTail (\r
               (AML_NODE_HEADER*)BufferNode,\r
               (AML_NODE_HEADER*)DataNode\r
               );\r
    if (EFI_ERROR (Status)) {\r
      ASSERT (0);\r
      goto error_handler;\r
    }\r
  }\r
\r
  *NewObjectNode = BufferNode;\r
  return Status;\r
\r
error_handler:\r
  if (BufferSizeNode != NULL) {\r
    AmlDeleteTree ((AML_NODE_HEADER*)BufferSizeNode);\r
  }\r
  if (BufferNode != NULL) {\r
    AmlDeleteTree ((AML_NODE_HEADER*)BufferNode);\r
  }\r
  if (DataNode != NULL) {\r
    AmlDeleteTree ((AML_NODE_HEADER*)DataNode);\r
  }\r
  return Status;\r
}\r
\r
/** AML code generation for a ResourceTemplate.\r
\r
  "ResourceTemplate" is a macro defined in ACPI 6.3, s19.3.3\r
  "ASL Resource Templates". It allows to store resource data elements.\r
\r
  In AML, a ResourceTemplate is implemented as a Buffer storing resource\r
  data elements. An EndTag resource data descriptor must be at the end\r
  of the list of resource data elements.\r
  This function generates a Buffer node with an EndTag resource data\r
  descriptor. It can be seen as an empty list of resource data elements.\r
\r
  @param [out] NewObjectNode   If success, contains the created\r
                               ResourceTemplate object 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
STATIC\r
EFI_STATUS\r
EFIAPI\r
AmlCodeGenResourceTemplate (\r
  OUT AML_OBJECT_NODE    ** NewObjectNode\r
  )\r
{\r
  EFI_STATUS          Status;\r
  AML_OBJECT_NODE   * BufferNode;\r
\r
  if (NewObjectNode == NULL) {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  // Create a BufferNode with an empty buffer.\r
  Status = AmlCodeGenBuffer (NULL, 0, &BufferNode);\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    return Status;\r
  }\r
\r
  // Create an EndTag resource data element and attach it to the Buffer.\r
  Status = AmlCodeGenEndTag (0, BufferNode, NULL);\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    AmlDeleteTree ((AML_NODE_HEADER*)BufferNode);\r
    return Status;\r
  }\r
\r
  *NewObjectNode = BufferNode;\r
  return Status;\r
}\r
\r
/** AML code generation for a Name object node.\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
                              This input string is copied.\r
  @param [in]  Object         Object associated 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
STATIC\r
EFI_STATUS\r
EFIAPI\r
AmlCodeGenName (\r
  IN  CONST CHAR8              * NameString,\r
  IN        AML_OBJECT_NODE    * Object,\r
  IN        AML_NODE_HEADER    * ParentNode,     OPTIONAL\r
  OUT       AML_OBJECT_NODE   ** NewObjectNode   OPTIONAL\r
  )\r
{\r
  EFI_STATUS          Status;\r
  AML_OBJECT_NODE   * ObjectNode;\r
  AML_DATA_NODE     * DataNode;\r
  CHAR8             * AmlNameString;\r
  UINT32              AmlNameStringSize;\r
\r
  if ((NameString == NULL)    ||\r
      (Object == NULL)        ||\r
      ((ParentNode == NULL) && (NewObjectNode == NULL))) {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  ObjectNode = NULL;\r
  DataNode = NULL;\r
  AmlNameString = NULL;\r
\r
  Status = ConvertAslNameToAmlName (NameString, &AmlNameString);\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    return Status;\r
  }\r
\r
  Status = AmlGetNameStringSize (AmlNameString, &AmlNameStringSize);\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    goto error_handler1;\r
  }\r
\r
  Status = AmlCreateObjectNode (\r
             AmlGetByteEncodingByOpCode (AML_NAME_OP, 0),\r
             0,\r
             &ObjectNode\r
             );\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    goto error_handler1;\r
  }\r
\r
  Status = AmlCreateDataNode (\r
             EAmlNodeDataTypeNameString,\r
             (UINT8*)AmlNameString,\r
             AmlNameStringSize,\r
             &DataNode\r
             );\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    goto error_handler2;\r
  }\r
\r
  Status = AmlSetFixedArgument (\r
             ObjectNode,\r
             EAmlParseIndexTerm0,\r
             (AML_NODE_HEADER*)DataNode\r
             );\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    AmlDeleteTree ((AML_NODE_HEADER*)DataNode);\r
    goto error_handler2;\r
  }\r
\r
  Status = AmlSetFixedArgument (\r
             ObjectNode,\r
             EAmlParseIndexTerm1,\r
             (AML_NODE_HEADER*)Object\r
             );\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    goto error_handler2;\r
  }\r
\r
  Status = LinkNode (\r
             ObjectNode,\r
             ParentNode,\r
             NewObjectNode\r
             );\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    goto error_handler2;\r
  }\r
\r
  // Free AmlNameString before returning as it is copied\r
  // in the call to AmlCreateDataNode().\r
  goto error_handler1;\r
\r
error_handler2:\r
  if (ObjectNode != NULL) {\r
    AmlDeleteTree ((AML_NODE_HEADER*)ObjectNode);\r
  }\r
\r
error_handler1:\r
  if (AmlNameString != NULL) {\r
    FreePool (AmlNameString);\r
  }\r
\r
  return Status;\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
  @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_HEADER    * ParentNode,     OPTIONAL\r
  OUT       AML_OBJECT_NODE   ** NewObjectNode   OPTIONAL\r
  )\r
{\r
  EFI_STATUS          Status;\r
  AML_OBJECT_NODE   * ObjectNode;\r
\r
  if ((NameString == NULL)  ||\r
      (String == NULL)      ||\r
      ((ParentNode == NULL) && (NewObjectNode == NULL))) {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  Status = AmlCodeGenString (String, &ObjectNode);\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    return Status;\r
  }\r
\r
  Status = AmlCodeGenName (\r
             NameString,\r
             ObjectNode,\r
             ParentNode,\r
             NewObjectNode\r
             );\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    AmlDeleteTree ((AML_NODE_HEADER*)ObjectNode);\r
  }\r
\r
  return Status;\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
  @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_HEADER    * ParentNode,     OPTIONAL\r
  OUT       AML_OBJECT_NODE   ** NewObjectNode   OPTIONAL\r
  )\r
{\r
  EFI_STATUS          Status;\r
  AML_OBJECT_NODE   * ObjectNode;\r
\r
  if ((NameString == NULL)  ||\r
      ((ParentNode == NULL) && (NewObjectNode == NULL))) {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  Status = AmlCodeGenInteger (Integer, &ObjectNode);\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    return Status;\r
  }\r
\r
  Status = AmlCodeGenName (\r
             NameString,\r
             ObjectNode,\r
             ParentNode,\r
             NewObjectNode\r
             );\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    AmlDeleteTree ((AML_NODE_HEADER*)ObjectNode);\r
  }\r
\r
  return Status;\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
  @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_HEADER    * ParentNode,     OPTIONAL\r
  OUT       AML_OBJECT_NODE   ** NewObjectNode   OPTIONAL\r
  )\r
{\r
  EFI_STATUS          Status;\r
  AML_OBJECT_NODE   * ObjectNode;\r
  AML_DATA_NODE     * DataNode;\r
  CHAR8             * AmlNameString;\r
  UINT32              AmlNameStringSize;\r
\r
  if ((NameString == NULL)  ||\r
      ((ParentNode == NULL) && (NewObjectNode == NULL))) {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  ObjectNode = NULL;\r
  DataNode = NULL;\r
  AmlNameString = NULL;\r
\r
  Status = ConvertAslNameToAmlName (NameString, &AmlNameString);\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    return Status;\r
  }\r
\r
  Status = AmlGetNameStringSize (AmlNameString, &AmlNameStringSize);\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    goto error_handler1;\r
  }\r
\r
  Status = AmlCreateObjectNode (\r
             AmlGetByteEncodingByOpCode (AML_EXT_OP, AML_EXT_DEVICE_OP),\r
             AmlNameStringSize + AmlComputePkgLengthWidth (AmlNameStringSize),\r
             &ObjectNode\r
             );\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    goto error_handler1;\r
  }\r
\r
  Status = AmlCreateDataNode (\r
             EAmlNodeDataTypeNameString,\r
             (UINT8*)AmlNameString,\r
             AmlNameStringSize,\r
             &DataNode\r
             );\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    goto error_handler2;\r
  }\r
\r
  Status = AmlSetFixedArgument (\r
             ObjectNode,\r
             EAmlParseIndexTerm0,\r
             (AML_NODE_HEADER*)DataNode\r
             );\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    AmlDeleteTree ((AML_NODE_HEADER*)DataNode);\r
    goto error_handler2;\r
  }\r
\r
  Status = LinkNode (\r
             ObjectNode,\r
             ParentNode,\r
             NewObjectNode\r
             );\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    goto error_handler2;\r
  }\r
\r
  // Free AmlNameString before returning as it is copied\r
  // in the call to AmlCreateDataNode().\r
  goto error_handler1;\r
\r
error_handler2:\r
  if (ObjectNode != NULL) {\r
    AmlDeleteTree ((AML_NODE_HEADER*)ObjectNode);\r
  }\r
\r
error_handler1:\r
  if (AmlNameString != NULL) {\r
    FreePool (AmlNameString);\r
  }\r
\r
  return Status;\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
  @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_HEADER    * ParentNode,     OPTIONAL\r
  OUT       AML_OBJECT_NODE   ** NewObjectNode   OPTIONAL\r
  )\r
{\r
  EFI_STATUS          Status;\r
  AML_OBJECT_NODE   * ObjectNode;\r
  AML_DATA_NODE     * DataNode;\r
  CHAR8             * AmlNameString;\r
  UINT32              AmlNameStringSize;\r
\r
  if ((NameString == NULL)  ||\r
      ((ParentNode == NULL) && (NewObjectNode == NULL))) {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  ObjectNode = NULL;\r
  DataNode = NULL;\r
  AmlNameString = NULL;\r
\r
  Status = ConvertAslNameToAmlName (NameString, &AmlNameString);\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    return Status;\r
  }\r
\r
  Status = AmlGetNameStringSize (AmlNameString, &AmlNameStringSize);\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    goto error_handler1;\r
  }\r
\r
  Status = AmlCreateObjectNode (\r
             AmlGetByteEncodingByOpCode (AML_SCOPE_OP, 0),\r
             AmlNameStringSize + AmlComputePkgLengthWidth (AmlNameStringSize),\r
             &ObjectNode\r
             );\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    goto error_handler1;\r
  }\r
\r
  Status = AmlCreateDataNode (\r
             EAmlNodeDataTypeNameString,\r
             (UINT8*)AmlNameString,\r
             AmlNameStringSize,\r
             &DataNode\r
             );\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    goto error_handler2;\r
  }\r
\r
  Status = AmlSetFixedArgument (\r
             ObjectNode,\r
             EAmlParseIndexTerm0,\r
             (AML_NODE_HEADER*)DataNode\r
             );\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    AmlDeleteTree ((AML_NODE_HEADER*)DataNode);\r
    goto error_handler2;\r
  }\r
\r
  Status = LinkNode (\r
             ObjectNode,\r
             ParentNode,\r
             NewObjectNode\r
             );\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    goto error_handler2;\r
  }\r
\r
  // Free AmlNameString before returning as it is copied\r
  // in the call to AmlCreateDataNode().\r
  goto error_handler1;\r
\r
error_handler2:\r
  if (ObjectNode != NULL) {\r
    AmlDeleteTree ((AML_NODE_HEADER*)ObjectNode);\r
  }\r
\r
error_handler1:\r
  if (AmlNameString != NULL) {\r
    FreePool (AmlNameString);\r
  }\r
\r
  return Status;\r
}\r
\r
/** AML code generation for a Method object node.\r
\r
  AmlCodeGenMethod ("MET0", 1, TRUE, 3, ParentNode, NewObjectNode) is\r
  equivalent of the following ASL code:\r
    Method(MET0, 1, Serialized, 3) {}\r
\r
  ACPI 6.4, s20.2.5.2 "Named Objects Encoding":\r
    DefMethod := MethodOp PkgLength NameString MethodFlags TermList\r
    MethodOp := 0x14\r
\r
  The ASL parameters "ReturnType" and "ParameterTypes" are not asked\r
  in this function. They are optional parameters in ASL.\r
\r
  @param [in]  NameString     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]  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
STATIC\r
EFI_STATUS\r
EFIAPI\r
AmlCodeGenMethod (\r
  IN  CONST CHAR8              * NameString,\r
  IN        UINT8                NumArgs,\r
  IN        BOOLEAN              IsSerialized,\r
  IN        UINT8                SyncLevel,\r
  IN        AML_NODE_HEADER    * ParentNode,     OPTIONAL\r
  OUT       AML_OBJECT_NODE   ** NewObjectNode   OPTIONAL\r
  )\r
{\r
  EFI_STATUS        Status;\r
  UINT32            PkgLen;\r
  UINT8             Flags;\r
  AML_OBJECT_NODE * ObjectNode;\r
  AML_DATA_NODE   * DataNode;\r
  CHAR8           * AmlNameString;\r
  UINT32            AmlNameStringSize;\r
\r
  if ((NameString == NULL)    ||\r
      (NumArgs > 6)           ||\r
      (SyncLevel > 15)        ||\r
      ((ParentNode == NULL) && (NewObjectNode == NULL))) {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  ObjectNode = NULL;\r
  DataNode = NULL;\r
\r
  // ACPI 6.4, s20.2.5.2 "Named Objects Encoding":\r
  //   DefMethod := MethodOp PkgLength NameString MethodFlags TermList\r
  //   MethodOp := 0x14\r
  // So:\r
  //  1- Create the NameString\r
  //  2- Compute the size to write in the PkgLen\r
  //  3- Create nodes for the NameString and Method object node\r
  //  4- Set the NameString DataNode as a fixed argument\r
  //  5- Create and link the MethodFlags node\r
\r
  // 1- Create the NameString\r
  Status = ConvertAslNameToAmlName (NameString, &AmlNameString);\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    return Status;\r
  }\r
\r
  Status = AmlGetNameStringSize (AmlNameString, &AmlNameStringSize);\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    goto error_handler1;\r
  }\r
\r
  // 2- Compute the size to write in the PkgLen\r
  //    Add 1 byte (ByteData) for MethodFlags.\r
  Status = AmlComputePkgLength (AmlNameStringSize + 1, &PkgLen);\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    goto error_handler1;\r
  }\r
\r
  //  3- Create nodes for the NameString and Method object node\r
  Status = AmlCreateObjectNode (\r
             AmlGetByteEncodingByOpCode (AML_METHOD_OP, 0),\r
             PkgLen,\r
             &ObjectNode\r
             );\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    goto error_handler1;\r
  }\r
\r
  Status = AmlCreateDataNode (\r
             EAmlNodeDataTypeNameString,\r
             (UINT8*)AmlNameString,\r
             AmlNameStringSize,\r
             &DataNode\r
             );\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    goto error_handler2;\r
  }\r
\r
  //  4- Set the NameString DataNode as a fixed argument\r
  Status = AmlSetFixedArgument (\r
             ObjectNode,\r
             EAmlParseIndexTerm0,\r
             (AML_NODE_HEADER*)DataNode\r
             );\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    goto error_handler2;\r
  }\r
\r
  DataNode = NULL;\r
\r
  //  5- Create and link the MethodFlags node\r
  Flags = NumArgs                   |\r
          (IsSerialized ? BIT3 : 0) |\r
          (SyncLevel << 4);\r
\r
  Status = AmlCreateDataNode (EAmlNodeDataTypeUInt, &Flags, 1, &DataNode);\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    goto error_handler2;\r
  }\r
\r
  Status = AmlSetFixedArgument (\r
             ObjectNode,\r
             EAmlParseIndexTerm1,\r
             (AML_NODE_HEADER*)DataNode\r
             );\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    goto error_handler2;\r
  }\r
\r
  // Data node is attached so set the pointer to\r
  // NULL to ensure correct error handling.\r
  DataNode = NULL;\r
\r
  Status = LinkNode (\r
             ObjectNode,\r
             ParentNode,\r
             NewObjectNode\r
             );\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    goto error_handler2;\r
  }\r
\r
  // Free AmlNameString before returning as it is copied\r
  // in the call to AmlCreateDataNode().\r
  goto error_handler1;\r
\r
error_handler2:\r
  if (ObjectNode != NULL) {\r
    AmlDeleteTree ((AML_NODE_HEADER*)ObjectNode);\r
  }\r
  if (DataNode != NULL) {\r
    AmlDeleteTree ((AML_NODE_HEADER*)DataNode);\r
  }\r
\r
error_handler1:\r
  if (AmlNameString != NULL) {\r
    FreePool (AmlNameString);\r
  }\r
  return Status;\r
}\r
\r
/** AML code generation for a Return object node.\r
\r
  AmlCodeGenReturn (ReturnNode, ParentNode, NewObjectNode) is\r
  equivalent of the following ASL code:\r
    Return([Content of the ReturnNode])\r
\r
  The ACPI 6.3 specification, s20.2.5.3 "Type 1 Opcodes Encoding" states:\r
    DefReturn := ReturnOp ArgObject\r
    ReturnOp := 0xA4\r
    ArgObject := TermArg => DataRefObject\r
\r
  Thus, the ReturnNode must be evaluated as a DataRefObject. It can\r
  be a NameString referencing an object. As this CodeGen Api doesn't\r
  do semantic checking, it is strongly advised to check the AML bytecode\r
  generated by this function against an ASL compiler.\r
\r
  The ReturnNode must be generated inside a Method body scope.\r
\r
  @param [in]  ReturnNode     The object returned by the Return ASL statement.\r
                              This node is deleted if an error occurs.\r
  @param [in]  ParentNode     If provided, set ParentNode as the parent\r
                              of the node created.\r
                              Must be a MethodOp node.\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
STATIC\r
EFI_STATUS\r
EFIAPI\r
AmlCodeGenReturn (\r
  IN  AML_NODE_HEADER     * ReturnNode,\r
  IN  AML_NODE_HEADER     * ParentNode,     OPTIONAL\r
  OUT AML_OBJECT_NODE    ** NewObjectNode   OPTIONAL\r
  )\r
{\r
  EFI_STATUS        Status;\r
  AML_OBJECT_NODE * ObjectNode;\r
\r
  if ((ReturnNode == NULL)                              ||\r
      ((ParentNode == NULL) && (NewObjectNode == NULL)) ||\r
      ((ParentNode != NULL) &&\r
        !AmlNodeCompareOpCode (\r
            (AML_OBJECT_NODE*)ParentNode, AML_METHOD_OP, 0))) {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  Status = AmlCreateObjectNode (\r
             AmlGetByteEncodingByOpCode (AML_RETURN_OP, 0),\r
             0,\r
             &ObjectNode\r
             );\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    goto error_handler;\r
  }\r
\r
  Status = AmlSetFixedArgument (\r
             ObjectNode,\r
             EAmlParseIndexTerm0,\r
             (AML_NODE_HEADER*)ReturnNode\r
             );\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    goto error_handler;\r
  }\r
\r
  ReturnNode = NULL;\r
\r
  Status = LinkNode (\r
             ObjectNode,\r
             ParentNode,\r
             NewObjectNode\r
             );\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    goto error_handler;\r
  }\r
\r
  return Status;\r
\r
error_handler:\r
  if (ReturnNode != NULL) {\r
    AmlDeleteTree (ReturnNode);\r
  }\r
  if (ObjectNode != NULL) {\r
    AmlDeleteTree ((AML_NODE_HEADER*)ObjectNode);\r
  }\r
  return Status;\r
}\r
\r
/** AML code generation for a Return object node,\r
    returning the object as an input NameString.\r
\r
  AmlCodeGenReturn ("NAM1", ParentNode, NewObjectNode) is\r
  equivalent of the following ASL code:\r
    Return(NAM1)\r
\r
  The ACPI 6.3 specification, s20.2.5.3 "Type 1 Opcodes Encoding" states:\r
    DefReturn := ReturnOp ArgObject\r
    ReturnOp := 0xA4\r
    ArgObject := TermArg => DataRefObject\r
\r
  Thus, the ReturnNode must be evaluated as a DataRefObject. It can\r
  be a NameString referencing an object. As this CodeGen Api doesn't\r
  do semantic checking, it is strongly advised to check the AML bytecode\r
  generated by this function against an ASL compiler.\r
\r
  The ReturnNode must be generated inside a Method body scope.\r
\r
  @param [in]  NameString     The object referenced by this NameString\r
                              is returned by the Return ASL statement.\r
                              Must be a NULL-terminated ASL NameString\r
                              e.g.: "NAM1", "_SB.NAM1", etc.\r
                              The input string is copied.\r
  @param [in]  ParentNode     If provided, set ParentNode as the parent\r
                              of the node created.\r
                              Must be a MethodOp node.\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
STATIC\r
EFI_STATUS\r
EFIAPI\r
AmlCodeGenReturnNameString (\r
  IN  CONST CHAR8               * NameString,\r
  IN        AML_NODE_HEADER     * ParentNode,     OPTIONAL\r
  OUT       AML_OBJECT_NODE    ** NewObjectNode   OPTIONAL\r
  )\r
{\r
  EFI_STATUS          Status;\r
  AML_DATA_NODE     * DataNode;\r
  CHAR8             * AmlNameString;\r
  UINT32              AmlNameStringSize;\r
\r
  DataNode = NULL;\r
\r
  Status = ConvertAslNameToAmlName (NameString, &AmlNameString);\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    return Status;\r
  }\r
\r
  Status = AmlGetNameStringSize (AmlNameString, &AmlNameStringSize);\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    goto exit_handler;\r
  }\r
\r
  Status = AmlCreateDataNode (\r
             EAmlNodeDataTypeNameString,\r
             (UINT8*)AmlNameString,\r
             AmlNameStringSize,\r
             &DataNode\r
             );\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    goto exit_handler;\r
  }\r
\r
  // AmlCodeGenReturn() deletes DataNode if error.\r
  Status = AmlCodeGenReturn (\r
             (AML_NODE_HEADER*)DataNode,\r
             ParentNode,\r
             NewObjectNode\r
             );\r
  ASSERT_EFI_ERROR (Status);\r
\r
exit_handler:\r
  if (AmlNameString != NULL) {\r
    FreePool (AmlNameString);\r
  }\r
  return Status;\r
}\r