| 1 | //===-- mlir-c/Interfaces.h - C API to Core MLIR IR interfaces ----*- 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 declares the C interface to MLIR interface classes. It is |
| 11 | // intended to contain interfaces defined in lib/Interfaces. |
| 12 | // |
| 13 | //===----------------------------------------------------------------------===// |
| 14 | |
| 15 | #ifndef MLIR_C_INTERFACES_H |
| 16 | #define MLIR_C_INTERFACES_H |
| 17 | |
| 18 | #include "mlir-c/IR.h" |
| 19 | #include "mlir-c/Support.h" |
| 20 | |
| 21 | #ifdef __cplusplus |
| 22 | extern "C" { |
| 23 | #endif |
| 24 | |
| 25 | #define DEFINE_C_API_STRUCT(name, storage) \ |
| 26 | struct name { \ |
| 27 | storage *ptr; \ |
| 28 | }; \ |
| 29 | typedef struct name name |
| 30 | |
| 31 | DEFINE_C_API_STRUCT(MlirMemoryEffect, void); |
| 32 | DEFINE_C_API_STRUCT(MlirMemoryEffectInstance, void); |
| 33 | DEFINE_C_API_STRUCT(MlirSideEffectResource, void); |
| 34 | |
| 35 | #undef DEFINE_C_API_STRUCT |
| 36 | |
| 37 | /// Returns `true` if the given operation implements an interface identified by |
| 38 | /// its TypeID. |
| 39 | MLIR_CAPI_EXPORTED bool |
| 40 | mlirOperationImplementsInterface(MlirOperation operation, |
| 41 | MlirTypeID interfaceTypeID); |
| 42 | |
| 43 | /// Returns `true` if the operation identified by its canonical string name |
| 44 | /// implements the interface identified by its TypeID in the given context. |
| 45 | /// Note that interfaces may be attached to operations in some contexts and not |
| 46 | /// others. |
| 47 | MLIR_CAPI_EXPORTED bool |
| 48 | mlirOperationImplementsInterfaceStatic(MlirStringRef operationName, |
| 49 | MlirContext context, |
| 50 | MlirTypeID interfaceTypeID); |
| 51 | |
| 52 | //===----------------------------------------------------------------------===// |
| 53 | // InferTypeOpInterface. |
| 54 | //===----------------------------------------------------------------------===// |
| 55 | |
| 56 | /// Returns the interface TypeID of the InferTypeOpInterface. |
| 57 | MLIR_CAPI_EXPORTED MlirTypeID mlirInferTypeOpInterfaceTypeID(void); |
| 58 | |
| 59 | /// These callbacks are used to return multiple types from functions while |
| 60 | /// transferring ownership to the caller. The first argument is the number of |
| 61 | /// consecutive elements pointed to by the second argument. The third argument |
| 62 | /// is an opaque pointer forwarded to the callback by the caller. |
| 63 | typedef void (*MlirTypesCallback)(intptr_t, MlirType *, void *); |
| 64 | |
| 65 | /// Infers the return types of the operation identified by its canonical given |
| 66 | /// the arguments that will be supplied to its generic builder. Calls `callback` |
| 67 | /// with the types of inferred arguments, potentially several times, on success. |
| 68 | /// Returns failure otherwise. |
| 69 | MLIR_CAPI_EXPORTED MlirLogicalResult mlirInferTypeOpInterfaceInferReturnTypes( |
| 70 | MlirStringRef opName, MlirContext context, MlirLocation location, |
| 71 | intptr_t nOperands, MlirValue *operands, MlirAttribute attributes, |
| 72 | void *properties, intptr_t nRegions, MlirRegion *regions, |
| 73 | MlirTypesCallback callback, void *userData); |
| 74 | |
| 75 | //===----------------------------------------------------------------------===// |
| 76 | // InferShapedTypeOpInterface. |
| 77 | //===----------------------------------------------------------------------===// |
| 78 | |
| 79 | /// Returns the interface TypeID of the InferShapedTypeOpInterface. |
| 80 | MLIR_CAPI_EXPORTED MlirTypeID mlirInferShapedTypeOpInterfaceTypeID(void); |
| 81 | |
| 82 | /// These callbacks are used to return multiple shaped type components from |
| 83 | /// functions while transferring ownership to the caller. The first argument is |
| 84 | /// the has rank boolean followed by the the rank and a pointer to the shape |
| 85 | /// (if applicable). The next argument is the element type, then the attribute. |
| 86 | /// The last argument is an opaque pointer forwarded to the callback by the |
| 87 | /// caller. This callback will be called potentially multiple times for each |
| 88 | /// shaped type components. |
| 89 | typedef void (*MlirShapedTypeComponentsCallback)(bool, intptr_t, |
| 90 | const int64_t *, MlirType, |
| 91 | MlirAttribute, void *); |
| 92 | |
| 93 | /// Infers the return shaped type components of the operation. Calls `callback` |
| 94 | /// with the types of inferred arguments on success. Returns failure otherwise. |
| 95 | MLIR_CAPI_EXPORTED MlirLogicalResult |
| 96 | mlirInferShapedTypeOpInterfaceInferReturnTypes( |
| 97 | MlirStringRef opName, MlirContext context, MlirLocation location, |
| 98 | intptr_t nOperands, MlirValue *operands, MlirAttribute attributes, |
| 99 | void *properties, intptr_t nRegions, MlirRegion *regions, |
| 100 | MlirShapedTypeComponentsCallback callback, void *userData); |
| 101 | |
| 102 | //===---------------------------------------------------------------------===// |
| 103 | // ConditionallySpeculatable |
| 104 | //===---------------------------------------------------------------------===// |
| 105 | |
| 106 | /// Enum representing the speculatability of an operation. |
| 107 | typedef enum { |
| 108 | /// The operation is not speculatable. |
| 109 | MlirSpeculatabilityNotSpeculatable, |
| 110 | /// The operation is speculatable. |
| 111 | MlirSpeculatabilitySpeculatable, |
| 112 | /// The operation is speculatable if all nested operations are speculatable. |
| 113 | MlirSpeculatabilityRecursivelySpeculatable |
| 114 | } MlirSpeculatability; |
| 115 | |
| 116 | /// Returns the interface TypeID of the ConditionallySpeculatable interface. |
| 117 | MLIR_CAPI_EXPORTED MlirTypeID |
| 118 | mlirConditionallySpeculatableOpInterfaceTypeID(void); |
| 119 | |
| 120 | /// Callbacks for implementing ConditionallySpeculatable from external code. |
| 121 | typedef struct { |
| 122 | /// Optional constructor for user data. Set to nullptr to disable it. |
| 123 | void (*construct)(void *userData); |
| 124 | /// Optional destructor for user data. Set to nullptr to disable it. |
| 125 | void (*destruct)(void *userData); |
| 126 | /// Returns the speculatability of the given operation. |
| 127 | MlirSpeculatability (*getSpeculatability)(MlirOperation op, void *userData); |
| 128 | void *userData; |
| 129 | } MlirConditionallySpeculatableOpInterfaceCallbacks; |
| 130 | |
| 131 | /// Attach a new FallbackModel for the ConditionallySpeculatable interface to |
| 132 | /// the named operation. The FallbackModel will call the provided callbacks. |
| 133 | MLIR_CAPI_EXPORTED void |
| 134 | mlirConditionallySpeculatableOpInterfaceAttachFallbackModel( |
| 135 | MlirContext ctx, MlirStringRef opName, |
| 136 | MlirConditionallySpeculatableOpInterfaceCallbacks callbacks); |
| 137 | |
| 138 | /// Returns the speculatability of the given operation. |
| 139 | /// |
| 140 | /// The operation must implement the ConditionallySpeculatable interface. |
| 141 | MLIR_CAPI_EXPORTED MlirSpeculatability |
| 142 | mlirConditionallySpeculatableOpInterfaceGetSpeculatability( |
| 143 | MlirOperation operation); |
| 144 | |
| 145 | //===---------------------------------------------------------------------===// |
| 146 | // MemoryEffectsOpInterface |
| 147 | //===---------------------------------------------------------------------===// |
| 148 | |
| 149 | /// Returns the singleton instance of the allocate memory effect. |
| 150 | MLIR_CAPI_EXPORTED MlirMemoryEffect mlirMemoryEffectsAllocateGet(void); |
| 151 | |
| 152 | /// Returns the singleton instance of the free memory effect. |
| 153 | MLIR_CAPI_EXPORTED MlirMemoryEffect mlirMemoryEffectsFreeGet(void); |
| 154 | |
| 155 | /// Returns the singleton instance of the read memory effect. |
| 156 | MLIR_CAPI_EXPORTED MlirMemoryEffect mlirMemoryEffectsReadGet(void); |
| 157 | |
| 158 | /// Returns the singleton instance of the write memory effect. |
| 159 | MLIR_CAPI_EXPORTED MlirMemoryEffect mlirMemoryEffectsWriteGet(void); |
| 160 | |
| 161 | /// Returns the TypeID identifying the concrete type of the given memory effect. |
| 162 | MLIR_CAPI_EXPORTED MlirTypeID |
| 163 | mlirMemoryEffectGetEffectID(MlirMemoryEffect effect); |
| 164 | |
| 165 | /// Returns the singleton instance of the default side effect resource. |
| 166 | MLIR_CAPI_EXPORTED MlirSideEffectResource |
| 167 | mlirSideEffectsDefaultResourceGet(void); |
| 168 | |
| 169 | /// Creates a memory effect instance without an associated IR entity. |
| 170 | /// `parameters` may be a null attribute. The caller owns the returned instance |
| 171 | /// and must destroy it with `mlirMemoryEffectInstanceDestroy`. |
| 172 | MLIR_CAPI_EXPORTED MlirMemoryEffectInstance mlirMemoryEffectInstanceCreate( |
| 173 | MlirMemoryEffect effect, MlirAttribute parameters, int stage, |
| 174 | bool effectOnFullRegion, MlirSideEffectResource resource); |
| 175 | |
| 176 | /// Creates a memory effect instance associated with an operation operand. |
| 177 | /// `parameters` may be a null attribute. The caller owns the returned instance |
| 178 | /// and must destroy it with `mlirMemoryEffectInstanceDestroy`. |
| 179 | MLIR_CAPI_EXPORTED MlirMemoryEffectInstance |
| 180 | mlirMemoryEffectInstanceCreateForOpOperand(MlirMemoryEffect effect, |
| 181 | MlirOpOperand opOperand, |
| 182 | MlirAttribute parameters, int stage, |
| 183 | bool effectOnFullRegion, |
| 184 | MlirSideEffectResource resource); |
| 185 | |
| 186 | /// Creates a memory effect instance associated with an operation result. |
| 187 | /// `result` must wrap an OpResult. `parameters` may be a null attribute. The |
| 188 | /// caller owns the returned instance and must destroy it with |
| 189 | /// `mlirMemoryEffectInstanceDestroy`. |
| 190 | MLIR_CAPI_EXPORTED MlirMemoryEffectInstance |
| 191 | mlirMemoryEffectInstanceCreateForOpResult(MlirMemoryEffect effect, |
| 192 | MlirValue result, |
| 193 | MlirAttribute parameters, int stage, |
| 194 | bool effectOnFullRegion, |
| 195 | MlirSideEffectResource resource); |
| 196 | |
| 197 | /// Creates a memory effect instance associated with a block argument. |
| 198 | /// `blockArgument` must wrap a BlockArgument. `parameters` may be a null |
| 199 | /// attribute. The caller owns the returned instance and must destroy it with |
| 200 | /// `mlirMemoryEffectInstanceDestroy`. |
| 201 | MLIR_CAPI_EXPORTED MlirMemoryEffectInstance |
| 202 | mlirMemoryEffectInstanceCreateForBlockArgument( |
| 203 | MlirMemoryEffect effect, MlirValue blockArgument, MlirAttribute parameters, |
| 204 | int stage, bool effectOnFullRegion, MlirSideEffectResource resource); |
| 205 | |
| 206 | /// Creates a memory effect instance associated with a symbol. `symbol` must be |
| 207 | /// a SymbolRefAttr. `parameters` may be a null attribute. The caller owns the |
| 208 | /// returned instance and must destroy it with |
| 209 | /// `mlirMemoryEffectInstanceDestroy`. |
| 210 | MLIR_CAPI_EXPORTED MlirMemoryEffectInstance |
| 211 | mlirMemoryEffectInstanceCreateForSymbol(MlirMemoryEffect effect, |
| 212 | MlirAttribute symbol, |
| 213 | MlirAttribute parameters, int stage, |
| 214 | bool effectOnFullRegion, |
| 215 | MlirSideEffectResource resource); |
| 216 | |
| 217 | /// Creates a copy of a memory effect instance. The caller must destroy |
| 218 | /// the returned instance with `mlirMemoryEffectInstanceDestroy`. |
| 219 | MLIR_CAPI_EXPORTED MlirMemoryEffectInstance |
| 220 | mlirMemoryEffectInstanceClone(MlirMemoryEffectInstance instance); |
| 221 | |
| 222 | /// Destroys a memory effect instance created or cloned by APIs above. |
| 223 | MLIR_CAPI_EXPORTED void |
| 224 | mlirMemoryEffectInstanceDestroy(MlirMemoryEffectInstance instance); |
| 225 | |
| 226 | /// Returns the memory effect of the given instance. |
| 227 | MLIR_CAPI_EXPORTED MlirMemoryEffect |
| 228 | mlirMemoryEffectInstanceGetEffect(MlirMemoryEffectInstance instance); |
| 229 | |
| 230 | /// Returns the side effect resource of the given instance. |
| 231 | MLIR_CAPI_EXPORTED MlirSideEffectResource |
| 232 | mlirMemoryEffectInstanceGetResource(MlirMemoryEffectInstance instance); |
| 233 | |
| 234 | /// Returns the stage of the given instance. |
| 235 | MLIR_CAPI_EXPORTED int |
| 236 | mlirMemoryEffectInstanceGetStage(MlirMemoryEffectInstance instance); |
| 237 | |
| 238 | /// Returns true if the given instance has effect on every single value of |
| 239 | /// the resource. |
| 240 | MLIR_CAPI_EXPORTED bool mlirMemoryEffectInstanceGetEffectOnFullRegion( |
| 241 | MlirMemoryEffectInstance instance); |
| 242 | |
| 243 | /// Returns the parameters of the given instance, or a null attribute if there |
| 244 | /// are no parameters. |
| 245 | MLIR_CAPI_EXPORTED MlirAttribute |
| 246 | mlirMemoryEffectInstanceGetParameters(MlirMemoryEffectInstance instance); |
| 247 | |
| 248 | /// Returns the value (OpOperand, OpResult, or BlockArgument) of the given |
| 249 | /// instance, or a null value if there is no associated value. |
| 250 | MLIR_CAPI_EXPORTED MlirValue |
| 251 | mlirMemoryEffectInstanceGetValue(MlirMemoryEffectInstance instance); |
| 252 | |
| 253 | /// Returns the symbol reference of the given instance, or a null attribute if |
| 254 | /// there is no associated symbol. |
| 255 | MLIR_CAPI_EXPORTED MlirAttribute |
| 256 | mlirMemoryEffectInstanceGetSymbolRef(MlirMemoryEffectInstance instance); |
| 257 | |
| 258 | /// Callback for receiving a batch of memory effect instances. `effects` points |
| 259 | /// to `numEffects` consecutive instances. Ownership is not transferred, and |
| 260 | /// the instances are valid only while `callback` is executing. The |
| 261 | /// caller-provided `userData` is forwarded to the callback. |
| 262 | typedef void (*MlirMemoryEffectInstancesCallback)( |
| 263 | intptr_t numEffects, MlirMemoryEffectInstance *effects, void *userData); |
| 264 | |
| 265 | /// Returns the interface TypeID of the MemoryEffectsOpInterface. |
| 266 | MLIR_CAPI_EXPORTED MlirTypeID mlirMemoryEffectsOpInterfaceTypeID(void); |
| 267 | |
| 268 | /// Callbacks for implementing MemoryEffectsOpInterface from external code. |
| 269 | typedef struct { |
| 270 | /// Optional constructor for user data. Set to nullptr to disable it. |
| 271 | void (*construct)(void *userData); |
| 272 | /// Optional destructor for user data. Set to nullptr to disable it. |
| 273 | void (*destruct)(void *userData); |
| 274 | /// Get memory effects callback. Implementations report effects by invoking |
| 275 | /// `callback` before returning. The supplied callback copies the instances, |
| 276 | /// so implementations retain ownership of the instances and only need to |
| 277 | /// keep them valid until `callback` returns. |
| 278 | void (*getEffects)(MlirOperation op, |
| 279 | MlirMemoryEffectInstancesCallback callback, |
| 280 | void *callbackUserData, void *userData); |
| 281 | void *userData; |
| 282 | } MlirMemoryEffectsOpInterfaceCallbacks; |
| 283 | |
| 284 | /// Attach a new FallbackModel for the MemoryEffectsOpInterface to the named |
| 285 | /// operation. The FallbackModel will call the provided callbacks. |
| 286 | MLIR_CAPI_EXPORTED void mlirMemoryEffectsOpInterfaceAttachFallbackModel( |
| 287 | MlirContext ctx, MlirStringRef opName, |
| 288 | MlirMemoryEffectsOpInterfaceCallbacks callbacks); |
| 289 | |
| 290 | /// Gets the memory effects of the given operation. The operation must |
| 291 | /// implement the MemoryEffectsOpInterface. Invokes `callback` once with all |
| 292 | /// effects. Ownership is not transferred; call |
| 293 | /// `mlirMemoryEffectInstanceClone` from the callback to keep a copy after the |
| 294 | /// callback returns. |
| 295 | MLIR_CAPI_EXPORTED void mlirMemoryEffectsOpInterfaceGetEffects( |
| 296 | MlirOperation operation, MlirMemoryEffectInstancesCallback callback, |
| 297 | void *userData); |
| 298 | |
| 299 | #ifdef __cplusplus |
| 300 | } |
| 301 | #endif |
| 302 | |
| 303 | #endif // MLIR_C_INTERFACES_H |
| 304 | |