Supported Functions

Supported Functions#

ROCmSMI: Supported Functions
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;
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;
}
}
}
std::cout << "), ";
err = rsmi_func_iter_next(var_iter);
if (err == RSMI_STATUS_NO_DATA) {
break;
}
}
std::cout << std::endl;
}
err = rsmi_func_iter_next(iter_handle);
if (err == RSMI_STATUS_NO_DATA) {
break;
}
}
}
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.
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.
rsmi_status_t rsmi_func_iter_next(rsmi_func_id_iter_handle_t handle)
Advance a function identifer iterator.
rsmi_status_t rsmi_dev_supported_func_iterator_close(rsmi_func_id_iter_handle_t *handle)
Close a variant iterator handle.
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.
struct rsmi_func_id_iter_handle * rsmi_func_id_iter_handle_t
Opaque handle to function-support object.
Definition: rocm_smi.h:932
rsmi_status_t
Error codes retured by rocm_smi_lib functions.
Definition: rocm_smi.h:85
@ RSMI_STATUS_NO_DATA
Definition: rocm_smi.h:120
#define RSMI_DEFAULT_VARIANT
Definition: rocm_smi.h:936
This union holds the value of an rsmi_func_id_iter_handle_t. The value may be a function name,...
Definition: rocm_smi.h:943
uint64_t id
uint64_t representation of value
Definition: rocm_smi.h:944
const char * name
name string (applicable to functions only)
Definition: rocm_smi.h:945

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_inda device index of device for which support information is requested
[in,out]handleA pointer to caller-provided memory to which the function iterator will be written.
Return values
RSMI_STATUS_SUCCESSis 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_han iterator handle for which the variants are being requested
[in,out]var_iterA pointer to caller-provided memory to which the sub-variant iterator will be written.
Return values
RSMI_STATUS_SUCCESSis 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]handleA pointer to an iterator handle to be incremented
Return values
RSMI_STATUS_SUCCESSis returned upon successful call.
RSMI_STATUS_NO_DATAis 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]handleA pointer to an iterator handle to be closed
Return values
RSMI_STATUS_SUCCESSis 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]handleAn iterator for which the value is being requested
[in,out]valueA 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_SUCCESSis returned upon successful call.