Add a new extension: VK_EXT_map_memory_placed

appendices/VK_EXT_map_memory_placed.txt

@@ -0,0 +1,34 @@
+// 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.
+*Contributors*::
+  - Jason Ekstrand, Collabora
+
+=== Description
+
+This extension allows a client to request that flink:vkMapMemory 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?
+
+*PROPOSED*: The memory object should be left unmapped and flink:vkMapMemory
+should return ename:VK_ERROR_MEMORY_MAP_FAILED.
+
+=== 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 atomically re-reserving
+    memory ranges on unmap.
+
+: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,28 @@ 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 by
+    placed memory maps.
+
+: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 +4052,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

@@ -3096,17 +3096,34 @@ 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, 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[]
@@ -3163,12 +3180,85 @@ 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
+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`
+  * If sname:VkMemoryMapInfoEXT::pname:flags contains
+    ename:VK_MEMORY_MAP_PLACED_BIT_EXT, 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 +3452,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:
@@ -3394,17 +3484,44 @@ include::{generated}/api/structs/VkMemoryUnmapInfoEXT.txt[]
 .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
+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 be atomically re-reserved as
+    part of the memory unmap operation.
+    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 memory map
+    operation is done with ename:VK_MEMORY_MAP_PLACED_BIT_EXT or the system
+    memory map equivalent.
+    If the implementation fails to re-reserve the address range, 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[]