OpenCL™规范 5.8.9. 程序对象查询

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，则忽略它。

Table 43. List of supported param_names by clGetProgramInfo

​表43 clGetProgramInfo支持的参数名称列表

Program Info 程序信息	Return Type 返回类型	Description 描述
CL_PROGRAM_REFERENCE_COUNT [26]	cl_uint	Return the program reference count. 返回程序引用计数。
CL_PROGRAM_CONTEXT	cl_context	Return the context specified when the program object is created 返回创建程序对象时指定的上下文
CL_PROGRAM_NUM_DEVICES	cl_uint	Return the number of devices associated with program. 返回与程序关联的设备数量。
CL_PROGRAM_DEVICES	cl_device_id[]	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创建程序对象时指定的设备子集。
CL_PROGRAM_SOURCE	char[]	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. ​ 返回clCreateProgramWithSource指定的程序源代码。返回的源字符串是用null终止符指定给clCreateProgramWithSource的所有源字符串的连接。连接会删除原始源字符串中的所有空值。 ​ 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. 如果使用clCreateProgrammWithBinary、clCreateProgramWithIL、clCreateProgramWithILKHR或clCreateProgramaWithBuiltInKernels创建程序，则根据程序源代码是否存储在二进制文件中，将返回空字符串或相应的程序源代码。   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中返回表示包括空终止符的程序源代码的实际字符数。
CL_PROGRAM_IL missing before version 2.1. CL_PROGRAM_IL_KHR provided by the cl_khr_il_program extension.	char[]	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. ​ 如果使用clCreateProgramWithSource、clCreateProgram WithBinary或clCreateProgramaWithBuiltInKernels创建程序，则param_value指向的内存将保持不变，param_value_size_ret将设置为0。
CL_PROGRAM_BINARY_SIZES	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, the implementation may return zero in any entries of the returned array. ​如果程序是使用clCreateProgramWithBuiltInKernels创建的，则实现可能会在返回的数组的任何条目中返回零。
CL_PROGRAM_BINARIES	unsigned char*[]	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. ​ 返回与程序关联的所有设备的程序二进制文件（可以是可执行二进制文件、编译二进制文件或库二进制文件）。对于程序中的每个设备，返回的二进制文件可以是使用clCreateProgramWithBinary创建程序时为设备指定的二进制文件，也可以是clBuildProgram或clLinkProgram生成的可执行二进制文件。如果程序是用clCreateProgramWithSource或clCreateProgramWithIL创建的，则返回的二进制文件是由clBuildProgram、clCompileProgram或clLinkProgram生成的二进制文件。返回的位可以是特定于实现的中间表示（也称为IR）或特定于设备的可执行位，或两者兼而有之。二进制文件中返回哪些信息的决定取决于OpenCL实现。 ​ 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. ​ param_value指向由调用者分配的n个指针的数组，其中n是与程序关联的设备数量。分配这n个指针所引用的内存所需的缓冲区大小可以使用CL_PROGRAM_BINARY_SIZE查询来查询，如下表所述。 ​ 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返回的设备数组之间存在一一对应关系。
CL_PROGRAM_NUM_KERNELS missing before version 1.2.	size_t	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. ​ 返回程序中声明的可以使用clCreateKernel创建的内核数量。只有在为与program相关联的设备列表中的至少一个设备构建了成功的程序可执行文件后，此信息才可用。
CL_PROGRAM_KERNEL_NAMES missing before version 1.2.	char[]	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. ​ 返回可以使用clCreateKernel创建的程序中以分号分隔的内核名称列表。只有在为与程序相关联的设备列表中的至少一个设备构建了成功的程序可执行文件后，此信息才可用。
CL_PROGRAM_SCOPE_GLOBAL_CTORS_PRESENT missing before version 2.2 and deprecated by version 3.0.	cl_bool	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.	cl_bool	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，则忽略它。

Table 44. List of supported param_names by clGetProgramBuildInfo

​表44 clGetProgramBuildInfo支持的参数名列表

Program Build Info 程序编译信息	Return Type 返回类型	Description 描述
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. 返回构建、编译或链接状态，以最后在设备的指定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对象上执行的为准）尚未完成，则返回构建状态。
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. ​ 返回由clBuildProgram、clCompileProgram或clLinkProgram中的options参数指定的构建、编译或链接选项，以最后在device的指定program对象上执行的选项为准。 ​ If build status of the specified program for device is CL_BUILD_NONE, an empty string is returned. ​ 如果设备的指定程序的构建状态为CL_build_NONE，则返回一个空字符串。
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. ​ 返回clBuildProgram、clCompileProgram或clLinkProgram的构建、编译或链接日志，以最后在设备程序上执行的为准。 ​ If build status of the specified program for device is CL_BUILD_NONE, an empty string is returned. ​ 如果设备的指定程序的构建状态为CL_build_NONE，则返回一个空字符串。
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_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 -create-library link option, or when a compiled library binary was loaded using clCreateProgramWithBinary. CL_PROGRAM_BINARY_TYPE_LIBRARY-库二进制文件与device相关联。当clLinkProgram使用-create-library链接选项链接指定的program对象时，或者当使用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_BINARY_TYPE_EXCECUTABLE-可执行二进制文件与device相关联。当clLinkProgram在没有-create-library链接选项的情况下链接指定的program对象时，或者当使用clBuildProgram构建可执行二进制文件时，就会出现这种情况。 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.	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:

如果函数执行成功，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查询的设备的程序二进制文件可以用作相关根设备的二进制文件，以及从根级设备或其子设备创建的所有子设备。