DynamicTablesPkg/Include/Library/AmlLib/AmlLib.h

   1 /** @file
   2   AML Lib.
   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_LIB_H_
  10 #define AML_LIB_H_
  11
  12 /**
  13   @mainpage Dynamic AML Generation
  14   @{
  15     @par Summary
  16     @{
  17     ACPI tables are categorized as data tables and definition block
  18     tables. Dynamic Tables Framework currently supports generation of ACPI
  19     data tables. Generation of definition block tables is difficult as these
  20     tables are encoded in ACPI Machine Language (AML), which has a complex
  21     grammar.
  22
  23     Dynamic AML Generation is an extension to the Dynamic tables Framework.
  24     One of the techniques used to simplify definition block generation is to
  25     fixup a template SSDT table.
  26
  27     Dynamic AML aims to provide a framework that allows fixing up of an ACPI
  28     SSDT template with appropriate information about the hardware.
  29
  30     This framework consists of an:
  31     - AMLLib core that implements a rich set of interfaces to parse, traverse
  32       and update AML data.
  33     - AMLLib library APIs that provides interfaces to search and updates nodes
  34       in the AML namespace.
  35     @}
  36   @}
  37 */
  38
  39 #include <IndustryStandard/Acpi.h>
  40
  41 #ifndef AML_HANDLE
  42
  43 /** Node handle.
  44 */
  45 typedef void* AML_NODE_HANDLE;
  46
  47 /** Root Node handle.
  48 */
  49 typedef void* AML_ROOT_NODE_HANDLE;
  50
  51 /** Object Node handle.
  52 */
  53 typedef void* AML_OBJECT_NODE_HANDLE;
  54
  55 /** Data Node handle.
  56 */
  57 typedef void* AML_DATA_NODE_HANDLE;
  58
  59 #endif // AML_HANDLE
  60
  61 /** Parse the definition block.
  62
  63   The function parses the whole AML blob. It starts with the ACPI DSDT/SSDT
  64   header and then parses the AML bytestream.
  65   A tree structure is returned via the RootPtr.
  66   The tree must be deleted with the AmlDeleteTree function.
  67
  68   @ingroup UserApis
  69
  70   @param  [in]  DefinitionBlock   Pointer to the definition block.
  71   @param  [out] RootPtr           Pointer to the root node of the AML tree.
  72
  73   @retval EFI_SUCCESS             The function completed successfully.
  74   @retval EFI_BUFFER_TOO_SMALL    No space left in the buffer.
  75   @retval EFI_INVALID_PARAMETER   Invalid parameter.
  76   @retval EFI_OUT_OF_RESOURCES    Could not allocate memory.
  77 **/
  78 EFI_STATUS
  79 EFIAPI
  80 AmlParseDefinitionBlock (
  81   IN  CONST EFI_ACPI_DESCRIPTION_HEADER   * DefinitionBlock,
  82   OUT       AML_ROOT_NODE_HANDLE          * RootPtr
  83   );
  84
  85 /** Serialize an AML definition block.
  86
  87   This functions allocates memory with the "AllocateZeroPool ()"
  88   function. This memory is used to serialize the AML tree and is
  89   returned in the Table.
  90
  91   @ingroup UserApis
  92
  93   @param [in]  RootNode         Root node of the tree.
  94   @param [out] Table            On return, hold the serialized
  95                                 definition block.
  96
  97   @retval EFI_SUCCESS            The function completed successfully.
  98   @retval EFI_INVALID_PARAMETER  Invalid parameter.
  99   @retval EFI_OUT_OF_RESOURCES   Could not allocate memory.
 100 **/
 101 EFI_STATUS
 102 EFIAPI
 103 AmlSerializeDefinitionBlock (
 104   IN  AML_ROOT_NODE_HANDLE              RootNode,
 105   OUT EFI_ACPI_DESCRIPTION_HEADER    ** Table
 106   );
 107
 108 /** Clone a node and its children (clone a tree branch).
 109
 110   The cloned branch returned is not attached to any tree.
 111
 112   @ingroup UserApis
 113
 114   @param  [in]  Node        Pointer to a node.
 115                             Node is the head of the branch to clone.
 116   @param  [out] ClonedNode  Pointer holding the head of the created cloned
 117                             branch.
 118
 119   @retval EFI_SUCCESS             The function completed successfully.
 120   @retval EFI_INVALID_PARAMETER   Invalid parameter.
 121   @retval EFI_OUT_OF_RESOURCES    Could not allocate memory.
 122 **/
 123 EFI_STATUS
 124 EFIAPI
 125 AmlCloneTree (
 126   IN  AML_NODE_HANDLE   Node,
 127   OUT AML_NODE_HANDLE * ClonedNode
 128   );
 129
 130 /** Delete a Node and its children.
 131
 132   The Node must be removed from the tree first,
 133   or must be the root node.
 134
 135   @ingroup UserApis
 136
 137   @param  [in]  Node  Pointer to the node to delete.
 138
 139   @retval EFI_SUCCESS             The function completed successfully.
 140   @retval EFI_INVALID_PARAMETER   Invalid parameter.
 141 **/
 142 EFI_STATUS
 143 EFIAPI
 144 AmlDeleteTree (
 145   IN  AML_NODE_HANDLE   Node
 146   );
 147
 148 /** Detach the Node from the tree.
 149
 150   The function will fail if the Node is in its parent's fixed
 151   argument list.
 152   The Node is not deleted. The deletion is done separately
 153   from the removal.
 154
 155   @ingroup UserApis
 156
 157   @param  [in]  Node  Pointer to a Node.
 158                       Must be a data node or an object node.
 159
 160   @retval EFI_SUCCESS             The function completed successfully.
 161   @retval EFI_INVALID_PARAMETER   Invalid parameter.
 162 **/
 163 EFI_STATUS
 164 EFIAPI
 165 AmlDetachNode (
 166   IN  AML_NODE_HANDLE   Node
 167   );
 168
 169 /** Find a node in the AML namespace, given an ASL path and a reference Node.
 170
 171    - The AslPath can be an absolute path, or a relative path from the
 172      reference Node;
 173    - Node must be a root node or a namespace node;
 174    - A root node is expected to be at the top of the tree.
 175
 176   E.g.:
 177   For the following AML namespace, with the ReferenceNode being the node with
 178   the name "AAAA":
 179    - the node with the name "BBBB" can be found by looking for the ASL
 180      path "BBBB";
 181    - the root node can be found by looking for the ASL relative path "^",
 182       or the absolute path "\\".
 183
 184   AML namespace:
 185   \
 186   \-AAAA      <- ReferenceNode
 187     \-BBBB
 188
 189   @ingroup NameSpaceApis
 190
 191   @param  [in]  ReferenceNode   Reference node.
 192                                 If a relative path is given, the
 193                                 search is done from this node. If
 194                                 an absolute path is given, the
 195                                 search is done from the root node.
 196                                 Must be a root node or an object
 197                                 node which is part of the
 198                                 namespace.
 199   @param  [in]  AslPath         ASL path to the searched node in
 200                                 the namespace. An ASL path name is
 201                                 NULL terminated. Can be a relative
 202                                 or absolute path.
 203                                 E.g.: "\\_SB.CLU0.CPU0" or "^CPU0"
 204   @param  [out] OutNode         Pointer to the found node.
 205                                 Contains NULL if not found.
 206
 207   @retval EFI_SUCCESS             The function completed successfully.
 208   @retval EFI_BUFFER_TOO_SMALL    No space left in the buffer.
 209   @retval EFI_INVALID_PARAMETER   Invalid parameter.
 210   @retval EFI_OUT_OF_RESOURCES    Out of memory.
 211 **/
 212 EFI_STATUS
 213 EFIAPI
 214 AmlFindNode (
 215   IN  AML_NODE_HANDLE       ReferenceNode,
 216   IN  CHAR8               * AslPath,
 217   OUT AML_NODE_HANDLE     * OutNode
 218   );
 219
 220 /**
 221   @defgroup UserApis User APIs
 222   @{
 223     User APIs are implemented to ease most common actions that might be done
 224     using the AmlLib. They allow to find specific objects like "_UID" or
 225     "_CRS" and to update their value. It also shows what can be done using
 226     AmlLib functions.
 227   @}
 228 */
 229
 230 /** Update the name of a DeviceOp object node.
 231
 232   @ingroup UserApis
 233
 234   @param  [in] DeviceOpNode   Object node representing a Device.
 235                               Must have an OpCode=AML_NAME_OP, SubOpCode=0.
 236                               OpCode/SubOpCode.
 237                               DeviceOp object nodes are defined in ASL
 238                               using the "Device ()" function.
 239   @param  [in] NewNameString  The new Device's name.
 240                               Must be a NULL-terminated ASL NameString
 241                               e.g.: "DEV0", "DV15.DEV0", etc.
 242                               The input string is copied.
 243
 244   @retval EFI_SUCCESS             The function completed successfully.
 245   @retval EFI_INVALID_PARAMETER   Invalid parameter.
 246 **/
 247 EFI_STATUS
 248 EFIAPI
 249 AmlDeviceOpUpdateName (
 250   IN  AML_OBJECT_NODE_HANDLE    DeviceOpNode,
 251   IN  CHAR8                   * NewNameString
 252   );
 253
 254 /** Update an integer value defined by a NameOp object node.
 255
 256   For compatibility reasons, the NameOpNode must initially
 257   contain an integer.
 258
 259   @ingroup UserApis
 260
 261   @param  [in] NameOpNode   NameOp object node.
 262                             Must have an OpCode=AML_NAME_OP, SubOpCode=0.
 263                             NameOp object nodes are defined in ASL
 264                             using the "Name ()" function.
 265   @param  [in] NewInt       New Integer value to assign.
 266                             Must be a UINT64.
 267
 268   @retval EFI_SUCCESS             The function completed successfully.
 269   @retval EFI_INVALID_PARAMETER   Invalid parameter.
 270 **/
 271 EFI_STATUS
 272 EFIAPI
 273 AmlNameOpUpdateInteger (
 274   IN  AML_OBJECT_NODE_HANDLE  NameOpNode,
 275   IN  UINT64                  NewInt
 276   );
 277
 278 /** Update a string value defined by a NameOp object node.
 279
 280   The NameOpNode must initially contain a string.
 281   The EISAID ASL macro converts a string to an integer. This, it is
 282   not accepted.
 283
 284   @ingroup UserApis
 285
 286   @param  [in] NameOpNode   NameOp object node.
 287                             Must have an OpCode=AML_NAME_OP, SubOpCode=0.
 288                             NameOp object nodes are defined in ASL
 289                             using the "Name ()" function.
 290   @param  [in] NewName      New NULL terminated string to assign to
 291                             the NameOpNode.
 292                             The input string is copied.
 293
 294   @retval EFI_SUCCESS             The function completed successfully.
 295   @retval EFI_INVALID_PARAMETER   Invalid parameter.
 296 **/
 297 EFI_STATUS
 298 EFIAPI
 299 AmlNameOpUpdateString (
 300   IN        AML_OBJECT_NODE_HANDLE    NameOpNode,
 301   IN  CONST CHAR8                   * NewName
 302   );
 303
 304 /** Get the first Resource Data element contained in a named object.
 305
 306   In the following ASL code, the function will return the Resource Data
 307   node corresponding to the "QWordMemory ()" ASL macro.
 308   Name (_CRS, ResourceTemplate() {
 309       QWordMemory (...) {...},
 310       Interrupt (...) {...}
 311     }
 312   )
 313
 314   Note:
 315   "_CRS" names defined as methods are not handled by this function.
 316   They must be defined as names, using the "Name ()" statement.
 317
 318   @ingroup UserApis
 319
 320   @param  [in] NameOpNode   NameOp object node defining a named object.
 321                             Must have an OpCode=AML_NAME_OP, SubOpCode=0.
 322                             NameOp object nodes are defined in ASL
 323                             using the "Name ()" function.
 324   @param  [out] OutRdNode   Pointer to the first Resource Data element of
 325                             the named object. A Resource Data element
 326                             is stored in a data node.
 327
 328   @retval EFI_SUCCESS             The function completed successfully.
 329   @retval EFI_INVALID_PARAMETER   Invalid parameter.
 330 **/
 331 EFI_STATUS
 332 EFIAPI
 333 AmlNameOpGetFirstRdNode (
 334   IN  AML_OBJECT_NODE_HANDLE   NameOpNode,
 335   OUT AML_DATA_NODE_HANDLE   * OutRdNode
 336   );
 337
 338 /** Get the Resource Data element following the CurrRdNode Resource Data.
 339
 340   In the following ASL code, if CurrRdNode corresponds to the first
 341   "QWordMemory ()" ASL macro, the function will return the Resource Data
 342   node corresponding to the "Interrupt ()" ASL macro.
 343   Name (_CRS, ResourceTemplate() {
 344       QwordMemory (...) {...},
 345       Interrupt (...) {...}
 346     }
 347   )
 348
 349   Note:
 350   "_CRS" names defined as methods are not handled by this function.
 351   They must be defined as names, using the "Name ()" statement.
 352
 353   @ingroup UserApis
 354
 355   @param  [in]  CurrRdNode   Pointer to the current Resource Data element of
 356                              the named object.
 357   @param  [out] OutRdNode    Pointer to the Resource Data element following
 358                              the CurrRdNode.
 359                              Contain a NULL pointer if CurrRdNode is the
 360                              last Resource Data element in the list.
 361                              The "End Tag" is not considered as a resource
 362                              data element and is not returned.
 363
 364   @retval EFI_SUCCESS             The function completed successfully.
 365   @retval EFI_INVALID_PARAMETER   Invalid parameter.
 366 **/
 367 EFI_STATUS
 368 EFIAPI
 369 AmlNameOpGetNextRdNode (
 370   IN  AML_DATA_NODE_HANDLE    CurrRdNode,
 371   OUT AML_DATA_NODE_HANDLE  * OutRdNode
 372   );
 373
 374 /** Update the first interrupt of an Interrupt resource data node.
 375
 376   The flags of the Interrupt resource data are left unchanged.
 377
 378   The InterruptRdNode corresponds to the Resource Data created by the
 379   "Interrupt ()" ASL macro. It is an Extended Interrupt Resource Data.
 380   See ACPI 6.3 specification, s6.4.3.6 "Extended Interrupt Descriptor"
 381   for more information about Extended Interrupt Resource Data.
 382
 383   @ingroup UserApis
 384
 385   @param  [in]  InterruptRdNode   Pointer to the an extended interrupt
 386                                   resource data node.
 387   @param  [in]  Irq               Interrupt value to update.
 388
 389   @retval  EFI_SUCCESS            The function completed successfully.
 390   @retval  EFI_INVALID_PARAMETER  Invalid parameter.
 391   @retval  EFI_OUT_OF_RESOURCES   Out of resources.
 392 **/
 393 EFI_STATUS
 394 EFIAPI
 395 AmlUpdateRdInterrupt (
 396   IN  AML_DATA_NODE_HANDLE    InterruptRdNode,
 397   IN  UINT32                  Irq
 398   );
 399
 400 /** Update the base address and length of a QWord resource data node.
 401
 402   @ingroup UserApis
 403
 404   @param  [in] QWordRdNode         Pointer a QWord resource data
 405                                    node.
 406   @param  [in] BaseAddress         Base address.
 407   @param  [in] BaseAddressLength   Base address length.
 408
 409   @retval  EFI_SUCCESS            The function completed successfully.
 410   @retval  EFI_INVALID_PARAMETER  Invalid parameter.
 411   @retval  EFI_OUT_OF_RESOURCES   Out of resources.
 412 **/
 413 EFI_STATUS
 414 EFIAPI
 415 AmlUpdateRdQWord (
 416   IN  AML_DATA_NODE_HANDLE  QWordRdNode,
 417   IN  UINT64                BaseAddress,
 418   IN  UINT64                BaseAddressLength
 419   );
 420
 421 /** Code generation for the "Interrupt ()" ASL function.
 422
 423   The Resource Data effectively created is an Extended Interrupt Resource
 424   Data. Cf ACPI 6.4:
 425    - s6.4.3.6 "Extended Interrupt Descriptor"
 426    - s19.6.64 "Interrupt (Interrupt Resource Descriptor Macro)"
 427
 428   The created resource data node can be:
 429    - appended to the list of resource data elements of the NameOpNode.
 430      In such case NameOpNode must be defined by a the "Name ()" ASL statement
 431      and initially contain a "ResourceTemplate ()".
 432    - returned through the NewRdNode parameter.
 433
 434   @ingroup CodeGenApis
 435
 436   @param  [in]  ResourceConsumer The device consumes the specified interrupt
 437                                  or produces it for use by a child device.
 438   @param  [in]  EdgeTriggered    The interrupt is edge triggered or
 439                                  level triggered.
 440   @param  [in]  ActiveLow        The interrupt is active-high or active-low.
 441   @param  [in]  Shared           The interrupt can be shared with other
 442                                  devices or not (Exclusive).
 443   @param  [in]  IrqList          Interrupt list. Must be non-NULL.
 444   @param  [in]  IrqCount         Interrupt count. Must be non-zero.
 445   @param  [in]  NameOpNode       NameOp object node defining a named object.
 446                                  If provided, append the new resource data node
 447                                  to the list of resource data elements of this
 448                                  node.
 449   @param  [out] NewRdNode        If provided and success,
 450                                  contain the created node.
 451
 452   @retval EFI_SUCCESS             The function completed successfully.
 453   @retval EFI_INVALID_PARAMETER   Invalid parameter.
 454   @retval EFI_OUT_OF_RESOURCES    Could not allocate memory.
 455 **/
 456 EFI_STATUS
 457 EFIAPI
 458 AmlCodeGenRdInterrupt (
 459   IN  BOOLEAN                 ResourceConsumer,
 460   IN  BOOLEAN                 EdgeTriggered,
 461   IN  BOOLEAN                 ActiveLow,
 462   IN  BOOLEAN                 Shared,
 463   IN  UINT32                  *IrqList,
 464   IN  UINT8                   IrqCount,
 465   IN  AML_OBJECT_NODE_HANDLE  NameOpNode  OPTIONAL,
 466   OUT AML_DATA_NODE_HANDLE    *NewRdNode  OPTIONAL
 467   );
 468
 469 /** AML code generation for DefinitionBlock.
 470
 471   Create a Root Node handle.
 472   It is the caller's responsibility to free the allocated memory
 473   with the AmlDeleteTree function.
 474
 475   AmlCodeGenDefinitionBlock (TableSignature, OemId, TableID, OEMRevision) is
 476   equivalent to the following ASL code:
 477     DefinitionBlock (AMLFileName, TableSignature, ComplianceRevision,
 478       OemId, TableID, OEMRevision) {}
 479   with the ComplianceRevision set to 2 and the AMLFileName is ignored.
 480
 481   @ingroup CodeGenApis
 482
 483   @param[in]  TableSignature       4-character ACPI signature.
 484                                    Must be 'DSDT' or 'SSDT'.
 485   @param[in]  OemId                6-character string OEM identifier.
 486   @param[in]  OemTableId           8-character string OEM table identifier.
 487   @param[in]  OemRevision          OEM revision number.
 488   @param[out] DefinitionBlockTerm  The ASL Term handle representing a
 489                                    Definition Block.
 490
 491   @retval EFI_SUCCESS             Success.
 492   @retval EFI_INVALID_PARAMETER   Invalid parameter.
 493   @retval EFI_OUT_OF_RESOURCES    Failed to allocate memory.
 494 **/
 495 EFI_STATUS
 496 EFIAPI
 497 AmlCodeGenDefinitionBlock (
 498   IN  CONST CHAR8                 * TableSignature,
 499   IN  CONST CHAR8                 * OemId,
 500   IN  CONST CHAR8                 * OemTableId,
 501   IN        UINT32                  OemRevision,
 502   OUT       AML_ROOT_NODE_HANDLE  * NewRootNode
 503   );
 504
 505 /** AML code generation for a Name object node, containing a String.
 506
 507   AmlCodeGenNameString ("_HID", "HID0000", ParentNode, NewObjectNode) is
 508   equivalent of the following ASL code:
 509     Name(_HID, "HID0000")
 510
 511   @ingroup CodeGenApis
 512
 513   @param  [in] NameString     The new variable name.
 514                               Must be a NULL-terminated ASL NameString
 515                               e.g.: "DEV0", "DV15.DEV0", etc.
 516                               The input string is copied.
 517   @param [in]  String         NULL terminated String to associate to the
 518                               NameString.
 519   @param [in]  ParentNode     If provided, set ParentNode as the parent
 520                               of the node created.
 521   @param [out] NewObjectNode  If success, contains the created node.
 522
 523   @retval EFI_SUCCESS             Success.
 524   @retval EFI_INVALID_PARAMETER   Invalid parameter.
 525   @retval EFI_OUT_OF_RESOURCES    Failed to allocate memory.
 526 **/
 527 EFI_STATUS
 528 EFIAPI
 529 AmlCodeGenNameString (
 530   IN  CONST CHAR8                   * NameString,
 531   IN        CHAR8                   * String,
 532   IN        AML_NODE_HANDLE           ParentNode      OPTIONAL,
 533   OUT       AML_OBJECT_NODE_HANDLE  * NewObjectNode   OPTIONAL
 534   );
 535
 536 /** AML code generation for a Name object node, containing an Integer.
 537
 538   AmlCodeGenNameInteger ("_UID", 1, ParentNode, NewObjectNode) is
 539   equivalent of the following ASL code:
 540     Name(_UID, One)
 541
 542   @ingroup CodeGenApis
 543
 544   @param  [in] NameString     The new variable name.
 545                               Must be a NULL-terminated ASL NameString
 546                               e.g.: "DEV0", "DV15.DEV0", etc.
 547                               The input string is copied.
 548   @param [in]  Integer        Integer to associate to the NameString.
 549   @param [in]  ParentNode     If provided, set ParentNode as the parent
 550                               of the node created.
 551   @param [out] NewObjectNode  If success, contains the created node.
 552
 553   @retval EFI_SUCCESS             Success.
 554   @retval EFI_INVALID_PARAMETER   Invalid parameter.
 555   @retval EFI_OUT_OF_RESOURCES    Failed to allocate memory.
 556 **/
 557 EFI_STATUS
 558 EFIAPI
 559 AmlCodeGenNameInteger (
 560   IN  CONST CHAR8                   * NameString,
 561   IN        UINT64                    Integer,
 562   IN        AML_NODE_HANDLE           ParentNode      OPTIONAL,
 563   OUT       AML_OBJECT_NODE_HANDLE  * NewObjectNode   OPTIONAL
 564   );
 565
 566 /** AML code generation for a Device object node.
 567
 568   AmlCodeGenDevice ("COM0", ParentNode, NewObjectNode) is
 569   equivalent of the following ASL code:
 570     Device(COM0) {}
 571
 572   @ingroup CodeGenApis
 573
 574   @param  [in] NameString     The new Device's name.
 575                               Must be a NULL-terminated ASL NameString
 576                               e.g.: "DEV0", "DV15.DEV0", etc.
 577                               The input string is copied.
 578   @param [in]  ParentNode     If provided, set ParentNode as the parent
 579                               of the node created.
 580   @param [out] NewObjectNode  If success, contains the created node.
 581
 582   @retval EFI_SUCCESS             Success.
 583   @retval EFI_INVALID_PARAMETER   Invalid parameter.
 584   @retval EFI_OUT_OF_RESOURCES    Failed to allocate memory.
 585 **/
 586 EFI_STATUS
 587 EFIAPI
 588 AmlCodeGenDevice (
 589   IN  CONST CHAR8                   * NameString,
 590   IN        AML_NODE_HANDLE           ParentNode      OPTIONAL,
 591   OUT       AML_OBJECT_NODE_HANDLE  * NewObjectNode   OPTIONAL
 592   );
 593
 594 /** AML code generation for a Scope object node.
 595
 596   AmlCodeGenScope ("_SB", ParentNode, NewObjectNode) is
 597   equivalent of the following ASL code:
 598     Scope(_SB) {}
 599
 600   @ingroup CodeGenApis
 601
 602   @param  [in] NameString     The new Scope's name.
 603                               Must be a NULL-terminated ASL NameString
 604                               e.g.: "DEV0", "DV15.DEV0", etc.
 605                               The input string is copied.
 606   @param [in]  ParentNode     If provided, set ParentNode as the parent
 607                               of the node created.
 608   @param [out] NewObjectNode  If success, contains the created node.
 609
 610   @retval EFI_SUCCESS             Success.
 611   @retval EFI_INVALID_PARAMETER   Invalid parameter.
 612   @retval EFI_OUT_OF_RESOURCES    Failed to allocate memory.
 613 **/
 614 EFI_STATUS
 615 EFIAPI
 616 AmlCodeGenScope (
 617   IN  CONST CHAR8                   * NameString,
 618   IN        AML_NODE_HANDLE           ParentNode      OPTIONAL,
 619   OUT       AML_OBJECT_NODE_HANDLE  * NewObjectNode   OPTIONAL
 620   );
 621
 622 /** AML code generation for a method returning a NameString.
 623
 624   AmlCodeGenMethodRetNameString (
 625     "MET0", "_CRS", 1, TRUE, 3, ParentNode, NewObjectNode
 626     );
 627   is equivalent of the following ASL code:
 628     Method(MET0, 1, Serialized, 3) {
 629       Return (_CRS)
 630     }
 631
 632   The ASL parameters "ReturnType" and "ParameterTypes" are not asked
 633   in this function. They are optional parameters in ASL.
 634
 635   @ingroup CodeGenApis
 636
 637   @param [in]  MethodNameString     The new Method's name.
 638                                     Must be a NULL-terminated ASL NameString
 639                                     e.g.: "MET0", "_SB.MET0", etc.
 640                                     The input string is copied.
 641   @param [in]  ReturnedNameString   The name of the object returned by the
 642                                     method. Optional parameter, can be:
 643                                      - NULL (ignored).
 644                                      - A NULL-terminated ASL NameString.
 645                                        e.g.: "MET0", "_SB.MET0", etc.
 646                                        The input string is copied.
 647   @param [in]  NumArgs              Number of arguments.
 648                                     Must be 0 <= NumArgs <= 6.
 649   @param [in]  IsSerialized         TRUE is equivalent to Serialized.
 650                                     FALSE is equivalent to NotSerialized.
 651                                     Default is NotSerialized in ASL spec.
 652   @param [in]  SyncLevel            Synchronization level for the method.
 653                                     Must be 0 <= SyncLevel <= 15.
 654                                     Default is 0 in ASL.
 655   @param [in]  ParentNode           If provided, set ParentNode as the parent
 656                                     of the node created.
 657   @param [out] NewObjectNode        If success, contains the created node.
 658
 659   @retval EFI_SUCCESS             Success.
 660   @retval EFI_INVALID_PARAMETER   Invalid parameter.
 661   @retval EFI_OUT_OF_RESOURCES    Failed to allocate memory.
 662 **/
 663 EFI_STATUS
 664 EFIAPI
 665 AmlCodeGenMethodRetNameString (
 666   IN  CONST CHAR8                   * MethodNameString,
 667   IN  CONST CHAR8                   * ReturnedNameString   OPTIONAL,
 668   IN        UINT8                     NumArgs,
 669   IN        BOOLEAN                   IsSerialized,
 670   IN        UINT8                     SyncLevel,
 671   IN        AML_NODE_HANDLE           ParentNode           OPTIONAL,
 672   OUT       AML_OBJECT_NODE_HANDLE  * NewObjectNode        OPTIONAL
 673   );
 674
 675 /** Create a _LPI name.
 676
 677   AmlCreateLpiNode ("_LPI", 0, 1, ParentNode, &LpiNode) is
 678   equivalent of the following ASL code:
 679     Name (_LPI, Package (
 680                   0,  // Revision
 681                   1,  // LevelId
 682                   0   // Count
 683                   ))
 684
 685   This function doesn't define any LPI state. As shown above, the count
 686   of _LPI state is set to 0.
 687   The AmlAddLpiState () function must be used to add LPI states.
 688
 689   Cf ACPI 6.3 specification, s8.4.4 "Lower Power Idle States".
 690
 691   @ingroup CodeGenApis
 692
 693   @param [in]  LpiNameString  The new LPI 's object name.
 694                               Must be a NULL-terminated ASL NameString
 695                               e.g.: "_LPI", "DEV0.PLPI", etc.
 696                               The input string is copied.
 697   @param [in]  Revision       Revision number of the _LPI states.
 698   @param [in]  LevelId        A platform defined number that identifies the
 699                               level of hierarchy of the processor node to
 700                               which the LPI states apply.
 701   @param [in]  ParentNode     If provided, set ParentNode as the parent
 702                               of the node created.
 703   @param [out] NewLpiNode     If success, contains the created node.
 704
 705   @retval EFI_SUCCESS             The function completed successfully.
 706   @retval EFI_INVALID_PARAMETER   Invalid parameter.
 707   @retval EFI_OUT_OF_RESOURCES    Failed to allocate memory.
 708 **/
 709 EFI_STATUS
 710 EFIAPI
 711 AmlCreateLpiNode (
 712   IN  CONST CHAR8                   * LpiNameString,
 713   IN        UINT16                    Revision,
 714   IN        UINT64                    LevelId,
 715   IN        AML_NODE_HANDLE           ParentNode   OPTIONAL,
 716   OUT       AML_OBJECT_NODE_HANDLE  * NewLpiNode   OPTIONAL
 717   );
 718
 719 /** Add an _LPI state to a LPI node created using AmlCreateLpiNode ().
 720
 721   AmlAddLpiState () increments the Count of LPI states in the LPI node by one,
 722   and adds the following package:
 723     Package() {
 724       MinResidency,
 725       WorstCaseWakeLatency,
 726       Flags,
 727       ArchFlags,
 728       ResCntFreq,
 729       EnableParentState,
 730       (GenericRegisterDescriptor != NULL) ?           // Entry method. If a
 731         ResourceTemplate(GenericRegisterDescriptor) : // Register is given,
 732         Integer,                                      // use it. Use the
 733                                                       // Integer otherwise.
 734       ResourceTemplate() {                            // NULL Residency Counter
 735         Register (SystemMemory, 0, 0, 0, 0)
 736       },
 737       ResourceTemplate() {                            // NULL Usage Counter
 738         Register (SystemMemory, 0, 0, 0, 0)
 739       },
 740       ""                                              // NULL State Name
 741     },
 742
 743   Cf ACPI 6.3 specification, s8.4.4 "Lower Power Idle States".
 744
 745   @ingroup CodeGenApis
 746
 747   @param [in]  MinResidency               Minimum Residency.
 748   @param [in]  WorstCaseWakeLatency       Worst case wake-up latency.
 749   @param [in]  Flags                      Flags.
 750   @param [in]  ArchFlags                  Architectural flags.
 751   @param [in]  ResCntFreq                 Residency Counter Frequency.
 752   @param [in]  EnableParentState          Enabled Parent State.
 753   @param [in]  GenericRegisterDescriptor  Entry Method.
 754                                           If not NULL, use this Register to
 755                                           describe the entry method address.
 756   @param [in]  Integer                    Entry Method.
 757                                           If GenericRegisterDescriptor is NULL,
 758                                           take this value.
 759   @param [in]  ResidencyCounterRegister   If not NULL, use it to populate the
 760                                           residency counter register.
 761   @param [in]  UsageCounterRegister       If not NULL, use it to populate the
 762                                           usage counter register.
 763   @param [in]  StateName                  If not NULL, use it to populate the
 764                                           state name.
 765   @param [in]  LpiNode                    Lpi node created with the function
 766                                           AmlCreateLpiNode to which the new LPI
 767                                           state is appended.
 768
 769   @retval EFI_SUCCESS             The function completed successfully.
 770   @retval EFI_INVALID_PARAMETER   Invalid parameter.
 771   @retval EFI_OUT_OF_RESOURCES    Failed to allocate memory.
 772 **/
 773 EFI_STATUS
 774 EFIAPI
 775 AmlAddLpiState (
 776   IN  UINT32                                    MinResidency,
 777   IN  UINT32                                    WorstCaseWakeLatency,
 778   IN  UINT32                                    Flags,
 779   IN  UINT32                                    ArchFlags,
 780   IN  UINT32                                    ResCntFreq,
 781   IN  UINT32                                    EnableParentState,
 782   IN  EFI_ACPI_6_3_GENERIC_ADDRESS_STRUCTURE  * GenericRegisterDescriptor   OPTIONAL,
 783   IN  UINT64                                    Integer                     OPTIONAL,
 784   IN  EFI_ACPI_6_3_GENERIC_ADDRESS_STRUCTURE  * ResidencyCounterRegister    OPTIONAL,
 785   IN  EFI_ACPI_6_3_GENERIC_ADDRESS_STRUCTURE  * UsageCounterRegister        OPTIONAL,
 786   IN  CHAR8                                   * StateName                   OPTIONAL,
 787   IN  AML_OBJECT_NODE_HANDLE                    LpiNode
 788   );
 789
 790 // DEPRECATED APIS
 791 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
 792
 793 /** DEPRECATED API
 794
 795   Get the first Resource Data element contained in a "_CRS" object.
 796
 797   In the following ASL code, the function will return the Resource Data
 798   node corresponding to the "QWordMemory ()" ASL macro.
 799   Name (_CRS, ResourceTemplate() {
 800       QWordMemory (...) {...},
 801       Interrupt (...) {...}
 802     }
 803   )
 804
 805   Note:
 806    - The "_CRS" object must be declared using ASL "Name (Declare Named Object)".
 807    - "_CRS" declared using ASL "Method (Declare Control Method)" is not
 808      supported.
 809
 810   @ingroup UserApis
 811
 812   @param  [in] NameOpCrsNode  NameOp object node defining a "_CRS" object.
 813                               Must have an OpCode=AML_NAME_OP, SubOpCode=0.
 814                               NameOp object nodes are defined in ASL
 815                               using the "Name ()" function.
 816   @param  [out] OutRdNode     Pointer to the first Resource Data element of
 817                               the "_CRS" object. A Resource Data element
 818                               is stored in a data node.
 819
 820   @retval EFI_SUCCESS             The function completed successfully.
 821   @retval EFI_INVALID_PARAMETER   Invalid parameter.
 822 **/
 823 EFI_STATUS
 824 EFIAPI
 825 AmlNameOpCrsGetFirstRdNode (
 826   IN  AML_OBJECT_NODE_HANDLE   NameOpCrsNode,
 827   OUT AML_DATA_NODE_HANDLE   * OutRdNode
 828   );
 829
 830 /** DEPRECATED API
 831
 832   Get the Resource Data element following the CurrRdNode Resource Data.
 833
 834   In the following ASL code, if CurrRdNode corresponds to the first
 835   "QWordMemory ()" ASL macro, the function will return the Resource Data
 836   node corresponding to the "Interrupt ()" ASL macro.
 837   Name (_CRS, ResourceTemplate() {
 838       QwordMemory (...) {...},
 839       Interrupt (...) {...}
 840     }
 841   )
 842
 843   The CurrRdNode Resource Data node must be defined in an object named "_CRS"
 844   and defined by a "Name ()" ASL function.
 845
 846   @ingroup UserApis
 847
 848   @param  [in]  CurrRdNode   Pointer to the current Resource Data element of
 849                              the "_CRS" variable.
 850   @param  [out] OutRdNode    Pointer to the Resource Data element following
 851                              the CurrRdNode.
 852                              Contain a NULL pointer if CurrRdNode is the
 853                              last Resource Data element in the list.
 854                              The "End Tag" is not considered as a resource
 855                              data element and is not returned.
 856
 857   @retval EFI_SUCCESS             The function completed successfully.
 858   @retval EFI_INVALID_PARAMETER   Invalid parameter.
 859 **/
 860 EFI_STATUS
 861 EFIAPI
 862 AmlNameOpCrsGetNextRdNode (
 863   IN  AML_DATA_NODE_HANDLE    CurrRdNode,
 864   OUT AML_DATA_NODE_HANDLE  * OutRdNode
 865   );
 866
 867 /** DEPRECATED API
 868
 869   Add an Interrupt Resource Data node.
 870
 871   This function creates a Resource Data element corresponding to the
 872   "Interrupt ()" ASL function, stores it in an AML Data Node.
 873
 874   It then adds it after the input CurrRdNode in the list of resource data
 875   element.
 876
 877   The Resource Data effectively created is an Extended Interrupt Resource
 878   Data. See ACPI 6.3 specification, s6.4.3.6 "Extended Interrupt Descriptor"
 879   for more information about Extended Interrupt Resource Data.
 880
 881   The Extended Interrupt contains one single interrupt.
 882
 883   This function allocates memory to create a data node. It is the caller's
 884   responsibility to either:
 885    - attach this node to an AML tree;
 886    - delete this node.
 887
 888   Note: The _CRS node must be defined using the ASL Name () function.
 889         e.g. Name (_CRS, ResourceTemplate () {
 890                ...
 891              }
 892
 893   @ingroup CodeGenApis
 894
 895   @param  [in]  NameOpCrsNode    NameOp object node defining a "_CRS" object.
 896                                  Must have an OpCode=AML_NAME_OP, SubOpCode=0.
 897                                  NameOp object nodes are defined in ASL
 898                                  using the "Name ()" function.
 899   @param  [in]  ResourceConsumer The device consumes the specified interrupt
 900                                  or produces it for use by a child device.
 901   @param  [in]  EdgeTriggered    The interrupt is edge triggered or
 902                                  level triggered.
 903   @param  [in]  ActiveLow        The interrupt is active-high or active-low.
 904   @param  [in]  Shared           The interrupt can be shared with other
 905                                  devices or not (Exclusive).
 906   @param  [in]  IrqList          Interrupt list. Must be non-NULL.
 907   @param  [in]  IrqCount         Interrupt count. Must be non-zero.
 908
 909
 910   @retval EFI_SUCCESS             The function completed successfully.
 911   @retval EFI_INVALID_PARAMETER   Invalid parameter.
 912   @retval EFI_OUT_OF_RESOURCES    Could not allocate memory.
 913 **/
 914 EFI_STATUS
 915 EFIAPI
 916 AmlCodeGenCrsAddRdInterrupt (
 917   IN  AML_OBJECT_NODE_HANDLE  NameOpCrsNode,
 918   IN  BOOLEAN                 ResourceConsumer,
 919   IN  BOOLEAN                 EdgeTriggered,
 920   IN  BOOLEAN                 ActiveLow,
 921   IN  BOOLEAN                 Shared,
 922   IN  UINT32                * IrqList,
 923   IN  UINT8                   IrqCount
 924   );
 925
 926 #endif // DISABLE_NEW_DEPRECATED_INTERFACES
 927
 928 #endif // AML_LIB_H_