TheRock/rocm-libraries/dnn-providers/miopen-provider/docs/ai-rules.md

alwaysApply

alwaysApply
true

AI Rules for MIOpen Provider Plugin

Project Overview

MIOpen Provider is a hipDNN plugin that wraps AMD's MIOpen library to provide GPU-accelerated deep learning operations. This plugin implements the hipDNN Plugin SDK interface to expose MIOpen kernels as execution engines.

hipDNN Context: hipDNN is a graph-based deep learning library for AMD GPUs with a plugin-based architecture. Plugins like this one implement the Plugin SDK to provide engine implementations that execute operation graphs.

Plugin Architecture

This plugin implements the following hipDNN Plugin SDK interfaces:

Interface	File	Purpose
Plugin API	PluginApi.h	Plugin metadata (name, version, type), error reporting, logging callbacks
Engine Plugin API	EnginePluginApi.h	Engine lifecycle - create handle, set stream, get engines, execute graphs
IEngine	EngineInterface.hpp	Engine interface - checks applicability, provides details, creates plans
IPlanBuilder	PlanInterface.hpp	Builds execution plans for specific operation patterns
IPlan	PlanInterface.hpp	Executable plan that runs operations on GPU

Execution Flow

FlatBuffer Graph → Engine Selection → Plan Creation → GPU Execution
       ↓                  ↓                 ↓              ↓
   IGraph API    isApplicable()     buildPlan()     execute()

1. Graph Analysis: Backend deserializes FlatBuffer graph, queries plugins for applicable engines
2. Engine Selection: Plugin's isApplicable() checks if any plan builder can handle the graph
3. Plan Building: Selected plan builder creates concrete IPlan instance with MIOpen setup
4. Execution: Plan's execute() launches MIOpen kernels on GPU

Component Linkage (Do Not Modify)

• Plugin uses: Plugin SDK (header-only), Data SDK (header-only), MIOpen library
• Plugin SDK uses: Data SDK
• Data SDK uses: FlatBuffers
• No direct dependencies on hipDNN Backend or Frontend

Key Classes

• HipdnnEnginePluginHandle: Plugin instance with MIOpen handle, stream, engine manager
• EngineManager: Manages available engines and routes requests to applicable engines
• MiopenEngine: Concrete engine with multiple plan builders for different operations
• HipdnnEnginePluginExecutionContext: Stores the execution plan for a graph
• Plan Builders: MiopenConvPlanBuilder, MiopenBatchnormPlanBuilder, etc.
• Plans: MiopenConvFwdPlan, MiopenBatchnormFwdPlan, etc.

---

Building & Testing

Build Commands

Via Superbuild (recommended):

cd <workspace>
cmake --preset miopen-provider
cmake --build build

This uses the miopen-provider preset which builds both hipDNN and miopen-provider together. Other available presets: hipdnn (hipDNN only), hipblaslt-provider (hipDNN + hipblaslt-provider).

In the superbuild, targets are prefixed and YAML category-driven (e.g., miopen-provider-check, miopen-provider-quick-check). See projects/hipdnn/docs/Superbuild.md for full details.

Standalone build (requires hipDNN installed):

cd <workspace>/dnn-providers/miopen-provider
mkdir -p build && cd build
cmake -GNinja -DCMAKE_PREFIX_PATH=<hipdnn-install-path> -DCMAKE_CXX_COMPILER=/opt/rocm/llvm/bin/clang++ ..
ninja

Test Binaries

Binary	Tests	Typical Use
miopen_plugin_tests	Plugin unit tests	Engine manager, plan builders, MIOpen integration
miopen_plugin_integration_tests	GPU integration tests	End-to-end operation execution

Running Specific Tests

Use --gtest_filter for fast iteration:

./bin/miopen_plugin_tests --gtest_filter="TestMiopenEngine.*"

When Modifying Code

Only build or run tests if explicitly requested in the user's prompt. Do not proactively run ninja, test binaries, or build commands unless asked.

When requested to build/test:

1. Rebuild with ninja (from build directory)
2. Run relevant tests using --gtest_filter for fast iteration

---

C++ Code Style

Naming Conventions

• CamelCase for class/struct names (e.g., MiopenEngine, ConvolutionPlanBuilder)
• camelCase for functions, variables, and private members (e.g., buildPlan(), engineId)
• Underscore prefix for private members (e.g., _miopenHandle, _planBuilders)

File Headers

• Copyright header on all source files: // Copyright © Advanced Micro Devices, Inc., or its affiliates. / // SPDX-License-Identifier: MIT
• #pragma once immediately after copyright in header files (.h, .hpp)

Code Practices

• Use auto with casts to avoid type duplication: auto tensor = static_cast<float*>(data)
• Use auto when initializing variables, unless the type is not obvious
• Avoid implicit casts — use explicit static_cast<>. The codebase compiles with -Wconversion and -Wsign-conversion
• Always use braces for if/for/while bodies, even single-line
• Use CMake for managing C/C++ dependencies
• Use Flatbuffers for serialization (via Data SDK wrapper classes: IGraph, GraphWrapper, etc.)

Testing

• Use Google Test (gtest) framework for all C/C++ tests
• Never generate a main() function in test files — gtest provides its own
• Use TEST(), TEST_F(), or TEST_P() macros as appropriate

Test Suite Naming

Rules apply to the TestSuite name (first param of TEST / TEST_F / TEST_P). TestCase (second param) should be PascalCase.

Composition (left → right):

1. Required Test (unit tests) or Integration (integration tests) prefix, always first
2. Optional Gpu immediately after Test/Integration if the test needs GPU support
3. Core Feature / Subject under test (PascalCase, no underscores)
4. Optional Datatype token: Bfp16, Fp16, Fp32

Omit any optional position that does not apply.

Unit tests: Mirror the class under test — TestMyClass or TestGpuMyClass if GPU is required.

Valid examples:

IntegrationGpuConvolutionFwdFp32   TestGpuMiopenEngineFp32
TestMiopenEngineManager            TestConvolutionPlanBuilder