[mirror_edk2.git] / DynamicTablesPkg / Library / Common / AmlLib / Utils / AmlUtility.c

/** @file\r
  AML Utility.\r
\r
  Copyright (c) 2019 - 2021, Arm Limited. All rights reserved.<BR>\r
\r
  SPDX-License-Identifier: BSD-2-Clause-Patent\r
**/\r
\r
#include <Utils/AmlUtility.h>\r
\r
#include <AmlCoreInterface.h>\r
#include <Tree/AmlNode.h>\r
#include <Tree/AmlTree.h>\r
\r
/** This function computes and updates the ACPI table checksum.\r
\r
  @param  [in]  AcpiTable   Pointer to an Acpi table.\r
\r
  @retval EFI_SUCCESS   The function completed successfully.\r
  @retval EFI_INVALID_PARAMETER   Invalid parameter.\r
**/\r
EFI_STATUS\r
EFIAPI\r
AcpiPlatformChecksum (\r
  IN  EFI_ACPI_DESCRIPTION_HEADER  *AcpiTable\r
  )\r
{\r
  UINT8   *Ptr;\r
  UINT8   Sum;\r
  UINT32  Size;\r
\r
  if (AcpiTable == NULL) {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  Ptr  = (UINT8 *)AcpiTable;\r
  Size = AcpiTable->Length;\r
  Sum  = 0;\r
\r
  // Set the checksum field to 0 first.\r
  AcpiTable->Checksum = 0;\r
\r
  // Compute the checksum.\r
  while ((Size--) != 0) {\r
    Sum = (UINT8)(Sum + (*Ptr++));\r
  }\r
\r
  // Set the checksum.\r
  AcpiTable->Checksum = (UINT8)(0xFF - Sum + 1);\r
\r
  return EFI_SUCCESS;\r
}\r
\r
/** A callback function that computes the size of a Node and adds it to the\r
    Size pointer stored in the Context.\r
    Calling this function on the root node will compute the total size of the\r
    AML bytestream.\r
\r
  @param  [in]      Node      Node to compute the size.\r
  @param  [in, out] Context   Pointer holding the computed size.\r
                              (UINT32 *) Context.\r
  @param  [in, out] Status    Pointer holding:\r
                               - At entry, the Status returned by the\r
                                 last call to this exact function during\r
                                 the enumeration;\r
                               - At exit, he returned status of the\r
                                 call to this function.\r
                              Optional, can be NULL.\r
\r
  @retval TRUE if the enumeration can continue or has finished without\r
          interruption.\r
  @retval FALSE if the enumeration needs to stopped or has stopped.\r
**/\r
STATIC\r
BOOLEAN\r
EFIAPI\r
AmlComputeSizeCallback (\r
  IN      AML_NODE_HEADER  *Node,\r
  IN  OUT VOID             *Context,\r
  IN  OUT EFI_STATUS       *Status   OPTIONAL\r
  )\r
{\r
  UINT32                 Size;\r
  EAML_PARSE_INDEX       IndexPtr;\r
  CONST AML_OBJECT_NODE  *ParentNode;\r
\r
  if (!IS_AML_NODE_VALID (Node) ||\r
      (Context == NULL))\r
  {\r
    ASSERT (0);\r
    if (Status != NULL) {\r
      *Status = EFI_INVALID_PARAMETER;\r
    }\r
\r
    return FALSE;\r
  }\r
\r
  // Ignore the second fixed argument of method invocation nodes\r
  // as the information stored there (the argument count) is not in the\r
  // ACPI specification.\r
  ParentNode = (CONST AML_OBJECT_NODE *)AmlGetParent (Node);\r
  if (IS_AML_OBJECT_NODE (ParentNode)                             &&\r
      AmlNodeCompareOpCode (ParentNode, AML_METHOD_INVOC_OP, 0)   &&\r
      AmlIsNodeFixedArgument (Node, &IndexPtr))\r
  {\r
    if (IndexPtr == EAmlParseIndexTerm1) {\r
      if (Status != NULL) {\r
        *Status = EFI_SUCCESS;\r
      }\r
\r
      return TRUE;\r
    }\r
  }\r
\r
  Size = *((UINT32 *)Context);\r
\r
  if (IS_AML_DATA_NODE (Node)) {\r
    Size += ((AML_DATA_NODE *)Node)->Size;\r
  } else if (IS_AML_OBJECT_NODE (Node)  &&\r
             !AmlNodeHasAttribute (\r
                (CONST AML_OBJECT_NODE *)Node,\r
                AML_IS_PSEUDO_OPCODE\r
                ))\r
  {\r
    // Ignore pseudo-opcodes as they are not part of the\r
    // ACPI specification.\r
\r
    Size += (((AML_OBJECT_NODE *)Node)->AmlByteEncoding->OpCode ==\r
             AML_EXT_OP) ? 2 : 1;\r
\r
    // Add the size of the PkgLen.\r
    if (AmlNodeHasAttribute (\r
          (AML_OBJECT_NODE *)Node,\r
          AML_HAS_PKG_LENGTH\r
          ))\r
    {\r
      Size += AmlComputePkgLengthWidth (((AML_OBJECT_NODE *)Node)->PkgLen);\r
    }\r
  }\r
\r
  // Check for overflow.\r
  // The root node has a null size, thus the strict comparison.\r
  if (*((UINT32 *)Context) > Size) {\r
    ASSERT (0);\r
    *Status = EFI_INVALID_PARAMETER;\r
    return FALSE;\r
  }\r
\r
  *((UINT32 *)Context) = Size;\r
\r
  if (Status != NULL) {\r
    *Status = EFI_SUCCESS;\r
  }\r
\r
  return TRUE;\r
}\r
\r
/** Compute the size of a tree/sub-tree.\r
\r
  @param  [in]      Node      Node to compute the size.\r
  @param  [in, out] Size      Pointer holding the computed size.\r
\r
  @retval EFI_SUCCESS             The function completed successfully.\r
  @retval EFI_INVALID_PARAMETER   Invalid parameter.\r
**/\r
EFI_STATUS\r
EFIAPI\r
AmlComputeSize (\r
  IN      CONST AML_NODE_HEADER  *Node,\r
  IN  OUT       UINT32           *Size\r
  )\r
{\r
  EFI_STATUS  Status;\r
\r
  if (!IS_AML_NODE_VALID (Node) ||\r
      (Size == NULL))\r
  {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  *Size = 0;\r
\r
  AmlEnumTree (\r
    (AML_NODE_HEADER *)Node,\r
    AmlComputeSizeCallback,\r
    (VOID *)Size,\r
    &Status\r
    );\r
\r
  return Status;\r
}\r
\r
/** Get the value contained in an integer node.\r
\r
  @param  [in]  Node    Pointer to an integer node.\r
                        Must be an object node.\r
  @param  [out] Value   Value contained in the integer node.\r
\r
  @retval EFI_SUCCESS             The function completed successfully.\r
  @retval EFI_INVALID_PARAMETER   Invalid parameter.\r
**/\r
EFI_STATUS\r
EFIAPI\r
AmlNodeGetIntegerValue (\r
  IN  AML_OBJECT_NODE  *Node,\r
  OUT UINT64           *Value\r
  )\r
{\r
  AML_DATA_NODE  *DataNode;\r
\r
  if ((!IsIntegerNode (Node)            &&\r
       !IsSpecialIntegerNode (Node))    ||\r
      (Value == NULL))\r
  {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  // For ZeroOp and OneOp, there is no data node.\r
  if (IsSpecialIntegerNode (Node)) {\r
    if (AmlNodeCompareOpCode (Node, AML_ZERO_OP, 0)) {\r
      *Value = 0;\r
    } else if (AmlNodeCompareOpCode (Node, AML_ONE_OP, 0)) {\r
      *Value = 1;\r
    } else {\r
      // OnesOp cannot be handled: it represents a maximum value.\r
      ASSERT (0);\r
      return EFI_INVALID_PARAMETER;\r
    }\r
\r
    return EFI_SUCCESS;\r
  }\r
\r
  // For integer nodes, the value is in the first fixed argument.\r
  DataNode = (AML_DATA_NODE *)Node->FixedArgs[EAmlParseIndexTerm0];\r
  if (!IS_AML_DATA_NODE (DataNode) ||\r
      (DataNode->DataType != EAmlNodeDataTypeUInt))\r
  {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  switch (DataNode->Size) {\r
    case 1:\r
    {\r
      *Value = *((UINT8 *)(DataNode->Buffer));\r
      break;\r
    }\r
    case 2:\r
    {\r
      *Value = *((UINT16 *)(DataNode->Buffer));\r
      break;\r
    }\r
    case 4:\r
    {\r
      *Value = *((UINT32 *)(DataNode->Buffer));\r
      break;\r
    }\r
    case 8:\r
    {\r
      *Value = *((UINT64 *)(DataNode->Buffer));\r
      break;\r
    }\r
    default:\r
    {\r
      ASSERT (0);\r
      return EFI_INVALID_PARAMETER;\r
    }\r
  } // switch\r
\r
  return EFI_SUCCESS;\r
}\r
\r
/** Replace a Zero (AML_ZERO_OP) or One (AML_ONE_OP) object node\r
    with a byte integer (AML_BYTE_PREFIX) object node having the same value.\r
\r
  @param  [in]  Node    Pointer to an integer node.\r
                        Must be an object node having ZeroOp or OneOp.\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
AmlUnwindSpecialInteger (\r
  IN  AML_OBJECT_NODE  *Node\r
  )\r
{\r
  EFI_STATUS  Status;\r
\r
  AML_DATA_NODE            *NewDataNode;\r
  UINT8                    Value;\r
  CONST AML_BYTE_ENCODING  *ByteEncoding;\r
\r
  if (!IsSpecialIntegerNode (Node)) {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  // Find the value.\r
  if (AmlNodeCompareOpCode (Node, AML_ZERO_OP, 0)) {\r
    Value = 0;\r
  } else if (AmlNodeCompareOpCode (Node, AML_ONE_OP, 0)) {\r
    Value = 1;\r
  } else {\r
    // OnesOp cannot be handled: it represents a maximum value.\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  Status = AmlCreateDataNode (\r
             EAmlNodeDataTypeUInt,\r
             &Value,\r
             sizeof (UINT8),\r
             (AML_DATA_NODE **)&NewDataNode\r
             );\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    return Status;\r
  }\r
\r
  // Change the encoding of the special node to a ByteOp encoding.\r
  ByteEncoding = AmlGetByteEncodingByOpCode (AML_BYTE_PREFIX, 0);\r
  if (ByteEncoding == NULL) {\r
    ASSERT (0);\r
    Status = EFI_INVALID_PARAMETER;\r
    goto error_handler;\r
  }\r
\r
  // Update the ByteEncoding from ZERO_OP/ONE_OP to AML_BYTE_PREFIX.\r
  Node->AmlByteEncoding = ByteEncoding;\r
\r
  // Add the data node as the first fixed argument of the ByteOp object.\r
  Status = AmlSetFixedArgument (\r
             (AML_OBJECT_NODE *)Node,\r
             EAmlParseIndexTerm0,\r
             (AML_NODE_HEADER *)NewDataNode\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 *)NewDataNode);\r
  return Status;\r
}\r
\r
/** Set the value contained in an integer node.\r
\r
  The OpCode is updated accordingly to the new value\r
  (e.g.: If the original value was a UINT8 value, then the OpCode\r
         would be AML_BYTE_PREFIX. If it the new value is a UINT16\r
         value then the OpCode will be updated to AML_WORD_PREFIX).\r
\r
  @param  [in]  Node            Pointer to an integer node.\r
                                Must be an object node.\r
  @param  [in]  NewValue        New value to write in the integer node.\r
  @param  [out] ValueWidthDiff  Difference in number of bytes used to store\r
                                the new value.\r
                                Can be negative.\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
AmlNodeSetIntegerValue (\r
  IN  AML_OBJECT_NODE  *Node,\r
  IN  UINT64           NewValue,\r
  OUT INT8             *ValueWidthDiff\r
  )\r
{\r
  EFI_STATUS     Status;\r
  AML_DATA_NODE  *DataNode;\r
\r
  UINT8  NewOpCode;\r
  UINT8  NumberOfBytes;\r
\r
  if ((!IsIntegerNode (Node)            &&\r
       !IsSpecialIntegerNode (Node))    ||\r
      (ValueWidthDiff == NULL))\r
  {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  *ValueWidthDiff = 0;\r
  // For ZeroOp and OneOp, there is no data node.\r
  // Thus the object node is converted to a byte object node holding 0 or 1.\r
  if (IsSpecialIntegerNode (Node)) {\r
    switch (NewValue) {\r
      case AML_ZERO_OP:\r
        Node->AmlByteEncoding = AmlGetByteEncodingByOpCode (AML_ZERO_OP, 0);\r
        return EFI_SUCCESS;\r
      case AML_ONE_OP:\r
        Node->AmlByteEncoding = AmlGetByteEncodingByOpCode (AML_ONE_OP, 0);\r
        return EFI_SUCCESS;\r
      default:\r
      {\r
        Status = AmlUnwindSpecialInteger (Node);\r
        if (EFI_ERROR (Status)) {\r
          ASSERT (0);\r
          return Status;\r
        }\r
\r
        // The AmlUnwindSpecialInteger functions converts a special integer\r
        // node to a UInt8/Byte data node. Thus, the size increments by one:\r
        // special integer are encoded as one byte (the opcode only) while byte\r
        // integers are encoded as two bytes (the opcode + the value).\r
        *ValueWidthDiff += sizeof (UINT8);\r
      }\r
    } // switch\r
  } // IsSpecialIntegerNode (Node)\r
\r
  // For integer nodes, the value is in the first fixed argument.\r
  DataNode = (AML_DATA_NODE *)Node->FixedArgs[EAmlParseIndexTerm0];\r
  if (!IS_AML_DATA_NODE (DataNode) ||\r
      (DataNode->DataType != EAmlNodeDataTypeUInt))\r
  {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  // The value can be encoded with a special 0 or 1 OpCode.\r
  // The AML_ONES_OP is not handled.\r
  if (NewValue <= 1) {\r
    NewOpCode             = (NewValue == 0) ? AML_ZERO_OP : AML_ONE_OP;\r
    Node->AmlByteEncoding = AmlGetByteEncodingByOpCode (NewOpCode, 0);\r
\r
    // The value is encoded with a AML_ZERO_OP or AML_ONE_OP.\r
    // This means there is no need for a DataNode containing the value.\r
    // The change in size is equal to the size of the DataNode's buffer.\r
    *ValueWidthDiff = -((INT8)DataNode->Size);\r
\r
    // Detach and free the DataNode containing the integer value.\r
    DataNode->NodeHeader.Parent          = NULL;\r
    Node->FixedArgs[EAmlParseIndexTerm0] = NULL;\r
    Status                               = AmlDeleteNode ((AML_NODE_HEADER *)DataNode);\r
    if (EFI_ERROR (Status)) {\r
      ASSERT (0);\r
      return Status;\r
    }\r
\r
    return EFI_SUCCESS;\r
  }\r
\r
  // Check the number of bits needed to represent the value.\r
  if (NewValue > MAX_UINT32) {\r
    // Value is 64 bits.\r
    NewOpCode     = AML_QWORD_PREFIX;\r
    NumberOfBytes = 8;\r
  } else if (NewValue > MAX_UINT16) {\r
    // Value is 32 bits.\r
    NewOpCode     = AML_DWORD_PREFIX;\r
    NumberOfBytes = 4;\r
  } else if (NewValue > MAX_UINT8) {\r
    // Value is 16 bits.\r
    NewOpCode     = AML_WORD_PREFIX;\r
    NumberOfBytes = 2;\r
  } else {\r
    // Value is 8 bits.\r
    NewOpCode     = AML_BYTE_PREFIX;\r
    NumberOfBytes = 1;\r
  }\r
\r
  *ValueWidthDiff += (INT8)(NumberOfBytes - DataNode->Size);\r
\r
  // Update the ByteEncoding as it may have changed between [8 .. 64] bits.\r
  Node->AmlByteEncoding = AmlGetByteEncodingByOpCode (NewOpCode, 0);\r
  if (Node->AmlByteEncoding == NULL) {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  // Free the old DataNode buffer and allocate a buffer with the right size\r
  // to store the new data.\r
  if (*ValueWidthDiff != 0) {\r
    FreePool (DataNode->Buffer);\r
    DataNode->Buffer = AllocateZeroPool (NumberOfBytes);\r
    if (DataNode->Buffer == NULL) {\r
      ASSERT (0);\r
      return EFI_OUT_OF_RESOURCES;\r
    }\r
\r
    DataNode->Size = NumberOfBytes;\r
  }\r
\r
  // Write the new value.\r
  CopyMem (DataNode->Buffer, &NewValue, NumberOfBytes);\r
\r
  return EFI_SUCCESS;\r
}\r
\r
/** Increment/decrement the value contained in the IntegerNode.\r
\r
  @param  [in]  IntegerNode     Pointer to an object node containing\r
                                an integer.\r
  @param  [in]  IsIncrement     Choose the operation to do:\r
                                 - TRUE:  Increment the Node's size and\r
                                          the Node's count;\r
                                 - FALSE: Decrement the Node's size and\r
                                          the Node's count.\r
  @param  [in]  Diff            Value to add/subtract to the integer.\r
  @param  [out] ValueWidthDiff  When modifying the integer, it can be\r
                                promoted/demoted, e.g. from UINT8 to UINT16.\r
                                Stores the change in width.\r
                                Can be negative.\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
AmlNodeUpdateIntegerValue (\r
  IN  AML_OBJECT_NODE  *IntegerNode,\r
  IN  BOOLEAN          IsIncrement,\r
  IN  UINT64           Diff,\r
  OUT INT8             *ValueWidthDiff\r
  )\r
{\r
  EFI_STATUS  Status;\r
  UINT64      Value;\r
\r
  if (ValueWidthDiff == NULL) {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  // Get the current value.\r
  // Checks on the IntegerNode are done in the call.\r
  Status = AmlNodeGetIntegerValue (IntegerNode, &Value);\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    return Status;\r
  }\r
\r
  // Check for UINT64 over/underflow.\r
  if ((IsIncrement && (Value > (MAX_UINT64 - Diff))) ||\r
      (!IsIncrement && (Value < Diff)))\r
  {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  // Compute the new value.\r
  if (IsIncrement) {\r
    Value += Diff;\r
  } else {\r
    Value -= Diff;\r
  }\r
\r
  Status = AmlNodeSetIntegerValue (\r
             IntegerNode,\r
             Value,\r
             ValueWidthDiff\r
             );\r
  ASSERT_EFI_ERROR (Status);\r
  return Status;\r
}\r
\r
/** Propagate the size information up the tree.\r
\r
  The length of the ACPI table is updated in the RootNode,\r
  but not the checksum.\r
\r
  @param  [in]  Node          Pointer to a node.\r
                              Must be a root node or an object node.\r
  @param  [in]  IsIncrement   Choose the operation to do:\r
                               - TRUE:  Increment the Node's size and\r
                                        the Node's count;\r
                               - FALSE: Decrement the Node's size and\r
                                        the Node's count.\r
  @param  [in]  Diff          Value to add/subtract to the Node's size.\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
AmlPropagateSize (\r
  IN  AML_NODE_HEADER  *Node,\r
  IN  BOOLEAN          IsIncrement,\r
  IN  UINT32           *Diff\r
  )\r
{\r
  EFI_STATUS       Status;\r
  AML_OBJECT_NODE  *ObjectNode;\r
  AML_NODE_HEADER  *ParentNode;\r
\r
  UINT32  Value;\r
  UINT32  InitialPkgLenWidth;\r
  UINT32  NewPkgLenWidth;\r
  UINT32  ReComputedPkgLenWidth;\r
  INT8    FieldWidthChange;\r
\r
  if (!IS_AML_OBJECT_NODE (Node) &&\r
      !IS_AML_ROOT_NODE (Node))\r
  {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  if (IS_AML_OBJECT_NODE (Node)) {\r
    ObjectNode = (AML_OBJECT_NODE *)Node;\r
\r
    // For BufferOp, the buffer size is stored in BufferSize. Therefore,\r
    // BufferOp needs special handling to update the BufferSize.\r
    // BufferSize must be updated before the PkgLen to accommodate any\r
    // increment resulting from the update of the BufferSize.\r
    // DefBuffer := BufferOp PkgLength BufferSize ByteList\r
    // BufferOp := 0x11\r
    // BufferSize := TermArg => Integer\r
    if (AmlNodeCompareOpCode (ObjectNode, AML_BUFFER_OP, 0)) {\r
      // First fixed argument of BufferOp is an integer (BufferSize)\r
      // (can be a BYTE, WORD, DWORD or QWORD).\r
      // BufferSize is an object node.\r
      Status = AmlNodeUpdateIntegerValue (\r
                 (AML_OBJECT_NODE *)AmlGetFixedArgument (\r
                                      ObjectNode,\r
                                      EAmlParseIndexTerm0\r
                                      ),\r
                 IsIncrement,\r
                 (UINT64)(*Diff),\r
                 &FieldWidthChange\r
                 );\r
      if (EFI_ERROR (Status)) {\r
        ASSERT (0);\r
        return Status;\r
      }\r
\r
      // FieldWidthChange is an integer.\r
      // It must be positive if IsIncrement is TRUE, negative otherwise.\r
      if ((IsIncrement              &&\r
           (FieldWidthChange < 0))  ||\r
          (!IsIncrement             &&\r
           (FieldWidthChange > 0)))\r
      {\r
        ASSERT (0);\r
        return EFI_INVALID_PARAMETER;\r
      }\r
\r
      // Check for UINT32 overflow.\r
      if (*Diff > (MAX_UINT32 - (UINT32)ABS (FieldWidthChange))) {\r
        ASSERT (0);\r
        return EFI_INVALID_PARAMETER;\r
      }\r
\r
      // Update Diff if the field width changed.\r
      *Diff = (UINT32)(*Diff + ABS (FieldWidthChange));\r
    } // AML_BUFFER_OP node.\r
\r
    // Update the PgkLen.\r
    // Needs to be done at last to reflect the potential field width changes.\r
    if (AmlNodeHasAttribute (ObjectNode, AML_HAS_PKG_LENGTH)) {\r
      Value = ObjectNode->PkgLen;\r
\r
      // Subtract the size of the PkgLen encoding. The size of the PkgLen\r
      // encoding must be computed after having updated Value.\r
      InitialPkgLenWidth = AmlComputePkgLengthWidth (Value);\r
      Value             -= InitialPkgLenWidth;\r
\r
      // Check for an over/underflows.\r
      // PkgLen is a 28 bit value, cf 20.2.4 Package Length Encoding\r
      // i.e. the maximum value is (2^28 - 1) = ((BIT0 << 28) - 1).\r
      if ((IsIncrement && ((((BIT0 << 28) - 1) - Value) < *Diff))   ||\r
          (!IsIncrement && (Value < *Diff)))\r
      {\r
        ASSERT (0);\r
        return EFI_INVALID_PARAMETER;\r
      }\r
\r
      // Update the size.\r
      if (IsIncrement) {\r
        Value += *Diff;\r
      } else {\r
        Value -= *Diff;\r
      }\r
\r
      // Compute the new PkgLenWidth.\r
      NewPkgLenWidth = AmlComputePkgLengthWidth (Value);\r
      if (NewPkgLenWidth == 0) {\r
        ASSERT (0);\r
        return EFI_INVALID_PARAMETER;\r
      }\r
\r
      // Add it to the Value.\r
      Value += NewPkgLenWidth;\r
\r
      // Check that adding the PkgLenWidth didn't trigger a domino effect,\r
      // increasing the encoding width of the PkgLen again.\r
      // The PkgLen is encoded on at most 4 bytes. It is possible to increase\r
      // the PkgLen width if its encoding is on less than 3 bytes.\r
      ReComputedPkgLenWidth = AmlComputePkgLengthWidth (Value);\r
      if (ReComputedPkgLenWidth != NewPkgLenWidth) {\r
        if ((ReComputedPkgLenWidth != 0)   &&\r
            (ReComputedPkgLenWidth < 4))\r
        {\r
          // No need to recompute the PkgLen since a new threshold cannot\r
          // be reached by incrementing the value by one.\r
          Value += 1;\r
        } else {\r
          ASSERT (0);\r
          return EFI_INVALID_PARAMETER;\r
        }\r
      }\r
\r
      *Diff += (InitialPkgLenWidth > ReComputedPkgLenWidth) ?\r
               (InitialPkgLenWidth - ReComputedPkgLenWidth) :\r
               (ReComputedPkgLenWidth - InitialPkgLenWidth);\r
      ObjectNode->PkgLen = Value;\r
    } // PkgLen update.\r
\r
    // During CodeGeneration, the tree is incomplete and\r
    // there is no root node at the top of the tree. Stop\r
    // propagating the new size when finding a root node\r
    // OR when a NULL parent is found.\r
    ParentNode = AmlGetParent ((AML_NODE_HEADER *)Node);\r
    if (ParentNode != NULL) {\r
      // Propagate the size up the tree.\r
      Status = AmlPropagateSize (\r
                 Node->Parent,\r
                 IsIncrement,\r
                 Diff\r
                 );\r
      if (EFI_ERROR (Status)) {\r
        ASSERT (0);\r
        return Status;\r
      }\r
    }\r
  } else if (IS_AML_ROOT_NODE (Node)) {\r
    // Update the length field in the SDT header.\r
    Value = ((AML_ROOT_NODE *)Node)->SdtHeader->Length;\r
\r
    // Check for an over/underflows.\r
    if ((IsIncrement && (Value > (MAX_UINT32 - *Diff))) ||\r
        (!IsIncrement && (Value < *Diff)))\r
    {\r
      ASSERT (0);\r
      return EFI_INVALID_PARAMETER;\r
    }\r
\r
    // Update the size.\r
    if (IsIncrement) {\r
      Value += *Diff;\r
    } else {\r
      Value -= *Diff;\r
    }\r
\r
    ((AML_ROOT_NODE *)Node)->SdtHeader->Length = Value;\r
  }\r
\r
  return EFI_SUCCESS;\r
}\r
\r
/** Propagate the node count information up the tree.\r
\r
  @param  [in]  ObjectNode        Pointer to an object node.\r
  @param  [in]  IsIncrement       Choose the operation to do:\r
                                   - TRUE:  Increment the Node's size and\r
                                            the Node's count;\r
                                   - FALSE: Decrement the Node's size and\r
                                           the Node's count.\r
  @param  [in]  NodeCount         Number of nodes added/removed (depends on the\r
                                  value of Operation).\r
  @param  [out] FieldWidthChange  When modifying the integer, it can be\r
                                  promoted/demoted, e.g. from UINT8 to UINT16.\r
                                  Stores the change in width.\r
                                  Can be negative.\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
AmlPropagateNodeCount (\r
  IN  AML_OBJECT_NODE  *ObjectNode,\r
  IN  BOOLEAN          IsIncrement,\r
  IN  UINT8            NodeCount,\r
  OUT INT8             *FieldWidthChange\r
  )\r
{\r
  EFI_STATUS  Status;\r
\r
  AML_NODE_HEADER  *NodeCountArg;\r
  UINT8            CurrNodeCount;\r
\r
  // Currently there is no use case where (NodeCount > 1).\r
  if (!IS_AML_OBJECT_NODE (ObjectNode)  ||\r
      (FieldWidthChange == NULL)        ||\r
      (NodeCount > 1))\r
  {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  *FieldWidthChange = 0;\r
\r
  // Update the number of elements stored in PackageOp and VarPackageOp.\r
  // The number of elements is stored as the first fixed argument.\r
  // DefPackage := PackageOp PkgLength NumElements PackageElementList\r
  // PackageOp := 0x12\r
  // DefVarPackage := VarPackageOp PkgLength VarNumElements PackageElementList\r
  // VarPackageOp := 0x13\r
  // NumElements := ByteData\r
  // VarNumElements := TermArg => Integer\r
  NodeCountArg = AmlGetFixedArgument (ObjectNode, EAmlParseIndexTerm0);\r
  if (AmlNodeCompareOpCode (ObjectNode, AML_PACKAGE_OP, 0)) {\r
    // First fixed argument of PackageOp stores the number of elements\r
    // in the package. It is an UINT8.\r
\r
    // Check for over/underflow.\r
    CurrNodeCount = *(((AML_DATA_NODE *)NodeCountArg)->Buffer);\r
    if ((IsIncrement && (CurrNodeCount == MAX_UINT8)) ||\r
        (!IsIncrement && (CurrNodeCount == 0)))\r
    {\r
      ASSERT (0);\r
      return EFI_INVALID_PARAMETER;\r
    }\r
\r
    // Update the node count in the DataNode.\r
    CurrNodeCount                              = IsIncrement ? (CurrNodeCount + 1) : (CurrNodeCount - 1);\r
    *(((AML_DATA_NODE *)NodeCountArg)->Buffer) =  CurrNodeCount;\r
  } else if (AmlNodeCompareOpCode (ObjectNode, AML_VAR_PACKAGE_OP, 0)) {\r
    // First fixed argument of PackageOp stores the number of elements\r
    // in the package. It is an integer (can be a BYTE, WORD, DWORD, QWORD).\r
    Status = AmlNodeUpdateIntegerValue (\r
               (AML_OBJECT_NODE *)NodeCountArg,\r
               IsIncrement,\r
               NodeCount,\r
               FieldWidthChange\r
               );\r
    if (EFI_ERROR (Status)) {\r
      ASSERT (0);\r
      return Status;\r
    }\r
  }\r
\r
  return EFI_SUCCESS;\r
}\r
\r
/** Propagate information up the tree.\r
\r
  The information can be a new size, a new number of arguments.\r
\r
  @param  [in]  Node          Pointer to a node.\r
                              Must be a root node or an object node.\r
  @param  [in]  IsIncrement   Choose the operation to do:\r
                               - TRUE:  Increment the Node's size and\r
                                        the Node's count;\r
                               - FALSE: Decrement the Node's size and\r
                                        the Node's count.\r
  @param  [in]  Diff          Value to add/subtract to the Node's size.\r
  @param  [in]  NodeCount     Number of nodes added/removed.\r
\r
  @retval EFI_SUCCESS             The function completed successfully.\r
  @retval EFI_INVALID_PARAMETER   Invalid parameter.\r
**/\r
EFI_STATUS\r
EFIAPI\r
AmlPropagateInformation (\r
  IN  AML_NODE_HEADER  *Node,\r
  IN  BOOLEAN          IsIncrement,\r
  IN  UINT32           Diff,\r
  IN  UINT8            NodeCount\r
  )\r
{\r
  EFI_STATUS  Status;\r
  INT8        FieldWidthChange;\r
\r
  // Currently there is no use case where (NodeCount > 1).\r
  if ((!IS_AML_ROOT_NODE (Node)     &&\r
       !IS_AML_OBJECT_NODE (Node))  ||\r
      (NodeCount > 1))\r
  {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  // Propagate the node count first as it may change the number of bytes\r
  // needed to store the node count, and then impact FieldWidthChange.\r
  if ((NodeCount != 0) &&\r
      IS_AML_OBJECT_NODE (Node))\r
  {\r
    Status = AmlPropagateNodeCount (\r
               (AML_OBJECT_NODE *)Node,\r
               IsIncrement,\r
               NodeCount,\r
               &FieldWidthChange\r
               );\r
    if (EFI_ERROR (Status)) {\r
      ASSERT (0);\r
      return Status;\r
    }\r
\r
    // Propagate the potential field width change.\r
    // Maximum change is between UINT8/UINT64: 8 bytes.\r
    if ((ABS (FieldWidthChange) > 8)                          ||\r
        (IsIncrement                                          &&\r
         ((FieldWidthChange < 0)                             ||\r
          ((Diff + (UINT8)FieldWidthChange) > MAX_UINT32)))  ||\r
        (!IsIncrement                                         &&\r
         ((FieldWidthChange > 0)                             ||\r
          (Diff < (UINT32)ABS (FieldWidthChange)))))\r
    {\r
      ASSERT (0);\r
      return EFI_INVALID_PARAMETER;\r
    }\r
\r
    Diff = (UINT32)(Diff + (UINT8)ABS (FieldWidthChange));\r
  }\r
\r
  // Diff can be zero if some data is updated without modifying the data size.\r
  if (Diff != 0) {\r
    Status = AmlPropagateSize (Node, IsIncrement, &Diff);\r
    if (EFI_ERROR (Status)) {\r
      ASSERT (0);\r
      return Status;\r
    }\r
  }\r
\r
  return EFI_SUCCESS;\r
}\r
\r
/** Find and set the EndTag's Checksum of a list of Resource Data elements.\r
\r
  Lists of Resource Data elements end with an EndTag (most of the time). This\r
  function finds the EndTag (if present) in a list of Resource Data elements\r
  and sets the checksum.\r
\r
  ACPI 6.4, s6.4.2.9 "End Tag":\r
  "This checksum is generated such that adding it to the sum of all the data\r
  bytes will produce a zero sum."\r
  "If the checksum field is zero, the resource data is treated as if the\r
  checksum operation succeeded. Configuration proceeds normally."\r
\r
  To avoid re-computing checksums, if a new resource data elements is\r
  added/removed/modified in a list of resource data elements, the AmlLib\r
  resets the checksum to 0.\r
\r
  @param [in]  BufferOpNode   Node having a list of Resource Data elements.\r
  @param [in]  CheckSum       CheckSum to store in the EndTag.\r
                              To ignore/avoid computing the checksum,\r
                              give 0.\r
\r
  @retval EFI_SUCCESS             The function completed successfully.\r
  @retval EFI_INVALID_PARAMETER   Invalid parameter.\r
  @retval EFI_NOT_FOUND           No EndTag found.\r
**/\r
EFI_STATUS\r
EFIAPI\r
AmlSetRdListCheckSum (\r
  IN  AML_OBJECT_NODE  *BufferOpNode,\r
  IN  UINT8            CheckSum\r
  )\r
{\r
  EFI_STATUS     Status;\r
  AML_DATA_NODE  *LastRdNode;\r
  AML_RD_HEADER  RdDataType;\r
\r
  if (!AmlNodeCompareOpCode (BufferOpNode, AML_BUFFER_OP, 0)) {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  // Get the last Resource data node in the variable list of\r
  // argument of the BufferOp node.\r
  LastRdNode = (AML_DATA_NODE *)AmlGetPreviousVariableArgument (\r
                                  (AML_NODE_HEADER *)BufferOpNode,\r
                                  NULL\r
                                  );\r
  if ((LastRdNode == NULL)             ||\r
      !IS_AML_DATA_NODE (LastRdNode)   ||\r
      (LastRdNode->DataType != EAmlNodeDataTypeResourceData))\r
  {\r
    ASSERT (0);\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  Status = AmlGetResourceDataType (LastRdNode, &RdDataType);\r
  if (EFI_ERROR (Status)) {\r
    ASSERT (0);\r
    return Status;\r
  }\r
\r
  // Check the LastRdNode is an EndTag.\r
  // It is possible to have only one Resource Data in a BufferOp with\r
  // no EndTag. Return EFI_NOT_FOUND is such case.\r
  if (!AmlRdCompareDescId (\r
         &RdDataType,\r
         AML_RD_BUILD_SMALL_DESC_ID (ACPI_SMALL_END_TAG_DESCRIPTOR_NAME)\r
         ))\r
  {\r
    ASSERT (0);\r
    return EFI_NOT_FOUND;\r
  }\r
\r
  Status = AmlRdSetEndTagChecksum (LastRdNode->Buffer, CheckSum);\r
  ASSERT_EFI_ERROR (Status);\r
\r
  return Status;\r
}\r