CLGETPROGRAMINFO(3clc)

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

okay so bestie, welcome to clGetProgramInfo(3clc) from the OpenCL Manual! This is part 1 of 3, so grab your boba and stay tuned 💖✨

✨ NAME ✨

clGetProgramInfo — returns info about the program object. Like, all the details, no cap. You wanna know something about a program object? This function is literally your girl 💅

       cl_int clGetProgramInfo(cl_program program, cl_program_info param_name,
                               size_t param_value_size, void *param_value,
                               size_t *param_value_size_ret);

🌸 PARAMETERS 🌸

  • program — specifies the program object you're querying. That's the one you're asking about, bestie 👑

and that's just part 1, bestie — there's more coming, so don't go anywhere! 🦋

Okay so, param_name — specifies the information to query. The list of supported param_name types and the information returned in param_value by clGetProgramInfo is described in the table below. 💅

cl_program_info → Return Type and Info. returned in param_value

  • CL_PROGRAM_REFERENCE_COUNT — return type: cl_uint. Returns the program reference count. ✨
  • CL_PROGRAM_CONTEXT — return type: cl_context. Returns the context specified when the program object is created. 🎀
  • CL_PROGRAM_NUM_DEVICES — return type: cl_uint. Returns the number of devices associated with program. 💖
  • CL_PROGRAM_DEVICES — return type: cl_device_id[]. Returns the list of devices associated with the program object. This can be the devices associated with context on which the program object has been created or can be a subset of devices that are specified when a progam object is created using clCreateProgramWithBinary(3clc). 🦋
  • CL_PROGRAM_SOURCE — return type: char[]. Returns the program source code specified by clCreateProgramWithSource(3clc). The source string returned is a concatenation of all source strings specified to clCreateProgramWithSource(3clc) with a null terminator. The concatenation strips any nulls in the original source strings. If program is created using clCreateProgramWithBinary(3clc) or clCreateProgramWithBuiltInKernels(3clc), a null string or the appropriate program source code is returned depending on whether or not the program source code is stored in the binary. The actual number of characters that represents the program source code including the null terminator is returned in param_value_size_ret. 💜
  • CL_PROGRAM_BINARY_SIZES — return type: size_t[]. Returns an array that contains the size in bytes of the program binary (could be an executable binary, compiled binary or library binary) for each device associated with program. The size of the array is the number of devices associated with program. If a binary is not available for a device(s), a size of zero is returned. If program is created using clCreateProgramWithBuiltInKernels(3clc), the implementation may return zero in any entries of the returned array. 🌈
  • CL_PROGRAM_BINARIES — return type: unsigned char *[]. Returns the program binaries (could be an executable binary, compiled binary or library binary) for all devices associated with program. For each device in program, the binary returned can be the binary specified for the device when program is created with clCreateProgramWithBinary(3clc) or it can be the executable binary generated by clBuildProgram(3clc) or clLinkProgram(3clc). If program is created with clCreateProgramWithSource(3clc), the binary returned is the binary generated by clBuildProgram(3clc), clCompileProgram(3clc), or clLinkProgram(3clc). The bits returned can be an implementation-specific intermediate representation (a.k.a. IR) or device specific executable bits or both. The decision on which information is returned in the binary is up to the OpenCL implementation. param_value points to an array of n pointers allocated by the caller, where n is the number of devices associated with program. The buffer sizes needed to allocate the memory that these n pointers refer to can be queried using the CL_PROGRAM_BINARY_SIZES query as described in this table. 👑
  • CL_PROGRAM_BINARIES — bestie, this one is the memory address plug 🔌 Every single entry in this array is where the implementation goes to copy the program binary for one specific device, if a binary actually exists for it. Wanna know which device each binary belongs to? Ask CL_PROGRAM_DEVICES and it'll hand you the device list. It's a whole one-to-one correspondence situation: the array of n pointers you get from CL_PROGRAM_BINARIES lines up index-for-index with the array of devices from CL_PROGRAM_DEVICES. Iconic matched set behavior 💅

And here's the lil plot twist: if an entry in that array is NULL, the implementation just skips copying the program binary for the device sitting at that array index. No drama, it just moves on 🙈

  • CL_PROGRAM_NUM_KERNELS — Return type: size_t

Hands you the number of kernels declared in program that can be made with clCreateKernel(3clc). Heads up though — this tea is only available after a successful program executable has been built for at least one device in the list of devices associated with program. No build, no numbers, periodt.

  • CL_PROGRAM_KERNEL_NAMES — Return type: char[]

Gives you a semi-colon separated list of the kernel names in program that can be made with clCreateKernel(3clc). Same rule as above, bestie: this info only shows up after a successful program executable has been built for at least one device in the list of devices associated with program. So don't come asking before the build slays 😭

🌸 param_value 🌸

A pointer to the memory where the result you're querying gets dropped off. And if param_value is NULL? It's ignored. Simple as that 🫶

🌸 param_value_size 🌸

This one specifies the size in bytes of the memory that param_value is pointing at. And this size must be ≥ the size of the return type as described in the table above. Too small = not it 💀

🌸 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's ignored. We love a flexible king ✨

💖 ERRORS 💖

Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of these:

  • 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 as described in the table above and param_value is not NULL. Both conditions gotta hit, okay?
  • CL_INVALID_PROGRAM — if program is not a valid program object. Fake program = instant reject 🙅‍♀️
  • CL_INVALID_PROGRAM_EXECUTABLE — if param_name is CL_PROGRAM_NUM_KERNELS or CL_PROGRAM_KERNEL_NAMES and a successful program executable has not been built for at least one device in the list of devices associated with program. Yeah, you gotta actually build it first bestie.
  • 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 💀

📜 SPECIFICATION 📜

OpenCL Specification[1]

👀 SEE ALSO 👀

clGetProgramBuildInfo(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 150, section 5.6.7 - Program Object Queries (updated for 1.2 rev 14)

That's the whole page, bestie — we ate and left absolutely zero crumbs 💅 This one came to you from The Khronos Group, dated 01/14/2021, and the page is literally called CLGETPROGRAMINFO(3clc) if you ever need to find her again. Go query something iconic 🌈💖✨

📦 where this page comes from