OpenCL™规范 5.8.1. 创建程序对象

5.8.1. Creating Program Objects

5.8.1. 创建程序对象

To creates a program object for a context and load source code into that object, call the function

要为上下文创建程序对象并将源代码加载到该对象中，请调用函数

// Provided by CL_VERSION_1_0
cl_program clCreateProgramWithSource(
    cl_context context,
    cl_uint count,
    const char** strings,
    const size_t* lengths,
    cl_int* errcode_ret);

• context must be a valid OpenCL context.

• context必须是有效的OpenCL上下文。

• strings is an array of count pointers to optionally null-terminated character strings that make up the source code.

• strings是一个计数指针数组，指向构成源代码的可选以null结尾的字符串。

• lengths argument is an array with the number of chars in each string (the string length). If an element in lengths is zero, its accompanying string is null-terminated. If lengths is NULL, all strings in the strings argument are considered null-terminated. Any length value passed in that is greater than zero excludes the null terminator in its count.

• lengths参数是一个数组，其中包含每个字符串中的字符数（字符串长度）。如果长度为零的元素，则其附带的字符串以null结尾。如果lengths为NULL，则字符串参数中的所有字符串都被视为以NULL结尾。传入的任何大于零的长度值都会在其计数中排除空终止符。

• errcode_ret will return an appropriate error code. If errcode_ret is NULL, no error code is returned.

• errcode_ret将返回适当的错误代码。如果errcode_ret为NULL，则不返回错误代码。

The source code specified by strings will be loaded into the program object.

由strings指定的源代码将被加载到程序对象中。

The devices associated with the program object are the devices associated with context. The source code specified by strings is either an OpenCL C program source, header or implementation-defined source for custom devices that support an online compiler. OpenCL C++ is not supported as an online-compiled kernel language through this interface.

与程序对象关联的设备是与context关联的设备。由字符串指定的源代码是OpenCL C程序源代码、头文件或支持在线编译器的自定义设备的实现定义源代码。OpenCL C++不支持通过此接口作为在线编译的内核语言。

clCreateProgramWithSource returns a valid non-zero program object and errcode_ret is set to CL_SUCCESS if the program object is created successfully. Otherwise, it returns a NULL value with one of the following error values returned in errcode_ret:

clCreateProgramWithSource返回一个有效的非零程序对象，如果程序对象创建成功，则errcode_ret设置为CL_SUCCESS。否则，它将返回一个NULL值，并在errcode_ret中返回以下错误值之一：

• CL_INVALID_CONTEXT if context is not a valid context.

• 如果context不是有效的上下文，则返回CL_INVALID_CONTEXT。

• CL_INVALID_VALUE if count is zero or if strings or any entry in strings is NULL.

• 如果count为零或strings或strings中的任何条目为NULL，则返回CL_INVALID_VALUE。

• 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 create a program object for a context and load code in an intermediate language into that object, call the function

要为上下文创建程序对象并将中间语言的代码加载到该对象中，请调用函数

// Provided by CL_VERSION_2_1
cl_program clCreateProgramWithIL(
    cl_context context,
    const void* il,
    size_t length,
    cl_int* errcode_ret);

clCreateProgramWithIL is missing before version 2.1. 2.1版本之前缺少clCreateProgramWithIL。

or the equivalent

或等效函数

// Provided by cl_khr_il_program
cl_program clCreateProgramWithILKHR(
    cl_context context,
    const void* il,
    size_t length,
    cl_int* errcode_ret);

clCreateProgramWithILKHR is provided by the cl_khr_il_program extension. clCreateProgramWithILKHR由cl_khr_il_program扩展提供。

• context must be a valid OpenCL context.

• context必须是有效的OpenCL上下文。

• il is a pointer to a block of memory containing SPIR-V or an implementation-defined intermediate language.

• il是指向包含SPIR-V或实现定义的中间语言的内存块的指针。

• length is the length of the block pointed to by il.

• length是il指向的块的长度。

• errcode_ret will return an appropriate error code. If errcode_ret is NULL, no error code is returned.

• errcode_ret将返回适当的错误代码。如果errcode_ret为NULL，则不返回错误代码。

The intermediate language pointed to by il and with length in bytes length will be loaded into the program object. The devices associated with the program object are the devices associated with context.

由il指向的中间语言，其长度以字节为单位，将被加载到程序对象中。与程序对象关联的设备是与context关联的设备。

clCreateProgramWithIL returns a valid non-zero program object and errcode_ret is set to CL_SUCCESS if the program object is created successfully. Otherwise, it returns a NULL value with one of the following error values returned in errcode_ret:

clCreateProgramWithIL返回一个有效的非零程序对象，如果程序对象创建成功，则errcode_ret设置为CL_SUCCESS。否则，它将返回一个NULL值，并在errcode_ret中返回以下错误值之一：

• CL_INVALID_CONTEXT if context is not a valid context.

• 如果context不是有效的上下文，则返回CL_INVALID_CONTEXT。

• CL_INVALID_OPERATION if no devices in context support intermediate language programs.

• CL_INVALID_OPERATION（如果context中没有设备支持中间语言程序）。

• CL_INVALID_VALUE if il is NULL or if length is zero.

• 如果il为NULL或长度为零，则为CL_INVALID_VALUE。

• CL_INVALID_VALUE if the length-byte block of memory pointed to by il does not contain well-formed intermediate language input that can be consumed by the OpenCL runtime.

• CL_INVALID_VALUE，如果il指向的内存长度字节块不包含OpenCL运行时可以使用的格式良好的中间语言输入。

• 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 create a program object for a context and load binary bits into that object, call the function

要为上下文创建程序对象并将二进制位加载到该对象中，请调用函数

// Provided by CL_VERSION_1_0
cl_program clCreateProgramWithBinary(
    cl_context context,
    cl_uint num_devices,
    const cl_device_id* device_list,
    const size_t* lengths,
    const unsigned char** binaries,
    cl_int* binary_status,
    cl_int* errcode_ret);

• context must be a valid OpenCL context.

• context必须是有效的OpenCL上下文。

• device_list is a pointer to a list of devices that are in context. device_list must be a non-NULL value. The binaries are loaded for devices specified in this list.

• device_list是指向context中设备列表的指针。device_list必须是非NULL值。为此列表中指定的设备加载二进制文件。

• num_devices is the number of devices listed in device_list.

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

• lengths is an array of the size in bytes of the program binaries to be loaded for devices specified by device_list.

• lengths是一个数组，表示要为devicelist指定的设备加载的程序二进制文件的字节大小。

• binaries is an array of pointers to program binaries to be loaded for devices specified by device_list. For each device given by device_list[i], the pointer to the program binary for that device is given by binaries[i] and the length of this corresponding binary is given by lengths[i]. lengths[i] cannot be zero and binaries[i] cannot be a NULL pointer.

• 二进制文件是指向要为device_list指定的设备加载的程序二进制文件的指针数组。对于device_list[i]给出的每个设备，该设备的程序二进制指针由binaries[i]给出，相应二进制文件的长度由lengths[i]给出。lengths[i]不能为零，binaries[i]不能是NULL指针。

• binary_status returns whether the program binary for each device specified in device_list was loaded successfully or not. It is an array of num_devices entries and returns CL_SUCCESS in binary_status[i] if binary was successfully loaded for device specified by device_list[i]; otherwise returns CL_INVALID_VALUE if lengths[i] is zero or if binaries[i] is a NULL value or CL_INVALID_BINARY in binary_status[i] if program binary is not a valid binary for the specified device. If binary_status is NULL, it is ignored.

• ​binary_status返回device_list中指定的每个设备的程序二进制文件是否已成功加载。它是一个num_devices条目的数组，如果成功为device_list[i]指定的设备加载了二进制文件，则返回binary_status[i]中的CL_SUCCESS；否则，如果lengths[i]为零，或者如果binaries[i]为NULL值，则返回CL_INVALID_VALUE；如果程序二进制文件不是指定设备的有效二进制文件，则返回binary_status[i]中的CL_INVALID BINARY。如果binary_status为NULL，则忽略它。

• errcode_ret will return an appropriate error code. If errcode_ret is NULL, no error code is returned.

• errcode_ret将返回适当的错误代码。如果errcode_ret为NULL，则不返回错误代码。

The devices associated with the program object will be the list of devices specified by device_list. The list of devices specified by device_list must be devices associated with context.

与程序对象关联的设备将是device_list指定的设备列表。device_list指定的设备列表必须是与context关联的设备。

The program binaries specified by binaries will be loaded into the program object. They contain bits that describe one of the following:

由二进制文件指定的程序二进制文件将被加载到程序对象中。它们包含描述以下内容之一的位：

• a program executable to be run on the device(s) associated with context,

• 可在与context相关联的设备上运行的程序，

• a compiled program for device(s) associated with context, or

• 与context相关联的设备的编译程序，或

• a library of compiled programs for device(s) associated with context.

• 与context相关联的设备的编译程序库。

The program binary can consist of either or both:

程序二进制文件可以由以下任一项或两项组成：

• Device-specific code and/or,

• 设备特定代码或，

• Implementation-specific intermediate representation (IR) which will be converted to the device-specific code.

• 实现特定的中间表示（IR），它将被转换为设备特定的代码。

OpenCL allows applications to create a program object using the program source or binary and build appropriate program executables. This can be very useful as it allows applications to load program source and then compile and link to generate a program executable online on its first instance for appropriate OpenCL devices in the system. These executables can now be queried and cached by the application. The cached executables can be read and loaded by the application, which can help significantly reduce the application initialization time.

OpenCL允许应用程序使用程序源代码或二进制文件创建程序对象，并构建适当的程序可执行文件。这可能非常有用，因为它允许应用程序加载程序源代码，然后编译和链接以在系统中适当的OpenCL设备的第一个实例上在线生成可执行程序。这些可执行文件现在可以由应用程序查询和缓存。应用程序可以读取和加载缓存的可执行文件，这有助于显著减少应用程序初始化时间。

If the cl_khr_spir extension is supported, clCreateProgramWithBinary can be used to load a SPIR binary. Once a program object has been created from a SPIR binary, clBuildProgram can be called to build a program executable or clCompileProgram can be called to compile the SPIR binary.

​如果支持cl_khr_spir扩展，则可以使用clCreateProgramWithBinary加载SPIR二进制文件。从SPIR二进制文件创建程序对象后，可以调用clBuildProgram来构建程序可执行文件，也可以调用clCompileProgram来编译SPIR二进制程序。

clCreateProgramWithBinary returns a valid non-zero program object and errcode_ret is set to CL_SUCCESS if the program object is created successfully. Otherwise, it returns a NULL value with one of the following error values returned in errcode_ret:

clCreateProgramWithBinary返回一个有效的非零程序对象，如果程序对象创建成功，则errcode_ret设置为CL_SUCCESS。否则，它将返回一个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 or num_devices is zero.

• 如果device_list为NULL或num_devices为零，则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_VALUE if lengths or binaries is NULL or if any entry in lengths[i] is zero or binaries[i] is NULL.

• 如果lengths或binaries为NULL，或者lengths[i]中的任何条目为零或binaries[i]为NULL，则CL_INVALID_VALUE。

• CL_INVALID_BINARY if an invalid program binary was encountered for any device. binary_status will return specific status for each device.

• CL_INVALID_BINARY，如果任何设备遇到无效的程序二进制文件。binary_status将返回每个设备的特定状态。

• 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 create a program object for a context and loads the information related to the built-in kernels into that object, call the function

要为上下文创建程序对象并将与内置内核相关的信息加载到该对象中，请调用以下函数

// Provided by CL_VERSION_1_2
cl_program clCreateProgramWithBuiltInKernels(
    cl_context context,
    cl_uint num_devices,
    const cl_device_id* device_list,
    const char* kernel_names,
    cl_int* errcode_ret);

clCreateProgramWithBuiltInKernels is missing before version 1.2. clCreateProgramWithBuiltInKernels在1.2版本之前缺失。

• context must be a valid OpenCL context.

• context必须是有效的OpenCL上下文。

• num_devices is the number of devices listed in device_list.

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

• device_list is a pointer to a list of devices that are in context. device_list must be a non-NULL value. The built-in kernels are loaded for devices specified in this list.

• device_list是指向context中设备列表的指针。device_list必须是非NULL值。为此列表中指定的设备加载内置内核。

• kernel_names is a semi-colon separated list of built-in kernel names.

• kernel_names是一个以分号分隔的内置内核名称列表。

The devices associated with the program object will be the list of devices specified by device_list. The list of devices specified by device_list must be devices associated with context.

与程序对象关联的设备将是device_list指定的设备列表。device_list指定的设备列表必须是与上下文关联的设备。

clCreateProgramWithBuiltInKernels returns a valid non-zero program object and errcode_ret is set to CL_SUCCESS if the program object is created successfully. Otherwise, it returns a NULL value with one of the following error values returned in errcode_ret:

clCreateProgramWithBuiltInKernels返回一个有效的非零程序对象，如果程序对象创建成功，则errcode_ret设置为CL_SUCCESS。否则，它将返回一个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 or num_devices is zero.

• 如果device_list为NULL或num_devices为零，则CL_INVALID_VALUE。

• CL_INVALID_VALUE if kernel_names is NULL or kernel_names contains a kernel name that is not supported by any of the devices in device_list.

• 如果kernel_names为NULL，或者kernel_names包含device_list中任何设备都不支持的内核名称，则返回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_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实现所需的资源。