LLVM
20.0.0git
include
llvm-c
Remarks.h
Go to the documentation of this file.
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
#ifdef __cplusplus
21
#include <cstddef>
22
#else
23
#include <stddef.h>
24
#endif
/* !defined(__cplusplus) */
25
26
LLVM_C_EXTERN_C_BEGIN
27
28
/**
29
* @defgroup LLVMCREMARKS Remarks
30
* @ingroup LLVMC
31
*
32
* @{
33
*/
34
35
// 0 -> 1: Bitstream remarks support.
36
#define REMARKS_API_VERSION 1
37
38
/**
39
* The type of the emitted remark.
40
*/
41
enum
LLVMRemarkType
{
42
LLVMRemarkTypeUnknown
,
43
LLVMRemarkTypePassed
,
44
LLVMRemarkTypeMissed
,
45
LLVMRemarkTypeAnalysis
,
46
LLVMRemarkTypeAnalysisFPCommute
,
47
LLVMRemarkTypeAnalysisAliasing
,
48
LLVMRemarkTypeFailure
49
};
50
51
/**
52
* String containing a buffer and a length. The buffer is not guaranteed to be
53
* zero-terminated.
54
*
55
* \since REMARKS_API_VERSION=0
56
*/
57
typedef
struct
LLVMRemarkOpaqueString *
LLVMRemarkStringRef
;
58
59
/**
60
* Returns the buffer holding the string.
61
*
62
* \since REMARKS_API_VERSION=0
63
*/
64
extern
const
char
*
LLVMRemarkStringGetData
(
LLVMRemarkStringRef
String);
65
66
/**
67
* Returns the size of the string.
68
*
69
* \since REMARKS_API_VERSION=0
70
*/
71
extern
uint32_t
LLVMRemarkStringGetLen
(
LLVMRemarkStringRef
String);
72
73
/**
74
* DebugLoc containing File, Line and Column.
75
*
76
* \since REMARKS_API_VERSION=0
77
*/
78
typedef
struct
LLVMRemarkOpaqueDebugLoc *
LLVMRemarkDebugLocRef
;
79
80
/**
81
* Return the path to the source file for a debug location.
82
*
83
* \since REMARKS_API_VERSION=0
84
*/
85
extern
LLVMRemarkStringRef
86
LLVMRemarkDebugLocGetSourceFilePath
(
LLVMRemarkDebugLocRef
DL
);
87
88
/**
89
* Return the line in the source file for a debug location.
90
*
91
* \since REMARKS_API_VERSION=0
92
*/
93
extern
uint32_t
LLVMRemarkDebugLocGetSourceLine
(
LLVMRemarkDebugLocRef
DL
);
94
95
/**
96
* Return the column in the source file for a debug location.
97
*
98
* \since REMARKS_API_VERSION=0
99
*/
100
extern
uint32_t
LLVMRemarkDebugLocGetSourceColumn
(
LLVMRemarkDebugLocRef
DL
);
101
102
/**
103
* Element of the "Args" list. The key might give more information about what
104
* the semantics of the value are, e.g. "Callee" will tell you that the value
105
* is a symbol that names a function.
106
*
107
* \since REMARKS_API_VERSION=0
108
*/
109
typedef
struct
LLVMRemarkOpaqueArg *
LLVMRemarkArgRef
;
110
111
/**
112
* Returns the key of an argument. The key defines what the value is, and the
113
* same key can appear multiple times in the list of arguments.
114
*
115
* \since REMARKS_API_VERSION=0
116
*/
117
extern
LLVMRemarkStringRef
LLVMRemarkArgGetKey
(
LLVMRemarkArgRef
Arg);
118
119
/**
120
* Returns the value of an argument. This is a string that can contain newlines.
121
*
122
* \since REMARKS_API_VERSION=0
123
*/
124
extern
LLVMRemarkStringRef
LLVMRemarkArgGetValue
(
LLVMRemarkArgRef
Arg);
125
126
/**
127
* Returns the debug location that is attached to the value of this argument.
128
*
129
* If there is no debug location, the return value will be `NULL`.
130
*
131
* \since REMARKS_API_VERSION=0
132
*/
133
extern
LLVMRemarkDebugLocRef
LLVMRemarkArgGetDebugLoc
(
LLVMRemarkArgRef
Arg);
134
135
/**
136
* A remark emitted by the compiler.
137
*
138
* \since REMARKS_API_VERSION=0
139
*/
140
typedef
struct
LLVMRemarkOpaqueEntry *
LLVMRemarkEntryRef
;
141
142
/**
143
* Free the resources used by the remark entry.
144
*
145
* \since REMARKS_API_VERSION=0
146
*/
147
extern
void
LLVMRemarkEntryDispose
(
LLVMRemarkEntryRef
Remark);
148
149
/**
150
* The type of the remark. For example, it can allow users to only keep the
151
* missed optimizations from the compiler.
152
*
153
* \since REMARKS_API_VERSION=0
154
*/
155
extern
enum
LLVMRemarkType
LLVMRemarkEntryGetType
(
LLVMRemarkEntryRef
Remark);
156
157
/**
158
* Get the name of the pass that emitted this remark.
159
*
160
* \since REMARKS_API_VERSION=0
161
*/
162
extern
LLVMRemarkStringRef
163
LLVMRemarkEntryGetPassName
(
LLVMRemarkEntryRef
Remark);
164
165
/**
166
* Get an identifier of the remark.
167
*
168
* \since REMARKS_API_VERSION=0
169
*/
170
extern
LLVMRemarkStringRef
171
LLVMRemarkEntryGetRemarkName
(
LLVMRemarkEntryRef
Remark);
172
173
/**
174
* Get the name of the function being processed when the remark was emitted.
175
*
176
* \since REMARKS_API_VERSION=0
177
*/
178
extern
LLVMRemarkStringRef
179
LLVMRemarkEntryGetFunctionName
(
LLVMRemarkEntryRef
Remark);
180
181
/**
182
* Returns the debug location that is attached to this remark.
183
*
184
* If there is no debug location, the return value will be `NULL`.
185
*
186
* \since REMARKS_API_VERSION=0
187
*/
188
extern
LLVMRemarkDebugLocRef
189
LLVMRemarkEntryGetDebugLoc
(
LLVMRemarkEntryRef
Remark);
190
191
/**
192
* Return the hotness of the remark.
193
*
194
* A hotness of `0` means this value is not set.
195
*
196
* \since REMARKS_API_VERSION=0
197
*/
198
extern
uint64_t
LLVMRemarkEntryGetHotness
(
LLVMRemarkEntryRef
Remark);
199
200
/**
201
* The number of arguments the remark holds.
202
*
203
* \since REMARKS_API_VERSION=0
204
*/
205
extern
uint32_t
LLVMRemarkEntryGetNumArgs
(
LLVMRemarkEntryRef
Remark);
206
207
/**
208
* Get a new iterator to iterate over a remark's argument.
209
*
210
* If there are no arguments in \p Remark, the return value will be `NULL`.
211
*
212
* The lifetime of the returned value is bound to the lifetime of \p Remark.
213
*
214
* \since REMARKS_API_VERSION=0
215
*/
216
extern
LLVMRemarkArgRef
LLVMRemarkEntryGetFirstArg
(
LLVMRemarkEntryRef
Remark);
217
218
/**
219
* Get the next argument in \p Remark from the position of \p It.
220
*
221
* Returns `NULL` if there are no more arguments available.
222
*
223
* The lifetime of the returned value is bound to the lifetime of \p Remark.
224
*
225
* \since REMARKS_API_VERSION=0
226
*/
227
extern
LLVMRemarkArgRef
LLVMRemarkEntryGetNextArg
(
LLVMRemarkArgRef
It,
228
LLVMRemarkEntryRef
Remark);
229
230
typedef
struct
LLVMRemarkOpaqueParser *
LLVMRemarkParserRef
;
231
232
/**
233
* Creates a remark parser that can be used to parse the buffer located in \p
234
* Buf of size \p Size bytes.
235
*
236
* \p Buf cannot be `NULL`.
237
*
238
* This function should be paired with LLVMRemarkParserDispose() to avoid
239
* leaking resources.
240
*
241
* \since REMARKS_API_VERSION=0
242
*/
243
extern
LLVMRemarkParserRef
LLVMRemarkParserCreateYAML
(
const
void
*Buf,
244
uint64_t
Size
);
245
246
/**
247
* Creates a remark parser that can be used to parse the buffer located in \p
248
* Buf of size \p Size bytes.
249
*
250
* \p Buf cannot be `NULL`.
251
*
252
* This function should be paired with LLVMRemarkParserDispose() to avoid
253
* leaking resources.
254
*
255
* \since REMARKS_API_VERSION=1
256
*/
257
extern
LLVMRemarkParserRef
LLVMRemarkParserCreateBitstream
(
const
void
*Buf,
258
uint64_t
Size
);
259
260
/**
261
* Returns the next remark in the file.
262
*
263
* The value pointed to by the return value needs to be disposed using a call to
264
* LLVMRemarkEntryDispose().
265
*
266
* All the entries in the returned value that are of LLVMRemarkStringRef type
267
* will become invalidated once a call to LLVMRemarkParserDispose is made.
268
*
269
* If the parser reaches the end of the buffer, the return value will be `NULL`.
270
*
271
* In the case of an error, the return value will be `NULL`, and:
272
*
273
* 1) LLVMRemarkParserHasError() will return `1`.
274
*
275
* 2) LLVMRemarkParserGetErrorMessage() will return a descriptive error
276
* message.
277
*
278
* An error may occur if:
279
*
280
* 1) An argument is invalid.
281
*
282
* 2) There is a parsing error. This can occur on things like malformed YAML.
283
*
284
* 3) There is a Remark semantic error. This can occur on well-formed files with
285
* missing or extra fields.
286
*
287
* Here is a quick example of the usage:
288
*
289
* ```
290
* LLVMRemarkParserRef Parser = LLVMRemarkParserCreateYAML(Buf, Size);
291
* LLVMRemarkEntryRef Remark = NULL;
292
* while ((Remark = LLVMRemarkParserGetNext(Parser))) {
293
* // use Remark
294
* LLVMRemarkEntryDispose(Remark); // Release memory.
295
* }
296
* bool HasError = LLVMRemarkParserHasError(Parser);
297
* LLVMRemarkParserDispose(Parser);
298
* ```
299
*
300
* \since REMARKS_API_VERSION=0
301
*/
302
extern
LLVMRemarkEntryRef
LLVMRemarkParserGetNext
(
LLVMRemarkParserRef
Parser);
303
304
/**
305
* Returns `1` if the parser encountered an error while parsing the buffer.
306
*
307
* \since REMARKS_API_VERSION=0
308
*/
309
extern
LLVMBool
LLVMRemarkParserHasError
(
LLVMRemarkParserRef
Parser);
310
311
/**
312
* Returns a null-terminated string containing an error message.
313
*
314
* In case of no error, the result is `NULL`.
315
*
316
* The memory of the string is bound to the lifetime of \p Parser. If
317
* LLVMRemarkParserDispose() is called, the memory of the string will be
318
* released.
319
*
320
* \since REMARKS_API_VERSION=0
321
*/
322
extern
const
char
*
LLVMRemarkParserGetErrorMessage
(
LLVMRemarkParserRef
Parser);
323
324
/**
325
* Releases all the resources used by \p Parser.
326
*
327
* \since REMARKS_API_VERSION=0
328
*/
329
extern
void
LLVMRemarkParserDispose
(
LLVMRemarkParserRef
Parser);
330
331
/**
332
* Returns the version of the remarks library.
333
*
334
* \since REMARKS_API_VERSION=0
335
*/
336
extern
uint32_t
LLVMRemarkVersion
(
void
);
337
338
/**
339
* @} // endgoup LLVMCREMARKS
340
*/
341
342
LLVM_C_EXTERN_C_END
343
344
#endif
/* LLVM_C_REMARKS_H */
DL
MachineBasicBlock MachineBasicBlock::iterator DebugLoc DL
Definition:
ARMSLSHardening.cpp:73
Size
uint64_t Size
Definition:
ELFObjHandler.cpp:81
ExternC.h
LLVM_C_EXTERN_C_BEGIN
#define LLVM_C_EXTERN_C_BEGIN
Definition:
ExternC.h:35
LLVM_C_EXTERN_C_END
#define LLVM_C_EXTERN_C_END
Definition:
ExternC.h:36
Types.h
uint32_t
uint64_t
LLVMRemarkVersion
uint32_t LLVMRemarkVersion(void)
Returns the version of the remarks library.
LLVMRemarkEntryGetPassName
LLVMRemarkStringRef LLVMRemarkEntryGetPassName(LLVMRemarkEntryRef Remark)
Get the name of the pass that emitted this remark.
Definition:
Remark.cpp:116
LLVMRemarkArgGetKey
LLVMRemarkStringRef LLVMRemarkArgGetKey(LLVMRemarkArgRef Arg)
Returns the key of an argument.
Definition:
Remark.cpp:91
LLVMRemarkStringGetData
const char * LLVMRemarkStringGetData(LLVMRemarkStringRef String)
Returns the buffer holding the string.
Definition:
Remark.cpp:69
LLVMRemarkStringGetLen
uint32_t LLVMRemarkStringGetLen(LLVMRemarkStringRef String)
Returns the size of the string.
Definition:
Remark.cpp:73
LLVMRemarkEntryRef
struct LLVMRemarkOpaqueEntry * LLVMRemarkEntryRef
A remark emitted by the compiler.
Definition:
Remarks.h:140
LLVMRemarkType
LLVMRemarkType
The type of the emitted remark.
Definition:
Remarks.h:41
LLVMRemarkParserCreateBitstream
LLVMRemarkParserRef LLVMRemarkParserCreateBitstream(const void *Buf, uint64_t Size)
Creates a remark parser that can be used to parse the buffer located in Buf of size Size bytes.
Definition:
RemarkParser.cpp:136
LLVMRemarkStringRef
struct LLVMRemarkOpaqueString * LLVMRemarkStringRef
String containing a buffer and a length.
Definition:
Remarks.h:57
LLVMRemarkEntryDispose
void LLVMRemarkEntryDispose(LLVMRemarkEntryRef Remark)
Free the resources used by the remark entry.
Definition:
Remark.cpp:106
LLVMRemarkArgRef
struct LLVMRemarkOpaqueArg * LLVMRemarkArgRef
Element of the "Args" list.
Definition:
Remarks.h:109
LLVMRemarkDebugLocGetSourceLine
uint32_t LLVMRemarkDebugLocGetSourceLine(LLVMRemarkDebugLocRef DL)
Return the line in the source file for a debug location.
Definition:
Remark.cpp:82
LLVMRemarkParserCreateYAML
LLVMRemarkParserRef LLVMRemarkParserCreateYAML(const void *Buf, uint64_t Size)
Creates a remark parser that can be used to parse the buffer located in Buf of size Size bytes.
Definition:
RemarkParser.cpp:130
LLVMRemarkEntryGetType
enum LLVMRemarkType LLVMRemarkEntryGetType(LLVMRemarkEntryRef Remark)
The type of the remark.
Definition:
Remark.cpp:110
LLVMRemarkParserRef
struct LLVMRemarkOpaqueParser * LLVMRemarkParserRef
Definition:
Remarks.h:230
LLVMRemarkEntryGetFirstArg
LLVMRemarkArgRef LLVMRemarkEntryGetFirstArg(LLVMRemarkEntryRef Remark)
Get a new iterator to iterate over a remark's argument.
Definition:
Remark.cpp:148
LLVMRemarkEntryGetNextArg
LLVMRemarkArgRef LLVMRemarkEntryGetNextArg(LLVMRemarkArgRef It, LLVMRemarkEntryRef Remark)
Get the next argument in Remark from the position of It.
Definition:
Remark.cpp:158
LLVMRemarkParserHasError
LLVMBool LLVMRemarkParserHasError(LLVMRemarkParserRef Parser)
Returns 1 if the parser encountered an error while parsing the buffer.
Definition:
RemarkParser.cpp:164
LLVMRemarkDebugLocGetSourceFilePath
LLVMRemarkStringRef LLVMRemarkDebugLocGetSourceFilePath(LLVMRemarkDebugLocRef DL)
Return the path to the source file for a debug location.
Definition:
Remark.cpp:78
LLVMRemarkEntryGetDebugLoc
LLVMRemarkDebugLocRef LLVMRemarkEntryGetDebugLoc(LLVMRemarkEntryRef Remark)
Returns the debug location that is attached to this remark.
Definition:
Remark.cpp:131
LLVMRemarkEntryGetNumArgs
uint32_t LLVMRemarkEntryGetNumArgs(LLVMRemarkEntryRef Remark)
The number of arguments the remark holds.
Definition:
Remark.cpp:143
LLVMRemarkEntryGetRemarkName
LLVMRemarkStringRef LLVMRemarkEntryGetRemarkName(LLVMRemarkEntryRef Remark)
Get an identifier of the remark.
Definition:
Remark.cpp:121
LLVMRemarkArgGetValue
LLVMRemarkStringRef LLVMRemarkArgGetValue(LLVMRemarkArgRef Arg)
Returns the value of an argument.
Definition:
Remark.cpp:95
LLVMRemarkParserGetErrorMessage
const char * LLVMRemarkParserGetErrorMessage(LLVMRemarkParserRef Parser)
Returns a null-terminated string containing an error message.
Definition:
RemarkParser.cpp:169
LLVMRemarkDebugLocGetSourceColumn
uint32_t LLVMRemarkDebugLocGetSourceColumn(LLVMRemarkDebugLocRef DL)
Return the column in the source file for a debug location.
Definition:
Remark.cpp:87
LLVMRemarkDebugLocRef
struct LLVMRemarkOpaqueDebugLoc * LLVMRemarkDebugLocRef
DebugLoc containing File, Line and Column.
Definition:
Remarks.h:78
LLVMRemarkArgGetDebugLoc
LLVMRemarkDebugLocRef LLVMRemarkArgGetDebugLoc(LLVMRemarkArgRef Arg)
Returns the debug location that is attached to the value of this argument.
Definition:
Remark.cpp:100
LLVMRemarkParserDispose
void LLVMRemarkParserDispose(LLVMRemarkParserRef Parser)
Releases all the resources used by Parser.
Definition:
RemarkParser.cpp:173
LLVMRemarkParserGetNext
LLVMRemarkEntryRef LLVMRemarkParserGetNext(LLVMRemarkParserRef Parser)
Returns the next remark in the file.
Definition:
RemarkParser.cpp:143
LLVMRemarkEntryGetFunctionName
LLVMRemarkStringRef LLVMRemarkEntryGetFunctionName(LLVMRemarkEntryRef Remark)
Get the name of the function being processed when the remark was emitted.
Definition:
Remark.cpp:126
LLVMRemarkEntryGetHotness
uint64_t LLVMRemarkEntryGetHotness(LLVMRemarkEntryRef Remark)
Return the hotness of the remark.
Definition:
Remark.cpp:137
LLVMRemarkTypeAnalysisFPCommute
@ LLVMRemarkTypeAnalysisFPCommute
Definition:
Remarks.h:46
LLVMRemarkTypeAnalysisAliasing
@ LLVMRemarkTypeAnalysisAliasing
Definition:
Remarks.h:47
LLVMRemarkTypePassed
@ LLVMRemarkTypePassed
Definition:
Remarks.h:43
LLVMRemarkTypeUnknown
@ LLVMRemarkTypeUnknown
Definition:
Remarks.h:42
LLVMRemarkTypeFailure
@ LLVMRemarkTypeFailure
Definition:
Remarks.h:48
LLVMRemarkTypeAnalysis
@ LLVMRemarkTypeAnalysis
Definition:
Remarks.h:45
LLVMRemarkTypeMissed
@ LLVMRemarkTypeMissed
Definition:
Remarks.h:44
LLVMBool
int LLVMBool
Definition:
Types.h:28
Generated on Fri Oct 11 2024 00:56:01 for LLVM by
1.9.6