DynamicTablesPkg/Library/Common/AmlLib/Utils/AmlUtility.h

   1 /** @file
   2   AML Utility.
   3
   4   Copyright (c) 2019 - 2021, Arm Limited. All rights reserved.<BR>
   5
   6   SPDX-License-Identifier: BSD-2-Clause-Patent
   7 **/
   8
   9 #ifndef AML_UTILITY_H_
  10 #define AML_UTILITY_H_
  11
  12 #include <AmlNodeDefines.h>
  13
  14 /** This function computes and updates the ACPI table checksum.
  15
  16   @param  [in]  AcpiTable   Pointer to an Acpi table.
  17
  18   @retval EFI_SUCCESS   The function completed successfully.
  19   @retval EFI_INVALID_PARAMETER   Invalid parameter.
  20 **/
  21 EFI_STATUS
  22 EFIAPI
  23 AcpiPlatformChecksum (
  24   IN  EFI_ACPI_DESCRIPTION_HEADER  * AcpiTable
  25   );
  26
  27 /** Compute the size of a tree/sub-tree.
  28
  29   @param  [in]      Node      Node to compute the size.
  30   @param  [in, out] Size      Pointer holding the computed size.
  31
  32   @retval EFI_SUCCESS             The function completed successfully.
  33   @retval EFI_INVALID_PARAMETER   Invalid parameter.
  34 **/
  35 EFI_STATUS
  36 EFIAPI
  37 AmlComputeSize (
  38   IN      CONST AML_NODE_HEADER   * Node,
  39   IN  OUT       UINT32            * Size
  40   );
  41
  42 /** Get the value contained in an integer node.
  43
  44   @param  [in]  Node    Pointer to an integer node.
  45                         Must be an object node.
  46   @param  [out] Value   Value contained in the integer node.
  47
  48   @retval EFI_SUCCESS             The function completed successfully.
  49   @retval EFI_INVALID_PARAMETER   Invalid parameter.
  50 **/
  51 EFI_STATUS
  52 EFIAPI
  53 AmlNodeGetIntegerValue (
  54   IN  AML_OBJECT_NODE   * Node,
  55   OUT UINT64            * Value
  56   );
  57
  58 /** Set the value contained in an integer node.
  59
  60   The OpCode is updated accordingly to the new value
  61   (e.g.: If the original value was a UINT8 value, then the OpCode
  62          would be AML_BYTE_PREFIX. If it the new value is a UINT16
  63          value then the OpCode will be updated to AML_WORD_PREFIX).
  64
  65   @param  [in]  Node            Pointer to an integer node.
  66                                 Must be an object node.
  67   @param  [in]  NewValue        New value to write in the integer node.
  68   @param  [out] ValueWidthDiff  Difference in number of bytes used to store
  69                                 the new value.
  70                                 Can be negative.
  71
  72   @retval EFI_SUCCESS             The function completed successfully.
  73   @retval EFI_INVALID_PARAMETER   Invalid parameter.
  74   @retval EFI_OUT_OF_RESOURCES    Could not allocate memory.
  75 **/
  76 EFI_STATUS
  77 EFIAPI
  78 AmlNodeSetIntegerValue (
  79   IN  AML_OBJECT_NODE   * Node,
  80   IN  UINT64              NewValue,
  81   OUT INT8              * ValueWidthDiff
  82   );
  83
  84 /** Propagate information up the tree.
  85
  86   The information can be a new size, a new number of arguments.
  87
  88   @param  [in]  Node          Pointer to a node.
  89                               Must be a root node or an object node.
  90   @param  [in]  IsIncrement   Choose the operation to do:
  91                                - TRUE:  Increment the Node's size and
  92                                         the Node's count;
  93                                - FALSE: Decrement the Node's size and
  94                                         the Node's count.
  95   @param  [in]  Diff          Value to add/subtract to the Node's size.
  96   @param  [in]  NodeCount     Number of nodes added/removed.
  97
  98   @retval EFI_SUCCESS             The function completed successfully.
  99   @retval EFI_INVALID_PARAMETER   Invalid parameter.
 100 **/
 101 EFI_STATUS
 102 EFIAPI
 103 AmlPropagateInformation (
 104   IN  AML_NODE_HEADER   * Node,
 105   IN  BOOLEAN             IsIncrement,
 106   IN  UINT32              Diff,
 107   IN  UINT8               NodeCount
 108   );
 109
 110 /** Find and set the EndTag's Checksum of a list of Resource Data elements.
 111
 112   Lists of Resource Data elements end with an EndTag (most of the time). This
 113   function finds the EndTag (if present) in a list of Resource Data elements
 114   and sets the checksum.
 115
 116   ACPI 6.4, s6.4.2.9 "End Tag":
 117   "This checksum is generated such that adding it to the sum of all the data
 118   bytes will produce a zero sum."
 119   "If the checksum field is zero, the resource data is treated as if the
 120   checksum operation succeeded. Configuration proceeds normally."
 121
 122   To avoid re-computing checksums, if a new resource data elements is
 123   added/removed/modified in a list of resource data elements, the AmlLib
 124   resets the checksum to 0.
 125
 126   @param [in]  BufferOpNode   Node having a list of Resource Data elements.
 127   @param [in]  CheckSum       CheckSum to store in the EndTag.
 128                               To ignore/avoid computing the checksum,
 129                               give 0.
 130
 131   @retval EFI_SUCCESS             The function completed successfully.
 132   @retval EFI_INVALID_PARAMETER   Invalid parameter.
 133   @retval EFI_NOT_FOUND           No EndTag found.
 134 **/
 135 EFI_STATUS
 136 EFIAPI
 137 AmlSetRdListCheckSum (
 138   IN  AML_OBJECT_NODE   * BufferOpNode,
 139   IN  UINT8               CheckSum
 140   );
 141
 142 #endif // AML_UTILITY_H_
 143