TheRock/docs/rfcs/RFC0004-Fusilli-IREE-Kernel-Provider-hipDNN.md

author(s), created, modified, status, discussion

author(s)	created	modified	status	discussion
Sambhav Jain, Aaron St. George, and Mahesh Ravishankar	2025-10-17	2025-11-13	draft	https://github.com/ROCm/TheRock/discussions/1817

Fusilli+IREE as a kernel provider and JIT engine for hipDNN

Status note: The iree-libs subtree and fusilli-provider component described here were implemented and then later removed from TheRock / rocm-libraries. This RFC is retained as historical record of the accepted design.

This RFC proposes adding IREE as a kernel provider to hipDNN to leverage JIT compiled and codegenerated kernels in ML training and inference solutions. This is made possible with the development of Fusilli - a C++ graph API and JIT engine for IREE. We believe hand-authored kernel libraries are great for highly tuned performance but they are difficult to 1) scale to newer models or target architectures and 2) package and release effectively. This RFC is founded on the overarching goal to complement our software stack with JIT solutions while being competitive to hand-authored kernel libraries. Apart from the usual benefits of having a compiler-backed JIT engine that gets progressively better, a systemic benefit of this is it helps reduce build times and binary sizes, making it easier to ship software effectively.

Overview

IREE is an open source ML compiler stack built using MLIR that is intended to support the compilation and execution of ML models. While IREE supports multiple target backends, over the past couple of years a lot of effort has gone into improving the codegeneration for AMD GPUs, specifically Instinct (MI-series) GPUs. Much of the IREE compiler stack is geared towards optimizing execution of full-scale ML models. However, a key objective of this work is to have efficient kernel code generation for MI300+ GPUs.

Fusilli is a C++ graph API that leverages the kernel codegeneration capabilities of IREE and packages it to be usable as a JIT engine for hipDNN. This allows use of IREE for specific portions of the program, even for training use cases. The advantages of this approach are:

1. IREE has been built from the ground-up as a fusion compiler. The kinds of fusions that libraries like hipDNN are expected to provide are supported out-of-the box in IREE.
2. Fusilli allows compiling codegenerated kernels just-in-time (on-demand) without having to ship pre-built kernels with hipDNN - saving both build times and binary sizes.

Workplan

From a code organization standpoint, there are three components to reason about:

1. IREE. This includes the compiler and runtime stack. It is a Linux Foundation project and lives here.
2. Fusilli. This is a general purpose API and backend-neutral JIT engine for IREE that lives here. It depends minimally on IREE compiler (CLI) and IREE runtime (C-API), and does NOT require a direct HIP dependency (abstracted by IREE's HAL design).
3. Fusilli-Plugin. The hipDNN engine plugin for Fusilli that specializes it for use within hipDNN - specifically for AMD GPUs. Currently it is being developed here.

Short term plan

The immediate goal is to build the hipDNN engine plugin (i.e., component 3 above) in TheRock. The plugin's dependencies require all three components to be part of the build. IREE is a large dependency; the desire is to keep it an optional, experimental, component not built by default. Therefore IREE's TheRock build and all dependent projects (Fusilli, Fusilli-Plugin) will be gated behind a CMake option THEROCK_ENABLE_BUILD_IREE_LIBS

For the various build scripts, this RFC proposes a new top level directory iree-libs, gated in the top level CMakeLists.txt. Note: iree-libs name is subject to change, we need a name, so iree-libs is a placeholder for the RFC.

 add_subdirectory(comm-libs)
 add_subdirectory(math-libs)
 add_subdirectory(ml-libs)
+
+if(THEROCK_ENABLE_BUILD_IREE_LIBS)
+  add_subdirectory(iree-libs)
+endif()

...
├── iree-libs
│   ├── CMakeLists.txt
│   ├── iree    (submodule)
│   └── fusilli (submodule)
├── math-libs
...

The following sections detail where each dependency will live outside of TheRock, and what its build will look like inside of TheRock.

IREE

IREE will remain in its Linux Foundation-governed iree-org repo. TheRock will fetch IREE as a submodule, and otherwise treat it as a fairly standard therock_cmake_subproject_declare.

The full IREE project includes the IREE compiler and runtime, but initially TheRock will only build the runtime. The compiler isn't (currently) necessary as Fusilli uses the standalone iree-compile executable. IREE has many submodules, including its own LLVM, but for the initial integration build_tools/fetch_sources.py will only fetch what's necessary to build the runtime: flatcc. Longer term, the story will evolve.

iree-libs/CMakeLists.txt

therock_cmake_subproject_declare(therock-iree-runtime
  EXCLUDE_FROM_ALL
  BINARY_DIR "${CMAKE_CURRENT_BINARY_DIR}/iree-runtime"
  EXTERNAL_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/iree"
  ...

The IREE runtime builds as a series of .a archives which are intended to be linked into a final executable with LTO style optimization.

Fusilli

Fusilli will remain in its Linux Foundation-governed iree-org repo. TheRock will fetch Fusilli as a submodule, and again otherwise treat it as a fairly standard therock_cmake_subproject_declare. Fusilli has no submodules.

iree-libs/CMakeLists.txt

therock_cmake_subproject_declare(therock-fusilli
  EXCLUDE_FROM_ALL
  BINARY_DIR "${CMAKE_CURRENT_BINARY_DIR}/fusilli"
  EXTERNAL_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/fusilli"
  BUILD_DEPS
   therock-iree-runtime
  ...

Fusilli builds as a series of .h files.

A small note on C++ standards: Fusilli and the hipDNN engine plugin for Fusilli are built on the C++20 standard. We believe this should not pose any issues from an integration standpoint but happy to revisit this further if the need arises.

Fusilli-Plugin

Fusilli-Plugin is currently in amd-shark-ai, and move into a plugins/ subdirectory of fusilli. It will remain a standalone project emulating the end state (as if it was "in TheRock") - built with the Fusilli API, rather than being a part of the Fusilli API itself - but just in the Fusilli repo to stage the roll-out to be less disruptive. This allows for it to be easily movable alongside other hipdnn plugins at a later point if desired.

Fusilli-Plugin will build as a therock_cmake_subproject_declare, reaching into the plugins/ directory of the fusilli submodule.

therock_cmake_subproject_declare(therock-fusilli-plugin
  EXCLUDE_FROM_ALL
  BINARY_DIR "${CMAKE_CURRENT_BINARY_DIR}/fusilli-plugin"
  EXTERNAL_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/fusilli/plugins/hipdnn-plugin"
  BUILD_DEPS
   hipDNN
   therock-iree-runtime
   therock-fusilli
  ...

The expected build artifact from the plugin integration is a self-contained libfusilliplugin.so, built with Fusilli headers, and linking IREE runtime libraries with LTO style optimizations.

Long term plan

As the Fusilli integration evolves, so will TheRock's IREE integration. It will likely follow the steps below:

1. (current state) Fusilli uses a "side loaded" iree-compile binary. If users build TheRock with THEROCK_ENABLE_BUILD_IREE_LIBS=ON (off by default) they will also need to pip install iree-compiler on their system.
2. (mid term) Fusilli will move to using IREE compiler's C-API + libIREECompiler.so built in TheRock. IREE uses a very recent LLVM (daily integration). In this phase, build_tools/fetch_sources.py will be updated to fetch IREE's captive LLVM, adding yet another LLVM build to TheRock. The main build will not be affected, but builds with THEROCK_ENABLE_BUILD_IREE_LIBS=ON will be slower at this point in the integration.
3. (long term) Unify some set of LLVMs to eliminate IREE's captive LLVM - this will be a large effort. After unification, building Fusilli integration should be cheap.

Revision History

• 2025-10-17: Sambhav Jain: Initial version

• 2025-11-13: Aaron St George: Added detail to Short term plan