OpenCL™规范 4.4. 上下文

꧁白杨树下꧂

于 2024-03-12 14:37:52 发布

阅读量29

点赞数

分类专栏： openCL 文章标签： opencl

原文链接：https://registry.khronos.org/OpenCL/specs/3.0-unified/html/OpenCL_API.html#_contexts

版权

openCL 专栏收录该内容

82 篇文章 2 订阅

订阅专栏

4.4. Contexts

4.4. 上下文

To create an OpenCL context, call the function:

要创建OpenCL上下文，请调用函数：

cl_context clCreateContext(
    const cl_context_properties* properties,
    cl_uint num_devices,
    const cl_device_id* devices,
    void (CL_CALLBACK* pfn_notify)(const char* errinfo, const void* private_info, size_t cb, void* user_data),
    void* user_data,
    cl_int* errcode_ret);

properties specifies a list of context property names and their corresponding values. Each property name is immediately followed by the corresponding desired value. The list is terminated with 0. The list of supported properties is described in the Context Properties table. properties can be NULL in which case the platform that is selected is implementation-defined.
属性指定上下文属性名称及其相应值的列表。每个属性名称后面紧跟着相应的所需值。列表以0终止。支持的属性列表在上下文属性表中进行了描述。属性可以为NULL，在这种情况下，所选的平台是由实现定义的。
num_devices is the number of devices specified in the devices argument.
num_devices是在devices参数中指定的设备数。
devices is a pointer to a list of unique devices returned by clGetDeviceIDs or sub-devices created by clCreateSubDevices for a platform. [11]
devices是指向clGetDeviceID返回的唯一设备列表或clCreateSubDevices为平台创建的子设备的指针。 [11]
pfn_notify is a callback function that can be registered by the application. This callback function will be used by the OpenCL implementation to report information on errors during context creation as well as errors that occur at runtime in this context. 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. If pfn_notify is NULL, no callback function is registered.
pfn_notify是一个回调函数，可以由应用程序注册。OpenCL实现将使用此回调函数来报告上下文创建期间的错误信息以及运行时在此上下文中发生的错误。这个回调函数可以由OpenCL实现异步调用。应用程序有责任确保回调函数是线程安全的。如果pfn_notify为NULL，则不会注册回调函数。
user_data will be passed as the user_data argument when pfn_notify is called. user_data can be NULL.
当调用pfn_notify时，user_data将作为user_data参数传递。user_data可以为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 parameters to the callback function pfn_notify are:

回调函数pfn_notify的参数为：

errinfo is a pointer to an error string.
errinfo是一个指向错误字符串的指针。
private_info and cb represent a pointer to binary data that is returned by the OpenCL implementation that can be used to log additional information helpful in debugging the error.
private_info和cb表示指向OpenCL实现返回的二进制数据的指针，可用于记录有助于调试错误的附加信息。
user_data is a pointer to user supplied data.
user_data是指向用户提供的数据的指针。

Contexts are used by the OpenCL runtime for managing objects such as command-queues, memory, program and kernel objects and for executing kernels on one or more devices specified in the context.

上下文由OpenCL运行时用于管理诸如命令队列、内存、程序和内核对象之类的对象，以及用于在上下文中指定的一个或多个设备上执行内核。

Table 7. List of supported context creation properties by clCreateContext

表7 clCreateContext支持的上下文创建属性列表
Context Property 上下文属性	Property Value 属性值	Description 描述
CL_CONTEXT_PLATFORM	`cl_platform_id`	Specifies the platform to use. 指定要使用的平台。
CL_CONTEXT_INTEROP_USER_SYNC missing before version 1.2.	`cl_bool`	Specifies whether the user is responsible for synchronization between OpenCL and other APIs. Please refer to the specific sections in the OpenCL Extension Specification that describe sharing with other APIs for restrictions on using this flag. 指定用户是否负责OpenCL和其他API之间的同步。有关使用此标志的限制，请参阅OpenCL扩展规范中描述与其他API共享的特定章节。 If CL_CONTEXT_INTEROP_USER_SYNC is not specified, a default of CL_FALSE is assumed. 如果未指定CL_CONTEXT_INTEROP_USER_SYNC，则假定默认值为CL_FALSE。

There are a number of cases where error notifications need to be delivered due to an error that occurs outside a context. Such notifications may not be delivered through the pfn_notify callback. Where these notifications go is implementation-defined.

在许多情况下，由于上下文之外发生的错误，需要传递错误通知。这样的通知可能不会通过pfn_notify回调来传递。这些通知的去向是由实现定义的。

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

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

CL_INVALID_PLATFORM if properties is NULL and no platform could be selected or if platform value specified in properties is not a valid platform.
CL_INVALID_PLATFORM如果属性为NULL且无法选择任何平台，或者如果属性中指定的平台值不是有效的平台。
CL_INVALID_PROPERTY if context property name in properties is not a supported property name, if the value specified for a supported property name is not valid, or if the same property name is specified more than once. This error code is missing before version 1.1.
CL_INVALID_PROPERTY如果属性中的上下文属性名称不是支持的属性名称，如果为支持的属性名指定的值无效，或者如果多次指定相同的属性名。1.1版本之前缺少此错误代码。
CL_INVALID_VALUE if devices is NULL.
CL_INVALID_VALUE（如果设备为NULL）。
CL_INVALID_VALUE if num_devices is equal to zero.
如果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 devices is not a valid device.
CL_INVALID_DEVICE（如果设备中的任何设备不是有效设备）。
CL_DEVICE_NOT_AVAILABLE if a device in devices is currently not available even though the device was returned by clGetDeviceIDs.
CL_DEVICE_NOT_AVAILABLE如果设备中的某个设备当前不可用，即使该设备是由clGetDeviceID返回的。
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实现所需的资源失败。

It is possible that a device(s) becomes unavailable after a context and command-queues that use this device(s) have been created and commands have been queued to command-queues. In this case the behavior of OpenCL API calls that use this context (and command-queues) are considered to be implementation-defined. The user callback function, if specified, when the context is created can be used to record appropriate information in the errinfo, private_info arguments passed to the callback function when the device becomes unavailable.

在创建了使用该设备的上下文和命令队列，并且命令已排入命令队列后，该设备可能变得不可用。在这种情况下，使用此上下文（和命令队列）的OpenCL API调用的行为被认为是实现定义的。如果指定了用户回调函数，则在创建上下文时，可以使用该函数在设备不可用时传递给回调函数的errinfo、private_info参数中记录适当的信息。

To create an OpenCL context from a specific device type [12], call the function:

要从特定的设备类型[12]创建OpenCL上下文，请调用函数：

cl_context clCreateContextFromType(
    const cl_context_properties* properties,
    cl_device_type device_type,
    void (CL_CALLBACK* pfn_notify)(const char* errinfo, const void* private_info, size_t cb, void* user_data),
    void* user_data,
    cl_int* errcode_ret);

properties specifies a list of context property names and their corresponding values. Each property name is immediately followed by the corresponding desired value. The list of supported properties is described in the Context Properties table. properties can also be NULL in which case the platform that is selected is implementation-defined.
属性指定上下文属性名称及其相应值的列表。每个属性名称后面紧跟着相应的所需值。支持的属性列表在上下文属性表中进行了描述。属性也可以为NULL，在这种情况下，所选的平台是由实现定义的。
device_type is a bit-field that identifies the type of device and is described in the Device Types table.
device_type是一个位字段，用于标识设备类型，并在“设备类型”表中进行了描述。
pfn_notify and user_data are described in clCreateContext.
pfn_notify和user_data在clCreateContext中进行了描述。
errcode_ret will return an appropriate error code. If errcode_ret is NULL, no error code is returned.
errcode_ret将返回相应的错误代码。如果errcode_ret为NULL，则不会返回任何错误代码。

Only devices that are returned by clGetDeviceIDs for device_type are used to create the context. The context does not reference any sub-devices that may have been created from these devices.

只有设备类型的clGetDeviceID返回的设备才能用于创建上下文。上下文不引用可能已经从这些设备创建的任何子设备。

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

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

CL_INVALID_PLATFORM if properties is NULL and no platform could be selected or if platform value specified in properties is not a valid platform.
CL_INVALID_PLATFORM如果属性为NULL且无法选择任何平台，或者如果属性中指定的平台值不是有效的平台。
CL_INVALID_PROPERTY if context property name in properties is not a supported property name, if the value specified for a supported property name is not valid, or if the same property name is specified more than once. This error code is missing before version 1.1.
CL_INVALID_PROPERTY如果属性中的上下文属性名称不是支持的属性名称，如果为支持的属性名指定的值无效，或者如果多次指定相同的属性名。1.1版本之前缺少此错误代码。
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_TYPE if device_type is not a valid value.
CL_INVALID_DEVICE_TYPE（如果设备类型不是有效值）。
CL_DEVICE_NOT_AVAILABLE if no devices that match device_type and property values specified in properties are currently available.
CL_DEVICE_NOT_AVAILABLE（如果当前没有与属性中指定的DEVICE_type和属性值匹配的设备）。
CL_DEVICE_NOT_FOUND if no devices that match device_type and property values specified in properties were found.
如果找不到与属性中指定的device_type 和属性值匹配的设备，则为CL_DEVICE_NOT_FOUND。
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 retain a context, call the function:

要保留上下文，请调用函数：

cl_int clRetainContext(
    cl_context context);

context specifies the OpenCL context to retain.
context指定要保留的OpenCL上下文。

clRetainContext increments the context reference count.

clRetainContext递增上下文引用计数。

clCreateContext and clCreateContextFromType perform an implicit retain. This is very helpful for 3rd party libraries, which typically get a context passed to them by the application. However, it is possible that the application may delete the context without informing the library. Allowing functions to attach to (i.e. retain) and release a context solves the problem of a context being used by a library no longer being valid.

clCreateContext和clCreateContextFromType执行隐式保留。这对第三方库非常有帮助，因为第三方程序库通常会获得应用程序传递给它们的上下文。但是，应用程序可能会在不通知库的情况下删除上下文。允许函数附加（即保留）和释放上下文解决了库使用的上下文不再有效的问题。

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

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

CL_INVALID_CONTEXT if context is not a valid OpenCL context.
CL_INVALID_CONTEXT（如果上下文不是有效的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 release a context, call the function:

要释放上下文，请调用函数：

cl_int clReleaseContext(
    cl_context context);

context specifies the OpenCL context to release.
context指定要释放的OpenCL上下文。

clReleaseContext decrements the context reference count. After the reference count becomes zero and all the objects attached to context (such as memory objects, command-queues) are released, the context is deleted. Using this function to release a reference that was not obtained by creating the object or by calling clRetainContext causes undefined behavior.

clReleaseContext减少上下文引用计数。在引用计数变为零并且所有附加到上下文的对象（如内存对象、命令队列）都被释放后，上下文将被删除。使用此函数释放不是通过创建对象或调用clRetainContext获得的引用会导致未定义的行为。

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

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

CL_INVALID_CONTEXT if context is not a valid OpenCL context.
CL_INVALID_CONTEXT（如果上下文不是有效的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 query information about a context, call the function:

要查询有关上下文的信息，请调用函数：

cl_int clGetContextInfo(
    cl_context context,
    cl_context_info param_name,
    size_t param_value_size,
    void* param_value,
    size_t* param_value_size_ret);

context specifies the OpenCL context being queried.
context指定要查询的OpenCL上下文。
param_name is an enumeration constant that specifies the information to query.
param_name是一个枚举常量，用于指定要查询的信息。
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 specifies the size in bytes of memory pointed to by param_value. This size must be greater than or equal to the size of return type as described in the Context Attributes 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，则忽略它。

The list of supported param_name values and the information returned in param_value by clGetContextInfo is described in the Context Attributes table.

上下文属性表中描述了支持的param_name值列表以及clGetContextInfo在param_value中返回的信息。

Table 8. List of supported param_names by clGetContextInfo

表8 clGetContextInfo支持的参数名称列表
Context Info 上下文信息	Return Type 返回类型	Description 描述
CL_CONTEXT_REFERENCE_COUNT [13]	`cl_uint`	Return the context reference count. 返回上下文引用计数。
CL_CONTEXT_NUM_DEVICES missing before version 1.1.	`cl_uint`	Return the number of devices in context. 返回上下文中的设备数量。
CL_CONTEXT_DEVICES	`cl_device_id`[]	Return the list of devices and sub-devices in context. 返回上下文中设备和子设备的列表。
CL_CONTEXT_PROPERTIES	`cl_context_properties`[]	Return the properties argument specified in clCreateContext or clCreateContextFromType. 返回在clCreateContext或clCreateContextFromType中指定的属性参数。 If the properties argument specified in clCreateContext or clCreateContextFromType used to create context was not `NULL`, the implementation must return the values specified in the properties argument in the same order and without including additional properties. 如果用于创建上下文的clCreateContext或clCreateContextFromType中指定的属性参数不是NULL，则实现必须以相同的顺序返回属性参数中指定的值，并且不包括其他属性。 If the properties argument specified in clCreateContext or clCreateContextFromType used to create context was `NULL`, the implementation must return param_value_size_ret equal to 0, indicating that there are no properties to be returned. 如果在用于创建上下文的clCreateContext或clCreateContextFromType中指定的属性参数为NULL，则该实现必须返回等于0的param_value_size_ret，表示没有要返回的属性。

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

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

CL_INVALID_CONTEXT if context is not a valid context.
CL_INVALID_CONTEXT（如果上下文不是有效上下文）。
CL_INVALID_VALUE if param_name is not one of the supported values or if size in bytes specified by param_value_size is < size of return type as specified in the Context Attributes table and param_value is not a NULL value.
如果param_name不是支持的值之一，或者param_value_size指定的字节大小小于上下文属性表中指定的返回类型的大小，并且param_value不是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 register a callback function with a context that is called when the context is destroyed, call the function

若要将回调函数注册到上下文被破坏时调用的上下文中，请调用

cl_int clSetContextDestructorCallback(
    cl_context context,
    void (CL_CALLBACK* pfn_notify)(cl_context context, void* user_data),
    void* user_data);

clSetContextDestructorCallback is missing before version 3.0.

版本3.0之前缺少clSetContextDestructorCallback。

context specifies the OpenCL context to register the callback to.
context指定要将回调注册到的OpenCL上下文。
pfn_notify is the callback function to register. 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. The parameters to this callback function are:

pfn_notify是要注册的回调函数。这个回调函数可以由OpenCL实现异步调用。应用程序有责任确保回调函数是线程安全的。此回调函数的参数为：
- context is the OpenCL context being deleted. When the callback function is called by the implementation, this context is no longer valid. context is only provided for reference purposes.
- context是要删除的OpenCL上下文。当实现调用回调函数时，此上下文不再有效。上下文仅供参考。
- user_data is a pointer to user-supplied data.
- user_data是指向用户提供的数据的指针。
user_data will be passed as the user_data argument when pfn_notify is called. user_data can be NULL.
当调用pfn_notify时，user_data将作为user_data参数传递。user_data可以为NULL。

Each call to clSetContextDestructorCallback registers the specified callback function on a destructor callback stack associated with context. The registered callback functions are called in the reverse order in which they were registered. If a context callback function was specified when context was created, it will not be called after any context destructor callback is called. Therefore, the context destructor callback provides a mechanism for an application to safely re-use or free any user_data specified for the context callback function when context was created.

每次调用clSetContextDestructorCallback都会在与上下文关联的析构函数回调堆栈上注册指定的回调函数。已注册的回调函数的调用顺序与它们的注册顺序相反。如果在创建上下文时指定了上下文回调函数，则在调用任何上下文析构函数回调后都不会调用该函数。因此，上下文析构函数回调为应用程序提供了一种机制，以便在创建上下文时安全地重用或释放为上下文回调函数指定的任何user_data。

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

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

CL_INVALID_CONTEXT if context is not a valid context.
CL_INVALID_CONTEXT（如果上下文不是有效上下文）。
CL_INVALID_VALUE if pfn_notify is NULL.
如果pfn_notify为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实现所需的资源失败。

꧁白杨树下꧂

关注

0
点赞
踩
0

收藏

觉得还不错? 一键收藏
0
评论
OpenCL™规范 4.4. 上下文

如果在用于创建上下文的clCreateContext或clCreateContextFromType中指定的属性参数为NULL，则该实现必须返回等于0的param_value_size_ret，表示没有要返回的属性。CL_INVALID_PROPERTY如果属性中的上下文属性名称不是支持的属性名称，如果为支持的属性名指定的值无效，或者如果多次指定相同的属性名。CL_INVALID_PROPERTY如果属性中的上下文属性名称不是支持的属性名称，如果为支持的属性名指定的值无效，或者如果多次指定相同的属性名。
复制链接

扫一扫