TheRock/rocm-systems/projects/rocprofiler-compute/tools/config_management/README.md

ROCProfiler-Compute Configuration Management

This directory contains the authoritative configuration-management system for ROCProfiler-Compute analysis configurations.

It is designed to guarantee:

• Structural correctness across GPU architectures
• Byte-level immutability of panel YAMLs enforced via hashes
• CI enforcement of all invariants

All workflows are orchestrated by a single sequential driver script:

tools/config_management/master_config_workflow_script.py

Repository Layout

rocprofiler-compute/
├── src/rocprof_compute_soc/
│   └── analysis_configs/
│       ├── gfx908/
│       │   └── 0000_top_stats.yaml
│       ├── gfx90a/
│       ├── gfx940/
│       ├── gfx950/
│       ├── gfx115x/                     # RDNA 3.5 shared analysis configs
│       ├── gfx9_config_template.yaml    # CDNA (gfx9) panel contract
│       └── gfx11_config_template.yaml   # RDNA 3.5 (gfx115*) panel contract
│
└── tools/config_management/
    ├── master_config_workflow_script.py
    ├── parse_config_template.py
    ├── verify_against_config_template.py
    ├── hash_manager.py
    ├── hash_checker.py
    ├── .config_hashes.json
    └── README.md

Core Concepts

Panel YAMLs

• Live under:

analysis_configs/<arch>/*.yaml

• Must conform strictly to the template schema
• Are edited in-place using ruamel.yaml round-trip mode

Hash Database

• Stored at:

tools/config_management/.config_hashes.json

• Records md5 hashes of panel YAMLs per arch
• Machine-generated only
• Enforced by the pre-commit hash-check hook (see Automated Testing)

Architecture Diagram (End-to-End Flow)

                   ┌──────────────────────────┐
                   │  analysis_configs/       │
                   │  gfx9_config_template    │
                   └───────────┬──────────────┘
                               │
                               ▼
                 ┌───────────────────────────────┐
                 │ verify_against_config_template│
                 │ (structural validation)       │
                 └───────────┬───────────────────┘
                             │
                             ▼
                 ┌───────────────────────────────┐
                 │ hash_manager.py --compute-all │
                 │ (refresh .config_hashes.json) │
                 └───────────┬───────────────────┘
                             │
                             ▼
                 ┌───────────────────────────────┐
                 │ hash_checker.py               │
                 │ (panel-file hash consistency) │
                 └───────────────────────────────┘

Contributor Quick Start

Note

Required Python Dependency This configuration management system requires the ruamel.yaml Python package. It is used to safely modify YAML files while preserving comments, ordering, and formatting. The workflow scripts will not function correctly without it.

See Development dependencies for install instructions.

1. Validate the current state

Before making any config changes:

python tools/config_management/master_config_workflow_script.py --validate-only

This must pass.

2. Editing an existing architecture

Edit panel YAMLs directly under:

src/rocprof_compute_soc/analysis_configs/<arch>/

Rules:

• Preserve structure
• Preserve ordering
• Use multiline >- formatting for metric descriptions
• Do not regenerate entire files

After editing:

python tools/config_management/master_config_workflow_script.py --validate-only
python tools/config_management/hash_manager.py --compute-all src/rocprof_compute_soc/analysis_configs

The first command verifies structural conformance. The second refreshes the hash DB so hash_checker.py agrees.

3. Hash checks (fast local / CI)

python tools/config_management/master_config_workflow_script.py --hash-only

or:

python tools/config_management/master_config_workflow_script.py --ci

This runs panel-file hash validation only.

Automated Testing

Pre-commit Hash Consistency Hook

Hash integrity is enforced automatically by the pre-commit hash-check hook, which runs tools/config_management/hash_checker.py on every commit touching the project. The same script can be run manually from the project root:

python3 tools/config_management/hash_checker.py

This check:

• parses .config_hashes.json
• verifies byte-for-byte integrity of panel YAMLs
• fails on:
  • missing files
  • changed content
  • stale hash DB

Contributor Rules (Strict)

• Do not edit .config_hashes.json manually
• Do not regenerate full YAMLs unnecessarily
• Use in-place edits (ruamel round-trip)
• Expect CI to reject inconsistent states

Metric Descriptions

Metric descriptions flow unidirectionally from panel YAMLs to documentation:

Panel YAMLs (src/) → Per-Arch YAMLs (tools/) → Docs YAMLs (docs/) → Sphinx HTML

Files:

tools/per_arch_metric_definitions/
  ├── gfx{908,90a,942,950,1151}_metrics_description.yaml   # plain + rst + unit

docs/data/metrics/
  └── <arch>_metrics.yaml                                  # per-arch rst + unit (generated)

After editing panel metrics_description sections:

python tools/config_management/metric_description_manager.py --sync-all src/rocprof_compute_soc/analysis_configs
python tools/config_management/metric_description_manager.py --generate-docs

To regenerate the docs YAML for a single architecture without rewriting the others:

python tools/config_management/metric_description_manager.py --generate-docs --docs-arch <arch>

Manual RST edits: Edit per-arch YAMLs directly. The framework preserves an edit when its rst differs from plain.