Add a new extension: VK_EXT_map_memory_placed

appendices/VK_EXT_map_memory_placed.txt

@@ -0,0 +1,48 @@
+// Copyright 2017-2022 The Khronos Group Inc.
+//
+// SPDX-License-Identifier: CC-BY-4.0
+
+include::{generated}/meta/{refprefix}VK_EXT_map_memory_placed.txt[]
+
+=== Other Extension Metadata
+
+*Last Modified Date*::
+    2022-07-28
+*IP Status*::
+    No known IP claims.
+*Interactions and External Dependencies*::
+  - Interacts with apitext:VK_EXT_external_memory_host
+*Contributors*::
+  - Jason Ekstrand, Collabora
+  - Tobias Hector, AMD
+  - Georg Lehmann, Valve
+  - Derek Lesho, Codeweavers
+
+=== Description
+
+This extension allows a client to request that flink:vkMapMemory2EXT
+attempt to place the memory map at a particular virtual address.
+
+include::{generated}/interfaces/VK_EXT_map_memory_placed.txt[]
+
+=== 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:vkMapMemory2EXT 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
+`vkUnmapMemory2EXT()`, 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.
+
+=== Version History
+
+  * Revision 0, 2022-07-27 (Jason Ekstrand)
+  ** Internal revisions

chapters/features.txt

@@ -5451,6 +5451,33 @@ include::{generated}/validity/structs/VkPhysicalDeviceImageProcessingFeaturesQCO
 --
 endif::VK_QCOM_image_processing[]
 
+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.txt[]
+
+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.txt[tag=features]
+
+include::{generated}/validity/structs/VkPhysicalDeviceMapMemoryPlacedFeaturesEXT.txt[]
+--
+endif::VK_EXT_map_memory_placed[]
+
 
 [[features-requirements]]
 == Feature Requirements
@@ -5968,6 +5995,10 @@ ifdef::VK_EXT_attachment_feedback_loop_layout[]
     pname:attachmentFeedbackLoopLayout>>, if the
     `apiext:VK_EXT_attachment_feedback_loop_layout` extension is supported.
 endif::VK_EXT_attachment_feedback_loop_layout[]
+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.txt

@@ -3370,6 +3370,29 @@ include::{generated}/validity/structs/VkPhysicalDevicePipelineRobustnessProperti
 --
 endif::VK_EXT_pipeline_robustness[]
 
+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.txt[]
+
+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.txt[tag=limits_desc]
+
+include::{generated}/validity/structs/VkPhysicalDeviceMapMemoryPlacedPropertiesEXT.txt[]
+--
+endif::VK_EXT_map_memory_placed[]
+
 [[limits-minmax]]
 == Limit Requirements
 
@@ -4030,6 +4053,9 @@ ifdef::VK_QCOM_image_processing[]
 | pname:maxBlockMatchRegion             | - | (64,64) | min
 | pname:maxBoxFilterBlockSize           | - | (64,64) | min
 endif::VK_QCOM_image_processing[]
+ifdef::VK_EXT_map_memory_placed[]
+| pname:minPlacedMemoryMapAlignment     | - | 65536 | max
+endif::VK_EXT_map_memory_placed[]
 |====
 
 1::

chapters/memory.txt

@@ -3018,7 +3018,8 @@ include::{generated}/api/protos/vkMapMemory.txt[]
   * 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.
-  * pname:flags is reserved for future use.
+  * pname:flags is a bitmask of elink:VkMemoryMapFlagBits specifying
+    additional parameters of the memory map operation.
   * pname:ppData is a pointer to a `void *` variable in which is returned a
     host-accessible pointer to the beginning of the mapped range.
     This pointer minus pname:offset must: be aligned to at least
@@ -3096,17 +3097,35 @@ 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.txt[]
 --
 
-[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:VkMemoryMapInfoEXT::pname:flags, specifying additional properties of
+a memory map, are:
+
+include::{generated}/api/enums/VkMemoryMapFlagBits.txt[]
+
+  * ename:VK_MEMORY_MAP_PLACED_BIT_EXT requests that the implementation
+    attempt to place the memory map at the virtual address specified by the
+    client via pname:ppData.
+--
+endif::VK_EXT_map_memory_placed[]
+
+[open,refpage='VkMemoryMapFlags',desc='Bitmask of VkMemoryMapFlagBits',type='flags']
 --
 include::{generated}/api/flags/VkMemoryMapFlags.txt[]
 
-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_EXT_map_memory2[]
@@ -3148,7 +3167,8 @@ include::{generated}/api/structs/VkMemoryMapInfoEXT.txt[]
   * 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.
-  * pname:flags is reserved for future use.
+  * pname:flags is a bitmask of elink:VkMemoryMapFlagBits specifying
+    additional parameters of the memory map operation.
 
 .Valid Usage
 ****
@@ -3163,12 +3183,89 @@ include::{generated}/api/structs/VkMemoryMapInfoEXT.txt[]
 ifdef::VK_KHR_device_group[]
   * 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
+  * 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/VkMemoryMapInfoEXT.txt[]
 --
 endif::VK_EXT_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:VkMemoryMapInfoEXT::pname:flags and the pname:pNext chain of
+slink:VkMemoryMapInfoEXT includes a sname:VkMemoryMapPlacedInfoEXT
+structure, then that structure specifies the placement address of the
+memory map.
+The implementation will attempt to place the memory map at
+that address.
+If successful, pname:ppData will be set to the same value as
+sname:VkMemoryMapPlacedInfoEXT::pname:pPlacedAddress and
+fname:vkMapMemory2EXT 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:vkMapMemory2EXT will
+return ename:VK_ERROR_MEMORY_MAP_FAILED.
+
+[NOTE]
+.Note
+====
+In order for a placed map to succeed, the client may: first have to reserve
+the virtual address range via a platform-specific mechanism.
+====
+
+The sname:VkMemoryMapPlacedInfoEXT structure is defined as:
+
+include::{generated}/api/structs/VkMemoryMapPlacedInfoEXT.txt[]
+
+  * 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:VkMemoryMapInfoEXT::pname:flags does not contain
+    ename:VK_MEMORY_MAP_PLACED_BIT_EXT, this value is ignored.
+
+.Valid Usage
+****
+  * If sname:VkMemoryMapInfoEXT::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
+****
+
+include::{generated}/validity/structs/VkMemoryMapPlacedInfoEXT.txt[]
+--
+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.
@@ -3362,7 +3459,7 @@ include::{generated}/validity/protos/vkUnmapMemory.txt[]
 --
 
 ifdef::VK_EXT_map_memory2[]
-[open,refpage='vkUnmapMemory2EXT',desc=Unmap a previously mapped memory object',type='protos']
+[open,refpage='vkUnmapMemory2EXT',desc='Unmap a previously mapped memory object',type='protos']
 --
 Alternatively, to unmap a memory object once host access to it is no longer
 needed by the application, call:
@@ -3390,22 +3487,58 @@ include::{generated}/api/structs/VkMemoryUnmapInfoEXT.txt[]
   * pname:pNext is `NULL` or a pointer to a structure extending this
     structure.
   * pname:memory is the slink:VkDeviceMemory object to be unmapped.
-  * pname:flags is reserved for future use.
+  * pname:flags is a bitmask of elink:VkMemoryUnmapFlagBitsEXT specifying
+    additional parameters of the memory map operation.
 
 .Valid Usage
 ****
   * 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/VkMemoryUnmapInfoEXT.txt[]
 --
 
-[open,refpage='VkMemoryUnmapFlagsEXT',desc='Reserved for future use',type='flags']
+ifdef::VK_EXT_map_memory_placed[]
+[open,refpage='VkMemoryUnmapFlagBitsEXT',desc='Bitmask specifying additional parameters of a memory unmap',type='enums']
+--
+Bits which can: be set in slink:VkMemoryUnmapInfoEXT::pname:flags, specifying
+additional properties of a memory unmap, are:
+
+include::{generated}/api/enums/VkMemoryUnmapFlagBitsEXT.txt[]
+
+  * ename:VK_MEMORY_UNMAP_RESERVE_BIT_EXT requests that virtual address
+    range currently occupied by the memory map remains reserved after the
+    flink:vkUnmapMemory2EXT call completes.
+    Future system memory map operations or calls to flink:vkMapMemory or
+    flink:vkMapMemory2EXT 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:vkMapMemory2EXT 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:vkUnmapMemory2EXT will return
+    ename:VK_ERROR_MEMORY_MAP_FAILED.
+--
+endif::VK_EXT_map_memory_placed[]
+
+[open,refpage='VkMemoryUnmapFlagsEXT',desc='Bitmask of VkMemoryUnmapFlagBitsEXT',type='flags']
 --
 include::{generated}/api/flags/VkMemoryUnmapFlagsEXT.txt[]
 
-tname:VkMemoryMapFlagsEXT is a bitmask type for setting a mask, but is
-currently reserved for future use.
+tname:VkMemoryUnmapFlagsEXT is a bitmask type for setting a mask of zero or
+more elink:VkMemoryUnmapFlagBitsEXT.
 --
 endif::VK_EXT_map_memory2[]