Event Notification Functions

Event Notification Functions#

ROCmSMI: Event Notification Functions

Functions
rsmi_status_t	rsmi_event_notification_init (uint32_t dv_ind)
	Prepare to collect event notifications for a GPU. More...

rsmi_status_t	rsmi_event_notification_mask_set (uint32_t dv_ind, uint64_t mask)
	Specify which events to collect for a device. More...

rsmi_status_t	rsmi_event_notification_get (int timeout_ms, uint32_t num_elem, rsmi_evt_notification_data_t data)
	Collect event notifications, waiting a specified amount of time. More...

rsmi_status_t	rsmi_event_notification_stop (uint32_t dv_ind)
	Close any file handles and free any resources used by event notification for a GPU. More...

Detailed Description

These functions are used to configure for and get asynchronous event notifications.

Function Documentation

◆ rsmi_event_notification_init()

rsmi_status_t rsmi_event_notification_init ( uint32_t dv_ind )

Prepare to collect event notifications for a GPU.

This function prepares to collect events for the GPU with device ID dv_ind, by initializing any required system parameters. This call may open files which will remain open until rsmi_event_notification_stop() is called.

Parameters

dv_ind a device index corresponding to the device on which to listen for events

Return values

RSMI_STATUS_SUCCESS is returned upon successful call.

◆ rsmi_event_notification_mask_set()

rsmi_status_t rsmi_event_notification_mask_set	(	uint32_t	dv_ind,
		uint64_t	mask
	)

Specify which events to collect for a device.

Given a device index dv_ind and a mask consisting of elements of rsmi_evt_notification_type_t OR'd together, this function will listen for the events specified in mask on the device corresponding to dv_ind.

Parameters

dv_ind a device index corresponding to the device on which to listen for events

mask Bitmask generated by OR'ing 1 or more elements of rsmi_evt_notification_type_t indicating which event types to listen for, where the rsmi_evt_notification_type_t value indicates the bit field, with bit position starting from 1. For example, if the mask field is 0x0000000000000003, which means first bit, bit 1 (bit position start from 1) and bit 2 are set, which indicate interest in receiving RSMI_EVT_NOTIF_VMFAULT (which has a value of 1) and RSMI_EVT_NOTIF_THERMAL_THROTTLE event (which has a value of 2).

Return values

RSMI_STATUS_INIT_ERROR	is returned if rsmi_event_notification_init() has not been called before a call to this function
RSMI_STATUS_SUCCESS	is returned upon successful call

◆ rsmi_event_notification_get()

rsmi_status_t rsmi_event_notification_get	(	int	timeout_ms,
		uint32_t *	num_elem,
		rsmi_evt_notification_data_t *	data
	)

Collect event notifications, waiting a specified amount of time.

Given a time period timeout_ms in milliseconds and a caller- provided buffer of rsmi_evt_notification_data_t's data with a length (in rsmi_evt_notification_data_t's, also specified by the caller) in the memory location pointed to by num_elem, this function will collect rsmi_evt_notification_type_t events for up to timeout_ms milliseconds, and write up to *num_elem event items to data. Upon return num_elem is updated with the number of events that were actually written. If events are already present when this function is called, it will write the events to the buffer then poll for new events if there is still caller-provided buffer available to write any new events that would be found.

This function requires prior calls to rsmi_event_notification_init() and rsmi_event_notification_mask_set(). This function polls for the occurrance of the events on the respective devices that were previously specified by rsmi_event_notification_mask_set().

Parameters

[in]	timeout_ms	number of milliseconds to wait for an event to occur
[in,out]	num_elem	pointer to uint32_t, provided by the caller. On input, this value tells how many rsmi_evt_notification_data_t elements are being provided by the caller with `data`. On output, the location pointed to by `num_elem` will contain the number of items written to the provided buffer.
[out]	data	pointer to a caller-provided memory buffer of size `num_elem` rsmi_evt_notification_data_t to which this function may safely write. If there are events found, up to `num_elem` event items will be written to `data`.

Return values

RSMI_STATUS_SUCCESS	The function ran successfully. The events that were found are written to `data` and `num_elems` is updated with the number of elements that were written.
RSMI_STATUS_NO_DATA	No events were found to collect.

◆ rsmi_event_notification_stop()

rsmi_status_t rsmi_event_notification_stop ( uint32_t dv_ind )

Close any file handles and free any resources used by event notification for a GPU.

Any resources used by event notification for the GPU with device index dv_ind will be free with this function. This includes freeing any memory and closing file handles. This should be called for every call to rsmi_event_notification_init()

Parameters

[in] dv_ind The device index of the GPU for which event notification resources will be free

Return values

RSMI_STATUS_INVALID_ARGS	resources for the given device have either already been freed, or were never allocated by rsmi_event_notification_init()
RSMI_STATUS_SUCCESS	is returned upon successful call