Skip to content

Commit

Permalink
[SYCL][DOC] Clarify device global error conditions (#4972)
Browse files Browse the repository at this point in the history
Clarify the behavior of `handler::copy()` and `handler::memcpy()` in
two error cases w.r.t `device_global` variables.
  • Loading branch information
gmlueck authored Dec 3, 2021
1 parent 5ab3cd3 commit 842f2dd
Showing 1 changed file with 43 additions and 0 deletions.
43 changes: 43 additions & 0 deletions sycl/doc/extensions/DeviceGlobal/SYCL_INTEL_device_global.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -947,6 +947,14 @@ Not available if `PropertyListT` contains the `host_access` property with
`read` or `none` assertions.

Copies _count_ elements of type `std::remove_all_extents_t<T>` from the pointer _src_ to the `device_global` _dest_, starting at _startIndex_ elements of _dest_. _src_ may be either a host or USM pointer.

If _count_ and _startIndex_ would cause data to be written beyond the end of
the variable _dest_, the implementation throws an `exception` with the
`errc::invalid` error code.

If `PropertyListT` contains the `device_image_scope` property and the _dest_
variable exists in more than one _device image_ for this queue's device, the
implementation throws an `exception` with the `errc::invalid` error code.
a|
[source, c++]
----
Expand All @@ -963,6 +971,14 @@ Not available if `PropertyListT` contains the `host_access` property with

Copies _count_ elements of type `std::remove_all_extents_t<T>` from the `device_global` _src_ to the pointer _dest_, starting at _startIndex_ elements of _src_. _dest_ may be either a host or USM pointer.

If _count_ and _startIndex_ would cause data to be read beyond the end of
the variable _src_, the implementation throws an `exception` with the
`errc::invalid` error code.

If `PropertyListT` contains the `device_image_scope` property and the _src_
variable exists in more than one _device image_ for this queue's device, the
implementation throws an `exception` with the `errc::invalid` error code.

a|
[source, c++]
----
Expand All @@ -977,6 +993,14 @@ Not available if `PropertyListT` contains the `host_access` property with

Copies _count_ bytes from the pointer _src_ to the `device_global` _dest_, starting at _offset_ bytes. _src_ may be either a host or USM pointer.

If _numBytes_ and _offset_ would cause data to be written beyond the end of
the variable _dest_, the implementation throws an `exception` with the
`errc::invalid` error code.

If `PropertyListT` contains the `device_image_scope` property and the _dest_
variable exists in more than one _device image_ for this queue's device, the
implementation throws an `exception` with the `errc::invalid` error code.

a|
[source, c++]
----
Expand All @@ -991,9 +1015,28 @@ Not available if `PropertyListT` contains the `host_access` property with
`write` or `none` assertions.

Copies _count_ bytes from the `device_global` _src_ to the pointer _dest_, starting at _offset_ bytes. _dest_ may be either a host or USM pointer.

If _numBytes_ and _offset_ would cause data to be read beyond the end of
the variable _src_, the implementation throws an `exception` with the
`errc::invalid` error code.

If `PropertyListT` contains the `device_image_scope` property and the _src_
variable exists in more than one _device image_ for this queue's device, the
implementation throws an `exception` with the `errc::invalid` error code.
|====
--

[NOTE]
====
As specified above, the `copy` and `memcpy` functions throw an exception if the
global variable has the `device_image_scope` property and exists in more than
one _device image_ for the queue's device. This condition could occur if the
application submits a kernel referencing the variable to the same device with
different values for a specialization constant (when the device supports
specialization constants natively). This condition could also occur if the
application submits the same kernel from more than one kernel bundle.
====


== Non-normative: Future anticipated changes, not enabled within this version of the specification

Expand Down

0 comments on commit 842f2dd

Please sign in to comment.