Using the rocsys command

rocsys is the unified command-line entry point for ROCm Systems Profiler. A subcommand selects the tool. Flags after the subcommand are forwarded to that tool, including --help.

The existing rocprof-sys-* executables remain available and behave as before. Use them directly when a workflow page shows that command, or use the matching rocsys verb below.

Usage

rocsys -- ./app
rocsys profile -- ./app
rocsys <subcommand> [options] -- <app> [app-args]
rocsys --help
rocsys <subcommand> --help

rocsys with no arguments prints the top-level help. rocsys --version prints the version.

Subcommands

Verb	Runs	See also
profile	A full trace profile through rocprof-sys-run. This is also the default when the first argument is a flag or --.	Using preset profiles and domain flags, Instrumenting and rewriting a binary application
instrument	Runtime instrumentation through rocprof-sys-instrument.	Instrumenting and rewriting a binary application
rewrite	Binary rewrite through rocprof-sys-instrument. rocsys inserts -o when you do not pass an output path.	Instrumenting and rewriting a binary application
causal	rocprof-sys-causal	Performing causal profiling
avail	rocprof-sys-avail. An application argument is optional.	General tips for using ROCm Systems Profiler
python	rocprof-sys-python	Profiling Python scripts
attach	rocprof-sys-attach	Attaching to a running process

These two forms collect the same full trace profile:

rocsys -- ./app
rocsys profile -- ./app

rocsys profile with no application exits with an error. Pass --help to read the rocprof-sys-run options, including presets:

rocsys profile --help
rocsys profile --preset=balanced -- ./app

Default output for rewrite

rocsys rewrite -- ./app runs rocprof-sys-instrument -o -- ./app. When -o has no filename, the rewritten file is written in the current directory:

Target	Default output
./app, already in the current directory and not a library	./app.inst
A name with no extension, such as ./libfoo	./libfoo.inst
A library already in the current directory, such as ./libfoo.so	./instrumented/libfoo.so
A target outside the current directory, such as /usr/bin/app	./app

A target is treated as a library only when its basename contains a dot and either starts with lib, contains .so, or ends with .a. Pass -o, --output, or -o= to choose the path yourself:

rocsys rewrite -o app.inst -- ./app

Call-stack sampling

rocsys sample is not a subcommand and reports an unknown subcommand. Enable call-stack sampling while profiling with --sample:

rocsys --sample -- ./my_app
rocsys profile --sample -- ./my_app