Is this page helpful?

Event Handling Methods#

This chapter describes methods that NVML can perform against each device to register and wait for some event to occur.

Macros#

NVML_COMPUTE_INSTANCE_ID_ANY

Sentinel value used when no MIG compute instance ID applies.

NVML_GPU_INSTANCE_ID_ANY

Sentinel value used when no MIG GPU instance ID applies.

NVML_OPERATIONAL_EVENT_ATTR_COMPONENT_RESET

Event involved a component reset.

NVML_OPERATIONAL_EVENT_ATTR_LATENT

Event reports a latent condition.

NVML_OPERATIONAL_EVENT_ATTR_OVERFLOW

One or more events or associated payloads were dropped before this event was returned.

NVML_OPERATIONAL_EVENT_ATTR_PRIMARY

Event is the primary event in its group.

NVML_OPERATIONAL_EVENT_ATTR_PROPAGATED

Event was propagated from another source.

NVML_OPERATIONAL_EVENT_ATTR_THRESHOLD_EXCEEDED

Event reports an exceeded threshold.

NVML_OPERATIONAL_EVENT_ATTR_UNCONTAINED

Event reports an uncontained condition.

NVML_OPERATIONAL_EVENT_GROUP_ATTR_PREVERR

Event group reports a previous error condition.

NVML_OPERATIONAL_EVENT_GROUP_ATTR_RECOVERED

Event group reports a recovered condition.

NVML_OPERATIONAL_EVENT_GROUP_ATTR_SIMULATED

Event group was generated by simulation or testing.

nvmlSystemEventSetCreateRequest_v1

nvmlSystemEventSetFreeRequest_v1

nvmlSystemEventSetWaitRequest_v1

nvmlSystemEventTypeCount

Number of system event types.

nvmlSystemEventTypeGpuDriverBind

Bitmask value of Driver Bind System Event.

nvmlSystemEventTypeGpuDriverUnbind

System Event for GPU Driver Unbind.

nvmlSystemRegisterEventRequest_v1

Enumerations#

nvmlEventDataType_t

Event data formats returned by nvmlEventSetWait_v3 .

nvmlGpuOperationalEventContextType_t

NVML-defined GPU Operational Event context classifications.

nvmlGpuOperationalEventLogLevel_t

Log-level values used by GPU Operational Events.

nvmlOperationalEventSeverity_t

Severity values used by Operational Events.

Functions#

nvmlReturn_t nvmlDeviceGetSupportedEventTypes(nvmlDevice_t device, unsigned long long *eventTypes)

Returns information about events supported on device.

nvmlReturn_t nvmlDeviceRegisterEvents(nvmlDevice_t device, unsigned long long eventTypes, nvmlEventSet_t set)

Starts recording of events on a specified devices and add the events to specified nvmlEventSet_t .

nvmlReturn_t nvmlEventSetCreate(nvmlEventSet_t *set)

Create an empty set of events.

nvmlReturn_t nvmlEventSetFree(nvmlEventSet_t set)

Releases events in the set.

nvmlReturn_t nvmlEventSetGetContextCount_v1(nvmlEventSet_t set, nvmlEventSetGetContextCount_v1_t *params)

Gets the number of context records for the most recent event returned by nvmlEventSetWait_v3 on this event set.

nvmlReturn_t nvmlEventSetGetContextData_v1(nvmlEventSet_t set, nvmlEventSetGetContextData_v1_t *params)

Copies the raw payload for a context record from the most recent event returned by nvmlEventSetWait_v3 .

nvmlReturn_t nvmlEventSetGetContextInfo_v1(nvmlEventSet_t set, nvmlEventSetGetContextInfo_v1_t *params)

Gets metadata for a context record from the most recent event returned by nvmlEventSetWait_v3 .

nvmlReturn_t nvmlEventSetGetGpuOperationalEventContextLegacyXid_v1(nvmlEventSet_t set, nvmlEventSetGetGpuOperationalEventContextLegacyXid_v1_t *params)

Gets decoded GPU legacy-Xid context data for a context record from the most recent event returned by nvmlEventSetWait_v3 .

nvmlReturn_t nvmlEventSetRegisterGpuOperationalEvents_v1(nvmlEventSet_t eventSet, const nvmlGpuOperationalEventConfig_v1_t *config)

Adds a GPU Operational Event subscription to an event set.

nvmlReturn_t nvmlEventSetWait_v2(nvmlEventSet_t set, nvmlEventData_t *data, unsigned int timeoutms)

Waits on events and delivers events.

nvmlReturn_t nvmlEventSetWait_v3(nvmlEventSet_t set, nvmlEventSetWait_v3_t *params)

Waits on an event set and returns the next event in the extended event format.

nvmlReturn_t nvmlSystemEventSetCreate(nvmlSystemEventSetCreateRequest_t *request)

Create an empty set of system events.

nvmlReturn_t nvmlSystemEventSetFree(nvmlSystemEventSetFreeRequest_t *request)

Releases system event set.

nvmlReturn_t nvmlSystemEventSetWait(nvmlSystemEventSetWaitRequest_t *request)

Waits on system events and delivers events.

nvmlReturn_t nvmlSystemRegisterEvents(nvmlSystemRegisterEventRequest_t *request)

Starts recording of events on system and add the events to specified nvmlSystemEventSet_t .

Groups#

Event Types

Event Types which user can be notified about.

Structs#

nvmlEventData_t

Information about occurred event.

nvmlEventSetGetContextCount_v1_t

Parameters for retrieving the number of context records associated with the most recent event.

nvmlEventSetGetContextData_v1_t

Parameters for retrieving raw context data associated with the most recent event.

nvmlEventSetGetContextInfo_v1_t

Parameters for retrieving context metadata associated with the most recent event.

nvmlEventSetGetGpuOperationalEventContextLegacyXid_v1_t

Parameters for retrieving decoded GPU legacy-Xid context data.

nvmlSystemEventData_v1_t

nvmlSystemEventData_v1_t

nvmlSystemEventSetCreateRequest_v1_t

nvmlSystemEventSetCreateRequest

nvmlSystemEventSetFreeRequest_v1_t

nvmlSystemEventSetFreeRequest

nvmlSystemEventSetWaitRequest_v1_t

nvmlSystemEventSetWait

nvmlSystemRegisterEventRequest_v1_t

nvmlSystemRegisterEventRequest

Typedefs#

nvmlEventSet_t

Handle to an event set.

nvmlSystemEventSetCreateRequest_t

nvmlSystemEventSetFreeRequest_t

nvmlSystemEventSetWaitRequest_t

nvmlSystemEventSet_t

System Event Set.

nvmlSystemRegisterEventRequest_t

Macros#

NVML_COMPUTE_INSTANCE_ID_ANY#

Sentinel value used when no MIG compute instance ID applies.

NVML_GPU_INSTANCE_ID_ANY#

Sentinel value used when no MIG GPU instance ID applies.

NVML_OPERATIONAL_EVENT_ATTR_COMPONENT_RESET#

Event involved a component reset.

NVML_OPERATIONAL_EVENT_ATTR_LATENT#

Event reports a latent condition.

NVML_OPERATIONAL_EVENT_ATTR_OVERFLOW#

One or more events or associated payloads were dropped before this event was returned.

NVML_OPERATIONAL_EVENT_ATTR_PRIMARY#

Event is the primary event in its group.

NVML_OPERATIONAL_EVENT_ATTR_PROPAGATED#

Event was propagated from another source.

NVML_OPERATIONAL_EVENT_ATTR_THRESHOLD_EXCEEDED#

Event reports an exceeded threshold.

NVML_OPERATIONAL_EVENT_ATTR_UNCONTAINED#

Event reports an uncontained condition.

NVML_OPERATIONAL_EVENT_GROUP_ATTR_PREVERR#

Event group reports a previous error condition.

NVML_OPERATIONAL_EVENT_GROUP_ATTR_RECOVERED#

Event group reports a recovered condition.

NVML_OPERATIONAL_EVENT_GROUP_ATTR_SIMULATED#

Event group was generated by simulation or testing.

nvmlSystemEventSetCreateRequest_v1#
nvmlSystemEventSetFreeRequest_v1#
nvmlSystemEventSetWaitRequest_v1#
nvmlSystemEventTypeCount#

Number of system event types.

nvmlSystemEventTypeGpuDriverBind#

Bitmask value of Driver Bind System Event.

nvmlSystemEventTypeGpuDriverUnbind#

System Event for GPU Driver Unbind.

Bitmask value of Driver Unbind System Event

nvmlSystemRegisterEventRequest_v1#

Enumerations#

enum nvmlEventDataType_t#

Event data formats returned by nvmlEventSetWait_v3.

Values:

enumerator NVML_EVENT_DATA_TYPE_NVML_EVENT#

NVML event-bit data. eventType contains an NVML event bit.

enumerator NVML_EVENT_DATA_TYPE_GPU_OPERATIONAL_EVENT#

Structured GPU Operational Event data.

enum nvmlGpuOperationalEventContextType_t#

NVML-defined GPU Operational Event context classifications.

These values describe the NVML public interpretation of a context payload. The original source-defined context type is returned separately in nvmlEventSetGetContextInfo_v1_t::sourceEventContextType.

Values:

enumerator NVML_GPU_OPERATIONAL_EVENT_CONTEXT_TYPE_UNKNOWN#

No NVML public interpretation is defined for this context payload.

enumerator NVML_GPU_OPERATIONAL_EVENT_CONTEXT_TYPE_LEGACY_XID#

Context payload can be decoded with nvmlEventSetGetGpuOperationalEventContextLegacyXid_v1.

enum nvmlGpuOperationalEventLogLevel_t#

Log-level values used by GPU Operational Events.

These values are used both for event reporting in nvmlEventSetWait_v3_t and for subscription filtering in nvmlGpuOperationalEventConfig_v1_t. Higher numeric values represent more selective log levels. NVML_GPU_OPERATIONAL_EVENT_LOG_LEVEL_ALL disables log-level filtering when used as a subscription threshold. Event data may contain newer log-level values that are not named in this header; clients should handle unrecognized numeric values.

Values:

enumerator NVML_GPU_OPERATIONAL_EVENT_LOG_LEVEL_ALL#

Matches all GPU Operational Event log levels.

enumerator NVML_GPU_OPERATIONAL_EVENT_LOG_LEVEL_TELEMETRY#

High-volume telemetry events.

enumerator NVML_GPU_OPERATIONAL_EVENT_LOG_LEVEL_DIAG#

Diagnostic events.

enumerator NVML_GPU_OPERATIONAL_EVENT_LOG_LEVEL_NOTICE#

Notable operational events.

enumerator NVML_GPU_OPERATIONAL_EVENT_LOG_LEVEL_WARNING#

Warning events.

enumerator NVML_GPU_OPERATIONAL_EVENT_LOG_LEVEL_ERROR#

Error events.

enum nvmlOperationalEventSeverity_t#

Severity values used by Operational Events.

These values are used both for event reporting in nvmlEventSetWait_v3_t and for subscription filtering in nvmlGpuOperationalEventConfig_v1_t. Higher numeric values represent more selective severities. NVML_OPERATIONAL_EVENT_SEVERITY_ALL disables severity filtering when used as a subscription threshold. Event data may contain newer severity values that are not named in this header; clients should handle unrecognized numeric values.

Values:

enumerator NVML_OPERATIONAL_EVENT_SEVERITY_ALL#

Matches all Operational Event severities.

enumerator NVML_OPERATIONAL_EVENT_SEVERITY_INFORMATIONAL#

Informational event.

enumerator NVML_OPERATIONAL_EVENT_SEVERITY_CORRECTED#

Corrected error event.

enumerator NVML_OPERATIONAL_EVENT_SEVERITY_RECOVERABLE#

Recoverable error event.

enumerator NVML_OPERATIONAL_EVENT_SEVERITY_FATAL#

Fatal error event.

Functions#

nvmlReturn_t nvmlDeviceGetSupportedEventTypes(
nvmlDevice_t device,
unsigned long long *eventTypes,
)#

Returns information about events supported on device.

For Fermi or newer fully supported devices.

Events are not supported on Windows. So this function returns an empty mask in eventTypes on Windows.

See also

Event Types

See also

nvmlDeviceRegisterEvents

Parameters:

  • device – The identifier of the target device

  • eventTypes – Reference in which to return bitmask of supported events

Returns:

nvmlReturn_t nvmlDeviceRegisterEvents(
nvmlDevice_t device,
unsigned long long eventTypes,
nvmlEventSet_t set,
)#

Starts recording of events on a specified devices and add the events to specified nvmlEventSet_t.

For Fermi or newer fully supported devices. ECC events are available only on ECC-enabled devices (see nvmlDeviceGetTotalEccErrors) Power capping events are available only on Power Management enabled devices (see nvmlDeviceGetPowerManagementMode)

For Linux only.

This call starts recording of events on specific device. All events that occurred before this call are not recorded. Checking if some event occurred can be done with nvmlEventSetWait_v2

If function reports NVML_ERROR_UNKNOWN, event set is in undefined state and should be freed. If function reports NVML_ERROR_NOT_SUPPORTED, event set can still be used. None of the requested eventTypes are registered in that case.

See also

Event Types

See also

nvmlDeviceGetSupportedEventTypes

See also

nvmlEventSetWait

See also

nvmlEventSetFree

Parameters:

  • device – The identifier of the target device

  • eventTypes – Bitmask of Event Types to record

  • set – Set to which add new event types

Returns:

nvmlReturn_t nvmlEventSetCreate(nvmlEventSet_t *set)#

Create an empty set of events.

Event set should be freed by nvmlEventSetFree

For Fermi or newer fully supported devices.

See also

nvmlEventSetFree

Parameters:

set – Reference in which to return the event handle

Returns:

nvmlReturn_t nvmlEventSetFree(nvmlEventSet_t set)#

Releases events in the set.

For Fermi or newer fully supported devices.

See also

nvmlDeviceRegisterEvents

Parameters:

set – Reference to events to be released

Returns:

nvmlReturn_t nvmlEventSetGetContextCount_v1(
nvmlEventSet_t set,
nvmlEventSetGetContextCount_v1_t *params,
)#

Gets the number of context records for the most recent event returned by nvmlEventSetWait_v3 on this event set.

This count is tied to the event set, not to a caller-owned copy of nvmlEventSetWait_v3_t. It is replaced by the next successful call to nvmlEventSetWait_v3 on the same event set.

For Turing or newer fully supported devices.

For Linux only.

See also

nvmlEventSetWait_v3

See also

nvmlEventSetGetContextInfo_v1

See also

nvmlEventSetGetContextData_v1

Parameters:

  • set – [in] Event set previously used with nvmlEventSetWait_v3

  • params – [out] Parameters in which to return the number of context records

Returns:

nvmlReturn_t nvmlEventSetGetContextData_v1(
nvmlEventSet_t set,
nvmlEventSetGetContextData_v1_t *params,
)#

Copies the raw payload for a context record from the most recent event returned by nvmlEventSetWait_v3.

Passing params->data as NULL performs a size query. In that case params->dataSize is set to the required payload size and the function returns NVML_ERROR_INSUFFICIENT_SIZE when the payload is non-empty. If the context payload is empty, params->dataSize is set to 0 and the function returns NVML_SUCCESS.

For Turing or newer fully supported devices.

For Linux only.

See also

nvmlEventSetWait_v3

See also

nvmlEventSetGetContextCount_v1

See also

nvmlEventSetGetContextInfo_v1

Parameters:

  • set – [in] Event set previously used with nvmlEventSetWait_v3

  • params – [inout] Context index, optional data buffer, and buffer size

Returns:

nvmlReturn_t nvmlEventSetGetContextInfo_v1(
nvmlEventSet_t set,
nvmlEventSetGetContextInfo_v1_t *params,
)#

Gets metadata for a context record from the most recent event returned by nvmlEventSetWait_v3.

The returned metadata identifies the NVML public interpretation, the source-defined context payload type, payload size, and payload format version. The raw payload for any context record can be copied with nvmlEventSetGetContextData_v1. When nvmlGpuOperationalEventContextType names a type-specific accessor, callers may use that accessor instead. Metadata is replaced by the next successful call to nvmlEventSetWait_v3 on the same event set.

For Turing or newer fully supported devices.

For Linux only.

See also

nvmlEventSetGetContextInfo_v1_t

See also

nvmlEventSetGetContextCount_v1

See also

nvmlEventSetGetContextData_v1

Parameters:

  • set – [in] Event set previously used with nvmlEventSetWait_v3

  • params – [inout] Context index and returned context metadata

Returns:

nvmlReturn_t nvmlEventSetGetGpuOperationalEventContextLegacyXid_v1(
nvmlEventSet_t set,
nvmlEventSetGetGpuOperationalEventContextLegacyXid_v1_t *params,
)#

Gets decoded GPU legacy-Xid context data for a context record from the most recent event returned by nvmlEventSetWait_v3.

This helper succeeds only for context records whose nvmlGpuOperationalEventContextType is NVML_GPU_OPERATIONAL_EVENT_CONTEXT_TYPE_LEGACY_XID. Other context records remain available through nvmlEventSetGetContextData_v1.

For Turing or newer fully supported devices.

For Linux only.

See also

nvmlEventSetGetGpuOperationalEventContextLegacyXid_v1_t

See also

nvmlEventSetGetContextInfo_v1

See also

nvmlEventSetGetContextData_v1

Parameters:

  • set – [in] Event set previously used with nvmlEventSetWait_v3

  • params – [inout] Context index and returned legacy-Xid data

Returns:

nvmlReturn_t nvmlEventSetRegisterGpuOperationalEvents_v1(
nvmlEventSet_t eventSet,
const nvmlGpuOperationalEventConfig_v1_t *config,
)#

Adds a GPU Operational Event subscription to an event set.

This API is separate from nvmlDeviceRegisterEvents. Calling this API opts the event set into the structured GPU Operational Event format for the target GPU UUID. Subscriptions are identified by config; registering the same subscription more than once is treated as success.

nvmlDeviceRegisterEvents and nvmlEventSetRegisterGpuOperationalEvents_v1 may both be used on the same event set. In that mixed-subscription model, NVML event-bit subscriptions continue to deliver event bits such as nvmlEventTypeXidCriticalError, while GPU Operational Event subscriptions deliver NVML_EVENT_DATA_TYPE_GPU_OPERATIONAL_EVENT records through nvmlEventSetWait_v3 with eventType set to nvmlEventTypeNone. The same underlying incident may generate both an NVML event-bit notification and a structured notification.

This API supports GPU UUID subscriptions.

For Turing or newer fully supported devices.

For Linux only.

See also

nvmlGpuOperationalEventConfig_v1_t

See also

nvmlEventSetWait_v3

See also

nvmlEventSetFree

Parameters:

  • eventSet – [in] Event set created by nvmlEventSetCreate

  • config – [in] GPU Operational Event subscription configuration

Returns:

nvmlReturn_t nvmlEventSetWait_v2(
nvmlEventSet_t set,
nvmlEventData_t *data,
unsigned int timeoutms,
)#

Waits on events and delivers events.

For Fermi or newer fully supported devices.

If some events are ready to be delivered at the time of the call, function returns immediately. If there are no events ready to be delivered, function sleeps till event arrives but not longer than specified timeout. This function in certain conditions can return before specified timeout passes (e.g. when interrupt arrives)

On Windows, in case of Xid error, the function returns the most recent Xid error type seen by the system. If there are multiple Xid errors generated before nvmlEventSetWait is invoked then the last seen Xid error type is returned for all Xid error events.

On Linux, every Xid error event would return the associated event data and other information if applicable.

In MIG mode, if device handle is provided, the API reports all the events for the available instances, only if the caller has appropriate privileges. In absence of required privileges, only the events which affect all the instances (i.e. whole device) are reported.

This API does not currently support per-instance event reporting using MIG device handles.

See also

Event Types

See also

nvmlDeviceRegisterEvents

Parameters:

  • set – Reference to set of events to wait on

  • data – Reference in which to return event data

  • timeoutms – Maximum amount of wait time in milliseconds for registered event

Returns:

nvmlReturn_t nvmlEventSetWait_v3(
nvmlEventSet_t set,
nvmlEventSetWait_v3_t *params,
)#

Waits on an event set and returns the next event in the extended event format.

This API is the unified wait surface for NVML event-bit subscriptions registered with nvmlDeviceRegisterEvents and structured GPU Operational Event subscriptions registered with nvmlEventSetRegisterGpuOperationalEvents_v1.

The returned format is distinguished by dataType in params. If dataType is NVML_EVENT_DATA_TYPE_NVML_EVENT, the event came from the nvmlDeviceRegisterEvents path, eventType is an NVML event bit such as nvmlEventTypeXidCriticalError, and the existing fields preserve their historical semantics. If dataType is NVML_EVENT_DATA_TYPE_GPU_OPERATIONAL_EVENT, the event came from the structured format, eventType is nvmlEventTypeNone, and the structured metadata fields are populated.

When an event set contains only NVML event-bit subscriptions, this API normalizes those events into nvmlEventSetWait_v3_t. When an event set contains both NVML event-bit and structured subscriptions, each successful call returns the next available event from either path. Clients should branch on dataType to determine which format was returned. An event set is not required to have structured GPU Operational Event subscriptions to be used with this API.

Context records for the returned event, if any, are made available through nvmlEventSetGetContextCount_v1, nvmlEventSetGetContextInfo_v1, and nvmlEventSetGetContextData_v1. Context records remain associated with the event set until the next successful call to nvmlEventSetWait_v3 on the same event set or until the event set is freed.

For Turing or newer fully supported devices.

For Linux only.

See also

nvmlEventSetWait_v3_t

See also

nvmlDeviceRegisterEvents

See also

nvmlEventSetRegisterGpuOperationalEvents_v1

See also

nvmlEventSetGetContextCount_v1

Parameters:

  • set – [in] Reference to set of events to wait on

  • params – [inout] Wait parameters and returned event data

Returns:

nvmlReturn_t nvmlSystemEventSetCreate(
nvmlSystemEventSetCreateRequest_t *request,
)#

Create an empty set of system events.

Event set should be freed by nvmlSystemEventSetFree

For Fermi or newer fully supported devices.

See also

nvmlSystemEventSetFree

Parameters:

request – Reference to nvmlSystemEventSetCreateRequest_t

Returns:

nvmlReturn_t nvmlSystemEventSetFree(
nvmlSystemEventSetFreeRequest_t *request,
)#

Releases system event set.

For Fermi or newer fully supported devices.

See also

nvmlDeviceRegisterEvents

Parameters:

request – Reference to nvmlSystemEventSetFreeRequest_t

Returns:

nvmlReturn_t nvmlSystemEventSetWait(
nvmlSystemEventSetWaitRequest_t *request,
)#

Waits on system events and delivers events.

For Fermi or newer fully supported devices.

If some events are ready to be delivered at the time of the call, function returns immediately. If there are no events ready to be delivered, function sleeps till event arrives but not longer than specified timeout. This function in certain conditions can return before specified timeout passes (e.g. when interrupt arrives)

if the return request->numEvent equals to request->dataSize, there might be outstanding event, it is recommended to call nvmlSystemEventSetWait again to query all the events.

See also

nvmlSystemEventType

See also

nvmlSystemRegisterEvents

Parameters:

request – Reference in which to nvmlSystemEventSetWaitRequest_t

Returns:

nvmlReturn_t nvmlSystemRegisterEvents(
nvmlSystemRegisterEventRequest_t *request,
)#

Starts recording of events on system and add the events to specified nvmlSystemEventSet_t.

For Linux only.

This call starts recording of events on specific device. All events that occurred before this call are not recorded. Checking if some event occurred can be done with nvmlSystemEventSetWait

If function reports NVML_ERROR_UNKNOWN, event set is in undefined state and should be freed. If function reports NVML_ERROR_NOT_SUPPORTED, event set can still be used. None of the requested eventTypes are registered in that case.

See also

nvmlSystemEventType

See also

nvmlSystemEventSetWait

See also

nvmlEventSetFree

Parameters:

request – Reference to the struct nvmlSystemRegisterEventRequest_t

Returns:

Typedefs#

typedef struct nvmlEventSet_st *nvmlEventSet_t#

Handle to an event set.

typedef nvmlSystemEventSetCreateRequest_v1_t nvmlSystemEventSetCreateRequest_t#
typedef nvmlSystemEventSetFreeRequest_v1_t nvmlSystemEventSetFreeRequest_t#
typedef nvmlSystemEventSetWaitRequest_v1_t nvmlSystemEventSetWaitRequest_t#
typedef struct nvmlSystemEventSet_st *nvmlSystemEventSet_t#

System Event Set.

typedef nvmlSystemRegisterEventRequest_v1_t nvmlSystemRegisterEventRequest_t#
On this page