TheRock/rocm-systems/projects/rocprofiler-systems/examples/README.md

rocprofiler-systems Examples

This directory contains example applications demonstrating various profiling scenarios with rocprofiler-systems. Each example targets a specific workload type - GPU compute, CPU threading, distributed computing, or library integration - and shows how to capture performance data using rocprof-sys-run.

Examples by Category

GPU Compute

Example	Description	Dependencies
transpose	Tiled matrix transpose on GPU with multi-threaded stream execution	HIP
unified-memory	Managed-memory workload that triggers KFD page fault and migration events and emits unified-memory profiling reports	HIP, XNACK-capable AMD GPU
scratch-memory	GPU scratch memory allocation stress test across primary and overflow slots	HIP, HSA
sdma-test	SDMA engine bandwidth benchmark for H2D, D2D, and D2H transfers	HIP
transferBench	All-to-all transfer benchmark across CPU, GPU, SDMA, and NIC executors	HIP, HSA

Profiler API

Example	Description	Dependencies
user-api	User API for named regions, annotations, and selective thread tracing	rocprofiler-systems user library
roctx	ROCTx range/marker API with thread naming, pause/resume, and device labeling	rocprofiler-sdk-roctx, HIP
causal	Causal profiling with slow/fast parallel workloads and progress point tracking	rocprofiler-systems user library
rewrite-caller	Minimal call chain for binary rewrite instrumentation testing	None
trace-time-window	Mixed CPU-bound and sleep workload for time-windowed trace analysis	None

CPU Threading

Example	Description	Dependencies
thread-limit	Thread scaling stress test with batched Fibonacci workers	pthreads
parallel-overhead	Mutex vs. atomic synchronization overhead comparison	pthreads
code-coverage	Dual code-path execution for coverage analysis testing	pthreads
fork	Multi-process forking from worker threads with child process profiling	pthreads

Distributed Computing

Example	Description	Dependencies
mpi	MPI collective and point-to-point operations with communicator patterns	MPI
rccl	RCCL collective communication performance tests across GPUs	HIP, RCCL
shmem	OpenSHMEM hello world and ping-pong latency benchmark	OpenSHMEM (oshcc)

OpenMP

Example	Description	Dependencies
openmp	NAS Parallel Benchmarks (CG, LU) with OpenMP threading	OpenMP

GPU Libraries

Example	Description	Dependencies
jpegdecode	Batch JPEG decoding performance benchmark using rocJPEG	HIP, rocJPEG
videodecode	Batch video decoding benchmark using ROCDecode with VCN hardware	HIP, ROCDecode, FFmpeg
hipfile	hipFILE (GPU-direct storage) API tracing demo	HIP, hipFILE, ROCProfiler-SDK 1.3.5+

HPC

Example	Description	Dependencies
lulesh	LULESH shock hydrodynamics mini-app with Kokkos parallelism	Kokkos, optional MPI
hpc	Six HPC training examples covering Jacobi solvers, matrix exponentials, and stream overlap	HIP, rocBLAS, Fortran (varies)

Python

Example	Description	Dependencies
python	Python profiling with decorators, user regions, and selective tracing	Python 3, optional NumPy

Building All Examples

• The examples are built as part of the rocprofiler-systems CMake project.
• They can also be built as standalone applications or as part of the full examples suite.
• The following commands build the full examples suite.

From the examples directory run:

cmake -B <build_dir> \
    -DCMAKE_PREFIX_PATH=/opt/rocm \
    -DCMAKE_INSTALL_PREFIX=./install \
    .

cmake --build <build_dir> --parallel

Or from the repository root:

cmake -B <build_dir> \
    -DCMAKE_PREFIX_PATH=/opt/rocm \
    projects/rocprofiler-systems/examples

cmake --build <build_dir> --parallel

Individual examples can be built by specifying the target:

cmake --build <build_dir> --target <example_name>

GPU examples require ROCm (hipcc or amdclang++) and detect available architectures automatically. To specify architectures manually:

cmake -B <build_dir> -DROCPROFSYS_GFX_TARGETS="gfx90a;gfx942" ...

Profiling Modes

rocprofiler-systems supports several instrumentation modes:

Mode	Command	Description
System-level	rocprof-sys-run -- ./app	Lightweight tracing via LD_PRELOAD, no binary modification
Binary rewrite	rocprof-sys-instrument -o app.inst -- ./app then rocprof-sys-run -- ./app.inst	Statically rewrite the binary for repeated profiling
Runtime instrument	rocprof-sys-instrument -- ./app	Dynamically instrument at launch without modifying the binary
Sampling	rocprof-sys-sample -- ./app	Statistical sampling of call stacks at configurable frequency
Causal	rocprof-sys-causal -- ./app	Causal profiling to identify optimization opportunities

Common Environment Variables

Variable	Description	Default
ROCPROFSYS_TRACE	Enable Perfetto trace output	true
ROCPROFSYS_PROFILE	Enable call-stack profile output	true
ROCPROFSYS_USE_ROCPD	Generate rocpd database output	false
ROCPROFSYS_USE_SAMPLING	Enable statistical sampling	false
ROCPROFSYS_SAMPLING_FREQ	Sampling frequency (interrupts/sec)	50
ROCPROFSYS_USE_PROCESS_SAMPLING	Enable process-level resource sampling	true
ROCPROFSYS_OUTPUT_PATH	Base directory for output files	rocprofsys-output
ROCPROFSYS_TIME_OUTPUT	Timestamp output subdirectories	true
ROCPROFSYS_ROCM_DOMAINS	ROCm API domains to trace	all
ROCPROFSYS_USE_MPIP	Enable MPI profiling interposition	false