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