Name Strings cl_ext_migrate_memobject Contributors Yariv Aridor Greg Bellows Aaftab Munshi Barry Minor Ian Ollmann Amit Rao Ofer Rosenberg Contact Greg Bellows, gbello 'at' us 'dot. ibm 'dot' com IP Status No known IP issues Version Version 1, June 8, 2010 Number OpenCL Extension #10 Status Approved by contributing members Extension Type OpenCL device extension Dependencies None Overview This extension defines a mechanism for assigning which device an OpenCL memory object resides. Header File Extension interfaces and constants defined in cl_ext.h New Procedures and Functions cl_int clEnqueueMigrateMemObjectEXT( cl_command_queue command_queue, cl_uint num_mem_objects, const cl_mem *mem_objects, cl_mem_migration_flags_ext flags, cl_uint num_events_in_wait_list, const cl_event *event_wait_list, cl_event *event); New Types typedef cl_bitfield cl_mem_migration_flags_ext; New Tokens Besides a value of zero, the following cl_mem_migration_flags_ext values are allowed: CL_MIGRATE_MEM_OBJECT_HOST_EXT 0x1 Returned in the parameter of the clGetEventInfo when is CL_EVENT_COMMAND_TYPE: CL_COMMAND_MIGRATE_MEM_OBJECT_EXT 0x4040 Additions to Section 5.2 (Memory Objects, Buffers, Images...) "clEnqueueMigrateMemObjectEXT provides the application with a way to indicate which device a set of memory objects should be associated. Typically, memory objects are implicitly migrated to a device for which enqueued commands, using the memory object, are targeted. clEnqueueMigrateMemObjectEXT allows this migration to be explicitly performed ahead of the dependent commands. This permits an application to overlap the placement of memory objects with other unrelated operations. Once the OpenCL event, returned from clEnqueueMigrateMemObject, 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. As well, clEnqueueMigrateMemObjectEXT can 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. 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 clEnqueueMigrateMemObject could result in undefined results. cl_int clEnqueueMigrateMemObjectEXT(cl_command_queue command_queue, cl_uint num_mem_objects, const cl_mem *mem_objects, cl_mem_migration_flags_ext flags, cl_uint num_events_in_wait_list, const cl_event *event_wait_list, cl_event *event); is a valid command queue. The specified set of memory objects in will be migrated to the OpenCL device associated with or to the application host if the CL_MIGRATE_MEM_OBJECT_HOST_EXT flag has been specified. is the number of memory objects specified in the mem_objects argument. is a pointer to a list of valid memory objects. is a bitfield that is used to specify migration options. Table 2.1 describes the possible values for flags: -------------------------------------------------------------------- flags description ----------- ---------------------------------- CL_MIGRATE_MEM_OBJECT_HOST_EXT This flag specifies that the specified set of memory objects are to be migrated to the host, regardless of the target command queue. -------------------------------------------------------------------- Table 2.1 - Supported cl_mem_migration_flags_ext flags and specify events that need to complete before this particular command can be executed. If is NULL, then this particular command does not wait on any event to complete. If is NULL, must be 0. If is not NULL, the list of events pointed to by must be valid and must be greater than 0. The events specified in act as synchronization points. The context associated with events in and must be the same. returns an event object that identifies this particular command and can be used to query or queue a wait for this particular command to complete. can be NULL in which case it will not be possible for the application to query the status of this command or queue a wait for this command to complete. clEnqueueMigrateMemObjectEXT returns CL_SUCCESS if the operation was successfully queued. Otherwise, it returns one of the following errors: - CL_INVALID_COMMAND_QUEUE if is not a valid command queue. - CL_INVALID_CONTEXT if the context associated with and memory objects in are not the same or if the context associated with and events in are not the same. - CL_INVALID_VALUE if is zero. - CL_INVALID_VALUE if is NULL. - CL_INVALID_VALUE if flags is not 0 or CL_MIGRATE_MEM_OBJECT_HOST_EXT. - CL_INVALID_MEM_OBJECT if contains an invalid memory object. - CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate memory for the specified set of memory objects in . - CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device. - CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host. - CL_INVALID_EVENT_WAIT_LIST if is NULL and > 0, or is not NULL and is 0, or if event objects in are not valid events. "