Using the rocsys command (experimental)#
The rocprof-sys-* executables are the original ROCm Systems Profiler tools.
The other pages in this documentation show those commands.
The rocsys command is a new unified command-line entry point for profiling.
Running rocsys -- ./app or rocsys profile -- ./app produces a full trace
profile, and rocsys rewrite runs rocprof-sys-instrument in binary-rewrite
mode (-o). A rocsys subcommand selects the tool, and any arguments after the subcommand are
forwarded to the selected tool. rocsys --help reports that the command is
experimental and that commands and workflows are subject to change.
Usage#
rocsys -- ./app
rocsys profile -- ./app
rocsys <subcommand> [options] -- <app> [app-args]
rocsys --help
rocsys --version
rocsys <subcommand> --help
profile is the default. rocsys -- ./app and rocsys profile -- ./app
both produce a full trace profile, the same way rocprof-sys-run launches the
application. With no other flags, that records a rocpd trace of the default
ROCm domains and GPU telemetry.
It does not rewrite the binary, and it does not enable call-stack sampling or
an aggregated function profile. You can change the data that is collected by using
--preset or domain flags, as described in Using preset profiles and domain flags. Output
paths follow rocprof-sys-run; see Understanding the Systems Profiler output.
rocsys with no arguments prints the top-level help. rocsys --version
prints the version. Pass --help after profile to read the
rocprof-sys-run options, including presets:
rocsys profile --help
rocsys profile --preset=balanced -- ./app
Subcommands#
rocsys --help lists the verbs in this order.
Verb |
Description |
See also |
|---|---|---|
|
The default. Produces a full trace profile, using the same run mode as |
Using preset profiles and domain flags, Understanding the Systems Profiler output |
|
Queries the settings, domains, hardware counters, and components available on this system through |
|
|
Attaches to an already running process through |
|
|
Estimates how much faster the application would run if a selected function or line were sped up, through |
|
|
Instruments the application in memory and then runs it, through |
|
|
Writes an instrumented binary through |
|
|
Profiles a Python script through the |
Examples#
rocsys instrument -- ./app
rocsys rewrite -- ./app
rocsys profile -- ./app.inst
rocsys avail
rocsys avail -d
rocsys causal -l foo -- ./app
rocsys python -- ./script.py
rocsys attach -p $(pidof my_app)
instrument performs runtime instrumentation and does not write a new binary.
rewrite writes a new binary and exits. Profile that binary with
rocsys profile -- ./app.inst.
python forwards to the rocprof-sys-python helper. Its flags are the
ones on Profiling Python scripts, such as -b, -I, and -E.
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.
“Already in the current directory” means the resolved path is the current
directory plus the file’s basename. A relative path such as ./subdir/app
is handled like a target outside the current directory.
Target |
Default output |
|---|---|
|
|
A name with no extension, such as |
|
A local non-library whose name contains a dot, such as |
|
A library already in the current directory, such as |
|
A target outside the current directory, such as |
|
A library outside the current directory, such as |
|
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.
The instrumented/ directory is used only for a library whose resolved path
is the current directory plus its basename.
The default name is written in the current directory and can overwrite a file
that is already there. Rewriting /usr/bin/app writes ./app.
Pass -o, --output, -o=, or --output= to choose the path yourself:
rocsys rewrite -o app.inst -- ./app
rocsys rewrite --output=app.inst -- ./app
Call-stack sampling#
There is no sample subcommand. rocsys sample -- ./app reports an unknown
subcommand.
Call-stack sampling without instrumentation is rocprof-sys-sample.
See Sampling the call stack.
To turn call-stack sampling on during a profile run, pass --sample
(-S) or --cpu. --sample accepts a timer, cputime or
realtime. --cpu=50 sets the sampling frequency in Hz:
rocsys profile --sample -- ./my_app
rocsys profile --sample realtime -- ./my_app
rocsys profile --cpu=50 -- ./my_app
That keeps the run-tool collection and adds sampling. It does not switch to
rocprof-sys-sample.