Documentation: Update docs on IPC/P2P Usage of Reserved Memory (#474)

Signed-off-by: Neil R. Spruit <neil.r.spruit@intel.com>

Author: nrspruit

scripts/core/EXT_IPC_MEM_HANDLE_TYPE.rst

@@ -39,6 +39,17 @@ When users are requesting IPC handles for L0 memory, there may be requirements f
 
 To facilitate this, the IPC Memory Handle Type Extension provides a mechanism to specify the type of IPC handle to be created during memory allocation or when obtaining an IPC handle for existing memory.
 
+Physical memory handles (``${x}_physical_mem_handle_t``) may be used as a source for IPC handles via
+${x}MemGetIpcHandleWithProperties. The ``ptr`` argument may be either:
+
+- A virtual address that was mapped to a physical memory object via ${x}VirtualMemMap, or
+- A value returned directly from ${x}PhysicalMemCreate.
+
+Only one physical memory object may be associated with a single IPC handle at a time. When the
+resulting IPC handle is opened in the receiving process via ${x}MemOpenIpcHandle, the driver
+assigns a new virtual address in the importing process without requiring a separate
+${x}VirtualMemReserve or ${x}VirtualMemMap call.
+
 Checking IPC Support
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -77,6 +88,65 @@ To request an IPC handle for L0 memory that is fabric accessible, the user would
 
     If the driver does not support ``ZE_IPC_MEM_HANDLE_TYPE_FLAG_FABRIC_ACCESSIBLE``, the function will return ``ZE_RESULT_ERROR_UNSUPPORTED_FEATURE``. Applications can proactively check for support by querying ``${x}_driver_ipc_properties_t`` as shown in the "Checking IPC Support" section above.
 
+Get IPC Handle from Physical Memory Example
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To obtain an IPC handle from a physical memory object, the ``ptr`` argument passed to
+${x}MemGetIpcHandleWithProperties may be either the physical memory handle cast to a pointer,
+or a virtual address previously mapped to the physical memory object via ${x}VirtualMemMap.
+The following example demonstrates the mapped VA case:
+
+**Sending process:**
+
+.. parsed-literal::
+
+    // Create a physical memory object
+    ze_physical_mem_desc_t pmemDesc = {
+        .stype = ZE_STRUCTURE_TYPE_PHYSICAL_MEM_DESC,
+        .pNext = NULL,
+        .flags = 0,
+        .size = physicalSize
+    };
+    ze_physical_mem_handle_t hPhysicalMem;
+    zePhysicalMemCreate(hContext, hDevice, &pmemDesc, &hPhysicalMem);
+
+    // Reserve VA and map the physical memory
+    void* ptr = NULL;
+    zeVirtualMemReserve(hContext, NULL, physicalSize, &ptr);
+    zeVirtualMemMap(hContext, ptr, physicalSize, hPhysicalMem, 0,
+        ZE_MEMORY_ACCESS_ATTRIBUTE_READWRITE);
+
+    // Request a fabric-accessible IPC handle for the mapped physical memory
+    ze_ipc_mem_handle_type_ext_desc_t desc = {
+        .stype = ZE_STRUCTURE_TYPE_IPC_MEM_HANDLE_TYPE_EXT_DESC,
+        .pNext = NULL,
+        .typeFlags = ZE_IPC_MEM_HANDLE_TYPE_FLAG_FABRIC_ACCESSIBLE
+    };
+    ze_ipc_mem_handle_t ipcHandle;
+    ze_result_t result = zeMemGetIpcHandleWithProperties(hContext, ptr, &ipcHandle, &desc);
+
+    // NOTE: Transferring IPC handles is not a Level Zero API. The application is responsible
+    // for sending the handle to the receiving process using its preferred out of band method
+    // (e.g., Shared memory, TCP/IP, fabric, etc.)
+
+**Receiving process:**
+
+.. parsed-literal::
+
+    // NOTE: Receiving IPC handles is not a Level Zero API. The application is responsible
+    // for receiving the handle from the sending process using its preferred out of band method
+    // (e.g., Shared memory, TCP/IP, fabric, etc.)
+    ze_ipc_mem_handle_t ipcHandle;
+
+    // Opening the handle assigns a new VA in this process for the physical memory.
+    void* remotePtr = NULL;
+    zeMemOpenIpcHandle(hContext, hDevice, ipcHandle, 0, &remotePtr);
+
+.. note::
+
+    Only one physical memory object may be mapped per IPC handle. Passing a ``ptr`` that spans
+    multiple physical memory mappings will result in an error.
+
 
 Memory Allocation Usage Example
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~