Codex Instructions for hipDNNEP

This is an out-of-tree ONNXRuntime Execution Provider (EP) that uses AMD's hipDNN library for accelerated inference on AMD GPUs. The EP is built as a plugin that can be dynamically loaded by ONNXRuntime.

Primary Repo Guidance

• Supported ops:
  • Conv2D via hipDNN graph API
  • MatMul/Gemm via hipBLAS-LT when enabled
• Optional features:
  • hipBLAS-LT support
  • Torch-MLIR integration via HIPDNN_EP_ENABLE_TORCH_MLIR=ON
• Build environment:
  • THEROCK_DIST=/path/to/TheRock/build/dist/rocm
  • ONNXRUNTIME_ROOT=/path/to/onnxruntime

Build Commands

Standard Build

cmake --preset RelWithDebInfo
cmake --build --preset RelWithDebInfo
ctest --preset RelWithDebInfo --output-on-failure

Build With Torch-MLIR

cmake --preset RelWithDebInfo-MLIR
cmake --build --preset RelWithDebInfo-MLIR
ctest --preset RelWithDebInfo-MLIR --output-on-failure

One-time torch-mlir build:

cd third_party/torch-mlir
cmake -G Ninja -B ../../../build/torch-mlir \
  -DCMAKE_BUILD_TYPE=RelWithDebInfo \
  -DCMAKE_INSTALL_PREFIX=../../../build/torch-mlir/install \
  -DLLVM_ENABLE_PROJECTS=mlir \
  -DLLVM_TARGETS_TO_BUILD=host \
  -DMLIR_ENABLE_BINDINGS_PYTHON=OFF \
  -DTORCH_MLIR_ENABLE_STABLEHLO=OFF \
  -DTORCH_MLIR_ENABLE_REFBACKEND=OFF \
  -DTORCH_MLIR_USE_INSTALLED_PYTORCH=OFF \
  -DTORCH_MLIR_ENABLE_PYTORCH_EXTENSIONS=OFF \
  externals/llvm-project/llvm
cmake --build ../../../build/torch-mlir --target install
cd ../..

Code Style

• Use clang-format with the repo .clang-format.
• Prefer static helpers in anonymous namespaces for file-local logic.
• Keep implementation details out of headers when possible.
• Use RAII and smart pointers for resource ownership.
• Prefer early returns over nested validation branches.

Testing

• Runtime tests use Google Test.
• Torch-MLIR pass tests use lit + FileCheck.
• When adding lit tests:
  • Align CHECK: colons vertically.
  • Capture SSA values as %[[NAME:.*]], not hardcoded %0.
  • Use CHECK-SAME to split long signatures.

Worktree And Bead Workflow

Use the beads tracker as the durable task log and source of truth:

• Claim and update work with br.
• Create one git worktree per bead.
• Do not implement features directly on the main checkout.
• Record decisions, PR links, and review outcomes in bead comments so the workflow does not depend on private chat memory.

Recommended branch pattern:

• users/<author>/<branchName>
• Example: users/MaheshRavishankar/addClangFormat

Durable Memory In Codex

Claude's agentic-memory does not have a direct repo-local equivalent here. For Codex, treat these as persistent memory:

• br show, br comments, and bead status
• git history and worktree names
• PR descriptions and review comments
• repo docs under docs/

If a decision matters later, write it down in one of those places.

Codex Workflow

Codex-specific reusable workflows live in the repo-local plugin:

• plugins/hipdnnep-codex/

That plugin provides skills for:

• implementer
• pm
• review

Use the Codex sandbox launcher for isolated implementer work:

scripts/hipdnn-codex-sandbox.sh <bead-id> -- "<codex-args...>"

The Claude workflow remains available through scripts/hipdnn-sandbox.sh.