Event Notification Functions

Event Notification Functions#

AMD SMI: Event Notification Functions

Functions
amdsmi_status_t	amdsmi_init_event_notification (amdsmi_device_handle device_handle)
	Prepare to collect event notifications for a GPU. More...

amdsmi_status_t	amdsmi_set_event_notification_mask (amdsmi_device_handle device_handle, uint64_t mask)
	Specify which events to collect for a device. More...

amdsmi_status_t	amdsmi_get_event_notification (int timeout_ms, uint32_t num_elem, amdsmi_evt_notification_data_t data)
	Collect event notifications, waiting a specified amount of time. More...

amdsmi_status_t	amdsmi_stop_event_notification (amdsmi_device_handle device_handle)
	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

◆ amdsmi_init_event_notification()

amdsmi_status_t amdsmi_init_event_notification ( amdsmi_device_handle device_handle )

Prepare to collect event notifications for a GPU.

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

Parameters

device_handle a device handle corresponding to the device on which to listen for events

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

◆ amdsmi_set_event_notification_mask()

amdsmi_status_t amdsmi_set_event_notification_mask	(	amdsmi_device_handle	device_handle,
		uint64_t	mask
	)

Specify which events to collect for a device.

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

Parameters

device_handle a device handle corresponding to the device on which to listen for events

mask Bitmask generated by OR'ing 1 or more elements of amdsmi_evt_notification_type_t indicating which event types to listen for, where the amdsmi_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 AMDSMI_EVT_NOTIF_VMFAULT (which has a value of 1) and AMDSMI_EVT_NOTIF_THERMAL_THROTTLE event (which has a value of 2).

Note: AMDSMI_STATUS_INIT_ERROR is returned if amdsmi_init_event_notification() has not been called before a call to this function

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

◆ amdsmi_get_event_notification()

amdsmi_status_t amdsmi_get_event_notification	(	int	timeout_ms,
		uint32_t *	num_elem,
		amdsmi_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 amdsmi_evt_notification_data_t's data with a length (in amdsmi_evt_notification_data_t's, also specified by the caller) in the memory location pointed to by num_elem, this function will collect amdsmi_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 amdsmi_init_event_notification() and :: amdsmi_set_event_notification_mask(). This function polls for the occurrance of the events on the respective devices that were previously specified by :: amdsmi_set_event_notification_mask().

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 amdsmi_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` amdsmi_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`.

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

◆ amdsmi_stop_event_notification()

amdsmi_status_t amdsmi_stop_event_notification ( amdsmi_device_handle device_handle )

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 handle device_handle will be free with this function. This includes freeing any memory and closing file handles. This should be called for every call to amdsmi_init_event_notification()

Parameters

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

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