.. index:: pair: group; USM Interface
.. _doxid-df/d6e/group___u_s_m_interface:

USM Interface
=============

.. toctree::
	:hidden:

Overview
~~~~~~~~




.. ref-code-block:: cpp
	:class: doxyrest-overview-code-block

	
	// global functions

	:ref:`DPCTL_API<doxid-d3/daa/_dll_export_8h_1aed0c117c235d99c414e0b5033d096785>` :ref:`__dpctl_give<doxid-d2/d43/group___memory_semantics_1ga836492a42cdfef6419378dbf8d81f452>` :ref:`DPCTLSyclUSMRef<doxid-df/d57/dpctl__sycl__types_8h_1a8c78ad1413045f90e15f5b6a2727d2e6>`
	:ref:`DPCTLaligned_alloc_device<doxid-df/d6e/group___u_s_m_interface_1ga40c3e68d157d775bbe6daa188b84b3e3>`(
		size_t alignment,
		size_t size,
		:ref:`__dpctl_keep<doxid-d2/d43/group___memory_semantics_1gadd48a0161309931574aed2025a16ade7>` const :ref:`DPCTLSyclQueueRef<doxid-df/d57/dpctl__sycl__types_8h_1af23137a8bf20ff63b10db9f7f987799a>` QRef
		);

	:ref:`DPCTL_API<doxid-d3/daa/_dll_export_8h_1aed0c117c235d99c414e0b5033d096785>` :ref:`__dpctl_give<doxid-d2/d43/group___memory_semantics_1ga836492a42cdfef6419378dbf8d81f452>` :ref:`DPCTLSyclUSMRef<doxid-df/d57/dpctl__sycl__types_8h_1a8c78ad1413045f90e15f5b6a2727d2e6>`
	:ref:`DPCTLaligned_alloc_host<doxid-df/d6e/group___u_s_m_interface_1ga327bba1e6a5a1f6922e74ab6914e58ff>`(
		size_t alignment,
		size_t size,
		:ref:`__dpctl_keep<doxid-d2/d43/group___memory_semantics_1gadd48a0161309931574aed2025a16ade7>` const :ref:`DPCTLSyclQueueRef<doxid-df/d57/dpctl__sycl__types_8h_1af23137a8bf20ff63b10db9f7f987799a>` QRef
		);

	:ref:`DPCTL_API<doxid-d3/daa/_dll_export_8h_1aed0c117c235d99c414e0b5033d096785>` :ref:`__dpctl_give<doxid-d2/d43/group___memory_semantics_1ga836492a42cdfef6419378dbf8d81f452>` :ref:`DPCTLSyclUSMRef<doxid-df/d57/dpctl__sycl__types_8h_1a8c78ad1413045f90e15f5b6a2727d2e6>`
	:ref:`DPCTLaligned_alloc_shared<doxid-df/d6e/group___u_s_m_interface_1ga7c3e58848a979723dc350d2a8016edd8>`(
		size_t alignment,
		size_t size,
		:ref:`__dpctl_keep<doxid-d2/d43/group___memory_semantics_1gadd48a0161309931574aed2025a16ade7>` const :ref:`DPCTLSyclQueueRef<doxid-df/d57/dpctl__sycl__types_8h_1af23137a8bf20ff63b10db9f7f987799a>` QRef
		);

	:ref:`DPCTL_API<doxid-d3/daa/_dll_export_8h_1aed0c117c235d99c414e0b5033d096785>` void
	:ref:`DPCTLfree_with_context<doxid-df/d6e/group___u_s_m_interface_1gad1da9c1cb7fca0b3c1bc0edc9467c0a9>`(
		:ref:`__dpctl_take<doxid-d2/d43/group___memory_semantics_1ga17fe5722d78d8ce138ca952889d07bc6>` :ref:`DPCTLSyclUSMRef<doxid-df/d57/dpctl__sycl__types_8h_1a8c78ad1413045f90e15f5b6a2727d2e6>` MRef,
		:ref:`__dpctl_keep<doxid-d2/d43/group___memory_semantics_1gadd48a0161309931574aed2025a16ade7>` const :ref:`DPCTLSyclContextRef<doxid-df/d57/dpctl__sycl__types_8h_1accf78808322af80b73da617cb2f15f08>` CRef
		);

	:ref:`DPCTL_API<doxid-d3/daa/_dll_export_8h_1aed0c117c235d99c414e0b5033d096785>` void
	:ref:`DPCTLfree_with_queue<doxid-df/d6e/group___u_s_m_interface_1ga0d8486b09ea0a677a3fb6cbe677f8633>`(
		:ref:`__dpctl_take<doxid-d2/d43/group___memory_semantics_1ga17fe5722d78d8ce138ca952889d07bc6>` :ref:`DPCTLSyclUSMRef<doxid-df/d57/dpctl__sycl__types_8h_1a8c78ad1413045f90e15f5b6a2727d2e6>` MRef,
		:ref:`__dpctl_keep<doxid-d2/d43/group___memory_semantics_1gadd48a0161309931574aed2025a16ade7>` const :ref:`DPCTLSyclQueueRef<doxid-df/d57/dpctl__sycl__types_8h_1af23137a8bf20ff63b10db9f7f987799a>` QRef
		);

	:ref:`DPCTL_API<doxid-d3/daa/_dll_export_8h_1aed0c117c235d99c414e0b5033d096785>` :ref:`__dpctl_give<doxid-d2/d43/group___memory_semantics_1ga836492a42cdfef6419378dbf8d81f452>` :ref:`DPCTLSyclUSMRef<doxid-df/d57/dpctl__sycl__types_8h_1a8c78ad1413045f90e15f5b6a2727d2e6>`
	:ref:`DPCTLmalloc_device<doxid-df/d6e/group___u_s_m_interface_1gac1927ffcb3ca7ef43366a8b64e211ef2>`(
		size_t size,
		:ref:`__dpctl_keep<doxid-d2/d43/group___memory_semantics_1gadd48a0161309931574aed2025a16ade7>` const :ref:`DPCTLSyclQueueRef<doxid-df/d57/dpctl__sycl__types_8h_1af23137a8bf20ff63b10db9f7f987799a>` QRef
		);

	:ref:`DPCTL_API<doxid-d3/daa/_dll_export_8h_1aed0c117c235d99c414e0b5033d096785>` :ref:`__dpctl_give<doxid-d2/d43/group___memory_semantics_1ga836492a42cdfef6419378dbf8d81f452>` :ref:`DPCTLSyclUSMRef<doxid-df/d57/dpctl__sycl__types_8h_1a8c78ad1413045f90e15f5b6a2727d2e6>`
	:ref:`DPCTLmalloc_host<doxid-df/d6e/group___u_s_m_interface_1ga699b56970ac78f3b3ca87a2ad6ff4615>`(
		size_t size,
		:ref:`__dpctl_keep<doxid-d2/d43/group___memory_semantics_1gadd48a0161309931574aed2025a16ade7>` const :ref:`DPCTLSyclQueueRef<doxid-df/d57/dpctl__sycl__types_8h_1af23137a8bf20ff63b10db9f7f987799a>` QRef
		);

	:ref:`DPCTL_API<doxid-d3/daa/_dll_export_8h_1aed0c117c235d99c414e0b5033d096785>` :ref:`__dpctl_give<doxid-d2/d43/group___memory_semantics_1ga836492a42cdfef6419378dbf8d81f452>` :ref:`DPCTLSyclUSMRef<doxid-df/d57/dpctl__sycl__types_8h_1a8c78ad1413045f90e15f5b6a2727d2e6>`
	:ref:`DPCTLmalloc_shared<doxid-df/d6e/group___u_s_m_interface_1ga7c9316842db74f4730fab04a4e4f4eb5>`(
		size_t size,
		:ref:`__dpctl_keep<doxid-d2/d43/group___memory_semantics_1gadd48a0161309931574aed2025a16ade7>` const :ref:`DPCTLSyclQueueRef<doxid-df/d57/dpctl__sycl__types_8h_1af23137a8bf20ff63b10db9f7f987799a>` QRef
		);

	:ref:`DPCTL_API<doxid-d3/daa/_dll_export_8h_1aed0c117c235d99c414e0b5033d096785>` :ref:`DPCTLSyclDeviceRef<doxid-df/d57/dpctl__sycl__types_8h_1a8dae76b436012ecbdebbd568e77f440d>`
	:ref:`DPCTLUSM_GetPointerDevice<doxid-df/d6e/group___u_s_m_interface_1ga7ebb5012408e40e3e78b4da551da8412>`(
		:ref:`__dpctl_keep<doxid-d2/d43/group___memory_semantics_1gadd48a0161309931574aed2025a16ade7>` const :ref:`DPCTLSyclUSMRef<doxid-df/d57/dpctl__sycl__types_8h_1a8c78ad1413045f90e15f5b6a2727d2e6>` MRef,
		:ref:`__dpctl_keep<doxid-d2/d43/group___memory_semantics_1gadd48a0161309931574aed2025a16ade7>` const :ref:`DPCTLSyclContextRef<doxid-df/d57/dpctl__sycl__types_8h_1accf78808322af80b73da617cb2f15f08>` CRef
		);

	:ref:`DPCTL_API<doxid-d3/daa/_dll_export_8h_1aed0c117c235d99c414e0b5033d096785>` :ref:`DPCTLSyclUSMType<doxid-d3/d94/dpctl__sycl__enum__types_8h_1a61bd8b72de91212af565a9be9b913844>`
	:ref:`DPCTLUSM_GetPointerType<doxid-df/d6e/group___u_s_m_interface_1ga8cdbaff72515ca1f9caa745cf342f5cc>`(
		:ref:`__dpctl_keep<doxid-d2/d43/group___memory_semantics_1gadd48a0161309931574aed2025a16ade7>` const :ref:`DPCTLSyclUSMRef<doxid-df/d57/dpctl__sycl__types_8h_1a8c78ad1413045f90e15f5b6a2727d2e6>` MRef,
		:ref:`__dpctl_keep<doxid-d2/d43/group___memory_semantics_1gadd48a0161309931574aed2025a16ade7>` const :ref:`DPCTLSyclContextRef<doxid-df/d57/dpctl__sycl__types_8h_1accf78808322af80b73da617cb2f15f08>` CRef
		);

.. _details-df/d6e/group___u_s_m_interface:

Detailed Documentation
~~~~~~~~~~~~~~~~~~~~~~



Global Functions
----------------

.. index:: pair: function; DPCTLaligned_alloc_device
.. _doxid-df/d6e/group___u_s_m_interface_1ga40c3e68d157d775bbe6daa188b84b3e3:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`DPCTL_API<doxid-d3/daa/_dll_export_8h_1aed0c117c235d99c414e0b5033d096785>` :ref:`__dpctl_give<doxid-d2/d43/group___memory_semantics_1ga836492a42cdfef6419378dbf8d81f452>` :ref:`DPCTLSyclUSMRef<doxid-df/d57/dpctl__sycl__types_8h_1a8c78ad1413045f90e15f5b6a2727d2e6>`
	DPCTLaligned_alloc_device(
		size_t alignment,
		size_t size,
		:ref:`__dpctl_keep<doxid-d2/d43/group___memory_semantics_1gadd48a0161309931574aed2025a16ade7>` const :ref:`DPCTLSyclQueueRef<doxid-df/d57/dpctl__sycl__types_8h_1af23137a8bf20ff63b10db9f7f987799a>` QRef
		)

Create USM device memory.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- alignment

		- Allocation's byte alignment

	*
		- size

		- Number of bytes to allocate

	*
		- QRef

		- Sycl queue reference to use in allocation



.. rubric:: Returns:

The pointer to USM device memory with requested alignment. On failure, returns nullptr.

.. index:: pair: function; DPCTLaligned_alloc_host
.. _doxid-df/d6e/group___u_s_m_interface_1ga327bba1e6a5a1f6922e74ab6914e58ff:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`DPCTL_API<doxid-d3/daa/_dll_export_8h_1aed0c117c235d99c414e0b5033d096785>` :ref:`__dpctl_give<doxid-d2/d43/group___memory_semantics_1ga836492a42cdfef6419378dbf8d81f452>` :ref:`DPCTLSyclUSMRef<doxid-df/d57/dpctl__sycl__types_8h_1a8c78ad1413045f90e15f5b6a2727d2e6>`
	DPCTLaligned_alloc_host(
		size_t alignment,
		size_t size,
		:ref:`__dpctl_keep<doxid-d2/d43/group___memory_semantics_1gadd48a0161309931574aed2025a16ade7>` const :ref:`DPCTLSyclQueueRef<doxid-df/d57/dpctl__sycl__types_8h_1af23137a8bf20ff63b10db9f7f987799a>` QRef
		)

Create USM host memory.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- alignment

		- Allocation's byte alignment

	*
		- size

		- Number of bytes to allocate

	*
		- QRef

		- Sycl queue reference to use in allocation



.. rubric:: Returns:

The pointer to USM host memory with the requested alignment. On failure, returns nullptr.

.. index:: pair: function; DPCTLaligned_alloc_shared
.. _doxid-df/d6e/group___u_s_m_interface_1ga7c3e58848a979723dc350d2a8016edd8:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`DPCTL_API<doxid-d3/daa/_dll_export_8h_1aed0c117c235d99c414e0b5033d096785>` :ref:`__dpctl_give<doxid-d2/d43/group___memory_semantics_1ga836492a42cdfef6419378dbf8d81f452>` :ref:`DPCTLSyclUSMRef<doxid-df/d57/dpctl__sycl__types_8h_1a8c78ad1413045f90e15f5b6a2727d2e6>`
	DPCTLaligned_alloc_shared(
		size_t alignment,
		size_t size,
		:ref:`__dpctl_keep<doxid-d2/d43/group___memory_semantics_1gadd48a0161309931574aed2025a16ade7>` const :ref:`DPCTLSyclQueueRef<doxid-df/d57/dpctl__sycl__types_8h_1af23137a8bf20ff63b10db9f7f987799a>` QRef
		)

Create USM shared memory.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- alignment

		- Allocation's byte alignment

	*
		- size

		- Number of bytes to allocate

	*
		- QRef

		- Sycl queue reference to use in allocation



.. rubric:: Returns:

The pointer to USM shared memory with the requested alignment. On failure, returns nullptr.

.. index:: pair: function; DPCTLfree_with_context
.. _doxid-df/d6e/group___u_s_m_interface_1gad1da9c1cb7fca0b3c1bc0edc9467c0a9:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`DPCTL_API<doxid-d3/daa/_dll_export_8h_1aed0c117c235d99c414e0b5033d096785>` void
	DPCTLfree_with_context(
		:ref:`__dpctl_take<doxid-d2/d43/group___memory_semantics_1ga17fe5722d78d8ce138ca952889d07bc6>` :ref:`DPCTLSyclUSMRef<doxid-df/d57/dpctl__sycl__types_8h_1a8c78ad1413045f90e15f5b6a2727d2e6>` MRef,
		:ref:`__dpctl_keep<doxid-d2/d43/group___memory_semantics_1gadd48a0161309931574aed2025a16ade7>` const :ref:`DPCTLSyclContextRef<doxid-df/d57/dpctl__sycl__types_8h_1accf78808322af80b73da617cb2f15f08>` CRef
		)

Free USM memory.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- MRef

		- USM pointer to free

	*
		- CRef

		- Sycl context reference to use.

.. index:: pair: function; DPCTLfree_with_queue
.. _doxid-df/d6e/group___u_s_m_interface_1ga0d8486b09ea0a677a3fb6cbe677f8633:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`DPCTL_API<doxid-d3/daa/_dll_export_8h_1aed0c117c235d99c414e0b5033d096785>` void
	DPCTLfree_with_queue(
		:ref:`__dpctl_take<doxid-d2/d43/group___memory_semantics_1ga17fe5722d78d8ce138ca952889d07bc6>` :ref:`DPCTLSyclUSMRef<doxid-df/d57/dpctl__sycl__types_8h_1a8c78ad1413045f90e15f5b6a2727d2e6>` MRef,
		:ref:`__dpctl_keep<doxid-d2/d43/group___memory_semantics_1gadd48a0161309931574aed2025a16ade7>` const :ref:`DPCTLSyclQueueRef<doxid-df/d57/dpctl__sycl__types_8h_1af23137a8bf20ff63b10db9f7f987799a>` QRef
		)

Free USM memory.

USM pointer must have been allocated using the same context as the one used to construct the queue.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- MRef

		- USM pointer to free

	*
		- QRef

		- Sycl queue reference to use.

.. index:: pair: function; DPCTLmalloc_device
.. _doxid-df/d6e/group___u_s_m_interface_1gac1927ffcb3ca7ef43366a8b64e211ef2:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`DPCTL_API<doxid-d3/daa/_dll_export_8h_1aed0c117c235d99c414e0b5033d096785>` :ref:`__dpctl_give<doxid-d2/d43/group___memory_semantics_1ga836492a42cdfef6419378dbf8d81f452>` :ref:`DPCTLSyclUSMRef<doxid-df/d57/dpctl__sycl__types_8h_1a8c78ad1413045f90e15f5b6a2727d2e6>`
	DPCTLmalloc_device(
		size_t size,
		:ref:`__dpctl_keep<doxid-d2/d43/group___memory_semantics_1gadd48a0161309931574aed2025a16ade7>` const :ref:`DPCTLSyclQueueRef<doxid-df/d57/dpctl__sycl__types_8h_1af23137a8bf20ff63b10db9f7f987799a>` QRef
		)

Create USM device memory.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- size

		- Number of bytes to allocate

	*
		- QRef

		- Sycl queue reference to use in allocation



.. rubric:: Returns:

The pointer to USM device memory. On failure, returns nullptr.

.. index:: pair: function; DPCTLmalloc_host
.. _doxid-df/d6e/group___u_s_m_interface_1ga699b56970ac78f3b3ca87a2ad6ff4615:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`DPCTL_API<doxid-d3/daa/_dll_export_8h_1aed0c117c235d99c414e0b5033d096785>` :ref:`__dpctl_give<doxid-d2/d43/group___memory_semantics_1ga836492a42cdfef6419378dbf8d81f452>` :ref:`DPCTLSyclUSMRef<doxid-df/d57/dpctl__sycl__types_8h_1a8c78ad1413045f90e15f5b6a2727d2e6>`
	DPCTLmalloc_host(
		size_t size,
		:ref:`__dpctl_keep<doxid-d2/d43/group___memory_semantics_1gadd48a0161309931574aed2025a16ade7>` const :ref:`DPCTLSyclQueueRef<doxid-df/d57/dpctl__sycl__types_8h_1af23137a8bf20ff63b10db9f7f987799a>` QRef
		)

Create USM host memory.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- size

		- Number of bytes to allocate

	*
		- QRef

		- Sycl queue reference to use in allocation



.. rubric:: Returns:

The pointer to USM host memory. On failure, returns nullptr.

.. index:: pair: function; DPCTLmalloc_shared
.. _doxid-df/d6e/group___u_s_m_interface_1ga7c9316842db74f4730fab04a4e4f4eb5:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`DPCTL_API<doxid-d3/daa/_dll_export_8h_1aed0c117c235d99c414e0b5033d096785>` :ref:`__dpctl_give<doxid-d2/d43/group___memory_semantics_1ga836492a42cdfef6419378dbf8d81f452>` :ref:`DPCTLSyclUSMRef<doxid-df/d57/dpctl__sycl__types_8h_1a8c78ad1413045f90e15f5b6a2727d2e6>`
	DPCTLmalloc_shared(
		size_t size,
		:ref:`__dpctl_keep<doxid-d2/d43/group___memory_semantics_1gadd48a0161309931574aed2025a16ade7>` const :ref:`DPCTLSyclQueueRef<doxid-df/d57/dpctl__sycl__types_8h_1af23137a8bf20ff63b10db9f7f987799a>` QRef
		)

Create USM shared memory.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- size

		- Number of bytes to allocate

	*
		- QRef

		- Sycl queue reference to use in allocation



.. rubric:: Returns:

The pointer to USM shared memory. On failure, returns nullptr.

.. index:: pair: function; DPCTLUSM_GetPointerDevice
.. _doxid-df/d6e/group___u_s_m_interface_1ga7ebb5012408e40e3e78b4da551da8412:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`DPCTL_API<doxid-d3/daa/_dll_export_8h_1aed0c117c235d99c414e0b5033d096785>` :ref:`DPCTLSyclDeviceRef<doxid-df/d57/dpctl__sycl__types_8h_1a8dae76b436012ecbdebbd568e77f440d>`
	DPCTLUSM_GetPointerDevice(
		:ref:`__dpctl_keep<doxid-d2/d43/group___memory_semantics_1gadd48a0161309931574aed2025a16ade7>` const :ref:`DPCTLSyclUSMRef<doxid-df/d57/dpctl__sycl__types_8h_1a8c78ad1413045f90e15f5b6a2727d2e6>` MRef,
		:ref:`__dpctl_keep<doxid-d2/d43/group___memory_semantics_1gadd48a0161309931574aed2025a16ade7>` const :ref:`DPCTLSyclContextRef<doxid-df/d57/dpctl__sycl__types_8h_1accf78808322af80b73da617cb2f15f08>` CRef
		)

Get the device associated with USM pointer.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- MRef

		- USM pointer

	*
		- CRef

		- Sycl context reference associated with the pointer



.. rubric:: Returns:

A DPCTLSyclDeviceRef pointer to the sycl device.

.. index:: pair: function; DPCTLUSM_GetPointerType
.. _doxid-df/d6e/group___u_s_m_interface_1ga8cdbaff72515ca1f9caa745cf342f5cc:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`DPCTL_API<doxid-d3/daa/_dll_export_8h_1aed0c117c235d99c414e0b5033d096785>` :ref:`DPCTLSyclUSMType<doxid-d3/d94/dpctl__sycl__enum__types_8h_1a61bd8b72de91212af565a9be9b913844>`
	DPCTLUSM_GetPointerType(
		:ref:`__dpctl_keep<doxid-d2/d43/group___memory_semantics_1gadd48a0161309931574aed2025a16ade7>` const :ref:`DPCTLSyclUSMRef<doxid-df/d57/dpctl__sycl__types_8h_1a8c78ad1413045f90e15f5b6a2727d2e6>` MRef,
		:ref:`__dpctl_keep<doxid-d2/d43/group___memory_semantics_1gadd48a0161309931574aed2025a16ade7>` const :ref:`DPCTLSyclContextRef<doxid-df/d57/dpctl__sycl__types_8h_1accf78808322af80b73da617cb2f15f08>` CRef
		)

Returns the USM allocator type for a pointer.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- MRef

		- USM allocated pointer

	*
		- CRef

		- Sycl context reference associated with the pointer



.. rubric:: Returns:

DPCTLSyclUSMType enum value indicating if the pointer is of USM type "shared", "host", or "device".