AI/rocm-systems
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update installation and ROCPD documentation (#1300)

Browse Source 
* Updating install doc page

* Removing the Quick Start page

* Add documentation for rocpd output

* Update links to reference rocm-systems repo

* Update README.md

Installation instructions references ROCm Docs link.

* Updated git clone instructions

Back to using https to clone the repository

* Fix formatting

* Update projects/rocprofiler-systems/docs/how-to/understanding-rocprof-sys-output.rst

* Add reference to "rocpd" section to the "Profiling Python" section

* Update CONTRIBUTING.md

* For ROCPD, document minimum version of SDK.

* Update CHANGELOGS

Signed-off-by: David Galiffi <David.Galiffi@amd.com>

* Update CHANGELOG.md

Updated based on feedback from docs team

* Update CONTRIBUTING.md

* Update CONTRIBUTING.md.

Simplify and remove setup information overlapping with the "rocm-systems" contributing documentation.

* Apply suggestion from @prbasyal-amd

Co-authored-by: Pratik Basyal <pratik.basyal@amd.com>

* Apply suggestion from @prbasyal-amd

Co-authored-by: Pratik Basyal <pratik.basyal@amd.com>

* Update CHANGELOG.md

* Apply suggestion from @prbasyal-amd

Co-authored-by: Pratik Basyal <pratik.basyal@amd.com>

* Apply suggestion from @prbasyal-amd

Co-authored-by: Pratik Basyal <pratik.basyal@amd.com>

* Apply suggestion from @prbasyal-amd

Co-authored-by: Pratik Basyal <pratik.basyal@amd.com>

* Apply suggestion from @prbasyal-amd

Co-authored-by: Pratik Basyal <pratik.basyal@amd.com>

* Apply suggestion from @prbasyal-amd

Co-authored-by: Pratik Basyal <pratik.basyal@amd.com>

* Apply suggestion from @prbasyal-amd

Co-authored-by: Pratik Basyal <pratik.basyal@amd.com>

* Apply suggestion from @prbasyal-amd

Co-authored-by: Pratik Basyal <pratik.basyal@amd.com>

* Apply suggestion from @prbasyal-amd

Co-authored-by: Pratik Basyal <pratik.basyal@amd.com>

* Apply suggestion from @prbasyal-amd

Co-authored-by: Pratik Basyal <pratik.basyal@amd.com>

---------

Signed-off-by: David Galiffi <David.Galiffi@amd.com>
Co-authored-by: Pratik Basyal <pratik.basyal@amd.com>
This commit is contained in:
David Galiffi
2025-10-15 23:11:46 -04:00
committed by GitHub
parent 02bf0a8492
commit b75423b173
17 changed files with 161 additions and 303 deletions
Download Patch File Download Diff File Expand all files Collapse all files
projects/rocprofiler-systems/docs/conceptual/rocprof-sys-feature-set.rst
+1 -1
View File
@@ -6,7 +6,7 @@
ROCm Systems Profiler features and use cases
********************************************
`ROCm Systems Profiler <https://github.com/ROCm/rocprofiler-systems>`_ is designed to be highly extensible.
`ROCm Systems Profiler <https://github.com/ROCm/rocm-systems/tree/develop/projects/rocprofiler-systems>`_ is designed to be highly extensible.
Internally, it leverages the `Timemory performance analysis toolkit <https://github.com/ROCm/timemory>`_
to manage extensions, resources, data, and other items. It supports the following features,
modes, metrics, and APIs.
projects/rocprofiler-systems/docs/how-to/configuring-runtime-options.rst
+1 -1
View File
@@ -7,7 +7,7 @@ Configuring runtime options
****************************************************
The ``rocprof-sys.cfg`` file maintains a list of the
`ROCm Systems Profiler <https://github.com/ROCm/rocprofiler-systems>`_ runtime
`ROCm Systems Profiler <https://github.com/ROCm/rocm-systems/tree/develop/projects/rocprofiler-systems>`_ runtime
options. To create this configuration
file and view the current runtime options, use the ``rocprof-sys-avail`` executable.
projects/rocprofiler-systems/docs/how-to/configuring-validating-environment.rst
+1 -1
View File
@@ -6,7 +6,7 @@
Configuring and validating the environment
****************************************************
After installing `ROCm Systems Profiler <https://github.com/ROCm/rocprofiler-systems>`_, additional steps are required to set up
After installing `ROCm Systems Profiler <https://github.com/ROCm/rocm-systems/tree/develop/projects/rocprofiler-systems>`_, additional steps are required to set up
and validate the environment.
.. note::
projects/rocprofiler-systems/docs/how-to/nic-profiling.rst
+1 -1
View File
@@ -6,7 +6,7 @@
Network performance profiling
********************************************
`ROCm Systems Profiler <https://github.com/ROCm/rocprofiler-systems>`_ supports network profiling.
`ROCm Systems Profiler <https://github.com/ROCm/rocm-systems/tree/develop/projects/rocprofiler-systems>`_ supports network profiling.
All network events that can be traced on the system can be listed by running the command:
projects/rocprofiler-systems/docs/how-to/performing-causal-profiling.rst
+1 -1
View File
@@ -79,7 +79,7 @@ Causal profiling requires "progress points" to track progress through the code
in between samples. Progress points must be triggered in a deterministic manner via instrumentation.
This can happen in three different ways:
* `ROCm Systems Profiler <https://github.com/ROCm/rocprofiler-systems>`_ can leverage the callbacks from
* `ROCm Systems Profiler <https://github.com/ROCm/rocm-systems/tree/develop/projects/rocprofiler-systems>`_ can leverage the callbacks from
Kokkos-Tools, OpenMP-Tools, rocprofiler-sdk, etc. and the wrappers around functions for
MPI, NUMA, RCCL, etc. to act as progress points
* Users can leverage the :doc:`runtime instrumentation capabilities <./instrumenting-rewriting-binary-application>`
projects/rocprofiler-systems/docs/how-to/profiling-python-scripts.rst
+4 -4
View File
@@ -6,7 +6,7 @@
Profiling Python scripts
****************************************************
`ROCm Systems Profiler <https://github.com/ROCm/rocprofiler-systems>`_ supports profiling Python code at the
`ROCm Systems Profiler <https://github.com/ROCm/rocm-systems/tree/develop/projects/rocprofiler-systems>`_ supports profiling Python code at the
source level and the script level.
Python support is enabled via the ``ROCPROFSYS_USE_PYTHON`` and the
``ROCPROFSYS_PYTHON_VERSIONS="<MAJOR>.<MINOR>`` CMake options.
@@ -30,9 +30,9 @@ be the same size.
.. note::
ROCm Systems Profiler has limited support for Artificial Intelligence (AI) and Machine Learning (ML) workloads.
Data from child threads is not captured. For other profiling options,
see `rocprofV3 <https://rocm.docs.amd.com/projects/rocprofiler-sdk/en/latest/how-to/using-rocprofv3.html#using-rocprofv3>`_.
Direct Perfetto output (using `--trace` or `ROCPROFSYS_USE_TRACE=ON`) has limited support for Artificial Intelligence (AI) and Machine Learning (ML) workloads.
Data from child threads is not captured. Instead, use ROCPD (`ROCPROFSYS_USE_ROCPD=ON`) as the output type.
For more information, see the :ref:`_rocprof_sys_rocpd_output` section.
Getting started
========================================
projects/rocprofiler-systems/docs/how-to/sampling-call-stack.rst
+1 -2
View File
@@ -6,7 +6,7 @@
Sampling the call stack
****************************************************
`ROCm Systems Profiler <https://github.com/ROCm/rocprofiler-systems>`_ can use call-stack sampling
`ROCm Systems Profiler <https://github.com/ROCm/rocm-systems/tree/develop/projects/rocprofiler-systems>`_ can use call-stack sampling
on a binary instrumented with either the ``rocprof-sys`` executable
or the ``rocprof-sys-sample`` executable.
For example, all of the following commands are effectively equivalent:
@@ -410,4 +410,3 @@ Here is the full output from the previous
[rocprof-sys][1785877][metadata]> Outputting 'rocprof-sys-output/2024-07-15_16.21/parallel-overhead-locksmetadata-1785877.json' and 'rocprof-sys-output/2024-07-15_16.21/parallel-overhead-locksfunctions-1785877.json'
[rocprof-sys][1785877][0][rocprofsys_finalize] Finalized: 0.054582 sec wall_clock, 0.000 MB peak_rss, -1.798 MB page_rss, 0.040000 sec cpu_clock, 73.3 % cpu_util
[989.312] perfetto.cc:60128 Tracing session 1 ended, total sessions:0
projects/rocprofiler-systems/docs/how-to/understanding-rocprof-sys-output.rst
+52 -42
View File
@@ -1,12 +1,12 @@
.. meta::
:description: ROCm Systems Profiler system output documentation and reference
:keywords: rocprof-sys, rocprofiler-systems, Omnitrace, ROCm, profiler, system output, tracking, visualization, tool, Instinct, accelerator, AMD
:keywords: rocprof-sys, rocprofiler-systems, Omnitrace, ROCm, profiler, system output, tracking, visualization, tool, Instinct, accelerator, AMD, rocpd, perfetto, timemory
****************************************************
Understanding the Systems Profiler output
****************************************************
The general output form of `ROCm Systems Profiler <https://github.com/ROCm/rocprofiler-systems>`_ is
The general output form of `ROCm Systems Profiler <https://github.com/ROCm/rocm-systems/tree/develop/projects/rocprofiler-systems>`_ is
``<OUTPUT_PATH>[/<TIMESTAMP>]/[<PREFIX>]<DATA_NAME>[-<OUTPUT_SUFFIX>].<EXT>``.
For example, starting with the following base configuration:
@@ -157,33 +157,6 @@ Metadata JSON Sample
"inode": 0,
"pathname": "/opt/rocm/lib/libhsa-runtime64.so.1"
},
{
"load_address": "76005b935000",
"last_address": "76005b9aeab8",
"permissions": "r---",
"offset": "135000",
"device": "",
"inode": 0,
"pathname": "/opt/rocm/lib/libhsa-runtime64.so.1"
},
{
"load_address": "76005b9b0638",
"last_address": "76005bb2d598",
"permissions": "rw--",
"offset": "1af638",
"device": "",
"inode": 0,
"pathname": "/opt/rocm/lib/libhsa-runtime64.so.1"
},
{
"load_address": "76005bc00000",
"last_address": "76005bc26140",
"permissions": "r---",
"offset": "0",
"device": "",
"inode": 0,
"pathname": "/opt/rocm/lib/librocprofiler-sdk.so.0"
},
{
"... etc. ..."
}
@@ -227,18 +200,6 @@ Metadata JSON Sample
]
},
"environment": [
{
"key": "GOTCHA_DEBUG",
"value": "0"
},
{
"key": "HIP_VISIBLE_DEVICES",
"value": ""
},
{
"key": "HOME",
"value": "/home/rocm-dev"
},
{
"key": "LD_LIBRARY_PATH",
"value": "/home/rocm-dev/code/rocprofiler-systems/build/ubuntu/22.04/lib:/opt/rocm/lib"
@@ -358,7 +319,56 @@ set ``ROCPROFSYS_OUTPUT_PREFIX="%argt%-"``, and let ROCm Systems Profiler cleanl
an ``%arg0%`` of ``/usr/bin/foo`` translates to ``usr_bin_foo``. Additionally, any ``%arg<N>%`` keys which
do not have a command line argument at position ``<N>`` are ignored.
Perfetto output
.. _rocprof_sys_rocpd_output:
ROCm Profiling Data (rocpd) output
=========================================
Use the ``ROCPROFSYS_USE_ROCPD`` setting to trigger the ROCm Systems Profiler to output a
SQLite3 database. The ROCm Profiling Data (or ``rocpd``) database will soon be the default output
format. To output in `rocpd` format, ROCProfiler-SDK version 1.0.0 or later is required (introduced in ROCm 7.0.0).
Features of rocpd format
-----------------------------------------------
- **Comprehensive Data Model**: Consolidates all profiling artifacts including
execution traces, performance counters, hardware metrics, and contextual metadata
within a single SQLite3 database file (`.db` extension).
- **Standards-Compliant Access**: Supports querying through industry-standard SQL
interfaces including command-line tools (``sqlite3`` CLI), programming language
bindings (Python ``sqlite3`` module, C/C++ SQLite API), and database management
applications.
- **Advanced Analytics Integration**: Facilitates sophisticated post-processing
workflows through custom analytical scripts, automated reporting systems, and
integration with third-party visualization and analysis frameworks that provide
SQLite3 connectivity.
Generating rocpd Output
+++++++++++++++++++++++
To generate profiling data in the rocpd format, add "ROCPROFSYS_USE_ROCPD=ON" to your profiling configuration.
.. code-block:: shell
export ROCPROFSYS_USE_ROCPD=ON
export ROCPROFSYS_USE_TRACE=OFF # disabling default Perfetto output
rocprof-sys-sample -- ./your_application
See :doc:`configuring runtime options <./configuring-runtime-options>` for additional
details on setting up the profiling configuration options.
Converting rocpd to Alternative Formats
+++++++++++++++++++++++++++++++++++++
ROCm provides a Python module to convert the ``rocpd`` database to alternative
output formats for specialized analysis and visualization workflows. For example,
(Open Trace Format 2) OTF2, Perfetto Protocol Buffers (PFTrace), and
Comma-Separated Values (CSV) tables.
See `rocpd tool documentation <https://github.com/ROCm/rocm-systems/blob/develop/projects/rocprofiler-sdk/source/docs/how-to/using-rocpd-output-format.rst>`_
for additional information on these conversion tools.
Native Perfetto output
========================================
Use the ``ROCPROFSYS_OUTPUT_FILE`` to specify a specific location. If this is an
projects/rocprofiler-systems/docs/how-to/vcn-jpeg-sampling.rst
+3 -3
View File
@@ -6,7 +6,7 @@
VCN and JPEG activity sampling and tracing
********************************************
`ROCm Systems Profiler <https://github.com/ROCm/rocprofiler-systems>`_ supports
`ROCm Systems Profiler <https://github.com/ROCm/rocm-systems/tree/develop/projects/rocprofiler-systems>`_ supports
sampling of VCN and JPEG engines activities. It allows you to gather key performance metrics for
VCN utilization and understand engine usage through visualization. This information can be used
to optimize media and video workloads. Additionally, it supports tracing of `rocDecode
@@ -47,7 +47,7 @@ Alternatively, you can use the following to collect all available GPU metrics:
API tracing support
=====================
Tracing of rocDecode and rocJPEG APIs is supported by leveraging `ROCprofiler-SDK <https://rocm.docs.amd.com/projects/rocprofiler-sdk/en/latest/index.html>`_
Tracing of rocDecode and rocJPEG APIs is supported by leveraging `ROCprofiler-SDK <https://rocm.docs.amd.com/projects/rocprofiler-sdk/en/latest/index.html>`_
which provides runtime-independent APIs for tracing the runtime calls and asynchronous activities associated with decoder activities and workload in VCN and JPEG engines.
To enable tracing for the rocDecode and rocJPEG APIs, update the ``ROCPROFSYS_ROCM_DOMAINS`` variable. The default value is:
@@ -157,4 +157,4 @@ To view the generated ``.proto`` file in the browser, open the
Duplicate the images to generate enough workload to see activity in the trace
.. image:: ../data/rocprof-sys-jpeg-activity.png
:alt: Visualization of a performance graph in Perfetto with JPEG Activity tracks
:alt: Visualization of a performance graph in Perfetto with JPEG Activity tracks
projects/rocprofiler-systems/docs/index.rst
+2 -3
View File
@@ -11,7 +11,7 @@ of applications running on the CPU or the CPU and GPU. It supports dynamic binar
instrumentation, call-stack sampling, and various other features for determining
which function and line number are currently executing. To learn more, see :doc:`what-is-rocprof-sys`
ROCm Systems Profiler is open source and hosted at `<https://github.com/ROCm/rocprofiler-systems>`__.
ROCm Systems Profiler is open source and hosted at `<https://github.com/ROCm/rocm-systems>`__.
It is the successor to `<https://github.com/ROCm/omnitrace>`__.
.. grid:: 2
@@ -19,7 +19,6 @@ It is the successor to `<https://github.com/ROCm/omnitrace>`__.
.. grid-item-card:: Install
* :doc:`Quick start <./install/quick-start>`
* :doc:`ROCm Systems Profiler installation <./install/install>`
Use the following topics to learn more about the advantages of ROCm Systems Profiler in application
@@ -62,7 +61,7 @@ profiling, how it supports performance analysis, and how to leverage its capabil
.. grid-item-card:: Tutorials
* `GitHub examples <https://github.com/ROCm/rocprofiler-systems/tree/amd-mainline/examples>`_
* `GitHub examples <https://github.com/ROCm/rocm-systems/tree/develop/projects/rocprofiler-systems/examples>`_
* :doc:`Video tutorials <./tutorials/video-tutorials>`
To contribute to the documentation, refer to
projects/rocprofiler-systems/docs/install/install.rst
+49 -101
View File
@@ -6,116 +6,64 @@
ROCm Systems Profiler installation
*************************************
The following information builds on the guidelines in the :doc:`Quick start <./quick-start>` guide.
It covers how to install `ROCm Systems Profiler <https://github.com/ROCm/rocprofiler-systems>`_ from
source or a binary distribution, as well as the :ref:`post-installation-steps`.
If you have problems using ROCm Systems Profiler after installation,
consult the :ref:`post-installation-troubleshooting` section.
Release links
========================================
To review and install either the current ROCm Systems Profiler release or earlier releases, use these links:
* Latest ROCm Systems Profiler Release: `<https://github.com/ROCm/rocprofiler-systems/releases/latest>`_
* All ROCm Systems Profiler Releases: `<https://github.com/ROCm/rocprofiler-systems/releases>`_
Operating system support
========================================
ROCm Systems Profiler is only supported on Linux. The following distributions are tested in the ROCm Systems Profiler GitHub workflows:
* Ubuntu 20.04
* Ubuntu 22.04
* OpenSUSE 15.5
* OpenSUSE 15.6
* Red Hat 8.8
* Red Hat 8.9
* Red Hat 8.10
* Red Hat 9.2
* Red Hat 9.3
* Red Hat 9.4
Other OS distributions might function but are not supported or tested.
ROCm Systems Profiler is only supported on Linux. See
`Supported operating systems <https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html#supported-operating-systems>`_
for ROCm supported operating systems.
Identifying the operating system
-----------------------------------
If you are unsure of the operating system and version, the ``/etc/os-release`` and
``/usr/lib/os-release`` files contain operating system identification data for Linux systems.
If you are unsure of the Linux distribution and version, the ``/etc/os-release`` and
``/usr/lib/os-release`` files contain this information.
.. code-block:: shell
$ cat /etc/os-release
.. code-block:: shell
NAME="Ubuntu"
VERSION="20.04.4 LTS (Focal Fossa)"
VERSION_ID="24.04"
VERSION="24.04.3 LTS (Noble Numbat)"
VERSION_CODENAME=noble
ID=ubuntu
...
VERSION_ID="20.04"
...
The relevant fields are ``ID`` and the ``VERSION_ID``.
Architecture
========================================
Install via package manager
============================
With regards to instrumentation, at present only AMD64 (x86_64) architectures are tested. However,
Dyninst supports several more architectures and ROCm Systems Profiler instrumentation may support other
CPU architectures such as aarch64 and ppc64.
Other modes of use, such as sampling and causal profiling, are not dependent on Dyninst and therefore
might be more portable.
If you have ROCm version 6.3 or higher installed, you can use the
package manager to install a pre-built copy of ROCm Systems Profiler.
Installing ROCm Systems Profiler from binary distributions
==========================================================
.. tab-set::
Every ROCm Systems Profiler release provides binary installer scripts of the form:
.. tab-item:: Ubuntu
.. code-block:: shell
.. code-block:: shell
rocprof-sys-{VERSION}-{OS_DISTRIB}-{OS_VERSION}[-ROCm-{ROCM_VERSION}[-{EXTRA}]].sh
$ sudo apt install rocprofiler-systems
For example,
.. tab-item:: Red Hat Enterprise Linux
.. code-block:: shell
.. code-block:: shell
rocprof-sys-1.0.0-ubuntu-18.04-OMPT-PAPI-Python3.sh
rocprof-sys-1.0.0-ubuntu-18.04-ROCm-405000-OMPT-PAPI-Python3.sh
...
rocprof-sys-1.0.0-ubuntu-20.04-ROCm-50000-OMPT-PAPI-Python3.sh
$ sudo dnf install rocprofiler-systems
Any of the ``EXTRA`` fields with a CMake build option
(for example, PAPI, as referenced in a following section) or
with no link requirements (such as OMPT) have
self-contained support for these packages.
.. tab-item:: SUSE Linux Enterprise Server
To install ROCm Systems Profiler using a binary installer script, follow these steps:
.. code-block:: shell
#. Download the appropriate binary distribution
.. code-block:: shell
wget https://github.com/ROCm/rocprofiler-systems/releases/download/v<VERSION>/<SCRIPT>
#. Create the target installation directory
.. code-block:: shell
mkdir /opt/rocprofiler-systems
#. Run the installer script
.. code-block:: shell
./rocprofiler-systems-1.0.0-ubuntu-18.04-ROCm-405000-OMPT-PAPI.sh --prefix=/opt/rocprofiler-systems --exclude-subdir
$ sudo zypper install rocprofiler-systems
Building ROCm Systems Profiler from source
==========================================
ROCm Systems Profiler needs a GCC compiler with full support for C++17 and CMake v3.16 or higher.
ROCm Systems Profiler needs a GCC compiler with full support for C++17 and CMake v3.21 or higher.
The Clang compiler may be used instead of the GCC compiler if `Dyninst <https://github.com/dyninst/dyninst>`_
is already installed.
@@ -127,16 +75,15 @@ Build requirements
* Older GCC compilers may be supported but are not tested
* Clang compilers are generally supported for ROCm Systems Profiler but not Dyninst
* `CMake <https://cmake.org/>`_ v3.16+
* `CMake <https://cmake.org/>`_ v3.21 or later
.. note::
* If the installed version of CMake is too old, installing a new version of CMake can be done through several methods
* One of the easiest options is to use the python ``pip`` utility, as follows:
If the ``CMake`` installed on the system is too old, you can install a new
version using various methods. One of the easiest options is to use PyPi (Python's pip).
.. code-block:: shell
pip install --user 'cmake==3.18.4'
pip install --user 'cmake==3.21.0'
export PATH=${HOME}/.local/bin:${PATH}
Required third-party packages
@@ -152,6 +99,7 @@ Required third-party packages
* `OpenMP <https://www.openmp.org/>`_ (optional)
* `libunwind <https://www.nongnu.org/libunwind/>`_ for call-stack sampling
* `SQLite <https://github.com/sqlite/sqlite>`_ for database output
Any of the third-party packages required by Dyninst, along with Dyninst itself, can be built and installed
during the ROCm Systems Profiler build. The following list indicates the package, the version,
@@ -161,8 +109,9 @@ while Dyninst requires TBB), and the CMake option to build the package alongside
.. csv-table::
:header: "Third-Party Library", "Minimum Version", "Required By", "CMake Option"
"Dyninst", "12.0", "ROCm Systems Profiler", "``ROCPROFSYS_BUILD_DYNINST`` (default: OFF)"
"Dyninst", "13.0", "ROCm Systems Profiler", "``ROCPROFSYS_BUILD_DYNINST`` (default: OFF)"
"Libunwind", "", "ROCm Systems Profiler", "``ROCPROFSYS_BUILD_LIBUNWIND`` (default: ON)"
"SQLite", "", "ROCm Systems Profiler", "``ROCPROFSYS_BUILD_SQLITE`` (default: OFF)"
"TBB", "2018.6", "Dyninst", "``ROCPROFSYS_BUILD_TBB`` (default: OFF)"
"ElfUtils", "0.178", "Dyninst", "``ROCPROFSYS_BUILD_ELFUTILS`` (default: OFF)"
"LibIberty", "", "Dyninst", "``ROCPROFSYS_BUILD_LIBIBERTY`` (default: OFF)"
@@ -174,7 +123,6 @@ Optional third-party packages
* `ROCm <https://rocm.docs.amd.com/projects/install-on-linux/en/latest>`_
* HIP
* AMD SMI Lib for GPU monitoring
* ROCprofiler SDK for GPU hardware counters and ROCm tracing
@@ -186,16 +134,14 @@ Optional third-party packages
(By default, if ROCm Systems Profiler cannot find an OpenMPI MPI distribution, it uses a local copy
of the OpenMPI ``mpi.h``.)
* Several optional third-party profiling tools supported by Timemory
(for example, `Caliper <https://github.com/LLNL/Caliper>`_, `TAU <https://www.cs.uoregon.edu/research/tau/home.php>`_, CrayPAT, and others)
.. csv-table::
:header: "Third-Party Library", "CMake Enable Option", "CMake Build Option"
:widths: 15, 45, 40
:header: "Third-Party Library", "CMake Enable Option"
:widths: 15, 45
"PAPI", "``ROCPROFSYS_USE_PAPI`` (default: ON)", "``ROCPROFSYS_BUILD_PAPI`` (default: ON)"
"MPI", "``ROCPROFSYS_USE_MPI`` (default: OFF)", ""
"MPI (header-only)", "``ROCPROFSYS_USE_MPI_HEADERS`` (default: ON)", ""
"ROCm", "``ROCPROFSYS_USE_ROCM`` (default: ON)"
"PAPI", "``ROCPROFSYS_USE_PAPI`` (default: ON)"
"MPI", "``ROCPROFSYS_USE_MPI`` (default: OFF)"
"MPI (header-only)", "``ROCPROFSYS_USE_MPI_HEADERS`` (default: ON)"
Installing Dyninst
-----------------------------------
@@ -209,13 +155,15 @@ To install Dyninst alongside ROCm Systems Profiler, configure ROCm Systems Profi
Depending on the version of Ubuntu, the ``apt`` package manager might have current enough
versions of the Dyninst Boost, TBB, and LibIberty dependencies
(use ``apt-get install libtbb-dev libiberty-dev libboost-dev``).
However, it is possible to request Dyninst to build and install
its dependencies via ``ROCPROFSYS_BUILD_<DEP>=ON``, as follows:
However, it is possible to also build and install the Dyninst dependencies
via ``ROCPROFSYS_BUILD_<DEP>=ON``, as follows:
.. code-block:: shell
git clone https://github.com/ROCm/rocprofiler-systems.git rocprof-sys-source
cmake -B rocprof-sys-build -DROCPROFSYS_BUILD_DYNINST=ON -DROCPROFSYS_BUILD_{TBB,ELFUTILS,BOOST,LIBIBERTY}=ON rocprof-sys-source
git clone https://github.com/ROCm/rocm-systems.git
cmake -B rocprof-sys-build -DROCPROFSYS_BUILD_DYNINST=ON \
-DROCPROFSYS_BUILD_{TBB,ELFUTILS,BOOST,LIBIBERTY}=ON \
-S rocm-systems/projects/rocprofiler-systems
where ``-DROCPROFSYS_BUILD_{TBB,BOOST,ELFUTILS,LIBIBERTY}=ON`` is expanded by
the shell to ``-DROCPROFSYS_BUILD_TBB=ON -DROCPROFSYS_BUILD_BOOST=ON ...``
@@ -241,9 +189,9 @@ Building and installing ROCm Systems Profiler
---------------------------------------------
ROCm Systems Profiler has CMake configuration options for MPI support (``ROCPROFSYS_USE_MPI`` or
``ROCPROFSYS_USE_MPI_HEADERS``),
ROCm tracing and sampling (``ROCPROFSYS_USE_ROCM``), OpenMP-Tools (``ROCPROFSYS_USE_OMPT``),
hardware counters via PAPI (``ROCPROFSYS_USE_PAPI``), among other features.
``ROCPROFSYS_USE_MPI_HEADERS``), ROCm tracing and sampling (``ROCPROFSYS_USE_ROCM``),
OpenMP-Tools (``ROCPROFSYS_USE_OMPT``), hardware counters via PAPI (``ROCPROFSYS_USE_PAPI``),
among other features.
Various additional features can be enabled via the
``TIMEMORY_USE_*`` `CMake options <https://timemory.readthedocs.io/en/develop/installation.html#cmake-options>`_.
Any ``ROCPROFSYS_USE_<VAL>`` option which has a corresponding ``TIMEMORY_USE_<VAL>``
@@ -255,7 +203,7 @@ in `the Perfetto UI <https://ui.perfetto.dev>`_.
.. code-block:: shell
git clone https://github.com/ROCm/rocprofiler-systems.git rocprof-sys-source
git clone https://github.com/ROCm/rocm-systems.git
cmake \
-B rocprof-sys-build \
-D CMAKE_INSTALL_PREFIX=/opt/rocprofiler-systems \
@@ -270,7 +218,7 @@ in `the Perfetto UI <https://ui.perfetto.dev>`_.
-D ROCPROFSYS_BUILD_BOOST=ON \
-D ROCPROFSYS_BUILD_ELFUTILS=ON \
-D ROCPROFSYS_BUILD_LIBIBERTY=ON \
rocprof-sys-source
-S rocm-systems/projects/rocprofiler-systems
cmake --build rocprof-sys-build --target all --parallel 8
cmake --build rocprof-sys-build --target install
source /opt/rocprofiler-systems/share/rocprofiler-systems/setup-env.sh
@@ -360,7 +308,8 @@ You should also test the executables to confirm ROCm Systems Profiler is correct
Configure the environment
-----------------------------------
If environment modules are available and preferred, add them using these commands:
If environment modules are available and preferred, then add them using these commands,
replacing ``1.0.0`` with the desired version number to load:
.. code-block:: shell
@@ -454,4 +403,3 @@ Configuring PAPI to collect hardware counters
To use PAPI to collect the majority of hardware counters, ensure
the ``/proc/sys/kernel/perf_event_paranoid`` setting has a value less than or equal to ``2``.
For more information, see the :ref:`rocprof-sys_papi_events` section.
projects/rocprofiler-systems/docs/install/quick-start.rst
-51
View File
@@ -1,51 +0,0 @@
.. meta::
:description: ROCm Systems Profiler quick start documentation and reference
:keywords: rocprof-sys, rocprofiler-systems, Omnitrace, ROCm, profiler, quick start, getting started, quick install, tracking, visualization, tool, Instinct, accelerator, AMD
*************************************
ROCm Systems Profiler quick start
*************************************
To install ROCm Systems Profiler, download the
`ROCm Systems Profiler installer <https://github.com/ROCm/rocprofiler-systems/releases/latest/download/rocprofiler-systems-install.py>`_
and specify ``--prefix <install-directory>``. The script attempts to auto-detect
the appropriate OS distribution and version. To include AMD ROCm Software support,
specify ``--rocm X.Y``, where ``X`` is the ROCm major
version and ``Y`` is the ROCm minor version, for example, ``--rocm 6.3``.
.. code-block:: shell
wget https://github.com/ROCm/rocprofiler-systems/releases/latest/download/rocprofiler-systems-install.py
python3 ./rocprofiler-systems-install.py --prefix /opt/rocprofiler-systems --rocm 6.3
This script supports installation on Ubuntu, OpenSUSE, Red Hat, Debian, CentOS, and Fedora.
If the target OS is compatible with one of the operating system versions listed in
the comprehensive :doc:`Installation guidelines <./install>`,
specify ``-d <DISTRO> -v <VERSION>``. For example, if the OS is compatible with Ubuntu 22.04, pass
``-d ubuntu -v 22.04`` to the script.
Install via package manager
============================
If you have ROCm version 6.3 or higher installed, you can use the
package manager to install a pre-built copy of ROCm Systems Profiler.
.. tab-set::
.. tab-item:: Ubuntu
.. code-block:: shell
$ sudo apt install rocprofiler-systems
.. tab-item:: Red Hat Enterprise Linux
.. code-block:: shell
$ sudo dnf install rocprofiler-systems
.. tab-item:: SUSE Linux Enterprise Server
.. code-block:: shell
$ sudo zypper install rocprofiler-systems
projects/rocprofiler-systems/docs/reference/development-guide.rst
+17 -17
View File
@@ -6,7 +6,7 @@
Development guide
****************************************************
This guide discusses the `ROCm Systems Profiler <https://github.com/ROCm/rocprofiler-systems>`_ design.
This guide discusses the `ROCm Systems Profiler <https://github.com/ROCm/rocm-systems/tree/develop/projects/rocprofiler-systems>`_ design.
It includes a list of the executables and libraries, along with a discussion of the application's
memory, sampling, and time-window constraint models.
@@ -15,7 +15,7 @@ Executables
This section lists the ROCm Systems Profiler executables.
rocprof-sys-avail: `source/bin/rocprof-sys-avail <https://github.com/ROCm/rocprofiler-systems/tree/amd-mainline/source/bin/rocprof-sys-avail>`_
rocprof-sys-avail: `source/bin/rocprof-sys-avail <https://github.com/ROCm/rocm-systems/tree/develop/projects/rocprofiler-systems/source/bin/rocprof-sys-avail>`_
-----------------------------------------------------------------------------------------------------------------------------------------------
The ``main`` routine of ``rocprof-sys-avail`` has three important sections:
@@ -24,7 +24,7 @@ The ``main`` routine of ``rocprof-sys-avail`` has three important sections:
* Printing options
* Printing hardware counters
rocprof-sys-sample: `source/bin/rocprof-sys-sample <https://github.com/ROCm/rocprofiler-systems/tree/amd-mainline/source/bin/rocprof-sys-sample>`_
rocprof-sys-sample: `source/bin/rocprof-sys-sample <https://github.com/ROCm/rocm-systems/tree/develop/projects/rocprofiler-systems/source/bin/rocprof-sys-sample>`_
--------------------------------------------------------------------------------------------------------------------------------------------------
* Requires a command-line format of ``rocprof-sys-sample <options> -- <command> <command-args>``
@@ -32,7 +32,7 @@ rocprof-sys-sample: `source/bin/rocprof-sys-sample <https://github.com/ROCm/rocp
* Adds ``librocprof-sys-dl.so`` to ``LD_PRELOAD``
* Is launched by using ``execvpe`` with ``<command> <command-args>`` and a modified environment
rocprof-sys-causal: `source/bin/rocprof-sys-causal <https://github.com/ROCm/rocprofiler-systems/tree/amd-mainline/source/bin/rocprof-sys-causal>`_
rocprof-sys-causal: `source/bin/rocprof-sys-causal <https://github.com/ROCm/rocm-systems/tree/develop/projects/rocprofiler-systems/source/bin/rocprof-sys-causal>`_
---------------------------------------------------------------------------------------------------------------------------------------------------
When there is exactly one causal profiling configuration variant (which enables debugging),
@@ -45,7 +45,7 @@ the following actions take place for each variant:
* the child process launches ``<command> <command-args>`` using ``execvpe``, which modifies the environment for the variant
* the parent process waits for the child process to finish
rocprof-sys-instrument: `source/bin/rocprof-sys-instrument <https://github.com/ROCm/rocprofiler-systems/tree/amd-mainline/source/bin/rocprof-sys-instrument>`_
rocprof-sys-instrument: `source/bin/rocprof-sys-instrument <https://github.com/ROCm/rocm-systems/tree/develop/projects/rocprofiler-systems/source/bin/rocprof-sys-instrument>`_
--------------------------------------------------------------------------------------------------------------------------------------------------------------
* Requires a command-line format of ``rocprof-sys-instrument <options> -- <command> <command-args>``
@@ -70,31 +70,31 @@ rocprof-sys-instrument: `source/bin/rocprof-sys-instrument <https://github.com/R
Libraries
========================================
Common library: `source/lib/common <https://github.com/ROCm/rocprofiler-systems/tree/amd-mainline/source/lib/common>`_
Common library: `source/lib/common <https://github.com/ROCm/rocm-systems/tree/develop/projects/rocprofiler-systems/source/lib/common>`_
--------------------------------------------------------------------------------------------------------------------------------
* General header-only functionality used in multiple executables and/or libraries.
* Not installed or exported outside of the build tree.
Core library: `source/lib/core <https://github.com/ROCm/rocprofiler-systems/tree/amd-mainline/source/lib/core>`_
Core library: `source/lib/core <https://github.com/ROCm/rocm-systems/tree/develop/projects/rocprofiler-systems/source/lib/core>`_
--------------------------------------------------------------------------------------------------------------------------------
* Static PIC library with functionality that does not depend on any components.
* Not installed or exported outside of the build tree.
Binary library: `source/lib/binary <https://github.com/ROCm/rocprofiler-systems/tree/amd-mainline/source/lib/binary>`_
Binary library: `source/lib/binary <https://github.com/ROCm/rocm-systems/tree/develop/projects/rocprofiler-systems/source/lib/binary>`_
--------------------------------------------------------------------------------------------------------------------------------
* Static PIC library with functionality for reading/analyzing binary info.
* Mostly used by the causal profiling sections of ``librocprof-sys``.
* Not installed or exported outside of the build tree.
librocprof-sys: `source/lib/rocprof-sys <https://github.com/ROCm/rocprofiler-systems/tree/amd-mainline/source/lib/rocprof-sys>`_
librocprof-sys: `source/lib/rocprof-sys <https://github.com/ROCm/rocm-systems/tree/develop/projects/rocprofiler-systems/source/lib/rocprof-sys>`_
--------------------------------------------------------------------------------------------------------------------------------
This is the main library encapsulating all the capabilities.
librocprof-sys-dl: `source/lib/rocprof-sys-dl <https://github.com/ROCm/rocprofiler-systems/tree/amd-mainline/source/lib/rocprof-sys-dl>`_
librocprof-sys-dl: `source/lib/rocprof-sys-dl <https://github.com/ROCm/rocm-systems/tree/develop/projects/rocprofiler-systems/source/lib/rocprof-sys-dl>`_
-----------------------------------------------------------------------------------------------------------------------------------------
This is a lightweight, front-end library for ``librocprof-sys`` which serves three primary purposes:
@@ -105,7 +105,7 @@ This is a lightweight, front-end library for ``librocprof-sys`` which serves thr
* Prevents re-entry if ``librocprof-sys`` calls an instrumented function internally
* Coordinates communication between ``librocprof-sys-user`` and ``librocprof-sys``
librocprof-sys-user: `source/lib/rocprof-sys-user <https://github.com/ROCm/rocprofiler-systems/tree/amd-mainline/source/lib/rocprof-sys-user>`_
librocprof-sys-user: `source/lib/rocprof-sys-user <https://github.com/ROCm/rocm-systems/tree/develop/projects/rocprofiler-systems/source/lib/rocprof-sys-user>`_
-----------------------------------------------------------------------------------------------------------------------------------------------
* Provides a set of functions and types for the users to add to their code, for example,
@@ -356,15 +356,15 @@ lowers the sampling frequency for the real-time sampler
to 10 interrupts per second of real-time.
The ROCm Systems Profiler-specific implementation can be found in
`source/lib/rocprof-sys/library/sampling.cpp <https://github.com/ROCm/rocprofiler-systems/blob/amd-mainline/source/lib/rocprof-sys/library/sampling.cpp>`_.
Within `sampling.cpp <https://github.com/ROCm/rocprofiler-systems/blob/amd-mainline/source/lib/rocprof-sys/library/sampling.cpp>`_,
`source/lib/rocprof-sys/library/sampling.cpp <https://github.com/ROCm/rocm-systems/blob/develop/projects/rocprofiler-systems/source/lib/rocprof-sys/library/sampling.cpp>`_.
Within `sampling.cpp <https://github.com/ROCm/rocm-systems/blob/develop/projects/rocprofiler-systems/source/lib/rocprof-sys/library/sampling.cpp>`_,
there is a bundle of three sampling components:
* `backtrace_timestamp <https://github.com/ROCm/rocprofiler-systems/blob/amd-mainline/source/lib/rocprof-sys/library/components/backtrace_timestamp.hpp>`_ simply
* `backtrace_timestamp <https://github.com/ROCm/rocm-systems/blob/develop/projects/rocprofiler-systems/source/lib/rocprof-sys/library/components/backtrace_timestamp.hpp>`_ simply
records the wall-clock time of the sample.
* `backtrace <https://github.com/ROCm/rocprofiler-systems/blob/amd-mainline/source/lib/rocprof-sys/library/components/backtrace.hpp>`_
* `backtrace <https://github.com/ROCm/rocm-systems/blob/develop/projects/rocprofiler-systems/source/lib/rocprof-sys/library/components/backtrace.hpp>`_
records the call-stack via libunwind.
* `backtrace_metrics <https://github.com/ROCm/rocprofiler-systems/blob/amd-mainline/source/lib/rocprof-sys/library/components/backtrace_metrics.hpp>`_
* `backtrace_metrics <https://github.com/ROCm/rocm-systems/blob/develop/projects/rocprofiler-systems/source/lib/rocprof-sys/library/components/backtrace_metrics.hpp>`_
records the sample metrics, such as peak RSS and the hardware counters.
These three components are bundled together in
@@ -387,7 +387,7 @@ Time-window constraint model
========================================
With the recent introduction of tracing delay and duration, the
`constraint namespace <https://github.com/ROCm/rocprofiler-systems/blob/amd-mainline/source/lib/core/constraint.hpp>`_
`constraint namespace <https://github.com/ROCm/rocm-systems/blob/develop/projects/rocprofiler-systems/source/lib/core/constraint.hpp>`_
was introduced to improve the management of delays and duration limits for
data collection. The ``spec`` class accepts a clock identifier, a delay value, a duration value, and an
integer indicating how many times to repeat the delay and duration cycle. It is therefore
projects/rocprofiler-systems/docs/sphinx/_toc.yml.in
+1 -3
View File
@@ -10,8 +10,6 @@ subtrees:
- caption: Install
entries:
- file: install/quick-start.rst
title: ROCm Systems Profiler quick start
- file: install/install.rst
title: ROCm Systems Profiler installation guide
@@ -68,7 +66,7 @@ subtrees:
- caption: Tutorials
entries:
- url: https://github.com/ROCm/rocprofiler-systems/tree/amd-mainline/examples
- url: https://github.com/ROCm/rocm-systems/tree/develop/projects/rocprofiler-systems/examples
title: GitHub examples
- file: tutorials/video-tutorials.rst
title: Video tutorials