CUPTI

cfg = CUPTI.ActivityConfig(activity_kinds)

CUPTI.enable!(cfg) do
    # do stuff
end

CUPTI.process(cfg) do ctx, stream_id, record
    # inspect record
end

High-level interface to the CUPTI activity API.

cfg = CUPTI.CallbackConfig(callback_kinds) do domain, id, data
    # inspect data
end

CUPTI.enable!(cfg) do
    # do stuff
end

CUPTI.PCSamples

PC samples collected by CUPTI.pc_sample:

• reasons: the name of every stall reason, by CUPTI's index;
• pcs: for every sampled PC, keyed by the CRC of its cubin (as computed by CUPTI.cubin_crc), its function's name and the offset of the PC in that function, the number of samples per stall reason index;
• total: the number of samples, including dropped ones and samples in kernels that CUPTI doesn't report (e.g. in the driver);
• dropped: the number of samples that were lost because CUPTI's buffers were full.

CUPTI.ProfilerHost(f, ctx::CuContext)

Create a profiler host object for the device of ctx, which configures and evaluates range profiler metrics, and pass it to f.

can_profile() -> Bool

Whether CUDA.jl should attempt to use CUPTI in the current process.

On Tegra, CUDA 10 through 12 require root, while CUDA 13 and later require read/write access to a profiling device node. This check is intentionally conservative because some CUPTI versions crash in cuptiSubscribe when that access is missing. On other systems, CUPTI reports permission errors normally, so this function returns true and lets CUPTI handle them.

CUPTI.check_pc_sampling_support(dev::CuDevice)

Throw an error explaining why dev doesn't support PC sampling, if it doesn't.

CUPTI.check_profiler_support(dev::CuDevice; api=CUPTI_PROFILER_RANGE_PROFILING,
                             feature="hardware metrics")

Throw an error explaining why dev doesn't support the profiling api, if it doesn't. feature names what the API is used for in the error message.

CUPTI.chip_name(dev::CuDevice) -> String

The name of the chip of dev, as used to configure the profiler (e.g. "GB203").

CUPTI.config_image(host::ProfilerHost, metrics::Vector{String}) -> Vector{UInt8}

Build the configuration image that makes the range profiler collect metrics.

CUPTI.cubin_crc(cubin::Vector) -> UInt64

The CRC that CUPTI uses to identify cubin in PC sampling records.

CUPTI.has_pc_sampling() -> Bool

Whether the loaded CUPTI library supports PC sampling as CUDA.jl uses it (CUDA 13 or later).

CUPTI.has_range_profiler() -> Bool

Whether the loaded CUPTI library provides the range profiler (CUDA 12.6 Update 2 and later). The API version doesn't change between update releases, so look for the symbol.

CUPTI.metric_properties(host::ProfilerHost, metric::String)

Look up the description and unit of metric (e.g. dram__bytes or dram__bytes.sum), or throw a CUPTIError with code CUPTI_ERROR_INVALID_METRIC_NAME if it doesn't exist.

CUPTI.num_passes(config::Vector{UInt8}) -> Int

The number of times each kernel needs to be replayed to collect the metrics in config.

CUPTI.pc_sample(f; ctx=context(), period=14) -> CUPTI.PCSamples

Sample the PCs of warps executing kernels in ctx while executing f(), once every 2^period cycles on each SM. The caller should synchronize the context before and after f, as samples are only collected while sampling is active.

CUPTI.profiler_params(T, lastfield; fields...)

Construct a zero-initialized profiler API parameter struct of type T, setting the given fields. structSize covers the fields up to and including lastfield, which should be the last field the oldest supported CUPTI knows about: CUPTI appends fields to these structs, and rejects sizes it doesn't recognize.

CUPTI.range_profile(f, metrics::Vector{String}; ctx=context(), max_ranges=1024)

Collect metrics for every kernel launched in ctx while executing f(), and return a named tuple with a ranges × metrics matrix of values and the number of passes each kernel was replayed. Ranges are numbered in the order the kernels executed, which is serialized by CUPTI; at most max_ranges kernels are profiled.

@enable! cfg expr

Macro version of enable!(f, cfg) that avoids creating a closure, similar to @lock vs lock(f, l).