Add a new extension: VK_EXT_map_memory_placed

appendices/VK_EXT_map_memory_placed.adoc

@@ -0,0 +1,61 @@
+// Copyright 2022-2023 The Khronos Group Inc.
+//
+// SPDX-License-Identifier: CC-BY-4.0
+
+include::{generated}/meta/{refprefix}VK_EXT_map_memory_placed.adoc[]
+
+=== Other Extension Metadata
+
+*Last Modified Date*::
+    2023-03-21
+*IP Status*::
+    No known IP claims.
+*Interactions and External Dependencies*::
+  - Depends on apitext:VK_KHR_map_memory2
+  - Interacts with apitext:VK_EXT_external_memory_host
+*Contributors*::
+  - Faith Ekstrand, Collabora
+  - Tobias Hector, AMD
+  - James Jones, NVIDIA
+  - Georg Lehmann, Valve
+  - Derek Lesho, Codeweavers
+
+=== Description
+
+This extension allows a client to request that flink:vkMapMemory2KHR
+attempt to place the memory map at a particular virtual address.
+
+include::{generated}/interfaces/VK_EXT_map_memory_placed.adoc[]
+
+=== Issues
+
+1) What should happen if the implementation cannot place the memory map at
+the requested address?
+
+*RESOLVED*: The memory object should be left unmapped and
+flink:vkMapMemory2KHR should return ename:VK_ERROR_MEMORY_MAP_FAILED.
+
+2) How can a client atomically re-reserve the address range on unmap?
+
+*RESOLVED*: When `VK_MEMORY_UNMAP_RESERVE_BIT_EXT` is passed to
+`vkUnmapMemory2KHR()`, the implementation unmaps the memory range in such a
+way that the range is automatically re-reserved.  With `mmap()`, this is
+accomplished by simply mapping over the range with another anonymous
+mapping.  However, allowing this with `vkMapMemory()` would break Vulkan's
+concept of when a memory object is or is not mapped.
+
+3) Should a placed memory map replace existing maps in the specified
+range or fail if a map exists?
+
+*RESOLVED*: It should replace existing maps.  The client can get try
+behavior by using mmap with `MAP_ANONYMOUS` and an address and only call
+`vkMapMemory2KHR()` to do a placed map if that succeeds.  Without
+replacement, there is no way for the application to atomically exchange
+maps and prevent races between reservation and the final map.  Also, any
+attempt at a middle ground in which it might replace would make the spec
+less well-defined.
+
+=== Version History
+
+  * Revision 0, 2022-07-27 (Faith Ekstrand)
+  ** Internal revisions

chapters/features.adoc

@@ -7529,6 +7529,33 @@ include::{generated}/validity/structs/VkPhysicalDeviceShaderQuadControlFeaturesK
 --
 endif::VK_KHR_shader_quad_control[]
 
+ifdef::VK_EXT_map_memory_placed[]
+[open,refpage='VkPhysicalDeviceMapMemoryPlacedFeaturesEXT',desc='Structure describing placed memory map features that can be supported by an implementation',type='structs']
+--
+The sname:VkPhysicalDeviceMapMemoryPlacedFeaturesEXT structure is defined
+as:
+
+include::{generated}/api/structs/VkPhysicalDeviceMapMemoryPlacedFeaturesEXT.adoc[]
+
+This structure describes the following features:
+
+  * [[features-memoryMapPlaced]] pname:memoryMapPlaced indicates that
+    the implementation supports placing memory maps at client-specified
+    virtual addresses.
+  * [[features-memoryMapRangePlaced]] pname:memoryMapRangePlaced indicates
+    that the implementation supports placing memory maps of a subrange of a
+    memory object at client-specified virtual addresses.
+  * [[features-memoryUnmapReserve]] pname:memoryUnmapReserve
+    indicates that the implementation supports leaving the memory range
+    reserved when unmapping a memory object.
+
+:refpage: VkPhysicalDeviceMapMemoryPlacedFeaturesEXT
+include::{chapters}/features.adoc[tag=features]
+
+include::{generated}/validity/structs/VkPhysicalDeviceMapMemoryPlacedFeaturesEXT.adoc[]
+--
+endif::VK_EXT_map_memory_placed[]
+
 
 [[features-requirements]]
 == Feature Requirements
@@ -8439,6 +8466,10 @@ ifdef::VK_KHR_shader_quad_control[]
   * <<features-shaderQuadControl, pname:shaderQuadControl>>, if the
     `apiext:VK_KHR_shader_quad_control` extension is supported.
 endif::VK_KHR_shader_quad_control[]
+ifdef::VK_EXT_map_memory_placed[]
+  * <<features-memoryMapPlaced, pname:memoryMapPlaced>> if the
+    `apiext:VK_EXT_map_memory_placed` extension is supported.
+endif::VK_EXT_map_memory_placed[]
 
 All other features defined in the Specification are optional:.
 

chapters/limits.adoc

@@ -4566,6 +4566,30 @@ include::{generated}/validity/structs/VkPhysicalDeviceRenderPassStripedPropertie
 
 endif::VK_ARM_render_pass_striped[]
 
+ifdef::VK_EXT_map_memory_placed[]
+[open,refpage='VkPhysicalDeviceMapMemoryPlacedPropertiesEXT',desc='Structure describing the alignment requirements of placed memory maps for a physical device',type='structs']
+--
+The sname:VkPhysicalDeviceMapMemoryPlacedPropertiesEXT structure is
+defined as:
+
+include::{generated}/api/structs/VkPhysicalDeviceMapMemoryPlacedPropertiesEXT.adoc[]
+
+The members of the sname:VkPhysicalDeviceMapMemoryPlacedPropertiesEXT
+structure describe the following:
+
+  * [[limits-minPlacedMemoryMapAlignment]]
+    pname:minPlacedMemoryMapAlignment is the minimum alignment required for
+    memory object offsets and virtual address ranges when using placed
+    memory mapping.
+
+:refpage: VkPhysicalDeviceMapMemoryPlacedPropertiesEXT
+include::{chapters}/limits.adoc[tag=limits_desc]
+
+include::{generated}/validity/structs/VkPhysicalDeviceMapMemoryPlacedPropertiesEXT.adoc[]
+--
+endif::VK_EXT_map_memory_placed[]
+
+
 [[limits-minmax]]
 == Limit Requirements
 
@@ -5472,6 +5496,9 @@ ifdef::VK_ARM_render_pass_striped[]
 | pname:renderPassStripeGranularity               | - | (64,64) | max
 | pname:maxRenderPassStripes                      | - | 32 | min
 endif::VK_ARM_render_pass_striped[]
+ifdef::VK_EXT_map_memory_placed[]
+| pname:minPlacedMemoryMapAlignment     | - | 65536 | max
+endif::VK_EXT_map_memory_placed[]
 |====
 
 1::

chapters/memory.adoc

@@ -3490,7 +3490,13 @@ include::{generated}/api/protos/vkMapMemory.adoc[]
   * pname:size is the size of the memory range to map, or
     ename:VK_WHOLE_SIZE to map from pname:offset to the end of the
     allocation.
+ifndef::VK_EXT_map_memory_placed[]
   * pname:flags is reserved for future use.
+endif::VK_EXT_map_memory_placed[]
+ifdef::VK_EXT_map_memory_placed[]
+  * pname:flags is a bitmask of elink:VkMemoryMapFlagBits specifying
+    additional parameters of the memory map operation.
+endif::VK_EXT_map_memory_placed[]
   * pname:ppData is a pointer to a code:void* variable in which a
     host-accessible pointer to the beginning of the mapped range is
     returned.
@@ -3576,17 +3582,38 @@ ifdef::VK_KHR_device_group[]
   * [[VUID-vkMapMemory-memory-00683]]
     pname:memory must: not have been allocated with multiple instances
 endif::VK_KHR_device_group[]
+ifdef::VK_EXT_map_memory_placed[]
+  * ename:VK_MEMORY_MAP_PLACED_BIT_EXT must: not be set in pname:flags
+endif::VK_EXT_map_memory_placed[]
 ****
 
 include::{generated}/validity/protos/vkMapMemory.adoc[]
 --
 
-[open,refpage='VkMemoryMapFlags',desc='Reserved for future use',type='flags']
+ifdef::VK_EXT_map_memory_placed[]
+[open,refpage='VkMemoryMapFlagBits',desc='Bitmask specifying additional parameters of a memory map',type='enums']
+--
+Bits which can: be set in flink:vkMapMemory::pname:flags and
+slink:VkMemoryMapInfoKHR::pname:flags, specifying additional properties of
+a memory map, are:
+
+include::{generated}/api/enums/VkMemoryMapFlagBits.adoc[]
+
+  * ename:VK_MEMORY_MAP_PLACED_BIT_EXT requests that the implementation
+    place the memory map at the virtual address specified by the client via
+    slink:VkMemoryMapPlacedInfoEXT::pname:pPlacedAddress, replacing any
+    existing mapping at that address.
+    This flag must: not be used with flink:vkMapMemory as there is no way
+    to specify the placement address.
+--
+endif::VK_EXT_map_memory_placed[]
+
+[open,refpage='VkMemoryMapFlags',desc='Bitmask of VkMemoryMapFlagBits',type='flags']
 --
 include::{generated}/api/flags/VkMemoryMapFlags.adoc[]
 
-tname:VkMemoryMapFlags is a bitmask type for setting a mask, but is
-currently reserved for future use.
+tname:VkMemoryMapFlags is a bitmask type for setting a mask of zero or more
+elink:VkMemoryMapFlagBits.
 --
 
 ifdef::VK_KHR_map_memory2[]
@@ -3622,7 +3649,8 @@ include::{generated}/api/structs/VkMemoryMapInfoKHR.adoc[]
   * pname:sType is a elink:VkStructureType value identifying this structure.
   * pname:pNext is `NULL` or a pointer to a structure extending this
     structure.
-  * pname:flags is reserved for future use.
+  * pname:flags is a bitmask of elink:VkMemoryMapFlagBits specifying
+    additional parameters of the memory map operation.
   * pname:memory is the slink:VkDeviceMemory object to be mapped.
   * pname:offset is a zero-based byte offset from the beginning of the
     memory object.
@@ -3649,12 +3677,90 @@ ifdef::VK_KHR_device_group[]
   * [[VUID-VkMemoryMapInfoKHR-memory-07963]]
     pname:memory must: not have been allocated with multiple instances
 endif::VK_KHR_device_group[]
+ifdef::VK_EXT_map_memory_placed[]
+  * If ename:VK_MEMORY_MAP_PLACED_BIT_EXT is set in pname:flags, the
+    <<features-memoryMapPlaced, pname:memoryMapPlaced>> feature must: be
+    enabled
+  * If ename:VK_MEMORY_MAP_PLACED_BIT_EXT is set in pname:flags, the
+    pname:pNext chain must: include a slink:VkMemoryMapPlacedInfoEXT
+    structure and sname:VkMemoryMapPlacedInfoEXT::pname:pPlacedAddress
+    must: not be `NULL`
+  * If ename:VK_MEMORY_MAP_PLACED_BIT_EXT is set in pname:flags and the
+    <<features-memoryMapRangePlaced, pname:memoryMapRangePlaced>> feature
+    is not enabled, pname:offset must: be zero
+  * If ename:VK_MEMORY_MAP_PLACED_BIT_EXT is set in pname:flags and the
+    <<features-memoryMapRangePlaced, pname:memoryMapRangePlaced>> feature
+    is not enabled, pname:size must: be ename:VK_WHOLE_SIZE
+  * If ename:VK_MEMORY_MAP_PLACED_BIT_EXT is set in pname:flags and the
+    <<features-memoryMapRangePlaced, pname:memoryMapRangePlaced>> feature
+    is enabled, pname:offset must: be aligned to an integer multiple of
+    sname:VkPhysicalDeviceMapMemoryPlacedPropertiesEXT::pname:minPlacedMemoryMapAlignment
+  * If ename:VK_MEMORY_MAP_PLACED_BIT_EXT is set in pname:flags and the
+    <<features-memoryMapRangePlaced, pname:memoryMapRangePlaced>> feature
+    is enabled, pname:size must: be ename:VK_WHOLE_SIZE or be aligned to an
+    integer multiple of
+    sname:VkPhysicalDeviceMapMemoryPlacedPropertiesEXT::pname:minPlacedMemoryMapAlignment
+ifdef::VK_EXT_external_memory_host[]
+  * If ename:VK_MEMORY_MAP_PLACED_BIT_EXT is set in pname:flags, the memory
+    object must: not have been imported from a handle type of
+    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT or
+    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT
+endif::VK_EXT_external_memory_host[]
+endif::VK_EXT_map_memory_placed[]
 ****
 
 include::{generated}/validity/structs/VkMemoryMapInfoKHR.adoc[]
 --
 endif::VK_KHR_map_memory2[]
 
+ifdef::VK_EXT_map_memory_placed[]
+[open,refpage='VkMemoryMapPlacedInfoEXT',desc='Structure containing memory map placement parameters',type='structs']
+--
+If ename:VK_MEMORY_MAP_PLACED_BIT_EXT is set in
+sname:VkMemoryMapInfoKHR::pname:flags and the pname:pNext chain of
+slink:VkMemoryMapInfoKHR includes a sname:VkMemoryMapPlacedInfoEXT
+structure, then that structure specifies the placement address of the
+memory map.
+The implementation will place the memory map at the specified address,
+replacing any existing maps in the specified memory range.
+Replacing memory maps in this way does not implicitly unmap Vulkan memory
+objects.
+Instead, the client must: ensure no other Vulkan memory objects are mapped
+anywhere in the specified virtual address range.
+If successful, pname:ppData will be set to the same value as
+sname:VkMemoryMapPlacedInfoEXT::pname:pPlacedAddress and
+fname:vkMapMemory2KHR will return ename:VK_SUCCESS.
+If it cannot place the map at the requested address for any
+reason, the memory object is left unmapped and fname:vkMapMemory2KHR will
+return ename:VK_ERROR_MEMORY_MAP_FAILED.
+
+The sname:VkMemoryMapPlacedInfoEXT structure is defined as:
+
+include::{generated}/api/structs/VkMemoryMapPlacedInfoEXT.adoc[]
+
+  * pname:sType is the type of this structure.
+  * pname:pNext is `NULL` or a pointer to a structure extending this
+    structure.
+  * pname:pPlacedAddress is the virtual address at which to place the
+    address.  If sname:VkMemoryMapInfoKHR::pname:flags does not contain
+    ename:VK_MEMORY_MAP_PLACED_BIT_EXT, this value is ignored.
+
+.Valid Usage
+****
+  * If sname:VkMemoryMapInfoKHR::pname:flags contains
+    ename:VK_MEMORY_MAP_PLACED_BIT_EXT, pname:pPlacedAddress must: not be
+    `NULL`
+  * pname:pPlacedAddress must: be aligned to an integer multiple of
+    sname:VkPhysicalDeviceMapMemoryPlacedPropertiesEXT::pname:minPlacedMemoryMapAlignment
+  * The address range specified by pname:pPlacedAddress and
+    sname:VkMemoryMapInfoKHR::pname:size must: not overlap any existing
+    Vulkan memory object mapping.
+****
+
+include::{generated}/validity/structs/VkMemoryMapPlacedInfoEXT.adoc[]
+--
+endif::VK_EXT_map_memory_placed[]
+
 Two commands are provided to enable applications to work with non-coherent
 memory allocations: fname:vkFlushMappedMemoryRanges and
 fname:vkInvalidateMappedMemoryRanges.
@@ -3889,24 +3995,60 @@ include::{generated}/api/structs/VkMemoryUnmapInfoKHR.adoc[]
   * pname:sType is a elink:VkStructureType value identifying this structure.
   * pname:pNext is `NULL` or a pointer to a structure extending this
     structure.
-  * pname:flags is reserved for future use.
+  * pname:flags is a bitmask of elink:VkMemoryUnmapFlagBitsKHR specifying
+    additional parameters of the memory map operation.
   * pname:memory is the slink:VkDeviceMemory object to be unmapped.
 
 .Valid Usage
 ****
   * [[VUID-VkMemoryUnmapInfoKHR-memory-07964]]
     pname:memory must: be currently host mapped
+ifdef::VK_EXT_map_memory_placed[]
+  * If ename:VK_MEMORY_UNMAP_RESERVE_BIT_EXT is set in pname:flags,
+    the <<features-memoryUnmapReserve, pname:memoryUnmapReserve>>
+    must: be enabled
+ifdef::VK_EXT_external_memory_host[]
+  * If ename:VK_MEMORY_UNMAP_RESERVE_BIT_EXT is set in pname:flags, the
+    memory object must: not have been imported from a handle type of
+    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT or
+    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT
+endif::VK_EXT_external_memory_host[]
+endif::VK_EXT_map_memory_placed[]
 ****
 
 include::{generated}/validity/structs/VkMemoryUnmapInfoKHR.adoc[]
 --
 
-[open,refpage='VkMemoryUnmapFlagsKHR',desc='Reserved for future use',type='flags']
+ifdef::VK_EXT_map_memory_placed[]
+[open,refpage='VkMemoryUnmapFlagBitsKHR',desc='Bitmask specifying additional parameters of a memory unmap',type='enums']
+--
+Bits which can: be set in slink:VkMemoryUnmapInfoKHR::pname:flags, specifying
+additional properties of a memory unmap, are:
+
+include::{generated}/api/enums/VkMemoryUnmapFlagBitsKHR.adoc[]
+
+  * ename:VK_MEMORY_UNMAP_RESERVE_BIT_EXT requests that virtual address
+    range currently occupied by the memory map remain reserved after the
+    flink:vkUnmapMemory2KHR call completes.
+    Future system memory map operations or calls to flink:vkMapMemory or
+    flink:vkMapMemory2KHR will not return addresses in that range unless
+    the range has since been unreserved by the client or the mapping is
+    explicitly placed in that range by calling flink:vkMapMemory2KHR with
+    ename:VK_MEMORY_MAP_PLACED_BIT_EXT, or doing the system memory map
+    equivalent.
+    When ename:VK_MEMORY_UNMAP_RESERVE_BIT_EXT is set, the memory unmap
+    operation may: fail, in which case the memory object will remain host
+    mapped and flink:vkUnmapMemory2KHR will return
+    ename:VK_ERROR_MEMORY_MAP_FAILED.
+--
+endif::VK_EXT_map_memory_placed[]
+
+[open,refpage='VkMemoryUnmapFlagsKHR',desc='Bitmask of VkMemoryUnmapFlagBitsKHR',type='flags']
 --
 include::{generated}/api/flags/VkMemoryUnmapFlagsKHR.adoc[]
 
-tname:VkMemoryMapFlagsKHR is a bitmask type for setting a mask, but is
-currently reserved for future use.
+tname:VkMemoryUnmapFlagsKHR is a bitmask type for setting a mask of zero or
+more elink:VkMemoryUnmapFlagBitsKHR.
 --
 endif::VK_KHR_map_memory2[]