Update installation and ROCPD documentation (#1300)
* 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>
Этот коммит содержится в:
David Galiffi
коммит произвёл
GitHub
GitHub
родитель
02bf0a8492
Коммит
b75423b173
@@ -4,16 +4,27 @@
|
||||
|
||||
Full documentation for ROCm Systems Profiler is available at [https://rocm.docs.amd.com/projects/rocprofiler-systems/en/latest/](https://rocm.docs.amd.com/projects/rocprofiler-systems/en/latest/).
|
||||
|
||||
## ROCm Systems Profiler 1.2.0 for ROCm 7.1
|
||||
## ROCm Systems Profiler 1.2.0 for ROCm 7.1.0
|
||||
|
||||
### Added
|
||||
|
||||
- ``ROCPROFSYS_ROCM_GROUP_BY_QUEUE`` configuration setting to allow grouping of events by hardware queue, instead of the default grouping.
|
||||
- Support for rocPD database output with the `ROCPROFSYS_USE_ROCPD` configuration setting.
|
||||
- Support for `rocpd` database output with the `ROCPROFSYS_USE_ROCPD` configuration setting.
|
||||
- Support for profiling PyTorch workloads using the `rocpd` output database.
|
||||
- Support for tracing OpenMP API in Fortran applications.
|
||||
- An error warning that is triggered if the profiler application fails due to SELinux enforcement being enabled. The warning includes steps to disable SELinux enforcement.
|
||||
|
||||
## Changed
|
||||
### Changed
|
||||
|
||||
- Updated the grouping of "kernel dispatch" and "memory copy" events in Perfetto traces. They are now grouped together by HIP Stream rather than separately and by hardware queue.
|
||||
- Updated PAPI module to v7.2.0b2.
|
||||
- ROCprofiler-SDK is now used for tracing OMPT API calls.
|
||||
|
||||
## ROCm Systems Profiler 1.1.1 for ROCm 7.0.2
|
||||
|
||||
### Resolved issues
|
||||
|
||||
- Fixed an issue where ROC-TX ranges were displayed as two separate events instead of a single spanning event.
|
||||
|
||||
## ROCm Systems Profiler 1.1.0 for ROCm 7.0
|
||||
|
||||
|
||||
@@ -4,26 +4,15 @@
|
||||
<meta name="keywords" content="ROCm, contributing, rocprofiler-systems">
|
||||
</head>
|
||||
|
||||
# Contributing to rocprofiler-systems #
|
||||
# Contributing to ROCm Systems Profiler #
|
||||
|
||||
ROCm Systems Profiler (rocprofiler-systems), formerly Omnitrace, is a comprehensive profiling and tracing tool for parallel applications written in C, C++, Fortran, HIP, OpenCL, and Python which execute on the CPU or CPU+GPU.
|
||||
|
||||
We welcome contributions to rocprofiler-systems. Please follow these details to help ensure your contributions will be successfully accepted.
|
||||
|
||||
## Table of Contents ##
|
||||
|
||||
1. [Issue Discussion](#issue-discussion)
|
||||
2. [Acceptance Criteria](#acceptance-criteria)
|
||||
3. [Pull Request Guidelines](#pull-request-guidelines)
|
||||
4. [Coding Style](#coding-style)
|
||||
5. [Code License](#code-license)
|
||||
6. [References](#references)
|
||||
Contributions to ROCm Systems Profiler are encouraged and welcomed. Contributions at a basic level must conform to the MIT license and pass the code test requirements (i.e., ctest). The author must also be able to respond to comments/questions on the PR and make any changes requested.
|
||||
|
||||
## Issue Discussion ##
|
||||
|
||||
Please use the GitHub Issues tab to notify us of issues.
|
||||
|
||||
* Use your best judgement for issue creation. Search [existing issues](https://github.com/ROCm/rocprofiler-systems/issues) to make sure your issue isn't already listed
|
||||
* Use your best judgement for issue creation. Search [existing issues](https://github.com/ROCm/rocm-systems/issues) to make sure your issue isn't already listed
|
||||
* If your issue is already listed, upvote the issue and comment or post to provide additional details, such as how you reproduced this issue.
|
||||
* If you're not sure if your issue is the same, err on the side of caution and file your issue. You can add a comment to include the issue number (and link) for the similar issue. If we evaluate your issue as being the same as the existing issue, we'll close the duplicate.
|
||||
* If your issue doesn't exist, use the issue template to file a new issue.
|
||||
@@ -33,55 +22,21 @@ Please use the GitHub Issues tab to notify us of issues.
|
||||
|
||||
## Acceptance Criteria ##
|
||||
|
||||
* Contributions should align with the project's goals and maintainability.
|
||||
* Code should be well-documented and include tests where applicable.
|
||||
* Ensure that your changes do not break existing functionality.
|
||||
* Each commit is to be digitally signed. For more details see: [About commit signature verification - GitHub Docs](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification).
|
||||
|
||||
### Exceptions ###
|
||||
|
||||
* If you believe your contribution does not fit the guidelines but is still valuable, please discuss it with the maintainers before submitting.
|
||||
GitHub Issues are recommended for any significant change to the code base that adds a feature or fixes a non-trivial issue. If the code change is large without the presence of an issue (or prior discussion with AMD), the change may not be reviewed. Small fixes that fix broken behavior or other bugs are always welcome, with or without an associated issue.
|
||||
|
||||
## Pull Request Guidelines ##
|
||||
|
||||
By creating a pull request, you agree to the statements made in the [code license](#code-license) section. Your pull request should target the default branch. Our current default branch is the **amd-staging** branch, which serves as our integration branch.
|
||||
|
||||
### Process ###
|
||||
|
||||
* Fork the repository and create your branch from `amd-staging`.
|
||||
* If you've added code that should be tested, add tests.
|
||||
* Ensure the test suite passes.
|
||||
* Make sure your code conforms to the format. Use clang-format-18 and/or gersemi.
|
||||
* Use clear and descriptive commit messages.
|
||||
* Submit your PR and work with the reviewer or maintainer to get your PR approved
|
||||
* Once approved, the PR is brought onto internal CI systems and may be merged into the component during our release cycle, as coordinated by the maintainer.
|
||||
|
||||
### Setting Up the Development Environment ###
|
||||
|
||||
* It is recommended to [fork](https://github.com/ROCm/rocprofiler-systems/fork) the repository.
|
||||
* Clone your forked repository: `git clone https://github.com/ROCm/<yourgithub-id>/rocprofiler-systems.git`
|
||||
* Navigate to the project directory: `cd rocprofiler-systems`
|
||||
* Set the original repository URL as the remote upstream using `git remote add upstream https://github.com/ROCm/rocprofiler-systems` (or `git remote set-url upstream https://github.com/ROCm/rocprofiler-systems`)
|
||||
* Verify if origin and upstream points correctly with `git remote -v`.
|
||||
* Start a new branch for your work: `git checkout -b topic-<yourFeatureName>`
|
||||
* Build the project as outlined in [ROCm documentation](https://github.com/ROCm/rocprofiler-systems/blob/a03770c0606c23fda5e2c83782f2d188eb8522f5/docs/install/install.rst#building-and-installing-rocm-systems-profiler).
|
||||
|
||||
### Running Tests ###
|
||||
|
||||
* To run the test suite, use the following command: `make test`
|
||||
* Ensure all tests pass before submitting a pull request.
|
||||
* If the project was built with option `-D ROCPROFSYS_BUILD_TESTING=ON`, then the tests are built with it. Individual tests groups can be run using command: `ctest -R <test-name> -V --output-on-failure`. Command `ctest --print-labels` will list all the test names which can be passed to -R as test-name.
|
||||
By creating a pull request, you agree to the statements made in the [code license](#code-license) section. Your pull request should target the default branch. Our current default branch is the **develop** branch, which serves as our integration branch.
|
||||
|
||||
## Coding Style ##
|
||||
|
||||
* Adhere to the coding style used in the project. This includes naming conventions, indentation, and commenting practices.
|
||||
* Follow the existing directory structure and organization of the codebase.
|
||||
* Group related files together and maintain a logical hierarchy.
|
||||
* Use `clang-format-18` and `gersemi` formatters to ensure consistency.
|
||||
* The exact settings for these formatters must be the ones in this repository.
|
||||
|
||||
### Using pre-commit hooks ###
|
||||
|
||||
Our project supports optional [*pre-commit hooks*](https://pre-commit.com/#introduction) which developers can leverage to verify formatting before publishing their code. Once enabled, any commits you propose to the repository will be automatically checked for formatting. Initial setup is as follows:
|
||||
Our project supports [*pre-commit hooks*](https://pre-commit.com/#introduction) which developers can
|
||||
leverage to automatically verify formatting before committing their change. Initial setup is as follows:
|
||||
|
||||
```shell
|
||||
pip install pre-commit # or: apt-get install pre-commit
|
||||
@@ -91,7 +46,7 @@ pre-commit install
|
||||
|
||||
**Note:** pre-commit version **3.0.0 or higher** is required.
|
||||
|
||||
Now, when you commit code to the repository you should see something like this:
|
||||
Now, these pre-commit checks must pass before a change can be committed.
|
||||
|
||||
|
||||
|
||||
@@ -101,6 +56,10 @@ Please see the [pre-commit documentation](https://pre-commit.com/#quick-start) f
|
||||
|
||||
All code contributed to this project will be licensed under the license identified in the [License](LICENSE.md). Your contribution will be accepted under the same license.
|
||||
|
||||
## Release Cadence ##
|
||||
|
||||
Any code contribution to this library will be released with the next version of ROCm if the contribution window for the upcoming release is still open. If the contribution window is closed but the PR contains a critical security/bug fix, an exception may be made to include the change in the next release.
|
||||
|
||||
## References ##
|
||||
|
||||
1. [ROCm Systems Profiler Documentation](https://rocm.docs.amd.com/projects/rocprofiler-systems/en/latest/index.html)
|
||||
|
||||
@@ -90,21 +90,6 @@ The documentation source files reside in the [`/docs`](/docs) folder of this rep
|
||||
|
||||
### Installation
|
||||
|
||||
- Visit [Releases](https://github.com/ROCm/rocprofiler-systems/releases) page
|
||||
- Select appropriate installer (recommendation: `.sh` scripts do not require super-user priviledges unlike the DEB/RPM installers)
|
||||
- If targeting a ROCm application, find the installer script with the matching ROCm version
|
||||
- If you are unsure about your Linux distro, check `/etc/os-release` or use the `rocprofiler-systems-install.py` script
|
||||
|
||||
If the above recommendation is not desired, download the `rocprofiler-systems-install.py` and specify `--prefix <install-directory>` when
|
||||
executing it. This script will attempt to auto-detect a compatible OS distribution and version.
|
||||
If ROCm support is desired, specify `--rocm X.Y` where `X` is the ROCm major version and `Y`
|
||||
is the ROCm minor version, e.g. `--rocm 6.2`.
|
||||
|
||||
```console
|
||||
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.2
|
||||
```
|
||||
|
||||
See the [ROCm Systems Profiler installation guide](https://rocm.docs.amd.com/projects/rocprofiler-systems/en/latest/install/install.html) for detailed information.
|
||||
|
||||
### Setup
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
+1
-1
@@ -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::
|
||||
|
||||
@@ -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:
|
||||
|
||||
|
||||
@@ -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>`
|
||||
|
||||
@@ -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
|
||||
========================================
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
+52
-42
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
Ссылка в новой задаче
Block a user