| 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 |
| 18 | |
| 19 | #include "mlir-c/IR.h" |
| 20 | #include "mlir-c/Support.h" |
| 21 | |
| 22 | #ifdef __cplusplus |
| 23 | extern "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. |
| 32 | struct { |
| 33 | const void *; |
| 34 | }; |
| 35 | typedef struct MlirRemark ; |
| 36 | |
| 37 | /// The outcome a remark describes (see mlir::remark::RemarkKind). |
| 38 | enum { |
| 39 | , |
| 40 | /// An optimization was applied. |
| 41 | , |
| 42 | /// A profitable optimization opportunity was found but not applied. |
| 43 | , |
| 44 | /// The optimization was attempted but failed. |
| 45 | , |
| 46 | /// Informational context without a pass/fail outcome. |
| 47 | |
| 48 | }; |
| 49 | typedef enum MlirRemarkKind ; |
| 50 | |
| 51 | /// The emitting policy of the remark engine. |
| 52 | enum { |
| 53 | /// Report every remark as it is emitted. |
| 54 | , |
| 55 | /// Postpone remarks and report the final set when the engine is finalized, |
| 56 | /// grouping related remarks under their parents. |
| 57 | |
| 58 | }; |
| 59 | typedef enum MlirRemarkPolicy ; |
| 60 | |
| 61 | /// The serialization format of a remark output file. |
| 62 | enum { |
| 63 | , |
| 64 | |
| 65 | }; |
| 66 | typedef enum 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. |
| 72 | struct { |
| 73 | MlirStringRef ; |
| 74 | MlirStringRef ; |
| 75 | MlirStringRef ; |
| 76 | MlirStringRef ; |
| 77 | MlirStringRef ; |
| 78 | }; |
| 79 | typedef struct MlirRemarkCategories ; |
| 80 | |
| 81 | /// Callback receiving every remark the engine reports. |
| 82 | typedef void (*)(MlirRemark , 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). |
| 92 | MLIR_CAPI_EXPORTED MlirLogicalResult ( |
| 93 | MlirContext context, MlirRemarkCategories categories, |
| 94 | MlirRemarkPolicy policy, bool ); |
| 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. |
| 100 | MLIR_CAPI_EXPORTED MlirLogicalResult ( |
| 101 | MlirContext context, MlirRemarkCategories categories, |
| 102 | MlirRemarkPolicy policy, MlirRemarkFileFormat format, MlirStringRef path, |
| 103 | bool ); |
| 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. |
| 109 | MLIR_CAPI_EXPORTED MlirLogicalResult |
| 110 | ( |
| 111 | MlirContext context, MlirRemarkCategories categories, |
| 112 | MlirRemarkPolicy policy, MlirRemarkCallback callback, void *userData, |
| 113 | void (*deleteUserData)(void *), bool ); |
| 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. |
| 118 | MLIR_CAPI_EXPORTED void |
| 119 | (MlirContext context); |
| 120 | |
| 121 | /// Returns whether the context has a remark engine enabled. |
| 122 | MLIR_CAPI_EXPORTED bool (MlirContext context); |
| 123 | |
| 124 | //===----------------------------------------------------------------------===// |
| 125 | // Remark accessors (valid only inside a remark callback). |
| 126 | //===----------------------------------------------------------------------===// |
| 127 | |
| 128 | /// Returns the kind of the remark. |
| 129 | MLIR_CAPI_EXPORTED MlirRemarkKind (MlirRemark ); |
| 130 | |
| 131 | /// Returns the name identifying the remark. |
| 132 | MLIR_CAPI_EXPORTED MlirStringRef (MlirRemark ); |
| 133 | |
| 134 | /// Returns the category of the remark (the subject of the filters). |
| 135 | MLIR_CAPI_EXPORTED MlirStringRef (MlirRemark ); |
| 136 | |
| 137 | /// Returns the combined `category:subcategory` name of the remark. |
| 138 | MLIR_CAPI_EXPORTED MlirStringRef |
| 139 | (MlirRemark ); |
| 140 | |
| 141 | /// Returns the name of the function the remark refers to. |
| 142 | MLIR_CAPI_EXPORTED MlirStringRef (MlirRemark ); |
| 143 | |
| 144 | /// Returns the location of the remark. |
| 145 | MLIR_CAPI_EXPORTED MlirLocation (MlirRemark ); |
| 146 | |
| 147 | /// Returns the unique id of the remark within its engine (0 when unset). |
| 148 | MLIR_CAPI_EXPORTED uint64_t (MlirRemark ); |
| 149 | |
| 150 | /// Returns the number of related remark IDs. |
| 151 | MLIR_CAPI_EXPORTED intptr_t (MlirRemark ); |
| 152 | |
| 153 | /// Returns the `pos`-th related remark ID. |
| 154 | MLIR_CAPI_EXPORTED uint64_t (MlirRemark , |
| 155 | intptr_t pos); |
| 156 | |
| 157 | /// Returns the number of key/value arguments attached to the remark. |
| 158 | MLIR_CAPI_EXPORTED intptr_t (MlirRemark ); |
| 159 | |
| 160 | /// Returns the key of the `pos`-th argument of the remark. |
| 161 | MLIR_CAPI_EXPORTED MlirStringRef (MlirRemark , |
| 162 | intptr_t pos); |
| 163 | |
| 164 | /// Returns the value of the `pos`-th argument of the remark. |
| 165 | MLIR_CAPI_EXPORTED MlirStringRef (MlirRemark , |
| 166 | intptr_t pos); |
| 167 | |
| 168 | /// Prints the remark in its textual form, `[Kind] name | Category:... | |
| 169 | /// Function=... | key=value, ...` (without its location). |
| 170 | MLIR_CAPI_EXPORTED void |
| 171 | (MlirRemark , 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. |
| 182 | MLIR_CAPI_EXPORTED bool ( |
| 183 | MlirLocation location, MlirRemarkKind kind, MlirStringRef , |
| 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 | |