Skip to content

Commit

Permalink
Update the accessor section
Browse files Browse the repository at this point in the history
This reflects the restructure that @gmlueck suggested in
KhronosGroup#537.
  • Loading branch information
hdelan committed Mar 19, 2024
1 parent 4234c45 commit 0a7190b
Showing 1 changed file with 20 additions and 20 deletions.
40 changes: 20 additions & 20 deletions adoc/chapters/programming_interface.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -6511,15 +6511,15 @@ access an element produces undefined behaviour.

==== Buffer accessor for commands

The [code]#accessor# class provides access to data in a [code]#buffer# from
within a <<sycl-kernel-function>> or from within a <<host-task>>.
When used in a <<sycl-kernel-function>>, it accesses the contents of the buffer
via the device's <<global-memory>>.
These two forms of the accessor are distinguished by the [code]#AccessTarget#
template parameter as shown in <<table.accessors.command.buffer.capabilities>>.
Both forms support the following values for the [code]#AccessMode# template
parameter: [code]#access_mode::read#, [code]#access_mode::write# and
[code]#access_mode::read_write#.
The [code]#accessor# class provides access to data in a [code]#buffer# in three
different ways.
It can be used to access the buffer's data from within a
<<sycl-kernel-function>> via the device's <<global-memory>>.
It can also be used to access the buffer's data on host from within a host task.
Finally, it can be used to get a native backend handle to the buffer from
within a host task, to be used on device.
The AccessTarget template parameter helps distinguish these three cases as
shown in <<table.accessors.command.buffer.capabilities>>.

[[table.accessors.command.buffer.capabilities]]
.Description of access targets for buffer accessors
Expand All @@ -6528,20 +6528,20 @@ parameter: [code]#access_mode::read#, [code]#access_mode::write# and
| Access target | Meaning
| [code]#target::device#
| Access a buffer from a <<sycl-kernel-function>> via device global memory.
Also used to get a native backend handle to the buffer from within a host
task, to be used on device.
| [code]#target::host_task#
| Access a buffer from a <<host-task>>.
| Access a buffer's data on host from within a <<host-task>>.
|====

Programs which specify the access target as [code]#target::device# and then
capture the [code]#accessor# in a <<host-task>> can only use the accessor for
interoperability through the [code]#interop_handle#, any other uses result in
undefined behavior.

An accessor with access target [code]#target::host_task# is accessible on the
host, within the host task function for which the accessor is declared.
Programs which specify the access target as [code]#target::host_task# and then
use the [code]#accessor# from a <<sycl-kernel-function>> result in undefined
behavior.
When an [code]#accessor# is used from within a host task, the use of the
accessor must correspond to the access target, otherwise the behavior is
undefined.
If the access target is [code]#target::host_task#, the accessor may only be
used to access the buffer's data on host, from within the host task function.
If the access target is [code]#target::device#, the accessor may only be
used to get a native backend handle for the buffer as described in
<<subsec:interfaces.hosttasks.interophandle>>.

The dimensionality of the accessor must match the underlying buffer, however,
there is a special case if the buffer is one-dimensional.
Expand Down

0 comments on commit 0a7190b

Please sign in to comment.