DynamicTablesPkg: AmlLib APIs

[mirror_edk2.git] / DynamicTablesPkg / Library / Common / AmlLib / Api / AmlApi.c

/** @file\r
  AML Api.\r
\r
  Copyright (c) 2020, Arm Limited. All rights reserved.<BR>\r
\r
  SPDX-License-Identifier: BSD-2-Clause-Patent\r
**/\r
\r
/* Even though this file has access to the internal Node definition,\r
   i.e. AML_ROOT_NODE, AML_OBJECT_NODE, etc. Only the external node\r
   handle types should be used, i.e. AML_NODE_HANDLE, AML_ROOT_NODE_HANDLE,\r
   etc.\r
   Indeed, the functions in the "Api" folder should be implemented only\r
   using the "safe" functions available in the "Include" folder. This\r
   makes the functions available in the "Api" folder easy to export.\r
*/\r
#include <AmlNodeDefines.h>\r
\r
#include <AmlCoreInterface.h>\r
#include <AmlInclude.h>\r
#include <Api/AmlApiHelper.h>\r
#include <String/AmlString.h>\r
\r
/** Update the name of a DeviceOp object node.\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
  EFI_STATUS              Status;\r
\r
  AML_DATA_NODE_HANDLE    DeviceNameDataNode;\r
  CHAR8                 * NewAmlNameString;\r
  UINT32                  NewAmlNameStringSize;\r
\r
  // Check the input node is an object node.\r
  if ((DeviceOpNode == NULL)                                              ||\r
      (AmlGetNodeType ((AML_NODE_HANDLE)DeviceOpNode) != EAmlNodeObject)  ||\r
      (!AmlNodeHasOpCode (DeviceOpNode, AML_EXT_OP, AML_EXT_DEVICE_OP))   ||\r
      (NewNameString == NULL)) {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  // Get the Device's name, being a data node\r
  // which is the 1st fixed argument (i.e. index 0).\r
  DeviceNameDataNode = (AML_DATA_NODE_HANDLE)AmlGetFixedArgument (\r
                                               DeviceOpNode,\r
                                               EAmlParseIndexTerm0\r
                                               );\r
  if ((DeviceNameDataNode == NULL)                                            ||\r
      (AmlGetNodeType ((AML_NODE_HANDLE)DeviceNameDataNode) != EAmlNodeData)  ||\r
      (!AmlNodeHasDataType (DeviceNameDataNode, EAmlNodeDataTypeNameString))) {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  Status = ConvertAslNameToAmlName (NewNameString, &NewAmlNameString);\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    return Status;\r
  }\r
\r
  Status = AmlGetNameStringSize (NewAmlNameString, &NewAmlNameStringSize);\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    goto exit_handler;\r
  }\r
\r
  // Update the Device's name node.\r
  Status = AmlUpdateDataNode (\r
             DeviceNameDataNode,\r
             EAmlNodeDataTypeNameString,\r
             (UINT8*)NewAmlNameString,\r
             NewAmlNameStringSize\r
             );\r
  ASSERT_EFI_ERROR (Status);\r
\r
exit_handler:\r
  FreePool (NewAmlNameString);\r
  return Status;\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
  @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
  EFI_STATUS              Status;\r
  AML_OBJECT_NODE_HANDLE  IntegerOpNode;\r
\r
  if ((NameOpNode == NULL)                                             ||\r
      (AmlGetNodeType ((AML_NODE_HANDLE)NameOpNode) != EAmlNodeObject) ||\r
      (!AmlNodeHasOpCode (NameOpNode, AML_NAME_OP, 0))) {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  // Get the Integer object node defined by the "Name ()" function:\r
  // it must have an Integer OpCode (Byte/Word/DWord/QWord).\r
  // It is the 2nd fixed argument (i.e. index 1) of the NameOp node.\r
  // This can also be a ZeroOp or OneOp node.\r
  IntegerOpNode = (AML_OBJECT_NODE_HANDLE)AmlGetFixedArgument (\r
                                            NameOpNode,\r
                                            EAmlParseIndexTerm1\r
                                            );\r
  if ((IntegerOpNode == NULL)  ||\r
      (AmlGetNodeType ((AML_NODE_HANDLE)IntegerOpNode) != EAmlNodeObject)) {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  // Update the Integer value.\r
  Status = AmlUpdateInteger (IntegerOpNode, NewInt);\r
  ASSERT_EFI_ERROR (Status);\r
\r
  return Status;\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
  @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
  EFI_STATUS              Status;\r
  AML_OBJECT_NODE_HANDLE  StringOpNode;\r
  AML_DATA_NODE_HANDLE    StringDataNode;\r
\r
  if ((NameOpNode == NULL)                                             ||\r
      (AmlGetNodeType ((AML_NODE_HANDLE)NameOpNode) != EAmlNodeObject) ||\r
      (!AmlNodeHasOpCode (NameOpNode, AML_NAME_OP, 0))) {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  // Get the String object node defined by the "Name ()" function:\r
  // it must have a string OpCode.\r
  // It is the 2nd fixed argument (i.e. index 1) of the NameOp node.\r
  StringOpNode = (AML_OBJECT_NODE_HANDLE)AmlGetFixedArgument (\r
                                           NameOpNode,\r
                                           EAmlParseIndexTerm1\r
                                           );\r
  if ((StringOpNode == NULL)  ||\r
      (AmlGetNodeType ((AML_NODE_HANDLE)StringOpNode) != EAmlNodeObject)) {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  // Get the string data node.\r
  // It is the 1st fixed argument (i.e. index 0) of the StringOpNode node.\r
  StringDataNode = (AML_DATA_NODE_HANDLE)AmlGetFixedArgument (\r
                                           StringOpNode,\r
                                           EAmlParseIndexTerm0\r
                                           );\r
  if ((StringDataNode == NULL)  ||\r
      (AmlGetNodeType ((AML_NODE_HANDLE)StringDataNode) != EAmlNodeData)) {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  // Update the string value.\r
  Status = AmlUpdateDataNode (\r
             StringDataNode,\r
             EAmlNodeDataTypeString,\r
             (UINT8*)NewName,\r
             (UINT32)AsciiStrLen (NewName) + 1\r
             );\r
  ASSERT_EFI_ERROR (Status);\r
\r
  return Status;\r
}\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
  @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
  AML_OBJECT_NODE_HANDLE  BufferOpNode;\r
  AML_DATA_NODE_HANDLE    FirstRdNode;\r
\r
  if ((NameOpCrsNode == NULL)                                              ||\r
      (AmlGetNodeType ((AML_NODE_HANDLE)NameOpCrsNode) != EAmlNodeObject)  ||\r
      (!AmlNodeHasOpCode (NameOpCrsNode, AML_NAME_OP, 0))                  ||\r
      (!AmlNameOpCompareName (NameOpCrsNode, "_CRS"))                      ||\r
      (OutRdNode == NULL)) {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  *OutRdNode = NULL;\r
\r
  // Get the _CRS value which is represented as a BufferOp object node\r
  // which is the 2nd fixed argument (i.e. index 1).\r
  BufferOpNode = (AML_OBJECT_NODE_HANDLE)AmlGetFixedArgument (\r
                                           NameOpCrsNode,\r
                                           EAmlParseIndexTerm1\r
                                           );\r
  if ((BufferOpNode == NULL)                                             ||\r
      (AmlGetNodeType ((AML_NODE_HANDLE)BufferOpNode) != EAmlNodeObject) ||\r
      (!AmlNodeHasOpCode (BufferOpNode, AML_BUFFER_OP, 0))) {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  // Get the first Resource data node in the variable list of\r
  // argument of the BufferOp node.\r
  FirstRdNode = (AML_DATA_NODE_HANDLE)AmlGetNextVariableArgument (\r
                                        (AML_NODE_HANDLE)BufferOpNode,\r
                                        NULL\r
                                        );\r
  if ((FirstRdNode == NULL)                                            ||\r
      (AmlGetNodeType ((AML_NODE_HANDLE)FirstRdNode) != EAmlNodeData)  ||\r
      (!AmlNodeHasDataType (FirstRdNode, EAmlNodeDataTypeResourceData))) {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  *OutRdNode = FirstRdNode;\r
  return EFI_SUCCESS;\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
  The CurrRdNode Resource Data node must be defined in an object named "_CRS"\r
  and defined by a "Name ()" ASL function.\r
\r
  @param  [in]  CurrRdNode   Pointer to the current Resource Data element of\r
                             the "_CRS" 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
AmlNameOpCrsGetNextRdNode (\r
  IN  AML_DATA_NODE_HANDLE    CurrRdNode,\r
  OUT AML_DATA_NODE_HANDLE  * OutRdNode\r
  )\r
{\r
  AML_OBJECT_NODE_HANDLE     NameOpCrsNode;\r
  AML_OBJECT_NODE_HANDLE     BufferOpNode;\r
\r
  if ((CurrRdNode == NULL)                                              ||\r
      (AmlGetNodeType ((AML_NODE_HANDLE)CurrRdNode) != EAmlNodeData)    ||\r
      (!AmlNodeHasDataType (CurrRdNode, EAmlNodeDataTypeResourceData))  ||\r
      (OutRdNode == NULL)) {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  *OutRdNode = NULL;\r
\r
  // The parent of the CurrRdNode must be a BufferOp node.\r
  BufferOpNode = (AML_OBJECT_NODE_HANDLE)AmlGetParent (\r
                                           (AML_NODE_HANDLE)CurrRdNode\r
                                           );\r
  if ((BufferOpNode == NULL)  ||\r
      (!AmlNodeHasOpCode (BufferOpNode, AML_BUFFER_OP, 0))) {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  // The parent of the BufferOpNode must be a NameOp node.\r
  NameOpCrsNode = (AML_OBJECT_NODE_HANDLE)AmlGetParent (\r
                                            (AML_NODE_HANDLE)BufferOpNode\r
                                            );\r
  if ((NameOpCrsNode == NULL)                             ||\r
      (!AmlNodeHasOpCode (NameOpCrsNode, AML_NAME_OP, 0)) ||\r
      (!AmlNameOpCompareName (NameOpCrsNode, "_CRS"))) {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  *OutRdNode = (AML_DATA_NODE_HANDLE)AmlGetNextVariableArgument (\r
                                       (AML_NODE_HANDLE)BufferOpNode,\r
                                       (AML_NODE_HANDLE)CurrRdNode\r
                                       );\r
\r
  // If the Resource Data is an End Tag, return NULL.\r
  if (AmlNodeHasRdDataType (\r
        *OutRdNode,\r
        AML_RD_BUILD_SMALL_DESC_ID (ACPI_SMALL_END_TAG_DESCRIPTOR_NAME))) {\r
    *OutRdNode = NULL;\r
  }\r
\r
  return EFI_SUCCESS;\r
}\r