1 /*===-- llvm-c/Remarks.h - Remarks Public C Interface -------------*- C -*-===*\
3 |* Part of the LLVM Project, under the Apache License v2.0 with LLVM *|
5 |* See https://llvm.org/LICENSE.txt for license information. *|
6 |* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception *|
8 |*===----------------------------------------------------------------------===*|
10 |* This header provides a public interface to a remark diagnostics library. *|
11 |* LLVM provides an implementation of this interface. *|
13 \*===----------------------------------------------------------------------===*/
15 #ifndef LLVM_C_REMARKS_H
16 #define LLVM_C_REMARKS_H
18 #include "llvm-c/Types.h"
24 #endif /* !defined(__cplusplus) */
27 * @defgroup LLVMCREMARKS Remarks
33 #define REMARKS_API_VERSION 0
36 * The type of the emitted remark.
39 LLVMRemarkTypeUnknown,
42 LLVMRemarkTypeAnalysis,
43 LLVMRemarkTypeAnalysisFPCommute,
44 LLVMRemarkTypeAnalysisAliasing,
49 * String containing a buffer and a length. The buffer is not guaranteed to be
52 * \since REMARKS_API_VERSION=0
54 typedef struct LLVMRemarkOpaqueString *LLVMRemarkStringRef;
57 * Returns the buffer holding the string.
59 * \since REMARKS_API_VERSION=0
61 extern const char *LLVMRemarkStringGetData(LLVMRemarkStringRef String);
64 * Returns the size of the string.
66 * \since REMARKS_API_VERSION=0
68 extern uint32_t LLVMRemarkStringGetLen(LLVMRemarkStringRef String);
71 * DebugLoc containing File, Line and Column.
73 * \since REMARKS_API_VERSION=0
75 typedef struct LLVMRemarkOpaqueDebugLoc *LLVMRemarkDebugLocRef;
78 * Return the path to the source file for a debug location.
80 * \since REMARKS_API_VERSION=0
82 extern LLVMRemarkStringRef
83 LLVMRemarkDebugLocGetSourceFilePath(LLVMRemarkDebugLocRef DL);
86 * Return the line in the source file for a debug location.
88 * \since REMARKS_API_VERSION=0
90 extern uint32_t LLVMRemarkDebugLocGetSourceLine(LLVMRemarkDebugLocRef DL);
93 * Return the column in the source file for a debug location.
95 * \since REMARKS_API_VERSION=0
97 extern uint32_t LLVMRemarkDebugLocGetSourceColumn(LLVMRemarkDebugLocRef DL);
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.
104 * \since REMARKS_API_VERSION=0
106 typedef struct LLVMRemarkOpaqueArg *LLVMRemarkArgRef;
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.
112 * \since REMARKS_API_VERSION=0
114 extern LLVMRemarkStringRef LLVMRemarkArgGetKey(LLVMRemarkArgRef Arg);
117 * Returns the value of an argument. This is a string that can contain newlines.
119 * \since REMARKS_API_VERSION=0
121 extern LLVMRemarkStringRef LLVMRemarkArgGetValue(LLVMRemarkArgRef Arg);
124 * Returns the debug location that is attached to the value of this argument.
126 * If there is no debug location, the return value will be `NULL`.
128 * \since REMARKS_API_VERSION=0
130 extern LLVMRemarkDebugLocRef LLVMRemarkArgGetDebugLoc(LLVMRemarkArgRef Arg);
133 * A remark emitted by the compiler.
135 * \since REMARKS_API_VERSION=0
137 typedef struct LLVMRemarkOpaqueEntry *LLVMRemarkEntryRef;
140 * Free the resources used by the remark entry.
142 * \since REMARKS_API_VERSION=0
144 extern void LLVMRemarkEntryDispose(LLVMRemarkEntryRef Remark);
147 * The type of the remark. For example, it can allow users to only keep the
148 * missed optimizations from the compiler.
150 * \since REMARKS_API_VERSION=0
152 extern enum LLVMRemarkType LLVMRemarkEntryGetType(LLVMRemarkEntryRef Remark);
155 * Get the name of the pass that emitted this remark.
157 * \since REMARKS_API_VERSION=0
159 extern LLVMRemarkStringRef
160 LLVMRemarkEntryGetPassName(LLVMRemarkEntryRef Remark);
163 * Get an identifier of the remark.
165 * \since REMARKS_API_VERSION=0
167 extern LLVMRemarkStringRef
168 LLVMRemarkEntryGetRemarkName(LLVMRemarkEntryRef Remark);
171 * Get the name of the function being processed when the remark was emitted.
173 * \since REMARKS_API_VERSION=0
175 extern LLVMRemarkStringRef
176 LLVMRemarkEntryGetFunctionName(LLVMRemarkEntryRef Remark);
179 * Returns the debug location that is attached to this remark.
181 * If there is no debug location, the return value will be `NULL`.
183 * \since REMARKS_API_VERSION=0
185 extern LLVMRemarkDebugLocRef
186 LLVMRemarkEntryGetDebugLoc(LLVMRemarkEntryRef Remark);
189 * Return the hotness of the remark.
191 * A hotness of `0` means this value is not set.
193 * \since REMARKS_API_VERSION=0
195 extern uint64_t LLVMRemarkEntryGetHotness(LLVMRemarkEntryRef Remark);
198 * The number of arguments the remark holds.
200 * \since REMARKS_API_VERSION=0
202 extern uint32_t LLVMRemarkEntryGetNumArgs(LLVMRemarkEntryRef Remark);
205 * Get a new iterator to iterate over a remark's argument.
207 * If there are no arguments in \p Remark, the return value will be `NULL`.
209 * The lifetime of the returned value is bound to the lifetime of \p Remark.
211 * \since REMARKS_API_VERSION=0
213 extern LLVMRemarkArgRef LLVMRemarkEntryGetFirstArg(LLVMRemarkEntryRef Remark);
216 * Get the next argument in \p Remark from the position of \p It.
218 * Returns `NULL` if there are no more arguments available.
220 * The lifetime of the returned value is bound to the lifetime of \p Remark.
222 * \since REMARKS_API_VERSION=0
224 extern LLVMRemarkArgRef LLVMRemarkEntryGetNextArg(LLVMRemarkArgRef It,
225 LLVMRemarkEntryRef Remark);
227 typedef struct LLVMRemarkOpaqueParser *LLVMRemarkParserRef;
230 * Creates a remark parser that can be used to parse the buffer located in \p
231 * Buf of size \p Size bytes.
233 * \p Buf cannot be `NULL`.
235 * This function should be paired with LLVMRemarkParserDispose() to avoid
238 * \since REMARKS_API_VERSION=0
240 extern LLVMRemarkParserRef LLVMRemarkParserCreateYAML(const void *Buf,
244 * Returns the next remark in the file.
246 * The value pointed to by the return value needs to be disposed using a call to
247 * LLVMRemarkEntryDispose().
249 * All the entries in the returned value that are of LLVMRemarkStringRef type
250 * will become invalidated once a call to LLVMRemarkParserDispose is made.
252 * If the parser reaches the end of the buffer, the return value will be `NULL`.
254 * In the case of an error, the return value will be `NULL`, and:
256 * 1) LLVMRemarkParserHasError() will return `1`.
258 * 2) LLVMRemarkParserGetErrorMessage() will return a descriptive error
261 * An error may occur if:
263 * 1) An argument is invalid.
265 * 2) There is a parsing error. This can occur on things like malformed YAML.
267 * 3) There is a Remark semantic error. This can occur on well-formed files with
268 * missing or extra fields.
270 * Here is a quick example of the usage:
273 * LLVMRemarkParserRef Parser = LLVMRemarkParserCreateYAML(Buf, Size);
274 * LLVMRemarkEntryRef Remark = NULL;
275 * while ((Remark = LLVMRemarkParserGetNext(Parser))) {
277 * LLVMRemarkEntryDispose(Remark); // Release memory.
279 * bool HasError = LLVMRemarkParserHasError(Parser);
280 * LLVMRemarkParserDispose(Parser);
283 * \since REMARKS_API_VERSION=0
285 extern LLVMRemarkEntryRef LLVMRemarkParserGetNext(LLVMRemarkParserRef Parser);
288 * Returns `1` if the parser encountered an error while parsing the buffer.
290 * \since REMARKS_API_VERSION=0
292 extern LLVMBool LLVMRemarkParserHasError(LLVMRemarkParserRef Parser);
295 * Returns a null-terminated string containing an error message.
297 * In case of no error, the result is `NULL`.
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
303 * \since REMARKS_API_VERSION=0
305 extern const char *LLVMRemarkParserGetErrorMessage(LLVMRemarkParserRef Parser);
308 * Releases all the resources used by \p Parser.
310 * \since REMARKS_API_VERSION=0
312 extern void LLVMRemarkParserDispose(LLVMRemarkParserRef Parser);
315 * Returns the version of the remarks library.
317 * \since REMARKS_API_VERSION=0
319 extern uint32_t LLVMRemarkVersion(void);
322 * @} // endgoup LLVMCREMARKS
327 #endif /* !defined(__cplusplus) */
329 #endif /* LLVM_C_REMARKS_H */