From 36bfbe40e0aa1c3d61a43417731166a25cc461b8 Mon Sep 17 00:00:00 2001
From: Hugh Delaney <hugh.delaney@codeplay.com>
Date: Thu, 4 Jan 2024 15:38:35 +0000
Subject: [PATCH] Add some description for behaviour of the
 urMemGetNativeHandle for CUDA and HIP

---
 scripts/core/CUDA.rst | 15 +++++++++++++++
 scripts/core/HIP.rst  | 16 ++++++++++++++++
 2 files changed, 31 insertions(+)

diff --git a/scripts/core/CUDA.rst b/scripts/core/CUDA.rst
index 9771693113..cca73d743e 100644
--- a/scripts/core/CUDA.rst
+++ b/scripts/core/CUDA.rst
@@ -148,6 +148,21 @@ take the extra global offset argument. Use of the global offset is not
 recommended for non SYCL compiler toolchains. This parameter can be ignored if
 the user does not wish to use the global offset.
 
+Interoperability
+================
+
+Unified Runtime offers a number of entry points in order to get native handles
+for UR objects. The native handle may refer to a number of different native CUDA
+types, depending on the entry point called.
+
+- ${x}MemGetNativeHandle stores a ``CUdeviceptr`` in the ${x}_native_handle_t
+  argument passed. The ``CUdeviceptr`` will be resident on the
+  ${x}_device_handle_t provided as an argument, if the device shares a context
+  with the ${x}_mem_handle_t. If the ${x}_device_handle_t argument passed to
+  ${x}MemGetNativeHandle is ``nullptr``,
+  ``UR_RESULT_ERROR_UNSUPPORTED_FEATURE`` will be returned.
+- TODO: add more stuff
+
 Other Notes
 ===========
 
diff --git a/scripts/core/HIP.rst b/scripts/core/HIP.rst
index 3ded0138ff..f0908ed707 100644
--- a/scripts/core/HIP.rst
+++ b/scripts/core/HIP.rst
@@ -91,6 +91,22 @@ take the extra global offset argument. Use of the global offset is not
 recommended for non SYCL compiler toolchains. This parameter can be ignored if
 the user does not wish to use the global offset.
 
+Interoperability
+================
+
+Unified Runtime offers a number of entry points in order to get native handles
+for UR objects. The native handle may refer to a number of different native HIP
+types, depending on the entry point called.
+
+- ${x}MemGetNativeHandle stores a ``hipDeviceptr_t`` in the
+  ${x}_native_handle_t argument passed. The ``hipDeviceptr_t`` will be resident
+  on the ${x}_device_handle_t provided as an argument, if the device shares a
+  context with the ${x}_mem_handle_t. If the ${x}_device_handle_t argument
+  passed to ${x}MemGetNativeHandle is ``nullptr``,
+  ``UR_RESULT_ERROR_UNSUPPORTED_FEATURE`` will be returned.
+- TODO: add more stuff
+
+
 Other Notes
 ===========