1//===-- mlir-c/Support.h - Helpers for C API to Core MLIR ---------*- 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 auxiliary data structures used in C APIs to core
11// MLIR functionality.
12//
13//===----------------------------------------------------------------------===//
14
15#ifndef MLIR_C_SUPPORT_H
16#define MLIR_C_SUPPORT_H
17
18#include <stdbool.h>
19#include <stddef.h>
20#include <stdint.h>
21
22//===----------------------------------------------------------------------===//
23// Visibility annotations.
24// Use MLIR_CAPI_EXPORTED for exported functions.
25//
26// On Windows, if MLIR_CAPI_ENABLE_WINDOWS_DLL_DECLSPEC is defined, then
27// __declspec(dllexport) and __declspec(dllimport) will be generated. This
28// can only be enabled if actually building DLLs. It is generally, mutually
29// exclusive with the use of other mechanisms for managing imports/exports
30// (i.e. CMake's WINDOWS_EXPORT_ALL_SYMBOLS feature).
31//===----------------------------------------------------------------------===//
32
33#if (defined(_WIN32) || defined(__CYGWIN__)) && \
34 !defined(MLIR_CAPI_ENABLE_WINDOWS_DLL_DECLSPEC)
35// Visibility annotations disabled.
36#define MLIR_CAPI_EXPORTED
37#elif defined(_WIN32) || defined(__CYGWIN__)
38// Windows visibility declarations.
39#if MLIR_CAPI_BUILDING_LIBRARY
40#define MLIR_CAPI_EXPORTED __declspec(dllexport)
41#else
42#define MLIR_CAPI_EXPORTED __declspec(dllimport)
43#endif
44#else
45// Non-windows: use visibility attributes.
46#define MLIR_CAPI_EXPORTED __attribute__((visibility("default")))
47#endif
48
49#define MLIR_PYTHON_API_EXPORTED MLIR_CAPI_EXPORTED
50
51#ifdef __cplusplus
52extern "C" {
53#endif
54
55#define DEFINE_C_API_STRUCT(name, storage) \
56 struct name { \
57 storage *ptr; \
58 }; \
59 typedef struct name name
60
61/// Re-export llvm::ThreadPool so as to avoid including the LLVM C API directly.
62DEFINE_C_API_STRUCT(MlirLlvmThreadPool, void);
63/// Re-export llvm::raw_fd_ostream so as to avoid including the LLVM C API
64/// directly.
65DEFINE_C_API_STRUCT(MlirLlvmRawFdOStream, void);
66DEFINE_C_API_STRUCT(MlirTypeID, const void);
67DEFINE_C_API_STRUCT(MlirTypeIDAllocator, void);
68
69#undef DEFINE_C_API_STRUCT
70
71//===----------------------------------------------------------------------===//
72// MlirStringRef.
73//===----------------------------------------------------------------------===//
74
75/// A pointer to a sized fragment of a string, not necessarily null-terminated.
76/// Does not own the underlying string. This is equivalent to llvm::StringRef.
77
78struct MlirStringRef {
79 const char *data; ///< Pointer to the first symbol.
80 size_t length; ///< Length of the fragment.
81};
82typedef struct MlirStringRef MlirStringRef;
83
84/// Constructs a string reference from the pointer and length. The pointer need
85/// not reference to a null-terminated string.
86
87inline static MlirStringRef mlirStringRefCreate(const char *str,
88 size_t length) {
89 MlirStringRef result;
90 result.data = str;
91 result.length = length;
92 return result;
93}
94
95/// Constructs a string reference from a null-terminated C string. Prefer
96/// mlirStringRefCreate if the length of the string is known.
97MLIR_CAPI_EXPORTED MlirStringRef
98mlirStringRefCreateFromCString(const char *str);
99
100/// Returns true if two string references are equal, false otherwise.
101MLIR_CAPI_EXPORTED bool mlirStringRefEqual(MlirStringRef string,
102 MlirStringRef other);
103
104/// A callback for returning string references.
105///
106/// This function is called back by the functions that need to return a
107/// reference to the portion of the string with the following arguments:
108/// - an MlirStringRef representing the current portion of the string
109/// - a pointer to user data forwarded from the printing call.
110typedef void (*MlirStringCallback)(MlirStringRef, void *);
111
112//===----------------------------------------------------------------------===//
113// MlirLogicalResult.
114//===----------------------------------------------------------------------===//
115
116/// A logical result value, essentially a boolean with named states. LLVM
117/// convention for using boolean values to designate success or failure of an
118/// operation is a moving target, so MLIR opted for an explicit class.
119/// Instances of MlirLogicalResult must only be inspected using the associated
120/// functions.
121struct MlirLogicalResult {
122 int8_t value;
123};
124typedef struct MlirLogicalResult MlirLogicalResult;
125
126/// Checks if the given logical result represents a success.
127inline static bool mlirLogicalResultIsSuccess(MlirLogicalResult res) {
128 return res.value != 0;
129}
130
131/// Checks if the given logical result represents a failure.
132inline static bool mlirLogicalResultIsFailure(MlirLogicalResult res) {
133 return res.value == 0;
134}
135
136/// Creates a logical result representing a success.
137inline static MlirLogicalResult mlirLogicalResultSuccess(void) {
138 MlirLogicalResult res = {.value: 1};
139 return res;
140}
141
142/// Creates a logical result representing a failure.
143inline static MlirLogicalResult mlirLogicalResultFailure(void) {
144 MlirLogicalResult res = {.value: 0};
145 return res;
146}
147
148//===----------------------------------------------------------------------===//
149// MlirLlvmThreadPool.
150//===----------------------------------------------------------------------===//
151
152/// Create an LLVM thread pool. This is reexported here to avoid directly
153/// pulling in the LLVM headers directly.
154MLIR_CAPI_EXPORTED MlirLlvmThreadPool mlirLlvmThreadPoolCreate(void);
155
156/// Destroy an LLVM thread pool.
157MLIR_CAPI_EXPORTED void mlirLlvmThreadPoolDestroy(MlirLlvmThreadPool pool);
158
159/// Returns the maximum number of threads in the thread pool.
160MLIR_CAPI_EXPORTED int
161mlirLlvmThreadPoolGetMaxConcurrency(MlirLlvmThreadPool pool);
162
163//===----------------------------------------------------------------------===//
164// MlirLlvmRawFdOStream.
165//===----------------------------------------------------------------------===//
166
167/// Create a raw_fd_ostream for the given path. This wrapper is needed because
168/// std::ostream does not provide the file sharing semantics required on
169/// Windows.
170/// - `path`: output file path.
171/// - `binary`: controls text vs binary mode.
172/// - `errorCallback`: called with an error message on failure (optional).
173/// - `userData`: forwarded to `errorCallback` so it can copy the error message
174/// into caller-owned storage (e.g., a `std::string`).
175/// On failure, returns a null stream and invokes the optional error callback
176/// with the error message.
177MLIR_CAPI_EXPORTED MlirLlvmRawFdOStream
178mlirLlvmRawFdOStreamCreate(const char *path, bool binary,
179 MlirStringCallback errorCallback, void *userData);
180
181/// Write a string to a raw_fd_ostream created with mlirLlvmRawFdOStreamCreate.
182MLIR_CAPI_EXPORTED void mlirLlvmRawFdOStreamWrite(MlirLlvmRawFdOStream stream,
183 MlirStringRef string);
184
185/// Checks if a raw_fd_ostream is null.
186MLIR_CAPI_EXPORTED bool mlirLlvmRawFdOStreamIsNull(MlirLlvmRawFdOStream stream);
187
188/// Destroy a raw_fd_ostream created with mlirLlvmRawFdOStreamCreate.
189MLIR_CAPI_EXPORTED void
190mlirLlvmRawFdOStreamDestroy(MlirLlvmRawFdOStream stream);
191
192//===----------------------------------------------------------------------===//
193// TypeID API.
194//===----------------------------------------------------------------------===//
195
196/// `ptr` must be 8 byte aligned and unique to a type valid for the duration of
197/// the returned type id's usage
198MLIR_CAPI_EXPORTED MlirTypeID mlirTypeIDCreate(const void *ptr);
199
200/// Checks whether a type id is null.
201static inline bool mlirTypeIDIsNull(MlirTypeID typeID) { return !typeID.ptr; }
202
203/// Checks if two type ids are equal.
204MLIR_CAPI_EXPORTED bool mlirTypeIDEqual(MlirTypeID typeID1, MlirTypeID typeID2);
205
206/// Returns the hash value of the type id.
207MLIR_CAPI_EXPORTED size_t mlirTypeIDHashValue(MlirTypeID typeID);
208
209//===----------------------------------------------------------------------===//
210// TypeIDAllocator API.
211//===----------------------------------------------------------------------===//
212
213/// Creates a type id allocator for dynamic type id creation
214MLIR_CAPI_EXPORTED MlirTypeIDAllocator mlirTypeIDAllocatorCreate(void);
215
216/// Deallocates the allocator and all allocated type ids
217MLIR_CAPI_EXPORTED void
218mlirTypeIDAllocatorDestroy(MlirTypeIDAllocator allocator);
219
220/// Allocates a type id that is valid for the lifetime of the allocator
221MLIR_CAPI_EXPORTED MlirTypeID
222mlirTypeIDAllocatorAllocateTypeID(MlirTypeIDAllocator allocator);
223
224#ifdef __cplusplus
225}
226#endif
227
228#endif // MLIR_C_SUPPORT_H
229