DynamicTablesPkg/Library/Common/AmlLib/Parser/AmlMethodParser.h

   1 /** @file
   2   AML Method Parser.
   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_METHOD_PARSER_H_
  10 #define AML_METHOD_PARSER_H_
  11
  12 #include <AmlNodeDefines.h>
  13 #include <Stream/AmlStream.h>
  14
  15 /** AML namespace reference node.
  16
  17   Namespace reference nodes allow to associate an AML absolute pathname
  18   to the tree node defining this object in the namespace.
  19
  20   Namespace reference nodes are stored in a separate list. They are not part of
  21   the tree.
  22 */
  23 typedef struct AmlNameSpaceRefNode {
  24   /// Double linked list.
  25   /// This must be the first field in this structure.
  26   LIST_ENTRY               Link;
  27
  28   /// Node part of the AML namespace. It must have the AML_IN_NAMESPACE
  29   /// attribute.
  30   CONST AML_OBJECT_NODE    *NodeRef;
  31
  32   /// Raw AML absolute pathname of the NodeRef.
  33   /// This is a raw AML NameString (cf AmlNameSpace.c: A concatenated list
  34   /// of 4 chars long names. The dual/multi NameString prefix have been
  35   /// stripped.).
  36   CONST CHAR8              *RawAbsolutePath;
  37
  38   /// Size of the raw AML absolute pathname buffer.
  39   UINT32                   RawAbsolutePathSize;
  40 } AML_NAMESPACE_REF_NODE;
  41
  42 /** Delete a list of namespace reference nodes.
  43
  44   @param  [in]  NameSpaceRefList    List of namespace reference nodes.
  45
  46   @retval EFI_SUCCESS             The function completed successfully.
  47   @retval EFI_INVALID_PARAMETER   Invalid parameter.
  48 **/
  49 EFI_STATUS
  50 EFIAPI
  51 AmlDeleteNameSpaceRefList (
  52   IN  LIST_ENTRY  *NameSpaceRefList
  53   );
  54
  55 #if !defined (MDEPKG_NDEBUG)
  56
  57 /** Print the list of raw absolute paths of the NameSpace reference list.
  58
  59   @param  [in]    NameSpaceRefList    List of NameSpace reference nodes.
  60 **/
  61 VOID
  62 EFIAPI
  63 AmlDbgPrintNameSpaceRefList (
  64   IN  CONST LIST_ENTRY  *NameSpaceRefList
  65   );
  66
  67 #endif // MDEPKG_NDEBUG
  68
  69 /** Check whether a pathname is a method invocation.
  70
  71   If there is a matching method definition, returns the corresponding
  72   NameSpaceRef node.
  73
  74   To do so, the NameSpaceRefList is keeping track of every namespace node
  75   and its raw AML absolute path.
  76   To check whether a pathname is a method invocation, a corresponding raw
  77   absolute pathname is built. This raw absolute pathname is then compared
  78   to the list of available pathnames. If a pathname defining a method
  79   matches the scope of the input pathname, return.
  80
  81   @param  [in]  ParentNode          Parent node. Node to which the node to be
  82                                     created will be attached.
  83   @param  [in]  FStream             Forward stream pointing to the NameString
  84                                     to find.
  85   @param  [in]  NameSpaceRefList    List of NameSpaceRef nodes.
  86   @param  [out] OutNameSpaceRefNode If the NameString pointed by FStream is
  87                                     a method invocation, OutNameSpaceRefNode
  88                                     contains the NameSpaceRef corresponding
  89                                     to the method definition.
  90                                     NULL otherwise.
  91
  92   @retval EFI_SUCCESS             The function completed successfully.
  93   @retval EFI_INVALID_PARAMETER   Invalid parameter.
  94 **/
  95 EFI_STATUS
  96 EFIAPI
  97 AmlIsMethodInvocation (
  98   IN  CONST AML_NODE_HEADER   *ParentNode,
  99   IN  CONST AML_STREAM        *FStream,
 100   IN  CONST LIST_ENTRY        *NameSpaceRefList,
 101   OUT AML_NAMESPACE_REF_NODE  **OutNameSpaceRefNode
 102   );
 103
 104 /** Create a namespace reference node and add it to the NameSpaceRefList.
 105
 106   When a namespace node is encountered, the namespace it defines must be
 107   associated to the node. This allow to keep track of the nature of each
 108   name present in the AML namespace.
 109
 110   In the end, this allows to recognize method invocations and parse the right
 111   number of arguments after the method name.
 112
 113   @param [in]       Node              Namespace node.
 114   @param [in, out]  NameSpaceRefList  List of namespace reference nodes.
 115
 116   @retval EFI_SUCCESS             The function completed successfully.
 117   @retval EFI_INVALID_PARAMETER   Invalid parameter.
 118 **/
 119 EFI_STATUS
 120 EFIAPI
 121 AmlAddNameSpaceReference (
 122   IN      CONST AML_OBJECT_NODE  *Node,
 123   IN  OUT       LIST_ENTRY       *NameSpaceRefList
 124   );
 125
 126 /** Create a method invocation node.
 127
 128   The AML grammar does not attribute an OpCode/SubOpCode couple for
 129   method invocations. This library is representing method invocations
 130   as if they had one.
 131
 132   The AML encoding for method invocations in the ACPI specification 6.3 is:
 133     MethodInvocation := NameString TermArgList
 134   In this library, it is:
 135     MethodInvocation := MethodInvocationOp NameString ArgumentCount TermArgList
 136     ArgumentCount    := ByteData
 137
 138   When computing the size of a tree or serializing it, the additional data is
 139   not taken into account (i.e. the MethodInvocationOp and the ArgumentCount).
 140
 141   Method invocation nodes have the AML_METHOD_INVOVATION attribute.
 142
 143   @param  [in]  NameSpaceRefNode          NameSpaceRef node pointing to the
 144                                           the definition of the invoked
 145                                           method.
 146   @param  [in]  MethodInvocationName      Data node containing the method
 147                                           invocation name.
 148   @param  [out] MethodInvocationNodePtr   Created method invocation node.
 149
 150   @retval EFI_SUCCESS             The function completed successfully.
 151   @retval EFI_INVALID_PARAMETER   Invalid parameter.
 152   @retval EFI_OUT_OF_RESOURCES    Could not allocate memory.
 153 **/
 154 EFI_STATUS
 155 EFIAPI
 156 AmlCreateMethodInvocationNode (
 157   IN  CONST AML_NAMESPACE_REF_NODE  *NameSpaceRefNode,
 158   IN        AML_DATA_NODE           *MethodInvocationName,
 159   OUT       AML_OBJECT_NODE         **MethodInvocationNodePtr
 160   );
 161
 162 /** Get the number of arguments of a method invocation node.
 163
 164   This function also allow to identify whether a node is a method invocation
 165   node. If the input node is not a method invocation node, just return.
 166
 167   @param  [in]  MethodInvocationNode  Method invocation node.
 168   @param  [out] IsMethodInvocation    Boolean stating whether the input
 169                                       node is a method invocation.
 170   @param  [out] ArgCount              Number of arguments of the method
 171                                       invocation.
 172                                       Set to 0 if MethodInvocationNode
 173                                       is not a method invocation.
 174
 175   @retval EFI_SUCCESS             The function completed successfully.
 176   @retval EFI_BUFFER_TOO_SMALL    No space left in the buffer.
 177   @retval EFI_INVALID_PARAMETER   Invalid parameter.
 178   @retval EFI_OUT_OF_RESOURCES    Could not allocate memory.
 179 */
 180 EFI_STATUS
 181 EFIAPI
 182 AmlGetMethodInvocationArgCount (
 183   IN  CONST AML_OBJECT_NODE  *MethodInvocationNode,
 184   OUT       BOOLEAN          *IsMethodInvocation,
 185   OUT       UINT8            *ArgCount
 186   );
 187
 188 #endif // AML_METHOD_PARSER_H_