DynamicTablesPkg/Library/Common/AmlLib/CodeGen/AmlResourceDataCodeGen.h

   1 /** @file
   2   AML Resource Data Code Generation.
   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_RESOURCE_DATA_CODE_GEN_H_
  10 #define AML_RESOURCE_DATA_CODE_GEN_H_
  11
  12 /** Code generation for the "Interrupt ()" ASL function.
  13
  14   The Resource Data effectively created is an Extended Interrupt Resource
  15   Data. Cf ACPI 6.4:
  16    - s6.4.3.6 "Extended Interrupt Descriptor"
  17    - s19.6.64 "Interrupt (Interrupt Resource Descriptor Macro)"
  18
  19   The created resource data node can be:
  20    - appended to the list of resource data elements of the NameOpNode.
  21      In such case NameOpNode must be defined by a the "Name ()" ASL statement
  22      and initially contain a "ResourceTemplate ()".
  23    - returned through the NewRdNode parameter.
  24
  25   @param  [in]  ResourceConsumer The device consumes the specified interrupt
  26                                  or produces it for use by a child device.
  27   @param  [in]  EdgeTriggered    The interrupt is edge triggered or
  28                                  level triggered.
  29   @param  [in]  ActiveLow        The interrupt is active-high or active-low.
  30   @param  [in]  Shared           The interrupt can be shared with other
  31                                  devices or not (Exclusive).
  32   @param  [in]  IrqList          Interrupt list. Must be non-NULL.
  33   @param  [in]  IrqCount         Interrupt count. Must be non-zero.
  34   @param  [in]  NameOpNode       NameOp object node defining a named object.
  35                                  If provided, append the new resource data node
  36                                  to the list of resource data elements of this
  37                                  node.
  38   @param  [out] NewRdNode        If provided and success,
  39                                  contain the created node.
  40
  41   @retval EFI_SUCCESS             The function completed successfully.
  42   @retval EFI_INVALID_PARAMETER   Invalid parameter.
  43   @retval EFI_OUT_OF_RESOURCES    Could not allocate memory.
  44 **/
  45 EFI_STATUS
  46 EFIAPI
  47 AmlCodeGenRdInterrupt (
  48   IN  BOOLEAN                 ResourceConsumer,
  49   IN  BOOLEAN                 EdgeTriggered,
  50   IN  BOOLEAN                 ActiveLow,
  51   IN  BOOLEAN                 Shared,
  52   IN  UINT32                  *IrqList,
  53   IN  UINT8                   IrqCount,
  54   IN  AML_OBJECT_NODE_HANDLE  NameOpNode  OPTIONAL,
  55   OUT AML_DATA_NODE_HANDLE    *NewRdNode  OPTIONAL
  56   );
  57
  58 /** Code generation for the "Register ()" ASL function.
  59
  60   The Resource Data effectively created is a Generic Register Descriptor.
  61   Data. Cf ACPI 6.4:
  62    - s6.4.3.7 "Generic Register Descriptor".
  63    - s19.6.114 "Register".
  64
  65   The created resource data node can be:
  66    - appended to the list of resource data elements of the NameOpNode.
  67      In such case NameOpNode must be defined by a the "Name ()" ASL statement
  68      and initially contain a "ResourceTemplate ()".
  69    - returned through the NewRdNode parameter.
  70
  71   @param [in]  AddressSpace    Address space where the register exists.
  72                                Can be one of I/O space, System Memory, etc.
  73   @param [in]  BitWidth        Number of bits in the register.
  74   @param [in]  BitOffset       Offset in bits from the start of the register
  75                                indicated by the Address.
  76   @param [in]  Address         Register address.
  77   @param [in]  AccessSize      Size of data values used when accessing the
  78                                address space. Can be one of:
  79                                  0 - Undefined, legacy (EFI_ACPI_6_4_UNDEFINED)
  80                                  1 - Byte access (EFI_ACPI_6_4_BYTE)
  81                                  2 - Word access (EFI_ACPI_6_4_WORD)
  82                                  3 - DWord access (EFI_ACPI_6_4_DWORD)
  83                                  4 - QWord access (EFI_ACPI_6_4_QWORD)
  84   @param  [in]  NameOpNode       NameOp object node defining a named object.
  85                                  If provided, append the new resource data node
  86                                  to the list of resource data elements of this
  87                                  node.
  88   @param  [out] NewRdNode        If provided and success,
  89                                  contain the created node.
  90
  91   @retval EFI_SUCCESS             The function completed successfully.
  92   @retval EFI_INVALID_PARAMETER   Invalid parameter.
  93   @retval EFI_OUT_OF_RESOURCES    Could not allocate memory.
  94 **/
  95 EFI_STATUS
  96 EFIAPI
  97 AmlCodeGenRdRegister (
  98   IN  UINT8                   AddressSpace,
  99   IN  UINT8                   BitWidth,
 100   IN  UINT8                   BitOffset,
 101   IN  UINT64                  Address,
 102   IN  UINT8                   AccessSize,
 103   IN  AML_OBJECT_NODE_HANDLE  NameOpNode  OPTIONAL,
 104   OUT AML_DATA_NODE_HANDLE    *NewRdNode  OPTIONAL
 105   );
 106
 107 /** Code generation for the EndTag resource data.
 108
 109   The EndTag resource data is automatically generated by the ASL compiler
 110   at the end of a list of resource data elements. Thus, it doesn't have
 111   a corresponding ASL function.
 112
 113   This function allocates memory to create a data node. It is the caller's
 114   responsibility to either:
 115    - attach this node to an AML tree;
 116    - delete this node.
 117
 118   ACPI 6.4, s6.4.2.9 "End Tag":
 119   "This checksum is generated such that adding it to the sum of all the data
 120   bytes will produce a zero sum."
 121   "If the checksum field is zero, the resource data is treated as if the
 122   checksum operation succeeded. Configuration proceeds normally."
 123
 124   To avoid re-computing checksums, if a new resource data elements is
 125   added/removed/modified in a list of resource data elements, the AmlLib
 126   resets the checksum to 0.
 127
 128   @param [in]  CheckSum        CheckSum to store in the EndTag.
 129                                To ignore/avoid computing the checksum,
 130                                give 0.
 131   @param [in]  ParentNode      If not NULL, add the generated node
 132                                to the end of the variable list of
 133                                argument of the ParentNode.
 134                                The ParentNode must not initially contain
 135                                an EndTag resource data element.
 136   @param  [out] NewRdNode      If success, contains the generated node.
 137
 138   @retval EFI_SUCCESS             The function completed successfully.
 139   @retval EFI_INVALID_PARAMETER   Invalid parameter.
 140   @retval EFI_OUT_OF_RESOURCES    Could not allocate memory.
 141 **/
 142 EFI_STATUS
 143 EFIAPI
 144 AmlCodeGenEndTag (
 145   IN  UINT8               CheckSum    OPTIONAL,
 146   IN  AML_OBJECT_NODE   * ParentNode  OPTIONAL,
 147   OUT AML_DATA_NODE    ** NewRdNode   OPTIONAL
 148   );
 149
 150 #endif // AML_RESOURCE_DATA_CODE_GEN_H_