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

@@ -5427,6 +5427,30 @@ 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.
+
+:refpage: VkPhysicalDeviceMapMemoryPlacedFeaturesEXT
+include::{chapters}/features.txt[tag=features]
+
+include::{generated}/validity/structs/VkPhysicalDeviceMapMemoryPlacedFeaturesEXT.txt[]
+--
+endif::VK_EXT_map_memory_placed[]
+
 
 [[features-requirements]]
 == Feature Requirements
@@ -5939,6 +5963,10 @@ ifdef::VK_QCOM_tile_properties[]
   * <<features-tileProperties,pname:tileProperties>> if
     `apiext:VK_QCOM_tile_properties` extension is supported.
 endif::VK_QCOM_tile_properties[]
+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

@@ -3077,6 +3077,22 @@ familiar with all of the mechanisms described in the chapter on
 to maintaining memory access ordering.
 ====
 
+ifdef::VK_EXT_map_memory_placed[]
+If ename:VK_MEMORY_MAP_PLACED_BIT_EXT is set in pname:flags, the variable
+pointed to by pname:ppData instead contains the requested map address.
+The implementation will attempt to place the memory map at that address.
+If it cannot place the map at the requested address for any reason, the
+memory object is left unmapped and fname:vkMapMemory 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.
+====
+endif::VK_EXT_map_memory_placed[]
+
 .Valid Usage
 ****
   * [[VUID-vkMapMemory-memory-00678]]
@@ -3096,12 +3112,46 @@ 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[]
+  * 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 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: equal the size of pname:memory
+  * If ename:VK_MEMORY_MAP_PLACED_BIT_EXT is set in pname:flags,
+    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,
+    pname:size 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, the value
+    pointed to by pname:ppData must: be aligned to an integer multiple of
+    sname:VkPhysicalDeviceMapMemoryPlacedPropertiesEXT::pname:minPlacedMemoryMapAlignment
+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[]
 

xml/vk.xml

@@ -306,7 +306,7 @@ typedef void* <name>MTLSharedEvent_id</name>;
         <type requires="VkCommandBufferResetFlagBits"     category="bitmask">typedef <type>VkFlags</type> <name>VkCommandBufferResetFlags</name>;</type>
         <type requires="VkCommandBufferUsageFlagBits"     category="bitmask">typedef <type>VkFlags</type> <name>VkCommandBufferUsageFlags</name>;</type>
         <type requires="VkQueryPipelineStatisticFlagBits" category="bitmask">typedef <type>VkFlags</type> <name>VkQueryPipelineStatisticFlags</name>;</type>
-        <type                                             category="bitmask">typedef <type>VkFlags</type> <name>VkMemoryMapFlags</name>;</type>
+        <type requires="VkMemoryMapFlagBits"              category="bitmask">typedef <type>VkFlags</type> <name>VkMemoryMapFlags</name>;</type>
         <type requires="VkImageAspectFlagBits"            category="bitmask">typedef <type>VkFlags</type> <name>VkImageAspectFlags</name>;</type>
         <type requires="VkSparseMemoryBindFlagBits"       category="bitmask">typedef <type>VkFlags</type> <name>VkSparseMemoryBindFlags</name>;</type>
         <type requires="VkSparseImageFormatFlagBits"      category="bitmask">typedef <type>VkFlags</type> <name>VkSparseImageFormatFlags</name>;</type>
@@ -561,6 +561,7 @@ typedef void* <name>MTLSharedEvent_id</name>;
         <type name="VkFormat" category="enum"/>
         <type name="VkFormatFeatureFlagBits" category="enum"/>
         <type name="VkFrontFace" category="enum"/>
+        <type name="VkMemoryMapFlagBits" category="enum"/>
         <type name="VkImageAspectFlagBits" category="enum"/>
         <type name="VkImageCreateFlagBits" category="enum"/>
         <type name="VkImageLayout" category="enum"/>
@@ -7089,6 +7090,17 @@ typedef void* <name>MTLSharedEvent_id</name>;
             <member><type>VkExtent2D</type>                       <name>apronSize</name></member>
             <member><type>VkOffset2D</type>                       <name>origin</name></member>
         </type>
+        <type category="struct" name="VkPhysicalDeviceMapMemoryPlacedFeaturesEXT" structextends="VkPhysicalDeviceFeatures2,VkDeviceCreateInfo">
+            <member values="VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAP_MEMORY_PLACED_FEATURES_EXT"><type>VkStructureType</type> <name>sType</name></member>
+            <member optional="true"><type>void</type>*            <name>pNext</name></member>
+            <member><type>VkBool32</type>                         <name>memoryMapPlaced</name></member>
+            <member><type>VkBool32</type>                         <name>memoryMapRangePlaced</name></member>
+        </type>
+        <type category="struct" name="VkPhysicalDeviceMapMemoryPlacedPropertiesEXT" structextends="VkPhysicalDeviceProperties2">
+            <member values="VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAP_MEMORY_PLACED_PROPERTIES_EXT"><type>VkStructureType</type> <name>sType</name></member>
+            <member optional="true"><type>void</type>*            <name>pNext</name></member>
+            <member limittype="min,pot"><type>VkDeviceSize</type> <name>minPlacedMemoryMapAlignment</name></member>
+        </type>
     </types>
     <comment>Vulkan enumerant (token) definitions</comment>
 
@@ -7819,6 +7831,8 @@ typedef void* <name>MTLSharedEvent_id</name>;
         <enum bitpos="9"    name="VK_QUERY_PIPELINE_STATISTIC_TESSELLATION_EVALUATION_SHADER_INVOCATIONS_BIT" comment="Optional"/>
         <enum bitpos="10"   name="VK_QUERY_PIPELINE_STATISTIC_COMPUTE_SHADER_INVOCATIONS_BIT"                 comment="Optional"/>
     </enums>
+    <enums name="VkMemoryMapFlagBits" type="bitmask">
+    </enums>
     <enums name="VkImageAspectFlagBits" type="bitmask">
         <enum bitpos="0"    name="VK_IMAGE_ASPECT_COLOR_BIT"/>
         <enum bitpos="1"    name="VK_IMAGE_ASPECT_DEPTH_BIT"/>
@@ -12341,6 +12355,7 @@ typedef void* <name>MTLSharedEvent_id</name>;
         <require comment="Memory commands">
             <type name="VkMappedMemoryRange"/>
             <type name="VkMemoryAllocateInfo"/>
+            <type name="VkMemoryMapFlagBits"/>
             <type name="VkMemoryMapFlags"/>
             <command name="vkAllocateMemory"/>
             <command name="vkFreeMemory"/>
@@ -17227,10 +17242,15 @@ typedef void* <name>MTLSharedEvent_id</name>;
                 <enum bitpos="22" extends="VkImageUsageFlagBits"            name="VK_IMAGE_USAGE_RESERVED_22_BIT_EXT"/>
             </require>
         </extension>
-        <extension name="VK_INTEL_extension_272" number="272" type="device" author="INTEL" contact="Jason Ekstrand @jekstrand" supported="disabled">
+        <extension name="VK_EXT_map_memory_placed" number="272" type="device" author="EXT" contact="Jason Ekstrand @jekstrand" supported="vulkan">
             <require>
-                <enum value="0"                                             name="VK_INTEL_EXTENSION_272_SPEC_VERSION"/>
-                <enum value="&quot;VK_INTEL_extension_272&quot;"            name="VK_INTEL_EXTENSION_272_EXTENSION_NAME"/>
+                <enum value="0"                                         name="VK_EXT_MAP_MEMORY_PLACED_SPEC_VERSION"/>
+                <enum value="&quot;VK_EXT_map_memory_placed&quot;"      name="VK_EXT_MAP_MEMORY_PLACED_EXTENSION_NAME"/>
+                <enum offset="0" extends="VkStructureType"              name="VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAP_MEMORY_PLACED_FEATURES_EXT"/>
+                <enum offset="1" extends="VkStructureType"              name="VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MAP_MEMORY_PLACED_PROPERTIES_EXT"/>
+                <enum bitpos="0" extends="VkMemoryMapFlagBits"          name="VK_MEMORY_MAP_PLACED_BIT_EXT"/>
+                <type name="VkPhysicalDeviceMapMemoryPlacedFeaturesEXT"/>
+                <type name="VkPhysicalDeviceMapMemoryPlacedPropertiesEXT"/>
             </require>
         </extension>
         <extension name="VK_INTEL_extension_273" number="273" type="device" author="INTEL" contact="Jason Ekstrand @jekstrand" supported="disabled">