1//===-- mlir-c/Remarks.h - MLIR Remark Engine C API ---------------*- C -*-===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8//
9// This header declares the C interface to the MLIR optimization remark engine:
10// enabling the engine on a context with category filters, an emitting policy
11// and a sink (MLIR diagnostics, a YAML/bitstream file, or a callback),
12// emitting remarks, and inspecting a remark from inside a callback.
13//
14//===----------------------------------------------------------------------===//
15
16#ifndef MLIR_C_REMARKS_H
17#define MLIR_C_REMARKS_H
18
19#include "mlir-c/IR.h"
20#include "mlir-c/Support.h"
21
22#ifdef __cplusplus
23extern "C" {
24#endif
25
26//===----------------------------------------------------------------------===//
27// Opaque types and enums.
28//===----------------------------------------------------------------------===//
29
30/// An opaque reference to a remark. A remark is only valid for the duration of
31/// the callback it is passed to; it must not be stored.
32struct MlirRemark {
33 const void *ptr;
34};
35typedef struct MlirRemark MlirRemark;
36
37/// The outcome a remark describes (see mlir::remark::RemarkKind).
38enum MlirRemarkKind {
39 MlirRemarkKindUnknown,
40 /// An optimization was applied.
41 MlirRemarkKindPassed,
42 /// A profitable optimization opportunity was found but not applied.
43 MlirRemarkKindMissed,
44 /// The optimization was attempted but failed.
45 MlirRemarkKindFailure,
46 /// Informational context without a pass/fail outcome.
47 MlirRemarkKindAnalysis
48};
49typedef enum MlirRemarkKind MlirRemarkKind;
50
51/// The emitting policy of the remark engine.
52enum MlirRemarkPolicy {
53 /// Report every remark as it is emitted.
54 MlirRemarkPolicyAll,
55 /// Postpone remarks and report the final set when the engine is finalized,
56 /// grouping related remarks under their parents.
57 MlirRemarkPolicyFinal
58};
59typedef enum MlirRemarkPolicy MlirRemarkPolicy;
60
61/// The serialization format of a remark output file.
62enum MlirRemarkFileFormat {
63 MlirRemarkFileFormatYAML,
64 MlirRemarkFileFormatBitstream
65};
66typedef enum MlirRemarkFileFormat MlirRemarkFileFormat;
67
68/// Regular expressions (llvm::Regex syntax, anchored by the engine) selecting
69/// the remark categories to report: `all` applies to every kind, the others to
70/// one kind each. A string of length 0 means the filter is not set, so the
71/// corresponding kind is not reported unless `all` matches.
72struct MlirRemarkCategories {
73 MlirStringRef all;
74 MlirStringRef passed;
75 MlirStringRef missed;
76 MlirStringRef analysis;
77 MlirStringRef failed;
78};
79typedef struct MlirRemarkCategories MlirRemarkCategories;
80
81/// Callback receiving every remark the engine reports.
82typedef void (*MlirRemarkCallback)(MlirRemark remark, void *userData);
83
84//===----------------------------------------------------------------------===//
85// Enabling and finalizing the engine of a context.
86//===----------------------------------------------------------------------===//
87
88/// Enables the remark engine on the context without a streamer; when
89/// `printAsEmitRemarks` is set, every reported remark is emitted as an MLIR
90/// remark diagnostic at its location. Fails when the context already has a
91/// remark engine (finalize it first).
92MLIR_CAPI_EXPORTED MlirLogicalResult mlirContextEnableOptimizationRemarks(
93 MlirContext context, MlirRemarkCategories categories,
94 MlirRemarkPolicy policy, bool printAsEmitRemarks);
95
96/// Enables the remark engine on the context, streaming the reported remarks to
97/// the file at `path` in `format`. The file is written when the engine is
98/// finalized. Fails when the file cannot be created or the context already has
99/// a remark engine.
100MLIR_CAPI_EXPORTED MlirLogicalResult mlirContextEnableOptimizationRemarksToFile(
101 MlirContext context, MlirRemarkCategories categories,
102 MlirRemarkPolicy policy, MlirRemarkFileFormat format, MlirStringRef path,
103 bool printAsEmitRemarks);
104
105/// Enables the remark engine on the context, delivering every reported remark
106/// to `callback`. `userData` is passed to the callback unchanged and released
107/// through `deleteUserData` (may be null) when the engine is finalized or the
108/// context is destroyed. Fails when the context already has a remark engine.
109MLIR_CAPI_EXPORTED MlirLogicalResult
110mlirContextEnableOptimizationRemarksWithCallback(
111 MlirContext context, MlirRemarkCategories categories,
112 MlirRemarkPolicy policy, MlirRemarkCallback callback, void *userData,
113 void (*deleteUserData)(void *), bool printAsEmitRemarks);
114
115/// Finalizes and removes the remark engine of the context: postponed remarks
116/// are reported, the output file is written and the callback's user data is
117/// released. Does nothing when no engine is enabled.
118MLIR_CAPI_EXPORTED void
119mlirContextFinalizeOptimizationRemarks(MlirContext context);
120
121/// Returns whether the context has a remark engine enabled.
122MLIR_CAPI_EXPORTED bool mlirContextHasRemarkEngine(MlirContext context);
123
124//===----------------------------------------------------------------------===//
125// Remark accessors (valid only inside a remark callback).
126//===----------------------------------------------------------------------===//
127
128/// Returns the kind of the remark.
129MLIR_CAPI_EXPORTED MlirRemarkKind mlirRemarkGetKind(MlirRemark remark);
130
131/// Returns the name identifying the remark.
132MLIR_CAPI_EXPORTED MlirStringRef mlirRemarkGetRemarkName(MlirRemark remark);
133
134/// Returns the category of the remark (the subject of the filters).
135MLIR_CAPI_EXPORTED MlirStringRef mlirRemarkGetCategoryName(MlirRemark remark);
136
137/// Returns the combined `category:subcategory` name of the remark.
138MLIR_CAPI_EXPORTED MlirStringRef
139mlirRemarkGetFullCategoryName(MlirRemark remark);
140
141/// Returns the name of the function the remark refers to.
142MLIR_CAPI_EXPORTED MlirStringRef mlirRemarkGetFunctionName(MlirRemark remark);
143
144/// Returns the location of the remark.
145MLIR_CAPI_EXPORTED MlirLocation mlirRemarkGetLocation(MlirRemark remark);
146
147/// Returns the unique id of the remark within its engine (0 when unset).
148MLIR_CAPI_EXPORTED uint64_t mlirRemarkGetId(MlirRemark remark);
149
150/// Returns the number of related remark IDs.
151MLIR_CAPI_EXPORTED intptr_t mlirRemarkGetNumRelatedRemarks(MlirRemark remark);
152
153/// Returns the `pos`-th related remark ID.
154MLIR_CAPI_EXPORTED uint64_t mlirRemarkGetRelatedRemarkId(MlirRemark remark,
155 intptr_t pos);
156
157/// Returns the number of key/value arguments attached to the remark.
158MLIR_CAPI_EXPORTED intptr_t mlirRemarkGetNumArgs(MlirRemark remark);
159
160/// Returns the key of the `pos`-th argument of the remark.
161MLIR_CAPI_EXPORTED MlirStringRef mlirRemarkGetArgKey(MlirRemark remark,
162 intptr_t pos);
163
164/// Returns the value of the `pos`-th argument of the remark.
165MLIR_CAPI_EXPORTED MlirStringRef mlirRemarkGetArgValue(MlirRemark remark,
166 intptr_t pos);
167
168/// Prints the remark in its textual form, `[Kind] name | Category:... |
169/// Function=... | key=value, ...` (without its location).
170MLIR_CAPI_EXPORTED void
171mlirRemarkPrint(MlirRemark remark, MlirStringCallback callback, void *userData);
172
173//===----------------------------------------------------------------------===//
174// Emission.
175//===----------------------------------------------------------------------===//
176
177/// Emits a remark of `kind` at `location` through the remark engine of the
178/// location's context. `message` (when non-empty) and the `numArgs` key/value
179/// pairs become the arguments of the remark. Returns false, emitting nothing,
180/// when the context has no remark engine, the category is filtered out, or
181/// `kind` is MlirRemarkKindUnknown.
182MLIR_CAPI_EXPORTED bool mlirEmitOptimizationRemark(
183 MlirLocation location, MlirRemarkKind kind, MlirStringRef remarkName,
184 MlirStringRef categoryName, MlirStringRef subCategoryName,
185 MlirStringRef functionName, MlirStringRef message, intptr_t numArgs,
186 const MlirStringRef *argKeys, const MlirStringRef *argValues);
187
188#ifdef __cplusplus
189}
190#endif
191
192#endif // MLIR_C_REMARKS_H
193