// Copyright (c) 2020-2022 NVIDIA Corporation
//
// SPDX-License-Identifier: CC-BY-4.0

include::{generated}/meta/{refprefix}VK_NV_external_sci_sync.adoc[]

=== Other Extension Metadata

*Last Modified Date*::
    2022-04-12
*Contributors*::
  - Kai Zhang, NVIDIA
  - Jeff Bolz, NVIDIA
  - Jonathan McCaffrey, NVIDIA
  - Daniel Koch, NVIDIA

[[NvSciSync-extension-page]]
=== Description
An application using external memory may wish to synchronize access to that
memory using semaphores and fences.
This extension enables an application to import and export semaphore and
fence payloads to and from stext:NvSciSync objects.
To import a stext:NvSciSyncObj to a slink:VkSemaphore or slink:VkFence,
applications need to:

  * Create an unreconciled stext:NvSciSyncAttrList via
    stext:NvSciSyncAttrListCreate()
  * Fill the private attribute list via
    flink:vkGetPhysicalDeviceSciSyncAttributesNV()
  * Fill the public attribute list via stext:NvSciSyncAttrListSetAttrs()
  * Reconcile the stext:NvSciSyncAttrList via
    stext:NvSciSyncAttrListReconcile()
  * Create a stext:NvSciSyncObj via stext:NvSciSyncObjAlloc()
  * Import the stext:NvSciSyncObj to a slink:VkSemaphore by passing the
    slink:VkImportSemaphoreSciSyncInfoNV structure to the
    flink:vkImportSemaphoreSciSyncObjNV command, or to a slink:VkFence by
    passing the slink:VkImportFenceSciSyncInfoNV structure to the
    flink:vkImportFenceSciSyncObjNV command.

To import/export a stext:NvSciSyncFence to a slink:VkFence object, that
slink:VkFence object must: already have a stext:NvSciSyncObj previously
imported.

For details of the stext:NvSciSync APIs and data structures, see the
https://developer.nvidia.com/docs/drive/drive-os/latest/linux/sdk/api%5Freference/group%5F%5Fnvsci%5F%5Ftop.html[`NvStreams
Documentation`].

include::{generated}/interfaces/VK_NV_external_sci_sync.adoc[]

=== Issues

1) What should we call this extension?

RESOLVED.
The external API is stext:NvSciSync, but the Vulkan convention is to append
the vendor suffix at the end of an identifier.
Using stext:NvSciSyncNV seems awkward, so we have chosen to use just the
stext:SciSync portion of the name in Vulkan commands and tokens.
Since this is for interacting with objects from outside Vulkan, we use
"external" in the name, similar to apiext:VK_KHR_external_fence_fd.
To avoid an explosion of extensions, we include the capability to import and
export both semaphores and fences in one extension but include separate
features in case implementations only implement (or safety certify) a
subset.

2) How do we resolve the NvStreams terminology of NvSciSyncFence which
conflicts with the Vulkan SC terminology of VkFence.

RESOLVED: "fence" refers to VkFence.
"NvSciSyncFence" refers to the NvStreams type and "VkFence" refers to the
Vulkan SC type.


=== Version History

  * Revision 2, 2022-03-29 (Daniel Koch)
  ** use separate entry points for stext:NvSciSyncFence and
     stext:NvSciSyncObj handles
  * Revision 1, 2020-11-25 (Kai Zhang, Daniel Koch)
  ** Initial revision