C Specification

To return build information for each device in the program object, call the function

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);

Parameters

  • program specifies the program object being queried.

  • device specifies the device for which build information is being queried. device must be a valid device associated with program.

  • param_name specifies the information to query. The list of supported param_name types and the information returned in param_value by clGetProgramBuildInfo is described in the Program Build Queries table.

  • param_value is a pointer to memory where the appropriate result being queried is returned. If param_value is NULL, it is ignored.

  • param_value_size is used to specify the size in bytes of memory pointed to by param_value. This size must be ≥ size of return type as described in the Program Build Queries table.

  • param_value_size_ret returns the actual size in bytes of data being queried by param_name. If param_value_size_ret is NULL, it is ignored.

Description

Table 1. List of supported param_names by https://www.khronos.org/registry/OpenCL/specs/2.2/html/OpenCL_API.html#clGetProgramBuildInfo
cl_program_build_info Return Type Info. returned in param_value

CL_​PROGRAM_​BUILD_​STATUS

cl_build_status

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

This can be one of the following:

CL_​BUILD_​NONE - The build status returned if no clBuildProgram, clCompileProgram or clLinkProgram has been performed on the specified program object for device).

CL_​BUILD_​ERROR - The build status returned if clBuildProgram, clCompileProgram or clLinkProgram - whichever was performed last on the specified program object for device - generated an error.

CL_​BUILD_​SUCCESS - The build status returned if clBuildProgram, clCompileProgram or clLinkProgram - whichever was performed last on the specified program object for device - was successful.

CL_​BUILD_​IN_​PROGRESS - The build status returned if clBuildProgram, clCompileProgram or clLinkProgram - whichever was performed last on the specified program object for device - has not finished.

CL_​PROGRAM_​BUILD_​OPTIONS

char[]

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

If build status of the specified program for device is CL_​BUILD_​NONE, an empty string is returned.

CL_​PROGRAM_​BUILD_​LOG

char[]

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

If build status of the specified program for device is CL_​BUILD_​NONE, an empty string is returned.

CL_​PROGRAM_​BINARY_​TYPE

Missing before version 1.2.

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 the specified program object for device.

CL_​PROGRAM_​BINARY_​TYPE_​COMPILED_​OBJECT - A compiled binary is associated with device. This is the case when the specified program object was created using clCreateProgramWithSource and compiled using clCompileProgram, or when a compiled binary was loaded using clCreateProgramWithBinary.

CL_​PROGRAM_​BINARY_​TYPE_​LIBRARY - A library binary is associated with device. This is the case when the specified program object was linked by clLinkProgram using the -create-library link option, or when a compiled library binary was loaded using clCreateProgramWithBinary.

CL_​PROGRAM_​BINARY_​TYPE_​EXECUTABLE - An executable binary is associated with device. This is the case when the specified program object was linked by clLinkProgram without the -create-library link option, or when an executable binary was built using clBuildProgram.

CL_​PROGRAM_​BUILD_​GLOBAL_​VARIABLE_​TOTAL_​SIZE

Missing before version 2.0.

size_t

The total amount of storage, in bytes, used by program variables in the global address space.

clGetProgramBuildInfo returns CL_​SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:

  • CL_​INVALID_​DEVICE if device is not in the list of devices associated with program.

  • 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 Program Build Queries table and param_value is not NULL.

  • 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.

A program binary (compiled binary, library binary or executable binary) built for a parent device can be used by all its sub-devices. If a program binary has not been built for a sub-device, the program binary associated with the parent device will be used.

A program binary for a device specified with clCreateProgramWithBinary or queried using clGetProgramInfo 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.

See Also

Document Notes

For more information, see the OpenCL Specification

This page is extracted from the OpenCL Specification. Fixes and changes should be made to the Specification, not directly.

Copyright (c) 2014-2020 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.