CLGETPROGRAMBUILDINF(3clc)

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

✨ CLGETPROGRAMBUILDINF ✨

okay bestie, welcome to the OpenCL Manual 💖 this one lives in section 3clc, and it's literally the vibe check for your build info. iykyk 🫶

🌸 NAME 🌸

clGetProgramBuildInfo — it hands you back the build information for each device in the program object. yes, each device, not just one, we love a multitasker 💅

cl_int clGetProgramBuildInfo(cl_program program, cl_device_id device,
                             cl_program_build_info param_name,
                             size_t param_value_size, void *param_value,
                             size_t *param_value_size_ret);

like, that's the whole signature, copy it exactly, no cap 🎀

🦋 PARAMETERS 🦋

  • program — Specifies the program object being queried. that's the lil guy you're asking all your questions about 💜
  • device — Specifies the device for which build information is being queried. and listen — device must be a valid device associated with program. not some random device you found in the group chat, it has to actually belong to the program or it's giving 🙈 💀

okay so param_name is literally you going "hey bestie, which lil fact do you want me to pull up for you?" ✨ And param_value is where that fact lands. The full list of supported param_name types and the info returned in param_value by clGetProgramBuildInfo is right here:

real talk: the header row of this table in the source docs says cl_program_buid_info (not a drill, the typo is canon 💀). Anyway — the menu:

🎀 CL_PROGRAM_BUILD_STATUS

Return type: cl_build_status

Returns the build, compile or link status, whichever was performed last on program for device.

This can be one of the following:

🌸 CL_PROGRAM_BUILD_OPTIONS

Return type: char[]

Return the build, compile or link options specified by the options argument in clBuildProgram(3clc), clCompileProgram(3clc) or clLinkProgram(3clc), whichever was performed last on program for device.

If build status of program for device is CL_BUILD_NONE, an empty string is returned.

🦋 CL_PROGRAM_BUILD_LOG

Return type: char[]

Return the build, compile or link log for clBuildProgram(3clc), clCompileProgram(3clc) or clLinkProgram(3clc) whichever was performed last on program for device.

If build status of program for device is CL_BUILD_NONE, an empty string is returned.

👑 CL_PROGRAM_BINARY_TYPE

Return type: cl_program_binary_type

Return the program binary type for device. This can be one of the following values:

  • CL_PROGRAM_BINARY_TYPE_NONE — there is no binary associated with device.
  • CL_PROGRAM_BINARY_TYPE_COMPILED_OBJECT — a compiled binary is associated with device. This is the case if program was created using clCreateProgramWithSource(3clc) and compiled using clCompileProgram(3clc) or a compiled binary is loaded using clCreateProgramWithBinary(3clc).
  • CL_PROGRAM_BINARY_TYPE_LIBRARY — a library binary is associated with device. This is the case if program was created by clLinkProgram(3clc) which is called with the –createlibrary link option or if a library binary is loaded using clCreateProgramWithBinary(3clc).
  • CL_PROGRAM_BINARY_TYPE_EXECUTABLE — an executable binary is associated with device.

...and that last row of the table? It's the one that tells you when the program's binary type is what it is:

okay and now the three little parameter besties that every query hands you, one by one:

  • param_value — a pointer to memory where the appropriate result being queried gets returned. If param_value is NULL, bestie, it's just ignored. 🫥
  • param_value_size — specifies the size in bytes of the memory that param_value points to. This size must be ≥ size of return type as described in the table above. No shrinking the cup, it needs to fit the whole drink. 🥤
  • 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. 🙈

✨ NOTES ✨

A program binary (compiled binary, library binary or executable binary) built for a parent device can be used by all its sub-devices. And if a program binary has not been built for a sub-device? The program binary associated with the parent device will be used. it's giving "borrow your mom's card, she won't notice" energy 💳

A program binary for a device specified with clCreateProgramWithBinary(3clc) or queried using clGetProgramInfo(3clc) can be used as the binary for the associated root device, and all sub-devices created from the root-level device or sub-devices thereof. the family tree is thriving 🌳

💀 ERRORS 💀

Returns CL_SUCCESS if the function is executed successfully. Otherwise it returns the following:

  • Returns CL_INVALID_DEVICE if device is not in the list of devices associated with program. not your device, not your business. 🚫
  • Returns CL_INVALID_VALUE if param_name is not valid, or if the 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.
  • Returns CL_INVALID_PROGRAM if program is a not a valid program 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.

📖 SPECIFICATION 📖

OpenCL Specification[1]

👀 SEE ALSO 👀

clGetProgramInfo(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 📎

(yeah bestie, there are two NOTES sections on this page, that's not a typo, that's just how the manpage is built 💅)

  1. OpenCL Specification page 153, section 5.6.7 - Program Object Queries

and that's the whole page, start to finish 🎀 sourced from The Khronos Group, stamped 01/14/2021, living its life as CLGETPROGRAMBUILDINF(3clc) — go query some program build info, you absolute icon ✨💖

📦 where this page comes from