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
27LLVM_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 */
42enum 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 */
58typedef struct LLVMRemarkOpaqueString *LLVMRemarkStringRef;
59
60/**
61 * Returns the buffer holding the string.
62 *
63 * \since REMARKS_API_VERSION=0
64 */
65LLVM_C_ABI extern const char *
66LLVMRemarkStringGetData(LLVMRemarkStringRef String);
67
68/**
69 * Returns the size of the string.
70 *
71 * \since REMARKS_API_VERSION=0
72 */
73LLVM_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 */
80typedef 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 */
87LLVM_C_ABI extern LLVMRemarkStringRef
88LLVMRemarkDebugLocGetSourceFilePath(LLVMRemarkDebugLocRef DL);
89
90/**
91 * Return the line in the source file for a debug location.
92 *
93 * \since REMARKS_API_VERSION=0
94 */
95LLVM_C_ABI extern uint32_t
96LLVMRemarkDebugLocGetSourceLine(LLVMRemarkDebugLocRef DL);
97
98/**
99 * Return the column in the source file for a debug location.
100 *
101 * \since REMARKS_API_VERSION=0
102 */
103LLVM_C_ABI extern uint32_t
104LLVMRemarkDebugLocGetSourceColumn(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 */
113typedef 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 */
121LLVM_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 */
128LLVM_C_ABI extern LLVMRemarkStringRef
129LLVMRemarkArgGetValue(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 */
138LLVM_C_ABI extern LLVMRemarkDebugLocRef
139LLVMRemarkArgGetDebugLoc(LLVMRemarkArgRef Arg);
140
141/**
142 * A remark emitted by the compiler.
143 *
144 * \since REMARKS_API_VERSION=0
145 */
146typedef struct LLVMRemarkOpaqueEntry *LLVMRemarkEntryRef;
147
148/**
149 * Free the resources used by the remark entry.
150 *
151 * \since REMARKS_API_VERSION=0
152 */
153LLVM_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 */
161LLVM_C_ABI extern enum LLVMRemarkType
162LLVMRemarkEntryGetType(LLVMRemarkEntryRef Remark);
163
164/**
165 * Get the name of the pass that emitted this remark.
166 *
167 * \since REMARKS_API_VERSION=0
168 */
169LLVM_C_ABI extern LLVMRemarkStringRef
170LLVMRemarkEntryGetPassName(LLVMRemarkEntryRef Remark);
171
172/**
173 * Get an identifier of the remark.
174 *
175 * \since REMARKS_API_VERSION=0
176 */
177LLVM_C_ABI extern LLVMRemarkStringRef
178LLVMRemarkEntryGetRemarkName(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 */
185LLVM_C_ABI extern LLVMRemarkStringRef
186LLVMRemarkEntryGetFunctionName(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 */
195LLVM_C_ABI extern LLVMRemarkDebugLocRef
196LLVMRemarkEntryGetDebugLoc(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 */
205LLVM_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 */
212LLVM_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 */
223LLVM_C_ABI extern LLVMRemarkArgRef
224LLVMRemarkEntryGetFirstArg(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 */
235LLVM_C_ABI extern LLVMRemarkArgRef
236LLVMRemarkEntryGetNextArg(LLVMRemarkArgRef It, LLVMRemarkEntryRef Remark);
237
238typedef 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 */
251LLVM_C_ABI extern LLVMRemarkParserRef
252LLVMRemarkParserCreateYAML(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 */
265LLVM_C_ABI extern LLVMRemarkParserRef
266LLVMRemarkParserCreateBitstream(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 */
310LLVM_C_ABI extern LLVMRemarkEntryRef
311LLVMRemarkParserGetNext(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 */
318LLVM_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 */
331LLVM_C_ABI extern const char *
332LLVMRemarkParserGetErrorMessage(LLVMRemarkParserRef Parser);
333
334/**
335 * Releases all the resources used by \p Parser.
336 *
337 * \since REMARKS_API_VERSION=0
338 */
339LLVM_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 */
346extern uint32_t LLVMRemarkVersion(void);
347
348/**
349 * @} // endgoup LLVMCREMARKS
350 */
351
352LLVM_C_EXTERN_C_END
353
354#endif /* LLVM_C_REMARKS_H */
355