Documentation: Clarify External Memory Mapping (sysmem) extension semantics (#477)

Resolve the open questions raised in review of the ze_external_memmap_sysmem_ext
extension by documenting the previously-unspecified behavior of mapping host
system memory into a host allocation via zeMemAllocHost:

- Alignment is the host page size, queried via OS-specific calls (no L0 query).
- The returned pointer equals pSystemMemory; the virtual address is preserved
  on both host and device.
- Any host pointer (heap, stack, or static storage) may be passed; the OS may
  fail the mapping if unsupported. Read-only memory requires the
  MEM_READ_ONLY flag.
- The underlying system memory must remain valid for the allocation's lifetime.
- Mapped ranges must not overlap.
- zeMemGetAllocProperties reports ZE_MEMORY_TYPE_HOST_IMPORTED.
- The mapping is released via zeMemFree.

Author: MichalMrozek

scripts/core/EXT_ExternalMemMap.rst

@@ -28,9 +28,19 @@ API
     * ${x}_external_memmap_sysmem_ext_desc_t
 
 Mapping External Memory to Host Allocation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Accelerator devices can map external memory as a host allocation. The ${x}_external_memmap_sysmem_ext_desc_t struct defines the system memory being mapped as part of the ${x}MemAllocHost.
-The user may use this extention to specify, as part of the pNext member of the ${x}_host_mem_alloc_desc_t , the system memory that needs to be mapped as part of the allocation being created with a call to ${x}MemAllocHost.
-For read-only system memory $(X}_HOST_MEM_ALLOC_FLAG_MEM_READ_ONLY flag should be set in ${x}_host_mem_alloc_desc_t.
+Accelerator devices can map existing host system memory into a host allocation. The ${x}_external_memmap_sysmem_ext_desc_t struct defines the system memory being mapped as part of the ${x}MemAllocHost call.
+The user may use this extension to specify, as part of the pNext member of the ${x}_host_mem_alloc_desc_t, the system memory that needs to be mapped as part of the allocation being created with a call to ${x}MemAllocHost.
+
+The following rules apply when mapping external system memory:
+
+* The ``pSystemMemory`` pointer and ``size`` must be aligned to the host page size. The host page size must be obtained using operating-system-specific calls; the mapped memory originates from the system allocator rather than from Level-Zero, so there is no Level-Zero query for this value.
+* On success, the pointer returned from ${x}MemAllocHost is identical to ``pSystemMemory``. The virtual address is preserved, so the same address is valid on both the host and the device.
+* Memory from the application's heap, stack, or statically-allocated (global) storage is supported. Support for memory obtained by other means is platform- and driver-dependent and is not guaranteed. If ``pSystemMemory`` points to a memory type that cannot be mapped, ${x}MemAllocHost returns ${X}_RESULT_ERROR_INVALID_ARGUMENT.
+* Read-only host memory can only be mapped successfully when the ${X}_HOST_MEM_ALLOC_FLAG_MEM_READ_ONLY flag is set in ${x}_host_mem_alloc_desc_t. In that case device access to the mapped memory is read-only.
+* The system memory referenced by ``pSystemMemory`` must remain valid for the entire lifetime of the resulting allocation. Freeing or unmapping the underlying system memory before the allocation is released results in undefined behavior.
+* Mapped memory ranges must not overlap. Releasing a mapping with ${x}MemFree tears down the device page-table entries for its virtual address range. Because these page tables are shared across imports, releasing a mapping that overlaps another import also tears down the overlapping device page-table entries, leaving the other allocation invalid for device access. The host system memory itself is unaffected.
+* After mapping, ${x}MemGetAllocProperties reports the allocation type as ${X}_MEMORY_TYPE_HOST_IMPORTED.
+* The mapping is released by passing the pointer to ${x}MemFree, like any other host allocation.
 

scripts/core/externalMemMap.yml

@@ -7,7 +7,7 @@
 #
 --- #--------------------------------------------------------------------------
 type: header
-desc: "Intel $OneApi Level-Zero Extension APIs for Mapping External Memory as part of host llocation"
+desc: "Intel $OneApi Level-Zero Extension APIs for Mapping External Memory as part of host allocation"
 version: "1.14"
 --- #--------------------------------------------------------------------------
 type: macro
@@ -37,7 +37,14 @@ members:
       desc: "[in] system memory pointer to map; must be page-aligned."
     - type: uint64_t
       name: size
-      desc: "[in] size of the system memory to map; must be page-aligned."
+      desc: "[in] size of the system memory to map; must be a multiple of the page size."
 details:
     - "This structure may be passed to $xMemAllocHost, via the `pNext` member of $x_host_mem_alloc_desc_t to map system memory for a host allocation."
-    - "The system memory pointer and size being mapped must be page aligned based on the supported page sizes on the device."
+    - "The `pSystemMemory` pointer and `size` being mapped must be aligned to the host page size. The host page size must be queried using operating-system-specific calls, as the mapped memory originates from the system allocator rather than from Level-Zero; there is no Level-Zero query for this value."
+    - "On success, the pointer returned from $xMemAllocHost is identical to `pSystemMemory`; the mapping preserves the virtual address, so the same address is valid on both the host and the device."
+    - "Memory from the application's heap, stack, or statically-allocated (global) storage is supported. Support for memory obtained by other means is platform- and driver-dependent and is not guaranteed. If `pSystemMemory` points to a memory type that cannot be mapped, $xMemAllocHost returns $X_RESULT_ERROR_INVALID_ARGUMENT."
+    - "Host memory that is read-only can only be mapped successfully when the $X_HOST_MEM_ALLOC_FLAG_MEM_READ_ONLY flag is set in $x_host_mem_alloc_desc_t; in that case device access to the mapped memory is read-only."
+    - "The system memory referenced by `pSystemMemory` must remain valid for the entire lifetime of the resulting allocation. Freeing or unmapping the underlying system memory before the allocation is released results in undefined behavior."
+    - "Mapped memory ranges must not overlap. Releasing a mapping with $xMemFree tears down the device page-table entries for its virtual address range. Because these page tables are shared across imports, releasing a mapping that overlaps another import also tears down the overlapping device page-table entries, leaving the other allocation invalid for device access. The host system memory itself is unaffected."
+    - "After mapping, $xMemGetAllocProperties reports the allocation type as $X_MEMORY_TYPE_HOST_IMPORTED."
+    - "The mapping is released by passing the pointer to $xMemFree, like any other host allocation."