DynamicTablesPkg: Change OPTIONAL keyword usage style

[mirror_edk2.git] / DynamicTablesPkg / Library / Common / AmlLib / Tree / AmlNodeInterface.c

/** @file\r
  AML Node Interface.\r
\r
  Copyright (c) 2019 - 2020, Arm Limited. All rights reserved.<BR>\r
\r
  SPDX-License-Identifier: BSD-2-Clause-Patent\r
**/\r
\r
#include <AmlNodeDefines.h>\r
\r
#include <AmlCoreInterface.h>\r
#include <ResourceData/AmlResourceData.h>\r
#include <String/AmlString.h>\r
#include <Tree/AmlNode.h>\r
#include <Tree/AmlTree.h>\r
#include <Utils/AmlUtility.h>\r
\r
/** Returns the tree node type (Root/Object/Data).\r
\r
  @param [in] Node  Pointer to a Node.\r
\r
  @return The node type.\r
           EAmlNodeUnknown if invalid parameter.\r
**/\r
EAML_NODE_TYPE\r
EFIAPI\r
AmlGetNodeType (\r
  IN  AML_NODE_HEADER   * Node\r
  )\r
{\r
  if (!IS_AML_NODE_VALID (Node)) {\r
    ASSERT (0);\r
    return EAmlNodeUnknown;\r
  }\r
\r
  return Node->NodeType;\r
}\r
\r
/** Get the RootNode information.\r
    The Node must be a root node.\r
\r
  @param  [in]  RootNode          Pointer to a root node.\r
  @param  [out] SdtHeaderBuffer   Buffer to copy the ACPI DSDT/SSDT header to.\r
\r
  @retval EFI_SUCCESS             The function completed successfully.\r
  @retval EFI_INVALID_PARAMETER   Invalid parameter.\r
**/\r
EFI_STATUS\r
EFIAPI\r
AmlGetRootNodeInfo (\r
  IN  AML_ROOT_NODE                 * RootNode,\r
  OUT EFI_ACPI_DESCRIPTION_HEADER   * SdtHeaderBuffer\r
  )\r
{\r
  if (!IS_AML_ROOT_NODE (RootNode)  ||\r
      (SdtHeaderBuffer == NULL)) {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  CopyMem (\r
    SdtHeaderBuffer,\r
    RootNode->SdtHeader,\r
    sizeof (EFI_ACPI_DESCRIPTION_HEADER)\r
    );\r
\r
  return EFI_SUCCESS;\r
}\r
\r
/** Get the ObjectNode information.\r
    The Node must be an object node.\r
\r
  @ingroup NodeInterfaceApi\r
\r
  @param  [in]  ObjectNode        Pointer to an object node.\r
  @param  [out] OpCode            Pointer holding the OpCode.\r
                                  Optional, can be NULL.\r
  @param  [out] SubOpCode         Pointer holding the SubOpCode.\r
                                  Optional, can be NULL.\r
  @param  [out] PkgLen            Pointer holding the PkgLen.\r
                                  The PkgLen is 0 for nodes\r
                                  not having the Pkglen attribute.\r
                                  Optional, can be NULL.\r
  @param  [out] IsNameSpaceNode   Pointer holding TRUE if the node is defining\r
                                  or changing the NameSpace scope.\r
                                  E.g.: The "Name ()" and "Scope ()" ASL\r
                                  statements add/modify the NameSpace scope.\r
                                  Their corresponding node are NameSpace nodes.\r
                                  Optional, can be NULL.\r
\r
  @retval EFI_SUCCESS             The function completed successfully.\r
  @retval EFI_INVALID_PARAMETER   Invalid parameter.\r
**/\r
EFI_STATUS\r
EFIAPI\r
AmlGetObjectNodeInfo (\r
  IN  AML_OBJECT_NODE   * ObjectNode,\r
  OUT UINT8             * OpCode            OPTIONAL,\r
  OUT UINT8             * SubOpCode         OPTIONAL,\r
  OUT UINT32            * PkgLen            OPTIONAL,\r
  OUT BOOLEAN           * IsNameSpaceNode   OPTIONAL\r
  )\r
{\r
  if (!IS_AML_OBJECT_NODE (ObjectNode)) {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  if (OpCode != NULL) {\r
    *OpCode = ObjectNode->AmlByteEncoding->OpCode;\r
  }\r
  if (SubOpCode != NULL) {\r
    *SubOpCode = ObjectNode->AmlByteEncoding->SubOpCode;\r
  }\r
  if (PkgLen != NULL) {\r
    *PkgLen = ObjectNode->PkgLen;\r
  }\r
  if (IsNameSpaceNode != NULL) {\r
    *IsNameSpaceNode = AmlNodeHasAttribute (ObjectNode, AML_IN_NAMESPACE);\r
  }\r
\r
  return EFI_SUCCESS;\r
}\r
\r
/** Returns the count of the fixed arguments for the input Node.\r
\r
  @param  [in]  Node  Pointer to an object node.\r
\r
  @return Number of fixed arguments of the object node.\r
          Return 0 if the node is not an object node.\r
**/\r
UINT8\r
AmlGetFixedArgumentCount (\r
  IN  AML_OBJECT_NODE   * Node\r
  )\r
{\r
  if (IS_AML_OBJECT_NODE (Node) &&\r
      (Node->AmlByteEncoding != NULL)) {\r
    return (UINT8)Node->AmlByteEncoding->MaxIndex;\r
  }\r
\r
  return 0;\r
}\r
\r
/** Get the data type of the DataNode.\r
    The Node must be a data node.\r
\r
  @param  [in]  DataNode  Pointer to a data node.\r
  @param  [out] DataType  Pointer holding the data type of the data buffer.\r
\r
  @retval EFI_SUCCESS             The function completed successfully.\r
  @retval EFI_INVALID_PARAMETER   Invalid parameter.\r
**/\r
EFI_STATUS\r
EFIAPI\r
AmlGetNodeDataType (\r
  IN  AML_DATA_NODE       * DataNode,\r
  OUT EAML_NODE_DATA_TYPE * DataType\r
  )\r
{\r
  if (!IS_AML_DATA_NODE (DataNode)  ||\r
      (DataType == NULL)) {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  *DataType = DataNode->DataType;\r
\r
  return EFI_SUCCESS;\r
}\r
\r
/** Get the descriptor Id of the resource data element\r
    contained in the DataNode.\r
\r
  The Node must be a data node.\r
  The Node must have the resource data type, i.e. have the\r
  EAmlNodeDataTypeResourceData data type.\r
\r
  @param  [in]  DataNode          Pointer to a data node containing a\r
                                  resource data element.\r
  @param  [out] ResourceDataType  Pointer holding the descriptor Id of\r
                                  the resource data.\r
\r
  @retval EFI_SUCCESS             The function completed successfully.\r
  @retval EFI_INVALID_PARAMETER   Invalid parameter.\r
**/\r
EFI_STATUS\r
EFIAPI\r
AmlGetResourceDataType (\r
  IN  AML_DATA_NODE   * DataNode,\r
  OUT AML_RD_HEADER   * ResourceDataType\r
  )\r
{\r
  if (!IS_AML_DATA_NODE (DataNode)  ||\r
      (ResourceDataType == NULL)    ||\r
      (DataNode->DataType != EAmlNodeDataTypeResourceData)) {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  *ResourceDataType = AmlRdGetDescId (DataNode->Buffer);\r
\r
  return EFI_SUCCESS;\r
}\r
\r
/** Get the data buffer and size of the DataNode.\r
    The Node must be a data node.\r
\r
  BufferSize is always updated to the size of buffer of the DataNode.\r
\r
  If:\r
   - the content of BufferSize is >= to the DataNode's buffer size;\r
   - Buffer is not NULL;\r
  then copy the content of the DataNode's buffer in Buffer.\r
\r
  @param  [in]      DataNode      Pointer to a data node.\r
  @param  [out]     Buffer        Buffer to write the data to.\r
                                  Optional, if NULL, only update BufferSize.\r
  @param  [in, out] BufferSize    Pointer holding:\r
                                   - At entry, the size of the Buffer;\r
                                   - At exit, the size of the DataNode's\r
                                     buffer size.\r
\r
  @retval EFI_SUCCESS           The function completed successfully.\r
  @retval EFI_INVALID_PARAMETER Invalid parameter.\r
**/\r
EFI_STATUS\r
EFIAPI\r
AmlGetDataNodeBuffer (\r
  IN      AML_DATA_NODE   * DataNode,\r
      OUT UINT8           * Buffer        OPTIONAL,\r
  IN  OUT UINT32          * BufferSize\r
  )\r
{\r
  if (!IS_AML_DATA_NODE (DataNode) ||\r
      (BufferSize == NULL)) {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  if ((*BufferSize >= DataNode->Size)  &&\r
      (Buffer != NULL)) {\r
    CopyMem (Buffer, DataNode->Buffer, DataNode->Size);\r
  }\r
\r
  *BufferSize = DataNode->Size;\r
\r
  return EFI_SUCCESS;\r
}\r
\r
/** Update the ACPI DSDT/SSDT table header.\r
\r
  The input SdtHeader information is copied to the tree RootNode.\r
  The table Length field is automatically updated.\r
  The checksum field is only updated when serializing the tree.\r
\r
  @param  [in]  RootNode    Pointer to a root node.\r
  @param  [in]  SdtHeader   Pointer to an ACPI DSDT/SSDT table header.\r
\r
  @retval EFI_SUCCESS             The function completed successfully.\r
  @retval EFI_INVALID_PARAMETER   Invalid parameter.\r
**/\r
EFI_STATUS\r
EFIAPI\r
AmlUpdateRootNode (\r
  IN        AML_ROOT_NODE                 * RootNode,\r
  IN  CONST EFI_ACPI_DESCRIPTION_HEADER   * SdtHeader\r
  )\r
{\r
  EFI_STATUS  Status;\r
  UINT32      Length;\r
\r
  if (!IS_AML_ROOT_NODE (RootNode)  ||\r
      (SdtHeader == NULL)           ||\r
      ((SdtHeader->Signature !=\r
        EFI_ACPI_6_3_SECONDARY_SYSTEM_DESCRIPTION_TABLE_SIGNATURE) &&\r
       (SdtHeader->Signature !=\r
        EFI_ACPI_6_3_DIFFERENTIATED_SYSTEM_DESCRIPTION_TABLE_SIGNATURE))) {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  CopyMem (\r
    RootNode->SdtHeader,\r
    SdtHeader,\r
    sizeof (EFI_ACPI_DESCRIPTION_HEADER)\r
    );\r
\r
  // Update the Length field.\r
  Status = AmlComputeSize ((AML_NODE_HEADER*)RootNode, &Length);\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    return Status;\r
  }\r
\r
  RootNode->SdtHeader->Length = Length +\r
                                  (UINT32)sizeof (EFI_ACPI_DESCRIPTION_HEADER);\r
\r
  return Status;\r
}\r
\r
/** Update an object node representing an integer with a new value.\r
\r
  The object node must have one of the following OpCodes:\r
   - AML_BYTE_PREFIX\r
   - AML_WORD_PREFIX\r
   - AML_DWORD_PREFIX\r
   - AML_QWORD_PREFIX\r
   - AML_ZERO_OP\r
   - AML_ONE_OP\r
\r
  The following OpCode is not supported:\r
   - AML_ONES_OP\r
\r
  @param  [in] IntegerOpNode   Pointer an object node containing an integer.\r
                               Must not be an object node with an AML_ONES_OP\r
                               OpCode.\r
  @param  [in] NewInteger      New integer value to set.\r
\r
  @retval EFI_SUCCESS             The function completed successfully.\r
  @retval EFI_INVALID_PARAMETER   Invalid parameter.\r
**/\r
EFI_STATUS\r
EFIAPI\r
AmlUpdateInteger (\r
  IN  AML_OBJECT_NODE   * IntegerOpNode,\r
  IN  UINT64              NewInteger\r
  )\r
{\r
  EFI_STATUS   Status;\r
\r
  INT8         ValueWidthDiff;\r
\r
  if (!IS_AML_OBJECT_NODE (IntegerOpNode)     ||\r
      (!IsIntegerNode (IntegerOpNode)         &&\r
       !IsSpecialIntegerNode (IntegerOpNode)) ||\r
      AmlNodeCompareOpCode (IntegerOpNode, AML_ONES_OP, 0)) {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  Status = AmlNodeSetIntegerValue (IntegerOpNode, NewInteger, &ValueWidthDiff);\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    return Status;\r
  }\r
\r
  // If the new size is different from the old size, propagate the new size.\r
  if (ValueWidthDiff != 0) {\r
    // Propagate the information.\r
    Status = AmlPropagateInformation (\r
               (AML_NODE_HEADER*)IntegerOpNode,\r
               (ValueWidthDiff > 0) ? TRUE : FALSE,\r
               ABS (ValueWidthDiff),\r
               0\r
               );\r
    if (EFI_ERROR (Status)) {\r
      ASSERT (0);\r
    }\r
  }\r
\r
  return Status;\r
}\r
\r
/** Update the buffer of a data node.\r
\r
  Note: The data type of the buffer's content must match the data type of the\r
        DataNode. This is a hard restriction to prevent undesired behaviour.\r
\r
  @param  [in]  DataNode  Pointer to a data node.\r
  @param  [in]  DataType  Data type of the Buffer's content.\r
  @param  [in]  Buffer    Buffer containing the new data. The content of\r
                          the Buffer is copied.\r
  @param  [in]  Size      Size of the Buffer.\r
\r
  @retval EFI_SUCCESS             The function completed successfully.\r
  @retval EFI_INVALID_PARAMETER   Invalid parameter.\r
  @retval EFI_UNSUPPORTED         Operation not supporter.\r
**/\r
EFI_STATUS\r
EFIAPI\r
AmlUpdateDataNode (\r
  IN  AML_DATA_NODE         * DataNode,\r
  IN  EAML_NODE_DATA_TYPE     DataType,\r
  IN  UINT8                 * Buffer,\r
  IN  UINT32                  Size\r
  )\r
{\r
  EFI_STATUS              Status;\r
\r
  UINT32                  ExpectedSize;\r
  AML_OBJECT_NODE       * ParentNode;\r
  EAML_NODE_DATA_TYPE     ExpectedArgType;\r
  EAML_PARSE_INDEX        Index;\r
\r
  if (!IS_AML_DATA_NODE (DataNode)      ||\r
      (DataType > EAmlNodeDataTypeMax)  ||\r
      (Buffer == NULL)                  ||\r
      (Size == 0)) {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  ParentNode = (AML_OBJECT_NODE*)AmlGetParent ((AML_NODE_HEADER*)DataNode);\r
  if (!IS_AML_OBJECT_NODE (ParentNode)) {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  // The NewNode and OldNode must have the same type.\r
  // We do not allow to change the argument type of a data node.\r
  // If required, the initial ASL template should be modified\r
  // accordingly.\r
  // It is however possible to interchange a raw buffer and a\r
  // resource data element, since raw data can be misinterpreted\r
  // as a resource data element.\r
  ExpectedArgType = DataNode->DataType;\r
  if ((ExpectedArgType != DataType)                         &&\r
      (((ExpectedArgType != EAmlNodeDataTypeRaw)            &&\r
        (ExpectedArgType != EAmlNodeDataTypeResourceData))  ||\r
       ((DataType != EAmlNodeDataTypeRaw)                   &&\r
        (DataType != EAmlNodeDataTypeResourceData)))) {\r
    ASSERT (0);\r
    return EFI_UNSUPPORTED;\r
  }\r
\r
  // Perform some compatibility checks.\r
  switch (DataType) {\r
    case EAmlNodeDataTypeNameString:\r
    {\r
      // Check the name contained in the Buffer is an AML name\r
      // with the right size.\r
      Status = AmlGetNameStringSize ((CONST CHAR8*)Buffer, &ExpectedSize);\r
      if (EFI_ERROR (Status)  ||\r
          (Size != ExpectedSize)) {\r
        ASSERT (0);\r
        return Status;\r
      }\r
      break;\r
    }\r
    case EAmlNodeDataTypeString:\r
    {\r
      ExpectedSize = 0;\r
      while (ExpectedSize < Size) {\r
        // Cf ACPI 6.3 specification 20.2.3 Data Objects Encoding.\r
        // AsciiCharList := Nothing | <AsciiChar AsciiCharList>\r
        // AsciiChar := 0x01 - 0x7F\r
        // NullChar := 0x00\r
        if (Buffer[ExpectedSize] > 0x7F) {\r
          ASSERT (0);\r
          return EFI_INVALID_PARAMETER;\r
        }\r
        ExpectedSize++;\r
      }\r
\r
      if (ExpectedSize != Size) {\r
        ASSERT (0);\r
        return EFI_INVALID_PARAMETER;\r
      }\r
      break;\r
    }\r
    case EAmlNodeDataTypeUInt:\r
    {\r
      if (AmlIsNodeFixedArgument ((CONST AML_NODE_HEADER*)DataNode, &Index)) {\r
        if ((ParentNode->AmlByteEncoding == NULL) ||\r
            (ParentNode->AmlByteEncoding->Format == NULL)) {\r
          ASSERT (0);\r
          return EFI_INVALID_PARAMETER;\r
        }\r
\r
        // It is not possible to change the size of a fixed length UintX.\r
        // E.g. for PackageOp the first fixed argument is of type EAmlUInt8\r
        // and represents the count of elements. This type cannot be changed.\r
        if ((ParentNode->AmlByteEncoding->Format[Index] != EAmlObject) &&\r
            (DataNode->Size != Size)) {\r
          ASSERT (0);\r
          return EFI_UNSUPPORTED;\r
        }\r
      }\r
      break;\r
    }\r
    case EAmlNodeDataTypeRaw:\r
    {\r
      // Check if the parent node has the byte list flag set.\r
      if (!AmlNodeHasAttribute (ParentNode, AML_HAS_BYTE_LIST)) {\r
        ASSERT (0);\r
        return EFI_INVALID_PARAMETER;\r
      }\r
      break;\r
    }\r
    case EAmlNodeDataTypeResourceData:\r
    {\r
      // The resource data can be either small or large resource data.\r
      // Small resource data must be at least 1 byte.\r
      // Large resource data must be at least as long as the header\r
      // of a large resource data.\r
      if (AML_RD_IS_LARGE (Buffer)  &&\r
          (Size < sizeof (ACPI_LARGE_RESOURCE_HEADER))) {\r
        ASSERT (0);\r
        return EFI_INVALID_PARAMETER;\r
      }\r
\r
      // Check if the parent node has the byte list flag set.\r
      if (!AmlNodeHasAttribute (ParentNode, AML_HAS_BYTE_LIST)) {\r
        ASSERT (0);\r
        return EFI_INVALID_PARAMETER;\r
      }\r
\r
      // Check the size of the buffer is equal to the resource data size\r
      // encoded in the input buffer.\r
      ExpectedSize = AmlRdGetSize (Buffer);\r
      if (ExpectedSize != Size) {\r
        ASSERT (0);\r
        return EFI_INVALID_PARAMETER;\r
      }\r
\r
      Status = AmlSetRdListCheckSum (ParentNode, 0);\r
      if (EFI_ERROR (Status)) {\r
        ASSERT (0);\r
        return Status;\r
      }\r
\r
      break;\r
    }\r
    case EAmlNodeDataTypeFieldPkgLen:\r
    {\r
      // Check the parent is a FieldNamed field element.\r
      if (!AmlNodeCompareOpCode (ParentNode, AML_FIELD_NAMED_OP, 0)) {\r
        ASSERT (0);\r
        return EFI_INVALID_PARAMETER;\r
      }\r
      break;\r
    }\r
    // None and reserved types.\r
    default:\r
    {\r
      ASSERT (0);\r
      return EFI_INVALID_PARAMETER;\r
      break;\r
    }\r
  } // switch\r
\r
  // If the new size is different from the old size, propagate the new size.\r
  if (DataNode->Size != Size) {\r
    // Propagate the information.\r
    Status = AmlPropagateInformation (\r
               DataNode->NodeHeader.Parent,\r
               (Size > DataNode->Size) ? TRUE : FALSE,\r
               (Size > DataNode->Size) ?\r
                (Size - DataNode->Size) :\r
                (DataNode->Size - Size),\r
               0\r
               );\r
    if (EFI_ERROR (Status)) {\r
      ASSERT (0);\r
      return Status;\r
    }\r
\r
    // Free the old DataNode buffer and allocate a new buffer to store the\r
    // new data.\r
    FreePool (DataNode->Buffer);\r
    DataNode->Buffer = AllocateZeroPool (Size);\r
    if (DataNode->Buffer == NULL) {\r
      ASSERT (0);\r
      return EFI_OUT_OF_RESOURCES;\r
    }\r
    DataNode->Size = Size;\r
  }\r
\r
  CopyMem (DataNode->Buffer, Buffer, Size);\r
\r
  return EFI_SUCCESS;\r
}\r