include/llvm-c/Remarks.h

   1 /*===-- llvm-c/Remarks.h - Remarks 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 a remark diagnostics library.   *|
  11 |* LLVM provides an implementation of this interface.                         *|
  12 |*                                                                            *|
  13 \*===----------------------------------------------------------------------===*/
  14
  15 #ifndef LLVM_C_REMARKS_H
  16 #define LLVM_C_REMARKS_H
  17
  18 #include "llvm-c/Types.h"
  19 #ifdef __cplusplus
  20 #include <cstddef>
  21 extern "C" {
  22 #else
  23 #include <stddef.h>
  24 #endif /* !defined(__cplusplus) */
  25
  26 /**
  27  * @defgroup LLVMCREMARKS Remarks
  28  * @ingroup LLVMC
  29  *
  30  * @{
  31  */
  32
  33 #define REMARKS_API_VERSION 0
  34
  35 /**
  36  * The type of the emitted remark.
  37  */
  38 enum LLVMRemarkType {
  39   LLVMRemarkTypeUnknown,
  40   LLVMRemarkTypePassed,
  41   LLVMRemarkTypeMissed,
  42   LLVMRemarkTypeAnalysis,
  43   LLVMRemarkTypeAnalysisFPCommute,
  44   LLVMRemarkTypeAnalysisAliasing,
  45   LLVMRemarkTypeFailure
  46 };
  47
  48 /**
  49  * String containing a buffer and a length. The buffer is not guaranteed to be
  50  * zero-terminated.
  51  *
  52  * \since REMARKS_API_VERSION=0
  53  */
  54 typedef struct LLVMRemarkOpaqueString *LLVMRemarkStringRef;
  55
  56 /**
  57  * Returns the buffer holding the string.
  58  *
  59  * \since REMARKS_API_VERSION=0
  60  */
  61 extern const char *LLVMRemarkStringGetData(LLVMRemarkStringRef String);
  62
  63 /**
  64  * Returns the size of the string.
  65  *
  66  * \since REMARKS_API_VERSION=0
  67  */
  68 extern uint32_t LLVMRemarkStringGetLen(LLVMRemarkStringRef String);
  69
  70 /**
  71  * DebugLoc containing File, Line and Column.
  72  *
  73  * \since REMARKS_API_VERSION=0
  74  */
  75 typedef struct LLVMRemarkOpaqueDebugLoc *LLVMRemarkDebugLocRef;
  76
  77 /**
  78  * Return the path to the source file for a debug location.
  79  *
  80  * \since REMARKS_API_VERSION=0
  81  */
  82 extern LLVMRemarkStringRef
  83 LLVMRemarkDebugLocGetSourceFilePath(LLVMRemarkDebugLocRef DL);
  84
  85 /**
  86  * Return the line in the source file for a debug location.
  87  *
  88  * \since REMARKS_API_VERSION=0
  89  */
  90 extern uint32_t LLVMRemarkDebugLocGetSourceLine(LLVMRemarkDebugLocRef DL);
  91
  92 /**
  93  * Return the column in the source file for a debug location.
  94  *
  95  * \since REMARKS_API_VERSION=0
  96  */
  97 extern uint32_t LLVMRemarkDebugLocGetSourceColumn(LLVMRemarkDebugLocRef DL);
  98
  99 /**
 100  * Element of the "Args" list. The key might give more information about what
 101  * the semantics of the value are, e.g. "Callee" will tell you that the value
 102  * is a symbol that names a function.
 103  *
 104  * \since REMARKS_API_VERSION=0
 105  */
 106 typedef struct LLVMRemarkOpaqueArg *LLVMRemarkArgRef;
 107
 108 /**
 109  * Returns the key of an argument. The key defines what the value is, and the
 110  * same key can appear multiple times in the list of arguments.
 111  *
 112  * \since REMARKS_API_VERSION=0
 113  */
 114 extern LLVMRemarkStringRef LLVMRemarkArgGetKey(LLVMRemarkArgRef Arg);
 115
 116 /**
 117  * Returns the value of an argument. This is a string that can contain newlines.
 118  *
 119  * \since REMARKS_API_VERSION=0
 120  */
 121 extern LLVMRemarkStringRef LLVMRemarkArgGetValue(LLVMRemarkArgRef Arg);
 122
 123 /**
 124  * Returns the debug location that is attached to the value of this argument.
 125  *
 126  * If there is no debug location, the return value will be `NULL`.
 127  *
 128  * \since REMARKS_API_VERSION=0
 129  */
 130 extern LLVMRemarkDebugLocRef LLVMRemarkArgGetDebugLoc(LLVMRemarkArgRef Arg);
 131
 132 /**
 133  * A remark emitted by the compiler.
 134  *
 135  * \since REMARKS_API_VERSION=0
 136  */
 137 typedef struct LLVMRemarkOpaqueEntry *LLVMRemarkEntryRef;
 138
 139 /**
 140  * The type of the remark. For example, it can allow users to only keep the
 141  * missed optimizations from the compiler.
 142  *
 143  * \since REMARKS_API_VERSION=0
 144  */
 145 extern enum LLVMRemarkType LLVMRemarkEntryGetType(LLVMRemarkEntryRef Remark);
 146
 147 /**
 148  * Get the name of the pass that emitted this remark.
 149  *
 150  * \since REMARKS_API_VERSION=0
 151  */
 152 extern LLVMRemarkStringRef
 153 LLVMRemarkEntryGetPassName(LLVMRemarkEntryRef Remark);
 154
 155 /**
 156  * Get an identifier of the remark.
 157  *
 158  * \since REMARKS_API_VERSION=0
 159  */
 160 extern LLVMRemarkStringRef
 161 LLVMRemarkEntryGetRemarkName(LLVMRemarkEntryRef Remark);
 162
 163 /**
 164  * Get the name of the function being processsed when the remark was emitted.
 165  *
 166  * \since REMARKS_API_VERSION=0
 167  */
 168 extern LLVMRemarkStringRef
 169 LLVMRemarkEntryGetFunctionName(LLVMRemarkEntryRef Remark);
 170
 171 /**
 172  * Returns the debug location that is attached to this remark.
 173  *
 174  * If there is no debug location, the return value will be `NULL`.
 175  *
 176  * \since REMARKS_API_VERSION=0
 177  */
 178 extern LLVMRemarkDebugLocRef
 179 LLVMRemarkEntryGetDebugLoc(LLVMRemarkEntryRef Remark);
 180
 181 /**
 182  * Return the hotness of the remark.
 183  *
 184  * A hotness of `0` means this value is not set.
 185  *
 186  * \since REMARKS_API_VERSION=0
 187  */
 188 extern uint64_t LLVMRemarkEntryGetHotness(LLVMRemarkEntryRef Remark);
 189
 190 /**
 191  * The number of arguments the remark holds.
 192  *
 193  * \since REMARKS_API_VERSION=0
 194  */
 195 extern uint32_t LLVMRemarkEntryGetNumArgs(LLVMRemarkEntryRef Remark);
 196
 197 /**
 198  * Get a new iterator to iterate over a remark's argument.
 199  *
 200  * If there are no arguments in \p Remark, the return value will be `NULL`.
 201  *
 202  * \since REMARKS_API_VERSION=0
 203  */
 204 extern LLVMRemarkArgRef LLVMRemarkEntryGetFirstArg(LLVMRemarkEntryRef Remark);
 205
 206 /**
 207  * Get the next argument in \p Remark from the position of \p It.
 208  *
 209  * Returns `NULL` if there are no more arguments available.
 210  *
 211  * \since REMARKS_API_VERSION=0
 212  */
 213 extern LLVMRemarkArgRef LLVMRemarkEntryGetNextArg(LLVMRemarkArgRef It,
 214                                                   LLVMRemarkEntryRef Remark);
 215
 216 typedef struct LLVMRemarkOpaqueParser *LLVMRemarkParserRef;
 217
 218 /**
 219  * Creates a remark parser that can be used to parse the buffer located in \p
 220  * Buf of size \p Size bytes.
 221  *
 222  * \p Buf cannot be `NULL`.
 223  *
 224  * This function should be paired with LLVMRemarkParserDispose() to avoid
 225  * leaking resources.
 226  *
 227  * \since REMARKS_API_VERSION=0
 228  */
 229 extern LLVMRemarkParserRef LLVMRemarkParserCreateYAML(const void *Buf,
 230                                                       uint64_t Size);
 231
 232 /**
 233  * Returns the next remark in the file.
 234  *
 235  * The value pointed to by the return value is invalidated by the next call to
 236  * LLVMRemarkParserGetNext().
 237  *
 238  * If the parser reaches the end of the buffer, the return value will be `NULL`.
 239  *
 240  * In the case of an error, the return value will be `NULL`, and:
 241  *
 242  * 1) LLVMRemarkParserHasError() will return `1`.
 243  *
 244  * 2) LLVMRemarkParserGetErrorMessage() will return a descriptive error
 245  *    message.
 246  *
 247  * An error may occur if:
 248  *
 249  * 1) An argument is invalid.
 250  *
 251  * 2) There is a parsing error. This can occur on things like malformed YAML.
 252  *
 253  * 3) There is a Remark semantic error. This can occur on well-formed files with
 254  *    missing or extra fields.
 255  *
 256  * Here is a quick example of the usage:
 257  *
 258  * ```
 259  * LLVMRemarkParserRef Parser = LLVMRemarkParserCreateYAML(Buf, Size);
 260  * LLVMRemarkEntryRef Remark = NULL;
 261  * while ((Remark == LLVMRemarkParserGetNext(Parser))) {
 262  *    // use Remark
 263  * }
 264  * bool HasError = LLVMRemarkParserHasError(Parser);
 265  * LLVMRemarkParserDispose(Parser);
 266  * ```
 267  *
 268  * \since REMARKS_API_VERSION=0
 269  */
 270 extern LLVMRemarkEntryRef LLVMRemarkParserGetNext(LLVMRemarkParserRef Parser);
 271
 272 /**
 273  * Returns `1` if the parser encountered an error while parsing the buffer.
 274  *
 275  * \since REMARKS_API_VERSION=0
 276  */
 277 extern LLVMBool LLVMRemarkParserHasError(LLVMRemarkParserRef Parser);
 278
 279 /**
 280  * Returns a null-terminated string containing an error message.
 281  *
 282  * In case of no error, the result is `NULL`.
 283  *
 284  * The memory of the string is bound to the lifetime of \p Parser. If
 285  * LLVMRemarkParserDispose() is called, the memory of the string will be
 286  * released.
 287  *
 288  * \since REMARKS_API_VERSION=0
 289  */
 290 extern const char *LLVMRemarkParserGetErrorMessage(LLVMRemarkParserRef Parser);
 291
 292 /**
 293  * Releases all the resources used by \p Parser.
 294  *
 295  * \since REMARKS_API_VERSION=0
 296  */
 297 extern void LLVMRemarkParserDispose(LLVMRemarkParserRef Parser);
 298
 299 /**
 300  * Returns the version of the remarks library.
 301  *
 302  * \since REMARKS_API_VERSION=0
 303  */
 304 extern uint32_t LLVMRemarkVersion(void);
 305
 306 /**
 307  * @} // endgoup LLVMCREMARKS
 308  */
 309
 310 #ifdef __cplusplus
 311 }
 312 #endif /* !defined(__cplusplus) */
 313
 314 #endif /* LLVM_C_REMARKS_H */