OpenCL™规范 5.8.4. 构建程序可执行文件

5.8.4. Building Program Executables

5.8.4. 构建程序可执行文件

To build (compile & link) a program executable, call the function

要构建（编译和链接）可执行程序，请调用以下函数

// Provided by CL_VERSION_1_0
cl_int clBuildProgram(
    cl_program program,
    cl_uint num_devices,
    const cl_device_id* device_list,
    const char* options,
    void (CL_CALLBACK* pfn_notify)(cl_program program, void* user_data),
    void* user_data);

• program is the program object.

• program是程序对象。

• device_list is a pointer to a list of devices associated with program. If device_list is a NULL value, the program executable is built for all devices associated with program for which a source or binary has been loaded. If device_list is a non-NULL value, the program executable is built for devices specified in this list for which a source or binary has been loaded.

• device_list是指向与program关联的设备列表的指针。如果device_list为NULL值，则为与已加载源代码或二进制文件的程序关联的所有设备构建程序可执行文件。如果device_list是非NULL值，则程序可执行文件是为此列表中指定的设备构建的，这些设备已加载源代码或二进制文件。

• num_devices is the number of devices listed in device_list.

• num_devices是device_list中列出的设备数量。

• options is a pointer to a null-terminated string of characters that describes the build options to be used for building the program executable. The list of supported options is described in Compiler Options. If the program was created using clCreateProgramWithBinary and options is a NULL pointer, the program will be built as if options were the same as when the program binary was originally built. If the program was created using clCreateProgramWithBinary and options string contains anything other than the same options in the same order (whitespace ignored) as when the program binary was originally built, then the behavior is implementation-defined. Otherwise, if options is a NULL pointer then it will have the same result as the empty string.

• ​options是一个指向以null结尾的字符串的指针，该字符串描述了用于构建程序可执行文件的构建选项。编译器选项中描述了支持的选项列表。如果程序是使用clCreateProgramWithBinary创建的，并且options是NULL指针，则程序将被构建为选项与最初构建程序二进制文件时相同。如果程序是使用clCreateProgramWithBinary创建的，并且选项字符串包含与程序二进制文件最初构建时顺序相同的选项以外的任何内容（忽略空格），则行为是实现定义的。否则，如果选项是NULL指针，则其结果将与空字符串相同。

• pfn_notify is a function pointer to a notification routine. The notification routine is a callback function that an application can register and which will be called when the program executable has been built (successfully or unsuccessfully). If pfn_notify is not NULL, clBuildProgram does not need to wait for the build to complete and can return immediately once the build operation can begin. Any state changes of the program object that result from calling clBuildProgram (e.g. build status or log) will be observable from this callback function. The build operation can begin if the context, program whose sources are being compiled and linked, list of devices and build options specified are all valid and appropriate host and device resources needed to perform the build are available. If pfn_notify is NULL, clBuildProgram does not return until the build has completed. This callback function may be called asynchronously by the OpenCL implementation. It is the application’s responsibility to ensure that the callback function is thread-safe.

• ​pfn_notify是一个指向通知例程的函数指针。通知例程是一个回调函数，应用程序可以注册它，当程序可执行文件构建完成（成功或失败）时，它将被调用。如果pfn_notify不为NULL，clBuildProgram不需要等待构建完成，并且可以在构建操作开始后立即返回。调用clBuildProgram导致的程序对象的任何状态更改（例如构建状态或日志）都可以从该回调函数中观察到。如果上下文、源代码正在编译和链接的程序、设备列表和指定的构建选项都有效，并且执行构建所需的适当主机和设备资源可用，则可以开始构建操作。如果pfn_notify为NULL，则clBuildProgram在构建完成之前不会返回。OpenCL实现可以异步调用此回调函数。应用程序有责任确保回调函数是线程安全的。

• user_data will be passed as an argument when pfn_notify is called. user_data can be NULL.

• 当调用pfn_notify时，user_data将作为参数传递。user_data可以为NULL。

The program executable is built from the program source or binary for all the devices, or a specific device(s) in the OpenCL context associated with program. OpenCL allows program executables to be built using the source or the binary. clBuildProgram must be called for program created using clCreateProgramWithSource, clCreateProgramWithIL or clCreateProgramWithBinary to build the program executable for one or more devices associated with program. If program is created with clCreateProgramWithBinary, then the program binary must be an executable binary (not a compiled binary or library).

​程序可执行文件是从程序源代码或二进制文件构建的，适用于所有设备，或与程序相关联的OpenCL上下文中的特定设备。OpenCL允许使用源代码或二进制文件构建程序可执行文件。对于使用clCreateProgramWithSource、clCreateProgram WithIL或clCreateProgramaWithBinary创建的program，必须调用clBuildProgram，以便为与程序关联的一个或多个设备构建可执行程序。如果program是用clCreateProgramWithBinary创建的，那么程序二进制文件必须是可执行二进制文件（不是编译的二进制文件或库）。

The executable binary can be queried using clGetProgramInfo(program, CL_PROGRAM_BINARIES, …​) and can be specified to clCreateProgramWithBinary to create a new program object.

​可执行二进制文件可以使用clGetProgramInfo（程序，CL_PROGRAM_BINARIES，…）查询，并且可以指定给clCreateProgramWithBinary以创建新的程序对象。

clBuildProgram returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:

如果函数执行成功，clBuildProgram将返回CL_SUCCESS。否则，它将返回以下错误之一：

• CL_INVALID_PROGRAM if program is not a valid program object.

• CL_INVALID_PROGRAM，如果program不是有效的程序对象。

• CL_INVALID_VALUE if device_list is NULL and num_devices is greater than zero, or if device_list is not NULL and num_devices is zero.

• 如果device_list为NULL且num_devices大于零，或者device_list不为NULL且num_devices为零，则CL_INVALID_VALUE。

• CL_INVALID_VALUE if pfn_notify is NULL but user_data is not NULL.

• 如果pfn_notify为NULL，但user_data不为NULL，则CL_INVALID_VALUE。

• CL_INVALID_DEVICE if any device in device_list is not in the list of devices associated with program.

• CL_INVALID_DEVICE，如果device_list中的任何设备不在与program关联的设备列表中。

• CL_INVALID_BINARY if program is created with clCreateProgramWithBinary and devices listed in device_list do not have a valid program binary loaded.

• CL_INVALID_BINARY如果program是用clCreateProgramWithBinary创建的，并且device_list中列出的设备没有加载有效的程序二进制文件。

• CL_INVALID_BUILD_OPTIONS if the build options specified by options are invalid.

• 如果选项指定的构建选项无效，则返回CL_INVALID_BUILD_OPTIONS。

• CL_COMPILER_NOT_AVAILABLE if program is created with clCreateProgramWithILKHR, clCreateProgramWithSource or clCreateProgramWithIL and a compiler is not available, i.e. CL_DEVICE_COMPILER_AVAILABLE specified in the Device Queries table is set to CL_FALSE.

• 如果程序是使用clCreateProgramWithILKHR、clCreateProgramaWithSource或clCreateProgram WithIL创建的，并且编译器不可用，即设备查询表中指定的CLD_COMPILER_AVAILABLE设置为CL_FALSE，则CL_COMPILER_NOT_AVAILABLE可用。

• CL_BUILD_PROGRAM_FAILURE if there is a failure to build the program executable. This error will be returned if clBuildProgram does not return until the build has completed.

• CL_BUILD_PROGRAM_FAILURE如果生成可执行程序失败。如果clBuildProgram在构建完成之前没有返回，则将返回此错误。

• CL_INVALID_OPERATION if the build of a program executable for any of the devices listed in device_list by a previous call to clBuildProgram for program has not completed.

• CL_INVALID_OPERATION如果之前调用clBuildProgram for program时，尚未完成device_list中列出的任何设备的可执行程序的构建。

• CL_INVALID_OPERATION if there are kernel objects attached to program.

• CL_INVALID_OPERATION（如果program附加了内核对象）。

• CL_INVALID_OPERATION if program was not created with clCreateProgramWithSource, clCreateProgramWithIL or clCreateProgramWithBinary.

• 如果program不是用clCreateProgramWithSource、clCreateProgramaWithIL或clCreateProgram WithBinary创建的，则为CL_INVALID_OPERATION。

• 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实现所需的资源。