AI/rocm-systems
2
0
Fork 0
Código Incidencias Pull Requests Acciones Paquetes Proyectos Lanzamientos Wiki Actividad

Doxysphinx docs (#3192)

Explorar el Código 
* Reorganize documenation based on rocm-docs-core

* Move build, install and contributing guides to docs

* Bump readthedocs config to Ubuntu 20.04

* Add more direct links to the API modules

* Pin rocm-docs-core version, add dependabot

- Use the pip package to have rocm-docs-core pinned
- Add dependabot config to update pinned packages (including rocm-docs-core)

* fixup! Add more direct links to the API modules

---------


[ROCm/hip commit: ae5f8714f4]
Este commit está contenido en:
Mészáros Gergely
2023-04-19 05:49:28 +02:00
cometido por GitHub
padre 550bb45784
commit 57ad953d7b
Se han modificado 37 ficheros con 704 adiciones y 4726 borrados
Descargar archivo de parche Descargar archivo de diferencias Expandir todos los archivos Contraer todos los archivos
projects/hip/docs/developer_guide/build.md
Archivo ejecutable
+222
Ver fichero
@@ -0,0 +1,222 @@
# Building HIP from Source
## Prerequisites
HIP code can be developed either on AMD ROCm platform using HIP-Clang compiler, or a CUDA platform with nvcc installed.
Before build and run HIP, make sure drivers and pre-build packages are installed properly on the platform.
### AMD platform
Install ROCm packages (see ROCm Installation Guide on AMD public documentation site (https://docs.amd.com/)) or install pre-built binary packages using the package manager,
```shell
sudo apt install mesa-common-dev
sudo apt install clang
sudo apt install comgr
sudo apt-get -y install rocm-dkms
```
### NVIDIA platform
Install Nvidia driver and pre-build packages (see HIP Installation Guide at https://docs.amd.com/ for the release)
### Branch of repository
Before get HIP source code, set the expected branch of repository at the variable `ROCM_BRANCH`.
For example, for ROCm5.0 release branch, set
```shell
export ROCM_BRANCH=rocm-5.0.x
```
ROCm5.4 release branch, set
```shell
export ROCM_BRANCH=rocm-5.4.x
```
Similiar format for future branches.
`ROCM_PATH` is path where ROCM is installed. BY default `ROCM_PATH` is at `/opt/rocm`.
## Build HIP on AMD platform
### Get HIP source code
```shell
git clone -b "$ROCM_BRANCH" https://github.com/ROCm-Developer-Tools/hipamd.git
git clone -b "$ROCM_BRANCH" https://github.com/ROCm-Developer-Tools/hip.git
git clone -b "$ROCM_BRANCH" https://github.com/ROCm-Developer-Tools/ROCclr.git
git clone -b "$ROCM_BRANCH" https://github.com/RadeonOpenCompute/ROCm-OpenCL-Runtime.git
```
### Set the environment variables
```shell
export HIPAMD_DIR="$(readlink -f hipamd)"
export HIP_DIR="$(readlink -f hip)"
```
ROCclr is defined on AMD platform that HIP use Radeon Open Compute Common Language Runtime (ROCclr), which is a virtual device interface that HIP runtimes interact with different backends.
See https://github.com/ROCm-Developer-Tools/ROCclr
HIPAMD repository provides implementation specifically for AMD platform.
See https://github.com/ROCm-Developer-Tools/hipamd
### Build HIP
```shell
cd "$HIPAMD_DIR"
mkdir -p build; cd build
cmake -DHIP_COMMON_DIR=$HIP_DIR -DCMAKE_PREFIX_PATH="<ROCM_PATH>/" -DCMAKE_INSTALL_PREFIX=$PWD/install ..
make -j$(nproc)
sudo make install
```
::::{note}
If you don't specify `CMAKE_INSTALL_PREFIX`, hip runtime will be installed to `<ROCM_PATH>/hip`.
By default, release version of AMDHIP is built.
::::
### Default paths and environment variables
* By default HIP looks for HSA in `<ROCM_PATH>/hsa` (can be overridden by setting `HSA_PATH` environment variable).
* By default HIP is installed into `<ROCM_PATH>/hip` (can be overridden by setting HIP_PATH environment variable).
* By default HIP looks for clang in `<ROCM_PATH>/llvm/bin` (can be overridden by setting `HIP_CLANG_PATH` environment variable)
* By default HIP looks for device library in `<ROCM_PATH>/lib` (can be overridden by setting `DEVICE_LIB_PATH` environment variable).
* Optionally, consider adding `<ROCM_PATH>/bin` to your `PATH` to make it easier to use the tools.
* Optionally, set `HIPCC_VERBOSE=7` to output the command line for compilation.
After make install command, make sure `HIP_PATH` is pointed to `$PWD/install/hip`.
### Generating profiling header after adding/changing a HIP API
When you add or change a HIP API, you might need to generate a new `hip_prof_str.h` header. This header is used by rocm tools to track HIP APIs like rocprofiler/roctracer etc.
To generate the header after your change, use the tool `hip_prof_gen.py` present in `hipamd/src`.
Usage:
`hip_prof_gen.py [-v] <input HIP API .h file> <patched srcs path> <previous output> [<output>]`
Flags:
* -v - verbose messages
* -r - process source directory recursively
* -t - API types matching check
* --priv - private API check
* -e - on error exit mode
* -p - HIP_INIT_API macro patching mode
Example Usage:
```shell
hip_prof_gen.py -v -p -t --priv <hip>/include/hip/hip_runtime_api.h \
<hipamd>/src <hipamd>/include/hip/amd_detail/hip_prof_str.h \
<hipamd>/include/hip/amd_detail/hip_prof_str.h.new
```
### Build HIP tests
#### Build HIP directed tests
Developers can build HIP directed tests right after build HIP commands,
```shell
sudo make install
make -j$(nproc) build_tests
```
By default, all HIP directed tests will be built and generated under the folder `$HIPAMD_DIR/build/`directed_tests.
Take HIP directed device APIs tests, as an example, all available test applications will have executable files generated under,
`$HIPAMD_DIR/build/directed_tests/runtimeApi/device`.
Run all HIP directed_tests, use the command,
```shell
ctest
```
Or
```shell
make test
```
Build and run a single directed test, use the follow command as an example,
```shell
make directed_tests.texture.hipTexObjPitch
cd $HIPAMD_DIR/build/directed_tests/texcture
./hipTexObjPitch
```
Please note, the integrated HIP directed tests, will be deprecated in future release.
##### Build HIP catch tests
HIP catch tests, with new architectured Catch2, are official seperated from HIP project, exist in HIP tests repository, can be built via the following instructions.
##### Get HIP tests source code
```shell
git clone -b "$ROCM_BRANCH" https://github.com/ROCm-Developer-Tools/hip-tests.git
```
##### Build HIP tests from source
```shell
export HIP_TESTS_DIR="$(readlink -f hip-tests)"
cd "$HIP_TESTS_DIR"
mkdir -p build; cd build
export HIP_PATH=$HIPAMD_DIR/build/install (or any path where HIP is installed, for example, /opt/rocm)
cmake ../catch/ -DHIP_PLATFORM=amd
make -j$(nproc) build_tests
ctest # run tests
```
HIP catch tests are built under the folder $HIP_TESTS_DIR/build.
To run any single catch test, the following is an example,
```shell
cd $HIP_TESTS_DIR/build/catch_tests/unit/texture
./TextureTest
```
##### Build HIP Catch2 standalone test
HIP Catch2 supports build a standalone test, for example,
```shell
cd "$HIP_TESTS_DIR"
hipcc $HIP_TESTS_DIR/catch/unit/memory/hipPointerGetAttributes.cc -I ./catch/include ./catch/hipTestMain/standalone_main.cc -I ./catch/external/Catch2 -o hipPointerGetAttributes
./hipPointerGetAttributes
...
All tests passed
```
## Build HIP on NVIDIA platform
### Get HIP source code
```shell
git clone -b "$ROCM_BRANCH" https://github.com/ROCm-Developer-Tools/hip.git
git clone -b "$ROCM_BRANCH" https://github.com/ROCm-Developer-Tools/hipamd.git
```
### Set the environment variables
```shell
export HIP_DIR="$(readlink -f hip)"
export HIPAMD_DIR="$(readlink -f hipamd)"
```
### Build HIP
```shell
cd "$HIPAMD_DIR"
mkdir -p build; cd build
cmake -DHIP_COMMON_DIR=$HIP_DIR -DHIP_PLATFORM=nvidia -DCMAKE_INSTALL_PREFIX=$PWD/install ..
make -j$(nproc)
sudo make install
```
### Build HIP tests
Build HIP tests commands on NVIDIA platform are basically the same as AMD, except set `-DHIP_PLATFORM=nvidia`.
## Run HIP
Compile and run the [square sample](https://github.com/ROCm-Developer-Tools/HIP/tree/rocm-5.0.x/samples/0_Intro/square).
projects/hip/docs/developer_guide/contributing.md
+156
Ver fichero
@@ -0,0 +1,156 @@
# Contributor Guidelines
## Make Tips
`ROCM_PATH` is path where ROCM is installed. BY default `ROCM_PATH` is `/opt/rocm`.
When building HIP, you will likely want to build and install to a local user-accessible directory (rather than `<ROCM_PATH>`).
This can be easily be done by setting the `-DCMAKE_INSTALL_PREFIX` variable when running cmake. Typical use case is to
set `CMAKE_INSTALL_PREFIX` to your HIP git root, and then ensure `HIP_PATH` points to this directory. For example
```shell
cmake .. -DCMAKE_INSTALL_PREFIX=..
make install
export HIP_PATH=
```
After making HIP, don't forget the "make install" step !
## Adding a new HIP API
- Add a translation to the hipify-clang tool ; many examples abound.
- For stat tracking purposes, place the API into an appropriate stat category ("dev", "mem", "stream", etc).
- Add a inlined NVIDIA implementation for the function in include/hip/nvidia_detail/hip_runtime_api.h.
- These are typically headers
- Add an HIP_ROCclr definition and Doxygen comments for the function in include/amd_detail/hip_runtime_api.h
- Source implementation typically go in hip/rocclr/hip_*.cpp. The implementation involve calls to HIP runtime (ie for hipStream_t).
## Check HIP-Clang version
In some cases new HIP-Clang features are tied to specified releases, and it can be useful to check the current version is sufficiently new enough to support the desired feature.
HIP runtime version
```console
> cat <ROCM_PATH>/hip/bin/.hipVersion
# Auto-generated by cmake
HIP_VERSION_MAJOR=3
HIP_VERSION_MINOR=9
HIP_VERSION_PATCH=20345-519ef3f2
```
HIP-Clang compiler version
```console
$ <ROCM_PATH>/llvm/bin/clang -v
clang version 11.0.0 (/src/external/llvm-project/clang 075fedd3fd2f4d9d8cca79d0cd51f64c5ef21432)
Target: x86_64-unknown-linux-gnu
Thread model: posix
InstalledDir: <ROCM_PATH>/llvm/bin
Found candidate GCC installation: /usr/lib/gcc/x86_64-linux-gnu/7
Found candidate GCC installation: /usr/lib/gcc/x86_64-linux-gnu/7.5.0
Found candidate GCC installation: /usr/lib/gcc/x86_64-linux-gnu/8
Found candidate GCC installation: /usr/lib/gcc/x86_64-linux-gnu/9
Selected GCC installation: /usr/lib/gcc/x86_64-linux-gnu/9
Candidate multilib: .;@m64
Candidate multilib: 32;@m32
Candidate multilib: x32;@mx32
Selected multilib: .;@m64
```
## Unit Testing Environment
HIP includes unit tests in the tests/src directory.
When adding a new HIP feature, add a new unit test as well.
See [tests/README.md](README.md) for more information.
## Development Flow
Directed tests provide a great place to develop new features alongside the associated test.
For applications and benchmarks outside the directed test environment, developments should use a two-step development flow:
- #1. Compile, link, and install HIP/ROCclr. See [Installation](README.md#Installation) notes.
- #2. Relink the target application to include changes in HIP runtime file.
## Environment Variables
- **HIP_PATH** : Location of HIP include, src, bin, lib directories.
- **HCC_ROCCLR_HOME** : Path to HIP/ROCclr directory, used on AMD platforms. Default <ROCM_PATH>/rocclr.
- **HSA_PATH** : Path to HSA include, lib. Default <ROCM_PATH>/hsa.
- **CUDA_PATH* : On nvcc system, this points to root of CUDA installation.
## Contribution guidelines ##
Features (ie functions, classes, types) defined in hip*.h should resemble CUDA APIs.
The HIP interface is designed to be very familiar for CUDA programmers.
Differences or limitations of HIP APIs as compared to CUDA APIs should be clearly documented and described.
### Coding Guidelines (in brief)
- Code Indentation:
- Tabs should be expanded to spaces.
- Use 4 spaces indentation.
- Capitalization and Naming
- Prefer camelCase for HIP interfaces and internal symbols. Note HCC uses _ for separator.
This guideline is not yet consistently followed in HIP code - eventual compliance is aspirational.
- Member variables should begin with a leading "_". This allows them to be easily distinguished from other variables or functions.
- {} placement
- For functions, the opening { should be placed on a new line.
- For if/else blocks, the opening { is placed on same line as the if/else. Use a space to separate {/" from if/else. Example
'''
if (foo) {
doFoo()
} else {
doFooElse();
}
'''
- namespace should be on same line as { and separated by a space.
- Single-line if statement should still use {/} pair (even though C++ does not require).
- Miscellaneous
- All references in function parameter lists should be const.
- "ihip" = internal hip structures. These should not be exposed through the HIP API.
- Keyword TODO refers to a note that should be addressed in long-term. Could be style issue, software architecture, or known bugs.
- FIXME refers to a short-term bug that needs to be addressed.
- HIP_INIT_API() should be placed at the start of each top-level HIP API. This function will make sure the HIP runtime is initialized,
and also constructs an appropriate API string for tracing and CodeXL marker tracing. The arguments to HIP_INIT_API should match
those of the parent function.
- ihipLogStatus should only be called from top-level HIP APIs,and should be called to log and return the error code. The error code
is used by the GetLastError and PeekLastError functions - if a HIP API simply returns, then the error will not be logged correctly.
- All HIP environment variables should begin with the keyword HIP_
Environment variables should be long enough to describe their purpose but short enough so they can be remembered - perhaps 10-20 characters, with 3-4 parts separated by underscores.
To see the list of current environment variables, along with their values, set HIP_PRINT_ENV and run any hip applications on ROCm platform .
HIPCC or other tools may support additional environment variables which should follow the above convention.
### Presubmit Testing:
Before checking in or submitting a pull request, run all directed tests (see tests/README.md) and all Rodinia tests.
Ensure pass results match starting point:
```console
> cd examples/
> ./run_all.sh
```
### Checkin messages
Follow existing best practice for writing a good Git commit message. Some tips:
http://chris.beams.io/posts/git-commit/
https://robots.thoughtbot.com/5-useful-tips-for-a-better-commit-message
In particular :
- Use imperative voice, ie "Fix this bug", "Refactor the XYZ routine", "Update the doc".
Not : "Fixing the bug", "Fixed the bug", "Bug fix", etc.
- Subject should summarize the commit. Do not end subject with a period. Use a blank line
after the subject.
## Doxygen Editing Guidelines
- bugs should be marked with @bugs near the code where the bug might be fixed. The @bug message will appear in the API description and also in the
doxygen bug list.
## Other Tips:
### Markdown Editing
Recommended to use an offline Markdown viewer to review documentation, such as Markdown Preview Plus extension in Chrome browser, or Remarkable.
projects/hip/docs/developer_guide/logging.md
+193
Ver fichero
@@ -0,0 +1,193 @@
# Logging Mechanisms
HIP provides a logging mechanism, which is a convenient way of printing
important information so as to trace HIP API and runtime codes during the
execution of HIP application.
It assists HIP development team in the development of HIP runtime, and is useful
for HIP application developers as well.
Depending on the setting of logging level and logging mask, HIP logging will
print different kinds of information, for different types of functionalities
such as HIP APIs, executed kernels, queue commands and queue contents, etc.
## HIP Logging Level:
By default, HIP logging is disabled, it can be enabled via the `AMD_LOG_LEVEL`
environment variable.
The value controls the logging level. The levels are defined as:
```cpp
enum LogLevel {
LOG_NONE = 0,
LOG_ERROR = 1,
LOG_WARNING = 2,
LOG_INFO = 3,
LOG_DEBUG = 4
};
```
## HIP Logging Mask:
Logging mask is designed to print types of functionalities during the execution
of HIP application.
It can be set as one of the following values,
```cpp
enum LogMask {
LOG_API = 0x00000001, //!< API call
LOG_CMD = 0x00000002, //!< Kernel and Copy Commands and Barriers
LOG_WAIT = 0x00000004, //!< Synchronization and waiting for commands to finish
LOG_AQL = 0x00000008, //!< Decode and display AQL packets
LOG_QUEUE = 0x00000010, //!< Queue commands and queue contents
LOG_SIG = 0x00000020, //!< Signal creation, allocation, pool
LOG_LOCK = 0x00000040, //!< Locks and thread-safety code.
LOG_KERN = 0x00000080, //!< kernel creations and arguments, etc.
LOG_COPY = 0x00000100, //!< Copy debug
LOG_COPY2 = 0x00000200, //!< Detailed copy debug
LOG_RESOURCE = 0x00000400, //!< Resource allocation, performance-impacting events.
LOG_INIT = 0x00000800, //!< Initialization and shutdown
LOG_MISC = 0x00001000, //!< misc debug, not yet classified
LOG_AQL2 = 0x00002000, //!< Show raw bytes of AQL packet
LOG_CODE = 0x00004000, //!< Show code creation debug
LOG_CMD2 = 0x00008000, //!< More detailed command info, including barrier commands
LOG_LOCATION = 0x00010000, //!< Log message location
LOG_ALWAYS = 0xFFFFFFFF, //!< Log always even mask flag is zero
};
```
Once `AMD_LOG_LEVEL` is set, logging mask is set as default with the value
`0x7FFFFFFF`.
However, for different purpose of logging functionalities, logging mask can be
defined as well via environment variable `AMD_LOG_MASK`
## HIP Logging command:
To pring HIP logging information, the function is defined as
```cpp
#define ClPrint(level, mask, format, ...) \
do { \
if (AMD_LOG_LEVEL >= level) { \
if (AMD_LOG_MASK & mask || mask == amd::LOG_ALWAYS) { \
if (AMD_LOG_MASK & amd::LOG_LOCATION) { \
amd::log_printf(level, __FILENAME__, __LINE__, format, ##__VA_ARGS__);\
} else { \
amd::log_printf(level, "", 0, format, ##__VA_ARGS__); \
} \
} \
} \
} while (false)
```
So in HIP code, call `ClPrint()` function with proper input varibles as needed,
for example,
```cpp
ClPrint(amd::LOG_INFO, amd::LOG_INIT, "Initializing HSA stack.");
```
## HIP Logging Example:
Below is an example to enable HIP logging and get logging information during
execution of hipinfo,
```console
user@user-test:~/hip/bin$ export AMD_LOG_LEVEL=4
user@user-test:~/hip/bin$ ./hipinfo
:3:rocdevice.cpp :453 : 23647210092: Initializing HSA stack.
:3:comgrctx.cpp :33 : 23647639336: Loading COMGR library.
:3:rocdevice.cpp :203 : 23647687108: Numa select cpu agent[0]=0x13407c0(fine=0x13409a0,coarse=0x1340ad0) for gpu agent=0x1346150
:4:runtime.cpp :82 : 23647698669: init
:3:hip_device_runtime.cpp :473 : 23647698869: 5617 : [7fad295dd840] hipGetDeviceCount: Returned hipSuccess
:3:hip_device_runtime.cpp :502 : 23647698990: 5617 : [7fad295dd840] hipSetDevice ( 0 )
:3:hip_device_runtime.cpp :507 : 23647699042: 5617 : [7fad295dd840] hipSetDevice: Returned hipSuccess
--------------------------------------------------------------------------------
device# 0
:3:hip_device.cpp :150 : 23647699276: 5617 : [7fad295dd840] hipGetDeviceProperties ( 0x7ffdbe7db730, 0 )
:3:hip_device.cpp :237 : 23647699335: 5617 : [7fad295dd840] hipGetDeviceProperties: Returned hipSuccess
Name: Device 7341
pciBusID: 3
pciDeviceID: 0
pciDomainID: 0
multiProcessorCount: 11
maxThreadsPerMultiProcessor: 2560
isMultiGpuBoard: 0
clockRate: 1900 Mhz
memoryClockRate: 875 Mhz
memoryBusWidth: 0
clockInstructionRate: 1000 Mhz
totalGlobalMem: 7.98 GB
maxSharedMemoryPerMultiProcessor: 64.00 KB
totalConstMem: 8573157376
sharedMemPerBlock: 64.00 KB
canMapHostMemory: 1
regsPerBlock: 0
warpSize: 32
l2CacheSize: 0
computeMode: 0
maxThreadsPerBlock: 1024
maxThreadsDim.x: 1024
maxThreadsDim.y: 1024
maxThreadsDim.z: 1024
maxGridSize.x: 2147483647
maxGridSize.y: 2147483647
maxGridSize.z: 2147483647
major: 10
minor: 12
concurrentKernels: 1
cooperativeLaunch: 0
cooperativeMultiDeviceLaunch: 0
arch.hasGlobalInt32Atomics: 1
arch.hasGlobalFloatAtomicExch: 1
arch.hasSharedInt32Atomics: 1
arch.hasSharedFloatAtomicExch: 1
arch.hasFloatAtomicAdd: 1
arch.hasGlobalInt64Atomics: 1
arch.hasSharedInt64Atomics: 1
arch.hasDoubles: 1
arch.hasWarpVote: 1
arch.hasWarpBallot: 1
arch.hasWarpShuffle: 1
arch.hasFunnelShift: 0
arch.hasThreadFenceSystem: 1
arch.hasSyncThreadsExt: 0
arch.hasSurfaceFuncs: 0
arch.has3dGrid: 1
arch.hasDynamicParallelism: 0
gcnArch: 1012
isIntegrated: 0
maxTexture1D: 65536
maxTexture2D.width: 16384
maxTexture2D.height: 16384
maxTexture3D.width: 2048
maxTexture3D.height: 2048
maxTexture3D.depth: 2048
isLargeBar: 0
:3:hip_device_runtime.cpp :471 : 23647701557: 5617 : [7fad295dd840] hipGetDeviceCount ( 0x7ffdbe7db714 )
:3:hip_device_runtime.cpp :473 : 23647701608: 5617 : [7fad295dd840] hipGetDeviceCount: Returned hipSuccess
:3:hip_peer.cpp :76 : 23647701731: 5617 : [7fad295dd840] hipDeviceCanAccessPeer ( 0x7ffdbe7db728, 0, 0 )
:3:hip_peer.cpp :60 : 23647701784: 5617 : [7fad295dd840] canAccessPeer: Returned hipSuccess
:3:hip_peer.cpp :77 : 23647701831: 5617 : [7fad295dd840] hipDeviceCanAccessPeer: Returned hipSuccess
peers:
:3:hip_peer.cpp :76 : 23647701921: 5617 : [7fad295dd840] hipDeviceCanAccessPeer ( 0x7ffdbe7db728, 0, 0 )
:3:hip_peer.cpp :60 : 23647701965: 5617 : [7fad295dd840] canAccessPeer: Returned hipSuccess
:3:hip_peer.cpp :77 : 23647701998: 5617 : [7fad295dd840] hipDeviceCanAccessPeer: Returned hipSuccess
non-peers: device#0
:3:hip_memory.cpp :345 : 23647702191: 5617 : [7fad295dd840] hipMemGetInfo ( 0x7ffdbe7db718, 0x7ffdbe7db720 )
:3:hip_memory.cpp :360 : 23647702243: 5617 : [7fad295dd840] hipMemGetInfo: Returned hipSuccess
memInfo.total: 7.98 GB
memInfo.free: 7.98 GB (100%)
```
## HIP Logging Tips:
- HIP logging works for both release and debug version of HIP application.
- Logging function with different logging level can be called in the code as
needed.
- Information with logging level less than AMD_LOG_LEVEL will be printed.
- If need to save the HIP logging output information in a file, just define the
file at the command when run the application at the terminal, for example,
```console
user@user-test:~/hip/bin$ ./hipinfo > ~/hip_log.txt
```