1 /*===-- llvm-c/OptRemarks.h - OptRemarks Public C Interface -------*- C -*-===*\
3 |* The LLVM Compiler Infrastructure *|
5 |* This file is distributed under the University of Illinois Open Source *|
6 |* License. See LICENSE.TXT for details. *|
8 |*===----------------------------------------------------------------------===*|
10 |* This header provides a public interface to an opt-remark library. *|
11 |* LLVM provides an implementation of this interface. *|
13 \*===----------------------------------------------------------------------===*/
15 #ifndef LLVM_C_OPT_REMARKS_H
16 #define LLVM_C_OPT_REMARKS_H
18 #include "llvm-c/Core.h"
19 #include "llvm-c/Types.h"
25 #endif /* !defined(__cplusplus) */
28 * @defgroup LLVMCOPTREMARKS OptRemarks
34 #define OPT_REMARKS_API_VERSION 0
37 * String containing a buffer and a length. The buffer is not guaranteed to be
40 * \since OPT_REMARKS_API_VERSION=0
45 } LLVMOptRemarkStringRef;
48 * DebugLoc containing File, Line and Column.
50 * \since OPT_REMARKS_API_VERSION=0
54 LLVMOptRemarkStringRef SourceFile;
56 uint32_t SourceLineNumber;
58 uint32_t SourceColumnNumber;
59 } LLVMOptRemarkDebugLoc;
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.
66 * \since OPT_REMARKS_API_VERSION=0
70 LLVMOptRemarkStringRef Key;
72 LLVMOptRemarkStringRef Value;
74 // "DebugLoc": Optional
75 LLVMOptRemarkDebugLoc DebugLoc;
81 * \since OPT_REMARKS_API_VERSION=0
84 // e.g. !Missed, !Passed
85 LLVMOptRemarkStringRef RemarkType;
87 LLVMOptRemarkStringRef PassName;
89 LLVMOptRemarkStringRef RemarkName;
90 // "Function": Required
91 LLVMOptRemarkStringRef FunctionName;
93 // "DebugLoc": Optional
94 LLVMOptRemarkDebugLoc DebugLoc;
95 // "Hotness": Optional
97 // "Args": Optional. It is an array of `num_args` elements.
99 LLVMOptRemarkArg *Args;
100 } LLVMOptRemarkEntry;
102 typedef struct LLVMOptRemarkOpaqueParser *LLVMOptRemarkParserRef;
105 * Creates a remark parser that can be used to read and parse the buffer located
106 * in \p Buf of size \p Size.
108 * \p Buf cannot be NULL.
110 * This function should be paired with LLVMOptRemarkParserDispose() to avoid
113 * \since OPT_REMARKS_API_VERSION=0
115 extern LLVMOptRemarkParserRef LLVMOptRemarkParserCreate(const void *Buf,
119 * Returns the next remark in the file.
121 * The value pointed to by the return value is invalidated by the next call to
122 * LLVMOptRemarkParserGetNext().
124 * If the parser reaches the end of the buffer, the return value will be NULL.
126 * In the case of an error, the return value will be NULL, and:
128 * 1) LLVMOptRemarkParserHasError() will return `1`.
130 * 2) LLVMOptRemarkParserGetErrorMessage() will return a descriptive error
133 * An error may occur if:
135 * 1) An argument is invalid.
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.
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.
144 * Here is a quick example of the usage:
147 * LLVMOptRemarkParserRef Parser = LLVMOptRemarkParserCreate(Buf, Size);
148 * LLVMOptRemarkEntry *Remark = NULL;
149 * while ((Remark == LLVMOptRemarkParserGetNext(Parser))) {
152 * bool HasError = LLVMOptRemarkParserHasError(Parser);
153 * LLVMOptRemarkParserDispose(Parser);
156 * \since OPT_REMARKS_API_VERSION=0
158 extern LLVMOptRemarkEntry *
159 LLVMOptRemarkParserGetNext(LLVMOptRemarkParserRef Parser);
162 * Returns `1` if the parser encountered an error while parsing the buffer.
164 * \since OPT_REMARKS_API_VERSION=0
166 extern LLVMBool LLVMOptRemarkParserHasError(LLVMOptRemarkParserRef Parser);
169 * Returns a null-terminated string containing an error message.
171 * In case of no error, the result is `NULL`.
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
177 * \since OPT_REMARKS_API_VERSION=0
180 LLVMOptRemarkParserGetErrorMessage(LLVMOptRemarkParserRef Parser);
183 * Releases all the resources used by \p Parser.
185 * \since OPT_REMARKS_API_VERSION=0
187 extern void LLVMOptRemarkParserDispose(LLVMOptRemarkParserRef Parser);
190 * Returns the version of the opt-remarks dylib.
192 * \since OPT_REMARKS_API_VERSION=0
194 extern uint32_t LLVMOptRemarkVersion(void);
197 * @} // endgoup LLVMCOPTREMARKS
202 #endif /* !defined(__cplusplus) */
204 #endif /* LLVM_C_OPT_REMARKS_H */