diff --git a/sycl/doc/extensions/experimental/sycl_ext_oneapi_inter_process_communication.asciidoc b/sycl/doc/extensions/experimental/sycl_ext_oneapi_inter_process_communication.asciidoc index c26faa4c2af9..81e69ee02e8b 100644 --- a/sycl/doc/extensions/experimental/sycl_ext_oneapi_inter_process_communication.asciidoc +++ b/sycl/doc/extensions/experimental/sycl_ext_oneapi_inter_process_communication.asciidoc @@ -661,6 +661,207 @@ return ipc::event::open(handle_data_view, ctxt); |==== +=== Inter-process exchange of physical memory + +This extension allows for the exchange of a physical memory handle between +processes. A given physical memory handle can be mapped into a virtual address +space in multiple processes, so the processes can access the same device +memory. + +The following aspect and set of free functions are specific to +physical memory handle sharing feature. + +==== Extension to `enum class aspect` for physical memory + +[source] +---- +namespace sycl { +enum class aspect { + ... + ext_oneapi_ipc_physical_memory +} +} +---- + +If a SYCL device has this aspect, that device supports the functions in the +`ipc::physical_memory` namespace specified in the following section. + +==== New functions associated with physical memory + +This extension adds new free functions under the `ipc::physical_memory` experimental +namespace. + +``` +namespace syclext = sycl::ext::oneapi::experimental; + +namespace sycl::ext::oneapi::experimental::ipc::physical_memory { + +handle get(syclext::physical_mem &phys_mem); + +syclext::physical_mem open(const handle_data_t &handle_data, + const sycl::context &ctx, const sycl::device &dev); + +syclext::physical_mem open(const handle_data_t &handle_data, + const sycl::device &dev); + +syclext::physical_mem open(const handle_data_t &handle_data); + +// Requires C++20 +syclext::physical_mem open(const handle_data_view_t &handle_data_view, + const sycl::context &ctx, const sycl::device &dev); + +// Requires C++20 +syclext::physical_mem open(const handle_data_view_t &handle_data_view, + const sycl::device &dev); + +// Requires C++20 +syclext::physical_mem open(const handle_data_view_t &handle_data_view); + +} +``` + +|==== +a| +[frame=all,grid=none] +!==== +a! +[source] +---- +handle get(syclext::physical_mem &phys_mem) +---- +!==== + +_Returns:_ An IPC "handle" to this physical memory object. The bytes of this +handle can be transferred to another process on the same system, and the other +process can use the handle to get a physical memory object representing the +same memory allocation through a call to the `open` function. + +_Throws:_ An exception with the `errc::feature_not_supported` error code if +the device associated with `phys_mem` does not have +`aspect::ext_oneapi_ipc_physical_memory`. + +!==== +a! +[source] +---- +syclext::physical_mem open(const handle_data_t &handle_data, + const sycl::context &ctx, const sycl::device &dev) +---- +!==== + +_Preconditions:_ `handle_data` is the IPC "handle" to a physical memory object +that was returned from a call to the `get` function either in this process or in some +other process on the same system. + +_Returns:_ A physical memory object represented by `handle_data`. The returned +object is associated with context `ctx` and device `dev`. + +[_Note:_ The `open` function can be called multiple times on the same handle +within the same process. Each call to the `open` function may return a unique +physical memory object even for the same handle. +_{endnote}_] + +[_Note:_ The physical memory object returned from a call to the `open` function +is no longer valid if the original object associated with `handle_data` (passed +to a `get` function call) is destroyed. +_{endnote}_] + +_Throws:_ + + * An exception with the `errc::feature_not_supported` error code if device + `dev` does not have `aspect::ext_oneapi_ipc_physical_memory`. + * An exception with the `errc::invalid` error code if the handle data + `handle_data` has an unexpected number of bytes. + * An exception with the `errc::invalid` error code if `ctx` does not contain + `dev`. + +!==== +a! +[source] +---- +syclext::physical_mem open(const handle_data_t &handle_data, + const sycl::device &dev) +---- +!==== + +_Effects:_ Equivalent to: + +[source,c++,indent=2] +---- +sycl::context ctxt = dev.get_platform().khr_get_default_context(); +return ipc::physical_memory::open(handle_data, ctxt, dev); +---- + +!==== +a! +[source] +---- +syclext::physical_mem open(const handle_data_t &handle_data) +---- +!==== + +_Effects:_ Equivalent to: + +[source,c++,indent=2] +---- +sycl::device d; +sycl::context ctxt = d.get_platform().khr_get_default_context(); +return ipc::physical_memory::open(handle_data, ctxt, d); +---- + +!==== +a! +[source] +---- +syclext::physical_mem open(const handle_data_view_t &handle_data_view, + const sycl::context &ctx, const sycl::device &dev) +---- +!==== + +_Effects:_ Equivalent to: + +[source,c++,indent=2] +---- +handle_data_t handle_data{handle_data_view.begin(), handle_data_view.end()}; +return ipc::physical_memory::open(handle_data, ctx, dev); +---- + +!==== +a! +[source] +---- +syclext::physical_mem open(const handle_data_view_t &handle_data_view, + const sycl::device &dev) +---- +!==== + +_Effects:_ Equivalent to: + +[source,c++,indent=2] +---- +sycl::context ctxt = dev.get_platform().khr_get_default_context(); +return ipc::physical_memory::open(handle_data_view, ctxt, dev); +---- + +!==== +a! +[source] +---- +syclext::physical_mem open(const handle_data_view_t &handle_data_view) +---- +!==== + +_Effects:_ Equivalent to: + +[source,c++,indent=2] +---- +sycl::device d; +sycl::context ctxt = d.get_platform().khr_get_default_context(); +return ipc::physical_memory::open(handle_data_view, ctxt, d); +---- + +|==== + === Backward compatibility To provide backward compatibility of the extension API, the extension defines