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  * Free the resources used by the remark entry.
 141  *
 142  * \since REMARKS_API_VERSION=0
 143  */
 144 extern void LLVMRemarkEntryDispose(LLVMRemarkEntryRef Remark);
 145
 146 /**
 147  * The type of the remark. For example, it can allow users to only keep the
 148  * missed optimizations from the compiler.
 149  *
 150  * \since REMARKS_API_VERSION=0
 151  */
 152 extern enum LLVMRemarkType LLVMRemarkEntryGetType(LLVMRemarkEntryRef Remark);
 153
 154 /**
 155  * Get the name of the pass that emitted this remark.
 156  *
 157  * \since REMARKS_API_VERSION=0
 158  */
 159 extern LLVMRemarkStringRef
 160 LLVMRemarkEntryGetPassName(LLVMRemarkEntryRef Remark);
 161
 162 /**
 163  * Get an identifier of the remark.
 164  *
 165  * \since REMARKS_API_VERSION=0
 166  */
 167 extern LLVMRemarkStringRef
 168 LLVMRemarkEntryGetRemarkName(LLVMRemarkEntryRef Remark);
 169
 170 /**
 171  * Get the name of the function being processed when the remark was emitted.
 172  *
 173  * \since REMARKS_API_VERSION=0
 174  */
 175 extern LLVMRemarkStringRef
 176 LLVMRemarkEntryGetFunctionName(LLVMRemarkEntryRef Remark);
 177
 178 /**
 179  * Returns the debug location that is attached to this remark.
 180  *
 181  * If there is no debug location, the return value will be `NULL`.
 182  *
 183  * \since REMARKS_API_VERSION=0
 184  */
 185 extern LLVMRemarkDebugLocRef
 186 LLVMRemarkEntryGetDebugLoc(LLVMRemarkEntryRef Remark);
 187
 188 /**
 189  * Return the hotness of the remark.
 190  *
 191  * A hotness of `0` means this value is not set.
 192  *
 193  * \since REMARKS_API_VERSION=0
 194  */
 195 extern uint64_t LLVMRemarkEntryGetHotness(LLVMRemarkEntryRef Remark);
 196
 197 /**
 198  * The number of arguments the remark holds.
 199  *
 200  * \since REMARKS_API_VERSION=0
 201  */
 202 extern uint32_t LLVMRemarkEntryGetNumArgs(LLVMRemarkEntryRef Remark);
 203
 204 /**
 205  * Get a new iterator to iterate over a remark's argument.
 206  *
 207  * If there are no arguments in \p Remark, the return value will be `NULL`.
 208  *
 209  * The lifetime of the returned value is bound to the lifetime of \p Remark.
 210  *
 211  * \since REMARKS_API_VERSION=0
 212  */
 213 extern LLVMRemarkArgRef LLVMRemarkEntryGetFirstArg(LLVMRemarkEntryRef Remark);
 214
 215 /**
 216  * Get the next argument in \p Remark from the position of \p It.
 217  *
 218  * Returns `NULL` if there are no more arguments available.
 219  *
 220  * The lifetime of the returned value is bound to the lifetime of \p Remark.
 221  *
 222  * \since REMARKS_API_VERSION=0
 223  */
 224 extern LLVMRemarkArgRef LLVMRemarkEntryGetNextArg(LLVMRemarkArgRef It,
 225                                                   LLVMRemarkEntryRef Remark);
 226
 227 typedef struct LLVMRemarkOpaqueParser *LLVMRemarkParserRef;
 228
 229 /**
 230  * Creates a remark parser that can be used to parse the buffer located in \p
 231  * Buf of size \p Size bytes.
 232  *
 233  * \p Buf cannot be `NULL`.
 234  *
 235  * This function should be paired with LLVMRemarkParserDispose() to avoid
 236  * leaking resources.
 237  *
 238  * \since REMARKS_API_VERSION=0
 239  */
 240 extern LLVMRemarkParserRef LLVMRemarkParserCreateYAML(const void *Buf,
 241                                                       uint64_t Size);
 242
 243 /**
 244  * Returns the next remark in the file.
 245  *
 246  * The value pointed to by the return value needs to be disposed using a call to
 247  * LLVMRemarkEntryDispose().
 248  *
 249  * All the entries in the returned value that are of LLVMRemarkStringRef type
 250  * will become invalidated once a call to LLVMRemarkParserDispose is made.
 251  *
 252  * If the parser reaches the end of the buffer, the return value will be `NULL`.
 253  *
 254  * In the case of an error, the return value will be `NULL`, and:
 255  *
 256  * 1) LLVMRemarkParserHasError() will return `1`.
 257  *
 258  * 2) LLVMRemarkParserGetErrorMessage() will return a descriptive error
 259  *    message.
 260  *
 261  * An error may occur if:
 262  *
 263  * 1) An argument is invalid.
 264  *
 265  * 2) There is a parsing error. This can occur on things like malformed YAML.
 266  *
 267  * 3) There is a Remark semantic error. This can occur on well-formed files with
 268  *    missing or extra fields.
 269  *
 270  * Here is a quick example of the usage:
 271  *
 272  * ```
 273  * LLVMRemarkParserRef Parser = LLVMRemarkParserCreateYAML(Buf, Size);
 274  * LLVMRemarkEntryRef Remark = NULL;
 275  * while ((Remark = LLVMRemarkParserGetNext(Parser))) {
 276  *    // use Remark
 277  *    LLVMRemarkEntryDispose(Remark); // Release memory.
 278  * }
 279  * bool HasError = LLVMRemarkParserHasError(Parser);
 280  * LLVMRemarkParserDispose(Parser);
 281  * ```
 282  *
 283  * \since REMARKS_API_VERSION=0
 284  */
 285 extern LLVMRemarkEntryRef LLVMRemarkParserGetNext(LLVMRemarkParserRef Parser);
 286
 287 /**
 288  * Returns `1` if the parser encountered an error while parsing the buffer.
 289  *
 290  * \since REMARKS_API_VERSION=0
 291  */
 292 extern LLVMBool LLVMRemarkParserHasError(LLVMRemarkParserRef Parser);
 293
 294 /**
 295  * Returns a null-terminated string containing an error message.
 296  *
 297  * In case of no error, the result is `NULL`.
 298  *
 299  * The memory of the string is bound to the lifetime of \p Parser. If
 300  * LLVMRemarkParserDispose() is called, the memory of the string will be
 301  * released.
 302  *
 303  * \since REMARKS_API_VERSION=0
 304  */
 305 extern const char *LLVMRemarkParserGetErrorMessage(LLVMRemarkParserRef Parser);
 306
 307 /**
 308  * Releases all the resources used by \p Parser.
 309  *
 310  * \since REMARKS_API_VERSION=0
 311  */
 312 extern void LLVMRemarkParserDispose(LLVMRemarkParserRef Parser);
 313
 314 /**
 315  * Returns the version of the remarks library.
 316  *
 317  * \since REMARKS_API_VERSION=0
 318  */
 319 extern uint32_t LLVMRemarkVersion(void);
 320
 321 /**
 322  * @} // endgoup LLVMCREMARKS
 323  */
 324
 325 #ifdef __cplusplus
 326 }
 327 #endif /* !defined(__cplusplus) */
 328
 329 #endif /* LLVM_C_REMARKS_H */