OpenCL™规范 5.5.5. 迁移内存对象

最新推荐文章于 2024-07-28 15:28:07 发布

꧁白杨树下꧂

最新推荐文章于 2024-07-28 15:28:07 发布

阅读量50

点赞数

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

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

版权

openCL 专栏收录该内容

162 篇文章 12 订阅

订阅专栏

5.5.5. Migrating Memory Objects

5.5.5. 迁移内存对象

Migrating memory objects is missing before version 1.2.

1.2版本之前缺少迁移内存对象。

This section describes a mechanism for assigning which device an OpenCL memory object resides. A user may wish to have more explicit control over the location of their memory objects on creation. This could be used to:

本节描述了一种分配OpenCL内存对象所在设备的机制。用户可能希望在创建时对其存储器对象的位置具有更明确的控制。这可用于：

Ensure that an object is allocated on a specific device prior to usage.
在使用之前，请确保在特定设备上分配了对象。
Preemptively migrate an object from one device to another.
先发制人地将对象从一个设备迁移到另一个设备。

To enqueue a command to indicate which device a set of memory objects should be associated with, call the function

要将指示一组内存对象应与哪个设备关联的命令排入队列，请调用函数

// Provided by CL_VERSION_1_2
cl_int clEnqueueMigrateMemObjects(
    cl_command_queue command_queue,
    cl_uint num_mem_objects,
    const cl_mem* mem_objects,
    cl_mem_migration_flags flags,
    cl_uint num_events_in_wait_list,
    const cl_event* event_wait_list,
    cl_event* event);

clEnqueueMigrateMemObjects is missing before version 1.2.

clEnqueueMigrateMemoObjects在版本1.2之前丢失。

command_queue is a valid host command-queue. The specified set of memory objects in mem_objects will be migrated to the OpenCL device associated with command_queue or to the host if the CL_MIGRATE_MEM_OBJECT_HOST has been specified.
command_queue是一个有效的主机命令队列。mem_objects中指定的内存对象集将迁移到与command_queue关联的OpenCL设备，或者如果已指定CL_MIGRATE_MEM_OBJECT_HOST，则迁移到主机。
num_mem_objects is the number of memory objects specified in mem_objects.
num_mem_objects是在mem_objects中指定的内存对象数。
mem_objects is a pointer to a list of memory objects.
mem_objects是指向内存对象列表的指针。
flags is a bit-field that is used to specify migration options. The Memory Migration Flags describes the possible values for flags.
flags是一个用于指定迁移选项的位字段。内存迁移标志描述了标志的可能值。
event_wait_list and num_events_in_wait_list specify events that need to complete before this particular command can be executed. If event_wait_list is NULL, then this particular command does not wait on any event to complete. If event_wait_list is NULL, num_events_in_wait_list must be 0. If event_wait_list is not NULL, the list of events pointed to by event_wait_list must be valid and num_events_in_wait_list must be greater than 0. The events specified in event_wait_list act as synchronization points. The context associated with events in event_wait_list and command_queue must be the same. The memory associated with event_wait_list can be reused or freed after the function returns.
event_wait_list和num_events_in_wait_list指定在执行此特定命令之前需要完成的事件。如果event_wait_list为NULL，则此特定命令不等待任何事件完成。如果event_wait_list为NULL，则num_events_in_wait_list必须为0。如果event_wait_list不为NULL，则event_wail_list指向的事件列表必须有效，并且num_events_in_wait_list必须大于0。event_wait_list中指定的事件充当同步点。与event_wait_list和command_queue中的事件关联的上下文必须相同。函数返回后，可以重用或释放与event_wait_list关联的内存。
event returns an event object that identifies this command and can be used to query or queue a wait for this command to complete. If event is NULL or the enqueue is unsuccessful, no event will be created and therefore it will not be possible to query the status of this command or to wait for this command to complete. If event_wait_list and event are not NULL, event must not refer to an element of the event_wait_list array.
event返回一个标识此命令的事件对象，可用于查询或排队等待此命令完成。如果事件为NULL或排队不成功，则不会创建任何事件，因此无法查询此命令的状态或等待此命令完成。如果event_wait_list和event不为NULL，则event不能引用event_wail_list数组的元素。

Table 37. List of supported migration flags by clEnqueueMigrateMemObjects

表37 clEnqueueMigrateMemoObjects支持的迁移标志列表
Memory Migration Flags 内存迁移标志	Description 描述
CL_MIGRATE_MEM_OBJECT_HOST missing before version 1.2.	This flag indicates that the specified set of memory objects are to be migrated to the host, regardless of the target command-queue. 此标志表示要将指定的内存对象集迁移到主机，而与目标命令队列无关。
CL_MIGRATE_MEM_OBJECT_CONTENT_UNDEFINED missing before version 1.2.	This flag indicates that the contents of the set of memory objects are undefined after migration. The specified set of memory objects are migrated to the device associated with command_queue without incurring the overhead of migrating their contents. 此标志表示迁移后内存对象集的内容未定义。指定的内存对象集被迁移到与command_queue相关联的设备，而不会产生迁移其内容的开销。

Typically, memory objects are implicitly migrated to a device for which enqueued commands, using the memory object, are targeted. clEnqueueMigrateMemObjects allows this migration to be explicitly performed ahead of the dependent commands. This allows a user to preemptively change the association of a memory object, through regular command-queue scheduling, in order to prepare for another upcoming command. This also permits an application to overlap the placement of memory objects with other unrelated operations before these memory objects are needed potentially hiding transfer latencies. Once the event, returned from clEnqueueMigrateMemObjects, has been marked CL_COMPLETE the memory objects specified in mem_objects have been successfully migrated to the device associated with command_queue. The migrated memory object shall remain resident on the device until another command is enqueued that either implicitly or explicitly migrates it away.

通常，内存对象被隐式迁移到使用内存对象的排队命令所针对的设备。clEnqueueMigrateMemoObjects允许在依赖命令之前显式执行此迁移。这允许用户通过常规命令队列调度来抢先更改内存对象的关联，以便为另一个即将到来的命令做准备。这也允许应用程序在需要内存对象之前将内存对象的放置与其他不相关的操作重叠，从而潜在地隐藏传输延迟。从clEnqueueMigrateMemoObjects返回的事件被标记为CL_COMPLETE后，mem_objects中指定的内存对象已成功迁移到与command_queue关联的设备。迁移的内存对象应保持驻留在设备上，直到另一个命令被排队，隐式或显式地将其迁移出去。

clEnqueueMigrateMemObjects can also be used to direct the initial placement of a memory object, after creation, possibly avoiding the initial overhead of instantiating the object on the first enqueued command to use it.

clEnqueueMigrateMemoObjects还可以用于指导内存对象在创建后的初始放置，从而可能避免在使用该对象的第一个排队命令上实例化该对象的初始开销。

The user is responsible for managing the event dependencies, associated with this command, in order to avoid overlapping access to memory objects. Improperly specified event dependencies passed to clEnqueueMigrateMemObjects could result in undefined results.

用户负责管理与此命令相关的事件依赖关系，以避免对内存对象的重复访问。传递给clEnqueueMigrateMemoObjects的指定不正确的事件依赖项可能导致未定义的结果。

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

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

CL_INVALID_COMMAND_QUEUE if command_queue is not a valid host command-queue.
CL_INVALID_COMMAND_QUEUE（如果command_queue不是有效的主机命令队列）。
CL_INVALID_CONTEXT if the context associated with command_queue and memory objects in mem_objects are not the same or if the context associated with command_queue and events in event_wait_list are not the same.
如果与command_queue和mem_objects中的内存对象相关联的上下文不相同，或者与command_ queue和event_wait_list中的事件相关联的语境不相同，则CL_INVALID_CONTEXT。
CL_INVALID_MEM_OBJECT if any of the memory objects in mem_objects is not a valid memory object.
CL_INVALID_MEM_OBJECT，如果mem_objects中的任何内存对象不是有效的内存对象。
CL_INVALID_VALUE if num_mem_objects is zero or if mem_objects is NULL.
如果num_mem_objects为零或mem_objects是NULL，则CL_INVALID_VALUE。
CL_INVALID_VALUE if flags is not 0 or is not any of the values described in the table above.
CL_INVALID_VALUE，如果flags不为0或不是上表中描述的任何值。
CL_INVALID_EVENT_WAIT_LIST if event_wait_list is NULL and num_events_in_wait_list > 0, or event_wait_list is not NULL and num_events_in_wait_list is 0, or if event objects in event_wait_list are not valid events.
CL_INVALID_EVENT_WAIT_LIST如果event_wait_list为NULL且num_events_in_wait_list>0，或者event_wait_list不为NULL且num_events_in_wait_list为0，或者如果event_wait_list中的事件对象不是有效事件。
CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate memory for the specified set of memory objects in mem_objects.
如果为mem_objects中的指定内存对象集分配内存失败，则CL_MEM_OBJECT_ALLOCATION_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实现所需的资源失败。