CLGETKERNELWORKGROUP(3clc)

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

💖 NAME 💖

clGetKernelWorkGroupInfo — bestie, this one hands you the tea about a kernel object that's specific to a device. Like, the deets that only make sense for one particular piece of hardware. From the OpenCL Manual, section 3clc. iykyk 💅

✨ SYNOPSIS ✨

cl_int clGetKernelWorkGroupInfo(cl_kernel kernel, cl_device_id device,
                                cl_kernel_work_group_info param_name,
                                size_t param_value_size,
                                void *param_value,
                                size_t *param_value_size_ret);

🎀 PARAMETERS 🎀

okay so here's who's who in this function's little friend group 🫶

  • kernel — this is the kernel object you're interrogating. The one being queried. 🌸
  • device — this points at one specific device out of the list of devices associated with kernel. And where does that list come from? It's the list of devices in the OpenCL context that's associated with kernel. ✨
    • 💡 little shortcut: if the list of devices associated with kernel is just a single device, then device can be a NULL value. no cap, you can just skip it.
  • param_name — this is you telling it what you wanna know. The full list of supported param_name types, plus what info each one drops into param_value when you call clGetKernelWorkGroupInfo, lives in the table below. 👑
  • param_value — a pointer to memory where the appropriate result you're querying gets returned. And if param_value is NULL? It's ignored. literally just vibes, it does nothing. 🙈

more coming, bestie, don't go anywhere 💖

✨ param_value_size ✨

okay so bestie, param_value_size is literally just the size in bytes of the memory that param_value points at 💅 and this size must be ≥ the size of the return type — which return type? the one for your chosen cl_kernel_work_group_info value, bestie, as shown in the table below 👇

not me making a whole table into a bullet list because tables are not the vibe here, but every single detail is still present, no cap 🫶
  • CL_KERNEL_GLOBAL_WORK_SIZE — return type is size_t[3] — what you get back in param_value: this provides a mechanism for the application to query the maximum global size that can be used to execute a kernel (i.e. the global_work_size argument to clEnqueueNDRangeKernel(3clc)) on a custom device given by device or a built-in kernel on an OpenCL device given by device ✨ If device is not a custom device or kernel is not a built-in kernel, clGetKernelArgInfo(3clc) returns the error CL_INVALID_VALUE 💀 (yes, it says clGetKernelArgInfo, not clGetKernelWorkGroupInfo — that's literally what the original says, so I'm keeping it exactly, periodt).
  • CL_KERNEL_WORK_GROUP_SIZE — return type is size_t — what you get back in param_value: this provides a mechanism for the application to query the maximum work-group size that can be used to execute a kernel on a specific device given by device 👑 The OpenCL implementation uses the resource requirements of the kernel (register usage etc.) to determine what this work-group size should be, slay 💅
  • CL_KERNEL_COMPILE_WORK_GROUP_SIZE — return type is size_t[3] — what you get back in param_value: returns the work-group size specified by the __attribute__((reqd_work_group_size(X, Y, Z))) qualifier 🌸 See functionQualifiers(3clc). If the work-group size is not specified using the above attribute qualifier, (0, 0, 0) is returned. lowkey iconic that it tells you zero zero zero 🙈
  • CL_KERNEL_LOCAL_MEM_SIZE — return type is cl_ulong — what you get back in param_value: returns the amount of local memory in bytes being used by a kernel 💖 This includes local memory that may be needed by an implementation to execute the kernel, variables declared inside the kernel with the local(3clc) address qualifier and local memory to be allocated for arguments to the kernel declared as pointers with the local(3clc) address qualifier and whose size is specified with clSetKernelArg(3clc).

If the local memory size, for any pointer argument to the kernel declared with the local(3clc) address qualifier, is not specified, its size is assumed to be 0. noted bestie 📝

  • CL_KERNEL_PREFERRED_WORK_GROUP_SIZE_MULTIPLE — return type is size_t — what you get back in param_value: returns the preferred multiple of workgroup size for launch ✨ This is a performance hint. Specifying a workgroup size that is not a multiple of the value returned by this query as the value of the local work size argument to clEnqueueNDRangeKernel(3clc) will not fail to enqueue the kernel for execution unless the work-group size specified is larger than the device maximum. so like, it's giving suggestion energy, not requirement energy, iykyk 💅
  • CL_KERNEL_PRIVATE_MEM_SIZE — return type is cl_ulong — what you get back in param_value: returns the minimum amount of private memory, in bytes, used by each workitem in the kernel 🌈 This value may include any private memory needed by an implementation to execute the kernel, including that used by the language built-ins and variable declared inside the kernel with the private(3clc) qualifier. (yes, "variable" not "variables" — original said it that way, and I'm not about to change it, no cap 🫶)

✨ param_value_size_ret ✨

Returns the actual size in bytes of data copied to param_value. If param_value_size_ret is NULL, it is ignored. literally just ignored, bestie, no drama 💀💖

💀 ERRORS 💀

okay bestie, here's the tea on what this function hands back to you. It returns CL_SUCCESS when everything goes off without a hitch ✨ — the function executed successfully, we love to see it. Otherwise? She's returning one of these bad boys instead:

  • CL_INVALID_DEVICE — this pops up if device isn't in the list of devices associated with kernel, OR if device is NULL but there's more than one device chilling with kernel. like, pick a lane, we can't read minds 🙈
  • CL_INVALID_VALUE — if param_name isn't valid, or if the size in bytes you gave as param_value_size is < the size of the return type (as described in that table above, you remember her) AND param_value isn't NULL. so messy 💅
  • CL_INVALID_VALUE — yes she shows up TWICE, iconic behaviour actually. This time it's if param_name is CL_KERNEL_GLOBAL_WORK_SIZE and device is not a custom device, or kernel is not a built-in kernel. rules are rules 🎀
  • CL_INVALID_KERNEL — if kernel is not a valid kernel object. babe. that's not a kernel 💀
  • CL_OUT_OF_RESOURCES — there was a failure to allocate resources required by the OpenCL implementation on the device. she's going through it 😭
  • CL_OUT_OF_HOST_MEMORY — there was a failure to allocate resources required by the OpenCL implementation on the host. the host is also going through it 😭😭

📜 SPECIFICATION 📜

OpenCL Specification[1] — that's the source of truth, the blueprint, the main character document 👑

👀 SEE ALSO 👀

go read these next, they're all connected, it's giving cinematic universe fr fr 🦋

🫶 AUTHORS 🫶

The Khronos Group — thank you for your service, kings and queens 👑

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.

ngl this is the legal stuff so imma keep it exactly as-is, no edits, no vibes, just facts 💖

📝 NOTES 📝

  1. OpenCL Specification — page 164, section 5.7.3 - Kernel Object Queries 🎯

and that's a wrap on CLGETKERNELWORKGROUP(3clc) bestie!! 🌸 This page came to you from The Khronos Group, dated 01/14/2021 — go forth and query those kernel work-group things with confidence, you absolute legend 💅✨ slay, periodt, no cap 🦋💖

📦 where this page comes from