6.4. CUPTI Clock Control API#

Functions and types to lock GPU clock frequencies for deterministic profiling.

6.4.1. Enumerations#

CUpti_ClockControl_Mode

Clock control modes.

CUpti_ClockControl_Status

Device clock-control status.

6.4.2. Functions#

CUptiResult cuptiClockControlGetStatus(CUcontext ctx, CUpti_ClockControl_Status *pStatus)

Query the device-global GPU clock-control status.

CUptiResult cuptiClockControlLock(CUcontext ctx, CUpti_ClockControl_Mode mode)

Lock GPU clocks to the requested frequency.

CUptiResult cuptiClockControlUnlock(void)

Unlock GPU clocks previously locked via cuptiClockControlLock .

6.4.3. Enumerations#

enum CUpti_ClockControl_Mode#

Clock control modes.

Determines the frequency to which GPU clocks are pinned for a profiling session. Locking clocks produces reproducible metric values across kernel launches and replay passes.

Clock locking is device-global — affects all contexts on the GPU. It is not supported on platforms where the underlying driver clock-control operation is unavailable, such as MIG-partitioned devices.

To skip clock locking entirely, simply do not call cuptiClockControlLock. Numeric values start at 1 so that an uninitialized / zero-valued CUpti_ClockControl_Mode is rejected with CUPTI_ERROR_INVALID_PARAMETER rather than silently locking clocks.

Since

CUDA 13.4

Values:

enumerator CUPTI_CLOCK_CONTROL_MODE_BASE#

Lock GPU clocks to the base (rated TDP) frequency.

Exact clock domains that are pinned may depend on the driver and board configuration.

enumerator CUPTI_CLOCK_CONTROL_MODE_BOOST#

Lock GPU clocks to the boost frequency.

Returns an error if boost locking is not supported by the driver or platform — no automatic fallback to base. Clients that want a fallback can retry with CUPTI_CLOCK_CONTROL_MODE_BASE on error.

enumerator CUPTI_CLOCK_CONTROL_MODE_FORCE_INT#
enum CUpti_ClockControl_Status#

Device clock-control status.

This status describes the device-global clock-control state reported by the driver for the GPU associated with a CUDA context. It does not describe CUPTI ownership. For example, CUPTI_CLOCK_CONTROL_STATUS_LOCKED can be returned for a lock created by CUPTI, by another profiling tool, or by an administrator through an external mechanism such as nvidia-smi.

Tools can query this state before calling cuptiClockControlLock to make an informed policy decision. A common use case is MIG: CUPTI cannot create a new clock lock on MIG-partitioned devices, but a tool may still choose to run if this API reports that clocks are already externally locked.

A status of CUPTI_CLOCK_CONTROL_STATUS_UNLOCKED only means the driver currently reports no explicit clock lock. It does not guarantee fixed, deterministic, or non-boosting clocks.

Since

CUDA 13.4

Values:

enumerator CUPTI_CLOCK_CONTROL_STATUS_UNLOCKED#

The driver reports no explicit clock lock for this device.

enumerator CUPTI_CLOCK_CONTROL_STATUS_LOCKED#

The driver reports that clocks are locked to a fixed level.

This may be a CUPTI-owned lock or an externally-created lock.

enumerator CUPTI_CLOCK_CONTROL_STATUS_LOCKED_TO_FLOOR#

The driver reports that clocks are locked to a floor/minimum level.

enumerator CUPTI_CLOCK_CONTROL_STATUS_BOOST_ENABLED#

The driver reports that boost behavior is enabled by clock control.

enumerator CUPTI_CLOCK_CONTROL_STATUS_BOOST_DISABLED#

The driver reports that boost behavior is disabled by clock control.

enumerator CUPTI_CLOCK_CONTROL_STATUS_FORCE_INT#

6.4.4. Functions#

CUptiResult cuptiClockControlGetStatus(
CUcontext ctx,
CUpti_ClockControl_Status *pStatus,
)#

Query the device-global GPU clock-control status.

Queries the driver for the current clock-control state of the GPU associated with ctx and stores the result in pStatus. The returned status is device-global: it applies to the GPU, not just to ctx, and it can reflect locks created outside CUPTI.

This API does not create, take ownership of, release, or otherwise modify any clock lock. It only reports the current driver-visible state. In particular, receiving CUPTI_CLOCK_CONTROL_STATUS_LOCKED does not imply that a later cuptiClockControlUnlock call will release the lock; unlock only releases locks that were created by cuptiClockControlLock in this process.

If the query fails, pStatus is not modified. Failures can happen on platforms where clock-control state is unavailable or access is restricted.

Since

CUDA 13.4

Parameters:

  • ctx – A valid CUDA context on the device whose clock status should be queried.

  • pStatus – Returns the device clock-control status.

Return values:

  • CUPTI_SUCCESS –

  • CUPTI_ERROR_INVALID_PARAMETER – ctx is NULL or pStatus is NULL

  • CUPTI_ERROR_UNKNOWN – An unspecified error occurred, preventing the query.

CUptiResult cuptiClockControlLock(
CUcontext ctx,
CUpti_ClockControl_Mode mode,
)#

Lock GPU clocks to the requested frequency.

Lock GPU clocks to a fixed level (base/rated-TDP or boost) so profiling sessions collect deterministic metrics. Clocks remain locked until cuptiClockControlUnlock is called. If the process exits beforehand, clocks are not automatically unlocked.

Intended to be called BEFORE the profiling session is enabled (e.g., before cuptiRangeProfilerEnable), and matched with a call to cuptiClockControlUnlock AFTER the session is disabled.

Only one lock can be active at a time per process; calling this API again while a lock is active is a no-op that returns CUPTI_SUCCESS. Before attempting a new lock, CUPTI queries the device status. If clocks are already locked before this API is called, CUPTI leaves the existing lock untouched and returns CUPTI_SUCCESS without taking ownership of that lock. This external-lock check is performed before CUPTI rejects platforms where it cannot create a new lock, such as MIG-partitioned devices.

To skip clock locking entirely, do not call this API — passing an uninitialized or zero-valued mode returns CUPTI_ERROR_INVALID_PARAMETER.

Since

CUDA 13.4

Parameters:

  • ctx – A valid CUDA context on the device whose clocks should be locked.

  • mode – Clock control mode (see CUpti_ClockControl_Mode).

Return values:

  • CUPTI_SUCCESS –

  • CUPTI_ERROR_INVALID_PARAMETER – ctx is NULL or mode is not a valid enum value

  • CUPTI_ERROR_NOT_SUPPORTED – Device does not support clock control

  • CUPTI_ERROR_INSUFFICIENT_PRIVILEGES – BOOST mode failed — typically requires elevated privileges

  • CUPTI_ERROR_UNKNOWN – An unspecified error occurred, preventing the lock.

CUptiResult cuptiClockControlUnlock(void)#

Unlock GPU clocks previously locked via cuptiClockControlLock.

Releases any clock lock created by CUPTI in this process. No-op if no lock is currently held. Safe to call even without a matching lock (e.g., as a defensive cleanup). This API does not release a pre-existing external lock that was observed by cuptiClockControlLock.

Intended to be called AFTER the profiling session is disabled (e.g., after cuptiRangeProfilerDisable).

Since

CUDA 13.4

Return values:

  • CUPTI_SUCCESS –

  • CUPTI_ERROR_UNKNOWN – An unspecified error occurred, preventing the unlock.