include/llvm-c/OptRemarks.h

   1 /*===-- llvm-c/OptRemarks.h - OptRemarks Public C Interface -------*- C -*-===*\
   2 |*                                                                            *|
   3 |* Part of the LLVM Project, under the Apache License v2.0 with LLVM          *|
   4 |* Exceptions.                                                                *|
   5 |* See https://llvm.org/LICENSE.txt for license information.                  *|
   6 |* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception                    *|
   7 |*                                                                            *|
   8 |*===----------------------------------------------------------------------===*|
   9 |*                                                                            *|
  10 |* This header provides a public interface to an opt-remark library.          *|
  11 |* LLVM provides an implementation of this interface.                         *|
  12 |*                                                                            *|
  13 \*===----------------------------------------------------------------------===*/
  14
  15 #ifndef LLVM_C_OPT_REMARKS_H
  16 #define LLVM_C_OPT_REMARKS_H
  17
  18 #include "llvm-c/Core.h"
  19 #include "llvm-c/Types.h"
  20 #ifdef __cplusplus
  21 #include <cstddef>
  22 extern "C" {
  23 #else
  24 #include <stddef.h>
  25 #endif /* !defined(__cplusplus) */
  26
  27 /**
  28  * @defgroup LLVMCOPTREMARKS OptRemarks
  29  * @ingroup LLVMC
  30  *
  31  * @{
  32  */
  33
  34 #define OPT_REMARKS_API_VERSION 0
  35
  36 /**
  37  * String containing a buffer and a length. The buffer is not guaranteed to be
  38  * zero-terminated.
  39  *
  40  * \since OPT_REMARKS_API_VERSION=0
  41  */
  42 typedef struct {
  43   const char *Str;
  44   uint32_t Len;
  45 } LLVMOptRemarkStringRef;
  46
  47 /**
  48  * DebugLoc containing File, Line and Column.
  49  *
  50  * \since OPT_REMARKS_API_VERSION=0
  51  */
  52 typedef struct {
  53   // File:
  54   LLVMOptRemarkStringRef SourceFile;
  55   // Line:
  56   uint32_t SourceLineNumber;
  57   // Column:
  58   uint32_t SourceColumnNumber;
  59 } LLVMOptRemarkDebugLoc;
  60
  61 /**
  62  * Element of the "Args" list. The key might give more information about what
  63  * are the semantics of the value, e.g. "Callee" will tell you that the value
  64  * is a symbol that names a function.
  65  *
  66  * \since OPT_REMARKS_API_VERSION=0
  67  */
  68 typedef struct {
  69   // e.g. "Callee"
  70   LLVMOptRemarkStringRef Key;
  71   // e.g. "malloc"
  72   LLVMOptRemarkStringRef Value;
  73
  74   // "DebugLoc": Optional
  75   LLVMOptRemarkDebugLoc DebugLoc;
  76 } LLVMOptRemarkArg;
  77
  78 /**
  79  * One remark entry.
  80  *
  81  * \since OPT_REMARKS_API_VERSION=0
  82  */
  83 typedef struct {
  84   // e.g. !Missed, !Passed
  85   LLVMOptRemarkStringRef RemarkType;
  86   // "Pass": Required
  87   LLVMOptRemarkStringRef PassName;
  88   // "Name": Required
  89   LLVMOptRemarkStringRef RemarkName;
  90   // "Function": Required
  91   LLVMOptRemarkStringRef FunctionName;
  92
  93   // "DebugLoc": Optional
  94   LLVMOptRemarkDebugLoc DebugLoc;
  95   // "Hotness": Optional
  96   uint32_t Hotness;
  97   // "Args": Optional. It is an array of `num_args` elements.
  98   uint32_t NumArgs;
  99   LLVMOptRemarkArg *Args;
 100 } LLVMOptRemarkEntry;
 101
 102 typedef struct LLVMOptRemarkOpaqueParser *LLVMOptRemarkParserRef;
 103
 104 /**
 105  * Creates a remark parser that can be used to read and parse the buffer located
 106  * in \p Buf of size \p Size.
 107  *
 108  * \p Buf cannot be NULL.
 109  *
 110  * This function should be paired with LLVMOptRemarkParserDispose() to avoid
 111  * leaking resources.
 112  *
 113  * \since OPT_REMARKS_API_VERSION=0
 114  */
 115 extern LLVMOptRemarkParserRef LLVMOptRemarkParserCreate(const void *Buf,
 116                                                         uint64_t Size);
 117
 118 /**
 119  * Returns the next remark in the file.
 120  *
 121  * The value pointed to by the return value is invalidated by the next call to
 122  * LLVMOptRemarkParserGetNext().
 123  *
 124  * If the parser reaches the end of the buffer, the return value will be NULL.
 125  *
 126  * In the case of an error, the return value will be NULL, and:
 127  *
 128  * 1) LLVMOptRemarkParserHasError() will return `1`.
 129  *
 130  * 2) LLVMOptRemarkParserGetErrorMessage() will return a descriptive error
 131  *    message.
 132  *
 133  * An error may occur if:
 134  *
 135  * 1) An argument is invalid.
 136  *
 137  * 2) There is a YAML parsing error. This type of error aborts parsing
 138  *    immediately and returns `1`. It can occur on malformed YAML.
 139  *
 140  * 3) Remark parsing error. If this type of error occurs, the parser won't call
 141  *    the handler and will continue to the next one. It can occur on malformed
 142  *    remarks, like missing or extra fields in the file.
 143  *
 144  * Here is a quick example of the usage:
 145  *
 146  * ```
 147  *  LLVMOptRemarkParserRef Parser = LLVMOptRemarkParserCreate(Buf, Size);
 148  *  LLVMOptRemarkEntry *Remark = NULL;
 149  *  while ((Remark == LLVMOptRemarkParserGetNext(Parser))) {
 150  *    // use Remark
 151  *  }
 152  *  bool HasError = LLVMOptRemarkParserHasError(Parser);
 153  *  LLVMOptRemarkParserDispose(Parser);
 154  * ```
 155  *
 156  * \since OPT_REMARKS_API_VERSION=0
 157  */
 158 extern LLVMOptRemarkEntry *
 159 LLVMOptRemarkParserGetNext(LLVMOptRemarkParserRef Parser);
 160
 161 /**
 162  * Returns `1` if the parser encountered an error while parsing the buffer.
 163  *
 164  * \since OPT_REMARKS_API_VERSION=0
 165  */
 166 extern LLVMBool LLVMOptRemarkParserHasError(LLVMOptRemarkParserRef Parser);
 167
 168 /**
 169  * Returns a null-terminated string containing an error message.
 170  *
 171  * In case of no error, the result is `NULL`.
 172  *
 173  * The memory of the string is bound to the lifetime of \p Parser. If
 174  * LLVMOptRemarkParserDispose() is called, the memory of the string will be
 175  * released.
 176  *
 177  * \since OPT_REMARKS_API_VERSION=0
 178  */
 179 extern const char *
 180 LLVMOptRemarkParserGetErrorMessage(LLVMOptRemarkParserRef Parser);
 181
 182 /**
 183  * Releases all the resources used by \p Parser.
 184  *
 185  * \since OPT_REMARKS_API_VERSION=0
 186  */
 187 extern void LLVMOptRemarkParserDispose(LLVMOptRemarkParserRef Parser);
 188
 189 /**
 190  * Returns the version of the opt-remarks dylib.
 191  *
 192  * \since OPT_REMARKS_API_VERSION=0
 193  */
 194 extern uint32_t LLVMOptRemarkVersion(void);
 195
 196 /**
 197  * @} // endgoup LLVMCOPTREMARKS
 198  */
 199
 200 #ifdef __cplusplus
 201 }
 202 #endif /* !defined(__cplusplus) */
 203
 204 #endif /* LLVM_C_OPT_REMARKS_H */