CLGETKERNELARGINFO(3clc)

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

✨ CLGETKERNELARGINFO ✨

okay so bestie, welcome to the clGetKernelArgInfo page of the OpenCL Manual 💅 this is a <3clc> girlie, section 3, and she is so ready to spill the tea about your kernel arguments. no cap.

🌸 NAME 🌸

clGetKernelArgInfo — Returns information about the arguments of a kernel.

like, literally that's the whole job. you hand her a kernel, she tells you about its args. iconic behaviour tbh 🎀

🦋 SYNOPSIS 🦋

cl_int clGetKernelArgInfo(cl_kernel kernel, cl_uint arg_indx,
                          cl_kernel_arg_info param_name,
                          size_t param_value_size, void *param_value,
                          size_t *param_value_size_ret);

she returns a cl_int, takes a cl_kernel called kernel, a cl_uint called arg_indx, a cl_kernel_arg_info called param_name, a size_t called param_value_size, a void * called param_value, and a size_t * called param_value_size_ret. six whole things. she's a busy girl 💖

more parts incoming, bestie — don't go anywhere 🫶

💖 PARAMETERS 💖

okay bestie, here's everybody in the cast, one by one 🌸

  • kernel — the kernel object we're poking at. the one getting queried, periodt.
  • arg_indx — the argument index, iykyk. args to the kernel get referred to by indices that start at 0 for the leftmost argument and run all the way to n - 1, where n is the total number of arguments that kernel declared. so yeah, zero-indexed like everything else in this cursed lil world 😌
  • param_name — which piece of argument info you wanna query. the whole list of supported param_name types, plus what clGetKernelArgInfo hands back in param_value, is laid out right below 👇
  • param_value — a pointer to the memory where the result you asked for gets dropped. if param_value is NULL, it's just ignored. no drama. 🙈
  • param_value_size — how big (in bytes) the memory that param_value points to is. this size must be > the size of the return type as described in the table below. lowkey non-negotiable bestie 💅
  • param_value_size_ret — returns the actual size in bytes of the data that got copied into param_value. if param_value_size_ret is NULL, it gets ignored too. equal opportunity ignoring fr fr.

🦋 the cl_kernel_arg_info rundown 🦋

CL_KERNEL_ARG_ADDRESS_QUALIFIER

return type: cl_kernel_arg_address_qualifier 💜

this one gives you back the address qualifier that was specified for the argument at arg_indx. and it can be any one of these:

  • CL_KERNEL_ARG_ADDRESS_GLOBAL
  • CL_KERNEL_ARG_ADDRESS_LOCAL
  • CL_KERNEL_ARG_ADDRESS_CONSTANT
  • CL_KERNEL_ARG_ADDRESS_PRIVATE
and if no address qualifier was specified at all? then the default address qualifier gets returned, which is CL_KERNEL_ARG_ADDRESS_PRIVATE. so you're never left hanging, queen 👑

CL_KERNEL_ARG_ACCESS_QUALIFIER

return type: cl_kernel_arg_access_qualifier ✨

returns the access qualifier specified for the argument given by arg_indx. can be one of:

  • CL_KERNEL_ARG_ACCESS_READ_ONLY
  • CL_KERNEL_ARG_ACCESS_WRITE_ONLY
  • CL_KERNEL_ARG_ACCESS_READ_WRITE
  • CL_KERNEL_ARG_ACCESS_NONE

if the argument is not an image type, you get CL_KERNEL_ARG_ACCESS_NONE back. and if it is an image type, then you get the access qualifier that was specified, or the default access qualifier. either way, something comes home 🏠

CL_KERNEL_ARG_TYPE_NAME

return type: char[] 🌈

returns the type name that was specified for the argument at arg_indx. the type name you get back will be the argument type name exactly as it was declared, with any whitespace removed. if the argument type name is an unsigned scalar type (i.e. unsigned char, unsigned short, unsigned int, unsigned long), then uchar, ushort, uint and ulong will be returned instead. and the argument type name returned does not include any type qualifiers. so it's giving ✨clean✨

CL_KERNEL_ARG_TYPE_QUALIFIER

return type: cl_kernel_arg_type_qualifier 💅

returns the type qualifier specified for the argument given by arg_indx. the returned value can be:

  • CL_KERNEL_ARG_TYPE_CONST
  • CL_KERNEL_ARG_TYPE_RESTRICT
  • CL_KERNEL_ARG_TYPE_VOLATILE
  • a combination of the above enums
  • or CL_KERNEL_ARG_TYPE_NONE
NOTE: CL_KERNEL_ARG_TYPE_VOLATILE gets returned if the argument is a pointer and that pointer is declared with the volatile qualifier. both conditions, bestie. don't forget the second one 🫶

CL_KERNEL_ARG_NAME

return type: char[] 🎀

returns the name that was specified for the argument given by arg_indx. that's it, that's the whole thing, and honestly? iconic. 👑

🎀 NOTES 🎀

okay bestie, listen up because this is the tea ☕ and it matters so much:

kernel argument information is only available if the program object associated with kernel is created with clCreateProgramWithSource(3clc) AND the program executable is built with the -cl-kernel-arg-info option specified in the options argument to clBuildProgram(3clc) or clCompileProgram(3clc).

so basically: no source, no flag, no arg info. it's giving "you didn't do the homework so you don't get the notes" 💀 do both or this whole query is a ✨nothing burger✨.

💅 ERRORS 💅

Returns CL_SUCCESS if the function is executed successfully, which is the slay outcome obviously 🫶. Otherwise, it returns one of the following errors — and bestie, it will pick one:

  • CL_INVALID_ARG_INDEX — if arg_indx is not a valid argument index. (that index? not real. not a vibe. 🙈)
  • CL_INVALID_VALUE — if param_name is not valid, or if size in bytes specified by param_value_size is < size of return type as described in the table above and param_value is not NULL. (short buffer + not-NULL pointer = caught lacking 😭)
  • CL_KERNEL_ARG_INFO_NOT_AVAILABLE — if the argument information is not available for kernel. (the info is simply not there. it's not hiding, it's absent.)
  • CL_INVALID_KERNEL — if kernel is not a valid kernel object. (who is she? we don't know her 💀)

👑 SPECIFICATION 👑

OpenCL Specification<sup>[1]</sup>

🌸 SEE ALSO 🌸

clCreateKernel(3clc), clGetKernelInfo(3clc), clCreateKernelsInProgram(3clc), clRetainKernel(3clc), clReleaseKernel(3clc), clSetKernelArg(3clc), clGetKernelWorkGroupInfo(3clc)

the whole friend group fr fr 🫶 go read them, they're all iconic.

✨ AUTHORS ✨

The Khronos Group

Copyright © 2007-2011 The Khronos Group Inc.

and here's the legal bit, verbatim, because you never paraphrase a license (that's the one thing that would actually get you in trouble):

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 🍓

(sí, there are two NOTES sections. the manpage is quirky like that, we don't question it 💜)

  1. OpenCL Specification — page 166, section 5.7.3 - Kernel Object Queries (updated for 1.2 rev 14)

and that's a wrap bestie!! 🎀✌️ this page was brought to you by The Khronos Group, dated 01/14/2021, filed under CLGETKERNELARGINFO(3clc) — go forth and query those kernel args, you absolute main character 🌈👑💖

📦 where this page comes from