// Copyright (c) 2021 Google Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

[[fuchsia-external-memory]]
=== Fuchsia External Memory

On Fuchsia, when allocating memory that may: be imported from another
device, process or Vulkan instance, add a
slink:VkImportMemoryZirconHandleInfoFUCHSIA structure to the pname:pNext
chain of the slink:VkMemoryAllocateInfo structure.

External memory on Fuchsia is imported and exported using VMO handles of
type code:zx_handle_t.
VMO handles to external memory are canonically obtained from Fuchsia's
Sysmem service or from syscalls such as sname:zx_vmo_create().
VMO handles for import can also be obtained by exporting them from another
Vulkan instance as described in <<exporting-fuchsia-device-memory,exporting
fuchsia device memory>>.

Importing VMO handles to the Vulkan instance transfers ownership of the
handle to the instance from the application.
The application must: not perform any operations on the handle after
successful import.

Applications can: import the same underlying memory into multiple instances
of Vulkan, into the same instance from which it was exported, and multiple
times into a given Vulkan instance.
In all cases, each import operation must: create a distinct
sname:VkDeviceMemory object.


[[importing-fuchsia-external-memory]]
==== Importing Fuchsia External Memory

[open,refpage='VkImportMemoryZirconHandleInfoFUCHSIA',desc='Structure specifying import parameters for Zircon handle to external memory',type='structs']
--
The sname:VkImportMemoryZirconHandleInfoFUCHSIA structure is defined as:

include::{generated}/api/structs/VkImportMemoryZirconHandleInfoFUCHSIA.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:handleType is a elink:VkExternalMemoryHandleTypeFlagBits value
    specifying the type of pname:handle.
  * pname:handle is a code:zx_handle_t (Zircon) handle to the external
    memory.

.Valid Usage
****
  * [[VUID-VkImportMemoryZirconHandleInfoFUCHSIA-handleType-04771]]
    pname:handleType must: be
    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ZIRCON_VMO_BIT_FUCHSIA
  * [[VUID-VkImportMemoryZirconHandleInfoFUCHSIA-handle-04772]]
    pname:handle must be a valid VMO handle
****

include::{generated}/validity/structs/VkImportMemoryZirconHandleInfoFUCHSIA.txt[]
--

[open,refpage='vkGetMemoryZirconHandlePropertiesFUCHSIA',desc='Get a Zircon handle properties for an external memory object',type='protos']
--
To obtain the memoryTypeIndex for the slink:VkMemoryAllocateInfo structure,
call fname:vkGetMemoryZirconHandlePropertiesFUCHSIA:

include::{generated}/api/protos/vkGetMemoryZirconHandlePropertiesFUCHSIA.txt[]

  * pname:device is the slink:VkDevice.
  * pname:handleType is a elink:VkExternalMemoryHandleTypeFlagBits value
    specifying the type of pname:zirconHandle
  * pname:zirconHandle is a code:zx_handle_t (Zircon) handle to the external
    resource.
  * pname:pMemoryZirconHandleProperties is a pointer to a
    slink:VkMemoryZirconHandlePropertiesFUCHSIA structure in which the
    result will be stored.

.Valid Usage
****
  * [[VUID-vkGetMemoryZirconHandlePropertiesFUCHSIA-handleType-04773]]
    pname:handleType must: be
    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ZIRCON_VMO_BIT_FUCHSIA
  * [[VUID-vkGetMemoryZirconHandlePropertiesFUCHSIA-zirconHandle-04774]]
    pname:zirconHandle must reference a valid VMO
****

include::{generated}/validity/protos/vkGetMemoryZirconHandlePropertiesFUCHSIA.txt[]
--

[open,refpage='VkMemoryZirconHandlePropertiesFUCHSIA',desc='Structure specifying Zircon handle compatible external memory',type='structs']
--
The sname:VkMemoryZirconHandlePropertiesFUCHSIA structure is defined as:

include::{generated}/api/structs/VkMemoryZirconHandlePropertiesFUCHSIA.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:memoryTypeBits a bitmask containing one bit set for every memory
    type which the specified handle can be imported as.

include::{generated}/validity/structs/VkMemoryZirconHandlePropertiesFUCHSIA.txt[]
--

With pname:pMemoryZirconHandleProperties now successfully populated by
flink:vkGetMemoryZirconHandlePropertiesFUCHSIA, assign the
slink:VkMemoryAllocateInfo memoryTypeIndex field to a memory type which has
a bit set in the slink:VkMemoryZirconHandlePropertiesFUCHSIA memoryTypeBits
field.


[[exporting-fuchsia-device-memory]]
==== Exporting Fuchsia Device Memory
Similar to importing, exporting a VMO handle from Vulkan transfers ownership
of the handle from the Vulkan instance to the application.
The application is responsible for closing the handle with
code:zx_handle_close() when it is no longer in use.


[open,refpage='vkGetMemoryZirconHandleFUCHSIA',desc='Get a Zircon handle for an external memory object',type='protos']
--
To export device memory as a Zircon handle that can be used by another
instance, device, or process, the handle to the slink:VkDeviceMemory must be
retrieved using flink:vkGetMemoryZirconHandleFUCHSIA:

include::{generated}/api/protos/vkGetMemoryZirconHandleFUCHSIA.txt[]

  * pname:device is the slink:VkDevice.
  * pname:pGetZirconHandleInfo is a pointer to a
    slink:VkMemoryGetZirconHandleInfoFUCHSIA structure.
  * pname:pZirconHandle is a pointer to a code:zx_handle_t which holds the
    resulting Zircon handle.

include::{generated}/validity/protos/vkGetMemoryZirconHandleFUCHSIA.txt[]
--

[open,refpage='VkMemoryGetZirconHandleInfoFUCHSIA',desc='Structure specifying export parameters for Zircon handle to device memory',type='structs']
--
sname:VkMemoryGetZirconHandleInfoFUCHSIA is defined as:

include::{generated}/api/structs/VkMemoryGetZirconHandleInfoFUCHSIA.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:memory the slink:VkDeviceMemory being exported.
  * pname:handleType is a elink:VkExternalMemoryHandleTypeFlagBits value
    specifying the type of the handle pointed to by
    flink:vkGetMemoryZirconHandleFUCHSIA::pname:pZirconHandle.

.Valid Usage
****
  * [[VUID-VkMemoryGetZirconHandleInfoFUCHSIA-handleType-04775]]
    pname:handleType must: be
    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ZIRCON_VMO_BIT_FUCHSIA
  * [[VUID-VkMemoryGetZirconHandleInfoFUCHSIA-handleType-04776]]
    pname:handleType must: have been included in the sname:handleTypes field
    of the sname:VkExportMemoryAllocateInfo structure when the external
    memory was allocated
****

include::{generated}/validity/structs/VkMemoryGetZirconHandleInfoFUCHSIA.txt[]
--

With the result pname:pZirconHandle now obtained, the memory properties for
the handle can be retrieved using
flink:vkGetMemoryZirconHandlePropertiesFUCHSIA as documented above
substituting the dereferenced, retrieved pname:pZirconHandle in for the
pname:zirconHandle argument.