0
# Compiler API Embedding
1
2
Low-level Python bindings for IREE's C embedding API, providing direct access to compiler infrastructure for advanced use cases requiring fine-grained control over compilation sessions, invocations, and I/O handling.
3
4
## Capabilities
5
6
### Session Management
7
8
Manages compiler sessions that wrap MLIR contexts with configuration flags for setting up the compiler environment.
9
10
```python { .api }
11
class Session:
12
"""
13
Compiler session wrapping an MLIRContext with configuration flags.
14
15
Represents the top-level compiler state and configuration. Sessions are
16
thread-safe for read operations but require external synchronization
17
for mutations.
18
"""
19
20
def __init__(self, **kwargs): ...
21
22
def invocation(self) -> Invocation:
23
"""
24
Create a new compiler invocation within this session.
25
26
Returns:
27
Invocation: New invocation object for compilation
28
"""
29
30
def set_flags(self, *flags: str) -> None:
31
"""
32
Set compiler flags for this session.
33
34
Parameters:
35
- *flags: Variable number of compiler flag strings
36
"""
37
38
def get_flags(self, non_default_only: bool = False) -> Sequence[str]:
39
"""
40
Get current compiler flags.
41
42
Parameters:
43
- non_default_only: Only return non-default flags
44
45
Returns:
46
Sequence[str]: List of current flags
47
"""
48
49
@property
50
def context(self):
51
"""
52
Get the MLIR context for this session.
53
54
Returns:
55
MLIRContext: The underlying MLIR context
56
"""
57
58
def close(self) -> None:
59
"""
60
Close the session and release resources.
61
"""
62
```
63
64
### Compilation Invocations
65
66
Manages individual compilation invocations that wrap MLIR Modules during the compilation process.
67
68
```python { .api }
69
class Invocation:
70
"""
71
Compiler invocation wrapping a Module being compiled.
72
73
Represents a single compilation unit with its associated source,
74
transformations, and output. Invocations are not thread-safe.
75
"""
76
77
def parse_source(self, source: Source) -> bool:
78
"""
79
Parse source input for this invocation.
80
81
Parameters:
82
- source: Source object containing input to parse
83
84
Returns:
85
bool: True if parsing succeeded
86
"""
87
88
def pipeline(self, pipeline_type: int) -> bool:
89
"""
90
Run a compilation pipeline.
91
92
Parameters:
93
- pipeline_type: Pipeline type constant
94
95
Returns:
96
bool: True if pipeline succeeded
97
"""
98
99
def run_pass_pipeline(self, pipeline_str: str) -> bool:
100
"""
101
Run a custom pass pipeline.
102
103
Parameters:
104
- pipeline_str: Pass pipeline string
105
106
Returns:
107
bool: True if pipeline succeeded
108
"""
109
110
def output_ir(self, output: Output) -> None:
111
"""
112
Output MLIR IR to an output object.
113
114
Parameters:
115
- output: Output object to write to
116
"""
117
118
def output_ir_bytecode(self, output: Output, bytecode_version: int) -> None:
119
"""
120
Output MLIR bytecode to an output object.
121
122
Parameters:
123
- output: Output object to write to
124
- bytecode_version: Bytecode format version
125
"""
126
127
def output_vm_bytecode(self, output: Output) -> None:
128
"""
129
Output VM bytecode to an output object.
130
131
Parameters:
132
- output: Output object to write to
133
"""
134
135
def enable_console_diagnostics(self) -> None:
136
"""
137
Enable console diagnostic output.
138
"""
139
140
def export_module(self):
141
"""
142
Export the compiled module as MLIR Operation.
143
144
Returns:
145
ir.Operation: MLIR Operation containing the module
146
"""
147
148
def close(self) -> None:
149
"""
150
Close the invocation and release resources.
151
"""
152
```
153
154
### Source Input
155
156
Manages input sources for compilation including MLIR text, bytecode, and other supported formats.
157
158
```python { .api }
159
class Source:
160
"""
161
Source input for compiler invocations.
162
163
Wraps various input formats including MLIR assembly text,
164
MLIR bytecode, and other supported source formats.
165
"""
166
167
@staticmethod
168
def open_file(session: Session, file_path: str) -> Source:
169
"""
170
Create source from file path.
171
172
Parameters:
173
- session: Session object
174
- file_path: Path to source file
175
176
Returns:
177
Source: Source object for the file
178
"""
179
180
@staticmethod
181
def wrap_buffer(session: Session, buffer, *, buffer_name: str = "source.mlir") -> Source:
182
"""
183
Create source from memory buffer.
184
185
Parameters:
186
- session: Session object
187
- buffer: Buffer containing source data
188
- buffer_name: Name for the buffer source
189
190
Returns:
191
Source: Source object wrapping the buffer
192
"""
193
194
def close(self) -> None:
195
"""
196
Close the source and release resources.
197
"""
198
```
199
200
### Output Management
201
202
Manages compilation outputs including VM bytecode, MLIR text, and other generated formats.
203
204
```python { .api }
205
class Output:
206
"""
207
Compilation output containing generated code and metadata.
208
209
Provides access to the results of compilation including
210
bytecode, text representations, and diagnostic information.
211
"""
212
213
@staticmethod
214
def open_file(file_path: str) -> Output:
215
"""
216
Create output that writes to a file.
217
218
Parameters:
219
- file_path: Path to output file
220
221
Returns:
222
Output: Output object for the file
223
"""
224
225
@staticmethod
226
def open_membuffer() -> Output:
227
"""
228
Create output that writes to memory buffer.
229
230
Returns:
231
Output: Output object for memory buffer
232
"""
233
234
def keep(self) -> Output:
235
"""
236
Mark output to be kept after close.
237
238
Returns:
239
Output: Self for chaining
240
"""
241
242
def write(self, buffer) -> None:
243
"""
244
Write data to output.
245
246
Parameters:
247
- buffer: Data to write
248
"""
249
250
def map_memory(self) -> memoryview:
251
"""
252
Map output memory for reading.
253
254
Returns:
255
memoryview: Memory view of output content
256
"""
257
258
def close(self) -> None:
259
"""
260
Close the output and release resources.
261
"""
262
```
263
264
### Pipeline Types
265
266
Enumeration of compilation pipeline types for the pipeline() method.
267
268
```python { .api }
269
class PipelineType(IntEnum):
270
"""
271
Compilation pipeline type constants.
272
"""
273
IREE_COMPILER_PIPELINE_STD = 0
274
IREE_COMPILER_PIPELINE_HAL_EXECUTABLE = 1
275
IREE_COMPILER_PIPELINE_PRECOMPILE = 2
276
```
277
278
### Global Initialization
279
280
Global initialization function for setting up command-line argument processing.
281
282
```python { .api }
283
def _initializeGlobalCL(*cl_args: str) -> None:
284
"""
285
Initialize global command-line processing.
286
287
Parameters:
288
- *cl_args: Command-line arguments to initialize with
289
290
Must be called once before using the embedding API.
291
Sets up LLVM command-line argument parsing and global state.
292
"""
293
```
294
295
## Usage Examples
296
297
### Basic Compilation Workflow
298
299
```python
300
from iree.compiler.api import Session, Source, _initializeGlobalCL
301
302
# Initialize global state
303
_initializeGlobalCL()
304
305
# Create session
306
session = Session()
307
308
try:
309
# Create invocation
310
invocation = session.invocation()
311
312
# Set up source
313
mlir_code = """
314
func.func @simple_add(%arg0: tensor<4xf32>, %arg1: tensor<4xf32>) -> tensor<4xf32> {
315
%0 = arith.addf %arg0, %arg1 : tensor<4xf32>
316
return %0 : tensor<4xf32>
317
}
318
"""
319
source = Source.wrap_buffer(session, mlir_code.encode())
320
invocation.parse_source(source)
321
322
# Configure compilation
323
session.set_flags(
324
"--iree-hal-target-backends=llvm-cpu",
325
"--iree-input-type=auto"
326
)
327
328
# Create output and run compilation pipeline
329
output = Output.open_membuffer()
330
invocation.pipeline(0) # IREE_COMPILER_PIPELINE_STD
331
invocation.output_vm_bytecode(output)
332
333
# Get results
334
bytecode = output.map_memory()
335
336
# Clean up
337
output.close()
338
invocation.close()
339
source.close()
340
341
finally:
342
session.close()
343
```
344
345
### File-based Compilation
346
347
```python
348
from iree.compiler.api import Session, Source
349
350
session = Session()
351
352
try:
353
invocation = session.invocation()
354
355
# Load from file
356
source = Source.open_file(session, "model.mlir")
357
invocation.parse_source(source)
358
359
# Set compilation flags
360
session.set_flags(
361
"--iree-hal-target-backends=cuda",
362
"--iree-input-type=stablehlo"
363
)
364
365
# Compile and save
366
output = Output.open_file("model.vmfb")
367
invocation.pipeline(0) # IREE_COMPILER_PIPELINE_STD
368
invocation.output_vm_bytecode(output)
369
370
# Clean up
371
output.close()
372
invocation.close()
373
source.close()
374
375
finally:
376
session.close()
377
```
378
379
### Advanced Session Configuration
380
381
```python
382
from iree.compiler.api import Session
383
384
# Configure session with specific options
385
session = Session(
386
enable_debug_info=True,
387
enable_crash_reproducer=True
388
)
389
390
try:
391
# Set session-level flags
392
session.set_flags("--iree-hal-target-backends=vulkan-spirv")
393
394
# Multiple invocations can share the same session
395
for input_file in ["model1.mlir", "model2.mlir"]:
396
invocation = session.invocation()
397
398
source = Source.open_file(session, input_file)
399
invocation.parse_source(source)
400
401
output = Output.open_file(f"{input_file}.vmfb")
402
invocation.pipeline(0) # IREE_COMPILER_PIPELINE_STD
403
invocation.output_vm_bytecode(output)
404
405
output.close()
406
invocation.close()
407
source.close()
408
409
finally:
410
session.close()
411
```