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

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

=== Other Extension Metadata

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

[[NvSciSync2-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 semaphore and import/export
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()
  * To import a stext:NvSciSyncObj to a slink:VkSemaphore, create a
    slink:VkSemaphoreSciSyncPoolNV for the stext:NvSciSyncObj and then
    select the semaphore from slink:VkSemaphoreSciSyncPoolNV by passing the
    slink:VkSemaphoreSciSyncCreateInfoNV structure to
    flink:vkCreateSemaphore
  * To import a stext:NvSciSyncObj to a slink:VkFence, pass 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.

This extension does not support exporting semaphores from stext:NvSciSync
objects.

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_sync2.adoc[]

=== Issues

1) Does this extension extend or replace `apiext:VK_NV_external_sci_sync`?

RESOLVED.
Replaces - expect to deprecate it and eventually remove it.

2) What part of `apiext:VK_NV_external_sci_sync` is deprecated/removed in
this extension?

RESOLVED.
The commands to import and export semaphores from
`apiext:VK_NV_external_sci_sync` are removed and have been replaced with an
alternate mechanism to import semaphores.
Fence import and export functionality is unchanged.

In particular:

  * Removed Commands:
  ** flink:vkImportSemaphoreSciSyncObjNV
  ** flink:vkGetSemaphoreSciSyncObjNV
  * Removed Structures:
  ** slink:VkImportSemaphoreSciSyncInfoNV
  ** slink:VkExportSemaphoreSciSyncInfoNV
  ** slink:VkSemaphoreGetSciSyncInfoNV

3) Application migration guide from `apiext:VK_NV_external_sci_sync` to
`apiext:VK_NV_external_sci_sync2`

  * In `apiext:VK_NV_external_sci_sync`, to import a stext:NvSciSyncObj to
    slink:VkSemaphore, applications need to:

  ** Create a slink:VkSemaphore by command flink:vkCreateSemaphore.
  ** Call flink:vkImportSemaphoreSciSyncObjNV command to import the
     stext:NvSciSyncObj to slink:VkSemaphore created.
  ** Call flink:vkDestroySemaphore to destroy the slink:VkSemaphore after
     all submitted batches that refer to it have completed execution.

  * In order to migrate to `apiext:VK_NV_external_sci_sync2`, applications
    need to:

ifdef::VKSC_VERSION_1_0[]
  ** Chain slink:VkDeviceSemaphoreSciSyncPoolReservationCreateInfoNV to
     slink:VkDeviceObjectReservationCreateInfo and specify the
     pname:semaphoreSciSyncPoolRequestCount maximum number of semaphore
     SciSync pools that will be used simultaneously.
endif::VKSC_VERSION_1_0[]
  ** Import the a stext:NvSciSyncObj to a slink:VkSemaphoreSciSyncPoolNV by
     command flink:vkCreateSemaphoreSciSyncPoolNV.
  ** Select the slink:VkSemaphore from slink:VkSemaphoreSciSyncPoolNV by
     passing the slink:VkSemaphoreSciSyncCreateInfoNV structure to
     flink:vkCreateSemaphore.
  ** Can call flink:vkDestroySemaphore to destroy the slink:VkSemaphore
     immediately after all the batches that refer to it are submitted.
ifndef::VKSC_VERSION_1_0[]
  ** Call flink:vkDestroySemaphoreSciSyncPoolNV to destroy the semaphore
     SciSync pool after all submitted batches that refer to it have
     completed execution.
endif::VKSC_VERSION_1_0[]

=== Version History

  * Revision 1, 2022-09-07 (Kai Zhang, Daniel Koch)
  ** Initial revision