1 //===-- mlir-c/BuiltinAttributes.h - C API for Builtin Attributes -*- 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 Builtin attributes.
11 //
12 //===----------------------------------------------------------------------===//
13 
14 #ifndef MLIR_C_BUILTINATTRIBUTES_H
15 #define MLIR_C_BUILTINATTRIBUTES_H
16 
17 #include "mlir-c/AffineMap.h"
18 #include "mlir-c/IR.h"
19 #include "mlir-c/Support.h"
20 
21 #ifdef __cplusplus
22 extern "C" {
23 #endif
24 
25 //===----------------------------------------------------------------------===//
26 // Affine map attribute.
27 //===----------------------------------------------------------------------===//
28 
29 /// Checks whether the given attribute is an affine map attribute.
30 MLIR_CAPI_EXPORTED bool mlirAttributeIsAAffineMap(MlirAttribute attr);
31 
32 /** Creates an affine map attribute wrapping the given map. The attribute
33  * belongs to the same context as the affine map. */
34 MLIR_CAPI_EXPORTED MlirAttribute mlirAffineMapAttrGet(MlirAffineMap map);
35 
36 /// Returns the affine map wrapped in the given affine map attribute.
37 MLIR_CAPI_EXPORTED MlirAffineMap mlirAffineMapAttrGetValue(MlirAttribute attr);
38 
39 //===----------------------------------------------------------------------===//
40 // Array attribute.
41 //===----------------------------------------------------------------------===//
42 
43 /// Checks whether the given attribute is an array attribute.
44 MLIR_CAPI_EXPORTED bool mlirAttributeIsAArray(MlirAttribute attr);
45 
46 /** Creates an array element containing the given list of elements in the given
47  * context. */
48 MLIR_CAPI_EXPORTED MlirAttribute mlirArrayAttrGet(
49     MlirContext ctx, intptr_t numElements, MlirAttribute const *elements);
50 
51 /// Returns the number of elements stored in the given array attribute.
52 MLIR_CAPI_EXPORTED intptr_t mlirArrayAttrGetNumElements(MlirAttribute attr);
53 
54 /// Returns pos-th element stored in the given array attribute.
55 MLIR_CAPI_EXPORTED MlirAttribute mlirArrayAttrGetElement(MlirAttribute attr,
56                                                          intptr_t pos);
57 
58 //===----------------------------------------------------------------------===//
59 // Dictionary attribute.
60 //===----------------------------------------------------------------------===//
61 
62 /// Checks whether the given attribute is a dictionary attribute.
63 MLIR_CAPI_EXPORTED bool mlirAttributeIsADictionary(MlirAttribute attr);
64 
65 /** Creates a dictionary attribute containing the given list of elements in the
66  * provided context. */
67 MLIR_CAPI_EXPORTED MlirAttribute mlirDictionaryAttrGet(
68     MlirContext ctx, intptr_t numElements, MlirNamedAttribute const *elements);
69 
70 /// Returns the number of attributes contained in a dictionary attribute.
71 MLIR_CAPI_EXPORTED intptr_t
72 mlirDictionaryAttrGetNumElements(MlirAttribute attr);
73 
74 /// Returns pos-th element of the given dictionary attribute.
75 MLIR_CAPI_EXPORTED MlirNamedAttribute
76 mlirDictionaryAttrGetElement(MlirAttribute attr, intptr_t pos);
77 
78 /** Returns the dictionary attribute element with the given name or NULL if the
79  * given name does not exist in the dictionary. */
80 MLIR_CAPI_EXPORTED MlirAttribute
81 mlirDictionaryAttrGetElementByName(MlirAttribute attr, MlirStringRef name);
82 
83 //===----------------------------------------------------------------------===//
84 // Floating point attribute.
85 //===----------------------------------------------------------------------===//
86 
87 /* TODO: add support for APFloat and APInt to LLVM IR C API, then expose the
88  * relevant functions here. */
89 
90 /// Checks whether the given attribute is a floating point attribute.
91 MLIR_CAPI_EXPORTED bool mlirAttributeIsAFloat(MlirAttribute attr);
92 
93 /** Creates a floating point attribute in the given context with the given
94  * double value and double-precision FP semantics. */
95 MLIR_CAPI_EXPORTED MlirAttribute mlirFloatAttrDoubleGet(MlirContext ctx,
96                                                         MlirType type,
97                                                         double value);
98 
99 /** Same as "mlirFloatAttrDoubleGet", but if the type is not valid for a
100  * construction of a FloatAttr, returns a null MlirAttribute. */
101 MLIR_CAPI_EXPORTED MlirAttribute
102 mlirFloatAttrDoubleGetChecked(MlirType type, double value, MlirLocation loc);
103 
104 /** Returns the value stored in the given floating point attribute, interpreting
105  * the value as double. */
106 MLIR_CAPI_EXPORTED double mlirFloatAttrGetValueDouble(MlirAttribute attr);
107 
108 //===----------------------------------------------------------------------===//
109 // Integer attribute.
110 //===----------------------------------------------------------------------===//
111 
112 /* TODO: add support for APFloat and APInt to LLVM IR C API, then expose the
113  * relevant functions here. */
114 
115 /// Checks whether the given attribute is an integer attribute.
116 MLIR_CAPI_EXPORTED bool mlirAttributeIsAInteger(MlirAttribute attr);
117 
118 /** Creates an integer attribute of the given type with the given integer
119  * value. */
120 MLIR_CAPI_EXPORTED MlirAttribute mlirIntegerAttrGet(MlirType type,
121                                                     int64_t value);
122 
123 /** Returns the value stored in the given integer attribute, assuming the value
124  * fits into a 64-bit integer. */
125 MLIR_CAPI_EXPORTED int64_t mlirIntegerAttrGetValueInt(MlirAttribute attr);
126 
127 //===----------------------------------------------------------------------===//
128 // Bool attribute.
129 //===----------------------------------------------------------------------===//
130 
131 /// Checks whether the given attribute is a bool attribute.
132 MLIR_CAPI_EXPORTED bool mlirAttributeIsABool(MlirAttribute attr);
133 
134 /// Creates a bool attribute in the given context with the given value.
135 MLIR_CAPI_EXPORTED MlirAttribute mlirBoolAttrGet(MlirContext ctx, int value);
136 
137 /// Returns the value stored in the given bool attribute.
138 MLIR_CAPI_EXPORTED bool mlirBoolAttrGetValue(MlirAttribute attr);
139 
140 //===----------------------------------------------------------------------===//
141 // Integer set attribute.
142 //===----------------------------------------------------------------------===//
143 
144 /// Checks whether the given attribute is an integer set attribute.
145 MLIR_CAPI_EXPORTED bool mlirAttributeIsAIntegerSet(MlirAttribute attr);
146 
147 //===----------------------------------------------------------------------===//
148 // Opaque attribute.
149 //===----------------------------------------------------------------------===//
150 
151 /// Checks whether the given attribute is an opaque attribute.
152 MLIR_CAPI_EXPORTED bool mlirAttributeIsAOpaque(MlirAttribute attr);
153 
154 /** Creates an opaque attribute in the given context associated with the dialect
155  * identified by its namespace. The attribute contains opaque byte data of the
156  * specified length (data need not be null-terminated). */
157 MLIR_CAPI_EXPORTED MlirAttribute
158 mlirOpaqueAttrGet(MlirContext ctx, MlirStringRef dialectNamespace,
159                   intptr_t dataLength, const char *data, MlirType type);
160 
161 /** Returns the namespace of the dialect with which the given opaque attribute
162  * is associated. The namespace string is owned by the context. */
163 MLIR_CAPI_EXPORTED MlirStringRef
164 mlirOpaqueAttrGetDialectNamespace(MlirAttribute attr);
165 
166 /** Returns the raw data as a string reference. The data remains live as long as
167  * the context in which the attribute lives. */
168 MLIR_CAPI_EXPORTED MlirStringRef mlirOpaqueAttrGetData(MlirAttribute attr);
169 
170 //===----------------------------------------------------------------------===//
171 // String attribute.
172 //===----------------------------------------------------------------------===//
173 
174 /// Checks whether the given attribute is a string attribute.
175 MLIR_CAPI_EXPORTED bool mlirAttributeIsAString(MlirAttribute attr);
176 
177 /** Creates a string attribute in the given context containing the given string.
178  */
179 MLIR_CAPI_EXPORTED MlirAttribute mlirStringAttrGet(MlirContext ctx,
180                                                    MlirStringRef str);
181 
182 /** Creates a string attribute in the given context containing the given string.
183  * Additionally, the attribute has the given type. */
184 MLIR_CAPI_EXPORTED MlirAttribute mlirStringAttrTypedGet(MlirType type,
185                                                         MlirStringRef str);
186 
187 /** Returns the attribute values as a string reference. The data remains live as
188  * long as the context in which the attribute lives. */
189 MLIR_CAPI_EXPORTED MlirStringRef mlirStringAttrGetValue(MlirAttribute attr);
190 
191 //===----------------------------------------------------------------------===//
192 // SymbolRef attribute.
193 //===----------------------------------------------------------------------===//
194 
195 /// Checks whether the given attribute is a symbol reference attribute.
196 MLIR_CAPI_EXPORTED bool mlirAttributeIsASymbolRef(MlirAttribute attr);
197 
198 /** Creates a symbol reference attribute in the given context referencing a
199  * symbol identified by the given string inside a list of nested references.
200  * Each of the references in the list must not be nested. */
201 MLIR_CAPI_EXPORTED MlirAttribute
202 mlirSymbolRefAttrGet(MlirContext ctx, MlirStringRef symbol,
203                      intptr_t numReferences, MlirAttribute const *references);
204 
205 /** Returns the string reference to the root referenced symbol. The data remains
206  * live as long as the context in which the attribute lives. */
207 MLIR_CAPI_EXPORTED MlirStringRef
208 mlirSymbolRefAttrGetRootReference(MlirAttribute attr);
209 
210 /** Returns the string reference to the leaf referenced symbol. The data remains
211  * live as long as the context in which the attribute lives. */
212 MLIR_CAPI_EXPORTED MlirStringRef
213 mlirSymbolRefAttrGetLeafReference(MlirAttribute attr);
214 
215 /** Returns the number of references nested in the given symbol reference
216  * attribute. */
217 MLIR_CAPI_EXPORTED intptr_t
218 mlirSymbolRefAttrGetNumNestedReferences(MlirAttribute attr);
219 
220 /// Returns pos-th reference nested in the given symbol reference attribute.
221 MLIR_CAPI_EXPORTED MlirAttribute
222 mlirSymbolRefAttrGetNestedReference(MlirAttribute attr, intptr_t pos);
223 
224 //===----------------------------------------------------------------------===//
225 // Flat SymbolRef attribute.
226 //===----------------------------------------------------------------------===//
227 
228 /// Checks whether the given attribute is a flat symbol reference attribute.
229 MLIR_CAPI_EXPORTED bool mlirAttributeIsAFlatSymbolRef(MlirAttribute attr);
230 
231 /** Creates a flat symbol reference attribute in the given context referencing a
232  * symbol identified by the given string. */
233 MLIR_CAPI_EXPORTED MlirAttribute mlirFlatSymbolRefAttrGet(MlirContext ctx,
234                                                           MlirStringRef symbol);
235 
236 /** Returns the referenced symbol as a string reference. The data remains live
237  * as long as the context in which the attribute lives. */
238 MLIR_CAPI_EXPORTED MlirStringRef
239 mlirFlatSymbolRefAttrGetValue(MlirAttribute attr);
240 
241 //===----------------------------------------------------------------------===//
242 // Type attribute.
243 //===----------------------------------------------------------------------===//
244 
245 /// Checks whether the given attribute is a type attribute.
246 MLIR_CAPI_EXPORTED bool mlirAttributeIsAType(MlirAttribute attr);
247 
248 /** Creates a type attribute wrapping the given type in the same context as the
249  * type. */
250 MLIR_CAPI_EXPORTED MlirAttribute mlirTypeAttrGet(MlirType type);
251 
252 /// Returns the type stored in the given type attribute.
253 MLIR_CAPI_EXPORTED MlirType mlirTypeAttrGetValue(MlirAttribute attr);
254 
255 //===----------------------------------------------------------------------===//
256 // Unit attribute.
257 //===----------------------------------------------------------------------===//
258 
259 /// Checks whether the given attribute is a unit attribute.
260 MLIR_CAPI_EXPORTED bool mlirAttributeIsAUnit(MlirAttribute attr);
261 
262 /// Creates a unit attribute in the given context.
263 MLIR_CAPI_EXPORTED MlirAttribute mlirUnitAttrGet(MlirContext ctx);
264 
265 //===----------------------------------------------------------------------===//
266 // Elements attributes.
267 //===----------------------------------------------------------------------===//
268 
269 /// Checks whether the given attribute is an elements attribute.
270 MLIR_CAPI_EXPORTED bool mlirAttributeIsAElements(MlirAttribute attr);
271 
272 /// Returns the element at the given rank-dimensional index.
273 MLIR_CAPI_EXPORTED MlirAttribute mlirElementsAttrGetValue(MlirAttribute attr,
274                                                           intptr_t rank,
275                                                           uint64_t *idxs);
276 
277 /** Checks whether the given rank-dimensional index is valid in the given
278  * elements attribute. */
279 MLIR_CAPI_EXPORTED bool
280 mlirElementsAttrIsValidIndex(MlirAttribute attr, intptr_t rank, uint64_t *idxs);
281 
282 /** Gets the total number of elements in the given elements attribute. In order
283  * to iterate over the attribute, obtain its type, which must be a statically
284  * shaped type and use its sizes to build a multi-dimensional index. */
285 MLIR_CAPI_EXPORTED int64_t mlirElementsAttrGetNumElements(MlirAttribute attr);
286 
287 //===----------------------------------------------------------------------===//
288 // Dense elements attribute.
289 //===----------------------------------------------------------------------===//
290 
291 // TODO: decide on the interface and add support for complex elements.
292 /* TODO: add support for APFloat and APInt to LLVM IR C API, then expose the
293  * relevant functions here. */
294 
295 /// Checks whether the given attribute is a dense elements attribute.
296 MLIR_CAPI_EXPORTED bool mlirAttributeIsADenseElements(MlirAttribute attr);
297 MLIR_CAPI_EXPORTED bool mlirAttributeIsADenseIntElements(MlirAttribute attr);
298 MLIR_CAPI_EXPORTED bool mlirAttributeIsADenseFPElements(MlirAttribute attr);
299 
300 /** Creates a dense elements attribute with the given Shaped type and elements
301  * in the same context as the type. */
302 MLIR_CAPI_EXPORTED MlirAttribute mlirDenseElementsAttrGet(
303     MlirType shapedType, intptr_t numElements, MlirAttribute const *elements);
304 
305 /** Creates a dense elements attribute with the given Shaped type containing a
306  * single replicated element (splat). */
307 MLIR_CAPI_EXPORTED MlirAttribute
308 mlirDenseElementsAttrSplatGet(MlirType shapedType, MlirAttribute element);
309 MLIR_CAPI_EXPORTED MlirAttribute
310 mlirDenseElementsAttrBoolSplatGet(MlirType shapedType, bool element);
311 MLIR_CAPI_EXPORTED MlirAttribute
312 mlirDenseElementsAttrUInt32SplatGet(MlirType shapedType, uint32_t element);
313 MLIR_CAPI_EXPORTED MlirAttribute
314 mlirDenseElementsAttrInt32SplatGet(MlirType shapedType, int32_t element);
315 MLIR_CAPI_EXPORTED MlirAttribute
316 mlirDenseElementsAttrUInt64SplatGet(MlirType shapedType, uint64_t element);
317 MLIR_CAPI_EXPORTED MlirAttribute
318 mlirDenseElementsAttrInt64SplatGet(MlirType shapedType, int64_t element);
319 MLIR_CAPI_EXPORTED MlirAttribute
320 mlirDenseElementsAttrFloatSplatGet(MlirType shapedType, float element);
321 MLIR_CAPI_EXPORTED MlirAttribute
322 mlirDenseElementsAttrDoubleSplatGet(MlirType shapedType, double element);
323 
324 /** Creates a dense elements attribute with the given shaped type from elements
325  * of a specific type. Expects the element type of the shaped type to match the
326  * data element type. */
327 MLIR_CAPI_EXPORTED MlirAttribute mlirDenseElementsAttrBoolGet(
328     MlirType shapedType, intptr_t numElements, const int *elements);
329 MLIR_CAPI_EXPORTED MlirAttribute mlirDenseElementsAttrUInt32Get(
330     MlirType shapedType, intptr_t numElements, const uint32_t *elements);
331 MLIR_CAPI_EXPORTED MlirAttribute mlirDenseElementsAttrInt32Get(
332     MlirType shapedType, intptr_t numElements, const int32_t *elements);
333 MLIR_CAPI_EXPORTED MlirAttribute mlirDenseElementsAttrUInt64Get(
334     MlirType shapedType, intptr_t numElements, const uint64_t *elements);
335 MLIR_CAPI_EXPORTED MlirAttribute mlirDenseElementsAttrInt64Get(
336     MlirType shapedType, intptr_t numElements, const int64_t *elements);
337 MLIR_CAPI_EXPORTED MlirAttribute mlirDenseElementsAttrFloatGet(
338     MlirType shapedType, intptr_t numElements, const float *elements);
339 MLIR_CAPI_EXPORTED MlirAttribute mlirDenseElementsAttrDoubleGet(
340     MlirType shapedType, intptr_t numElements, const double *elements);
341 
342 /** Creates a dense elements attribute with the given shaped type from string
343  * elements. */
344 MLIR_CAPI_EXPORTED MlirAttribute mlirDenseElementsAttrStringGet(
345     MlirType shapedType, intptr_t numElements, MlirStringRef *strs);
346 
347 /** Creates a dense elements attribute that has the same data as the given dense
348  * elements attribute and a different shaped type. The new type must have the
349  * same total number of elements. */
350 MLIR_CAPI_EXPORTED MlirAttribute
351 mlirDenseElementsAttrReshapeGet(MlirAttribute attr, MlirType shapedType);
352 
353 /** Checks whether the given dense elements attribute contains a single
354  * replicated value (splat). */
355 MLIR_CAPI_EXPORTED bool mlirDenseElementsAttrIsSplat(MlirAttribute attr);
356 
357 /** Returns the single replicated value (splat) of a specific type contained by
358  * the given dense elements attribute. */
359 MLIR_CAPI_EXPORTED MlirAttribute
360 mlirDenseElementsAttrGetSplatValue(MlirAttribute attr);
361 MLIR_CAPI_EXPORTED int
362 mlirDenseElementsAttrGetBoolSplatValue(MlirAttribute attr);
363 MLIR_CAPI_EXPORTED int32_t
364 mlirDenseElementsAttrGetInt32SplatValue(MlirAttribute attr);
365 MLIR_CAPI_EXPORTED uint32_t
366 mlirDenseElementsAttrGetUInt32SplatValue(MlirAttribute attr);
367 MLIR_CAPI_EXPORTED int64_t
368 mlirDenseElementsAttrGetInt64SplatValue(MlirAttribute attr);
369 MLIR_CAPI_EXPORTED uint64_t
370 mlirDenseElementsAttrGetUInt64SplatValue(MlirAttribute attr);
371 MLIR_CAPI_EXPORTED float
372 mlirDenseElementsAttrGetFloatSplatValue(MlirAttribute attr);
373 MLIR_CAPI_EXPORTED double
374 mlirDenseElementsAttrGetDoubleSplatValue(MlirAttribute attr);
375 MLIR_CAPI_EXPORTED MlirStringRef
376 mlirDenseElementsAttrGetStringSplatValue(MlirAttribute attr);
377 
378 /** Returns the pos-th value (flat contiguous indexing) of a specific type
379  * contained by the given dense elements attribute. */
380 MLIR_CAPI_EXPORTED bool mlirDenseElementsAttrGetBoolValue(MlirAttribute attr,
381                                                           intptr_t pos);
382 MLIR_CAPI_EXPORTED int32_t
383 mlirDenseElementsAttrGetInt32Value(MlirAttribute attr, intptr_t pos);
384 MLIR_CAPI_EXPORTED uint32_t
385 mlirDenseElementsAttrGetUInt32Value(MlirAttribute attr, intptr_t pos);
386 MLIR_CAPI_EXPORTED int64_t
387 mlirDenseElementsAttrGetInt64Value(MlirAttribute attr, intptr_t pos);
388 MLIR_CAPI_EXPORTED uint64_t
389 mlirDenseElementsAttrGetUInt64Value(MlirAttribute attr, intptr_t pos);
390 MLIR_CAPI_EXPORTED float mlirDenseElementsAttrGetFloatValue(MlirAttribute attr,
391                                                             intptr_t pos);
392 MLIR_CAPI_EXPORTED double
393 mlirDenseElementsAttrGetDoubleValue(MlirAttribute attr, intptr_t pos);
394 MLIR_CAPI_EXPORTED MlirStringRef
395 mlirDenseElementsAttrGetStringValue(MlirAttribute attr, intptr_t pos);
396 
397 /** Returns the raw data of the given dense elements attribute. */
398 MLIR_CAPI_EXPORTED const void *
399 mlirDenseElementsAttrGetRawData(MlirAttribute attr);
400 
401 //===----------------------------------------------------------------------===//
402 // Opaque elements attribute.
403 //===----------------------------------------------------------------------===//
404 
405 // TODO: expose Dialect to the bindings and implement accessors here.
406 
407 /// Checks whether the given attribute is an opaque elements attribute.
408 MLIR_CAPI_EXPORTED bool mlirAttributeIsAOpaqueElements(MlirAttribute attr);
409 
410 //===----------------------------------------------------------------------===//
411 // Sparse elements attribute.
412 //===----------------------------------------------------------------------===//
413 
414 /// Checks whether the given attribute is a sparse elements attribute.
415 MLIR_CAPI_EXPORTED bool mlirAttributeIsASparseElements(MlirAttribute attr);
416 
417 /** Creates a sparse elements attribute of the given shape from a list of
418  * indices and a list of associated values. Both lists are expected to be dense
419  * elements attributes with the same number of elements. The list of indices is
420  * expected to contain 64-bit integers. The attribute is created in the same
421  * context as the type. */
422 MLIR_CAPI_EXPORTED MlirAttribute mlirSparseElementsAttribute(
423     MlirType shapedType, MlirAttribute denseIndices, MlirAttribute denseValues);
424 
425 /** Returns the dense elements attribute containing 64-bit integer indices of
426  * non-null elements in the given sparse elements attribute. */
427 MLIR_CAPI_EXPORTED MlirAttribute
428 mlirSparseElementsAttrGetIndices(MlirAttribute attr);
429 
430 /** Returns the dense elements attribute containing the non-null elements in the
431  * given sparse elements attribute. */
432 MLIR_CAPI_EXPORTED MlirAttribute
433 mlirSparseElementsAttrGetValues(MlirAttribute attr);
434 
435 #ifdef __cplusplus
436 }
437 #endif
438 
439 #endif // MLIR_C_BUILTINATTRIBUTES_H
440