DynamicTablesPkg/Library/Common/AmlLib/AmlDbgPrint/AmlDbgPrint.h

   1 /** @file
   2   AML Debug Print.
   3
   4   Copyright (c) 2010 - 2018, Intel Corporation. All rights reserved. <BR>
   5   Copyright (c) 2019 - 2020, Arm Limited. All rights reserved.<BR>
   6
   7   SPDX-License-Identifier: BSD-2-Clause-Patent
   8 **/
   9
  10 #ifndef AML_PRINT_H_
  11 #define AML_PRINT_H_
  12
  13 /* This header file does not include internal Node definition,
  14    i.e. AML_ROOT_NODE, AML_OBJECT_NODE, etc. The node definitions
  15    must be included by the caller file. The function prototypes must
  16    only expose AML_NODE_HANDLE, AML_ROOT_NODE_HANDLE, etc. node
  17    definitions.
  18    This allows to keep the functions defined here both internal and
  19    potentially external. If necessary, any function of this file can
  20    be exposed externally.
  21    The Api folder is internal to the AmlLib, but should only use these
  22    functions. They provide a "safe" way to interact with the AmlLib.
  23 */
  24
  25 #if !defined (MDEPKG_NDEBUG)
  26
  27   #include <AmlInclude.h>
  28
  29 /**
  30   @defgroup DbgPrintApis Print APIs for debugging.
  31   @ingroup AMLLib
  32   @{
  33     Print APIs provide a way to print:
  34      - A buffer;
  35      - A (root/object/data) node;
  36      - An AML tree/branch;
  37      - The AML NameSpace from the root node.
  38   @}
  39 */
  40
  41 /** This function performs a raw data dump of the ACPI table.
  42
  43   @param  [in]  Ptr     Pointer to the start of the table buffer.
  44   @param  [in]  Length  The length of the buffer.
  45 **/
  46 VOID
  47 EFIAPI
  48 AmlDbgDumpRaw (
  49   IN  CONST UINT8   *Ptr,
  50   IN        UINT32  Length
  51   );
  52
  53 /** Print Size chars at Buffer address.
  54
  55   @ingroup DbgPrintApis
  56
  57   @param  [in]  ErrorLevel    Error level for the DEBUG macro.
  58   @param  [in]  Buffer        Buffer containing the chars.
  59   @param  [in]  Size          Number of chars to print.
  60 **/
  61 VOID
  62 EFIAPI
  63 AmlDbgPrintChars (
  64   IN        UINT32  ErrorLevel,
  65   IN  CONST CHAR8   *Buffer,
  66   IN        UINT32  Size
  67   );
  68
  69 /** Print an AML NameSeg.
  70     Don't print trailing underscores ('_').
  71
  72   @param  [in] Buffer   Buffer containing an AML NameSeg.
  73 **/
  74 VOID
  75 EFIAPI
  76 AmlDbgPrintNameSeg (
  77   IN  CONST CHAR8  *Buffer
  78   );
  79
  80 /** Print an AML NameString.
  81
  82   @param  [in] Buffer   Buffer containing an AML NameString.
  83   @param  [in] NewLine  Print a newline char at the end of the NameString.
  84 **/
  85 VOID
  86 EFIAPI
  87 AmlDbgPrintNameString (
  88   IN  CONST CHAR8    *Buffer,
  89   IN        BOOLEAN  NewLine
  90   );
  91
  92 /** Print Node information.
  93
  94   @ingroup DbgPrintApis
  95
  96   @param  [in]  Node    Pointer to the Node to print.
  97                         Can be a root/object/data node.
  98 **/
  99 VOID
 100 EFIAPI
 101 AmlDbgPrintNode (
 102   IN  AML_NODE_HANDLE  Node
 103   );
 104
 105 /** Recursively print the subtree under the Node.
 106
 107   @ingroup DbgPrintApis
 108
 109   @param  [in]  Node    Pointer to the root of the subtree to print.
 110                         Can be a root/object/data node.
 111 **/
 112 VOID
 113 EFIAPI
 114 AmlDbgPrintTree (
 115   IN  AML_NODE_HANDLE  Node
 116   );
 117
 118 /** Print the absolute pathnames in the AML namespace of
 119     all the nodes in the tree starting from the Root node.
 120
 121   @ingroup DbgPrintApis
 122
 123   @param  [in]  RootNode    Pointer to a root node.
 124
 125   @retval EFI_SUCCESS             The function completed successfully.
 126   @retval EFI_BUFFER_TOO_SMALL    No space left in the buffer.
 127   @retval EFI_INVALID_PARAMETER   Invalid parameter.
 128   @retval EFI_OUT_OF_RESOURCES    Out of memory.
 129 **/
 130 EFI_STATUS
 131 EFIAPI
 132 AmlDbgPrintNameSpace (
 133   IN  AML_ROOT_NODE_HANDLE  RootNode
 134   );
 135
 136 /* Macros to encapsulate Aml Debug Print APIs.
 137 */
 138
 139 #define AMLDBG_DUMP_RAW(Ptr, Length)                  \
 140           AmlDbgDumpRaw (Ptr, Length)
 141
 142 #define AMLDBG_PRINT_CHARS(ErrorLevel, Buffer, Size)  \
 143           AmlDbgPrintChars (ErrorLevel, Buffer, Size)
 144
 145 #define AMLDBG_PRINT_NAMESEG(Buffer)                  \
 146           AmlDbgPrintNameSeg (Buffer)
 147
 148 #define AMLDBG_PRINT_NAMESTR(Buffer, NewLine)          \
 149           AmlDbgPrintNameString (Buffer,NewLine)
 150
 151 #define AMLDBG_PRINT_NODE(Node)                       \
 152           AmlDbgPrintNode (Node)
 153
 154 #define AMLDBG_PRINT_TREE(Node)                       \
 155           AmlDbgPrintTree (Node)
 156
 157 #define AMLDBG_PRINT_NAMESPACE(RootNode)              \
 158           AmlDbgPrintNameSpace (RootNode)
 159
 160 #else
 161
 162 #define AMLDBG_DUMP_RAW(Ptr, Length)
 163
 164 #define AMLDBG_PRINT_CHARS(ErrorLevel, Buffer, Size)
 165
 166 #define AMLDBG_PRINT_NAMESEG(Buffer)
 167
 168 #define AMLDBG_PRINT_NAMESTR(Buffer, NewLine)
 169
 170 #define AMLDBG_PRINT_NODE(Node)
 171
 172 #define AMLDBG_PRINT_TREE(Node)
 173
 174 #define AMLDBG_PRINT_NAMESPACE(RootNode)
 175
 176 #endif // MDEPKG_NDEBUG
 177
 178 #endif // AML_PRINT_H_