1// Copyright (c) 2021 Google Inc.
2//
3// SPDX-License-Identifier: CC-BY-4.0
4
5[[fuchsia-external-memory]]
6=== Fuchsia External Memory
7
8On Fuchsia, when allocating memory that may: be imported from another
9device, process or Vulkan instance, add a
10slink:VkImportMemoryZirconHandleInfoFUCHSIA structure to the pname:pNext
11chain of the slink:VkMemoryAllocateInfo structure.
12
13External memory on Fuchsia is imported and exported using VMO handles of
14type code:zx_handle_t.
15VMO handles to external memory are canonically obtained from Fuchsia's
16Sysmem service or from syscalls such as sname:zx_vmo_create().
17VMO handles for import can also be obtained by exporting them from another
18Vulkan instance as described in <<exporting-fuchsia-device-memory,exporting
19fuchsia device memory>>.
20
21Importing VMO handles to the Vulkan instance transfers ownership of the
22handle to the instance from the application.
23The application must: not perform any operations on the handle after
24successful import.
25
26Applications can: import the same underlying memory into multiple instances
27of Vulkan, into the same instance from which it was exported, and multiple
28times into a given Vulkan instance.
29In all cases, each import operation must: create a distinct
30sname:VkDeviceMemory object.
31
32
33[[importing-fuchsia-external-memory]]
34==== Importing Fuchsia External Memory
35
36[open,refpage='VkImportMemoryZirconHandleInfoFUCHSIA',desc='Structure specifying import parameters for Zircon handle to external memory',type='structs']
37--
38The sname:VkImportMemoryZirconHandleInfoFUCHSIA structure is defined as:
39
40include::{generated}/api/structs/VkImportMemoryZirconHandleInfoFUCHSIA.adoc[]
41
42  * pname:sType is a elink:VkStructureType value identifying this structure.
43  * pname:pNext is `NULL` or a pointer to a structure extending this
44    structure.
45  * pname:handleType is a elink:VkExternalMemoryHandleTypeFlagBits value
46    specifying the type of pname:handle.
47  * pname:handle is a code:zx_handle_t (Zircon) handle to the external
48    memory.
49
50.Valid Usage
51****
52  * [[VUID-VkImportMemoryZirconHandleInfoFUCHSIA-handleType-04771]]
53    pname:handleType must: be
54    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ZIRCON_VMO_BIT_FUCHSIA
55  * [[VUID-VkImportMemoryZirconHandleInfoFUCHSIA-handle-04772]]
56    pname:handle must be a valid VMO handle
57****
58
59include::{generated}/validity/structs/VkImportMemoryZirconHandleInfoFUCHSIA.adoc[]
60--
61
62[open,refpage='vkGetMemoryZirconHandlePropertiesFUCHSIA',desc='Get a Zircon handle properties for an external memory object',type='protos']
63--
64To obtain the memoryTypeIndex for the slink:VkMemoryAllocateInfo structure,
65call fname:vkGetMemoryZirconHandlePropertiesFUCHSIA:
66
67include::{generated}/api/protos/vkGetMemoryZirconHandlePropertiesFUCHSIA.adoc[]
68
69  * pname:device is the slink:VkDevice.
70  * pname:handleType is a elink:VkExternalMemoryHandleTypeFlagBits value
71    specifying the type of pname:zirconHandle
72  * pname:zirconHandle is a code:zx_handle_t (Zircon) handle to the external
73    resource.
74  * pname:pMemoryZirconHandleProperties is a pointer to a
75    slink:VkMemoryZirconHandlePropertiesFUCHSIA structure in which the
76    result will be stored.
77
78.Valid Usage
79****
80  * [[VUID-vkGetMemoryZirconHandlePropertiesFUCHSIA-handleType-04773]]
81    pname:handleType must: be
82    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ZIRCON_VMO_BIT_FUCHSIA
83  * [[VUID-vkGetMemoryZirconHandlePropertiesFUCHSIA-zirconHandle-04774]]
84    pname:zirconHandle must reference a valid VMO
85****
86
87include::{generated}/validity/protos/vkGetMemoryZirconHandlePropertiesFUCHSIA.adoc[]
88--
89
90[open,refpage='VkMemoryZirconHandlePropertiesFUCHSIA',desc='Structure specifying Zircon handle compatible external memory',type='structs']
91--
92The sname:VkMemoryZirconHandlePropertiesFUCHSIA structure is defined as:
93
94include::{generated}/api/structs/VkMemoryZirconHandlePropertiesFUCHSIA.adoc[]
95
96  * pname:sType is a elink:VkStructureType value identifying this structure.
97  * pname:pNext is `NULL` or a pointer to a structure extending this
98    structure.
99  * pname:memoryTypeBits a bitmask containing one bit set for every memory
100    type which the specified handle can be imported as.
101
102include::{generated}/validity/structs/VkMemoryZirconHandlePropertiesFUCHSIA.adoc[]
103--
104
105With pname:pMemoryZirconHandleProperties now successfully populated by
106flink:vkGetMemoryZirconHandlePropertiesFUCHSIA, assign the
107slink:VkMemoryAllocateInfo memoryTypeIndex field to a memory type which has
108a bit set in the slink:VkMemoryZirconHandlePropertiesFUCHSIA memoryTypeBits
109field.
110
111
112[[exporting-fuchsia-device-memory]]
113==== Exporting Fuchsia Device Memory
114Similar to importing, exporting a VMO handle from Vulkan transfers ownership
115of the handle from the Vulkan instance to the application.
116The application is responsible for closing the handle with
117code:zx_handle_close() when it is no longer in use.
118
119
120[open,refpage='vkGetMemoryZirconHandleFUCHSIA',desc='Get a Zircon handle for an external memory object',type='protos']
121--
122To export device memory as a Zircon handle that can be used by another
123instance, device, or process, the handle to the slink:VkDeviceMemory must be
124retrieved using flink:vkGetMemoryZirconHandleFUCHSIA:
125
126include::{generated}/api/protos/vkGetMemoryZirconHandleFUCHSIA.adoc[]
127
128  * pname:device is the slink:VkDevice.
129  * pname:pGetZirconHandleInfo is a pointer to a
130    slink:VkMemoryGetZirconHandleInfoFUCHSIA structure.
131  * pname:pZirconHandle is a pointer to a code:zx_handle_t which holds the
132    resulting Zircon handle.
133
134include::{generated}/validity/protos/vkGetMemoryZirconHandleFUCHSIA.adoc[]
135--
136
137[open,refpage='VkMemoryGetZirconHandleInfoFUCHSIA',desc='Structure specifying export parameters for Zircon handle to device memory',type='structs']
138--
139sname:VkMemoryGetZirconHandleInfoFUCHSIA is defined as:
140
141include::{generated}/api/structs/VkMemoryGetZirconHandleInfoFUCHSIA.adoc[]
142
143  * pname:sType is a elink:VkStructureType value identifying this structure.
144  * pname:pNext is `NULL` or a pointer to a structure extending this
145    structure.
146  * pname:memory the slink:VkDeviceMemory being exported.
147  * pname:handleType is a elink:VkExternalMemoryHandleTypeFlagBits value
148    specifying the type of the handle pointed to by
149    flink:vkGetMemoryZirconHandleFUCHSIA::pname:pZirconHandle.
150
151.Valid Usage
152****
153  * [[VUID-VkMemoryGetZirconHandleInfoFUCHSIA-handleType-04775]]
154    pname:handleType must: be
155    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ZIRCON_VMO_BIT_FUCHSIA
156  * [[VUID-VkMemoryGetZirconHandleInfoFUCHSIA-handleType-04776]]
157    pname:handleType must: have been included in the sname:handleTypes field
158    of the sname:VkExportMemoryAllocateInfo structure when the external
159    memory was allocated
160****
161
162include::{generated}/validity/structs/VkMemoryGetZirconHandleInfoFUCHSIA.adoc[]
163--
164
165With the result pname:pZirconHandle now obtained, the memory properties for
166the handle can be retrieved using
167flink:vkGetMemoryZirconHandlePropertiesFUCHSIA as documented above
168substituting the dereferenced, retrieved pname:pZirconHandle in for the
169pname:zirconHandle argument.
170