OpenParable
Skip to content
← Back to skills

Dump Intermediate Ir

Testing & Quality
dump-intermediate-ir

Dump Intermediate Ir is an Agent Skill for testing & quality published in the google/heir repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Augments a `bazel run` CLI command for `heir-opt` with additional flags that dump the IR before each compiler pass, allowing the agent to inspect intermediate IR during compilation, identify a particular pass at which the pipeline fails, or extract the corresponding IR input to a particular pass for further debugging.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/google/heir/blob/HEAD/.agents/skills/dump_intermediate_ir/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/dump-intermediate-ir, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Dump intermediate IR during compilation

Overview

This skill guides the agent in adding flags to the heir-opt tool to dump the compiled IR after each compiler pass to a series of files. These files can then be inspected to identify the failing pass as well as the IR input to the failing pass.

Usage

Converting a bazel run command

To convert a bazel run command, add the flags --mlir-print-ir-before-all and --mlir-print-ir-tree-dir=<PATH>, where <PATH> is a path to a temporary directory.

For example, given the following input command (which can be produced by the lit-to-bazel skill),

bazel run //tools:heir-opt -- --mlir-to-ckks='ciphertext-degree=8' --scheme-to-openfhe='entry-function=dot_product' /path/to/file

The agent should produce the following (again where <PATH> is chosen appropriately)

bazel run //tools:heir-opt -- --mlir-to-ckks='ciphertext-degree=8' --scheme-to-openfhe='entry-function=dot_product' --mlir-print-ir-before-all --mlir-print-ir-tree-dir=<PATH> /path/to/file

Tree structure

--mlir-print-ir-tree-dir nests the dumped IR in a tree structure that matches the nesting structure of the pass pipeline. In particular, by default all passes will be nested under a builtin_module_no-symbol-name/ folder, and any passes in the pipeline that are anchored on nested operations like func.func will be placed in subdirectories based on the name, such as func_func_matvec__decrypt__result0 for a pass anchored on func.func when the IR contains a function called matvec__decrypt__result0.

For example, if the flag --mlir-print-ir-tree-dir=/tmp/mlir is used, then the dumped files might look like:

/tmp/mlir/
└── builtin_module_no-symbol-name
    ├── 0_annotate-module.mlir
    ├── 10_compare-to-sign-rewrite.mlir
    ├── 11_canonicalize.mlir
    ├── 12_cse.mlir
    ├── 13_apply-folders.mlir
    ├── 14_canonicalize.mlir
    ├── 15_insert-rotate.mlir
    ├── 16_cse.mlir
    ├── 17_canonicalize.mlir
    ├── 18_cse.mlir
    ├── 19_collapse-insertion-chains.mlir
    ├── 1_debug-validate-names.mlir
    ├── 20_sccp.mlir
    ├── 21_canonicalize.mlir
    ...
    ├── func_func__assign_layout_9911323688340753831
    │   ├── 47_0_affine-expand-index-ops.mlir
    │   ├── 47_1_affine-simplify-structures.mlir
    │   ├── 47_2_affine-loop-normalize.mlir
    │   └── 47_3_forward-insert-slice-to-extract-slice.mlir
    ├── func_func_matvec
    │   ├── 47_0_affine-expand-index-ops.mlir
    │   ├── 47_1_affine-simplify-structures.mlir
    │   ├── 47_2_affine-loop-normalize.mlir
    │   └── 47_3_forward-insert-slice-to-extract-slice.mlir
    ├── func_func_matvec__decrypt__result0
    │   ├── 47_0_affine-expand-index-ops.mlir
    │   ├── 47_1_affine-simplify-structures.mlir
    │   ├── 47_2_affine-loop-normalize.mlir
    │   └── 47_3_forward-insert-slice-to-extract-slice.mlir
    └── func_func_matvec__encrypt__arg0
        ├── 47_0_affine-expand-index-ops.mlir
        ├── 47_1_affine-simplify-structures.mlir
        ├── 47_2_affine-loop-normalize.mlir
        └── 47_3_forward-insert-slice-to-extract-slice.mlir

Dumped file contents

At the top of each file, a comment is printed indicating how the file was generated, containing e.g., IR Dump Before CSEPass (cse). This will say whether the IR was dumped before or after a pass, as well as whether (in the case of --mlir-print-ir-after-failure) the pass failed.

Below the comment, the MLIR is printed in textual format.

Gotchas

  • Stale files: --mlir-print-ir-tree-dir does not delete existing files, so if the command is re-run, be sure to remove the existing temporary files first.
  • Dump before vs after: --mlir-print-ir-before-all prints the IR before a pass runs, which is required to extract the IR if a pass has a hard error like a segfault. To dump the IR after each pass, use --mlir-print-ir-after-all.
  • Dumping after failure: For some errors without stack traces (like a dialect conversion failure where the compiler fails gracefully), you can use --mlir-print-ir-after-failure to dump the IR at failure time, which can provide additional debugging information. One notable example is when dialect conversion fails, the IR dumped by --mlir-print-ir-after-failure includes the partially-converted IR including any unrealized_conversion_cast ops that failed to be removed.
  • Dumping after change: The number of files can be reduced by using --mlir-print-ir-after-change, which only prints the IR if the compiler pass changed it. There is no "before change" analogue.
  • Dumping after change: The number of files can be reduced by using --mlir-print-ir-before=<pass_name>, which only prints the IR before the target pass. Since a pass can be run multiple times in a pipeline, this may still produce many files if, for example, the pass is a common one like cse.
Copy this checklist and track progress:

- [ ] Step 1: Identify the command to convert, perhaps with `lit-to-bazel`
- [ ] Step 2: Add the relevant flags, defaulting to `--mlir-print-ir-before-all` and `--mlir-print-ir-tree-dir` if there is no specific reason to use the more specific flags.
- [ ] Step 3: Inspect the generated command and run it.
- [ ] Step 4: Inspect the dumped files for information.