AI/rocm-systems
2
0
Fork 0
Code Issues Pull-Requests Actions Pakete Projekte Releases Wiki Aktivität

docs: Remove redundant/stale docs

Quellcode durchsuchen 
bump rocm-docs-core to 1.8.2

rm unused files

rm stale docs

fix sphinx conf

reorg docs

SWDEV-482203 -- add note to usage guides

update readmes

Change-Id: I9e0111ac8fe2a691ac964b27436ba47747c27904
Signed-off-by: Peter Park <Peter.Park@amd.com>
Dieser Commit ist enthalten in:
Peter Park
2024-10-02 14:42:34 -04:00
committet von Maisam Arif
Ursprung 6e843436f5
Commit e196f98dba
26 geänderte Dateien mit 2871 neuen und 7034 gelöschten Zeilen
Patch-Datei herunterladen Vergleichs-Datei herunterladen Alle Dateien ausklappen Alle Dateien einklappen
README.md
+154 -293
Datei anzeigen
@@ -1,345 +1,195 @@
# AMD System Management Interface (AMD SMI) Library
# AMD System Management Interface (AMD SMI) library
The AMD System Management Interface Library, or AMD SMI library, is a C library for Linux that provides a user space interface for applications to monitor and control AMD devices.
The AMD System Management Interface (AMD SMI) library offers a unified tool for managing and monitoring GPUs,
particularly in high-performance computing environments. It provides a user-space interface that allows applications to
control GPU operations, monitor performance, and retrieve information about the system's drivers and GPUs.
For additional information refer to [ROCm Documentation](https://rocm.docs.amd.com/projects/amdsmi/en/latest/)
For information on available features, installation steps, API reference material, and helpful tips, refer to the online
documentation at [rocm.docs.amd.com/projects/amdsmi](https://rocm.docs.amd.com/projects/amdsmi/en/latest/)
Note: This project is a successor to [rocm_smi_lib](https://github.com/RadeonOpenCompute/rocm_smi_lib)
and [esmi_ib_library](https://github.com/amd/esmi_ib_library)
>[!NOTE]
>This project is a successor to [rocm_smi_lib](https://github.com/ROCm/rocm_smi_lib)
>and [esmi_ib_library](https://github.com/amd/esmi_ib_library).
## Supported platforms
At initial release, the AMD SMI library will support Linux bare metal and Linux virtual machine guest for AMD GPUs. In the future release, the library will be extended to support AMD EPYC™ CPUs.
At initial release, the AMD SMI library will support Linux bare metal and Linux
virtual machine guest for AMD GPUs. In a future release, the library will be
extended to support AMD EPYC™ CPUs.
AMD SMI library can run on AMD ROCm supported platforms, refer to [System requirements (Linux)](https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html) for more information.
AMD SMI library can run on AMD ROCm supported platforms, refer to
[System requirements (Linux)](https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html)
for more information.
To run the AMD SMI library, the amdgpu driver and the hsmp driver needs to be installed. Optionally, the libdrm can be
installed to query firmware information and hardware IPs.
## Installation
## Install CLI Tool and Libraries
* [Install the AMD SMI library and CLI tool](https://rocm.docs.amd.com/projects/amdsmi/en/latest/install/install.html)
**Disclaimer: CLI Tool is provided as an example code to aid the development of telemetry tools and is not guaranteed to be backwards compatible. The Python or C++ Library is recommended as a reliable data source.**
## Requirements
The following are required to install and use the AMD SMI libraries and CLI tool.
### Requirements
* Python 3.6.8+ (64-bit)
* `amdgpu` driver must be loaded for [`amdsmi_init()`](./docs/how-to/amdsmi-cpp-lib#hello-amd-smi) to work.
* python 3.6.8+ 64-bit
- prerequisite modules:
- python3-wheel
- python3-setuptools
* amdgpu driver must be loaded for amdsmi_init() to pass
## Install amdgpu driver and AMD SMI with ROCm
### Installation
1. Get the `amdgpu-install` installer following the instructions for your Linux distribution at
[Installation via AMDGPU installer](https://rocm.docs.amd.com/projects/install-on-linux/en/latest/install/amdgpu-install.html#installation).
### Install amdgpu using ROCm
* Install amdgpu driver:
See example below, your release and link may differ. The `amdgpu-install --usecase=rocm` triggers both an amdgpu driver update and AMD SMI packages to be installed on your device.
```shell
sudo apt update
wget https://repo.radeon.com/amdgpu-install/6.0.2/ubuntu/jammy/amdgpu-install_6.0.60002-1_all.deb
sudo apt install ./amdgpu-install_6.0.60002-1_all.deb
sudo amdgpu-install --usecase=rocm
```
* amd-smi --help
2. Use `amdgpu-install` to install the `amdgpu` driver and ROCm packages with
AMD SMI included.
### Install Example for Ubuntu 22.04 (without ROCm)
``` shell
sudo amdgpu-install --usecase=rocm
```
``` bash
apt install amd-smi-lib
# if installed with rocm ignore the export
export PATH="${PATH:+${PATH}:}~/opt/rocm/bin"
amd-smi --help
```
The `amdgpu-install --usecase=rocm` option triggers both an `amdgpu` driver
update and AMD SMI packages to be installed on your device.
### Optional autocompletion
3. Verify your installation.
`amd-smi` cli application supports autocompletion. The package should attempt to install it, if argcomplete is not installed you can enable it by using the following commands:
```shell
amd-smi --help
```
```bash
python3 -m pip install argcomplete
activate-global-python-argcomplete --user
# restart shell to enable
```
## Install AMD SMI without ROCm
### Manual/Multiple Rocm Instance Python Library Install
The following are example steps to install the AMD SMI libraries and CLI tool on
Ubuntu 22.04.
In the event there are multiple rocm installations and pyenv is not being used, to use the correct amdsmi version you must uninstall previous versions of amd-smi and install the version you want directly from your rocm instance.
1. Install the library.
#### Python Library Install Example for Ubuntu 22.04
```shell
sudo apt install amd-smi-lib
```
Remove previous amdsmi installation:
2. Add the installation directory to your PATH. If installed with ROCm, ignore
this step.
```bash
python3 -m pip list | grep amd
python3 -m pip uninstall amdsmi
```
```shell
export PATH="${PATH:+${PATH}:}~/opt/rocm/bin"
```
Then install Python library from your target rocm instance:
3. Verify your installation.
``` bash
apt install amd-smi-lib
cd /opt/rocm/share/amd_smi
python3 -m pip install --upgrade pip
python3 -m pip install --user .
```
```shell
amd-smi --help
```
Now you have the amdsmi python library in your python path:
## AMD SMI basic usage
``` bash
~$ python3
Python 3.8.10 (default, May 26 2023, 14:05:08)
[GCC 9.4.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import amdsmi
>>>
```
### C++ library
### Installing the Python Prerequisite Modules
For developers focused on performance monitoring, system diagnostics, or resource management, the AMD SMI C++ library
offers a powerful and versatile tool to unlock the full capabilities of AMD hardware.
Python3-setuptools and python3-wheel can both be installed through the pip installer as shown below:
Refer to the [user guide](https://rocm.docs.amd.com/projects/amdsmi/en/latest/how-to/amdsmi-cpp-lib.html) and the
detailed [C++ API reference](https://rocm.docs.amd.com/projects/amdsmi/en/latest/reference/amdsmi-cpp-api.html) in the
ROCm documentation portal.
```bash
python3 -m pip install setuptools wheel
```
### Python library
## Usage Basics for the C Library
The AMD SMI Python interface provides an easy-to-use
[API](https://rocm.docs.amd.com/projects/amdsmi/en/latest/reference/amdsmi-py-lib.html) for interacting with AMD
hardware. It simplifies tasks like monitoring and controlling GPU operations, allowing for rapid development.
### Device/Socket handles
Refer to the [user guide](https://rocm.docs.amd.com/projects/amdsmi/en/latest/how-to/amdsmi-py-lib.html) and the
detailed [Python API reference](https://rocm.docs.amd.com/projects/amdsmi/en/latest/reference/amdsmi-py-api.html) in the
ROCm documentation portal.
Many of the functions in the library take a "socket handle" or "device handle". The socket is an abstraction of hardware physical socket. This will enable amd-smi to provide a better representation of the hardware to user. Although there is always one distinct GPU for a socket, the APU may have both
GPU device and CPU device on the same socket. Moreover, for MI200, it may have multiple GCDs.
### CLI tool
To discover the sockets in the system, `amdsmi_get_socket_handles()` is called to get list of sockets
handles, which in turn can be used to query the devices in that socket using `amdsmi_get_processor_handles()`. The device handler is used to distinguish the detected devices from one another. It is important to note that a device may end up with a different device handles after restart application, so a device handle should not be relied upon to be constant over process.
A versatile command line tool for managing and monitoring AMD hardware. You can use `amd-smi` for:
The list of socket handles discovered using `amdsmi_get_socket_handles()`,can also be used to query the cpus in that socket using `amdsmi_get_processor_handles_by_type()`, which in turn can then be used to query the cores in that cpu using `amdsmi_get_processor_handles_by_type()` again.
- Device information: Quickly retrieve detailed information about AMD GPUs
- Performance monitoring: Real-time monitoring of GPU utilization, memory, temperature, and power consumption
## Hello AMD SMI
- Process information: Identify which processes are using GPUs
The only required AMD-SMI call for any program that wants to use AMD-SMI is the `amdsmi_init()` call. This call initializes some internal data structures that will be used by subsequent AMD-SMI calls. In the call, a flag can be passed if the application is only interested in a specific device type.
- Configuration management: Adjust GPU settings like clock speeds and power limits
When AMD-SMI is no longer being used, `amdsmi_shut_down()` should be called. This provides a way to do any releasing of resources that AMD-SMI may have held.
- Error reporting: Monitor and report GPU errors for proactive maintenance
1) A simple "Hello World" type program that displays the temperature of detected devices would look like this:
```c++
#include <iostream>
#include <vector>
#include "amd_smi/amdsmi.h"
int main() {
amdsmi_status_t ret;
// Init amdsmi for sockets and devices. Here we are only interested in AMD_GPUS.
ret = amdsmi_init(AMDSMI_INIT_AMD_GPUS);
// Get all sockets
uint32_t socket_count = 0;
// Get the socket count available in the system.
ret = amdsmi_get_socket_handles(&socket_count, nullptr);
// Allocate the memory for the sockets
std::vector<amdsmi_socket_handle> sockets(socket_count);
// Get the socket handles in the system
ret = amdsmi_get_socket_handles(&socket_count, &sockets[0]);
std::cout << "Total Socket: " << socket_count << std::endl;
// For each socket, get identifier and devices
for (uint32_t i=0; i < socket_count; i++) {
// Get Socket info
char socket_info[128];
ret = amdsmi_get_socket_info(sockets[i], 128, socket_info);
std::cout << "Socket " << socket_info<< std::endl;
// Get the device count for the socket.
uint32_t device_count = 0;
ret = amdsmi_get_processor_handles(sockets[i], &device_count, nullptr);
// Allocate the memory for the device handlers on the socket
std::vector<amdsmi_processor_handle> processor_handles(device_count);
// Get all devices of the socket
ret = amdsmi_get_processor_handles(sockets[i],
&device_count, &processor_handles[0]);
// For each device of the socket, get name and temperature.
for (uint32_t j=0; j < device_count; j++) {
// Get device type. Since the amdsmi is initialized with
// AMD_SMI_INIT_AMD_GPUS, the processor_type must be AMDSMI_PROCESSOR_TYPE_AMD_GPU.
processor_type_t processor_type;
ret = amdsmi_get_processor_type(processor_handles[j], &processor_type);
if (processor_type != AMDSMI_PROCESSOR_TYPE_AMD_GPU) {
std::cout << "Expect AMDSMI_PROCESSOR_TYPE_AMD_GPU device type!\n";
return 1;
}
// Get device name
amdsmi_board_info_t board_info;
ret = amdsmi_get_gpu_board_info(processor_handles[j], &board_info);
std::cout << "\tdevice "
<< j <<"\n\t\tName:" << board_info.product_name << std::endl;
// Get temperature
int64_t val_i64 = 0;
ret = amdsmi_get_temp_metric(processor_handles[j], AMDSMI_TEMPERATURE_TYPE_EDGE,
AMDSMI_TEMP_CURRENT, &val_i64);
std::cout << "\t\tTemperature: " << val_i64 << "C" << std::endl;
}
}
// Clean up resources allocated at amdsmi_init. It will invalidate sockets
// and devices pointers
ret = amdsmi_shut_down();
return 0;
}
```
2) A sample program that displays the power of detected cpus would look like this:
```c++
#include <iostream>
#include <vector>
#include "amd_smi/amdsmi.h"
int main(int argc, char **argv) {
amdsmi_status_t ret;
uint32_t socket_count = 0;
// Initialize amdsmi for AMD CPUs
ret = amdsmi_init(AMDSMI_INIT_AMD_CPUS);
ret = amdsmi_get_socket_handles(&socket_count, nullptr);
// Allocate the memory for the sockets
std::vector<amdsmi_socket_handle> sockets(socket_count);
// Get the sockets of the system
ret = amdsmi_get_socket_handles(&socket_count, &sockets[0]);
std::cout << "Total Socket: " << socket_count << std::endl;
// For each socket, get cpus
for (uint32_t i = 0; i < socket_count; i++) {
uint32_t cpu_count = 0;
// Set processor type as AMDSMI_PROCESSOR_TYPE_AMD_CPU
processor_type_t processor_type = AMDSMI_PROCESSOR_TYPE_AMD_CPU;
ret = amdsmi_get_processor_handles_by_type(sockets[i], processor_type, nullptr, &cpu_count);
// Allocate the memory for the cpus
std::vector<amdsmi_processor_handle> plist(cpu_count);
// Get the cpus for each socket
ret = amdsmi_get_processor_handles_by_type(sockets[i], processor_type, &plist[0], &cpu_count);
for (uint32_t index = 0; index < plist.size(); index++) {
uint32_t socket_power;
std::cout<<"CPU "<<index<<"\t"<< std::endl;
std::cout<<"Power (Watts): ";
ret = amdsmi_get_cpu_socket_power(plist[index], &socket_power);
if(ret != AMDSMI_STATUS_SUCCESS)
std::cout<<"Failed to get cpu socket power"<<"["<<index<<"] , Err["<<ret<<"] "<< std::endl;
if (!ret) {
std::cout<<static_cast<double>(socket_power)/1000<<std::endl;
}
std::cout<<std::endl;
}
}
// Clean up resources allocated at amdsmi_init
ret = amdsmi_shut_down();
return 0;
}
```
### Documentation
The reference manual, `AMD_SMI_Manual.pdf` will be in the /opt/rocm/share/doc/amd_smi directory upon a successful build.
### Sphinx Documentation
To build the documentation locally, run the commands below:
``` bash
cd docs
python3 -m pip install -r sphinx/requirements.txt
python3 -m sphinx -T -E -b html -d _build/doctrees -D language=en . _build/html
```
The output will be in `docs/_build/html`.
For additional details, see [Contribute to ROCm documentation](https://rocm.docs.amd.com/en/latest/contribute/contributing.html).
Check out
[Getting to Know Your GPU: A Deep Dive into AMD SMI -- ROCm Blogs](https://rocm.blogs.amd.com/software-tools-optimization/amd-smi-overview/README.html)
for a rundown.
## Building AMD SMI
### Rebuilding Python wrapper
This section describes the prerequisites and steps to build AMD SMI from source.
The python wrapper (binding) is an auto-generated file `py-interface/amdsmi_wrapper.py`
### Required software
Wrapper should be re-generated on each C++ API change, by doing:
To build the AMD SMI library, the following components are required. Note that the software versions specified were used
during development; earlier versions are not guaranteed to work.
```bash
* CMake (v3.14.0 or later) -- `python3 -m pip install cmake`
* g++ (v5.4.0 or later)
In order to build the AMD SMI Python package, the following components are required:
* Python (3.6.8 or later)
* prerequisite modules:
* python3-wheel
* python3-setuptools
* virtualenv -- `python3 -m pip install virtualenv`
### Build steps
1. Clone the AMD SMI repository to your local Linux machine.
```shell
git clone https://github.com/ROCm/amdsmi.git
```
2. The default installation location for the library and headers is `/opt/rocm`. Before installation, any old ROCm
directories should be deleted:
* `/opt/rocm`
* `/opt/rocm-<version_number>`
3. Build the library by following the typical CMake build sequence (run as root user or use `sudo` before `make install`
command); for instance:
```bash
mkdir -p build
cd build
cmake ..
make -j $(nproc)
make install
```
The built library is located in the `build/` directory. To build the `rpm` and `deb` packages use the following
command:
```bash
make package
```
### Rebuild the Python wrapper
The Python wrapper for the AMD SMI library is found in the [auto-generated file](#py_lib_fs)
`py-interface/amdsmi_wrapper.py`. It is essential to regenerate this wrapper whenever there are changes to the C++ API.
It is not regenerated automatically.
To regenerate the wrapper, use the following command.
```shell
./update_wrapper.sh
```
After this command, the file in `py-interface/amdsmi_wrapper.py` will be automatically updated on each compile.
After this command, the file in `py-interface/amdsmi_wrapper.py` will be updated
on compile.
Note: To be able to re-generate python wrapper you need **docker** installed.
>[!NOTE]
>You need Docker installed on your system to regenerate the Python wrapper.
Note: python_wrapper is NOT automatically re-generated. You must run `./update_wrapper.sh`.
### Build the tests
### Additional Required software for building
In order to build the AMD SMI library, the following components are required. Note that the software versions listed are what was used in development. Earlier versions are not guaranteed to work:
* CMake (v3.14.0) - `python3 -m pip install cmake`
* g++ (5.4.0)
In order to build the AMD SMI python package, the following components are required:
* python (3.6.8 or above)
* virtualenv - `python3 -m pip install virtualenv`
In order to build the latest documentation, the following are required:
* DOxygen (1.8.11)
* latex (pdfTeX 3.14159265-2.6-1.40.16)
The source code for AMD SMI is available on Github.
After the AMD SMI library git repository has been cloned to a local Linux machine, the Default location for the library and headers is /opt/rocm. Before installation, the old rocm directories should be deleted:
/opt/rocm
/opt/rocm-{number}
Building the library is achieved by following the typical CMake build sequence (run as root user or use 'sudo' before 'make install' command), specifically:
```bash
mkdir -p build
cd build
cmake ..
make -j $(nproc)
make install
```
The built library will appear in the `build` folder.
To build the rpm and deb packages follow the above steps with:
```bash
make package
```
### Building the Tests
In order to verify the build and capability of AMD SMI on your system and to see an example of how AMD SMI can be used, you may build and run the tests that are available in the repo. To build the tests, follow these steps:
To verify the build and capabilities of AMD SMI on your system, as well as to see practical examples of its usage, you
can build and run the available [tests in the repository](https://github.com/ROCm/amdsmi/tree/amd-staging/tests). Follow
these steps to build the tests:
```bash
mkdir -p build
@@ -348,13 +198,24 @@ cmake -DBUILD_TESTS=ON ..
make -j $(nproc)
```
### Run the Tests
#### Run the tests
To run the test, execute the program `amdsmitst` that is built from the steps above.
Path to the program `amdsmitst`: build/tests/amd_smi_test/
Once the tests are [built](#build-the-tests), you can run them by executing the `amdsmitst` program. The executable can
be found at `build/tests/amd_smi_test/`.
### Build the docs
To build the documentation, follow the instructions at
[Building documentation](https://rocm.docs.amd.com/en/latest/contribute/building.html).
## DISCLAIMER
The information contained herein is for informational purposes only, and is subject to change without notice. In addition, any stated support is planned and is also subject to change. While every precaution has been taken in the preparation of this document, it may contain technical inaccuracies, omissions and typographical errors, and AMD is under no obligation to update or otherwise correct this information. Advanced Micro Devices, Inc. makes no representations or warranties with respect to the accuracy or completeness of the contents of this document, and assumes no liability of any kind, including the implied warranties of noninfringement, merchantability or fitness for particular purposes, with respect to the operation or use of AMD hardware, software or other products described herein.
The information contained herein is for informational purposes only, and is subject to change without notice. In
addition, any stated support is planned and is also subject to change. While every precaution has been taken in the
preparation of this document, it may contain technical inaccuracies, omissions and typographical errors, and AMD is
under no obligation to update or otherwise correct this information. Advanced Micro Devices, Inc. makes no
representations or warranties with respect to the accuracy or completeness of the contents of this document, and assumes
no liability of any kind, including the implied warranties of noninfringement, merchantability or fitness for particular
purposes, with respect to the operation or use of AMD hardware, software or other products described herein.
© 2023-2024 Advanced Micro Devices, Inc. All Rights Reserved.