1 /*===-- llvm-c/OptRemarks.h - OptRemarks Public C Interface -------*- C -*-===*\ 2 |* *| 3 |* The LLVM Compiler Infrastructure *| 4 |* *| 5 |* This file is distributed under the University of Illinois Open Source *| 6 |* License. See LICENSE.TXT for details. *| 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 */ 205