diff --git a/projects/rocm-core/CODEOWNERS b/projects/rocm-core/CODEOWNERS index 89ea81341f..d239e886d7 100644 --- a/projects/rocm-core/CODEOWNERS +++ b/projects/rocm-core/CODEOWNERS @@ -1 +1 @@ -* @nunnikri @frepaul @raramakr @ashutom @amd-isparry +* @nunnikri @frepaul @raramakr @ashutom @amd-isparry @arvindcheru diff --git a/projects/rocm-core/CONTRIBUTING.md b/projects/rocm-core/CONTRIBUTING.md new file mode 100644 index 0000000000..002210e947 --- /dev/null +++ b/projects/rocm-core/CONTRIBUTING.md @@ -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 +``` + + +### 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) + diff --git a/projects/rocm-core/README.md b/projects/rocm-core/README.md new file mode 100644 index 0000000000..110dfdd624 --- /dev/null +++ b/projects/rocm-core/README.md @@ -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= .. +``` +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 + 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 +``` + diff --git a/projects/rocm-core/README.txt b/projects/rocm-core/README.txt deleted file mode 100644 index 2636219c54..0000000000 --- a/projects/rocm-core/README.txt +++ /dev/null @@ -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 - - 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 - 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 - - diff --git a/projects/rocm-core/copyright b/projects/rocm-core/copyright index 33843f52b6..8dc3cc8167 100644 --- a/projects/rocm-core/copyright +++ b/projects/rocm-core/copyright @@ -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