ROCm Systems Profiler Workflows

Main entry point for working with the rocprofiler-systems project. Provides guidance on configuration, building, testing, and common development workflows.

Project Overview

rocprofiler-systems (formerly Omnitrace) is a comprehensive profiling and tracing tool for parallel applications (C, C++, Fortran, HIP, OpenCL, Python) on CPU and GPU.

Key characteristics:

• C++17 codebase with CMake build system
• Part of the rocm-systems monorepo (projects/rocprofiler-systems/)
• Uses CMakePresets.json for standard configurations
• Complex dependencies: Dyninst, Perfetto, TBB, Boost, elfutils
• Supports dynamic instrumentation, sampling, tracing, causal profiling

Output Formats

rocprofiler-systems supports two main output types:

Perfetto Output Modes

Perfetto format has two implementations:

Key differences:

• Standard: Uses trace caching, more robust, recommended for all use cases
• Legacy: Direct Perfetto write, has known timing bug where counter tracks aren't captured for workloads <0.5 seconds

When to Use

Use this skill when:

• User asks about rocprofiler-systems or rocprof-sys
• User wants to configure, build, or work with the project
• User needs guidance on project structure or workflows
• User asks "how do I build rocprofsys?"

Project Structure

rocm-systems/                          # Monorepo root
└── projects/
    └── rocprofiler-systems/           # Project root
        ├── CMakeLists.txt
        ├── CMakePresets.json          # Standard build configs
        ├── build/                     # Build directories
        │   ├── ci/                    # CI build
        │   ├── debug/                 # Debug build
        │   ├── release/               # Release build
        │   └── debug-optimized/       # RelWithDebInfo build
        ├── source/                    # Source code
        ├── external/                  # Third-party deps
        ├── examples/                  # Example programs
        ├── tests/                     # Test suite
        ├── scripts/
        │   └── build-release.sh       # Release build script
        └── docs/                      # Documentation

Common Workflows

1. First-Time Setup

For new developers or clean environment:

1. Find project location (in monorepo)
2. Configure with a preset → use rocprofsys-configure
3. Build the project → use rocprofsys-build
4. Run tests

2. Development Build

For active development with debugging:

1. Configure with debug preset
2. Build incrementally
3. Run specific tests

3. Release Build

For packaging or performance testing:

1. Configure with release preset
2. Build with optimizations
3. Create packages

4. Clean Rebuild

When dependencies change or build is corrupted:

1. Remove build directory
2. Reconfigure from scratch
3. Full rebuild

Available Skills

Workflow Dispatcher

When user asks about rocprofsys, determine intent and route:

Finding the Project

Since the project may be in different locations (worktrees, different branches), always find it dynamically:

Common locations:

• /home/amd/worktree/rocm-systems/*/projects/rocprofiler-systems
• ~/rocm-systems/projects/rocprofiler-systems
• Current directory (if already in project)

Detection strategy:

1. Check if current directory is inside rocprofiler-systems
2. Search common worktree locations
3. Ask user for project path

CMake Presets

The project uses CMakePresets.json with these standard configurations:

Key CMake Options

Common Environment Variables

Runtime Variables

Example Usage

# Standard Perfetto trace with GPU metrics
ROCPROFSYS_TRACE=1 \
ROCPROFSYS_AMD_SMI_METRICS="all" \
bin/rocprof-sys-run -- ./my-app

# Legacy Perfetto mode
ROCPROFSYS_TRACE=1 \
ROCPROFSYS_TRACE_LEGACY=true \
ROCPROFSYS_AMD_SMI_METRICS="all" \
bin/rocprof-sys-run -- ./my-app

# RocPD database output
ROCPROFSYS_USE_ROCPD=1 \
ROCPROFSYS_AMD_SMI_METRICS="all" \
bin/rocprof-sys-run -- ./my-app

# NIC/AINIC metrics with fake devices
AMDSMI_FAKE_AINIC=1 \
ROCPROFSYS_TRACE=1 \
ROCPROFSYS_SAMPLING_AINICS="all" \
bin/rocprof-sys-run -- ./my-app

Common Issues

Integration with Other Skills

Process

1. Determine user intent
   • What does the user want to do with rocprofsys?
   • Configure? Build? Test? Install? Debug?
2. Find project location
   • Check current directory
   • Search common locations
   • Ask user if needed
3. Route to appropriate skill
   • Configuration needs → rocprofsys-configure
   • Build needs → rocprofsys-build
   • Both → configure first, then build
4. Provide context
   • Show current build status (if any)
   • Suggest next steps
   • Link to documentation if needed

Example Interactions

User: "Build rocprofsys" Action: Check if configured → if not, invoke rocprofsys-configure → then invoke rocprofsys-build

User: "Debug build of rocprofiler-systems" Action: Invoke rocprofsys-configure with debug preset → invoke rocprofsys-build

User: "Clean and rebuild rocprofsys" Action: Remove build directory → invoke rocprofsys-configure → invoke rocprofsys-build

User: "How do I configure rocprofsys?" Action: Invoke rocprofsys-configure skill

Output

This skill produces:

• Guidance on which sub-skill to use
• Project status information
• Next steps recommendations

No files are created by this dispatcher skill.

Common Mistakes