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

add sphinx configurations

Browse Source 
Change-Id: I1a66a02b18fb699415a87a6473eb72c097a13b5f


[ROCm/ROCR-Runtime commit: 57b3fcde51]
This commit is contained in:
Sam Wu
2023-05-08 15:58:01 -06:00
parent e2fc46c189
commit 56ec0e6412
1 changed files with 114 additions and 102 deletions
Download Patch File Download Diff File Expand all files Collapse all files
projects/rocr-runtime/runtime/hsa-runtime/README.md
+114 -102
View File
@@ -1,122 +1,134 @@
### Package Contents # Package Contents
This directory contains the ROC Runtime source code based on the HSA Runtime This directory contains the ROC Runtime source code based on the HSA Runtime
but modified to support AMD/ATI discrete GPUs. but modified to support AMD/ATI discrete GPUs.
#### Source & Include Directories ## Source & Include Directories
core - Contains the source code for AMD's implementation of the core HSA Runtime API's. `core` - Contains the source code for AMD's implementation of the core HSA
Runtime API's.
cmake_modules - CMake support modules and files. `cmake_modules` - CMake support modules and files.
inc - Contains the public and AMD specific header files exposing the HSA Runtimes interfaces. `inc` - Contains the public and AMD specific header files exposing the HSA
Runtime`s interfaces.
libamdhsacode - Code object definitions and interface. `libamdhsacode` - Code object definitions and interface.
loader - Used to load code objects. `loader` - Used to load code objects.
utils - Utilities required to build the core runtime. `utils` - Utilities required to build the core runtime.
#### Build Environment ## Build Environment
CMake build framework is used to build the ROC runtime. The minimum version is CMake build framework is used to build the ROC runtime. The minimum version is
3.7. 3.7.
Obtain cmake infrastructure: http://www.cmake.org/download/ Obtain cmake infrastructure: <http://www.cmake.org/download/>
Export cmake bin into your PATH Export cmake bin into your PATH
#### Package Dependencies ## Package Dependencies
The following support packages are required to successfully build the runtime: The following support packages are required to successfully build the runtime:
* libelf-dev * `libelf-dev`
* g++ * `g++`
#### Building the Runtime ## Building the Runtime
To build the runtime a compatible version of the libhsakmt library and the To build the runtime a compatible version of the `libhsakmt` library and the
hsakmt.h header file must be available. The latest version of these files `hsakmt.h` header file must be available. The latest version of these files
can be obtained from the ROCT-Thunk-Interface repository, available here: can be obtained from the ROCT-Thunk-Interface repository, available here:
https://github.com/RadeonOpenCompute/ROCT-Thunk-Interface <https://github.com/RadeonOpenCompute/ROCT-Thunk-Interface>
As of ROCm release 3.7 libhsakmt development packages now include a cmake As of ROCm release 3.7 `libhsakmt` development packages now include a CMake
package config file. The runtime will now locate libhsakmt via find_package if package config file. The runtime will now locate `libhsakmt` via `find_package`
libhsakmt is installed to a standard location. For installations that do not if `libhsakmt` is installed to a standard location. For installations that do
use ROCm standard paths set cmake variables CMAKE_PREFIX_PATH or hsakmt_DIR to not use ROCm standard paths set CMake variables `CMAKE_PREFIX_PATH` or
override find_package search paths. `hsakmt_DIR` to override `find_package` search paths.
As of ROCm release 3.7 the runtime includes an optional image support module As of ROCm release 3.7 the runtime includes an optional image support module
(previously hsa-ext-rocr-dev). By default this module is included in builds of (previously `hsa-ext-rocr-dev`). By default this module is included in builds of
the runtime. The image module may be excluded the runtime by setting the runtime. The image module may be excluded the runtime by setting
cmake variable IMAGE_SUPPORT to OFF. CMake variable `IMAGE_SUPPORT` to `OFF`.
When building the optional image module additional build dependencies are When building the optional image module additional build dependencies are
required. An amdgcn compatible clang and device library must be installed required. An AMDGCN compatible clang and device library must be installed
to build the image module. The latest version of these requirements can be to build the image module. The latest version of these requirements can be
obtained from the ROCm package repository obtained from the ROCm package repository
(see: https://rocmdocs.amd.com/en/latest/Installation_Guide/Installation-Guide.html) (see:
<https://rocmdocs.amd.com/en/latest/Installation_Guide/Installation-Guide.html>)
The latest source for these projects may be found here: The latest source for these projects may be found here:
https://github.com/RadeonOpenCompute/llvm-project <https://github.com/RadeonOpenCompute/llvm-project>
https://github.com/RadeonOpenCompute/ROCm-Device-Libs <https://github.com/RadeonOpenCompute/ROCm-Device-Libs>
Additionally xxd must be installed. Additionally `xxd` must be installed.
The runtime optionally supports use of the cmake user package registry. By The runtime optionally supports use of the cmake user package registry. By
default the registry is not modified. Set cmake variable default the registry is not modified. Set CMake variable
EXPORT_TO_USER_PACKAGE_REGISTRY to ON to enable updating the package registry. `EXPORT_TO_USER_PACKAGE_REGISTRY` to `ON` to enable updating the package
registry.
For example, to build, install, and produce packages on a system with standard For example, to build, install, and produce packages on a system with standard
ROCm packages installed, execute the following from src/: ROCm packages installed, execute the following from `src/`:
mkdir build ```bash
cd build mkdir build
cmake -DCMAKE_INSTALL_PATH=/opt/rocm .. cd build
make cmake -DCMAKE_INSTALL_PATH=/opt/rocm ..
make install make
make package make install
make package
```
Example with a custom installation path, build dependency path, and options: Example with a custom installation path, build dependency path, and options:
cmake -DIMAGE_SUPPORT=OFF \ ```bash
-DEXPORT_TO_USER_PACKAGE_REGISTRY=ON \ cmake -DIMAGE_SUPPORT=OFF \
-DCMAKE_VERBOSE_MAKEFILE=1 \ -DEXPORT_TO_USER_PACKAGE_REGISTRY=ON \
-DCMAKE_PREFIX_PATH=<alternate path(s) to build dependencies> \ -DCMAKE_VERBOSE_MAKEFILE=1 \
-DCMAKE_INSTALL_PATH=<custom install path for this build> \ -DCMAKE_PREFIX_PATH=<alternate path(s) to build dependencies> \
.. -DCMAKE_INSTALL_PATH=<custom install path for this build> \
..
```
Alternately ccmake and cmake-gui are supported: Alternately `ccmake` and `cmake-gui` are supported:
mkdir build ```bash
cd build mkdir build
ccmake .. cd build
press c to configure ccmake ..
populate variables as desired press c to configure
press c again populate variables as desired
press g to generate and exit press c again
make press g to generate and exit
make
```
#### Building Against the Runtime ## Building Against the Runtime
The runtime provides a cmake package config file, installed by default to The runtime provides a CMake package config file, installed by default to
/opt/rocm/lib/cmake/hsa-runtime64. The runtime exports cmake target `/opt/rocm/lib/cmake/hsa-runtime64`. The runtime exports CMake target
hsa-runtime64 in namespace hsa-runtime64. A cmake project (Foo) using the `hsa-runtime64` in namespace `hsa-runtime64`. A CMake project (`Foo`) using the
runtime may locate, include, and link the runtime with the following template: runtime may locate, include, and link the runtime with the following template:
Add /opt/rocm to CMAKE_PREFIX_PATH. ```cmake
# Add /opt/rocm to CMAKE_PREFIX_PATH.
find_package(hsa-runtime64 1.0 REQUIRED) find_package(hsa-runtime64 1.0 REQUIRED)
... ...
add_library(Foo ...) add_library(Foo ...)
... ...
target_link_library(Foo PRIVATE hsa-runtime64::hsa-runtime64) target_link_libraries(Foo PRIVATE hsa-runtime64::hsa-runtime64)
```
#### Specs ## Specs
http://www.hsafoundation.com/standards/ <http://www.hsafoundation.com/standards/>
HSA Runtime Specification 1.1 HSA Runtime Specification 1.1
@@ -124,7 +136,7 @@ HSA Programmer Reference Manual Specification 1.1
HSA Platform System Architecture Specification 1.1 HSA Platform System Architecture Specification 1.1
#### Runtime Design Overview ## Runtime Design Overview
The AMD ROC runtime consists of three primary layers: The AMD ROC runtime consists of three primary layers:
@@ -136,12 +148,12 @@ Additionally the runtime is dependent on a small utility library which provides
simple common functions, limited operating system and compiler abstraction, as simple common functions, limited operating system and compiler abstraction, as
well as atomic operation interfaces. well as atomic operation interfaces.
#### C Interface Adaptors ## C Interface Adaptors
Files: Files:
* hsa.h(cpp) * `hsa.h`(cpp)
* hsa_ext_interface.h(cpp) * `hsa_ext_interface.h`(cpp)
The C interface layer provides C99 APIs as defined in the HSA Runtime The C interface layer provides C99 APIs as defined in the HSA Runtime
Specification 1.1. The interfaces and default definitions for the standard Specification 1.1. The interfaces and default definitions for the standard
@@ -151,58 +163,58 @@ default definitions, which simply return an appropriate error code. If
available the extension library is loaded as part of runtime initialization and available the extension library is loaded as part of runtime initialization and
the table is updated to point into the extension library. the table is updated to point into the extension library.
#### C++ Interfaces Classes & Common Functions ## C++ Interfaces Classes & Common Functions
Files: Files:
* runtime.h(cpp) * `runtime.h`(cpp)
* agent.h * `agent.h`
* queue.h * `queue.h`
* signal.h * `signal.h`
* memory_region.h(cpp) * `memory_region.h`(cpp)
* checked.h * `checked.h`
* memory_database.h(cpp) * `memory_database.h`(cpp)
* default_signal.h(cpp) * `default_signal.h`(cpp)
The C++ interface layer provides abstract interface classes encapsulating The C++ interface layer provides abstract interface classes encapsulating
commands to HSA Signals, Agents, and Queues. This layer also contains the commands to HSA Signals, Agents, and Queues. This layer also contains the
implementation of device independent commands, such as hsa_init and implementation of device independent commands, such as `hsa_init` and
hsa_system_get_info, and a default signal and queue implementation. `hsa_system_get_info`, and a default signal and queue implementation.
#### Device Specific Implementations ## Device Specific Implementations
Files: Files:
* amd_cpu_agent.h(cpp) * `amd_cpu_agent.h`(cpp)
* amd_gpu_agent.h(cpp) * `amd_gpu_agent.h`(cpp)
* amd_hw_aql_command_processor.h(cpp) * `amd_hw_aql_command_processor.h`(cpp)
* amd_memory_region.h(cpp) * `amd_memory_region.h`(cpp)
* amd_memory_registration.h(cpp) * `amd_memory_registration.h`(cpp)
* amd_topology.h(cpp) * `amd_topology.h`(cpp)
* host_queue.h(cpp) * `host_queue.h`(cpp)
* interrupt_signal.h(cpp) * `interrupt_signal.h`(cpp)
* hsa_ext_private_amd.h(cpp) * `hsa_ext_private_amd.h`(cpp)
The device specific layer contains implementations of the C++ interface classes The device specific layer contains implementations of the C++ interface classes
which implement HSA functionality for ROCm supported devices. which implement HSA functionality for ROCm supported devices.
#### Implemented Functionality ## Implemented Functionality
* The following queries are not implemented: * The following queries are not implemented:
* hsa_code_symbol_get_info: * `hsa_code_symbol_get_info`:
* HSA_CODE_SYMBOL_INFO_INDIRECT_FUNCTION_CALL_CONVENTION * `HSA_CODE_SYMBOL_INFO_INDIRECT_FUNCTION_CALL_CONVENTION`
* hsa_executable_symbol_get_info: * `hsa_executable_symbol_get_info`:
* HSA_EXECUTABLE_SYMBOL_INFO_INDIRECT_FUNCTION_OBJECT * `HSA_EXECUTABLE_SYMBOL_INFO_INDIRECT_FUNCTION_OBJECT`
* HSA_EXECUTABLE_SYMBOL_INFO_INDIRECT_FUNCTION_CALL_CONVENTION * `HSA_EXECUTABLE_SYMBOL_INFO_INDIRECT_FUNCTION_CALL_CONVENTION`
#### Known Issues ## Known Issues
* hsa_agent_get_exception_policies is not implemented. * `hsa_agent_get_exception_policies` is not implemented.
* hsa_system_get_extension_table is not implemented for * `hsa_system_get_extension_table` is not implemented for
HSA_EXTENSION_AMD_PROFILER. `HSA_EXTENSION_AMD_PROFILER`.
#### Disclaimer ## Disclaimer
The information contained herein is for informational purposes only, and is The information contained herein is for informational purposes only, and is
subject to change without notice. While every precaution has been taken in the subject to change without notice. While every precaution has been taken in the
@@ -224,4 +236,4 @@ Micro Devices, Inc. Other product names used in this publication are for
identification purposes only and may be trademarks of their respective identification purposes only and may be trademarks of their respective
companies. companies.
Copyright (c) 2014-2021 Advanced Micro Devices, Inc. All rights reserved. Copyright © 2014-2021 Advanced Micro Devices, Inc. All rights reserved.