Skip to content

Latest commit

 

History

History
231 lines (178 loc) · 7.12 KB

sycl_ext_oneapi_memcpy2d.asciidoc

File metadata and controls

231 lines (178 loc) · 7.12 KB

sycl_ext_oneapi_memcpy2d

Notice

Copyright © 2022 Intel Corporation. All rights reserved.

Khronos® is a registered trademark and SYCL™ and SPIR™ are trademarks of The Khronos Group Inc. OpenCL™ is a trademark of Apple Inc. used by permission by Khronos.

Contact

To report problems with this extension, please open a new issue at:

Dependencies

This extension is written against the SYCL 2020 revision 4 specification. All references below to the "core SYCL specification" or to section numbers in the SYCL specification refer to that revision.

Status

This extension is implemented and fully supported by DPC++.

Specification

This extension adds support for 2D memcpy and associated routines that can copy a specified rectangular region in the presence of array padding.

Feature test macro

This extension provides a feature-test macro as described in the core SYCL specification. An implementation supporting this extension must predefine the macro SYCL_EXT_ONEAPI_MEMCPY2D to one of the values defined in the table below. Applications can test for the existence of this macro to determine if the implementation supports this feature, or applications can test the macro’s value to determine which of the extension’s features the implementation supports.

Value Description

1

Initial version of this extension.

API Additions

The handler class gains the following new methods:

Member Function Description
void ext_oneapi_memcpy2d(void *dest, size_t destPitch,
  const void *src, size_t srcPitch,
  size_t width, size_t height)

Copies the data located at src to dest. The width of a row in bytes, including any padding, is specified by destPitch for dest and srcPitch for src. The amount of data to copy is specified as width bytes per row times height number of rows. width must not be larger than either srcPitch or destPitch, otherwise this function throws a synchronous exception with the errc::invalid error code. The dest and src parameters must each either be a host pointer or a pointer within a USM allocation that is accessible on the handler’s device. If a pointer is to a USM allocation, that allocation must have been created from the same context as the handler’s queue.

template <typename T>
void ext_oneapi_copy2d(const T *src, size_t srcPitch,
  T *dest, size_t destPitch,
  size_t width, size_t height)

Copies the data located at src to dest. The width of a row in number of elements, including any padding, is specified by destPitch for dest and srcPitch for src. The amount of data to copy is specified as width elements per row times height number of rows. width must not be larger than either srcPitch or destPitch, otherwise this function throws a synchronous exception with the errc::invalid error code. The dest and src parameters must each either be a host pointer or a pointer within a USM allocation that is accessible on the handler’s device. If a pointer is to a USM allocation, that allocation must have been created from the same context as the handler’s queue.

void ext_oneapi_memset2d(void *dest, size_t destPitch,
  int value, size_t width, size_t height)

Fills the data located at dest with value. Note that value is interpreted as an unsigned char. The width of a row in bytes, including any padding, is specified by destPitch for dest. The amount of data to fill is specified as width bytes per row times height number of rows. width must not be larger than destPitch, otherwise this function throws a synchronous exception with the errc::invalid error code. The dest parameter must be a pointer within a USM allocation that is accessible on the handler’s device and that allocation must have been created from the same context as the handler’s queue.

template <typename T>
void ext_oneapi_fill2d(void *dest, size_t destPitch,
  const T& pattern, size_t width, size_t height)

Fills the data located at dest with pattern. The width of a row in number of elements, including any padding, is specified by destPitch. The amount of data to fill is specified as width elements per row times height number of rows. width must not be larger than destPitch, otherwise this function throws a synchronous exception with the errc::invalid error code. The dest parameter must be a pointer within a USM allocation that is accessible on the handler’s device and that allocation must have been created from the same context as the handler’s queue.

This extension also defines additional shortcut methods. The queue class gains several new methods:

Member Function Description
event ext_oneapi_memcpy2d(void *dest, size_t destPitch,
  const void *src, size_t srcPitch,
  size_t width, size_t height)

event ext_oneapi_memcpy2d(void *dest, size_t destPitch,
  const void *src, size_t srcPitch,
  size_t width, size_t height,
  event depEvent)

event ext_oneapi_memcpy2d(void *dest, size_t destPitch,
  const void *src, size_t srcPitch,
  size_t width, size_t height,
  const std::vector<event> &depEvents)

template <typename T>
event ext_oneapi_copy2d(const T *src, size_t srcPitch,
  T *dest, size_t destPitch,
  size_t width, size_t height)

template <typename T>
event ext_oneapi_copy2d(const T *src, size_t srcPitch,
  T *dest, size_t destPitch,
  size_t width, size_t height,
  event depEvent)

template <typename T>
event ext_oneapi_copy2d(const T *src, size_t srcPitch,
  T *dest, size_t destPitch,
  size_t width, size_t height,
  const std::vector<event> &depEvents)

event ext_oneapi_memset2d(void *dest, size_t destPitch,
  int value, size_t width, size_t height)

event ext_oneapi_memset2d(void *dest, size_t destPitch,
  int value, size_t width, size_t height,
  event depEvent)

event ext_oneapi_memset2d(void *dest, size_t destPitch,
  int value, size_t width, size_t height,
  const std::vector<event> &depEvents)

template <typename T>
event ext_oneapi_fill2d(void *dest, size_t destPitch,
  const T& pattern, size_t width, size_t height)

template <typename T>
event ext_oneapi_fill2d(void *dest, size_t destPitch,
  const T& pattern, size_t width, size_t height,
  event depEvent)

template <typename T>
event ext_oneapi_fill2d(void *dest, size_t destPitch,
  const T& pattern, size_t width, size_t height,
  const std::vector<event> &depEvents)

Equivalent to submitting a command group containing the corresponding method in the handler class. Dependences may be specified through the parameters depEvent or depEvents as if the handler contained a call to depends_on.