1//===-- mlir-c/IR.h - C API to Core MLIR IR classes ---------------*- 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 core IR classes.
11//
12// Many exotic languages can interoperate with C code but have a harder time
13// with C++ due to name mangling. So in addition to C, this interface enables
14// tools written in such languages.
15//
16//===----------------------------------------------------------------------===//
17
18#ifndef MLIR_C_IR_H
19#define MLIR_C_IR_H
20
21#include <stdbool.h>
22#include <stdint.h>
23
24#include "mlir-c/Support.h"
25
26#ifdef __cplusplus
27extern "C" {
28#endif
29
30//===----------------------------------------------------------------------===//
31/// Opaque type declarations.
32///
33/// Types are exposed to C bindings as structs containing opaque pointers. They
34/// are not supposed to be inspected from C. This allows the underlying
35/// representation to change without affecting the API users. The use of structs
36/// instead of typedefs enables some type safety as structs are not implicitly
37/// convertible to each other.
38///
39/// Instances of these types may or may not own the underlying object (most
40/// often only point to an IR fragment without owning it). The ownership
41/// semantics is defined by how an instance of the type was obtained.
42
43//===----------------------------------------------------------------------===//
44
45#define DEFINE_C_API_STRUCT(name, storage) \
46 struct name { \
47 storage *ptr; \
48 }; \
49 typedef struct name name
50
51DEFINE_C_API_STRUCT(MlirAsmState, void);
52DEFINE_C_API_STRUCT(MlirBytecodeWriterConfig, void);
53DEFINE_C_API_STRUCT(MlirContext, void);
54DEFINE_C_API_STRUCT(MlirDialect, void);
55DEFINE_C_API_STRUCT(MlirDialectRegistry, void);
56DEFINE_C_API_STRUCT(MlirOperation, void);
57DEFINE_C_API_STRUCT(MlirOpOperand, void);
58DEFINE_C_API_STRUCT(MlirOpPrintingFlags, void);
59DEFINE_C_API_STRUCT(MlirBlock, void);
60DEFINE_C_API_STRUCT(MlirRegion, void);
61DEFINE_C_API_STRUCT(MlirSymbolTable, void);
62DEFINE_C_API_STRUCT(MlirIRMapping, void);
63
64DEFINE_C_API_STRUCT(MlirAttribute, const void);
65DEFINE_C_API_STRUCT(MlirIdentifier, const void);
66DEFINE_C_API_STRUCT(MlirLocation, const void);
67DEFINE_C_API_STRUCT(MlirModule, const void);
68DEFINE_C_API_STRUCT(MlirType, const void);
69DEFINE_C_API_STRUCT(MlirValue, const void);
70
71#undef DEFINE_C_API_STRUCT
72
73/// Named MLIR attribute.
74///
75/// A named attribute is essentially a (name, attribute) pair where the name is
76/// a string.
77struct MlirNamedAttribute {
78 MlirIdentifier name;
79 MlirAttribute attribute;
80};
81typedef struct MlirNamedAttribute MlirNamedAttribute;
82
83//===----------------------------------------------------------------------===//
84// Context API.
85//===----------------------------------------------------------------------===//
86
87/// Creates an MLIR context and transfers its ownership to the caller.
88/// This sets the default multithreading option (enabled).
89MLIR_CAPI_EXPORTED MlirContext mlirContextCreate(void);
90
91/// Creates an MLIR context with an explicit setting of the multithreading
92/// setting and transfers its ownership to the caller.
93MLIR_CAPI_EXPORTED MlirContext
94mlirContextCreateWithThreading(bool threadingEnabled);
95
96/// Creates an MLIR context, setting the multithreading setting explicitly and
97/// pre-loading the dialects from the provided DialectRegistry.
98MLIR_CAPI_EXPORTED MlirContext mlirContextCreateWithRegistry(
99 MlirDialectRegistry registry, bool threadingEnabled);
100
101/// Checks if two contexts are equal.
102MLIR_CAPI_EXPORTED bool mlirContextEqual(MlirContext ctx1, MlirContext ctx2);
103
104/// Checks whether a context is null.
105static inline bool mlirContextIsNull(MlirContext context) {
106 return !context.ptr;
107}
108
109/// Takes an MLIR context owned by the caller and destroys it.
110MLIR_CAPI_EXPORTED void mlirContextDestroy(MlirContext context);
111
112/// Sets whether unregistered dialects are allowed in this context.
113MLIR_CAPI_EXPORTED void
114mlirContextSetAllowUnregisteredDialects(MlirContext context, bool allow);
115
116/// Returns whether the context allows unregistered dialects.
117MLIR_CAPI_EXPORTED bool
118mlirContextGetAllowUnregisteredDialects(MlirContext context);
119
120/// Returns the number of dialects registered with the given context. A
121/// registered dialect will be loaded if needed by the parser.
122MLIR_CAPI_EXPORTED intptr_t
123mlirContextGetNumRegisteredDialects(MlirContext context);
124
125/// Append the contents of the given dialect registry to the registry associated
126/// with the context.
127MLIR_CAPI_EXPORTED void
128mlirContextAppendDialectRegistry(MlirContext ctx, MlirDialectRegistry registry);
129
130/// Returns the number of dialects loaded by the context.
131
132MLIR_CAPI_EXPORTED intptr_t
133mlirContextGetNumLoadedDialects(MlirContext context);
134
135/// Gets the dialect instance owned by the given context using the dialect
136/// namespace to identify it, loads (i.e., constructs the instance of) the
137/// dialect if necessary. If the dialect is not registered with the context,
138/// returns null. Use mlirContextLoad<Name>Dialect to load an unregistered
139/// dialect.
140MLIR_CAPI_EXPORTED MlirDialect mlirContextGetOrLoadDialect(MlirContext context,
141 MlirStringRef name);
142
143/// Gets the dialect instance owned by the given context using the dialect
144/// namespace to identify it. If the dialect is not loaded by the context,
145/// returns null. Use mlirContextGetOrLoadDialect to load a dialect if it is
146/// registered with the context.
147MLIR_CAPI_EXPORTED MlirDialect mlirContextGetLoadedDialect(MlirContext context,
148 MlirStringRef name);
149
150/// Set threading mode (must be set to false to mlir-print-ir-after-all).
151MLIR_CAPI_EXPORTED void mlirContextEnableMultithreading(MlirContext context,
152 bool enable);
153
154/// Eagerly loads all available dialects registered with a context, making
155/// them available for use for IR construction.
156MLIR_CAPI_EXPORTED void
157mlirContextLoadAllAvailableDialects(MlirContext context);
158
159/// Returns whether the given fully-qualified operation (i.e.
160/// 'dialect.operation') is registered with the context. This will return true
161/// if the dialect is loaded and the operation is registered within the
162/// dialect.
163MLIR_CAPI_EXPORTED bool mlirContextIsRegisteredOperation(MlirContext context,
164 MlirStringRef name);
165
166/// Sets the thread pool of the context explicitly, enabling multithreading in
167/// the process. This API should be used to avoid re-creating thread pools in
168/// long-running applications that perform multiple compilations, see
169/// the C++ documentation for MLIRContext for details.
170MLIR_CAPI_EXPORTED void mlirContextSetThreadPool(MlirContext context,
171 MlirLlvmThreadPool threadPool);
172
173/// Gets the number of threads of the thread pool of the context when
174/// multithreading is enabled. Returns 1 if no multithreading.
175MLIR_CAPI_EXPORTED unsigned mlirContextGetNumThreads(MlirContext context);
176
177/// Gets the thread pool of the context when enabled multithreading, otherwise
178/// an assertion is raised.
179MLIR_CAPI_EXPORTED MlirLlvmThreadPool
180mlirContextGetThreadPool(MlirContext context);
181
182/// Begins a transient scope on the context, freezing the base layer (loaded
183/// dialects, registered operations, interface models, and existing
184/// types/attributes).
185/// Precondition: The context must not already be in a transient scope.
186MLIR_CAPI_EXPORTED void mlirContextBeginTransientScope(MlirContext context);
187
188/// Ends the transient scope and resets the context to the base state, pruning
189/// transient types, attributes, affine expressions, distinct attributes, and
190/// unregistered operations added during the transient scope.
191MLIR_CAPI_EXPORTED void mlirContextEndTransientScope(MlirContext context);
192
193/// Returns whether the context is currently in a transient scope.
194MLIR_CAPI_EXPORTED bool mlirContextIsInTransientScope(MlirContext context);
195
196//===----------------------------------------------------------------------===//
197// Dialect API.
198//===----------------------------------------------------------------------===//
199
200/// Returns the context that owns the dialect.
201MLIR_CAPI_EXPORTED MlirContext mlirDialectGetContext(MlirDialect dialect);
202
203/// Checks if the dialect is null.
204static inline bool mlirDialectIsNull(MlirDialect dialect) {
205 return !dialect.ptr;
206}
207
208/// Checks if two dialects that belong to the same context are equal. Dialects
209/// from different contexts will not compare equal.
210MLIR_CAPI_EXPORTED bool mlirDialectEqual(MlirDialect dialect1,
211 MlirDialect dialect2);
212
213/// Returns the namespace of the given dialect.
214MLIR_CAPI_EXPORTED MlirStringRef mlirDialectGetNamespace(MlirDialect dialect);
215
216//===----------------------------------------------------------------------===//
217// DialectHandle API.
218// Registration entry-points for each dialect are declared using the common
219// MLIR_DECLARE_DIALECT_REGISTRATION_CAPI macro, which takes the dialect
220// API name (i.e. "Func", "Tensor", "Linalg") and namespace (i.e. "func",
221// "tensor", "linalg"). The following declarations are produced:
222//
223// /// Gets the above hook methods in struct form for a dialect by namespace.
224// /// This is intended to facilitate dynamic lookup and registration of
225// /// dialects via a plugin facility based on shared library symbol lookup.
226// const MlirDialectHandle *mlirGetDialectHandle__{NAMESPACE}__();
227//
228// This is done via a common macro to facilitate future expansion to
229// registration schemes.
230//===----------------------------------------------------------------------===//
231
232struct MlirDialectHandle {
233 const void *ptr;
234};
235typedef struct MlirDialectHandle MlirDialectHandle;
236
237#define MLIR_DECLARE_CAPI_DIALECT_REGISTRATION(Name, Namespace) \
238 MLIR_CAPI_EXPORTED MlirDialectHandle mlirGetDialectHandle__##Namespace##__( \
239 void)
240
241/// Returns the namespace associated with the provided dialect handle.
242MLIR_CAPI_EXPORTED
243MlirStringRef mlirDialectHandleGetNamespace(MlirDialectHandle);
244
245/// Inserts the dialect associated with the provided dialect handle into the
246/// provided dialect registry
247MLIR_CAPI_EXPORTED void mlirDialectHandleInsertDialect(MlirDialectHandle,
248 MlirDialectRegistry);
249
250/// Registers the dialect associated with the provided dialect handle.
251MLIR_CAPI_EXPORTED void mlirDialectHandleRegisterDialect(MlirDialectHandle,
252 MlirContext);
253
254/// Loads the dialect associated with the provided dialect handle.
255MLIR_CAPI_EXPORTED MlirDialect mlirDialectHandleLoadDialect(MlirDialectHandle,
256 MlirContext);
257
258//===----------------------------------------------------------------------===//
259// DialectRegistry API.
260//===----------------------------------------------------------------------===//
261
262/// Creates a dialect registry and transfers its ownership to the caller.
263MLIR_CAPI_EXPORTED MlirDialectRegistry mlirDialectRegistryCreate(void);
264
265/// Checks if the dialect registry is null.
266static inline bool mlirDialectRegistryIsNull(MlirDialectRegistry registry) {
267 return !registry.ptr;
268}
269
270/// Takes a dialect registry owned by the caller and destroys it.
271MLIR_CAPI_EXPORTED void
272mlirDialectRegistryDestroy(MlirDialectRegistry registry);
273
274//===----------------------------------------------------------------------===//
275// Location API.
276//===----------------------------------------------------------------------===//
277
278/// Returns the underlying location attribute of this location.
279MLIR_CAPI_EXPORTED MlirAttribute
280mlirLocationGetAttribute(MlirLocation location);
281
282/// Creates a location from a location attribute.
283MLIR_CAPI_EXPORTED MlirLocation
284mlirLocationFromAttribute(MlirAttribute attribute);
285
286/// Creates an File/Line/Column location owned by the given context.
287MLIR_CAPI_EXPORTED MlirLocation mlirLocationFileLineColGet(
288 MlirContext context, MlirStringRef filename, unsigned line, unsigned col);
289
290/// Creates an File/Line/Column range location owned by the given context.
291MLIR_CAPI_EXPORTED MlirLocation mlirLocationFileLineColRangeGet(
292 MlirContext context, MlirStringRef filename, unsigned start_line,
293 unsigned start_col, unsigned end_line, unsigned end_col);
294
295/// Getter for filename of FileLineColRange.
296MLIR_CAPI_EXPORTED MlirIdentifier
297mlirLocationFileLineColRangeGetFilename(MlirLocation location);
298
299/// Getter for start_line of FileLineColRange.
300MLIR_CAPI_EXPORTED int
301mlirLocationFileLineColRangeGetStartLine(MlirLocation location);
302
303/// Getter for start_column of FileLineColRange.
304MLIR_CAPI_EXPORTED int
305mlirLocationFileLineColRangeGetStartColumn(MlirLocation location);
306
307/// Getter for end_line of FileLineColRange.
308MLIR_CAPI_EXPORTED int
309mlirLocationFileLineColRangeGetEndLine(MlirLocation location);
310
311/// Getter for end_column of FileLineColRange.
312MLIR_CAPI_EXPORTED int
313mlirLocationFileLineColRangeGetEndColumn(MlirLocation location);
314
315/// TypeID Getter for FileLineColRange.
316MLIR_CAPI_EXPORTED MlirTypeID mlirLocationFileLineColRangeGetTypeID(void);
317
318/// Checks whether the given location is an FileLineColRange.
319MLIR_CAPI_EXPORTED bool mlirLocationIsAFileLineColRange(MlirLocation location);
320
321/// Creates a call site location with a callee and a caller.
322MLIR_CAPI_EXPORTED MlirLocation mlirLocationCallSiteGet(MlirLocation callee,
323 MlirLocation caller);
324
325/// Getter for callee of CallSite.
326MLIR_CAPI_EXPORTED MlirLocation
327mlirLocationCallSiteGetCallee(MlirLocation location);
328
329/// Getter for caller of CallSite.
330MLIR_CAPI_EXPORTED MlirLocation
331mlirLocationCallSiteGetCaller(MlirLocation location);
332
333/// TypeID Getter for CallSite.
334MLIR_CAPI_EXPORTED MlirTypeID mlirLocationCallSiteGetTypeID(void);
335
336/// Checks whether the given location is an CallSite.
337MLIR_CAPI_EXPORTED bool mlirLocationIsACallSite(MlirLocation location);
338
339/// Creates a fused location with an array of locations and metadata.
340MLIR_CAPI_EXPORTED MlirLocation
341mlirLocationFusedGet(MlirContext ctx, intptr_t nLocations,
342 MlirLocation const *locations, MlirAttribute metadata);
343
344/// Getter for number of locations fused together.
345MLIR_CAPI_EXPORTED unsigned
346mlirLocationFusedGetNumLocations(MlirLocation location);
347
348/// Getter for locations of Fused. Requires pre-allocated memory of
349/// #fusedLocations X sizeof(MlirLocation).
350MLIR_CAPI_EXPORTED void
351mlirLocationFusedGetLocations(MlirLocation location,
352 MlirLocation *locationsCPtr);
353
354/// Getter for metadata of Fused.
355MLIR_CAPI_EXPORTED MlirAttribute
356mlirLocationFusedGetMetadata(MlirLocation location);
357
358/// TypeID Getter for Fused.
359MLIR_CAPI_EXPORTED MlirTypeID mlirLocationFusedGetTypeID(void);
360
361/// Checks whether the given location is an Fused.
362MLIR_CAPI_EXPORTED bool mlirLocationIsAFused(MlirLocation location);
363
364/// Creates a name location owned by the given context. Providing null location
365/// for childLoc is allowed and if childLoc is null location, then the behavior
366/// is the same as having unknown child location.
367MLIR_CAPI_EXPORTED MlirLocation mlirLocationNameGet(MlirContext context,
368 MlirStringRef name,
369 MlirLocation childLoc);
370
371/// Getter for name of Name.
372MLIR_CAPI_EXPORTED MlirIdentifier
373mlirLocationNameGetName(MlirLocation location);
374
375/// Getter for childLoc of Name.
376MLIR_CAPI_EXPORTED MlirLocation
377mlirLocationNameGetChildLoc(MlirLocation location);
378
379/// TypeID Getter for Name.
380MLIR_CAPI_EXPORTED MlirTypeID mlirLocationNameGetTypeID(void);
381
382/// Checks whether the given location is an Name.
383MLIR_CAPI_EXPORTED bool mlirLocationIsAName(MlirLocation location);
384
385/// Creates a location with unknown position owned by the given context.
386MLIR_CAPI_EXPORTED MlirLocation mlirLocationUnknownGet(MlirContext context);
387
388/// TypeID Getter for Unknown.
389MLIR_CAPI_EXPORTED MlirTypeID mlirLocationUnknownGetTypeID(void);
390
391/// Checks whether the given location is an Unknown.
392MLIR_CAPI_EXPORTED bool mlirLocationIsAUnknown(MlirLocation location);
393
394/// Gets the context that a location was created with.
395MLIR_CAPI_EXPORTED MlirContext mlirLocationGetContext(MlirLocation location);
396
397/// Checks if the location is null.
398static inline bool mlirLocationIsNull(MlirLocation location) {
399 return !location.ptr;
400}
401
402/// Checks if two locations are equal.
403MLIR_CAPI_EXPORTED bool mlirLocationEqual(MlirLocation l1, MlirLocation l2);
404
405/// Prints a location by sending chunks of the string representation and
406/// forwarding `userData to `callback`. Note that the callback may be called
407/// several times with consecutive chunks of the string.
408MLIR_CAPI_EXPORTED void mlirLocationPrint(MlirLocation location,
409 MlirStringCallback callback,
410 void *userData);
411
412//===----------------------------------------------------------------------===//
413// Module API.
414//===----------------------------------------------------------------------===//
415
416/// Creates a new, empty module and transfers ownership to the caller.
417MLIR_CAPI_EXPORTED MlirModule mlirModuleCreateEmpty(MlirLocation location);
418
419/// Parses a module from the string and transfers ownership to the caller.
420MLIR_CAPI_EXPORTED MlirModule mlirModuleCreateParse(MlirContext context,
421 MlirStringRef module);
422
423/// Parses a module from file and transfers ownership to the caller.
424MLIR_CAPI_EXPORTED MlirModule
425mlirModuleCreateParseFromFile(MlirContext context, MlirStringRef fileName);
426
427/// Gets the context that a module was created with.
428MLIR_CAPI_EXPORTED MlirContext mlirModuleGetContext(MlirModule module);
429
430/// Gets the body of the module, i.e. the only block it contains.
431MLIR_CAPI_EXPORTED MlirBlock mlirModuleGetBody(MlirModule module);
432
433/// Checks whether a module is null.
434static inline bool mlirModuleIsNull(MlirModule module) { return !module.ptr; }
435
436/// Takes a module owned by the caller and deletes it.
437MLIR_CAPI_EXPORTED void mlirModuleDestroy(MlirModule module);
438
439/// Views the module as a generic operation.
440MLIR_CAPI_EXPORTED MlirOperation mlirModuleGetOperation(MlirModule module);
441
442/// Views the generic operation as a module.
443/// The returned module is null when the input operation was not a ModuleOp.
444MLIR_CAPI_EXPORTED MlirModule mlirModuleFromOperation(MlirOperation op);
445
446/// Checks if two modules are equal.
447MLIR_CAPI_EXPORTED bool mlirModuleEqual(MlirModule lhs, MlirModule rhs);
448
449/// Compute a hash for the given module.
450MLIR_CAPI_EXPORTED size_t mlirModuleHashValue(MlirModule mod);
451
452//===----------------------------------------------------------------------===//
453// Operation state.
454//===----------------------------------------------------------------------===//
455
456/// An auxiliary class for constructing operations.
457///
458/// This class contains all the information necessary to construct the
459/// operation. It owns the MlirRegions it has pointers to and does not own
460/// anything else. By default, the state can be constructed from a name and
461/// location, the latter being also used to access the context, and has no other
462/// components. These components can be added progressively until the operation
463/// is constructed. Users are not expected to rely on the internals of this
464/// class and should use mlirOperationState* functions instead.
465
466struct MlirOperationState {
467 MlirStringRef name;
468 MlirLocation location;
469 intptr_t nResults;
470 MlirType *results;
471 intptr_t nOperands;
472 MlirValue *operands;
473 intptr_t nRegions;
474 MlirRegion *regions;
475 intptr_t nSuccessors;
476 MlirBlock *successors;
477 intptr_t nAttributes;
478 MlirNamedAttribute *attributes;
479 bool enableResultTypeInference;
480};
481typedef struct MlirOperationState MlirOperationState;
482
483/// Constructs an operation state from a name and a location.
484MLIR_CAPI_EXPORTED MlirOperationState mlirOperationStateGet(MlirStringRef name,
485 MlirLocation loc);
486
487/// Adds a list of components to the operation state.
488MLIR_CAPI_EXPORTED void mlirOperationStateAddResults(MlirOperationState *state,
489 intptr_t n,
490 MlirType const *results);
491MLIR_CAPI_EXPORTED void
492mlirOperationStateAddOperands(MlirOperationState *state, intptr_t n,
493 MlirValue const *operands);
494MLIR_CAPI_EXPORTED void
495mlirOperationStateAddOwnedRegions(MlirOperationState *state, intptr_t n,
496 MlirRegion const *regions);
497MLIR_CAPI_EXPORTED void
498mlirOperationStateAddSuccessors(MlirOperationState *state, intptr_t n,
499 MlirBlock const *successors);
500MLIR_CAPI_EXPORTED void
501mlirOperationStateAddAttributes(MlirOperationState *state, intptr_t n,
502 MlirNamedAttribute const *attributes);
503
504/// Enables result type inference for the operation under construction. If
505/// enabled, then the caller must not have called
506/// mlirOperationStateAddResults(). Note that if enabled, the
507/// mlirOperationCreate() call is failable: it will return a null operation
508/// on inference failure and will emit diagnostics.
509MLIR_CAPI_EXPORTED void
510mlirOperationStateEnableResultTypeInference(MlirOperationState *state);
511
512//===----------------------------------------------------------------------===//
513// AsmState API.
514// While many of these are simple settings that could be represented in a
515// struct, they are wrapped in a heap allocated object and accessed via
516// functions to maximize the possibility of compatibility over time.
517//===----------------------------------------------------------------------===//
518
519/// Creates new AsmState, as with AsmState the IR should not be mutated
520/// in-between using this state.
521/// Must be freed with a call to mlirAsmStateDestroy().
522// TODO: This should be expanded to handle location & resouce map.
523MLIR_CAPI_EXPORTED MlirAsmState
524mlirAsmStateCreateForOperation(MlirOperation op, MlirOpPrintingFlags flags);
525
526/// Creates new AsmState from value.
527/// Must be freed with a call to mlirAsmStateDestroy().
528// TODO: This should be expanded to handle location & resouce map.
529MLIR_CAPI_EXPORTED MlirAsmState
530mlirAsmStateCreateForValue(MlirValue value, MlirOpPrintingFlags flags);
531
532/// Destroys printing flags created with mlirAsmStateCreate.
533MLIR_CAPI_EXPORTED void mlirAsmStateDestroy(MlirAsmState state);
534
535//===----------------------------------------------------------------------===//
536// Op Printing flags API.
537// While many of these are simple settings that could be represented in a
538// struct, they are wrapped in a heap allocated object and accessed via
539// functions to maximize the possibility of compatibility over time.
540//===----------------------------------------------------------------------===//
541
542/// Creates new printing flags with defaults, intended for customization.
543/// Must be freed with a call to mlirOpPrintingFlagsDestroy().
544MLIR_CAPI_EXPORTED MlirOpPrintingFlags mlirOpPrintingFlagsCreate(void);
545
546/// Destroys printing flags created with mlirOpPrintingFlagsCreate.
547MLIR_CAPI_EXPORTED void mlirOpPrintingFlagsDestroy(MlirOpPrintingFlags flags);
548
549/// Enables the elision of large elements attributes by printing a lexically
550/// valid but otherwise meaningless form instead of the element data. The
551/// `largeElementLimit` is used to configure what is considered to be a "large"
552/// ElementsAttr by providing an upper limit to the number of elements.
553MLIR_CAPI_EXPORTED void
554mlirOpPrintingFlagsElideLargeElementsAttrs(MlirOpPrintingFlags flags,
555 intptr_t largeElementLimit);
556
557/// Enables the elision of large resources strings by omitting them from the
558/// `dialect_resources` section. The `largeResourceLimit` is used to configure
559/// what is considered to be a "large" resource by providing an upper limit to
560/// the string size.
561MLIR_CAPI_EXPORTED void
562mlirOpPrintingFlagsElideLargeResourceString(MlirOpPrintingFlags flags,
563 intptr_t largeResourceLimit);
564
565/// Enable or disable printing of debug information (based on `enable`). If
566/// 'prettyForm' is set to true, debug information is printed in a more readable
567/// 'pretty' form. Note: The IR generated with 'prettyForm' is not parsable.
568MLIR_CAPI_EXPORTED void
569mlirOpPrintingFlagsEnableDebugInfo(MlirOpPrintingFlags flags, bool enable,
570 bool prettyForm);
571
572/// Always print operations in the generic form.
573MLIR_CAPI_EXPORTED void
574mlirOpPrintingFlagsPrintGenericOpForm(MlirOpPrintingFlags flags);
575
576/// Print the name and location, if NamedLoc, as a prefix to the SSA ID.
577MLIR_CAPI_EXPORTED void
578mlirOpPrintingFlagsPrintNameLocAsPrefix(MlirOpPrintingFlags flags);
579
580/// Use local scope when printing the operation. This allows for using the
581/// printer in a more localized and thread-safe setting, but may not
582/// necessarily be identical to what the IR will look like when dumping
583/// the full module.
584MLIR_CAPI_EXPORTED void
585mlirOpPrintingFlagsUseLocalScope(MlirOpPrintingFlags flags);
586
587/// Do not verify the operation when using custom operation printers.
588MLIR_CAPI_EXPORTED void
589mlirOpPrintingFlagsAssumeVerified(MlirOpPrintingFlags flags);
590
591/// Skip printing regions.
592MLIR_CAPI_EXPORTED void
593mlirOpPrintingFlagsSkipRegions(MlirOpPrintingFlags flags);
594
595//===----------------------------------------------------------------------===//
596// Bytecode printing flags API.
597//===----------------------------------------------------------------------===//
598
599/// Creates new printing flags with defaults, intended for customization.
600/// Must be freed with a call to mlirBytecodeWriterConfigDestroy().
601MLIR_CAPI_EXPORTED MlirBytecodeWriterConfig
602mlirBytecodeWriterConfigCreate(void);
603
604/// Destroys printing flags created with mlirBytecodeWriterConfigCreate.
605MLIR_CAPI_EXPORTED void
606mlirBytecodeWriterConfigDestroy(MlirBytecodeWriterConfig config);
607
608/// Sets the version to emit in the writer config.
609MLIR_CAPI_EXPORTED void
610mlirBytecodeWriterConfigDesiredEmitVersion(MlirBytecodeWriterConfig flags,
611 int64_t version);
612
613//===----------------------------------------------------------------------===//
614// Operation API.
615//===----------------------------------------------------------------------===//
616
617/// Creates an operation and transfers ownership to the caller.
618/// Note that caller owned child objects are transferred in this call and must
619/// not be further used. Particularly, this applies to any regions added to
620/// the state (the implementation may invalidate any such pointers).
621///
622/// This call can fail under the following conditions, in which case, it will
623/// return a null operation and emit diagnostics:
624/// - Result type inference is enabled and cannot be performed.
625MLIR_CAPI_EXPORTED MlirOperation mlirOperationCreate(MlirOperationState *state);
626
627/// Parses an operation, giving ownership to the caller. If parsing fails a null
628/// operation will be returned, and an error diagnostic emitted.
629///
630/// `sourceStr` may be either the text assembly format, or binary bytecode
631/// format. `sourceName` is used as the file name of the source; any IR without
632/// locations will get a `FileLineColLoc` location with `sourceName` as the file
633/// name.
634MLIR_CAPI_EXPORTED MlirOperation mlirOperationCreateParse(
635 MlirContext context, MlirStringRef sourceStr, MlirStringRef sourceName);
636
637/// Creates a deep copy of an operation. The operation is not inserted and
638/// ownership is transferred to the caller.
639MLIR_CAPI_EXPORTED MlirOperation mlirOperationClone(MlirOperation op);
640
641/// Takes an operation owned by the caller and destroys it.
642MLIR_CAPI_EXPORTED void mlirOperationDestroy(MlirOperation op);
643
644/// Removes the given operation from its parent block. The operation is not
645/// destroyed. The ownership of the operation is transferred to the caller.
646MLIR_CAPI_EXPORTED void mlirOperationRemoveFromParent(MlirOperation op);
647
648/// Checks whether the underlying operation is null.
649static inline bool mlirOperationIsNull(MlirOperation op) { return !op.ptr; }
650
651/// Checks whether two operation handles point to the same operation. This does
652/// not perform deep comparison.
653MLIR_CAPI_EXPORTED bool mlirOperationEqual(MlirOperation op,
654 MlirOperation other);
655
656/// Compute a hash for the given operation. Operand and result SSA values are
657/// hashed by identity and locations are significant, so equivalent-but-distinct
658/// operations hash differently; use mlirOperationStructuralHashValue for a hash
659/// that pairs with mlirOperationIsStructurallyEquivalent.
660MLIR_CAPI_EXPORTED size_t mlirOperationHashValue(MlirOperation op);
661
662/// Flags controlling structural operation equivalence and hashing. These mirror
663/// `mlir::OperationEquivalence::Flags` and may be combined with bitwise OR.
664typedef enum MlirOperationEquivalenceFlags {
665 /// No flags: locations, discardable attributes, properties and
666 /// commutativity are all significant.
667 MLIR_OPERATION_EQUIVALENCE_NONE = 0,
668 /// Ignore the locations attached to operations.
669 MLIR_OPERATION_EQUIVALENCE_IGNORE_LOCATIONS = 1,
670 /// Ignore the discardable attributes attached to operations.
671 MLIR_OPERATION_EQUIVALENCE_IGNORE_DISCARDABLE_ATTRS = 2,
672 /// Ignore the properties attached to operations.
673 MLIR_OPERATION_EQUIVALENCE_IGNORE_PROPERTIES = 4,
674 /// Ignore commutativity, comparing operands in an order-sensitive way.
675 MLIR_OPERATION_EQUIVALENCE_IGNORE_COMMUTATIVITY = 8,
676} MlirOperationEquivalenceFlags;
677
678/// Checks whether two operations are structurally equivalent, i.e. they have
679/// the same name, attributes, operand and result types, and recursively
680/// equivalent regions. Operand equivalence is tracked structurally while
681/// recursing into regions, so operands defined inside the compared regions need
682/// not be the exact same SSA values; operands defined outside must be. `flags`
683/// is a bitwise OR of MlirOperationEquivalenceFlags values.
684MLIR_CAPI_EXPORTED bool mlirOperationIsStructurallyEquivalent(MlirOperation lhs,
685 MlirOperation rhs,
686 uint32_t flags);
687
688/// Computes a hash for the given operation that pairs with
689/// mlirOperationIsStructurallyEquivalent: two operations that are structurally
690/// equivalent under the same `flags` hash equally. Operands are hashed by
691/// identity, results are not hashed at all, and regions do not participate in
692/// the hash. `flags` is a bitwise OR of MlirOperationEquivalenceFlags values.
693MLIR_CAPI_EXPORTED size_t mlirOperationStructuralHashValue(MlirOperation op,
694 uint32_t flags);
695
696/// Gets the context this operation is associated with
697MLIR_CAPI_EXPORTED MlirContext mlirOperationGetContext(MlirOperation op);
698
699/// Checks if the operation name has a trait identified by the given type id.
700MLIR_CAPI_EXPORTED bool mlirOperationNameHasTrait(MlirStringRef opName,
701 MlirTypeID traitTypeID,
702 MlirContext context);
703
704/// Gets the location of the operation.
705MLIR_CAPI_EXPORTED MlirLocation mlirOperationGetLocation(MlirOperation op);
706
707/// Sets the location of the operation.
708MLIR_CAPI_EXPORTED void mlirOperationSetLocation(MlirOperation op,
709 MlirLocation loc);
710
711/// Gets the type id of the operation.
712/// Returns null if the operation does not have a registered operation
713/// description.
714MLIR_CAPI_EXPORTED MlirTypeID mlirOperationGetTypeID(MlirOperation op);
715
716/// Gets the name of the operation as an identifier.
717MLIR_CAPI_EXPORTED MlirIdentifier mlirOperationGetName(MlirOperation op);
718
719/// Gets the block that owns this operation, returning null if the operation is
720/// not owned.
721MLIR_CAPI_EXPORTED MlirBlock mlirOperationGetBlock(MlirOperation op);
722
723/// Gets the operation that owns this operation, returning null if the operation
724/// is not owned.
725MLIR_CAPI_EXPORTED MlirOperation
726mlirOperationGetParentOperation(MlirOperation op);
727
728/// Returns true if `a` is an ancestor of `b`, i.e. `a` contains `b` or
729/// `a == b`.
730MLIR_CAPI_EXPORTED bool mlirOperationIsAncestor(MlirOperation a,
731 MlirOperation b);
732
733/// Returns true if `a` is a proper ancestor of `b`, i.e. `a` contains `b` but
734/// `a != b`.
735MLIR_CAPI_EXPORTED bool mlirOperationIsProperAncestor(MlirOperation a,
736 MlirOperation b);
737
738/// Returns the number of regions attached to the given operation.
739MLIR_CAPI_EXPORTED intptr_t mlirOperationGetNumRegions(MlirOperation op);
740
741/// Returns `pos`-th region attached to the operation.
742MLIR_CAPI_EXPORTED MlirRegion mlirOperationGetRegion(MlirOperation op,
743 intptr_t pos);
744
745/// Returns an operation immediately following the given operation it its
746/// enclosing block.
747MLIR_CAPI_EXPORTED MlirOperation mlirOperationGetNextInBlock(MlirOperation op);
748
749/// Returns the number of operands of the operation.
750MLIR_CAPI_EXPORTED intptr_t mlirOperationGetNumOperands(MlirOperation op);
751
752/// Returns `pos`-th operand of the operation.
753MLIR_CAPI_EXPORTED MlirValue mlirOperationGetOperand(MlirOperation op,
754 intptr_t pos);
755
756/// Returns `pos`-th OpOperand of the operation.
757MLIR_CAPI_EXPORTED MlirOpOperand mlirOperationGetOpOperand(MlirOperation op,
758 intptr_t pos);
759
760/// Sets the `pos`-th operand of the operation.
761MLIR_CAPI_EXPORTED void mlirOperationSetOperand(MlirOperation op, intptr_t pos,
762 MlirValue newValue);
763
764/// Replaces the operands of the operation.
765MLIR_CAPI_EXPORTED void mlirOperationSetOperands(MlirOperation op,
766 intptr_t nOperands,
767 MlirValue const *operands);
768
769/// Returns the number of results of the operation.
770MLIR_CAPI_EXPORTED intptr_t mlirOperationGetNumResults(MlirOperation op);
771
772/// Returns `pos`-th result of the operation.
773MLIR_CAPI_EXPORTED MlirValue mlirOperationGetResult(MlirOperation op,
774 intptr_t pos);
775
776/// Returns the number of successor blocks of the operation.
777MLIR_CAPI_EXPORTED intptr_t mlirOperationGetNumSuccessors(MlirOperation op);
778
779/// Returns `pos`-th successor of the operation.
780MLIR_CAPI_EXPORTED MlirBlock mlirOperationGetSuccessor(MlirOperation op,
781 intptr_t pos);
782
783/// Set `pos`-th successor of the operation.
784MLIR_CAPI_EXPORTED void
785mlirOperationSetSuccessor(MlirOperation op, intptr_t pos, MlirBlock block);
786
787/// Returns true if this operation defines an inherent attribute with this name.
788/// Note: the attribute can be optional, so
789/// `mlirOperationGetInherentAttributeByName` can still return a null attribute.
790MLIR_CAPI_EXPORTED bool
791mlirOperationHasInherentAttributeByName(MlirOperation op, MlirStringRef name);
792
793/// Returns an inherent attribute attached to the operation given its name.
794MLIR_CAPI_EXPORTED MlirAttribute
795mlirOperationGetInherentAttributeByName(MlirOperation op, MlirStringRef name);
796
797/// Sets an inherent attribute by name, replacing the existing if it exists.
798/// This has no effect if "name" does not match an inherent attribute.
799MLIR_CAPI_EXPORTED void
800mlirOperationSetInherentAttributeByName(MlirOperation op, MlirStringRef name,
801 MlirAttribute attr);
802
803/// Returns the number of discardable attributes attached to the operation.
804MLIR_CAPI_EXPORTED intptr_t
805mlirOperationGetNumDiscardableAttributes(MlirOperation op);
806
807/// Return `pos`-th discardable attribute of the operation.
808MLIR_CAPI_EXPORTED MlirNamedAttribute
809mlirOperationGetDiscardableAttribute(MlirOperation op, intptr_t pos);
810
811/// Returns a discardable attribute attached to the operation given its name.
812MLIR_CAPI_EXPORTED MlirAttribute mlirOperationGetDiscardableAttributeByName(
813 MlirOperation op, MlirStringRef name);
814
815/// Sets a discardable attribute by name, replacing the existing if it exists or
816/// adding a new one otherwise. The new `attr` Attribute is not allowed to be
817/// null, use `mlirOperationRemoveDiscardableAttributeByName` to remove an
818/// Attribute instead.
819MLIR_CAPI_EXPORTED void
820mlirOperationSetDiscardableAttributeByName(MlirOperation op, MlirStringRef name,
821 MlirAttribute attr);
822
823/// Removes a discardable attribute by name. Returns false if the attribute was
824/// not found and true if removed.
825MLIR_CAPI_EXPORTED bool
826mlirOperationRemoveDiscardableAttributeByName(MlirOperation op,
827 MlirStringRef name);
828
829/// Returns the number of attributes attached to the operation.
830/// Deprecated, please use `mlirOperationGetNumInherentAttributes` or
831/// `mlirOperationGetNumDiscardableAttributes`.
832MLIR_CAPI_EXPORTED intptr_t mlirOperationGetNumAttributes(MlirOperation op);
833
834/// Return `pos`-th attribute of the operation.
835/// Deprecated, please use `mlirOperationGetInherentAttribute` or
836/// `mlirOperationGetDiscardableAttribute`.
837MLIR_CAPI_EXPORTED MlirNamedAttribute
838mlirOperationGetAttribute(MlirOperation op, intptr_t pos);
839
840/// Returns an attribute attached to the operation given its name.
841/// Deprecated, please use `mlirOperationGetInherentAttributeByName` or
842/// `mlirOperationGetDiscardableAttributeByName`.
843MLIR_CAPI_EXPORTED MlirAttribute
844mlirOperationGetAttributeByName(MlirOperation op, MlirStringRef name);
845
846/// Sets an attribute by name, replacing the existing if it exists or
847/// adding a new one otherwise.
848/// Deprecated, please use `mlirOperationSetInherentAttributeByName` or
849/// `mlirOperationSetDiscardableAttributeByName`.
850MLIR_CAPI_EXPORTED void mlirOperationSetAttributeByName(MlirOperation op,
851 MlirStringRef name,
852 MlirAttribute attr);
853
854/// Removes an attribute by name. Returns false if the attribute was not found
855/// and true if removed.
856/// Deprecated, please use `mlirOperationRemoveInherentAttributeByName` or
857/// `mlirOperationRemoveDiscardableAttributeByName`.
858MLIR_CAPI_EXPORTED bool mlirOperationRemoveAttributeByName(MlirOperation op,
859 MlirStringRef name);
860
861/// Prints an operation by sending chunks of the string representation and
862/// forwarding `userData to `callback`. Note that the callback may be called
863/// several times with consecutive chunks of the string.
864MLIR_CAPI_EXPORTED void mlirOperationPrint(MlirOperation op,
865 MlirStringCallback callback,
866 void *userData);
867
868/// Same as mlirOperationPrint but accepts flags controlling the printing
869/// behavior.
870MLIR_CAPI_EXPORTED void mlirOperationPrintWithFlags(MlirOperation op,
871 MlirOpPrintingFlags flags,
872 MlirStringCallback callback,
873 void *userData);
874
875/// Same as mlirOperationPrint but accepts AsmState controlling the printing
876/// behavior as well as caching computed names.
877MLIR_CAPI_EXPORTED void mlirOperationPrintWithState(MlirOperation op,
878 MlirAsmState state,
879 MlirStringCallback callback,
880 void *userData);
881
882/// Same as mlirOperationPrint but writing the bytecode format.
883MLIR_CAPI_EXPORTED void mlirOperationWriteBytecode(MlirOperation op,
884 MlirStringCallback callback,
885 void *userData);
886
887/// Same as mlirOperationWriteBytecode but with writer config and returns
888/// failure only if desired bytecode could not be honored.
889MLIR_CAPI_EXPORTED MlirLogicalResult mlirOperationWriteBytecodeWithConfig(
890 MlirOperation op, MlirBytecodeWriterConfig config,
891 MlirStringCallback callback, void *userData);
892
893/// Prints an operation to stderr.
894MLIR_CAPI_EXPORTED void mlirOperationDump(MlirOperation op);
895
896/// Verify the operation and return true if it passes, false if it fails.
897MLIR_CAPI_EXPORTED bool mlirOperationVerify(MlirOperation op);
898
899/// Moves the given operation immediately after the other operation in its
900/// parent block. The given operation may be owned by the caller or by its
901/// current block. The other operation must belong to a block. In any case, the
902/// ownership is transferred to the block of the other operation.
903MLIR_CAPI_EXPORTED void mlirOperationMoveAfter(MlirOperation op,
904 MlirOperation other);
905
906/// Moves the given operation immediately before the other operation in its
907/// parent block. The given operation may be owner by the caller or by its
908/// current block. The other operation must belong to a block. In any case, the
909/// ownership is transferred to the block of the other operation.
910MLIR_CAPI_EXPORTED void mlirOperationMoveBefore(MlirOperation op,
911 MlirOperation other);
912
913/// Given an operation 'other' that is within the same parent block, return
914/// whether the current operation is before 'other' in the operation list
915/// of the parent block.
916/// Note: This function has an average complexity of O(1), but worst case may
917/// take O(N) where N is the number of operations within the parent block.
918MLIR_CAPI_EXPORTED bool mlirOperationIsBeforeInBlock(MlirOperation op,
919 MlirOperation other);
920/// Operation walk result.
921typedef enum MlirWalkResult {
922 MlirWalkResultAdvance,
923 MlirWalkResultInterrupt,
924 MlirWalkResultSkip
925} MlirWalkResult;
926
927/// Traversal order for operation walk.
928typedef enum MlirWalkOrder {
929 MlirWalkPreOrder,
930 MlirWalkPostOrder
931} MlirWalkOrder;
932
933/// Operation walker type. The handler is passed an (opaque) reference to an
934/// operation and a pointer to a `userData`.
935typedef MlirWalkResult (*MlirOperationWalkCallback)(MlirOperation,
936 void *userData);
937
938/// Walks operation `op` in `walkOrder` and calls `callback` on that operation.
939/// `*userData` is passed to the callback as well and can be used to tunnel some
940/// context or other data into the callback.
941MLIR_CAPI_EXPORTED
942void mlirOperationWalk(MlirOperation op, MlirOperationWalkCallback callback,
943 void *userData, MlirWalkOrder walkOrder);
944
945/// Replace uses of 'of' value with the 'with' value inside the 'op' operation.
946MLIR_CAPI_EXPORTED void
947mlirOperationReplaceUsesOfWith(MlirOperation op, MlirValue of, MlirValue with);
948
949//===----------------------------------------------------------------------===//
950// Region API.
951//===----------------------------------------------------------------------===//
952
953/// Creates a new empty region and transfers ownership to the caller.
954MLIR_CAPI_EXPORTED MlirRegion mlirRegionCreate(void);
955
956/// Takes a region owned by the caller and destroys it.
957MLIR_CAPI_EXPORTED void mlirRegionDestroy(MlirRegion region);
958
959/// Checks whether a region is null.
960static inline bool mlirRegionIsNull(MlirRegion region) { return !region.ptr; }
961
962/// Checks whether two region handles point to the same region. This does not
963/// perform deep comparison.
964MLIR_CAPI_EXPORTED bool mlirRegionEqual(MlirRegion region, MlirRegion other);
965
966/// Gets the first block in the region.
967MLIR_CAPI_EXPORTED MlirBlock mlirRegionGetFirstBlock(MlirRegion region);
968
969/// Takes a block owned by the caller and appends it to the given region.
970MLIR_CAPI_EXPORTED void mlirRegionAppendOwnedBlock(MlirRegion region,
971 MlirBlock block);
972
973/// Takes a block owned by the caller and inserts it at `pos` to the given
974/// region. This is an expensive operation that linearly scans the region,
975/// prefer insertAfter/Before instead.
976MLIR_CAPI_EXPORTED void
977mlirRegionInsertOwnedBlock(MlirRegion region, intptr_t pos, MlirBlock block);
978
979/// Takes a block owned by the caller and inserts it after the (non-owned)
980/// reference block in the given region. The reference block must belong to the
981/// region. If the reference block is null, prepends the block to the region.
982MLIR_CAPI_EXPORTED void mlirRegionInsertOwnedBlockAfter(MlirRegion region,
983 MlirBlock reference,
984 MlirBlock block);
985
986/// Takes a block owned by the caller and inserts it before the (non-owned)
987/// reference block in the given region. The reference block must belong to the
988/// region. If the reference block is null, appends the block to the region.
989MLIR_CAPI_EXPORTED void mlirRegionInsertOwnedBlockBefore(MlirRegion region,
990 MlirBlock reference,
991 MlirBlock block);
992
993/// Returns first region attached to the operation.
994MLIR_CAPI_EXPORTED MlirRegion mlirOperationGetFirstRegion(MlirOperation op);
995
996/// Returns the region immediately following the given region in its parent
997/// operation.
998MLIR_CAPI_EXPORTED MlirRegion mlirRegionGetNextInOperation(MlirRegion region);
999
1000/// Moves the entire content of the source region to the target region.
1001MLIR_CAPI_EXPORTED void mlirRegionTakeBody(MlirRegion target,
1002 MlirRegion source);
1003
1004//===----------------------------------------------------------------------===//
1005// Block API.
1006//===----------------------------------------------------------------------===//
1007
1008/// Creates a new empty block with the given argument types and transfers
1009/// ownership to the caller.
1010MLIR_CAPI_EXPORTED MlirBlock mlirBlockCreate(intptr_t nArgs,
1011 MlirType const *args,
1012 MlirLocation const *locs);
1013
1014/// Takes a block owned by the caller and destroys it.
1015MLIR_CAPI_EXPORTED void mlirBlockDestroy(MlirBlock block);
1016
1017/// Detach a block from the owning region and assume ownership.
1018MLIR_CAPI_EXPORTED void mlirBlockDetach(MlirBlock block);
1019
1020/// Checks whether a block is null.
1021static inline bool mlirBlockIsNull(MlirBlock block) { return !block.ptr; }
1022
1023/// Checks whether two blocks handles point to the same block. This does not
1024/// perform deep comparison.
1025MLIR_CAPI_EXPORTED bool mlirBlockEqual(MlirBlock block, MlirBlock other);
1026
1027/// Returns the closest surrounding operation that contains this block.
1028MLIR_CAPI_EXPORTED MlirOperation mlirBlockGetParentOperation(MlirBlock);
1029
1030/// Returns the region that contains this block.
1031MLIR_CAPI_EXPORTED MlirRegion mlirBlockGetParentRegion(MlirBlock block);
1032
1033/// Returns the block immediately following the given block in its parent
1034/// region.
1035MLIR_CAPI_EXPORTED MlirBlock mlirBlockGetNextInRegion(MlirBlock block);
1036
1037/// Returns the first operation in the block.
1038MLIR_CAPI_EXPORTED MlirOperation mlirBlockGetFirstOperation(MlirBlock block);
1039
1040/// Returns the terminator operation in the block or null if no terminator.
1041MLIR_CAPI_EXPORTED MlirOperation mlirBlockGetTerminator(MlirBlock block);
1042
1043/// Takes an operation owned by the caller and appends it to the block.
1044MLIR_CAPI_EXPORTED void mlirBlockAppendOwnedOperation(MlirBlock block,
1045 MlirOperation operation);
1046
1047/// Takes an operation owned by the caller and inserts it as `pos` to the block.
1048/// This is an expensive operation that scans the block linearly, prefer
1049/// insertBefore/After instead.
1050MLIR_CAPI_EXPORTED void mlirBlockInsertOwnedOperation(MlirBlock block,
1051 intptr_t pos,
1052 MlirOperation operation);
1053
1054/// Takes an operation owned by the caller and inserts it after the (non-owned)
1055/// reference operation in the given block. If the reference is null, prepends
1056/// the operation. Otherwise, the reference must belong to the block.
1057MLIR_CAPI_EXPORTED void
1058mlirBlockInsertOwnedOperationAfter(MlirBlock block, MlirOperation reference,
1059 MlirOperation operation);
1060
1061/// Takes an operation owned by the caller and inserts it before the (non-owned)
1062/// reference operation in the given block. If the reference is null, appends
1063/// the operation. Otherwise, the reference must belong to the block.
1064MLIR_CAPI_EXPORTED void
1065mlirBlockInsertOwnedOperationBefore(MlirBlock block, MlirOperation reference,
1066 MlirOperation operation);
1067
1068/// Returns the number of arguments of the block.
1069MLIR_CAPI_EXPORTED intptr_t mlirBlockGetNumArguments(MlirBlock block);
1070
1071/// Appends an argument of the specified type to the block. Returns the newly
1072/// added argument.
1073MLIR_CAPI_EXPORTED MlirValue mlirBlockAddArgument(MlirBlock block,
1074 MlirType type,
1075 MlirLocation loc);
1076
1077/// Erase the argument at 'index' and remove it from the argument list.
1078MLIR_CAPI_EXPORTED void mlirBlockEraseArgument(MlirBlock block, unsigned index);
1079
1080/// Inserts an argument of the specified type at a specified index to the block.
1081/// Returns the newly added argument.
1082MLIR_CAPI_EXPORTED MlirValue mlirBlockInsertArgument(MlirBlock block,
1083 intptr_t pos,
1084 MlirType type,
1085 MlirLocation loc);
1086
1087/// Returns `pos`-th argument of the block.
1088MLIR_CAPI_EXPORTED MlirValue mlirBlockGetArgument(MlirBlock block,
1089 intptr_t pos);
1090
1091/// Prints a block by sending chunks of the string representation and
1092/// forwarding `userData to `callback`. Note that the callback may be called
1093/// several times with consecutive chunks of the string.
1094MLIR_CAPI_EXPORTED void
1095mlirBlockPrint(MlirBlock block, MlirStringCallback callback, void *userData);
1096
1097/// Returns the number of successor blocks of the block.
1098MLIR_CAPI_EXPORTED intptr_t mlirBlockGetNumSuccessors(MlirBlock block);
1099
1100/// Returns `pos`-th successor of the block.
1101MLIR_CAPI_EXPORTED MlirBlock mlirBlockGetSuccessor(MlirBlock block,
1102 intptr_t pos);
1103
1104/// Returns the number of predecessor blocks of the block.
1105MLIR_CAPI_EXPORTED intptr_t mlirBlockGetNumPredecessors(MlirBlock block);
1106
1107/// Returns `pos`-th predecessor of the block.
1108///
1109/// WARNING: This getter is more expensive than the others here because
1110/// the impl actually iterates the use-def chain (of block operands) anew for
1111/// each indexed access.
1112MLIR_CAPI_EXPORTED MlirBlock mlirBlockGetPredecessor(MlirBlock block,
1113 intptr_t pos);
1114
1115//===----------------------------------------------------------------------===//
1116// Value API.
1117//===----------------------------------------------------------------------===//
1118
1119/// Returns whether the value is null.
1120static inline bool mlirValueIsNull(MlirValue value) { return !value.ptr; }
1121
1122/// Returns 1 if two values are equal, 0 otherwise.
1123MLIR_CAPI_EXPORTED bool mlirValueEqual(MlirValue value1, MlirValue value2);
1124
1125/// Returns 1 if the value is a block argument, 0 otherwise.
1126MLIR_CAPI_EXPORTED bool mlirValueIsABlockArgument(MlirValue value);
1127
1128/// Returns 1 if the value is an operation result, 0 otherwise.
1129MLIR_CAPI_EXPORTED bool mlirValueIsAOpResult(MlirValue value);
1130
1131/// Returns the block in which this value is defined as an argument. Asserts if
1132/// the value is not a block argument.
1133MLIR_CAPI_EXPORTED MlirBlock mlirBlockArgumentGetOwner(MlirValue value);
1134
1135/// Returns the position of the value in the argument list of its block.
1136MLIR_CAPI_EXPORTED intptr_t mlirBlockArgumentGetArgNumber(MlirValue value);
1137
1138/// Sets the type of the block argument to the given type.
1139MLIR_CAPI_EXPORTED void mlirBlockArgumentSetType(MlirValue value,
1140 MlirType type);
1141
1142/// Sets the location of the block argument to the given location.
1143MLIR_CAPI_EXPORTED void mlirBlockArgumentSetLocation(MlirValue value,
1144 MlirLocation loc);
1145
1146/// Returns an operation that produced this value as its result. Asserts if the
1147/// value is not an op result.
1148MLIR_CAPI_EXPORTED MlirOperation mlirOpResultGetOwner(MlirValue value);
1149
1150/// Returns the position of the value in the list of results of the operation
1151/// that produced it.
1152MLIR_CAPI_EXPORTED intptr_t mlirOpResultGetResultNumber(MlirValue value);
1153
1154/// Returns the type of the value.
1155MLIR_CAPI_EXPORTED MlirType mlirValueGetType(MlirValue value);
1156
1157/// Set the type of the value.
1158MLIR_CAPI_EXPORTED void mlirValueSetType(MlirValue value, MlirType type);
1159
1160/// Prints the value to the standard error stream.
1161MLIR_CAPI_EXPORTED void mlirValueDump(MlirValue value);
1162
1163/// Prints a value by sending chunks of the string representation and
1164/// forwarding `userData to `callback`. Note that the callback may be called
1165/// several times with consecutive chunks of the string.
1166MLIR_CAPI_EXPORTED void
1167mlirValuePrint(MlirValue value, MlirStringCallback callback, void *userData);
1168
1169/// Prints a value as an operand (i.e., the ValueID).
1170MLIR_CAPI_EXPORTED void mlirValuePrintAsOperand(MlirValue value,
1171 MlirAsmState state,
1172 MlirStringCallback callback,
1173 void *userData);
1174
1175/// Returns an op operand representing the first use of the value, or a null op
1176/// operand if there are no uses.
1177MLIR_CAPI_EXPORTED MlirOpOperand mlirValueGetFirstUse(MlirValue value);
1178
1179/// Replace all uses of 'of' value with the 'with' value, updating anything in
1180/// the IR that uses 'of' to use the other value instead. When this returns
1181/// there are zero uses of 'of'.
1182MLIR_CAPI_EXPORTED void mlirValueReplaceAllUsesOfWith(MlirValue of,
1183 MlirValue with);
1184
1185/// Replace all uses of 'of' value with 'with' value, updating anything in the
1186/// IR that uses 'of' to use 'with' instead, except if the user is listed in
1187/// 'exceptions'. The 'exceptions' parameter is an array of MlirOperation
1188/// pointers with a length of 'numExceptions'.
1189MLIR_CAPI_EXPORTED void
1190mlirValueReplaceAllUsesExcept(MlirValue of, MlirValue with,
1191 intptr_t numExceptions,
1192 MlirOperation *exceptions);
1193
1194/// Callback deciding whether a particular use should be replaced. It is passed
1195/// the use as an MlirOpOperand (from which the owner operation, operand number
1196/// and value can be queried) and the user-provided `userData`. Returns true to
1197/// replace this use.
1198typedef bool (*MlirOpOperandReplaceFilterCallback)(MlirOpOperand opOperand,
1199 void *userData);
1200
1201/// Replace uses of 'of' value with 'with' value, but only for the uses for
1202/// which the `filter` callback returns true. `filter` must not be NULL; this is
1203/// only checked by an assertion, i.e. in builds with assertions enabled.
1204MLIR_CAPI_EXPORTED void
1205mlirValueReplaceUsesWithIf(MlirValue of, MlirValue with,
1206 MlirOpOperandReplaceFilterCallback filter,
1207 void *userData);
1208
1209/// Gets the location of the value.
1210MLIR_CAPI_EXPORTED MlirLocation mlirValueGetLocation(MlirValue v);
1211
1212/// Gets the context that a value was created with.
1213MLIR_CAPI_EXPORTED MlirContext mlirValueGetContext(MlirValue v);
1214
1215//===----------------------------------------------------------------------===//
1216// OpOperand API.
1217//===----------------------------------------------------------------------===//
1218
1219/// Returns whether the op operand is null.
1220MLIR_CAPI_EXPORTED bool mlirOpOperandIsNull(MlirOpOperand opOperand);
1221
1222/// Returns the value of an op operand.
1223MLIR_CAPI_EXPORTED MlirValue mlirOpOperandGetValue(MlirOpOperand opOperand);
1224
1225/// Returns the owner operation of an op operand.
1226MLIR_CAPI_EXPORTED MlirOperation mlirOpOperandGetOwner(MlirOpOperand opOperand);
1227
1228/// Returns the operand number of an op operand.
1229MLIR_CAPI_EXPORTED unsigned
1230mlirOpOperandGetOperandNumber(MlirOpOperand opOperand);
1231
1232/// Returns an op operand representing the next use of the value, or a null op
1233/// operand if there is no next use.
1234MLIR_CAPI_EXPORTED MlirOpOperand
1235mlirOpOperandGetNextUse(MlirOpOperand opOperand);
1236
1237//===----------------------------------------------------------------------===//
1238// Type API.
1239//===----------------------------------------------------------------------===//
1240
1241/// Parses a type. The type is owned by the context.
1242MLIR_CAPI_EXPORTED MlirType mlirTypeParseGet(MlirContext context,
1243 MlirStringRef type);
1244
1245/// Gets the context that a type was created with.
1246MLIR_CAPI_EXPORTED MlirContext mlirTypeGetContext(MlirType type);
1247
1248/// Gets the type ID of the type.
1249MLIR_CAPI_EXPORTED MlirTypeID mlirTypeGetTypeID(MlirType type);
1250
1251/// Gets the dialect a type belongs to.
1252MLIR_CAPI_EXPORTED MlirDialect mlirTypeGetDialect(MlirType type);
1253
1254/// Checks whether a type is null.
1255static inline bool mlirTypeIsNull(MlirType type) { return !type.ptr; }
1256
1257/// Checks if two types are equal.
1258MLIR_CAPI_EXPORTED bool mlirTypeEqual(MlirType t1, MlirType t2);
1259
1260/// Prints a location by sending chunks of the string representation and
1261/// forwarding `userData to `callback`. Note that the callback may be called
1262/// several times with consecutive chunks of the string.
1263MLIR_CAPI_EXPORTED void
1264mlirTypePrint(MlirType type, MlirStringCallback callback, void *userData);
1265
1266/// Prints the type to the standard error stream.
1267MLIR_CAPI_EXPORTED void mlirTypeDump(MlirType type);
1268
1269//===----------------------------------------------------------------------===//
1270// Attribute API.
1271//===----------------------------------------------------------------------===//
1272
1273/// Parses an attribute. The attribute is owned by the context.
1274MLIR_CAPI_EXPORTED MlirAttribute mlirAttributeParseGet(MlirContext context,
1275 MlirStringRef attr);
1276
1277/// Gets the context that an attribute was created with.
1278MLIR_CAPI_EXPORTED MlirContext mlirAttributeGetContext(MlirAttribute attribute);
1279
1280/// Gets the type of this attribute.
1281MLIR_CAPI_EXPORTED MlirType mlirAttributeGetType(MlirAttribute attribute);
1282
1283/// Gets the type id of the attribute.
1284MLIR_CAPI_EXPORTED MlirTypeID mlirAttributeGetTypeID(MlirAttribute attribute);
1285
1286/// Gets the dialect of the attribute.
1287MLIR_CAPI_EXPORTED MlirDialect mlirAttributeGetDialect(MlirAttribute attribute);
1288
1289/// Checks whether an attribute is null.
1290static inline bool mlirAttributeIsNull(MlirAttribute attr) { return !attr.ptr; }
1291
1292/// Checks if two attributes are equal.
1293MLIR_CAPI_EXPORTED bool mlirAttributeEqual(MlirAttribute a1, MlirAttribute a2);
1294
1295/// Prints an attribute by sending chunks of the string representation and
1296/// forwarding `userData to `callback`. Note that the callback may be called
1297/// several times with consecutive chunks of the string.
1298MLIR_CAPI_EXPORTED void mlirAttributePrint(MlirAttribute attr,
1299 MlirStringCallback callback,
1300 void *userData);
1301
1302/// Prints the attribute to the standard error stream.
1303MLIR_CAPI_EXPORTED void mlirAttributeDump(MlirAttribute attr);
1304
1305/// Associates an attribute with the name. Takes ownership of neither.
1306MLIR_CAPI_EXPORTED MlirNamedAttribute mlirNamedAttributeGet(MlirIdentifier name,
1307 MlirAttribute attr);
1308
1309//===----------------------------------------------------------------------===//
1310// Identifier API.
1311//===----------------------------------------------------------------------===//
1312
1313/// Gets an identifier with the given string value.
1314MLIR_CAPI_EXPORTED MlirIdentifier mlirIdentifierGet(MlirContext context,
1315 MlirStringRef str);
1316
1317/// Returns the context associated with this identifier
1318MLIR_CAPI_EXPORTED MlirContext mlirIdentifierGetContext(MlirIdentifier);
1319
1320/// Checks whether two identifiers are the same.
1321MLIR_CAPI_EXPORTED bool mlirIdentifierEqual(MlirIdentifier ident,
1322 MlirIdentifier other);
1323
1324/// Gets the string value of the identifier.
1325MLIR_CAPI_EXPORTED MlirStringRef mlirIdentifierStr(MlirIdentifier ident);
1326
1327//===----------------------------------------------------------------------===//
1328// Symbol and SymbolTable API.
1329//===----------------------------------------------------------------------===//
1330
1331/// Returns the name of the attribute used to store symbol names compatible with
1332/// symbol tables.
1333MLIR_CAPI_EXPORTED MlirStringRef mlirSymbolTableGetSymbolAttributeName(void);
1334
1335/// Returns the name of the attribute used by default to store symbol
1336/// visibility.
1337MLIR_CAPI_EXPORTED MlirStringRef
1338mlirSymbolTableGetDefaultVisibilityAttributeName(void);
1339
1340/// Creates a symbol table for the given operation. If the operation does not
1341/// have the SymbolTable trait, returns a null symbol table.
1342MLIR_CAPI_EXPORTED MlirSymbolTable
1343mlirSymbolTableCreate(MlirOperation operation);
1344
1345/// Returns true if the symbol table is null.
1346static inline bool mlirSymbolTableIsNull(MlirSymbolTable symbolTable) {
1347 return !symbolTable.ptr;
1348}
1349
1350/// Destroys the symbol table created with mlirSymbolTableCreate. This does not
1351/// affect the operations in the table.
1352MLIR_CAPI_EXPORTED void mlirSymbolTableDestroy(MlirSymbolTable symbolTable);
1353
1354/// Looks up a symbol with the given name in the given symbol table and returns
1355/// the operation that corresponds to the symbol. If the symbol cannot be found,
1356/// returns a null operation.
1357MLIR_CAPI_EXPORTED MlirOperation
1358mlirSymbolTableLookup(MlirSymbolTable symbolTable, MlirStringRef name);
1359
1360/// Inserts the given operation into the given symbol table. The operation must
1361/// have the symbol trait. If the symbol table already has a symbol with the
1362/// same name, renames the symbol being inserted to ensure name uniqueness. Note
1363/// that this does not move the operation itself into the block of the symbol
1364/// table operation, this should be done separately. Returns the name of the
1365/// symbol after insertion.
1366MLIR_CAPI_EXPORTED MlirAttribute
1367mlirSymbolTableInsert(MlirSymbolTable symbolTable, MlirOperation operation);
1368
1369/// Removes the given operation from the symbol table and erases it.
1370MLIR_CAPI_EXPORTED void mlirSymbolTableErase(MlirSymbolTable symbolTable,
1371 MlirOperation operation);
1372
1373/// Attempt to replace all uses that are nested within the given operation
1374/// of the given symbol 'oldSymbol' with the provided 'newSymbol'. This does
1375/// not traverse into nested symbol tables. Will fail atomically if there are
1376/// any unknown operations that may be potential symbol tables.
1377MLIR_CAPI_EXPORTED MlirLogicalResult mlirSymbolTableReplaceAllSymbolUses(
1378 MlirStringRef oldSymbol, MlirStringRef newSymbol, MlirOperation from);
1379
1380/// Walks all symbol table operations nested within, and including, `op`. For
1381/// each symbol table operation, the provided callback is invoked with the op
1382/// and a boolean signifying if the symbols within that symbol table can be
1383/// treated as if all uses within the IR are visible to the caller.
1384/// `allSymUsesVisible` identifies whether all of the symbol uses of symbols
1385/// within `op` are visible.
1386MLIR_CAPI_EXPORTED void mlirSymbolTableWalkSymbolTables(
1387 MlirOperation from, bool allSymUsesVisible,
1388 void (*callback)(MlirOperation, bool, void *userData), void *userData);
1389
1390//===----------------------------------------------------------------------===//
1391// IRMapping API
1392//===----------------------------------------------------------------------===//
1393
1394/// Creates a new empty IRMapping.
1395MLIR_CAPI_EXPORTED MlirIRMapping mlirIRMappingCreate(void);
1396
1397/// Destroys the given IRMapping.
1398MLIR_CAPI_EXPORTED void mlirIRMappingDestroy(MlirIRMapping mapping);
1399
1400/// Checks whether an IRMapping is null.
1401static inline bool mlirIRMappingIsNull(MlirIRMapping mapping) {
1402 return !mapping.ptr;
1403}
1404
1405/// Maps a Value in the mapping.
1406MLIR_CAPI_EXPORTED void mlirIRMappingMapValue(MlirIRMapping mapping,
1407 MlirValue from, MlirValue to);
1408
1409/// Maps a Block in the mapping.
1410MLIR_CAPI_EXPORTED void mlirIRMappingMapBlock(MlirIRMapping mapping,
1411 MlirBlock from, MlirBlock to);
1412
1413/// Maps an Operation in the mapping.
1414MLIR_CAPI_EXPORTED void mlirIRMappingMapOperation(MlirIRMapping mapping,
1415 MlirOperation from,
1416 MlirOperation to);
1417
1418/// Clears all mappings.
1419MLIR_CAPI_EXPORTED void mlirIRMappingClear(MlirIRMapping mapping);
1420
1421/// Looks up a mapped Value. Returns the mapped value, or the input value if
1422/// no mapping exists.
1423MLIR_CAPI_EXPORTED MlirValue
1424mlirIRMappingLookupOrDefaultValue(MlirIRMapping mapping, MlirValue from);
1425
1426/// Looks up a mapped Value. Returns a null MlirValue if no mapping exists.
1427MLIR_CAPI_EXPORTED MlirValue
1428mlirIRMappingLookupOrNullValue(MlirIRMapping mapping, MlirValue from);
1429
1430/// Looks up a mapped Block. Returns the mapped block, or the input block if
1431/// no mapping exists.
1432MLIR_CAPI_EXPORTED MlirBlock
1433mlirIRMappingLookupOrDefaultBlock(MlirIRMapping mapping, MlirBlock from);
1434
1435/// Looks up a mapped Block. Returns a null MlirBlock if no mapping exists.
1436MLIR_CAPI_EXPORTED MlirBlock
1437mlirIRMappingLookupOrNullBlock(MlirIRMapping mapping, MlirBlock from);
1438
1439/// Looks up a mapped Operation. Returns the mapped operation, or the input
1440/// operation if no mapping exists.
1441MLIR_CAPI_EXPORTED MlirOperation mlirIRMappingLookupOrDefaultOperation(
1442 MlirIRMapping mapping, MlirOperation from);
1443
1444/// Looks up a mapped Operation. Returns a null MlirOperation if no mapping
1445/// exists.
1446MLIR_CAPI_EXPORTED MlirOperation
1447mlirIRMappingLookupOrNullOperation(MlirIRMapping mapping, MlirOperation from);
1448
1449/// Returns true if the mapping contains a mapping for the given value.
1450MLIR_CAPI_EXPORTED bool mlirIRMappingContainsValue(MlirIRMapping mapping,
1451 MlirValue value);
1452
1453/// Returns true if the mapping contains a mapping for the given block.
1454MLIR_CAPI_EXPORTED bool mlirIRMappingContainsBlock(MlirIRMapping mapping,
1455 MlirBlock block);
1456
1457/// Returns true if the mapping contains a mapping for the given operation.
1458MLIR_CAPI_EXPORTED bool mlirIRMappingContainsOperation(MlirIRMapping mapping,
1459 MlirOperation op);
1460
1461/// Erases a value mapping.
1462MLIR_CAPI_EXPORTED void mlirIRMappingEraseValue(MlirIRMapping mapping,
1463 MlirValue value);
1464
1465/// Erases a block mapping.
1466MLIR_CAPI_EXPORTED void mlirIRMappingEraseBlock(MlirIRMapping mapping,
1467 MlirBlock block);
1468
1469/// Erases an operation mapping.
1470MLIR_CAPI_EXPORTED void mlirIRMappingEraseOperation(MlirIRMapping mapping,
1471 MlirOperation op);
1472
1473/// Clones the operation with the given mapping. The mapping is updated with
1474/// the cloned operation's results and regions.
1475MLIR_CAPI_EXPORTED MlirOperation
1476mlirOperationCloneWithMapping(MlirOperation op, MlirIRMapping mapping);
1477
1478#ifdef __cplusplus
1479}
1480#endif
1481
1482#endif // MLIR_C_IR_H
1483