Vulkan.Extensions.VK_KHR_external_semaphore_fd

Name

VK_KHR_external_semaphore_fd - device extension

VK_KHR_external_semaphore_fd

Name String

VK_KHR_external_semaphore_fd

Extension Type

Device extension

Registered Extension Number

80

Revision

1

Extension and Version Dependencies

• Requires Vulkan 1.0
• Requires VK_KHR_external_semaphore

Contact

• James Jones https://github.com/KhronosGroup/Vulkan-Docs/issues/new?title=VK_KHR_external_semaphore_fd:%20&body=@cubanismo%20

Other Extension Metadata

Last Modified Date

2016-10-21

IP Status

No known IP claims.

Contributors

• Jesse Hall, Google
• James Jones, NVIDIA
• Jeff Juliano, NVIDIA
• Carsten Rohde, NVIDIA

Description

An application using external memory may wish to synchronize access to that memory using semaphores. This extension enables an application to export semaphore payload to and import semaphore payload from POSIX file descriptors.

New Commands

• getSemaphoreFdKHR

• importSemaphoreFdKHR

New Structures

• ImportSemaphoreFdInfoKHR

• SemaphoreGetFdInfoKHR

New Enum Constants

• KHR_EXTERNAL_SEMAPHORE_FD_EXTENSION_NAME

• KHR_EXTERNAL_SEMAPHORE_FD_SPEC_VERSION

• Extending StructureType:

  • STRUCTURE_TYPE_IMPORT_SEMAPHORE_FD_INFO_KHR
  • STRUCTURE_TYPE_SEMAPHORE_GET_FD_INFO_KHR

Issues

1) Does the application need to close the file descriptor returned by getSemaphoreFdKHR?

RESOLVED: Yes, unless it is passed back in to a driver instance to import the semaphore. A successful get call transfers ownership of the file descriptor to the application, and a successful import transfers it back to the driver. Destroying the original semaphore object will not close the file descriptor or remove its reference to the underlying semaphore resource associated with it.

Version History

• Revision 1, 2016-10-21 (Jesse Hall)

  • Initial revision

See Also

ImportSemaphoreFdInfoKHR, SemaphoreGetFdInfoKHR, getSemaphoreFdKHR, importSemaphoreFdKHR

Document Notes

For more information, see the Vulkan Specification

This page is a generated document. Fixes and changes should be made to the generator scripts, not directly.

Documentation

getSemaphoreFdKHR

Arguments

:: forall io. MonadIO io

=> Device

device is the logical device that created the semaphore being exported.

device must be a valid Device handle

-> SemaphoreGetFdInfoKHR

pGetFdInfo is a pointer to a SemaphoreGetFdInfoKHR structure containing parameters of the export operation.

pGetFdInfo must be a valid pointer to a valid SemaphoreGetFdInfoKHR structure

-> io ("fd" ::: Int32)

vkGetSemaphoreFdKHR - Get a POSIX file descriptor handle for a semaphore

Description

Each call to getSemaphoreFdKHR must create a new file descriptor and transfer ownership of it to the application. To avoid leaking resources, the application must release ownership of the file descriptor when it is no longer needed.

Note

Ownership can be released in many ways. For example, the application can call close() on the file descriptor, or transfer ownership back to Vulkan by using the file descriptor to import a semaphore payload.

Where supported by the operating system, the implementation must set the file descriptor to be closed automatically when an execve system call is made.

Exporting a file descriptor from a semaphore may have side effects depending on the transference of the specified handle type, as described in Importing Semaphore State.

Return Codes

Success

• SUCCESS

Failure

• ERROR_TOO_MANY_OBJECTS
• ERROR_OUT_OF_HOST_MEMORY

See Also

Device, SemaphoreGetFdInfoKHR

importSemaphoreFdKHR

Arguments

:: forall io. MonadIO io

=> Device

device is the logical device that created the semaphore.

device must be a valid Device handle

-> ImportSemaphoreFdInfoKHR

pImportSemaphoreFdInfo is a pointer to a ImportSemaphoreFdInfoKHR structure specifying the semaphore and import parameters.

pImportSemaphoreFdInfo must be a valid pointer to a valid ImportSemaphoreFdInfoKHR structure

-> io ()

vkImportSemaphoreFdKHR - Import a semaphore from a POSIX file descriptor

Description

Importing a semaphore payload from a file descriptor transfers ownership of the file descriptor from the application to the Vulkan implementation. The application must not perform any operations on the file descriptor after a successful import.

Applications can import the same semaphore payload into multiple instances of Vulkan, into the same instance from which it was exported, and multiple times into a given Vulkan instance.

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_INVALID_EXTERNAL_HANDLE

See Also

Device, ImportSemaphoreFdInfoKHR

data ImportSemaphoreFdInfoKHR

VkImportSemaphoreFdInfoKHR - Structure specifying POSIX file descriptor to import to a semaphore

Description

The handle types supported by handleType are:

Handle Type	Transference	Permanence Supported
EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_FD_BIT	Reference	Temporary,Permanent
EXTERNAL_SEMAPHORE_HANDLE_TYPE_SYNC_FD_BIT	Copy	Temporary

Handle Types Supported by ImportSemaphoreFdInfoKHR

Valid Usage

• handleType must be a value included in the Handle Types Supported by table

• fd must obey any requirements listed for handleType in external semaphore handle types compatibility
• If handleType is EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_FD_BIT, the SemaphoreCreateInfo::flags field must match that of the semaphore from which fd was exported
• If handleType is EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_FD_BIT, the SemaphoreTypeCreateInfo::semaphoreType field must match that of the semaphore from which fd was exported
• If flags contains SEMAPHORE_IMPORT_TEMPORARY_BIT, the SemaphoreTypeCreateInfo::semaphoreType field of the semaphore from which fd was exported must not be SEMAPHORE_TYPE_TIMELINE

If handleType is EXTERNAL_SEMAPHORE_HANDLE_TYPE_SYNC_FD_BIT, the special value -1 for fd is treated like a valid sync file descriptor referring to an object that has already signaled. The import operation will succeed and the Semaphore will have a temporarily imported payload as if a valid file descriptor had been provided.

Note

This special behavior for importing an invalid sync file descriptor allows easier interoperability with other system APIs which use the convention that an invalid sync file descriptor represents work that has already completed and does not need to be waited for. It is consistent with the option for implementations to return a -1 file descriptor when exporting a EXTERNAL_SEMAPHORE_HANDLE_TYPE_SYNC_FD_BIT from a Semaphore which is signaled.

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_IMPORT_SEMAPHORE_FD_INFO_KHR

• pNext must be NULL
• semaphore must be a valid Semaphore handle
• flags must be a valid combination of SemaphoreImportFlagBits values
• handleType must be a valid ExternalSemaphoreHandleTypeFlagBits value

Host Synchronization

• Host access to semaphore must be externally synchronized

See Also

ExternalSemaphoreHandleTypeFlagBits, Semaphore, SemaphoreImportFlags, StructureType, importSemaphoreFdKHR

Constructors

ImportSemaphoreFdInfoKHR

Fields

• semaphore :: Semaphore

  semaphore is the semaphore into which the payload will be imported.

• flags :: SemaphoreImportFlags

  flags is a bitmask of SemaphoreImportFlagBits specifying additional parameters for the semaphore payload import operation.

• handleType :: ExternalSemaphoreHandleTypeFlagBits

  handleType is a ExternalSemaphoreHandleTypeFlagBits value specifying the type of fd.

• fd :: Int32

  fd is the external handle to import.

Instances

Eq ImportSemaphoreFdInfoKHR

Defined in Vulkan.Extensions.VK_KHR_external_semaphore_fd

Methods

(==) :: ImportSemaphoreFdInfoKHR -> ImportSemaphoreFdInfoKHR -> Bool

(/=) :: ImportSemaphoreFdInfoKHR -> ImportSemaphoreFdInfoKHR -> Bool

Show ImportSemaphoreFdInfoKHR

Defined in Vulkan.Extensions.VK_KHR_external_semaphore_fd

Methods

showsPrec :: Int -> ImportSemaphoreFdInfoKHR -> ShowS

show :: ImportSemaphoreFdInfoKHR -> String

showList :: [ImportSemaphoreFdInfoKHR] -> ShowS

Storable ImportSemaphoreFdInfoKHR

Defined in Vulkan.Extensions.VK_KHR_external_semaphore_fd

Methods

sizeOf :: ImportSemaphoreFdInfoKHR -> Int

alignment :: ImportSemaphoreFdInfoKHR -> Int

peekElemOff :: Ptr ImportSemaphoreFdInfoKHR -> Int -> IO ImportSemaphoreFdInfoKHR

pokeElemOff :: Ptr ImportSemaphoreFdInfoKHR -> Int -> ImportSemaphoreFdInfoKHR -> IO ()

peekByteOff :: Ptr b -> Int -> IO ImportSemaphoreFdInfoKHR

pokeByteOff :: Ptr b -> Int -> ImportSemaphoreFdInfoKHR -> IO ()

peek :: Ptr ImportSemaphoreFdInfoKHR -> IO ImportSemaphoreFdInfoKHR

poke :: Ptr ImportSemaphoreFdInfoKHR -> ImportSemaphoreFdInfoKHR -> IO ()

FromCStruct ImportSemaphoreFdInfoKHR

Defined in Vulkan.Extensions.VK_KHR_external_semaphore_fd

Methods

peekCStruct :: Ptr ImportSemaphoreFdInfoKHR -> IO ImportSemaphoreFdInfoKHR

ToCStruct ImportSemaphoreFdInfoKHR

Defined in Vulkan.Extensions.VK_KHR_external_semaphore_fd

Methods

withCStruct :: ImportSemaphoreFdInfoKHR -> (Ptr ImportSemaphoreFdInfoKHR -> IO b) -> IO b

pokeCStruct :: Ptr ImportSemaphoreFdInfoKHR -> ImportSemaphoreFdInfoKHR -> IO b -> IO b

withZeroCStruct :: (Ptr ImportSemaphoreFdInfoKHR -> IO b) -> IO b

pokeZeroCStruct :: Ptr ImportSemaphoreFdInfoKHR -> IO b -> IO b

cStructSize :: Int

cStructAlignment :: Int

Zero ImportSemaphoreFdInfoKHR

Defined in Vulkan.Extensions.VK_KHR_external_semaphore_fd

Methods

zero :: ImportSemaphoreFdInfoKHR

data SemaphoreGetFdInfoKHR

VkSemaphoreGetFdInfoKHR - Structure describing a POSIX FD semaphore export operation

Description

The properties of the file descriptor returned depend on the value of handleType. See ExternalSemaphoreHandleTypeFlagBits for a description of the properties of the defined external semaphore handle types.

Valid Usage

• handleType must have been included in ExportSemaphoreCreateInfo::handleTypes when semaphore’s current payload was created

• semaphore must not currently have its payload replaced by an imported payload as described below in Importing Semaphore Payloads unless that imported payload’s handle type was included in ExternalSemaphoreProperties::exportFromImportedHandleTypes for handleType
• If handleType refers to a handle type with copy payload transference semantics, as defined below in Importing Semaphore Payloads, there must be no queue waiting on semaphore
• If handleType refers to a handle type with copy payload transference semantics, semaphore must be signaled, or have an associated semaphore signal operation pending execution
• handleType must be defined as a POSIX file descriptor handle
• If handleType refers to a handle type with copy payload transference semantics, semaphore must have been created with a SemaphoreType of SEMAPHORE_TYPE_BINARY
• If handleType refers to a handle type with copy payload transference semantics, semaphore must have an associated semaphore signal operation that has been submitted for execution and any semaphore signal operations on which it depends (if any) must have also been submitted for execution

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_SEMAPHORE_GET_FD_INFO_KHR

• pNext must be NULL
• semaphore must be a valid Semaphore handle
• handleType must be a valid ExternalSemaphoreHandleTypeFlagBits value

See Also

ExternalSemaphoreHandleTypeFlagBits, Semaphore, StructureType, getSemaphoreFdKHR

Constructors

SemaphoreGetFdInfoKHR

Fields

• semaphore :: Semaphore

  semaphore is the semaphore from which state will be exported.

• handleType :: ExternalSemaphoreHandleTypeFlagBits

  handleType is a ExternalSemaphoreHandleTypeFlagBits value specifying the type of handle requested.

Instances

Eq SemaphoreGetFdInfoKHR

Defined in Vulkan.Extensions.VK_KHR_external_semaphore_fd

Methods

(==) :: SemaphoreGetFdInfoKHR -> SemaphoreGetFdInfoKHR -> Bool

(/=) :: SemaphoreGetFdInfoKHR -> SemaphoreGetFdInfoKHR -> Bool

Show SemaphoreGetFdInfoKHR

Defined in Vulkan.Extensions.VK_KHR_external_semaphore_fd

Methods

showsPrec :: Int -> SemaphoreGetFdInfoKHR -> ShowS

show :: SemaphoreGetFdInfoKHR -> String

showList :: [SemaphoreGetFdInfoKHR] -> ShowS

Storable SemaphoreGetFdInfoKHR

Defined in Vulkan.Extensions.VK_KHR_external_semaphore_fd

Methods

sizeOf :: SemaphoreGetFdInfoKHR -> Int

alignment :: SemaphoreGetFdInfoKHR -> Int

peekElemOff :: Ptr SemaphoreGetFdInfoKHR -> Int -> IO SemaphoreGetFdInfoKHR

pokeElemOff :: Ptr SemaphoreGetFdInfoKHR -> Int -> SemaphoreGetFdInfoKHR -> IO ()

peekByteOff :: Ptr b -> Int -> IO SemaphoreGetFdInfoKHR

pokeByteOff :: Ptr b -> Int -> SemaphoreGetFdInfoKHR -> IO ()

peek :: Ptr SemaphoreGetFdInfoKHR -> IO SemaphoreGetFdInfoKHR

poke :: Ptr SemaphoreGetFdInfoKHR -> SemaphoreGetFdInfoKHR -> IO ()

FromCStruct SemaphoreGetFdInfoKHR

Defined in Vulkan.Extensions.VK_KHR_external_semaphore_fd

Methods

peekCStruct :: Ptr SemaphoreGetFdInfoKHR -> IO SemaphoreGetFdInfoKHR

ToCStruct SemaphoreGetFdInfoKHR

Defined in Vulkan.Extensions.VK_KHR_external_semaphore_fd

Methods

withCStruct :: SemaphoreGetFdInfoKHR -> (Ptr SemaphoreGetFdInfoKHR -> IO b) -> IO b

pokeCStruct :: Ptr SemaphoreGetFdInfoKHR -> SemaphoreGetFdInfoKHR -> IO b -> IO b

withZeroCStruct :: (Ptr SemaphoreGetFdInfoKHR -> IO b) -> IO b

pokeZeroCStruct :: Ptr SemaphoreGetFdInfoKHR -> IO b -> IO b

cStructSize :: Int

cStructAlignment :: Int

Zero SemaphoreGetFdInfoKHR

Defined in Vulkan.Extensions.VK_KHR_external_semaphore_fd

Methods

zero :: SemaphoreGetFdInfoKHR

type KHR_EXTERNAL_SEMAPHORE_FD_SPEC_VERSION = 1

pattern KHR_EXTERNAL_SEMAPHORE_FD_SPEC_VERSION :: forall a. Integral a => a

type KHR_EXTERNAL_SEMAPHORE_FD_EXTENSION_NAME = "VK_KHR_external_semaphore_fd"

pattern KHR_EXTERNAL_SEMAPHORE_FD_EXTENSION_NAME :: forall a. (Eq a, IsString a) => a