Add 'projects/rocr-runtime/' from commit '72061a9024139fa0a99f73f9d3d4deb275670095'
git-subtree-dir: projects/rocr-runtime git-subtree-mainline:ad0fb25ed5git-subtree-split:72061a9024
This commit is contained in:
systems-assistant[bot]
@@ -0,0 +1,98 @@
|
||||
.. meta::
|
||||
:description: HSA runtime implementation
|
||||
:keywords: ROCR, ROCm, library, tool, runtime
|
||||
|
||||
.. _rocr-api:
|
||||
|
||||
API
|
||||
===
|
||||
|
||||
:ref:`genindex`
|
||||
|
||||
:ref:`search`
|
||||
|
||||
Architected Queuing Language
|
||||
############################
|
||||
.. doxygengroup:: aql
|
||||
:content-only:
|
||||
:inner:
|
||||
|
||||
Code objects [**DEPRECATED**]
|
||||
#############################
|
||||
.. doxygengroup:: code-object
|
||||
:content-only:
|
||||
:inner:
|
||||
|
||||
Executable
|
||||
##########
|
||||
.. doxygengroup:: executable
|
||||
:content-only:
|
||||
:inner:
|
||||
|
||||
Finalization extensions
|
||||
#######################
|
||||
.. doxygengroup:: ext-alt-finalizer-extensions
|
||||
:content-only:
|
||||
:inner:
|
||||
|
||||
Finalization program
|
||||
####################
|
||||
.. doxygengroup:: ext-alt-finalizer-program
|
||||
:content-only:
|
||||
:inner:
|
||||
|
||||
Images and samplers
|
||||
###################
|
||||
.. doxygengroup:: ext-images
|
||||
:content-only:
|
||||
:inner:
|
||||
|
||||
Instruction set architecture
|
||||
############################
|
||||
.. doxygengroup:: instruction-set-architecture
|
||||
:content-only:
|
||||
:inner:
|
||||
|
||||
Memory
|
||||
######
|
||||
.. doxygengroup:: memory
|
||||
:content-only:
|
||||
:inner:
|
||||
|
||||
Queues
|
||||
######
|
||||
.. doxygengroup:: queue
|
||||
:content-only:
|
||||
:inner:
|
||||
|
||||
Runtime notifications
|
||||
#####################
|
||||
.. doxygengroup:: status
|
||||
:content-only:
|
||||
:inner:
|
||||
|
||||
Signals
|
||||
#######
|
||||
.. doxygengroup:: signals
|
||||
:content-only:
|
||||
:inner:
|
||||
|
||||
System and agent information
|
||||
############################
|
||||
.. doxygengroup:: agentinfo
|
||||
:content-only:
|
||||
:inner:
|
||||
|
||||
Profiling
|
||||
###############
|
||||
.. doxygengroup:: profile
|
||||
:content-only:
|
||||
:inner:
|
||||
|
||||
Error codes
|
||||
#############
|
||||
.. doxygengroup:: error-codes
|
||||
:content-only:
|
||||
:inner:
|
||||
|
||||
|
||||
@@ -0,0 +1,16 @@
|
||||
.. meta::
|
||||
:description: HSA runtime implementation
|
||||
:keywords: ROCR, ROCm, library, tool, runtime
|
||||
|
||||
.. _c-interface-adaptors:
|
||||
|
||||
C interface adaptors
|
||||
=====================
|
||||
|
||||
The C interface layer is the :ref:`top layer in ROCR <runtime-design>` that provides C++ APIs as defined in the `HSA Runtime Specification 1.2 <https://hsafoundation.com/wp-content/uploads/2021/02/HSA-Runtime-1.2.pdf>`_. The C interface layer also consists of the interfaces and default definitions for the standard extensions. The interface functions simply forward to a function pointer table defined here. The table is initialized to point to default definitions, which simply returns an appropriate error code. If available, the extension library is loaded as part of runtime initialization and the table is updated to point to the extension library.
|
||||
|
||||
Files present in this layer:
|
||||
|
||||
- ``hsa.h`` (cpp)
|
||||
|
||||
- ``hsa_ext_interface.h`` (cpp)
|
||||
@@ -0,0 +1,12 @@
|
||||
.. meta::
|
||||
:description: HSA runtime implementation
|
||||
:keywords: ROCR, ROCm, library, tool, runtime
|
||||
|
||||
.. _environment-variables:
|
||||
|
||||
Environment variables
|
||||
========================
|
||||
|
||||
The following table lists the most often used environment variables.
|
||||
|
||||
.. include:: ../data/env_variables.rst
|
||||
@@ -0,0 +1,35 @@
|
||||
# Configuration file for the Sphinx documentation builder.
|
||||
#
|
||||
# This file only contains a selection of the most common options. For a full
|
||||
# list see the documentation:
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html
|
||||
|
||||
import os
|
||||
import re
|
||||
|
||||
from rocm_docs import ROCmDocs
|
||||
|
||||
with open('../../CMakeLists.txt', encoding='utf-8') as f:
|
||||
match = re.search(r'get_version\(\"?([0-9.]+)[^0-9.]+', f.read())
|
||||
if not match:
|
||||
raise ValueError("VERSION not found!")
|
||||
version_number = match[1]
|
||||
left_nav_title = f"ROCR {version_number} Documentation"
|
||||
|
||||
# for PDF output on Read the Docs
|
||||
project = "ROCR Documentation"
|
||||
author = "Advanced Micro Devices, Inc."
|
||||
copyright = "Copyright (c) 2024 Advanced Micro Devices, Inc. All rights reserved."
|
||||
version = version_number
|
||||
release = version_number
|
||||
|
||||
external_toc_path = "./sphinx/_toc.yml"
|
||||
|
||||
external_projects_current_project = "rocr-runtime"
|
||||
|
||||
docs_core = ROCmDocs(left_nav_title)
|
||||
docs_core.run_doxygen(doxygen_root="doxygen", doxygen_path="doxygen/xml")
|
||||
docs_core.setup()
|
||||
|
||||
for sphinx_var in ROCmDocs.SPHINX_VARS:
|
||||
globals()[sphinx_var] = getattr(docs_core, sphinx_var)
|
||||
@@ -0,0 +1,93 @@
|
||||
.. meta::
|
||||
:description: HSA runtime implementation
|
||||
:keywords: ROCR, ROCm, library, tool, runtime
|
||||
|
||||
.. _contributing-to-rocr:
|
||||
|
||||
Contributing to ROCR
|
||||
========================
|
||||
|
||||
This document contains useful information required to contribute to ROCR.
|
||||
|
||||
.. _runtime-design:
|
||||
|
||||
Runtime design
|
||||
-----------------
|
||||
|
||||
ROCR consists of the following primary layers:
|
||||
|
||||
1. :ref:`C interface adaptors <c-interface-adaptors>`
|
||||
|
||||
2. C++ interface classes and common functions
|
||||
|
||||
3. Device-specific implementations
|
||||
|
||||
The first layer provides interfaces to make ROCR APIs available to the user applications.
|
||||
The second and third layers comprise of the internal ROCR implementation, which is available for contribution.
|
||||
|
||||
Additionally, the runtime is dependent on a small utility library that provides simple common functions, limited operating system, compiler abstraction, and atomic operation interfaces.
|
||||
|
||||
The following sections list the important files present in the second and third layer.
|
||||
|
||||
C++ interface classes and common functions
|
||||
----------------------------------------------
|
||||
|
||||
The C++ interface layer provides abstract interface classes encapsulating commands to HSA signals, agents, and queues. This layer also contains the implementation of device-independent commands, such as ``hsa_init``, ``hsa_system_get_info``, and a default signal and queue implementation.
|
||||
|
||||
Files present in this layer:
|
||||
|
||||
- ``runtime.h`` (cpp)
|
||||
|
||||
- ``agent.h``
|
||||
|
||||
- ``queue.h``
|
||||
|
||||
- ``signal.h``
|
||||
|
||||
- ``memory_region.h`` (cpp)
|
||||
|
||||
- ``checked.h``
|
||||
|
||||
- ``memory_database.h`` (cpp)
|
||||
|
||||
- ``default_signal.h`` (cpp)
|
||||
|
||||
Device-specific implementations
|
||||
----------------------------------
|
||||
|
||||
The device-specific layer contains implementations of the C++ interface classes that implement HSA functionality for ROCm supported devices.
|
||||
|
||||
Files present in this layer:
|
||||
|
||||
- ``amd_cpu_agent.h`` (cpp)
|
||||
|
||||
- ``amd_gpu_agent.h`` (cpp)
|
||||
|
||||
- ``amd_hw_aql_command_processor.h`` (cpp)
|
||||
|
||||
- ``amd_memory_region.h`` (cpp)
|
||||
|
||||
- ``amd_memory_registration.h`` (cpp)
|
||||
|
||||
- ``amd_topology.h`` (cpp)
|
||||
|
||||
- ``host_queue.h`` (cpp)
|
||||
|
||||
- ``interrupt_signal.h`` (cpp)
|
||||
|
||||
- ``hsa_ext_private_amd.h`` (cpp)
|
||||
|
||||
Source and include directories
|
||||
--------------------------------
|
||||
|
||||
- ``core``: Source code for AMD’s implementation of the core HSA Runtime API’s
|
||||
|
||||
- ``cmake_modules``: CMake support modules and files
|
||||
|
||||
- ``inc``: Public and AMD-specific header files exposing the HSA Runtime`s interfaces
|
||||
|
||||
- ``libamdhsacode``: Code object definitions and interfaces
|
||||
|
||||
- ``loader``: Loads code objects
|
||||
|
||||
- ``utils``: Utilities required to build the core runtime
|
||||
@@ -0,0 +1,141 @@
|
||||
.. meta::
|
||||
:description: ROCR-Runtime environment variables
|
||||
:keywords: AMD, ROCR, environment variables, environment
|
||||
|
||||
.. _rocr-env:
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
:widths: 35,14,51
|
||||
|
||||
* - Environment variable
|
||||
- Default value
|
||||
- Value
|
||||
|
||||
* - | ``ROCR_VISIBLE_DEVICES``
|
||||
| Specifies a list of device indices or UUIDs to be exposed to the applications.
|
||||
- None
|
||||
- ``0,GPU-DEADBEEFDEADBEEF``
|
||||
|
||||
* - | ``HSA_NO_SCRATCH_RECLAIM``
|
||||
| Controls whether scratch memory allocations are permanently assigned to queues or can be reclaimed based on usage thresholds.
|
||||
- ``0``
|
||||
- | 0: Disable.
|
||||
| When dispatches need scratch memory that are lower than the threshold, the memory will be permanently assigned to the queue. For dispatches that exceed the threshold, a scratch-use-once mechanism will be used, resulting in the memory to be unassigned after the dispatch.
|
||||
| 1: Enable.
|
||||
| If a kernel dispatch needs scratch memory, runtime will allocate and permanently assign device memory to the queue handling the dispatch, even if the amount of scratch memory exceeds the default threshold. This memory will not be available to other queues or processes until this process exits.
|
||||
|
||||
* - | ``HSA_SCRATCH_SINGLE_LIMIT``
|
||||
| Specifies the threshold for the amount of scratch memory allocated and reclaimed in kernel dispatches.
|
||||
| Enabling ``HSA_NO_SCRATCH_RECLAIM`` circumvents ``HSA_SCRATCH_SINGLE_LIMIT``, and treats ``HSA_SCRATCH_SINGLE_LIMIT`` as the maximum value.
|
||||
- ``146800640``
|
||||
- 0 to 4GB per XCC
|
||||
|
||||
* - | ``HSA_SCRATCH_SINGLE_LIMIT_ASYNC``
|
||||
| On GPUs that support asynchronous scratch reclaim, this variable is used instead of ``HSA_SCRATCH_SINGLE_LIMIT`` to specify the threshold for scratch memory allocation.
|
||||
- ``3221225472`` (3GB)
|
||||
- 0 to 4GB per XCC
|
||||
|
||||
* - | ``HSA_ENABLE_SCRATCH_ASYNC_RECLAIM``
|
||||
| Controls asynchronous scratch memory reclamation on supported GPUs.
|
||||
| When enabled, if a device memory allocation fails, ROCr will attempt to reclaim scratch memory assigned to all queues and retry the allocation.
|
||||
- ``1``
|
||||
- | 0: Disable asynchronous scratch reclaim.
|
||||
| 1: Enable asynchronous scratch reclaim on supported GPUs.
|
||||
|
||||
* - | ``HSA_XNACK``
|
||||
| Enables XNACK.
|
||||
- None
|
||||
- 1: Enable
|
||||
|
||||
* - | ``HSA_CU_MASK``
|
||||
| Sets the mask on a lower level of queue creation in the driver.
|
||||
| This mask is also applied to the queues being profiled.
|
||||
- None
|
||||
- ``1:0-8``
|
||||
|
||||
* - | ``HSA_ENABLE_SDMA``
|
||||
| Enables the use of direct memory access (DMA) engines in all copy directions (Host-to-Device, Device-to-Host, Device-to-Device), when using any of the following APIs:
|
||||
| ``hsa_memory_copy``,
|
||||
| ``hsa_amd_memory_fill``,
|
||||
| ``hsa_amd_memory_async_copy``,
|
||||
| ``hsa_amd_memory_async_copy_on_engine``.
|
||||
- ``1``
|
||||
- | 0: Disable
|
||||
| 1: Enable
|
||||
|
||||
* - | ``HSA_ENABLE_PEER_SDMA``
|
||||
| **Note**: This environment variable is ignored if ``HSA_ENABLE_SDMA`` is set to 0.
|
||||
| Enables the use of DMA engines for Device-to-Device copies, when using any of the following APIs:
|
||||
| ``hsa_memory_copy``,
|
||||
| ``hsa_amd_memory_async_copy``,
|
||||
| ``hsa_amd_memory_async_copy_on_engine``.
|
||||
- ``1``
|
||||
- | 0: Disable
|
||||
| 1: Enable
|
||||
|
||||
* - | ``HSA_ENABLE_MWAITX``
|
||||
| When mwaitx is enabled, on AMD CPUs, runtime will hint to the CPU to go into lower power-states when doing busy loops by using the mwaitx instruction.
|
||||
- ``0``
|
||||
- | 0: Disable
|
||||
| 1: Enable
|
||||
|
||||
* - | ``HSA_OVERRIDE_CPU_AFFINITY_DEBUG``
|
||||
| Controls whether ROCm helper threads inherit the parent process's CPU affinity mask.
|
||||
- ``1``
|
||||
- | 0: Enable inheritance. Helper threads use the parent process's core affinity mask, which should be set with enough cores for all threads.
|
||||
| 1: Disable inheritance. Helper threads spawn on all available cores, ignoring the parent's affinity settings, which may affect performance in certain environments.
|
||||
|
||||
* - | ``HSA_ENABLE_DEBUG``
|
||||
| Enables additional debug information and validation in the runtime.
|
||||
- ``0``
|
||||
- | 0: Disable debug mode.
|
||||
| 1: Enable debug mode with additional validation and logging.
|
||||
|
||||
|
||||
Hardware Debugging Environment Variables
|
||||
----------------------------------------
|
||||
|
||||
The following environment variables are intended for experienced users who are debugging hardware-specific issues.
|
||||
These settings may impact performance and stability and should only be used when troubleshooting specific hardware problems.
|
||||
|
||||
.. _rocr-debug-env:
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
:widths: 35,14,51
|
||||
|
||||
* - Environment variable
|
||||
- Default value
|
||||
- Value
|
||||
|
||||
* - | ``HSA_DISABLE_FRAGMENT_ALLOCATOR``
|
||||
| Disables internal memory fragment caching to help debug memory faults.
|
||||
- ``0``
|
||||
- | 0: Fragment allocator enabled (normal operation).
|
||||
| 1: Fragment allocator disabled. Helps debug tools identify memory faults at their origin by preventing cached memory blocks from masking out-of-bounds writes.
|
||||
|
||||
* - | ``HSAKMT_DEBUG_LEVEL``
|
||||
| Controls the verbosity level of debug messages from the ``libhsakmt.so`` driver layer.
|
||||
- ``3``
|
||||
- | 3: Only error messages (``pr_err``) are printed.
|
||||
| 4: Error and warning messages (``pr_err``, ``pr_warn``) are printed.
|
||||
| 5: Same as level 4 (notice level not implemented).
|
||||
| 6: Error, warning, and info messages (``pr_err``, ``pr_warn``, ``pr_info``) are printed.
|
||||
| 7: All debug messages including ``pr_debug`` are printed.
|
||||
|
||||
* - | ``HSA_ENABLE_INTERRUPT``
|
||||
| Controls how completion signals are detected, useful for diagnosing interrupt storm issues.
|
||||
- ``1``
|
||||
- | 0: Disable hardware interrupts. Uses memory-based polling for completion signals instead of interrupts.
|
||||
| 1: Enable hardware interrupts (normal operation).
|
||||
|
||||
* - | ``HSA_SVM_GUARD_PAGES``
|
||||
| Controls the use of guard pages in Shared Virtual Memory (SVM) allocations.
|
||||
- ``1``
|
||||
- | 0: Disable SVM guard pages (for debugging memory access patterns).
|
||||
| 1: Enable SVM guard pages (normal operation).
|
||||
|
||||
* - | ``HSA_DISABLE_CACHE``
|
||||
| Controls GPU L2 cache utilization for all memory regions.
|
||||
- ``0``
|
||||
- | 0: Normal caching behavior (L2 cache enabled).
|
||||
| 1: Disables L2 cache entirely. Sets all memory regions as uncacheable (MTYPE=UC) in the GPU, bypassing the L2 cache. Useful for diagnosing cache-related performance or correctness issues.
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,37 @@
|
||||
.. meta::
|
||||
:description: HSA runtime implementation
|
||||
:keywords: ROCm runtime, HSA runtime
|
||||
|
||||
.. _index:
|
||||
|
||||
=====================
|
||||
ROCR documentation
|
||||
=====================
|
||||
|
||||
The ROCm runtime (ROCR) is AMD's implementation of HSA runtime, which is a thin, user-mode API that exposes the necessary interfaces to access and interact with graphics hardware driven by the AMDGPU driver set and the ROCK kernel driver. To learn more, see :ref:`what-is-rocr-runtime`
|
||||
|
||||
You can access ROCR code on our `GitHub repository <https://github.com/ROCm/ROCR-Runtime>`_.
|
||||
|
||||
The documentation is structured as follows:
|
||||
|
||||
.. grid:: 2
|
||||
:gutter: 3
|
||||
|
||||
.. grid-item-card:: Install
|
||||
|
||||
* :ref:`installation`
|
||||
|
||||
.. grid-item-card:: API reference
|
||||
|
||||
* :ref:`c-interface-adaptors`
|
||||
* :ref:`environment-variables`
|
||||
* :ref:`rocr-api`
|
||||
|
||||
.. grid-item-card:: Contribution
|
||||
|
||||
* :ref:`contributing-to-rocr`
|
||||
|
||||
To contribute to the documentation, refer to
|
||||
`Contributing to ROCm <https://rocm.docs.amd.com/en/latest/contribute/contributing.html>`_.
|
||||
|
||||
You can find licensing information on the `Licensing <https://rocm.docs.amd.com/en/latest/about/license.html>`_ page.
|
||||
@@ -0,0 +1,129 @@
|
||||
.. meta::
|
||||
:description: HSA runtime implementation
|
||||
:keywords: ROCR, ROCm, library, tool, runtime
|
||||
|
||||
.. _installation:
|
||||
|
||||
====================
|
||||
Installation
|
||||
====================
|
||||
|
||||
This document provides information required to build and install ROCR using prebuilt binaries or from source.
|
||||
|
||||
Build and install using prebuilt binaries
|
||||
-------------------------------------------
|
||||
|
||||
Here is how you can install ROCR using prebuilt binaries.
|
||||
|
||||
Prerequisites
|
||||
*******************
|
||||
|
||||
- A system supporting ROCm. See the `supported operating systems <https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html#supported-operating-systems>`_.
|
||||
|
||||
- Install ROCm. See `how to install ROCm <https://rocm.docs.amd.com/projects/install-on-linux/en/latest/>`_.
|
||||
|
||||
- Install ``libdrm`` package.
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
sudo apt install libdrm-dev
|
||||
|
||||
The ROCR prebuilt binaries include:
|
||||
|
||||
**Core runtime package:**
|
||||
|
||||
- HSA include files to support application development on the HSA runtime for the ROCR runtime
|
||||
|
||||
- A 64-bit version of AMD’s HSA core runtime for the ROCR runtime
|
||||
|
||||
**Runtime extension package:**
|
||||
|
||||
- A 64-bit version of AMD’s runtime tools library
|
||||
|
||||
- A 64-bit version of AMD’s runtime image library
|
||||
|
||||
The contents of these packages are installed in ``/opt/rocm/hsa`` and ``/opt/rocm`` by default. The core runtime package depends on the ``hsakmt-roct-dev`` package.
|
||||
|
||||
Build and install from source
|
||||
--------------------------------
|
||||
|
||||
Here is how you can build ROCR from source.
|
||||
|
||||
Prerequisites
|
||||
***************
|
||||
|
||||
- CMake 3.7 or later. Export CMake bin into your PATH.
|
||||
|
||||
- Support packages ``libelf-dev`` and ``g++``.
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
sudo apt install libelf-dev g++
|
||||
|
||||
- A compatible version of the ``libhsakmt`` library and the ``hsakmt.h`` header file. Obtain the latest version of these files from the `ROCT-Thunk-Interface repository <https://github.com/ROCm/ROCT-Thunk-Interface>`_.
|
||||
|
||||
- Install ``xxd``.
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
sudo apt install xxd
|
||||
|
||||
Building the runtime
|
||||
----------------------
|
||||
|
||||
The ``libhsakmt`` development packages include a CMake package config file. The runtime locates ``libhsakmt`` via ``find_package`` if ``libhsakmt`` is installed in a standard location. For installations that don't use standard ROCm paths, set CMake variables ``CMAKE_PREFIX_PATH`` or ``hsakmt_DIR`` to override ``find_package`` search paths.
|
||||
The runtime includes an optional image support module (previously ``hsa-ext-rocr-dev``). By default this module is included in the runtime builds. To exclude the image module from the runtime, set the CMake variable ``IMAGE_SUPPORT`` to OFF.
|
||||
To build the optional image module, install AMDGCN-compatible clang and device library. You can find the latest version of these additional build dependencies in the `ROCm package repository <https://rocm.docs.amd.com/projects/install-on-linux/en/latest/how-to/native-install/package-manager-integration.html#packages-in-rocm-programming-models>`_.
|
||||
The latest source for these projects are available in the `llvm project <https://github.com/ROCm/llvm-project>`_ and `ROCm device libs <https://github.com/ROCm/ROCm-Device-Libs>`_ repositories.
|
||||
|
||||
The runtime optionally supports use of the CMake user package registry. By default the registry is not modified. Set CMake variable ``EXPORT_TO_USER_PACKAGE_REGISTRY`` to ON to enable updating the package registry.
|
||||
|
||||
To build, install, and produce packages on a system with standard ROCm packages installed, clone your copy of ROCR and run the following from ``src/``:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
mkdir build
|
||||
cd build
|
||||
cmake -DCMAKE_INSTALL_PREFIX=/opt/rocm ..
|
||||
make
|
||||
make install
|
||||
make package
|
||||
|
||||
Example with a custom installation path, build dependency path, and options:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
cmake -DIMAGE_SUPPORT=OFF \
|
||||
-DEXPORT_TO_USER_PACKAGE_REGISTRY=ON \
|
||||
-DCMAKE_VERBOSE_MAKEFILE=1 \
|
||||
-DCMAKE_PREFIX_PATH=<alternate path(s) to build dependencies> \
|
||||
-DCMAKE_INSTALL_PATH=<custom install path for this build> \
|
||||
..
|
||||
|
||||
Alternatively, use ``ccmake`` and ``cmake-gui``:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
mkdir build
|
||||
cd build
|
||||
ccmake ..
|
||||
press c to configure
|
||||
populate variables as desired
|
||||
press c again
|
||||
press g to generate and exit
|
||||
make
|
||||
|
||||
Building against the runtime
|
||||
---------------------------------
|
||||
|
||||
The runtime provides a CMake package config file, installed by default to ``/opt/rocm/lib/cmake/hsa-runtime64``. The runtime exports CMake target ``hsa-runtime64`` in namespace ``hsa-runtime64``. A CMake project (``Foo``) using the runtime may locate, include, and link the runtime using the following template:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
# Add /opt/rocm to CMAKE_PREFIX_PATH.
|
||||
|
||||
find_package(hsa-runtime64 1.0 REQUIRED)
|
||||
...
|
||||
add_library(Foo ...)
|
||||
...
|
||||
target_link_libraries(Foo PRIVATE hsa-runtime64::hsa-runtime64)
|
||||
@@ -0,0 +1,4 @@
|
||||
License
|
||||
=======
|
||||
|
||||
.. include:: ../../LICENSE.txt
|
||||
@@ -0,0 +1,21 @@
|
||||
# Anywhere {branch} is used, the branch name will be substituted.
|
||||
# These comments will also be removed.
|
||||
root: index
|
||||
subtrees:
|
||||
- caption: Install
|
||||
entries:
|
||||
- file: install/installation
|
||||
|
||||
- caption: API reference
|
||||
entries:
|
||||
- file: api-reference/c-interface-adaptors
|
||||
- file: api-reference/environment_variables
|
||||
- file: api-reference/api
|
||||
|
||||
- caption: Contribution
|
||||
entries:
|
||||
- file: contribution/contributing-to-rocr
|
||||
|
||||
- caption: About
|
||||
entries:
|
||||
- file: license
|
||||
@@ -0,0 +1 @@
|
||||
rocm-docs-core==1.8.0
|
||||
@@ -0,0 +1,147 @@
|
||||
#
|
||||
# This file is autogenerated by pip-compile with Python 3.10
|
||||
# by the following command:
|
||||
#
|
||||
# pip-compile sphinx/requirements.in
|
||||
#
|
||||
accessible-pygments==0.0.5
|
||||
# via pydata-sphinx-theme
|
||||
alabaster==1.0.0
|
||||
# via sphinx
|
||||
babel==2.16.0
|
||||
# via
|
||||
# pydata-sphinx-theme
|
||||
# sphinx
|
||||
beautifulsoup4==4.12.3
|
||||
# via pydata-sphinx-theme
|
||||
breathe==4.35.0
|
||||
# via rocm-docs-core
|
||||
certifi==2024.8.30
|
||||
# via requests
|
||||
cffi==1.17.1
|
||||
# via
|
||||
# cryptography
|
||||
# pynacl
|
||||
charset-normalizer==3.3.2
|
||||
# via requests
|
||||
click==8.1.7
|
||||
# via sphinx-external-toc
|
||||
cryptography==43.0.1
|
||||
# via pyjwt
|
||||
deprecated==1.2.14
|
||||
# via pygithub
|
||||
docutils==0.21.2
|
||||
# via
|
||||
# breathe
|
||||
# myst-parser
|
||||
# pydata-sphinx-theme
|
||||
# sphinx
|
||||
fastjsonschema==2.20.0
|
||||
# via rocm-docs-core
|
||||
gitdb==4.0.11
|
||||
# via gitpython
|
||||
gitpython==3.1.43
|
||||
# via rocm-docs-core
|
||||
idna==3.10
|
||||
# via requests
|
||||
imagesize==1.4.1
|
||||
# via sphinx
|
||||
jinja2==3.1.4
|
||||
# via
|
||||
# myst-parser
|
||||
# sphinx
|
||||
markdown-it-py==3.0.0
|
||||
# via
|
||||
# mdit-py-plugins
|
||||
# myst-parser
|
||||
markupsafe==2.1.5
|
||||
# via jinja2
|
||||
mdit-py-plugins==0.4.2
|
||||
# via myst-parser
|
||||
mdurl==0.1.2
|
||||
# via markdown-it-py
|
||||
myst-parser==4.0.0
|
||||
# via rocm-docs-core
|
||||
packaging==24.1
|
||||
# via
|
||||
# pydata-sphinx-theme
|
||||
# sphinx
|
||||
pycparser==2.22
|
||||
# via cffi
|
||||
pydata-sphinx-theme==0.15.4
|
||||
# via
|
||||
# rocm-docs-core
|
||||
# sphinx-book-theme
|
||||
pygithub==2.4.0
|
||||
# via rocm-docs-core
|
||||
pygments==2.18.0
|
||||
# via
|
||||
# accessible-pygments
|
||||
# pydata-sphinx-theme
|
||||
# sphinx
|
||||
pyjwt[crypto]==2.9.0
|
||||
# via pygithub
|
||||
pynacl==1.5.0
|
||||
# via pygithub
|
||||
pyyaml==6.0.2
|
||||
# via
|
||||
# myst-parser
|
||||
# rocm-docs-core
|
||||
# sphinx-external-toc
|
||||
requests==2.32.3
|
||||
# via
|
||||
# pygithub
|
||||
# sphinx
|
||||
rocm-docs-core==1.8.0
|
||||
# via -r requirements.in
|
||||
smmap==5.0.1
|
||||
# via gitdb
|
||||
snowballstemmer==2.2.0
|
||||
# via sphinx
|
||||
soupsieve==2.6
|
||||
# via beautifulsoup4
|
||||
sphinx==8.0.2
|
||||
# via
|
||||
# breathe
|
||||
# myst-parser
|
||||
# pydata-sphinx-theme
|
||||
# rocm-docs-core
|
||||
# sphinx-book-theme
|
||||
# sphinx-copybutton
|
||||
# sphinx-design
|
||||
# sphinx-external-toc
|
||||
# sphinx-notfound-page
|
||||
sphinx-book-theme==1.1.3
|
||||
# via rocm-docs-core
|
||||
sphinx-copybutton==0.5.2
|
||||
# via rocm-docs-core
|
||||
sphinx-design==0.6.1
|
||||
# via rocm-docs-core
|
||||
sphinx-external-toc==1.0.1
|
||||
# via rocm-docs-core
|
||||
sphinx-notfound-page==1.0.4
|
||||
# via rocm-docs-core
|
||||
sphinxcontrib-applehelp==2.0.0
|
||||
# via sphinx
|
||||
sphinxcontrib-devhelp==2.0.0
|
||||
# via sphinx
|
||||
sphinxcontrib-htmlhelp==2.1.0
|
||||
# via sphinx
|
||||
sphinxcontrib-jsmath==1.0.1
|
||||
# via sphinx
|
||||
sphinxcontrib-qthelp==2.0.0
|
||||
# via sphinx
|
||||
sphinxcontrib-serializinghtml==2.0.0
|
||||
# via sphinx
|
||||
tomli==2.0.1
|
||||
# via sphinx
|
||||
typing-extensions==4.12.2
|
||||
# via
|
||||
# pydata-sphinx-theme
|
||||
# pygithub
|
||||
urllib3==2.2.3
|
||||
# via
|
||||
# pygithub
|
||||
# requests
|
||||
wrapt==1.16.0
|
||||
# via deprecated
|
||||
@@ -0,0 +1,32 @@
|
||||
.. meta::
|
||||
:description: HSA runtime implementation
|
||||
:keywords: ROCR, ROCm, library, tool, runtime
|
||||
|
||||
.. _what-is-rocr-runtime:
|
||||
|
||||
What is ROCR?
|
||||
========================
|
||||
|
||||
The ROCm runtime (ROCR) is AMD's implementation of HSA runtime, which is a thin, user-mode API that exposes the necessary interfaces to access and interact with graphics hardware driven by the AMDGPU driver set and the ROCK kernel driver. Together they enable you to directly harness the power of discrete AMD graphics devices by allowing host applications to launch compute kernels directly to the graphics hardware.
|
||||
|
||||
The ROCR APIs are capable of the following:
|
||||
|
||||
- Error handling
|
||||
|
||||
- Runtime initialization and shutdown
|
||||
|
||||
- System and agent information
|
||||
|
||||
- Signals and synchronization
|
||||
|
||||
- Architected dispatch
|
||||
|
||||
- Memory management
|
||||
|
||||
- Fitting into a typical software architecture stack
|
||||
|
||||
ROCR provides direct access to the graphics hardware, allowing you more control over execution. An example of low-level hardware access is the support for one or more user-mode queues, which provides a low-latency kernel dispatch interface, allowing you to develop customized dispatch algorithms specific to your application.
|
||||
The HSA Architected Queuing Language (AQL) is an open standard defined by the HSA Foundation, which specifies the packet syntax used to control supported AMD or ATI Radeon © graphics devices. The AQL language supports several packet types, including packets that can command the hardware to automatically resolve inter-packet dependencies (barrier AND and barrier OR packet), kernel dispatch packets, and agent dispatch packets.
|
||||
In addition to user-mode queues and AQL, the HSA runtime exposes various virtual address ranges that can be accessed by one or more of the system’s graphics devices and also possibly by the host. The exposed virtual address ranges support either a fine-grained or a coarse-grained access. Updates to memory in a fine-grained region are immediately visible to all devices that can access it, but only one device can have access to a coarse-grained allocation at a time. You can change the ownership of a coarse-grained region using the HSA runtime memory APIs, but this transfer of ownership must be explicitly done by the host application.
|
||||
|
||||
For a complete description of the HSA Runtime APIs, AQL, and the HSA memory policy, refer to the `HSA Runtime Programmer’s Reference Manual <https://hsafoundation.com/wp-content/uploads/2021/02/HSA-Runtime-1.2.pdf>`_.
|
||||
Reference in New Issue
Block a user