diff --git a/projects/rocprofiler-systems/CHANGELOG.md b/projects/rocprofiler-systems/CHANGELOG.md index 3cd0470434..0e12995e41 100644 --- a/projects/rocprofiler-systems/CHANGELOG.md +++ b/projects/rocprofiler-systems/CHANGELOG.md @@ -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 diff --git a/projects/rocprofiler-systems/CONTRIBUTING.md b/projects/rocprofiler-systems/CONTRIBUTING.md index a228db04a8..f1cf1f70ce 100644 --- a/projects/rocprofiler-systems/CONTRIBUTING.md +++ b/projects/rocprofiler-systems/CONTRIBUTING.md @@ -4,26 +4,15 @@ -# 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//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-` -* 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 -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. ![A screen capture showing terminal output from a pre-commit hook](docs/data/pre-commit-hook.png) @@ -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) diff --git a/projects/rocprofiler-systems/README.md b/projects/rocprofiler-systems/README.md index a5be140ae5..29cd6a4eee 100755 --- a/projects/rocprofiler-systems/README.md +++ b/projects/rocprofiler-systems/README.md @@ -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 ` 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 diff --git a/projects/rocprofiler-systems/docs/conceptual/rocprof-sys-feature-set.rst b/projects/rocprofiler-systems/docs/conceptual/rocprof-sys-feature-set.rst index 8aac222869..f5d2aeb2ae 100644 --- a/projects/rocprofiler-systems/docs/conceptual/rocprof-sys-feature-set.rst +++ b/projects/rocprofiler-systems/docs/conceptual/rocprof-sys-feature-set.rst @@ -6,7 +6,7 @@ ROCm Systems Profiler features and use cases ******************************************** -`ROCm Systems Profiler `_ is designed to be highly extensible. +`ROCm Systems Profiler `_ is designed to be highly extensible. Internally, it leverages the `Timemory performance analysis toolkit `_ to manage extensions, resources, data, and other items. It supports the following features, modes, metrics, and APIs. diff --git a/projects/rocprofiler-systems/docs/how-to/configuring-runtime-options.rst b/projects/rocprofiler-systems/docs/how-to/configuring-runtime-options.rst index da35a9cd4b..f69f8bec43 100644 --- a/projects/rocprofiler-systems/docs/how-to/configuring-runtime-options.rst +++ b/projects/rocprofiler-systems/docs/how-to/configuring-runtime-options.rst @@ -7,7 +7,7 @@ Configuring runtime options **************************************************** The ``rocprof-sys.cfg`` file maintains a list of the -`ROCm Systems Profiler `_ runtime +`ROCm Systems Profiler `_ runtime options. To create this configuration file and view the current runtime options, use the ``rocprof-sys-avail`` executable. diff --git a/projects/rocprofiler-systems/docs/how-to/configuring-validating-environment.rst b/projects/rocprofiler-systems/docs/how-to/configuring-validating-environment.rst index 99e33192f9..7cca6627d4 100644 --- a/projects/rocprofiler-systems/docs/how-to/configuring-validating-environment.rst +++ b/projects/rocprofiler-systems/docs/how-to/configuring-validating-environment.rst @@ -6,7 +6,7 @@ Configuring and validating the environment **************************************************** -After installing `ROCm Systems Profiler `_, additional steps are required to set up +After installing `ROCm Systems Profiler `_, additional steps are required to set up and validate the environment. .. note:: diff --git a/projects/rocprofiler-systems/docs/how-to/nic-profiling.rst b/projects/rocprofiler-systems/docs/how-to/nic-profiling.rst index 25b231af06..8c7f0bfb29 100644 --- a/projects/rocprofiler-systems/docs/how-to/nic-profiling.rst +++ b/projects/rocprofiler-systems/docs/how-to/nic-profiling.rst @@ -6,7 +6,7 @@ Network performance profiling ******************************************** -`ROCm Systems Profiler `_ supports network profiling. +`ROCm Systems Profiler `_ supports network profiling. All network events that can be traced on the system can be listed by running the command: diff --git a/projects/rocprofiler-systems/docs/how-to/performing-causal-profiling.rst b/projects/rocprofiler-systems/docs/how-to/performing-causal-profiling.rst index 2520c01cb3..a702b5bcbe 100644 --- a/projects/rocprofiler-systems/docs/how-to/performing-causal-profiling.rst +++ b/projects/rocprofiler-systems/docs/how-to/performing-causal-profiling.rst @@ -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 `_ can leverage the callbacks from +* `ROCm Systems Profiler `_ 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>` diff --git a/projects/rocprofiler-systems/docs/how-to/profiling-python-scripts.rst b/projects/rocprofiler-systems/docs/how-to/profiling-python-scripts.rst index 64fc98ba00..506520418d 100644 --- a/projects/rocprofiler-systems/docs/how-to/profiling-python-scripts.rst +++ b/projects/rocprofiler-systems/docs/how-to/profiling-python-scripts.rst @@ -6,7 +6,7 @@ Profiling Python scripts **************************************************** -`ROCm Systems Profiler `_ supports profiling Python code at the +`ROCm Systems Profiler `_ 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=".`` 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 `_. + 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 ======================================== diff --git a/projects/rocprofiler-systems/docs/how-to/sampling-call-stack.rst b/projects/rocprofiler-systems/docs/how-to/sampling-call-stack.rst index a32bab666a..3b0cd6ebaa 100644 --- a/projects/rocprofiler-systems/docs/how-to/sampling-call-stack.rst +++ b/projects/rocprofiler-systems/docs/how-to/sampling-call-stack.rst @@ -6,7 +6,7 @@ Sampling the call stack **************************************************** -`ROCm Systems Profiler `_ can use call-stack sampling +`ROCm Systems Profiler `_ 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 - diff --git a/projects/rocprofiler-systems/docs/how-to/understanding-rocprof-sys-output.rst b/projects/rocprofiler-systems/docs/how-to/understanding-rocprof-sys-output.rst index dc7e5eca97..baaf79cac4 100644 --- a/projects/rocprofiler-systems/docs/how-to/understanding-rocprof-sys-output.rst +++ b/projects/rocprofiler-systems/docs/how-to/understanding-rocprof-sys-output.rst @@ -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 `_ is +The general output form of `ROCm Systems Profiler `_ is ``[/]/[][-].``. 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%`` keys which do not have a command line argument at position ```` 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 `_ +for additional information on these conversion tools. + +Native Perfetto output ======================================== Use the ``ROCPROFSYS_OUTPUT_FILE`` to specify a specific location. If this is an diff --git a/projects/rocprofiler-systems/docs/how-to/vcn-jpeg-sampling.rst b/projects/rocprofiler-systems/docs/how-to/vcn-jpeg-sampling.rst index b8f402941e..af250f5af4 100644 --- a/projects/rocprofiler-systems/docs/how-to/vcn-jpeg-sampling.rst +++ b/projects/rocprofiler-systems/docs/how-to/vcn-jpeg-sampling.rst @@ -6,7 +6,7 @@ VCN and JPEG activity sampling and tracing ******************************************** -`ROCm Systems Profiler `_ supports +`ROCm Systems Profiler `_ 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 `_ +Tracing of rocDecode and rocJPEG APIs is supported by leveraging `ROCprofiler-SDK `_ 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 \ No newline at end of file + :alt: Visualization of a performance graph in Perfetto with JPEG Activity tracks diff --git a/projects/rocprofiler-systems/docs/index.rst b/projects/rocprofiler-systems/docs/index.rst index abde164fdb..3fe02eb55b 100644 --- a/projects/rocprofiler-systems/docs/index.rst +++ b/projects/rocprofiler-systems/docs/index.rst @@ -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 ``__. +ROCm Systems Profiler is open source and hosted at ``__. It is the successor to ``__. .. grid:: 2 @@ -19,7 +19,6 @@ It is the successor to ``__. .. 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 `_ + * `GitHub examples `_ * :doc:`Video tutorials <./tutorials/video-tutorials>` To contribute to the documentation, refer to diff --git a/projects/rocprofiler-systems/docs/install/install.rst b/projects/rocprofiler-systems/docs/install/install.rst index 1412ad6001..7616da8fda 100644 --- a/projects/rocprofiler-systems/docs/install/install.rst +++ b/projects/rocprofiler-systems/docs/install/install.rst @@ -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 `_ 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: ``_ -* All ROCm Systems Profiler 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 `_ +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/