AMD SMI Python interface overview

AMD SMI Python interface overview#

The AMD SMI Python interface provides a convenient way to interact with AMD hardware through a simple and accessible API.

See also

Refer to the Python library API reference.

Prerequisites#

Before get started, make sure your environment satisfies the following prerequisites. See the requirements section for more information.

  1. Ensure amdgpu drivers are installed properly for initialization.

  2. Export LD_LIBRARY_PATH to the amdsmi installation directory.

    export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/rocm/lib:/opt/rocm/lib64:

  3. Install Python 3.6.8+.

Get started#

Note

hipcc and other compilers will not automatically link in the libamd_smi dynamic library. To compile code that uses the AMD SMI library API, ensure the libamd_smi.so can be located by setting the LD_LIBRARY_PATH environment variable to the directory containing librocm_smi64.so (usually /opt/rocm/lib) or by passing the -lamd_smi flag to the compiler.

Note

The following environment variables can be set to control internal cache durations. They must be set before the AMDSMI library loads.

Variable

Description

Default

AMDSMI_GPU_METRICS_CACHE_MS

GPU metrics cache duration (ms)

1 ms (set to 0 to disable)

AMDSMI_ASIC_INFO_CACHE_MS

GPU ASIC info cache duration (ms)

10000 ms (set to 0 to disable)

You can set these in one of two ways:

  1. In Python (before the AMDSMI library loads):

    import os
os.environ["AMDSMI_GPU_METRICS_CACHE_MS"] = "200"
from amdsmi import *

  2. From the shell (when invoking Python):

    AMDSMI_GPU_METRICS_CACHE_MS=200 python tools/amdsmi_quick_start.py

To get started, the amdsmi folder should be copied and placed next to the importing script. Import it as follows:

from amdsmi import *

try:
    amdsmi_init()

    # amdsmi calls ...

except AmdSmiException as e:
    print(e)
finally:
    try:
        amdsmi_shut_down()
    except AmdSmiException as e:
        print(e)

Folder structure#

File name

Description

__init__.py

Python package initialization file

amdsmi_interface.py

Amdsmi library Python interface

amdsmi_wrapper.py

Python wrapper around amdsmi binary

amdsmi_exception.py

Amdsmi exceptions Python file

Usage#

An application using AMD SMI must call amdsmi_init() to initialize the AMI SMI library before all other calls. This call initializes the internal data structures required for subsequent AMD SMI operations. In the call, a flag can be passed to indicate if the application is interested in a specific device type.

amdsmi_shut_down() must be the last call to properly close connection to driver and make sure that any resources held by AMD SMI are released.

See also

Refer to the Python library API reference.

Exceptions#

All exceptions are in amdsmi_exception.py file.

Exceptions that can be thrown by AMD SMI are:

  • AmdSmiException: base amdsmi exception class

  • AmdSmiLibraryException: derives base AmdSmiException class and represents errors that can occur in amdsmi-lib. When this exception is thrown, err_code and err_info are set. err_code is an integer that corresponds to errors that can occur in amdsmi-lib and err_info is a string that explains the error that occurred.

    try:
    num_of_GPUs = len(amdsmi_get_processor_handles())
except amdsmi_exception.AmdSmiLibraryException as e:
    print("Unable to get processor handles, error: {} {}".format(str(e.get_error_code()), e.err_info))

  • AmdSmiParameterException: Derives base AmdSmiException class and represents errors related to invalid parameters passed to functions. When this exception is thrown, err_msg is set and it explains what is the actual and expected type of the parameters.

    For example:

    try:
    processor_handles = amdsmi_get_cpusocket_handles()
    if len(processor_handles) == 0:
        print("No CPU sockets on machine")
    else:
        for processor in processor_handles:
            temperature = amdsmi_get_cpu_socket_temperature(processor)
            print(temperature)
except amdsmi_exception.AmdSmiParameterException as e:
    print("Invalid parameter error: {} {}".format(str(e.get_error_code()), e.err_msg))
except amdsmi_exception.AmdSmiLibraryException as e:
    print("Unable to get processor handles, error: {} {}".format(str(e.get_error_code()), e.err_info))
Contents