5.8.9. Program Object Queries
5.8.9. 程序对象查询
To return information about a program object, call the function
要返回有关程序对象的信息,请调用函数
// Provided by CL_VERSION_1_0
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);
-
program specifies the program object being queried.
-
program指定要查询的程序对象。
-
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 Program Object Queries table.
-
param_name指定要查询的信息。程序对象查询表中描述了支持的param_name类型列表以及clGetProgramInfo在param_value中返回的信息。
-
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是一个指向内存的指针,在内存中返回适当的查询结果。如果param_value为NULL,则忽略它。
-
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 Object Queries table.
-
param_value_size用于指定param_value指向的内存字节数。此大小必须≥程序对象查询表中所述的返回类型的大小。
-
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. -
param_value_size_ret返回param_name查询的数据的实际大小(以字节为单位)。如果param_value_size_ret为NULL,则忽略它。
Program Info 程序信息 | Return Type 返回类型 | Description 描述 |
---|---|---|
| Return the program reference count. 返回程序引用计数。 | |
| Return the context specified when the program object is created 返回创建程序对象时指定的上下文 | |
| Return the number of devices associated with program. 返回与程序关联的设备数量。 | |
| Return 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 program object is created using clCreateProgramWithBinary. 返回与程序对象关联的设备列表。这可以是与创建程序对象的上下文相关联的设备,也可以是使用clCreateProgramWithBinary创建程序对象时指定的设备子集。 | |
| Return the program source code specified by clCreateProgramWithSource. The source string returned is a concatenation of all source strings specified to clCreateProgramWithSource with a null terminator. The concatenation strips any nulls in the original source strings. If program is created using clCreateProgramWithBinary, clCreateProgramWithIL, clCreateProgramWithILKHR, or clCreateProgramWithBuiltInKernels, 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. 在param_value_size_ret中返回表示包括空终止符的程序源代码的实际字符数。 | |
missing before version 2.1. provided by the |
| Returns the program IL for programs created with clCreateProgramWithILKHR or clCreateProgramWithIL. 返回用clCreateProgramWithILKHR或clCreateProgramaWithIL创建的程序的程序IL。 If program is created with clCreateProgramWithSource, clCreateProgramWithBinary or clCreateProgramWithBuiltInKernels the memory pointed to by param_value will be unchanged and param_value_size_ret will be set to 0. |
| 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, the implementation may return zero in any entries of the returned array. 如果程序是使用clCreateProgramWithBuiltInKernels创建的,则实现可能会在返回的数组的任何条目中返回零。 | |
| Return 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 or it can be the executable binary generated by clBuildProgram or clLinkProgram. If program is created with clCreateProgramWithSource or clCreateProgramWithIL, the binary returned is the binary generated by clBuildProgram, clCompileProgram or clLinkProgram. 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 Each entry in this array is used by the implementation as the location in memory where to copy the program binary for a specific device, if there is a binary available. To find out which device the program binary in the array refers to, use the CL_PROGRAM_DEVICES query to get the list of devices. There is a one-to-one correspondence between the array of n pointers returned by CL_PROGRAM_BINARIES and array of devices returned by CL_PROGRAM_DEVICES. 此数组中的每个条目都被实现用作内存中复制特定设备的程序二进制文件的位置(如果有可用的二进制文件)。要找出数组中程序二进制文件引用的设备,请使用CL_PROGRAM_DEVICES查询获取设备列表。CL_PROGRAM_BINARIES返回的n个指针数组与CL_PROGRA_MDEVICES返回的设备数组之间存在一一对应关系。 | |
missing before version 1.2. |
| Returns the number of kernels declared in program that can be created with clCreateKernel. This information is only available after a successful program executable has been built for at least one device in the list of devices associated with program. |
missing before version 1.2. |
| Returns a semi-colon separated list of kernel names in program that can be created with clCreateKernel. This information is only available after a successful program executable has been built for at least one device in the list of devices associated with program. |
CL_PROGRAM_SCOPE_GLOBAL_CTORS_PRESENT missing before version 2.2 and deprecated by version 3.0. |
| This indicates that the program object contains non-trivial constructor(s) that will be executed by runtime before any kernel from the program is executed. This information is only available after a successful program executable has been built for at least one device in the list of devices associated with program. 这表示程序对象包含非平凡构造函数,这些构造函数将在程序的任何内核执行之前由运行时执行。只有在为与程序相关联的设备列表中的至少一个设备构建了成功的程序可执行文件后,此信息才可用。 Querying CL_PROGRAM_SCOPE_GLOBAL_CTORS_PRESENT may unconditionally return CL_FALSE if no devices associated with program support constructors for program scope global variables. Support for constructors and destructors for program scope global variables is required only for OpenCL 2.2 devices. 如果没有与程序支持程序作用域全局变量的构造函数相关联的设备,则查询CL_PROGRAM_SCOPE_GLOBAL_CTORS_PRESENT可能会无条件返回CL_FALSE。仅OpenCL 2.2设备需要支持程序作用域全局变量的构造函数和析构函数。 |
CL_PROGRAM_SCOPE_GLOBAL_DTORS_PRESENT missing before version 2.2 and deprecated by version 3.0. |
| This indicates that the program object contains non-trivial destructor(s) that will be executed by runtime when program is destroyed. This information is only available after a successful program executable has been built for at least one device in the list of devices associated with program. 这表示程序对象包含非平凡析构函数,当程序被销毁时,这些析构函数将由运行时执行。只有在为与程序相关联的设备列表中的至少一个设备构建了成功的程序可执行文件后,此信息才可用。 Querying CL_PROGRAM_SCOPE_GLOBAL_CTORS_PRESENT may unconditionally return CL_FALSE if no devices associated with program support destructors for program scope global variables. Support for constructors and destructors for program scope global variables is required only for OpenCL 2.2 devices. 如果没有与程序关联的设备支持程序作用域全局变量的析构函数,则查询CL_PROGRAM_SCOPE_GLOBAL_CTORS_PRESENT可能会无条件返回CL_FALSE。仅OpenCL 2.2设备需要支持程序作用域全局变量的构造函数和析构函数。 |
clGetProgramInfo returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:
如果函数执行成功,clGetProgramInfo将返回CL_SUCCESS。否则,它将返回以下错误之一:
-
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 Object Queries table and param_value is not
NULL
. -
如果param_name无效,或者param_value_size指定的字节大小小于程序对象查询表中描述的返回类型的大小,并且param_VALUE不为NULL,则返回CL_INVALID_VALUE。
-
CL_INVALID_PROGRAM if program is a not a valid program object.
-
CL_INVALID_PROGRAM,如果program不是有效的程序对象。
-
CL_INVALID_PROGRAM_EXECUTABLE if param_name is CL_PROGRAM_NUM_KERNELS, CL_PROGRAM_KERNEL_NAMES, CL_PROGRAM_SCOPE_GLOBAL_CTORS_PRESENT, or CL_PROGRAM_SCOPE_GLOBAL_DTORS_PRESENT and a successful program executable has not been built for at least one device in the list of devices associated with program.
-
如果param_name为CL_PROGRAM_NUM_KERNELS、CL_PROGRAM-KERNEL_NAMES、CL_PROGRAM_SCOPE_GLOBAL_CTORS_PRESENT或CL_PROGRAD_SCOPE_GOLBAL_DTORS_PRESENCE,并且尚未为与程序关联的设备列表中的至少一个设备构建成功的程序可执行文件,则为CL_INVALID_PRORAM_EXECUTABLE。
-
CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
-
CL_OUT_OF_RESOURCES,如果无法在设备上分配OpenCL实现所需的资源。
-
CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
-
CL_OUT_OF_HOST_MEMORY,如果无法在主机上分配OpenCL实现所需的资源。
To return build information for each device in the program object, call the function
要返回程序对象中每个设备的构建信息,请调用函数
// Provided by CL_VERSION_1_0
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);
-
program specifies the program object being queried.
-
program指定要查询的程序对象。
-
device specifies the device for which build information is being queried. device must be a valid device associated with program.
-
device指定正在查询其构建信息的设备。device必须是与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_name指定要查询的信息。“程序构建查询”表中描述了支持的param_name类型列表以及clGetProgramBuildInfo在param_value中返回的信息。
-
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是一个指向内存的指针,在内存中返回适当的查询结果。如果param_value为NULL,则忽略它。
-
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用于指定param_value指向的内存字节数。此大小必须≥程序构建查询表中所述的返回类型的大小。
-
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. -
param_value_size_ret返回param_name查询的数据的实际大小(以字节为单位)。如果param_value_size_ret为NULL,则忽略它。
Program Build Info 程序编译信息 | Return Type 返回类型 | Description 描述 |
---|---|---|
| Returns the build, compile or link status, whichever was performed last on the specified program object for device. 返回构建、编译或链接状态,以最后在设备的指定program对象上执行的状态为准。 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_NONE-如果未对设备的指定program对象执行clBuildProgram、clCompileProgram或clLinkProgram,则返回构建状态)。 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_ERROR-如果clBuildProgram、clCompileProgram或clLinkProgram(以最后对device的指定program对象执行的程序为准)生成错误,则返回生成状态。 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_SUCCESS-如果clBuildProgram、clCompileProgram或clLinkProgram(以最后在device的指定program对象上执行的为准)成功,则返回构建状态。 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_BUILD_IN_PROGRESS-如果clBuildProgram、clCompileProgram或clLinkProgram(以最后在device的指定program对象上执行的为准)尚未完成,则返回构建状态。 | |
| 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. | |
| 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. | |
missing before version 1.2. |
| 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_NONE-没有与设备的指定program对象关联的二进制文件。 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_COMPILED_OBJECT-已编译的二进制文件与device相关联。当使用clCreateProgramWithSource创建指定的program对象并使用clCompileProgram编译时,或者当使用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 CL_PROGRAM_BINARY_TYPE_LIBRARY-库二进制文件与device相关联。当clLinkProgram使用 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 CL_PROGRAM_BINARY_TYPE_EXCECUTABLE-可执行二进制文件与device相关联。当clLinkProgram在没有 CL_PROGRAM_BINARY_TYPE_INTERMEDIATE — An intermediate (non-source) representation for the program is loaded as a binary. The program must be further processed with clCompileProgram or clBuildProgram. CL_PROGRAM_BINARY_TYPE_INTERMEDIATE——程序的中间(非源)表示以二进制形式加载。必须使用clCompileProgram或clBuildProgram对程序进行进一步处理。 If processed with clCompileProgram, the result will be a binary of type CL_PROGRAM_BINARY_TYPE_COMPILED_OBJECT or CL_PROGRAM_BINARY_TYPE_LIBRARY. If processed with clBuildProgram, the result will be a binary of type CL_PROGRAM_BINARY_TYPE_EXECUTABLE. 如果用clCompileProgram处理,结果将是CL_PROGRAM_BINARY_TYPE_COMPILED_OBJECT或CL_PROGRAM_BINARY_TYPE_LIBRARY类型的二进制文件。如果使用clBuildProgram进行处理,结果将是CL_PROGRAM_BINARY_TYPE_EXECUTABLE类型的二进制文件。 |
CL_PROGRAM_BUILD_GLOBAL_VARIABLE_TOTAL_SIZE missing before version 2.0. |
| 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:
如果函数执行成功,clGetProgramBuildInfo将返回CL_SUCCESS。否则,它将返回以下错误之一:
-
CL_INVALID_DEVICE if device is not in the list of devices associated with program.
-
CL_INVALID_DEVICE(如果device不在与程序关联的设备列表中)。
-
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
. -
如果param_name无效,或者param_value_size指定的字节大小小于程序构建查询表中描述的返回类型的大小,并且param_value不为NULL,则返回CL_INVALID_VALUE。
-
CL_INVALID_PROGRAM if program is a not a valid program object.
-
CL_INVALID_PROGRAM,如果program不是有效的程序对象。
-
CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
-
CL_OUT_OF_RESOURCES,如果无法在设备上分配OpenCL实现所需的资源。
-
CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
-
CL_OUT_OF_HOST_MEMORY,如果无法在主机上分配OpenCL实现所需的资源。
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. 使用clCreateProgramWithBinary指定或使用clGetProgramInfo查询的设备的程序二进制文件可以用作相关根设备的二进制文件,以及从根级设备或其子设备创建的所有子设备。 |