Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add a new extension: VK_EXT_map_memory_placed #1906

Merged
merged 1 commit into from
Feb 15, 2024
Merged

Add a new extension: VK_EXT_map_memory_placed #1906

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions appendices/VK_EXT_map_memory_placed.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
// 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[]

=== Version History

* Revision 0, 2024-01-14 (Faith Ekstrand)
** Internal revisions
31 changes: 31 additions & 0 deletions chapters/features.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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:.

Expand Down
27 changes: 27 additions & 0 deletions chapters/limits.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
cubanismo marked this conversation as resolved.
Show resolved Hide resolved
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

Expand Down Expand Up @@ -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::
Expand Down
158 changes: 150 additions & 8 deletions chapters/memory.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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[]
Expand Down Expand Up @@ -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.
Expand All @@ -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
gfxstrand marked this conversation as resolved.
Show resolved Hide resolved
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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

VkPhysicalDeviceLimits::minMemoryMapAlignment in normal vkMapMemory has some other constraint for ppData and offset. Is there any interaction between it and VkPhysicalDeviceMapMemoryPlacedPropertiesEXT::minPlacedMemoryMapAlignment?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How I read it:

If minPlacedMemoryMapAlignment is just as or less granular than minMemoryMapAlignment, there is no relevant interaction here, as *ppData = pPlacedAddress, and both pPlacedAddress and offset must be aligned to minPlacedMemoryMapAlignment.

But yeah, if minPlacedMemoryMapAlignment were ever more granular, capitalising on that granularity would be illegal, because pPlacedAddress - offset still needs to align to minMemoryMapAlignment.

I can't imagine a situation where the minimum placed alignment should be more granular than normal, so I'm not sure if this actually a problem.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

minMemoryMapAlignment can be as low as 1 because the driver can fake offsets internally. In fact, Windows drivers have to because the only Windows interface for mapping GPU memory maps the whole memory object every time. With placed maps, however, you are actually restricted to the OS page size and there's no getting around that.

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
cubanismo marked this conversation as resolved.
Show resolved Hide resolved
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
cubanismo marked this conversation as resolved.
Show resolved Hide resolved
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.
gfxstrand marked this conversation as resolved.
Show resolved Hide resolved

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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does size need to be larger than the mapped range? If the size is larger than actual memory size, what's the remaining data should be? Some random data or zeroed?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why would size need to be larger, I think that's illegal:

VUID-vkMapMemory-size-00681
"If size is not equal to VK_WHOLE_SIZE, size must be less than or equal to the size of the memory minus offset"

****

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.
Expand Down Expand Up @@ -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[]

Expand Down
Loading
Loading