CLGETEVENTPROFILINGI(3clc)

📦
version 1.0~svn33624 · 3 versions
, in ubuntu jammy, ubuntu noble

💖 CLGETEVENTPROFILINGI(3clc) — the OpenCL Manual, bestie edition 💖

okay so we're in the OpenCL Manual and today's main character is clGetEventProfilingInfo(3clc). she's the one who tells you how long your commands actually took on the device. timestamps, girl. we love a receipts moment. 🎀

✨ NAME ✨

clGetEventProfilingInfo — returns profiling information for the command associated with event if profiling is enabled.

lowkey the whole plot in one line. if profiling isn't enabled, she's not talking to you. 💅

cl_int clGetEventProfilingInfo(cl_event event,
                               cl_profiling_info param_name,
                               size_t param_value_size,
                               void *param_value,
                               size_t *param_value_size_ret);

🌸 PARAMETERS 🌸

  • event — the event object. the one we're snooping on. 👀
  • param_name — which piece of profiling data you wanna query. the full list of supported param_name types, and what comes back in param_value, is down in the parameter queries list below. no skimming, bestie.
  • param_value_size — the size, in bytes, of the memory that param_value points at. this size must be ≥ the size of the return type listed below. fr fr, respect the type size.
  • param_value — a pointer to the memory where the queried result gets returned. if param_value is NULL, it's just ignored. she said no pressure.
  • param_value_size_ret — returns the actual size, in bytes, of the data copied to param_value. if param_value_size_ret is NULL, it's ignored too. iconic, both of them.

here's the table of clGetEventProfilingInfo parameter queries, but as a list because we're terminal girls 💜

🦋 CL_PROFILING_COMMAND_QUEUED

  • Return type: cl_ulong
  • Info returned in param_value: a 64-bit value describing the current device time counter in nanoseconds when the command identified by event is enqueued in a command-queue by the host.

🦋 CL_PROFILING_COMMAND_SUBMIT

  • Return type: cl_ulong
  • Info returned in param_value: a 64-bit value describing the current device time counter in nanoseconds when the command identified by event that has been enqueued is submitted by the host to the device associated with the command-queue.

🦋 CL_PROFILING_COMMAND_START

  • Return type: cl_ulong
  • Info returned in param_value: a 64-bit value describing the current device time counter in nanoseconds when the command identified by event starts execution on the device.

🦋 CL_PROFILING_COMMAND_END

  • Return type: cl_ulong
  • Info returned in param_value: a 64-bit value describing the current device time counter in nanoseconds when the command identified by event has finished execution on the device.

✨ NOTES ✨

the unsigned 64-bit values you get back can be used to measure the time in nano-seconds consumed by OpenCL commands. it's giving stopwatch but make it 64-bit. ⏱️

OpenCL devices are required to correctly track time across changes in device frequency and power states. not optional, not vibes-based. and CL_DEVICE_PROFILING_TIMER_RESOLUTION specifies the resolution of the timer, i.e. the number of nanoseconds that elapse before the timer is incremented.

event objects can be used to capture profiling information that measures the execution time of a command. profiling of OpenCL commands can be enabled either by using a command-queue created with the CL_QUEUE_PROFILING_ENABLE flag set in the properties argument to clCreateCommandQueue(3clc). so like, go turn it on first. 🙈

💀 ERRORS 💀

returns CL_SUCCESS if the function executes successfully and the profiling information has been recorded. otherwise, she returns one of the following, and bestie she is not subtle about it:

  • CL_PROFILING_INFO_NOT_AVAILABLE — if the CL_QUEUE_PROFILING_ENABLE flag is not set for the command-queue, if the execution status of the command identified by event is not CL_COMPLETE, or if event is a user event object.
  • CL_INVALID_VALUE — if param_name is not valid, or if the size in bytes specified by param_value_size is < the size of the return type described in the table above and param_value is not NULL.
  • CL_INVALID_EVENT — if event is not a valid event object.
  • CL_OUT_OF_RESOURCES — if there is a failure to allocate resources required by the OpenCL implementation on the device.
  • CL_OUT_OF_HOST_MEMORY — if there is a failure to allocate resources required by the OpenCL implementation on the host.
heads up: CL_PROFILING_INFO_NOT_AVAILABLE is the one that shows up when you forgot to enable profiling. that's a you problem, not a her problem. 😭

🌈 SPECIFICATION 🌈

OpenCL Specification[1]

🫶 SEE ALSO 🫶

clCreateCommandQueue(3clc)

👑 AUTHORS 👑

The Khronos Group

Copyright © 2007-2011 The Khronos Group Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and/or associated documentation files (the "Materials"), to deal in the Materials without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Materials, and to permit persons to whom the Materials are furnished to do so, subject to the condition that this copyright notice and permission notice shall be included in all copies or substantial portions of the Materials.

📝 NOTES 📝

  1. OpenCL Specification — page 190, section 5.12 - Profiling Operations on Memory Objects and Kernels

and that's the whole page, bestie. brought to you by The Khronos Group, dated 01/14/2021, filed under CLGETEVENTPROFILINGI(3clc) ✨ go measure something. slay. 💖

📦 where this page comes from