TheRock/rocm-libraries/projects/hipdnn/samples/knobs/README.md

hipDNN Knobs Usage Sample

This sample demonstrates how to use hipDNN's engine configuration knobs system.

What are Knobs?

Knobs are runtime-configurable parameters that control engine behavior, performance tuning, and feature selection. They allow you to:

• Enable/disable features (e.g., benchmarking mode)
• Tune performance parameters (e.g., workspace size limits)
• Select algorithmic variants
• Control memory usage

What This Sample Demonstrates

1. Querying Available Knobs: How to discover what knobs an engine supports
2. Knob Metadata: Understanding knob types, constraints, and default values
3. Setting Knob Values: Creating execution plans with custom knob settings
4. Knob Validation: Validating settings against knob constraints
5. Knob Value Types: Using integer, float, and string knobs
6. Real Execution: Running graphs with different knob configurations

Building

The sample is built as part of the hipDNN samples:

cd /path/to/hipdnn/samples/build
cmake ..
make knobs_usage

Running

Basic Usage

./knobs_usage

This runs all demonstrations including actual graph executions.

Skip Execution Examples

To see knob API demonstrations without running graphs:

./knobs_usage --skip-execution

This is faster and useful when you only want to learn about the knob API.

Help

./knobs_usage --help

Sample Output

The sample produces detailed output organized into sections:

=========================================
  hipDNN Knobs Usage Sample
=========================================

1. Querying Available Knobs
   - Lists all knobs for an engine
   - Shows knob metadata (type, description, constraints, defaults)

2. Using Knob Lookup Map
   - Demonstrates map-based knob lookup
   - Shows how to find specific knobs by ID

3. Using Default Knob Values
   - Creates execution plan with defaults
   - Demonstrates simplest knob usage

4. Setting Custom Knob Values
   - Shows how to set integer knob values
   - Demonstrates creating plans with custom settings

5. Knob Validation
   - Validates settings against constraints
   - Shows both valid and invalid examples

6. Different Knob Value Types
   - Integer knobs (int64_t)
   - Float knobs (double)
   - String knobs

7. Execution with Default Knobs
   - Runs actual batchnorm graph with defaults

8. Execution with Benchmarking Enabled
   - Runs graph with global.benchmarking=1

Key Code Patterns

Query Available Knobs

std::vector<Knob> knobs;
auto error = graph.get_knobs_for_engine(engineId, knobs);

for (const auto& knob : knobs) {
    std::cout << knob.knobId() << ": " << knob.description() << "\n";
}

Set Custom Knob Values

std::vector<KnobSetting> settings;
settings.emplace_back("global.benchmarking", 1);
settings.emplace_back("global.workspace_size_limit", 64 * 1024 * 1024);

auto error = graph.create_execution_plan_ext(engineId, settings);

Validate Knob Settings

KnobSetting setting("global.benchmarking", 1);
auto validationError = knob.validate(setting);

if (validationError.is_good()) {
    std::cout << "Valid!\n";
}

Common Knobs

global.benchmarking

• Type: int64
• Default: 0 (disabled)
• Range: 0-1
• Purpose: Enable MIOpen kernel benchmarking for optimal performance

global.workspace_size_limit

• Type: int64
• Default: Maximum
• Range: Dynamic (operation-specific)
• Purpose: Limit workspace memory for convolution operations
• Note: Only available for convolution operations

Related Documentation

For comprehensive information about knobs:

• hipDNN Knobs Documentation - Complete guide with API reference
• HowTo Guide - Quick start guide
• Plugin Development Guide - For plugin authors
• MIOpen Provider Knobs - MIOpen-specific knobs

Notes

• The sample uses a batchnorm operation for demonstration, but knobs work with all operations
• Not all engines support all knobs; always query available knobs first
• Unknown knobs are ignored with a warning (not an error)
• Invalid knob values will cause execution plan creation to fail
• Knobs are set at execution plan creation time, not at execution time

Tips

1. Always query first: Use get_knobs_for_engine() to understand what's available
2. Check constraints: Look at the constraint object to understand valid ranges
3. Use defaults when possible: Only customize knobs when needed
4. Handle errors: Always check error return values when setting knobs
5. Read the docs: See the comprehensive documentation for advanced usage