Supported Functions

Supported Functions#

ROCmSMI: Supported Functions

Functions
rsmi_status_t	rsmi_dev_supported_func_iterator_open (uint32_t dv_ind, rsmi_func_id_iter_handle_t *handle)
	Get a function name iterator of supported RSMI functions for a device. More...

rsmi_status_t	rsmi_dev_supported_variant_iterator_open (rsmi_func_id_iter_handle_t obj_h, rsmi_func_id_iter_handle_t *var_iter)
	Get a variant iterator for a given handle. More...

rsmi_status_t	rsmi_func_iter_next (rsmi_func_id_iter_handle_t handle)
	Advance a function identifer iterator. More...

rsmi_status_t	rsmi_dev_supported_func_iterator_close (rsmi_func_id_iter_handle_t *handle)
	Close a variant iterator handle. More...

rsmi_status_t	rsmi_func_iter_value_get (rsmi_func_id_iter_handle_t handle, rsmi_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, rsmi_dev_temp_metric_get may support some types of temperature metrics (e.g., RSMI_TEMP_CRITICAL_HYST), but not others (e.g., RSMI_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 rsmi_dev_temp_metric_get example, if variant RSMI_TEMP_CRITICAL_HYST is supported, perhaps only the sub-variant sensors RSMI_TEMP_TYPE_EDGE and RSMI_TEMP_TYPE_EDGE are supported, but not RSMI_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", RSMI_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 RSMI types.

 rsmi_func_id_iter_handle_t iter_handle, var_iter, sub_var_iter;
 rsmi_func_id_value_t value;
 rsmi_status_t err;
 
 for (uint32_t i = 0; i < <number of devices>; ++i) {
  std::cout << "Supported RSMI Functions:" << std::endl;
  std::cout << "\tVariants (Monitors)" << std::endl;
 
  err = rsmi_dev_supported_func_iterator_open(i, &iter_handle);
 
  while (1) {
    err = rsmi_func_iter_value_get(iter_handle, &value);
    std::cout << "Function Name: " << value.name << std::endl;
 
    err = rsmi_dev_supported_variant_iterator_open(iter_handle, &var_iter);
    if (err != RSMI_STATUS_NO_DATA) {
      std::cout << "\tVariants/Monitors: ";
      while (1) {
        err = rsmi_func_iter_value_get(var_iter, &value);
        if (value.id == RSMI_DEFAULT_VARIANT) {
          std::cout << "Default Variant ";
        } else {
          std::cout << value.id;
        }
        std::cout << " (";
 
        err =
          rsmi_dev_supported_variant_iterator_open(var_iter, &sub_var_iter);
        if (err != RSMI_STATUS_NO_DATA) {
 
          while (1) {
            err = rsmi_func_iter_value_get(sub_var_iter, &value);
            std::cout << value.id << ", ";
 
            err = rsmi_func_iter_next(sub_var_iter);
 
            if (err == RSMI_STATUS_NO_DATA) {
              break;
            }
          }
          err = rsmi_dev_supported_func_iterator_close(&sub_var_iter);
        }
 
        std::cout << "), ";
 
        err = rsmi_func_iter_next(var_iter);
 
        if (err == RSMI_STATUS_NO_DATA) {
          break;
        }
      }
      std::cout << std::endl;
 
      err = rsmi_dev_supported_func_iterator_close(&var_iter);
    }
 
    err = rsmi_func_iter_next(iter_handle);
 
    if (err == RSMI_STATUS_NO_DATA) {
      break;
    }
  }
  err = rsmi_dev_supported_func_iterator_close(&iter_handle);
}

Function Documentation

◆ rsmi_dev_supported_func_iterator_open()

rsmi_status_t rsmi_dev_supported_func_iterator_open	(	uint32_t	dv_ind,
		rsmi_func_id_iter_handle_t *	handle
	)

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

Given a device index dv_ind, 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 dv_ind as an argument, rsmi_dev_supported_func_iterator_open itself will not be among the functions listed as supported. This is because rsmi_dev_supported_func_iterator_open does not depend on hardware or driver support and should always be supported.

Parameters

[in]	dv_ind	a device index 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.

Return values

RSMI_STATUS_SUCCESS is returned upon successful call.

◆ rsmi_dev_supported_variant_iterator_open()

rsmi_status_t rsmi_dev_supported_variant_iterator_open	(	rsmi_func_id_iter_handle_t	obj_h,
		rsmi_func_id_iter_handle_t *	var_iter
	)

Get a variant iterator for a given handle.

Given a rsmi_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 rsmi_dev_supported_func_iterator_open, or it may be a variant itself (from a call to rsmi_dev_supported_variant_iterator_open), 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 rsmi_dev_supported_func_iterator_close 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.

Return values

RSMI_STATUS_SUCCESS is returned upon successful call.

◆ rsmi_func_iter_next()

rsmi_status_t rsmi_func_iter_next ( rsmi_func_id_iter_handle_t handle )

Advance a function identifer iterator.

Given a function id iterator handle (rsmi_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, RSMI_STATUS_NO_DATA is returned.

Parameters

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

Return values

RSMI_STATUS_SUCCESS	is returned upon successful call.
RSMI_STATUS_NO_DATA	is returned when list of identifiers has been exhausted

◆ rsmi_dev_supported_func_iterator_close()

rsmi_status_t rsmi_dev_supported_func_iterator_close ( rsmi_func_id_iter_handle_t * handle )

Close a variant iterator handle.

Given a pointer to an rsmi_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

Return values

RSMI_STATUS_SUCCESS is returned upon successful call.

◆ rsmi_func_iter_value_get()

rsmi_status_t rsmi_func_iter_value_get	(	rsmi_func_id_iter_handle_t	handle,
		rsmi_func_id_value_t *	value
	)

Get the value associated with a function/variant iterator.

Given an rsmi_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 rsmi_func_id_value_t provided by the caller to which this function will write the value assocaited with `handle`

Return values

RSMI_STATUS_SUCCESS is returned upon successful call.