Supported Functions

Supported Functions#

AMD SMI: Supported Functions

Functions
amdsmi_status_t	amdsmi_dev_open_supported_func_iterator (amdsmi_device_handle device_handle, amdsmi_func_id_iter_handle_t *handle)
	Get a function name iterator of supported AMDSMI functions for a device. More...

amdsmi_status_t	amdsmi_dev_open_supported_variant_iterator (amdsmi_func_id_iter_handle_t obj_h, amdsmi_func_id_iter_handle_t *var_iter)
	Get a variant iterator for a given handle. More...

amdsmi_status_t	amdsmi_next_func_iter (amdsmi_func_id_iter_handle_t handle)
	Advance a function identifer iterator. More...

amdsmi_status_t	amdsmi_dev_close_supported_func_iterator (amdsmi_func_id_iter_handle_t *handle)
	Close a variant iterator handle. More...

amdsmi_status_t	amdsmi_get_func_iter_value (amdsmi_func_id_iter_handle_t handle, amdsmi_func_id_value_t *value)
	Get the value associated with a function/variant iterator. More...

Detailed Description

API function support varies by both GPU type and the version of the installed ROCm stack. The functions described in this section can be used to determine, up front, which functions are supported for a given device on a system. If such "up front" knowledge of support for a function is not needed, alternatively, one can call a device related function and check the return code.

Some functions have several variations ("variants") where some variants are supported and others are not. For example, on a given device, :: amdsmi_dev_get_temp_metric may support some types of temperature metrics (e.g., AMDSMI_TEMP_CRITICAL_HYST), but not others (e.g., AMDSMI_TEMP_EMERGENCY).

In addition to a top level of variant support for a function, a function may have varying support for monitors/sensors. These are considered "sub-variants" in functions described in this section. Continuing the :: amdsmi_dev_get_temp_metric example, if variant AMDSMI_TEMP_CRITICAL_HYST is supported, perhaps only the sub-variant sensors ::AMDSMI_TEMP_TYPE_EDGE and ::AMDSMI_TEMP_TYPE_EDGE are supported, but not ::AMDSMI_TEMP_TYPE_MEMORY.

In cases where a function takes in a sensor id parameter but does not have any "top level" variants, the functions in this section will indicate a default "variant", AMDSMI_DEFAULT_VARIANT, for the top level variant, and the various monitor support will be sub-variants of this.

The functions in this section use the "iterator" concept to list which functions are supported; to list which variants of the supported functions are supported; and finally which monitors/sensors are supported for a variant.

Here is example code that prints out all supported functions, their supported variants and sub-variants. Please see the related descriptions functions and AMDSMI types.

 amdsmi_func_id_iter_handle_t iter_handle, var_iter, sub_var_iter;
 amdsmi_func_id_value_t value;
 amdsmi_status_t err;
 amdsmi_device_handle device;
 
 // Get the device handle via amdsmi_get_device_handles()
 // ... ...
 
 std::cout << "Supported AMDSMI Functions:" << std::endl; *
 err = amdsmi_dev_open_supported_func_iterator(device, &iter_handle);
 
 while (1) {
    err = amdsmi_get_func_iter_value(iter_handle, &value);
    std::cout << "Function Name: " << value.name << std::endl;
 
    err = amdsmi_dev_open_supported_variant_iterator(iter_handle, &var_iter);
    if (err != AMDSMI_STATUS_NO_DATA) {
      std::cout << "\tVariants/Monitors: ";
      while (1) {
        err = amdsmi_get_func_iter_value(var_iter, &value);
        if (value.id == AMDSMI_DEFAULT_VARIANT) {
          std::cout << "Default Variant ";
        } else {
          std::cout << value.id;
        }
        std::cout << " (";
 
        err =
          amdsmi_dev_open_supported_variant_iterator(var_iter, &sub_var_iter);
        if (err != AMDSMI_STATUS_NO_DATA) {
 
          while (1) {
            err = amdsmi_get_func_iter_value(sub_var_iter, &value);
            std::cout << value.id << ", ";
 
            err = amdsmi_next_func_iter(sub_var_iter);
 
            if (err == AMDSMI_STATUS_NO_DATA) {
              break;
            }
          }
          err = amdsmi_dev_close_supported_func_iterator(&sub_var_iter);
        }
 
        std::cout << "), ";
 
        err = amdsmi_next_func_iter(var_iter);
 
        if (err == AMDSMI_STATUS_NO_DATA) {
          break;
        }
      }
      std::cout << std::endl;
 
      err = amdsmi_dev_close_supported_func_iterator(&var_iter);
    }
 
    err = amdsmi_next_func_iter(iter_handle);
 
    if (err == AMDSMI_STATUS_NO_DATA) {
      break;
    }
  }
  err = amdsmi_dev_close_supported_func_iterator(&iter_handle);
}

Function Documentation

◆ amdsmi_dev_open_supported_func_iterator()

amdsmi_status_t amdsmi_dev_open_supported_func_iterator	(	amdsmi_device_handle	device_handle,
		amdsmi_func_id_iter_handle_t *	handle
	)

Get a function name iterator of supported AMDSMI functions for a device.

Given a device handle device_handle, this function will write a function iterator handle to the caller-provided memory pointed to by handle. This handle can be used to iterate through all the supported functions.

Note that although this function takes in device_handle as an argument, amdsmi_dev_open_supported_func_iterator itself will not be among the functions listed as supported. This is because amdsmi_dev_open_supported_func_iterator does not depend on hardware or driver support and should always be supported.

Parameters

[in]	device_handle	a device handle of device for which support information is requested
[in,out]	handle	A pointer to caller-provided memory to which the function iterator will be written.

Returns: amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

◆ amdsmi_dev_open_supported_variant_iterator()

amdsmi_status_t amdsmi_dev_open_supported_variant_iterator	(	amdsmi_func_id_iter_handle_t	obj_h,
		amdsmi_func_id_iter_handle_t *	var_iter
	)

Get a variant iterator for a given handle.

Given a amdsmi_func_id_iter_handle_t obj_h, this function will write a function iterator handle to the caller-provided memory pointed to by var_iter. This handle can be used to iterate through all the supported variants of the provided handle. obj_h may be a handle to a function object, as provided by a call to amdsmi_dev_open_supported_func_iterator, or it may be a variant itself (from a call to amdsmi_dev_open_supported_variant_iterator), it which case var_iter will be an iterator of the sub-variants of obj_h (e.g., monitors).

This call allocates a small amount of memory to var_iter. To free this memory amdsmi_dev_close_supported_func_iterator should be called on the returned iterator handle var_iter when it is no longer needed.

Parameters

[in]	obj_h	an iterator handle for which the variants are being requested
[in,out]	var_iter	A pointer to caller-provided memory to which the sub-variant iterator will be written.

Returns: amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

◆ amdsmi_next_func_iter()

amdsmi_status_t amdsmi_next_func_iter ( amdsmi_func_id_iter_handle_t handle )

Advance a function identifer iterator.

Given a function id iterator handle (amdsmi_func_id_iter_handle_t) handle, this function will increment the iterator to point to the next identifier. After a successful call to this function, obtaining the value of the iterator handle will provide the value of the next item in the list of functions/variants.

If there are no more items in the list, AMDSMI_STATUS_NO_DATA is returned.

Parameters

[in] handle A pointer to an iterator handle to be incremented

Returns: amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

◆ amdsmi_dev_close_supported_func_iterator()

amdsmi_status_t amdsmi_dev_close_supported_func_iterator ( amdsmi_func_id_iter_handle_t * handle )

Close a variant iterator handle.

Given a pointer to an amdsmi_func_id_iter_handle_t handle, this function will free the resources being used by the handle

Parameters

[in] handle A pointer to an iterator handle to be closed

Returns: amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail

◆ amdsmi_get_func_iter_value()

amdsmi_status_t amdsmi_get_func_iter_value	(	amdsmi_func_id_iter_handle_t	handle,
		amdsmi_func_id_value_t *	value
	)

Get the value associated with a function/variant iterator.

Given an amdsmi_func_id_iter_handle_t handle, this function will write the identifier of the function/variant to the user provided memory pointed to by value.

value may point to a function name, a variant id, or a monitor/sensor index, depending on what kind of iterator handle is

Parameters

[in]	handle	An iterator for which the value is being requested
[in,out]	value	A pointer to an amdsmi_func_id_value_t provided by the caller to which this function will write the value assocaited with `handle`

Returns: amdsmi_status_t | AMDSMI_STATUS_SUCCESS on success, non-zero on fail