Getting Started

This document provides an overview of IREE‘s systems, including entry points to get started exploring IREE’s capabilities.

For information on how to set up a development environment, see Getting Started on Windows and Getting Started on Linux.

Project Code Layout

iree/

  • Core IREE project

integrations/

  • Integrations between IREE and other frameworks, such as TensorFlow

bindings/

  • Language and platform bindings, such as Python

colab/

  • Colab notebooks for interactively using IREE's Python bindings

IREE Code Layout

iree/base/

  • Common types and utilities used throughout IREE

iree/compiler/

  • IREE's MLIR dialects, LLVM compiler passes, module translation code, etc.

iree/hal/

  • Hardware Abstraction Layer for IREE's runtime, with implementations for hardware and software backends

iree/schemas/

  • Shared data storage format definitions, primarily using FlatBuffers

iree/tools/

  • Assorted tools used to optimize, translate, and evaluate IREE

iree/vm/

  • Bytecode Virtual Machine used to work with IREE modules and invoke IREE functions

Working with IREE's Components

IREE ingests MLIR in a high-level dialect like XLA/HLO, after which it can perform its own compiler passes to eventually translate the IR into an ‘IREE module’, which can be executed via IREE's runtime. IREE contains programs for running each step in that pipeline under various configurations (e.g. for tests, with a debugger attached, etc.).

iree-opt

The iree-opt program invokes MlirOptMain to run some set of IREE's optimization passes on a provided .mlir input file. Test .mlir files that are checked in typically include a RUN block at the top of the file that specifies which passes should be performed and if FileCheck should be used to test the generated output.

For example, to run some passes on the reshape.mlir test file with Bazel on Linux, use this command:

$ bazel run //iree/tools:iree-opt -- \
  -split-input-file \
  -iree-index-computation \
  -simplify-spirv-affine-exprs=false \
  -convert-iree-to-spirv \
  -verify-diagnostics \
  $PWD/iree/compiler/Translation/SPIRV/XLAToSPIRV/test/reshape.mlir

iree-translate

The iree-translate program translates from a .mlir input file into an IREE module.

For example, to translate simple.mlir to an IREE module with bazel on Linux, use this command:

$ bazel run //iree/tools:iree-translate -- \
  -iree-mlir-to-vm-bytecode-module \
  --iree-hal-target-backends=interpreter-bytecode \
  $PWD/iree/tools/test/simple.mlir \
  -o /tmp/module.fb

Custom translations may also be layered on top of iree-translate - see iree/samples/custom_modules/dialect for a sample.

iree-run-module

The iree-run-module program takes an already translated IREE module as input and executes an exported main function using the provided inputs.

This program can be used in sequence with iree-translate to translate a .mlir file to an IREE module and then execute it. Here is an example command that executes the simple module.fb compiled from simple.mlir above on the IREE interpreter

$ bazel run //iree/tools:iree-run-module -- \
  --input_file=/tmp/module.fb \
  --driver=interpreter \
  --entry_function=abs \
  --inputs="i32=-2"

iree-run-mlir

The iree-run-mlir program takes a .mlir file as input, translates it to an IREE bytecode module, and executes the module.

It is designed for testing and debugging, not production use cases, and therefore does some additional work that usually must be explicit, like marking every function as exported by default and running all of them.

For example, to execute the contents of a test .mlir file, use this command:

$ bazel run //iree/tools:iree-run-mlir -- \
  $PWD/iree/tools/test/simple.mlir \
  --input-value="i32=-2" \
  --iree-hal-target-backends=interpreter-bytecode

iree-dump-module

The iree-dump-module program prints the contents of an IREE module FlatBuffer file.

For example:

$ bazel run //iree/tools:iree-dump-module -- /tmp/module.fb