diff --git a/source/conf.py b/source/conf.py index 5538ba07..227908d1 100644 --- a/source/conf.py +++ b/source/conf.py @@ -130,6 +130,26 @@ def make_ref(ref_str, ref_view, ref_sufix): + make_ref( "SYCL_SPEC_COMMON_BYVAL", "Section 4.5.3", "#sec:byval-semantics" ) + + make_ref( + "SYCL_SPEC_BUFFER_ACCESSOR", + "Section 4.7.6.9", + "#_buffer_accessor_for_commands", + ) + + make_ref( + "SYCL_ACCESS_CON", + "Table 56", + "#table.accessors.command.buffer.constructors", + ) + + make_ref( + "SYCL_ACCESSOR_COMMON_TYPES", + "Table 79", + "#table.accessors.common.types", + ) + + make_ref( + "SYCL_ACCESSOR_COMMON_MEMBERS", + "Table 80", + "#table.accessors.common.members", + ) + f""" .. _`SYCL Specification`: {sycl_ref_url} .. |true| replace:: ``true`` @@ -140,7 +160,6 @@ def make_ref(ref_str, ref_view, ref_sufix): .. |SYCL_SPEC| replace:: `SYCL Specification`_ .. |SYCL_SPEC_BUFFER| replace:: `SYCL Specification`_ Section 4.7.2 .. |SYCL_SPEC_IMAGE| replace:: `SYCL Specification`_ Section 4.7.3 -.. |SYCL_SPEC_BUFFER_ACCESSOR| replace:: `SYCL Specification`_ Section 4.7.6.9 .. |SYCL_SPEC_LOCAL_ACCESSOR| replace:: `SYCL Specification`_ Section 4.7.6.11 .. |SYCL_SPEC_IMAGE_ACCESSOR| replace:: `SYCL Specification`_ Section 4.7.6.12 .. |SYCL_SPEC_MALLOC_DEVICE| replace:: `SYCL Specification`_ Section 4.8.5.1 diff --git a/source/iface/command-accessor.rst b/source/iface/command-accessor.rst index 49cca390..f378e565 100644 --- a/source/iface/command-accessor.rst +++ b/source/iface/command-accessor.rst @@ -6,281 +6,274 @@ .. _buffer-accessor: -****************** +================== ``sycl::accessor`` -****************** +================== :: - template - class accessor; + class accessor; -Description +The ``accessor`` class provides access to data in a ``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 ``AccessTarget`` template parameter. Both forms support +the following values for the ``AccessMode`` template parameter: +``access_mode::read``, ``access_mode::write`` and +``access_mode::read_write``. -.. rubric:: Template parameters +.. seealso:: SYCL Specification |SYCL_SPEC_BUFFER_ACCESSOR| -================= ======= -``dataT`` Type of buffer element -``dimensions`` Number of buffer dimensions -``accessmode`` See :ref:`access-mode` -``accessTarget`` See :ref:`access-target` -``isPlaceholder`` True if accessor is a placeholder -================= ======= +============ +Member types +============ + +``accessor_ptr`` +================ + +:: -.. rubric:: Member types + template accessor_ptr -=================== ======= -``value_type`` Type of buffer element -``reference`` Type of reference to buffer element -``const_reference`` Type of ``const`` reference to buffer element -=================== ======= +If ``(AccessTarget == target::device): +multi_ptr.`` + +The definition of this type is not specified when +``(AccessTarget == target::host_task)``. -.. seealso:: |SYCL_SPEC_BUFFER_ACCESSOR| (constructors) ============== .. parsed-literal:: - *Available only when: - ((isPlaceholder == access::placeholder::false_t && accessTarget == access::target::host_buffer) - || (isPlaceholder == access::placeholder::true_t - && (accessTarget == access::target::global_buffer - || accessTarget == access::target::constant_buffer))) - && dimensions == 0* + accessor() template - accessor(sycl::buffer &bufferRef, - const sycl::property_list &propList = {}); - - *Available only when: - (isPlaceholder == access::placeholder::false_t - && (accessTarget == access::target::global_buffer - || accessTarget == access::target::constant_buffer)) - && dimensions == 0* + accessor(buffer& bufferRef, + const property_list& propList = {}) template - accessor(sycl::buffer &bufferRef, - sycl::handler &commandGroupHandlerRef, const sycl::property_list &propList = {}); - - *Available only when: - ((isPlaceholder == access::placeholder::false_t - && accessTarget == access::target::host_buffer) - || (isPlaceholder == access::placeholder::true_t - && (accessTarget == access::target::global_buffer - || accessTarget == access::target::constant_buffer))) - && dimensions > 0* + accessor(buffer& bufferRef, + handler& commandGroupHandlerRef, const property_list& propList = {}) template - accessor(sycl::buffer &bufferRef, - const sycl::property_list &propList = {}); - template - accessor(sycl::buffer &bufferRef, - sycl::range accessRange, const sycl::property_list &propList = {}); - template - accessor(sycl::buffer &bufferRef, - sycl::range accessRange, id accessOffset, - const sycl::property_list &propList = {}); + accessor(buffer& bufferRef, + const property_list& propList = {}) - *Available only when: - (isPlaceholder == access::placeholder::false_t - && (accessTarget == access::target::global_buffer - || accessTarget == access::target::constant_buffer)) - && dimensions > 0* + template + accessor(buffer& bufferRef, TagT tag, + const property_list& propList = {}) template - accessor(sycl::buffer &bufferRef, - sycl::handler &commandGroupHandlerRef, const sycl::property_list &propList = {}); - template - accessor(sycl::buffer &bufferRef, - sycl::handler &commandGroupHandlerRef, sycl::range accessRange, - const sycl::property_list &propList = {}); - template - accessor(sycl:buffer &bufferRef, - sycl::handler &commandGroupHandlerRef, sycl::range accessRange, - sycl::id accessOffset, const sycl::property_list &propList = {}); + accessor(buffer& bufferRef, + handler& commandGroupHandlerRef, const property_list& propList = {}) + template + accessor(buffer& bufferRef, + handler& commandGroupHandlerRef, TagT tag, + const property_list& propList = {}) -Construct an accessor for a buffer. + template + accessor(buffer& bufferRef, + range accessRange, const property_list& propList = {}) -Programs typically find it more convenient to use -:ref:`buffer-get_access` to create an accessor for a buffer. + template + accessor(buffer& bufferRef, + range accessRange, TagT tag, + const property_list& propList = {}) -.. rubric:: Template parameters + template + accessor(buffer& bufferRef, + range accessRange, id accessOffset, + const property_list& propList = {}) -============== === -``AllocatorT`` Type of allocator for buffer element -============== === + template + accessor(buffer& bufferRef, + range accessRange, id accessOffset, TagT tag, + const property_list& propList = {}) -.. rubric:: Parameters + template + accessor(buffer& bufferRef, + handler& commandGroupHandlerRef, range accessRange, + const property_list& propList = {}) -========================== === -``bufferRef`` Associate accessor with this buffer -``commandGroupHandlerRef`` Associate accessor with this handler -``propList`` `sycl::accessor (buffer) properties`_ -``accessRange`` Dimensions of data to be accessed -``accessOffset`` Coordinates of origin of data -========================== === + template + accessor(buffer& bufferRef, + handler& commandGroupHandlerRef, range accessRange, + TagT tag, const property_list& propList = {}) -``is_placeholder`` -================== + template + accessor(buffer& bufferRef, + handler& commandGroupHandlerRef, range accessRange, + id accessOffset, const property_list& propList = {}) -:: + template + accessor(buffer& bufferRef, + handler& commandGroupHandlerRef, range accessRange, + id accessOffset, TagT tag, + const property_list& propList = {}) - constexpr bool is_placeholder() const; +Constructors of the accessor class. +The descriptions are listed in |SYCL_ACCESS_CON|. -Return True if this is a placeholder accessor. +================ +Member functions +================ -``get_size`` -============ +``swap`` +======== :: - size_t get_size() const; + void swap(accessor& other); -Returns size in bytes of the buffer region that this accesses. +Swaps the contents of the current accessor with +the contents of ``other``. -``get_count`` -============= +``is_placeholder`` +================== :: - size_t get_count() const; + bool is_placeholder() const -Returns number elements that this accesses. - -``get_range`` -============= - -.. parsed-literal:: - - *Available only when: - dimensions > 0* - - sycl::range get_range() const; - - -.. rubric:: Template parameters - -=============== === -``dimensions`` number of dimensions -=============== === - -Returns dimensions of the associated buffer or range that was -provided when the accessor was created. +Returns ``true`` if the accessor is a placeholder. +Otherwise returns ``false``. ``get_offset`` ============== -.. parsed-literal:: - - *Available only when: - dimensions > 0* +:: - sycl::id get_offset() const; + id get_offset() const +Available only when ``(Dimensions > 0)``. -.. rubric:: Template parameters +If this is a ranged accessor, returns the offset +that was specified when the accessor was constructed. +For other accessors, returns the default +constructed ``id{}``. -=============== === -``dimensions`` number of dimensions -=============== === +``get_pointer`` +=============== +:: -Returns coordinates of the origin of the buffer or offset that was -provided when the accessor was created. + global_ptr get_pointer() const noexcept -``operator ()`` -=============== +Deprecated in SYCL 2020. Use ``get_multi_ptr`` instead. -.. parsed-literal:: +``get_multi_ptr`` +================= - *Available only when: - accessMode == access::mode::write - || accessMode == access::mode::read_write - || accessMode == access::mode::discard_write - || accessMode == access::mode::discard_read_write* +:: - operator dataT &() const; + template + accessor_ptr get_multi_ptr() const noexcept - *Available only when: - accessMode == access::mode::read* +Available only when ``(AccessTarget == target::device)``. - operator dataT() const; +Returns a ``multi_ptr`` to the start of this accessor’s +underlying buffer, even if this is a ranged accessor +whose range does not start at the beginning of the buffer. +The return value is unspecified if the accessor is empty. - *Available only when: - accessMode == access::mode::atomic* +This function may only be called from within a command. - operator atomic () const; +``operator=`` +============= -Returns reference or value of element in the associated buffer. +:: -The variants of this operator are only available when *dimensions == -0*, which means that a buffer contains a single element. + const accessor& operator=(const value_type& other) const -``operator[]`` -============== + const accessor& operator=(value_type&& other) const -.. parsed-literal:: +Available only when +``(AccessMode != access_mode::atomic && +AccessMode != access_mode::read && Dimensions == 0)``. - *Reference variants* - dataT &operator[](size_t index) const; - dataT &operator[](sycl::id index) const; +Assignment to the single element that is accessed by this accessor. - *Value variants* - dataT operator[](size_t index) const; - dataT operator[](sycl::id index) const; +This function may only be called from within a command. - *Atomic variants* - atomic operator[]( - size_t index) const; - atomic operator[]( - id index) const; +.. _tags_buff_accessors: - *Single dimension in multi-dimensional buffer* - __unspecified__ &operator[](size_t index) const; +============================= +Buffer command accessors tags +============================= -Returns reference or value of element in the associated buffer at the -requested index. +Some ``accessor`` constructors take a ``TagT`` parameter, +which is used to deduce template arguments. +The permissible values for this parameter are listed in table below. -One dimensional buffers are indexed by a data of type -size_t. Multi-dimensional buffers may be indexed by a data of type -``id``, or by a sequence of *[]*, 1 per dimension. For -example ``a[1][2]``. The operator returns a reference when the -accessor allows writes, which requires that ``accessMode`` be one of -``access::mode::write``, ``accessMode == access::mode::read_write``, -``accessMode == access::mode::discard_write``, or ``accessMode == -access::mode::discard_read_write``. The operator returns an atomic if -the ``accessMode`` is ``access::mode::atomic``. +.. list-table:: + :header-rows: 1 + * - Tag value + - Access mode + - Accessor target + * - ``read_write;`` + - ``access_mode::read_write`` + - ``target::device`` + * - ``read_only;`` + - ``access_mode::read`` + - ``target::device`` + * - ``write_only;`` + - ``access_mode::write`` + - ``target::device`` + * - ``read_write_host_task;`` + - ``access_mode::read_write`` + - ``target::host_task`` + * - ``read_only_host_task;`` + - ``access_mode::read`` + - ``target::host_task`` + * - ``write_only_host_task;`` + - ``access_mode::write`` + - ``target::host_task`` -``get_pointer`` -=============== -.. parsed-literal:: +``read-only accessors`` +======================= - *Available only when: - accessTarget == access::target::host_buffer* +.. list-table:: + :header-rows: 1 - dataT \*get_pointer() const; + * - Data type + - Access mode + * - not const-qualified + - ``access_mode::read`` + * - const-qualified + - ``access_mode::read`` - *Available only when: - accessTarget == access::target::global_buffer* +The specializations of ``accessor`` with +``target::device or target::host_task`` that are read-only accessors. +There is an implicit conversion between any of these specializations, +provided that all other template parameters are the same. - sycl::global_ptr get_pointer() const; +``read-write accessors`` +======================== - *Available only when: - accessTarget == access::target::constant_buffer* +.. list-table:: + :header-rows: 1 - sycl::constant_ptr get_pointer() const; + * - Data type + - Access mode + * - not const-qualified + - ``access_mode::read_write`` -Returns pointer to memory in a host buffer. +The table present an implicit conversion from +the read-write specialization. +======================== +Common types and members +======================== -``sycl::accessor`` (buffer) properties -====================================== +The ``accessor``, ``host_accessor``, and ``local_accessor`` +classes have many member types and member functions with the +same name and meaning. -SYCL does not define any properties for the buffer specialization of -an accessor. +|SYCL_ACCESSOR_COMMON_TYPES| describes these common types and +|SYCL_ACCESSOR_COMMON_MEMBERS| describes the common member functions. diff --git a/source/spelling_wordlist.txt b/source/spelling_wordlist.txt index 3c0f58d0..ed66a710 100644 --- a/source/spelling_wordlist.txt +++ b/source/spelling_wordlist.txt @@ -6,6 +6,7 @@ accessor accessors backend backends +const destructor atomics dimensionality