OpenCL™规范 5.8.5. 程序的单独编译和链接-CSDN博客

5.8.5. Separate Compilation and Linking of Programs

5.8.5. 程序的单独编译和链接

Separate compilation and linking are missing before version 1.2.

1.2版本之前缺少单独的编译和链接。

OpenCL programs are compiled and linked to support the following:

OpenCL程序经过编译和链接，以支持以下内容：

Separate compilation and link stages. Program sources can be compiled to generate a compiled binary object and linked in a separate stage with other compiled program objects to the program executable.
单独的编译和链接阶段。程序源可以被编译以生成编译的二进制对象，并在单独的阶段与其他编译的程序对象链接到程序可执行文件。
Embedded headers. In OpenCL 1.0 and 1.1, the I build option could be used to specify the list of directories to be searched for headers files that are included by a program source(s). OpenCL 1.2 extends this by allowing the header sources to come from program objects instead of just header files.
嵌入式头文件。在OpenCL 1.0和1.1中，I build选项可用于指定要搜索程序源代码所包含的头文件的目录列表。OpenCL 1.2扩展了这一点，允许头源来自程序对象，而不仅仅是头文件。
Libraries. The linker can be used to link compiled objects and libraries into a program executable or to create a library of compiled binaries.
库文件。链接器可用于将编译后的对象和库链接到程序可执行文件中，或创建编译后的二进制文件库。

To compile a program’s source for all the devices or a specific device(s) in the OpenCL context associated with the program, call the function

要为与程序关联的OpenCL上下文中的所有设备或特定设备编译程序源代码，请调用以下函数

// Provided by CL_VERSION_1_2
cl_int clCompileProgram(
    cl_program program,
    cl_uint num_devices,
    const cl_device_id* device_list,
    const char* options,
    cl_uint num_input_headers,
    const cl_program* input_headers,
    const char** header_include_names,
    void (CL_CALLBACK* pfn_notify)(cl_program program, void* user_data),
    void* user_data);

clCompileProgram is missing before version 1.2.

clCompileProgram在1.2版本之前缺失。

program is the program object that is the compilation target.
program是作为编译目标的程序对象。
device_list is a pointer to a list of devices associated with program. If device_list is a NULL value, the compile is performed for all devices associated with program. If device_list is a non-NULL value, the compile is performed for devices specified in this list.
device_list是指向与program关联的设备列表的指针。如果device_list为NULL值，则对与program关联的所有设备执行编译。如果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 compilation options to be used for building the program executable. If options is a NULL pointer then it will have the same result as the empty string. Certain options are ignored when program is created with IL. The list of supported options is as described in Compiler Options.
options是指向以null结尾的字符串的指针，该字符串描述了用于构建程序可执行文件的编译选项。如果选项是NULL指针，则其结果将与空字符串相同。当使用IL创建程序时，某些选项将被忽略。支持的选项列表如编译器选项中所述。
num_input_headers specifies the number of programs that describe headers in the array referenced by input_headers.
num_input_headers指定在input_headers引用的数组中描述头文件的程序数量。
input_headers is an array of program embedded headers created with clCreateProgramWithSource.
input_headers是用clCreateProgramWithSource创建的程序嵌入头数组。
header_include_names is an array that has a one to one correspondence with input_headers. Each entry in header_include_names specifies the include name used by source in program that comes from an embedded header. The corresponding entry in input_headers identifies the program object which contains the header source to be used. The embedded headers are first searched before the headers in the list of directories specified by the -I compile option (as described in Preprocessor options). If multiple entries in header_include_names refer to the same header name, the first one encountered will be used.
header_include_names是一个与input_headers一一对应的数组。header_include_names中的每个条目都指定了源代码在程序中使用的包含名称，该名称来自嵌入式头。input_headers中的相应条目标识了包含要使用的头源的程序对象。在-I compile选项指定的目录列表中，首先搜索嵌入的头，然后搜索头（如预处理器选项中所述）。如果header_include_names中的多个条目引用了相同的头名称，则将使用遇到的第一个条目。
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, clCompileProgram does not need to wait for the compiler to complete and can return immediately once the compilation can begin. Any state changes of the program object that result from calling clCompileProgram (e.g. compile status or log) will be observable from this callback function. The compilation can begin if the context, program whose sources are being compiled, list of devices, input headers, programs that describe input headers and compiler options specified are all valid and appropriate host and device resources needed to perform the compile are available. If pfn_notify is NULL, clCompileProgram does not return until the compiler 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，clCompileProgram不需要等待编译器完成，并且可以在编译开始后立即返回。调用clCompileProgram导致的程序对象的任何状态更改（例如编译状态或日志）都可以通过此回调函数观察到。如果上下文、源代码正在编译的程序、设备列表、输入头、描述输入头的程序和指定的编译器选项都有效，并且执行编译所需的适当主机和设备资源可用，则可以开始编译。如果pfn_notify为NULL，则clCompileProgram在编译器完成之前不会返回。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 pre-processor runs before the program sources are compiled. The compiled binary is built for all devices associated with program or the list of devices specified. The compiled binary can be queried using clGetProgramInfo(program, CL_PROGRAM_BINARIES, …) and can be passed to clCreateProgramWithBinary to create a new program object.

预处理器在编译程序源代码之前运行。编译后的二进制文件是为与程序或指定设备列表关联的所有设备构建的。可以使用clGetProgramInfo（program，CL_PROGRAM_BINARIES，…）查询编译后的二进制文件，并将其传递给clCreateProgramWithBinary以创建新的程序对象。

If program was created using clCreateProgramWithIL, then num_input_headers, input_headers, and header_include_names are ignored.

若程序是使用clCreateProgramWithIL创建的，则num_input_headers、input_headers和header_include_names将被忽略。

For example, consider the following program source:

例如，考虑以下程序源：

#include <foo.h>
#include <mydir/myinc.h>
__kernel void
image_filter (int n, int m,
              __constant float *filter_weights,
              __read_only image2d_t src_image,
              __write_only image2d_t dst_image)
{
...
}

This kernel includes two headers foo.h and mydir/myinc.h. The following describes how these headers can be passed as embedded headers in program objects:

这个内核包含两个头文件foo.h和mydir/myinc.h。下面描述了如何将这些头文件作为嵌入式头文件传递到程序对象中：

cl_program foo_pg = clCreateProgramWithSource(context,
    1, &foo_header_src, NULL, &err);
cl_program myinc_pg = clCreateProgramWithSource(context,
    1, &myinc_header_src, NULL, &err);

// lets assume the program source described above is given
// by program_A and is loaded via clCreateProgramWithSource
cl_program input_headers[2] = { foo_pg, myinc_pg };
char * input_header_names[2] = { foo.h, mydir/myinc.h };
clCompileProgram(program_A,
                 0, NULL, // num_devices & device_list
                 NULL,    // compile_options
                 2,       // num_input_headers
                 input_headers,
                 input_header_names,
                 NULL, NULL); // pfn_notify & user_data

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

如果函数执行成功，clCompileProgram将返回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 num_input_headers is zero and header_include_names or input_headers are not NULL or if num_input_headers is not zero and header_include_names or input_headers are NULL.
如果num_input_headers为零且header_include_names或input_headers不为NULL，或者如果num_input _headers非零且header.include_names或input_headers为NULL，则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 device in device_list is not in the list of devices associated with program.
CL_INVALID_DEVICE，如果device_list中的设备不在与program关联的设备列表中。
CL_INVALID_COMPILER_OPTIONS if the compiler options specified by options are invalid.
如果选项指定的编译器选项无效，则返回CL_INVALID_COMPILER_OPTIONS。
CL_INVALID_OPERATION if the compilation or build of a program executable for any of the devices listed in device_list by a previous call to clCompileProgram or clBuildProgram for program has not completed.
CL_INVALID_OPERATION，如果之前对程序的clCompileProgram或clBuildProgram的调用未完成对device_list中列出的任何设备的可执行程序的编译或构建。
CL_COMPILER_NOT_AVAILABLE if a compiler is not available, i.e. CL_DEVICE_COMPILER_AVAILABLE specified in the Device Queries table is set to CL_FALSE.
如果编译器不可用，即“设备查询”表中指定的CLD_COMPILER_AVAILABLE设置为CL_FALSE，则为CL_COMPILER_NOT_AVAILABLE。
CL_COMPILE_PROGRAM_FAILURE if there is a failure to compile the program source. This error will be returned if clCompileProgram does not return until the compile has completed.
CL_COMPILE_PROGRAM_FAILURE如果编译程序源代码失败。如果clCompileProgram在编译完成之前没有返回，则将返回此错误。
CL_INVALID_OPERATION if there are kernel objects attached to program.
CL_INVALID_OPERATION（如果程序附加了内核对象）。
CL_INVALID_OPERATION if program has no source or IL available, i.e. it has not been created with one of
CL_INVALID_OPERATION，如果program没有可用的源或IL，即它不是用以下之一创建的
- clCreateProgramWithIL or clCreateProgramWithILKHR
- clCreateProgramWithIL或clCreateProgram withILKHR
- clCreateProgramWithBinary where -x spir is present in options, if the cl_khr_spir extension is supported.
- clCreateProgramWithBinary，如果支持cl_khr_spir扩展名，则选项中存在-x spir。
- clCreateProgramWithSource
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 link a set of compiled program objects and libraries for all the devices or a specific device(s) in the OpenCL context and create a library or executable, call the function

要链接OpenCL上下文中所有设备或特定设备的一组编译程序对象和库，并创建库或可执行文件，请调用以下函数

// Provided by CL_VERSION_1_2
cl_program clLinkProgram(
    cl_context context,
    cl_uint num_devices,
    const cl_device_id* device_list,
    const char* options,
    cl_uint num_input_programs,
    const cl_program* input_programs,
    void (CL_CALLBACK* pfn_notify)(cl_program program, void* user_data),
    void* user_data,
    cl_int* errcode_ret);

clLinkProgram is missing before version 1.2.

clLinkProgram在1.2版本之前缺失。

context must be a valid OpenCL context.
context必须是有效的OpenCL上下文。
device_list is a pointer to a list of devices that are in context. If device_list is a NULL value, the link is performed for all devices associated with context for which a compiled object is available. If device_list is a non-NULL value, the link is performed for devices specified in this list for which a compiled object is available.
device_list是指向上下文中设备列表的指针。如果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 link options to be used for building the program executable. The list of supported options is as described in Linker Options. If the program was created using clCreateProgramWithBinary and options is a NULL pointer, the program will be linked 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创建的，并且选项是NULL指针，则程序将被链接，就像选项与最初构建程序二进制文件时相同一样。如果程序是使用clCreateProgramWithBinary创建的，并且选项字符串包含与程序二进制文件最初构建时顺序相同的选项以外的任何内容（忽略空格），则行为是实现定义的。否则，如果选项是NULL指针，则其结果将与空字符串相同。
num_input_programs specifies the number of programs in array referenced by input_programs.
num_input_programs指定input_programs引用的数组中的程序数。
input_programs is an array of program objects that are compiled binaries or libraries that are to be linked to create the program executable. For each device in device_list or if device_list is NULL the list of devices associated with context, the following cases occur:
inputprograms是一组程序对象，这些对象是编译后的二进制文件或库，要链接它们以创建程序可执行文件。对于device_list中的每个设备，或者如果device_list为NULL，则与上下文关联的设备列表将出现以下情况：
- All programs specified by input_programs contain a compiled binary or library for the device. In this case, a link is performed to generate a program executable for this device.
- input_programs指定的所有程序都包含设备的编译二进制文件或库。在这种情况下，执行链接以生成可用于此设备的程序。
- None of the programs contain a compiled binary or library for that device. In this case, no link is performed and there will be no program executable generated for this device.
- 这些程序都不包含该设备的编译二进制文件或库。在这种情况下，不会执行任何链接，也不会为此设备生成可执行程序。
- All other cases will return a CL_INVALID_OPERATION error.
- 所有其他情况都将返回CL_INVALID_OPERATION错误。
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).
pfn_notify是一个指向通知例程的函数指针。通知例程是一个回调函数，应用程序可以注册它，当程序可执行文件构建完成（成功或失败）时，它将被调用。
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。

If pfn_notify is not NULL, clLinkProgram does not need to wait for the linker to complete, and can return immediately once the linking operation can begin. Once the linker has completed, the pfn_notify callback function is called which returns the program object returned by clLinkProgram. Any state changes of the program object that result from calling clLinkProgram (e.g. link status or log) will be observable from this callback function. 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不为NULL，则clLinkProgram不需要等待链接器完成，并且可以在链接操作开始后立即返回。链接器完成后，调用pfn_notify回调函数，该函数返回clLinkProgram返回的程序对象。调用clLinkProgram导致的程序对象的任何状态更改（例如链接状态或日志）都可以从该回调函数中观察到。OpenCL实现可以异步调用此回调函数。应用程序有责任确保回调函数是线程安全的。

If pfn_notify is NULL, clLinkProgram does not return until the linker has completed.

如果pfn_notify为NULL，则clLinkProgram在链接器完成之前不会返回。

clLinkProgram creates a new program object which contains the library or executable. The library or executable binary can be queried using clGetProgramInfo(program, CL_PROGRAM_BINARIES, …) and can be specified to clCreateProgramWithBinary to create a new program object.

clLinkProgram创建一个包含库或可执行文件的新程序对象。可以使用clGetProgramInfo（程序，CL_PROGRAM_BINARIES，…）查询库或可执行二进制文件，并可以将其指定给clCreateProgramWithBinary以创建新的程序对象。

The devices associated with the returned program object will be the list of devices specified by device_list or if device_list is NULL it will be the list of devices associated with context.

与返回的程序对象关联的设备将是device_list指定的设备列表，或者如果device_list为NULL，则将是与context关联的设备列表。

The linking operation can begin if the context, list of devices, input programs and linker options specified are all valid and appropriate host and device resources needed to perform the link are available. If the linking operation can begin, clLinkProgram returns a valid non-zero program object.

如果指定的上下文、设备列表、输入程序和链接器选项都有效，并且执行链接所需的适当主机和设备资源可用，则可以开始链接操作。如果链接操作可以开始，clLinkProgram将返回一个有效的非零程序对象。

If pfn_notify is NULL, errcode_ret will be set to CL_SUCCESS if the link operation was successful and CL_LINK_PROGRAM_FAILURE if there is a failure to link the compiled binaries and/or libraries.

如果pfn_notify为NULL，如果链接操作成功，则errcode_ret将设置为CL_SUCCESS，如果链接编译的二进制文件或库失败，则errcode_ret将被设置为CL_LINK_PROGRAM_FAILURE。

If pfn_notify is not NULL, clLinkProgram does not have to wait until the linker to complete and can return CL_SUCCESS in errcode_ret if the linking operation can begin. The pfn_notify callback function will return a CL_SUCCESS or CL_LINK_PROGRAM_FAILURE if the linking operation was successful or not.

如果pfn_notify不为NULL，clLinkProgram不必等到链接器完成，如果链接操作可以开始，它可以在errcode_ret中返回CL_SUCCESS。如果链接操作成功或失败，pfn_notify回调函数将返回CL_SUCCESS或CL_LINK_PROGRAM_FAILURE。

Otherwise clLinkProgram returns a NULL program object with an appropriate error in errcode_ret. The application should query the linker status of this program object to check if the link was successful or not. The list of errors that can be returned are:

否则，clLinkProgram将返回一个NULL程序对象，并在errcode_ret中显示相应的错误。应用程序应查询此程序对象的链接器状态，以检查链接是否成功。可以返回的错误列表包括：

CL_INVALID_CONTEXT if context is not a valid context.
如果context不是有效的上下文，则返回CL_INVALID_CONTEXT。
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 num_input_programs is zero and input_programs is NULL or if num_input_programs is zero and input_programs is not NULL or if num_input_programs is not zero and input_programs is NULL.
如果num_input_programs为零且input_programs是NULL，或者如果num_input _programs也为零且input _programs不为NULL，或者num_input programs也不为零且input _programs也是NULL，则CL_INVALID_VALUE。
CL_INVALID_PROGRAM if programs specified in input_programs are not valid program objects.
CL_INVALID_PROGRAM，如果input_programs中指定的程序不是有效的程序对象。
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 context.
CL_INVALID_DEVICE，如果device_list中的任何设备不在与context关联的设备列表中。
CL_INVALID_LINKER_OPTIONS if the linker options specified by options are invalid.
如果选项指定的链接器选项无效，则返回CL_INVALID_LINKER_OPTIONS。
CL_INVALID_OPERATION if the compilation or build of a program executable for any of the devices listed in device_list by a previous call to clCompileProgram or clBuildProgram for program has not completed.
CL_INVALID_OPERATION，如果之前对程序的clCompileProgram或clBuildProgram的调用未完成对device_list中列出的任何设备的可执行程序的编译或构建。
CL_INVALID_OPERATION if the rules for devices containing compiled binaries or libraries as described in input_programs argument above are not followed.
如果不遵守上述input_programs参数中描述的包含已编译二进制文件或库的设备的规则，则返回CL_INVALID_OPERATION。
CL_LINKER_NOT_AVAILABLE if a linker is not available, i.e. CL_DEVICE_LINKER_AVAILABLE specified in the Device Queries table is set to CL_FALSE.
CL_LINKER_NOT_AVAILABLE如果链接器不可用，即设备查询表中指定的CLD_LINKER_AVAILABLE设置为CL_FALSE。
CL_LINK_PROGRAM_FAILURE if there is a failure to link the compiled binaries and/or libraries.
CL_LINK_PROGRAM_FAILURE，如果链接已编译的二进制文件或库失败。
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实现所需的资源。