Skip to content

Update CL USM Extension from Rev O to Rev Q #1315

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Mar 14, 2020
Merged

Update CL USM Extension from Rev O to Rev Q #1315

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 38 additions & 7 deletions sycl/doc/extensions/USM/cl_intel_unified_shared_memory.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ If you are interested in using this feature in your software product, please let
== Version

Built On: {docdate} +
Revision: O
Revision: Q

== Dependencies

Expand All @@ -76,6 +76,25 @@ Unified Shared Memory provides:
* Fine-grain control over ownership and accessibility of OpenCL allocations, to optimally choose between performance and programmer convenience.
* A simpler programming model, by automatically migrating some allocations between OpenCL devices and the host.

While Unified Shared Memory (USM) shares many features with Shared Virtual Memory (SVM), Unified Shared Memory provides a different mix of capabilities and control.
Specifically:

* The matrix of USM capabilities supports combinations of features beyond the SVM capability queries.

* USM provides explicit control over memory placement and migration by supporting host allocations with wide visibility, devices allocations for best performance, and shared allocations that may migrate between devices and the host.

* USM allocations may be associated with both a device and a context.
The USM allocation APIs support additional memory flags and optional properties to affect how memory is allocated and migrated.

* There is no need for APIs to map or unmap USM allocations, because host accessible USM allocations do not need to be mapped or unmapped to access the contents of a USM allocation on the host.

* An application may indicate that a kernel may access categories of USM allocations indirectly, without passing a set of all indirectly accessed USM allocations to the kernel, improving usability and reducing driver overhead for kernels that access many USM allocations.

* USM adds API functions to query properties of a USM allocation and to provide memory advice for an allocation.

Unified Shared Memory and Shared Virtual Memory can and will coexist for many implementations.
All implementations that support Shared Virtual Memory may support at least some types of Unified Shared Memory.

== New API Functions

[source]
Expand Down Expand Up @@ -107,6 +126,10 @@ cl_int clMemFreeINTEL(
cl_context context,
void* ptr);

cl_int clMemBlockingFreeINTEL(
cl_context context,
void* ptr);

cl_int clGetMemAllocInfoINTEL(
cl_context context,
const void* ptr,
Expand Down Expand Up @@ -570,28 +593,34 @@ Otherwise, `NULL` will be returned, and _errcode_ret_ will be set to one of the

===== Freeing Allocations

The function
The functions

[source]
----
cl_int clMemFreeINTEL(
cl_context context,
void* ptr);

cl_int clMemBlockingFreeINTEL(
cl_context context,
void* ptr);
----

frees a Unified Shared Memory allocation.
free a Unified Shared Memory allocation.

_context_ is a valid OpenCL context used to free the Unified Shared Memory allocation.

_ptr_ is the Unified Shared Memory allocation to free.
It must be a value returned by *clHostMemAllocINTEL*, *clDeviceMemAllocINTEL*, or *clSharedMemAllocINTEL*, or a `NULL` pointer.
If _ptr_ is `NULL` then no action occurs.

Note that *clMemFreeINTEL* does not wait for previously enqueued commands that may be using _ptr_ to finish before freeing _ptr_.
Note that *clMemFreeINTEL* may not wait for previously enqueued commands that may be using _ptr_ to finish before freeing _ptr_.
It is the responsibility of the application to make sure enqueued commands that use _ptr_ are complete before freeing _ptr_.
Applications should take particular care freeing memory allocations with kernels that may access memory indirectly, since a kernel with indirect memory access counts as using all memory allocations of the specified type or types.
To wait for previously enqueued commands to finish that may be using _ptr_ before freeing _ptr_, use the *clMemBlockingFreeINTEL* function instead.

*clMemFreeINTEL* will return `CL_SUCCESS` if the function executes successfully.
Otherwise, it will return one of the following error values:
*clMemFreeINTEL* and *clMemBlockingFreeINTEL* will return `CL_SUCCESS` if the function executes successfully.
Otherwise, they will return one of the following error values:

* `CL_INVALID_CONTEXT` if _context_ is not a valid context.
* `CL_INVALID_VALUE` if _ptr_ is not a value returned by *clHostMemAllocINTEL*, *clDeviceMemAllocINTEL*, *clSharedMemAllocINTEL*, or a `NULL` pointer.
Expand Down Expand Up @@ -986,7 +1015,7 @@ Otherwise, it will return one of the following errors:
* `CL_INVALID_COMMAND_QUEUE` if _command_queue_ is not a valid host command-queue.
* `CL_INVALID_CONTEXT` if the context associated with _command_queue_ and events in _event_wait_list_ are not the same.
* `CL_INVALID_VALUE` **TODO**, are any values of _ptr_ and _size_ considered invalid?
* `CL_INVALID_VALUE` if _advice_ is zero or is not supported advice for the device associated with _command_queue_.
* `CL_INVALID_VALUE` if _advice_ is not supported advice for the device associated with _command_queue_.
* `CL_INVALID_EVENT_WAIT_LIST` if _event_wait_list_ is `NULL` and _num_events_in_wait_list_ is greater than zero, or if _event_wait_list_ is not `NULL` and _num_events_in_wait_list_ is zero, or if event objects in _event_wait_list_ are not valid events.
* `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.
Expand Down Expand Up @@ -1220,6 +1249,8 @@ Note that some flags will not be valid, such as `CL_MEM_USE_HOST_PTR`.
|M|2020-01-17|Ben Ashbaugh|Minor name changes, removed const from memfree API.
|N|2020-01-22|Ben Ashbaugh|Updated write combine description.
|O|2020-01-23|Ben Ashbaugh|Added aliases for USM migration flags.
|P|2020-02-28|Ben Ashbaugh|Added blocking memfree API.
|Q|2020-03-12|Ben Ashbaugh|Name tweak for blocking memfree API, added comparison to SVM, allow zero memory advice.
|========================================

//************************************************************************
Expand Down