AI/rocm-systems
2
0
Forka 0
Codice Problemi Pull Request Actions Pacchetti Progetti Rilasci Wiki Attività

Update ROCM-CORE contributing template and basics docs (#9)

Sfoglia il codice sorgente 
* Add Contributing documentation as per template, updated Readme documentation and Update codeowners
* Moving Readme.txt to Readme.md format 
* Update Review Comments - CMAKE commands Updated, removed library dump and added API usage
* Update Review Comments - Enhanced Text descriptions, prerequisites/install prefix descriptions
* Update Review Comments - Added RPM Package Samples also and Enhanced Descriptions

[ROCm/rocm-core commit: d11f5c20d5]
This commit is contained in:
arvindcheru
2024-12-02 23:24:44 -05:00
committato da GitHub
parent 6d58b23fc2
commit ad46bff375
5 ha cambiato i file con 380 aggiunte e 107 eliminazioni
Scarica il file Patch Scarica il file Diff Expand all files Collapse all files
projects/rocm-core/CODEOWNERS
+1 -1
Vedi File
@@ -1 +1 @@
* @nunnikri @frepaul @raramakr @ashutom @amd-isparry
* @nunnikri @frepaul @raramakr @ashutom @amd-isparry @arvindcheru
projects/rocm-core/CONTRIBUTING.md
+161
Vedi File
@@ -0,0 +1,161 @@
# ROCM-CORE Contributing Guide
To ensure the quality of the ROCM-CORE code base, the ROCM-CORE team has
established a code review process to inform developers of the steps
that are required to shepherd a change-set into the repository.
#### Table Of Contents
[How to get started](#How-to-get-started)
[How do I contribute?](#how-do-i-contribute)
* [Reporting Issues](#reporting-issues)
* [Creating a Pull Request](#Creating-a-Pull-Request)
[Responsibility of the Author](#Responsibility-of-the-Author)
[Responsibility of the Reviewer](#Responsibility-of-the-Reviewer)
[The Review](#the-review)
[References](#References)
## How to get started
rocm-core is a utility which can be used to get ROCm release version.
It also provides the Lmod modules files for the ROCm release.
getROCmVersion function provides the ROCm version.
## How do I contribute
### Deliverables
All contributions you make will be under the [MIT Software License](copyright).
For each new file in repository,
Please include the licensing header
```
/*******************************************************************************
*
* MIT License
*
* Copyright (c) 20xx Advanced Micro Devices, Inc.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in all
* copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*
*******************************************************************************/
```
### Formatting the code
All the code is formatted using `clang-format`. To format a file, use:
```shell
clang-format-10 -style=file -i <path-to-source-file>
```
### Reporting Issues
We use [GitHub Issues](https://github.com/ROCm/rocm-core/issues) to track public **bugs** and **enhancement requests**.
#### Bugs
Please follow the template below to report any bugs found in ROCM-CORE:
1. Description: ***Please be clear and descriptive***
2. How to Reproduce the issue:
* Hardware Information:
* Docker environment or Software Version:
* Expected behavior:
* Actual behavior:
3. Any additional information:
#### Enhancement Requests
Please follow the template below to report any enhancement requests for ROCM-CORE:
1. Description: ***Please be clear and descriptive***
2. Value and Motivation:
* Feature and functionalities enabled:
* Any alternatives:
3. Any additional information:
The author must set labels (and assigns a milestone) according to his/her own understanding.
Other contributors can change these values if they disagree. That being said,
adding a small comment explaining the motivation is highly recommended.
In this way, we keep the process flexible while cultivating mutual understanding.
[**Note**] Most likely, the labels like "bug", "feature" or "complexity*"
would not be changed. However, "value*" or "urgency*" might be from mutual
understanding.
### Creating a Pull Request
No changes are allowed to be directly committed to the develop
branch of the ROCM-CORE repository. All authors are required to
develop their change sets on a separate branch and then create
a pull request (PR) to merge their changes into the develop branch.
Once a PR has been created, a developer must choose two reviewers
to review the changes made. The first reviewer should be a
technical expert in the portion of the library that the changes
are being made in. You can find a list of these experts in
[CODEOWNERS](CODEOWNERS) list.
The second reviewer should be a peer reviewer. This reviewer
can be any other ROCM-CORE developer.
## Responsibility of the Author
The author of a PR is responsible for:
* Writing clear, well documented code
* Meeting expectations of code quality
* Verifying that the changes do not break current functionality
* Writing tests to ensure code coverage
* Report on the impact to performance
## Responsibility of the Reviewer
Each reviewer is responsible for verifying that the changes are
clearly written in keeping with the coding styles of the library,
are documented in a way that future developers will be able to
understand the intent of the added functionality, and will
maintain or improve the overall quality of the codebase.
Reviewer's task checklist:
1. Has the PR passed?
2. Does the PR consist of a well-organized sequence of small commits,
each of which is designed to make one specific feature or fix ?
3. Does the PR only include a reviewable amount of changes? Or it is a
consolidation of already reviewed small batches? e.g. break it into smaller
testable and reviewable tasks instead of a huge chunk at once.
4. Does the PR have sufficient documentation and easy to read and understand,
feasible for test and future maintainence, related docs already in place?
if API or functionality has changed?
5. For bugfixes and new features, new regression test created?
6. Is every PR associated with a ticket or issue number for tracking purposes?
## The Review
During the review, reviewers will look over the changes and make
suggestions or requests for changes.
In order to assist the reviewer in prioritizing their efforts,
authors can take the following actions:
* Set the urgency and value labels
* Set the milestone where the changes need to be delivered
* Describe the testing procedure and post the measured effect of
the change
* Remind reviewers via email if a PR needs attention
* If a PR needs to be reviewed as soon as possible, explain to
the reviewers why a review may need to take priority
## References
1. [ROCM-CORE Readme](README.md)
projects/rocm-core/README.md
+217
Vedi File
@@ -0,0 +1,217 @@
# ROCM-CORE Introduction
ROCM-CORE is a package which can be used to get ROCm release version, get ROCm install path information etc.
It is also important to note that ROCM-CORE takes the role as a base component on which all of ROCm can depend,
to make it easy to remove all of ROCm with a package manager.
getROCmVersion function provides the ROCm version.
It also provides an example Lmod modules files for the ROCm release.
Lmod module files can be loaded with the following commands.
``` shell
module load rocm/x.y or
module load rocm
```
You can find sources and binaries in our [GitHub repository](https://github.com/ROCm/rocm-core).
> [!NOTE]
> As with all ROCm projects, the documentation is open source. For more information, see [Contribute to ROCm documentation](https://rocm.docs.amd.com/en/latest/contribute/contributing.html).
## Installing ROCM-CORE
Before we proceed with how to install, take a look on references given below to understand System requirements, ROCm Installation prerequisites, ROCm package repository set up etc.
### Prerequisite References
* Refer [System Requirements](https://rocm.docs.amd.com/projects/install-on-linux/en/docs-6.2.2/reference/system-requirements.html#supported-gpus)
* Refer [ROCm installation for Linux](https://rocm.docs.amd.com/projects/install-on-linux/en/docs-6.2.2/index.html)
* A [ROCm](https://rocm.docs.amd.com/)-enabled platform
* To be noted that ROCM-CORE library primarily depends on having the C library available for the respective platform.
### Installing with pre-built packages
You can install ROCM-CORE on Ubuntu using
```shell
apt-get install rocm-core
```
## Building ROCM-CORE from source
You can build ROCM-CORE form source
First, get the sources from repository.
```shell
git clone https://github.com/ROCm/rocm-core.git
```
Go to Root Directory, create a build directory:
```shell
cd rocm-core; mkdir build; cd build
```
Next, configure CMake. Invoke cmake with the following variables define as deemed fit
```shell
cmake -S $PWD/../ -B . \
-DCMAKE_VERBOSE_MAKEFILE=1 \
-DCMAKE_INSTALL_PREFIX=./ \
-DROCM_VERSION="6.4.0" \
..
```
>[!NOTE]
>When specifying the path for the `CMAKE_PREFIX_PATH` variable, **do not** use the tilde (`~`)
>shorthand to represent the home directory.
### Setting up install locations
By default, the install location is set to `/opt/rocm`. You can change this using
`CMAKE_INSTALL_PREFIX`:
```shell
cmake -DCMAKE_INSTALL_PREFIX=<rocm-core-install-path> ..
```
where rocm-core-install-path is "./" in the cmake configure command shared above.
### Install
Once cmake configuration successfully completed, from the same build directory run build, install targets
```shell
cmake --build . --
cmake --build . -- install
```
### Package Generated
Once cmake configuration and build successfully completed from the same build directory trigger package generation
```shell
cmake --build . -- package
```
Once successfull execution of above command "rocm-core" RPM/DEBIAN packages will be generated (ex:rocm-core_6.4.0.60400-22.04_amd64.deb, rocm-core-6.4.0.60400-x86_64.rpm). The contents of the "rocm-core" package will include the following files:
```shell
Debian Package Sample:
$ dpkg -I rocm-core_6.4.0.60400-crdnnh.15158~22.04_amd64.deb
new debian package, version 2.0.
size 13986 bytes: control archive=2083 bytes.
305 bytes, 10 lines control
917 bytes, 11 lines md5sums
2871 bytes, 75 lines * postinst #!/bin/bash
873 bytes, 32 lines * prerm #!/bin/bash
Architecture: amd64
Description: Radeon Open Compute (ROCm) Runtime software stack
Homepage: https://github.com/RadeonOpenCompute/ROCm
Maintainer: ROCm Dev Support <rocm-dev.support@amd.com>
Package: rocm-core
Priority: optional
Section: devel
Version: 6.4.0.60400-crdnnh.15158~22.04
Installed-Size: 125
$ dpkg -c rocm-core_6.4.0.60400-crdnnh.15158~22.04_amd64.deb
drwxr-xr-x root/root 0 2024-11-22 10:37 ./opt/
drwxr-xr-x root/root 0 2024-11-22 10:37 ./opt/rocm-6.4.0/
drwxr-xr-x root/root 0 2024-11-22 10:37 ./opt/rocm-6.4.0/.info/
-rw-r--r-- root/root 12 2024-11-22 10:37 ./opt/rocm-6.4.0/.info/version
drwxr-xr-x root/root 0 2024-11-22 10:37 ./opt/rocm-6.4.0/include/
drwxr-xr-x root/root 0 2024-11-22 10:37 ./opt/rocm-6.4.0/include/rocm-core/
-rw-r--r-- root/root 2801 2024-11-22 10:37 ./opt/rocm-6.4.0/include/rocm-core/rocm_getpath.h
-rw-r--r-- root/root 2440 2024-11-22 10:37 ./opt/rocm-6.4.0/include/rocm-core/rocm_version.h
drwxr-xr-x root/root 0 2024-11-22 10:37 ./opt/rocm-6.4.0/lib/
drwxr-xr-x root/root 0 2024-11-22 10:37 ./opt/rocm-6.4.0/lib/cmake/
drwxr-xr-x root/root 0 2024-11-22 10:37 ./opt/rocm-6.4.0/lib/cmake/rocm-core/
-rw-r--r-- root/root 2878 2024-11-22 10:37 ./opt/rocm-6.4.0/lib/cmake/rocm-core/rocm-core-config-version.cmake
-rw-r--r-- root/root 1590 2024-11-22 10:37 ./opt/rocm-6.4.0/lib/cmake/rocm-core/rocm-core-config.cmake
-rw-r--r-- root/root 842 2024-11-22 10:37 ./opt/rocm-6.4.0/lib/cmake/rocm-core/rocmCoreTargets-release.cmake
-rw-r--r-- root/root 3774 2024-11-22 10:37 ./opt/rocm-6.4.0/lib/cmake/rocm-core/rocmCoreTargets.cmake
lrwxrwxrwx root/root 0 2024-11-22 10:37 ./opt/rocm-6.4.0/lib/librocm-core.so -> librocm-core.so.1
lrwxrwxrwx root/root 0 2024-11-22 10:37 ./opt/rocm-6.4.0/lib/librocm-core.so.1 -> librocm-core.so.1.0.60400
-rw-r--r-- root/root 16640 2024-11-22 10:37 ./opt/rocm-6.4.0/lib/librocm-core.so.1.0.60400
-rw-r--r-- root/root 550 2024-11-22 10:37 ./opt/rocm-6.4.0/lib/rocmmod
drwxr-xr-x root/root 0 2024-11-22 10:37 ./opt/rocm-6.4.0/libexec/
drwxr-xr-x root/root 0 2024-11-22 10:37 ./opt/rocm-6.4.0/libexec/rocm-core/
-rw-r--r-- root/root 8208 2024-11-22 10:34 ./opt/rocm-6.4.0/libexec/rocm-core/runpath_to_rpath.py
drwxr-xr-x root/root 0 2024-11-22 10:37 ./opt/rocm-6.4.0/share/
drwxr-xr-x root/root 0 2024-11-22 10:37 ./opt/rocm-6.4.0/share/doc/
drwxr-xr-x root/root 0 2024-11-22 10:37 ./opt/rocm-6.4.0/share/doc/rocm-core/
-rw-r--r-- root/root 1113 2024-11-22 10:34 ./opt/rocm-6.4.0/share/doc/rocm-core/LICENSE.txt
RPM Package Sample:
$ rpm -qip rocm-core-6.4.0.60400-crdnnh.15158.el8.x86_64.rpm
Name : rocm-core
Version : 6.4.0.60400
Release : crdnnh.15158.el8
Architecture: x86_64
Install Date: (not installed)
Group : unknown
Size : 37096
License : MIT
Signature : (none)
Source RPM : rocm-core-6.4.0.60400-crdnnh.15158.el8.src.rpm
Build Date : Fri 22 Nov 2024 10:41:01 AM PST
Build Host : 514dbdf6c195
Relocations : /opt/rocm-6.4.0
Vendor : Advanced Micro Devices, Inc.
Summary : Radeon Open Compute (ROCm) Runtime software stack
Description :
DESCRIPTION
===========
This is an installer created using CPack (https://cmake.org). No additional installation instructions provided.
$ rpm -qlp rocm-core-6.4.0.60400-crdnnh.15158.el8.x86_64.rpm
/opt/rocm-6.4.0
/opt/rocm-6.4.0/.info
/opt/rocm-6.4.0/.info/version
/opt/rocm-6.4.0/include
/opt/rocm-6.4.0/include/rocm-core
/opt/rocm-6.4.0/include/rocm-core/rocm_getpath.h
/opt/rocm-6.4.0/include/rocm-core/rocm_version.h
/opt/rocm-6.4.0/lib
/opt/rocm-6.4.0/lib/cmake
/opt/rocm-6.4.0/lib/cmake/rocm-core
/opt/rocm-6.4.0/lib/cmake/rocm-core/rocm-core-config-version.cmake
/opt/rocm-6.4.0/lib/cmake/rocm-core/rocm-core-config.cmake
/opt/rocm-6.4.0/lib/cmake/rocm-core/rocmCoreTargets-release.cmake
/opt/rocm-6.4.0/lib/cmake/rocm-core/rocmCoreTargets.cmake
/opt/rocm-6.4.0/lib/librocm-core.so
/opt/rocm-6.4.0/lib/librocm-core.so.1
/opt/rocm-6.4.0/lib/librocm-core.so.1.0.60400
/opt/rocm-6.4.0/lib/rocmmod
/opt/rocm-6.4.0/libexec
/opt/rocm-6.4.0/libexec/rocm-core
/opt/rocm-6.4.0/libexec/rocm-core/runpath_to_rpath.py
/opt/rocm-6.4.0/share
/opt/rocm-6.4.0/share/doc
/opt/rocm-6.4.0/share/doc/rocm-core
/opt/rocm-6.4.0/share/doc/rocm-core/LICENSE.txt
```
## ROCM-CORE Library
ROCM-CORE Library generated will be found in lib directory of the rocm-core package generated.
```shell
find . -name "librocm-core.so.*"
```
### Sample Usage of APIs provided by rocm-core Library
#### Get ROCm Version
For getting ROCm Version make use of getROCMVersion() API.
Sample Usage Example as shown below.
```C
// Usage :
int mj=0,mn=0,p=0,ret=0;
ret=getROCMVersion(&mj,&mn,&p);
if(ret !=VerSuccess ) // error occured
```
projects/rocm-core/README.txt
-105
Vedi File
@@ -1,105 +0,0 @@
Introduction:
rocm-core is a utility which can be used to get ROCm release version.
It also provides the Lmod modules files for the ROCm release.
getROCmVersion function provides the ROCm version.
Lmod module files can be loaded with the following commads.
module load rocm/x.y or
module load rocm
Build:
git clone <URL to git repo >
cd rocm-core; mkdir -p build ; cd build
After this invoke cmake with the following variables define as deemed fit
cmake \
-DCMAKE_CURRENT_BINARY_DIR=$PWD \
-DCMAKE_CURRENT_SOURCE_DIR=$PWD/../ \
-DCMAKE_VERBOSE_MAKEFILE=1 \
-DCMAKE_INSTALL_PREFIX=./ \
-DCPACK_GENERATOR=DEB \
-DCPACK_DEBIAN_PACKAGE_RELEASE="local.9999~20.04" \
-DCPACK_RPM_PACKAGE_RELEASE="local.9999" \
-DROCM_VERSION="5.5.0" \
..
make
make install
make package
After this the package "rocm-core_1.0.0-local_amd64.deb" will be generated accordingly
The content of which will be the following :
$dpkg -I rocm-core_1.0.0-local_amd64.deb
new Debian package, version 2.0.
size 6604 bytes: control archive=1608 bytes.
285 bytes, 10 lines control
191 bytes, 3 lines md5sums
2360 bytes, 65 lines * postinst #!/bin/bash
593 bytes, 25 lines * prerm #!/bin/bash
Architecture: amd64
Description: Radeon Open Compute (ROCm) Runtime software stack
Homepage: https://github.com/RadeonOpenCompute/ROCm
Maintainer: ROCm Dev Support <rocm-dev.support@amd.com>
Package: rocm-core
Priority: optional
Section: devel
Version: 1.0.0-local
Installed-Size: 70
$dpkg -c rocm-core_1.0.0-local_amd64.deb
drwxrwxr-x root/root 0 2022-11-09 09:02 ./opt/
drwxrwxr-x root/root 0 2022-11-09 09:02 ./opt/rocm/
drwxrwxr-x root/root 0 2022-11-09 09:02 ./opt/rocm/include/
-rw-r--r-- root/root 2970 2022-11-09 09:02 ./opt/rocm/include/rocm_version.h
drwxrwxr-x root/root 0 2022-11-09 09:02 ./opt/rocm/lib/
lrwxrwxrwx root/root 0 2022-11-09 09:02 ./opt/rocm/lib/librocm-core.so -> librocm-core.so.1
lrwxrwxrwx root/root 0 2022-11-09 09:02 ./opt/rocm/lib/librocm-core.so.1 -> librocm-core.so.1.0.0.
-rwxr-xr-x root/root 17096 2022-11-09 09:02 ./opt/rocm/lib/librocm-core.so.1.0.0.
-rw-r--r-- root/root 420 2022-11-09 09:02 ./opt/rocm/lib/rocmmod
The flags for the lib would the following :
$readelf -d ./opt/rocm/lib/librocm-core.so.1.0.0.
Dynamic section at offset 0x2de0 contains 28 entries:
Tag Type Name/Value
0x0000000000000001 (NEEDED) Shared library: [libstdc++.so.6]
0x0000000000000001 (NEEDED) Shared library: [libgcc_s.so.1]
0x0000000000000001 (NEEDED) Shared library: [libc.so.6]
0x000000000000000e (SONAME) Library soname: [librocm-core.so.1]
0x000000000000000c (INIT) 0x1000
0x000000000000000d (FINI) 0x12dc
0x0000000000000019 (INIT_ARRAY) 0x3dd0
0x000000000000001b (INIT_ARRAYSZ) 8 (bytes)
0x000000000000001a (FINI_ARRAY) 0x3dd8
0x000000000000001c (FINI_ARRAYSZ) 8 (bytes)
0x000000006ffffef5 (GNU_HASH) 0x2f0
0x0000000000000005 (STRTAB) 0x480
0x0000000000000006 (SYMTAB) 0x318
0x000000000000000a (STRSZ) 558 (bytes)
0x000000000000000b (SYMENT) 24 (bytes)
0x0000000000000003 (PLTGOT) 0x4000
0x0000000000000002 (PLTRELSZ) 168 (bytes)
0x0000000000000014 (PLTREL) RELA
0x0000000000000017 (JMPREL) 0x820
0x0000000000000007 (RELA) 0x760
0x0000000000000008 (RELASZ) 192 (bytes)
0x0000000000000009 (RELAENT) 24 (bytes)
0x000000006ffffffb (FLAGS_1) Flags: NODELETE
0x000000006ffffffe (VERNEED) 0x6d0
0x000000006fffffff (VERNEEDNUM) 3
0x000000006ffffff0 (VERSYM) 0x6ae
0x000000006ffffff9 (RELACOUNT) 3
0x0000000000000000 (NULL) 0x0
projects/rocm-core/copyright
+1 -1
Vedi File
@@ -1,6 +1,6 @@
MIT License
Copyright (c) 2017 - 2023 Advanced Micro Devices, Inc. All rights Reserved.
Copyright (c) 2017 - 2024 Advanced Micro Devices, Inc. All rights Reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal