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 */ 330