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

   1 /** @file
   2   AML Utility.
   3
   4   Copyright (c) 2019 - 2020, 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 /** Set the value contained in an integer node.
  43
  44   The OpCode is updated accordingly to the new value
  45   (e.g.: If the original value was a UINT8 value, then the OpCode
  46          would be AML_BYTE_PREFIX. If it the new value is a UINT16
  47          value then the OpCode will be updated to AML_WORD_PREFIX).
  48
  49   @param  [in]  Node            Pointer to an integer node.
  50                                 Must be an object node.
  51   @param  [in]  NewValue        New value to write in the integer node.
  52   @param  [out] ValueWidthDiff  Difference in number of bytes used to store
  53                                 the new value.
  54                                 Can be negative.
  55
  56   @retval EFI_SUCCESS             The function completed successfully.
  57   @retval EFI_INVALID_PARAMETER   Invalid parameter.
  58   @retval EFI_OUT_OF_RESOURCES    Could not allocate memory.
  59 **/
  60 EFI_STATUS
  61 EFIAPI
  62 AmlNodeSetIntegerValue (
  63   IN  AML_OBJECT_NODE   * Node,
  64   IN  UINT64              NewValue,
  65   OUT INT8              * ValueWidthDiff
  66   );
  67
  68 /** Propagate information up the tree.
  69
  70   The information can be a new size, a new number of arguments.
  71
  72   @param  [in]  Node          Pointer to a node.
  73                               Must be a root node or an object node.
  74   @param  [in]  IsIncrement   Choose the operation to do:
  75                                - TRUE:  Increment the Node's size and
  76                                         the Node's count;
  77                                - FALSE: Decrement the Node's size and
  78                                         the Node's count.
  79   @param  [in]  Diff          Value to add/subtract to the Node's size.
  80   @param  [in]  NodeCount     Number of nodes added/removed.
  81
  82   @retval EFI_SUCCESS             The function completed successfully.
  83   @retval EFI_INVALID_PARAMETER   Invalid parameter.
  84 **/
  85 EFI_STATUS
  86 EFIAPI
  87 AmlPropagateInformation (
  88   IN  AML_NODE_HEADER   * Node,
  89   IN  BOOLEAN             IsIncrement,
  90   IN  UINT32              Diff,
  91   IN  UINT8               NodeCount
  92   );
  93
  94 /** Find and set the EndTag's Checksum of a list of Resource Data elements.
  95
  96   Lists of Resource Data elements end with an EndTag (most of the time). This
  97   function finds the EndTag (if present) in a list of Resource Data elements
  98   and sets the checksum.
  99
 100   ACPI 6.4, s6.4.2.9 "End Tag":
 101   "This checksum is generated such that adding it to the sum of all the data
 102   bytes will produce a zero sum."
 103   "If the checksum field is zero, the resource data is treated as if the
 104   checksum operation succeeded. Configuration proceeds normally."
 105
 106   To avoid re-computing checksums, if a new resource data elements is
 107   added/removed/modified in a list of resource data elements, the AmlLib
 108   resets the checksum to 0.
 109
 110   @param [in]  BufferOpNode   Node having a list of Resource Data elements.
 111   @param [in]  CheckSum       CheckSum to store in the EndTag.
 112                               To ignore/avoid computing the checksum,
 113                               give 0.
 114
 115   @retval EFI_SUCCESS             The function completed successfully.
 116   @retval EFI_INVALID_PARAMETER   Invalid parameter.
 117   @retval EFI_NOT_FOUND           No EndTag found.
 118 **/
 119 EFI_STATUS
 120 EFIAPI
 121 AmlSetRdListCheckSum (
 122   IN  AML_OBJECT_NODE   * BufferOpNode,
 123   IN  UINT8               CheckSum
 124   );
 125
 126 #endif // AML_UTILITY_H_
 127