Event Notification Functions

Event Notification Functions#

AMD SMI: Event Notification Functions

Functions
amdsmi_status_t	amdsmi_init_gpu_event_notification (amdsmi_processor_handle processor_handle)
	Prepare to collect event notifications for a GPU. More...

amdsmi_status_t	amdsmi_set_gpu_event_notification_mask (amdsmi_processor_handle processor_handle, uint64_t mask)
	Specify which events to collect for a device. More...

amdsmi_status_t	amdsmi_get_gpu_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_gpu_event_notification (amdsmi_processor_handle processor_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_gpu_event_notification()

amdsmi_status_t amdsmi_init_gpu_event_notification ( amdsmi_processor_handle processor_handle )

Prepare to collect event notifications for a GPU.

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

Parameters

processor_handle a processor 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_gpu_event_notification_mask()

amdsmi_status_t amdsmi_set_gpu_event_notification_mask	(	amdsmi_processor_handle	processor_handle,
		uint64_t	mask
	)

Specify which events to collect for a device.

Given a processor handle processor_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 processor_handle.

Parameters

processor_handle a processor 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_gpu_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_gpu_event_notification()

amdsmi_status_t amdsmi_get_gpu_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_gpu_event_notification() and :: amdsmi_set_gpu_event_notification_mask(). This function polls for the occurrance of the events on the respective devices that were previously specified by :: amdsmi_set_gpu_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_gpu_event_notification()

amdsmi_status_t amdsmi_stop_gpu_event_notification ( amdsmi_processor_handle processor_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 processor handle processor_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_gpu_event_notification()

Parameters

[in] processor_handle The processor 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