Build AMD SMI from source

Build AMD SMI from source#

To build AMD SMI as part of the ROCm Core SDK, see TheRock build instructions. TheRock is the recommended way to build ROCm components from source.

Alternatively, you can build AMD SMI standalone using the following instructions.

Required software#

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.

  • CMake (v3.15.0 or later) – python3 -m pip install cmake

  • g++ (v5.4.0 or later)

  • libdrm-dev (for Ubuntu and Debian)

  • libssl-dev (for Ubuntu and Debian)

  • libdrm-devel (for RPM-based distributions)

  • openssl-devel (for RPM-based distributions)

In order to build the AMD SMI Python package, the following components are required:

  • Python (3.6.8 or later)

  • virtualenv – python3 -m pip install virtualenv

Users that wish to also build the AMD SMI Rust interface will also need the following components:

  • Rust (1.56 or later)

Build steps#

  1. Clone the rocm-systems repository to your local Linux machine and sparse-checkout the AMD SMI project.

    git clone --filter=blob:none --sparse https://github.com/ROCm/rocm-systems.git
git -C rocm-systems sparse-checkout set projects/amdsmi
cd rocm-systems/projects/amdsmi

  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:

    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:

    make package

    To build with AddressSanitizer instrumentation, see Build with AddressSanitizer.

Rebuild the Python wrapper#

The Python wrapper for the AMD SMI library is found in the auto-generated file 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.

./update_wrapper.sh

After this command, the file in py-interface/amdsmi_wrapper.py will be updated on compile.

Note

You need Docker installed on your system to regenerate the Python wrapper.

Build the tests#

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. Follow these steps to build the tests:

mkdir -p build
cd build
cmake -DBUILD_TESTS=ON ..
make -j $(nproc)

Run the tests#

Once the tests are built, you can run them by executing the amdsmitst program. The executable can be found at build/tests/amd_smi_test/.

Build with AddressSanitizer#

-DADDRESS_SANITIZER=ON instruments the library and the C/C++ tests.

cmake -DADDRESS_SANITIZER=ON ..
make -j $(nproc)

-DENABLE_ASAN_PACKAGING=ON produces a library-only amd-smi-lib-asan package. The CLI and the Python bindings are excluded from it because neither can load an instrumented libamd_smi.so unaided; see below.

Run the CLI or the Python bindings against an instrumented library#

amd-smi is a Python script, and the bindings are ctypes, so both reach the library through dlopen. AddressSanitizer has to be initialized before the process allocates any memory, which is long before dlopen runs, so an uninstrumented Python aborts with:

==1234==ASan runtime does not come first in initial library list; you should
either link runtime to your application or manually preload it with LD_PRELOAD.

Preload the runtime the library was linked against. Leak detection has to be off because CPython does not free everything at shutdown.

ASAN_RT=$(ldd build/lib/libamd_smi.so | awk '/libclang_rt\.asan|libasan/ && $3 ~ /^\// {print $3}')
[ -n "$ASAN_RT" ] || echo "No ASAN runtime resolved; rebuild with -DADDRESS_SANITIZER=ON."
LD_PRELOAD=$ASAN_RT ASAN_OPTIONS=detect_leaks=0 amd-smi static

An empty ASAN_RT means the library is either uninstrumented or instrumented against a runtime that is not on the search path, which ldd reports as => not found.

This applies to any Python process that imports amdsmi, not just the CLI. C and C++ consumers linked with -fsanitize=address need no preload, because the runtime is already in their initial library list.

Build the docs#

The C/C++ API reference is generated with Doxygen 1.15.0, which must be installed separately and available on your PATH.

  1. Create a Python virtual environment and install documentation dependencies.

    # From rocm-systems/projects/amdsmi
python3.12 -m venv docs/.venv
source docs/.venv/bin/activate
pip install -r docs/sphinx/requirements.txt

  2. Use the following command to build the documentation using Sphinx.

    python -m sphinx docs docs/_build -j auto -E -v

  3. Open docs/_build/index.html in your web browser to view the documentation. To serve the site locally instead, run:

    python -m http.server -d docs/_build
# Go to http://localhost:8000 in your browser

For related information, see Building documentation.

Contents