path: root/src/vulkan/runtime/vk_sync.h

/*
 * Copyright © 2021 Intel Corporation
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the "Software"),
 * to deal in the Software without restriction, including without limitation
 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
 * and/or sell copies of the Software, and to permit persons to whom the
 * Software is furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice (including the next
 * paragraph) shall be included in all copies or substantial portions of the
 * Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 * IN THE SOFTWARE.
 */
#ifndef VK_SYNC_H
#define VK_SYNC_H

#include <stdbool.h>
#include <vulkan/vulkan_core.h>

#include "util/macros.h"

#ifdef __cplusplus
extern "C" {
#endif

struct vk_device;
struct vk_sync;

enum vk_sync_features {
   /** Set if a sync type supports the binary mode of operation
    *
    * In binary mode, a vk_sync has two modes: signaled and unsignaled.  If
    * it supports CPU_RESET, it can be changed from signaled to unsignaled on
    * the CPU via vk_sync_reset().  If it supports CPU_SIGNAL, it can be
    * changed from unsignaled to signaled on the CPU via vk_sync_signal().
    *
    * Binary vk_sync types may also support WAIT_PENDING in which they have a
    * third hidden pending state.  Once such a vk_sync has been submitted to
    * the kernel driver for signaling, it is in the pending state and remains
    * there until the work is complete at which point it enters the signaled
    * state.  This pending state is visible across processes for shared
    * vk_sync types.  This is used to by the threaded submit mode to ensure
    * that everything gets submitted to the kernel driver in-order.
    *
    * A vk_sync operates in binary mode if VK_SYNC_IS_TIMELINE is not set
    * in vk_sync::flags.
    */
   VK_SYNC_FEATURE_BINARY              = (1 << 0),

   /** Set if a sync type supports the timeline mode of operation
    *
    * In timeline mode, a vk_sync has a monotonically increasing 64-bit value
    * which represents most recently signaled time point.  Waits are relative
    * to time points.  Instead of waiting for the vk_sync to enter a signaled
    * state, you wait for its 64-bit value to be at least some wait value.
    *
    * Timeline vk_sync types can also support WAIT_PENDING.  In this case, the
    * wait is not for a pending state, as such, but rather for someone to have
    * submitted a kernel request which will signal a time point with at least
    * that value.  Logically, you can think of this as having two timelines,
    * the real timeline and a pending timeline which runs slightly ahead of
    * the real one.  As with binary vk_sync types, this is used by threaded
    * submit to re-order things so that the kernel requests happen in a valid
    * linear order.
    *
    * A vk_sync operates in timeline mode if VK_SYNC_IS_TIMELINE is set in
    * vk_sync::flags.
    */
   VK_SYNC_FEATURE_TIMELINE            = (1 << 1),

   /** Set if this sync supports GPU waits */
   VK_SYNC_FEATURE_GPU_WAIT            = (1 << 2),

   /** Set if a sync type supports multiple GPU waits on one signal state
    *
    * The Vulkan spec for VkSemaphore requires GPU wait and signal operations
    * to have a one-to-one relationship.  This formally described by saying
    * that the VkSemaphore gets implicitly reset on wait.  However, it is
    * often useful to have well-defined multi-wait.  If binary vk_sync
    * supports multi-wait then any number of kernel requests can be submitted
    * which wait on one signal operation.  This also implies that you can
    * signal twice back-to-back (there are 0 waits on the first signal).
    *
    * This feature only applies to binary vk_sync objects.
    */
   VK_SYNC_FEATURE_GPU_MULTI_WAIT      = (1 << 3),

   /** Set if a sync type supports vk_sync_wait() and vk_sync_wait_many() */
   VK_SYNC_FEATURE_CPU_WAIT            = (1 << 4),

   /** Set if a sync type supports vk_sync_reset()
    *
    * This feature only applies to binary vk_sync objects.
    */
   VK_SYNC_FEATURE_CPU_RESET           = (1 << 5),

   /** Set if a sync type supports vk_sync_signal() */
   VK_SYNC_FEATURE_CPU_SIGNAL          = (1 << 6),

   /** Set if sync_type::wait_many supports the VK_SYNC_WAIT_ANY bit
    *
    * vk_sync_wait_many() will support the bit regardless.  If the sync type
    * doesn't support it natively, it will be emulated.
    */
   VK_SYNC_FEATURE_WAIT_ANY            = (1 << 7),

   /** Set if a sync type supports the VK_SYNC_WAIT_PENDING bit
    *
    * See VK_SYNC_FEATURE_BINARY and VK_SYNC_FEATURE_TIMELINE for descriptions
    * of what this does in each case.
    */
   VK_SYNC_FEATURE_WAIT_PENDING        = (1 << 8),

   /** Set if a sync type natively supports wait-before-signal
    *
    * If this is set then the underlying OS primitive supports submitting
    * kernel requests which wait on the vk_sync before submitting a kernel
    * request which would cause that wait to unblock.
    */
   VK_SYNC_FEATURE_WAIT_BEFORE_SIGNAL  = (1 << 9),
};

struct vk_sync_wait;

enum vk_sync_wait_flags {
   /** Placeholder for 0 to make vk_sync_wait() calls more clear */
   VK_SYNC_WAIT_COMPLETE   = 0,

   /** If set, only wait for the vk_sync operation to be pending
    *
    * See VK_SYNC_FEATURE_BINARY and VK_SYNC_FEATURE_TIMELINE for descriptions
    * of what this does in each case.
    */
   VK_SYNC_WAIT_PENDING    = (1 << 0),

   /** If set, wait for any of of the vk_sync operations to complete
    *
    * This is as opposed to waiting for all of them.  There is no guarantee
    * that vk_sync_wait_many() will return immediately after the first
    * operation completes but it will make a best effort to return as soon as
    * possible.
    */
   VK_SYNC_WAIT_ANY        = (1 << 1),
};

struct vk_sync_type {
   /** Size of this sync type */
   size_t size;

   /** Features supported by this sync type */
   enum vk_sync_features features;

   /** Initialize a vk_sync
    *
    * The base vk_sync will already be initialized and the sync type set
    * before this function is called.  If any OS primitives need to be
    * allocated, that should be done here.
    */
   VkResult (*init)(struct vk_device *device,
                    struct vk_sync *sync,
                    uint64_t initial_value);

   /** Finish a vk_sync
    *
    * This should free any internal data stored in this vk_sync.
    */
   void (*finish)(struct vk_device *device,
                  struct vk_sync *sync);

   /** Signal a vk_sync
    *
    * For non-timeline sync types, value == 0.
    */
   VkResult (*signal)(struct vk_device *device,
                      struct vk_sync *sync,
                      uint64_t value);

   /** Get the timeline value for a vk_sync */
   VkResult (*get_value)(struct vk_device *device,
                         struct vk_sync *sync,
                         uint64_t *value);

   /** Reset a non-timeline vk_sync */
   VkResult (*reset)(struct vk_device *device,
                     struct vk_sync *sync);

   /** Moves the guts of one binary vk_sync to another
    *
    * This moves the current binary vk_sync event from src to dst and resets
    * src.  If dst contained an event, it is discarded.
    *
    * This is required for all binary vk_sync types that can be used for a
    * semaphore wait in conjunction with real timeline semaphores.
    */
   VkResult (*move)(struct vk_device *device,
                    struct vk_sync *dst,
                    struct vk_sync *src);

   /** Wait on a vk_sync
    *
    * For a timeline vk_sync, wait_value is the timeline value to wait for.
    * This function should not return VK_SUCCESS until get_value on that
    * vk_sync would return a value >= wait_value.  A wait_value of zero is
    * allowed in which case the wait is a no-op.  For a non-timeline vk_sync,
    * wait_value should be ignored.
    *
    * This function is optional.  If the sync type needs to support CPU waits,
    * at least one of wait or wait_many must be provided.  If one is missing,
    * it will be implemented in terms of the other.
    */
   VkResult (*wait)(struct vk_device *device,
                    struct vk_sync *sync,
                    uint64_t wait_value,
                    enum vk_sync_wait_flags wait_flags,
                    uint64_t abs_timeout_ns);

   /** Wait for multiple vk_sync events
    *
    * If VK_SYNC_WAIT_ANY is set, it will return after at least one of the
    * wait events is complete instead of waiting for all of them.
    *
    * See wait for more details.
    */
   VkResult (*wait_many)(struct vk_device *device,
                         uint32_t wait_count,
                         const struct vk_sync_wait *waits,
                         enum vk_sync_wait_flags wait_flags,
                         uint64_t abs_timeout_ns);

   /** Permanently imports the given FD into this vk_sync
    *
    * This replaces the guts of the given vk_sync with whatever is in the FD.
    * In a sense, this vk_sync now aliases whatever vk_sync the FD was
    * exported from.
    */
   VkResult (*import_opaque_fd)(struct vk_device *device,
                                struct vk_sync *sync,
                                int fd);

   /** Export the guts of this vk_sync to an FD */
   VkResult (*export_opaque_fd)(struct vk_device *device,
                                struct vk_sync *sync,
                                int *fd);

   /** Imports a sync file into this binary vk_sync
    *
    * If this completes successfully, the vk_sync will now signal whenever
    * the sync file signals.
    *
    * If sync_file == -1, the vk_sync should be signaled immediately.  If
    * the vk_sync_type implements signal, sync_file will never be -1.
    */
   VkResult (*import_sync_file)(struct vk_device *device,
                                struct vk_sync *sync,
                                int sync_file);

   /** Exports the current binary vk_sync state as a sync file.
    *
    * The resulting sync file will contain the current event stored in this
    * binary vk_sync must be turned into a sync file.  If the vk_sync is later
    * modified to contain a new event, the sync file is unaffected.
    */
   VkResult (*export_sync_file)(struct vk_device *device,
                                struct vk_sync *sync,
                                int *sync_file);

   /** Permanently imports the given handle or name into this vk_sync
    *
    * This replaces the guts of the given vk_sync with whatever is in the object.
    * In a sense, this vk_sync now aliases whatever vk_sync the handle was
    * exported from.
    */
   VkResult (*import_win32_handle)(struct vk_device *device,
                                   struct vk_sync *sync,
                                   void *handle,
                                   const wchar_t *name);

   /** Export the guts of this vk_sync to a handle and/or name */
   VkResult (*export_win32_handle)(struct vk_device *device,
                                   struct vk_sync *sync,
                                   void **handle);

   /** Vulkan puts these as creation params instead of export params */
   VkResult (*set_win32_export_params)(struct vk_device *device,
                                       struct vk_sync *sync,
                                       const void *security_attributes,
                                       uint32_t access,
                                       const wchar_t *name);
};

enum vk_sync_flags {
   /** Set if the vk_sync is a timeline */
   VK_SYNC_IS_TIMELINE  = (1 << 0),

   /** Set if the vk_sync can have its payload shared */
   VK_SYNC_IS_SHAREABLE = (1 << 1),

   /** Set if the vk_sync has a shared payload */
   VK_SYNC_IS_SHARED    = (1 << 2),
};

struct vk_sync {
   const struct vk_sync_type *type;
   enum vk_sync_flags flags;
};

/* See VkSemaphoreSubmitInfo */
struct vk_sync_wait {
   struct vk_sync *sync;
   VkPipelineStageFlags2 stage_mask;
   uint64_t wait_value;
};

/* See VkSemaphoreSubmitInfo */
struct vk_sync_signal {
   struct vk_sync *sync;
   VkPipelineStageFlags2 stage_mask;
   uint64_t signal_value;
};

VkResult MUST_CHECK vk_sync_init(struct vk_device *device,
                                 struct vk_sync *sync,
                                 const struct vk_sync_type *type,
                                 enum vk_sync_flags flags,
                                 uint64_t initial_value);

void vk_sync_finish(struct vk_device *device,
                    struct vk_sync *sync);

VkResult MUST_CHECK vk_sync_create(struct vk_device *device,
                                   const struct vk_sync_type *type,
                                   enum vk_sync_flags flags,
                                   uint64_t initial_value,
                                   struct vk_sync **sync_out);

void vk_sync_destroy(struct vk_device *device,
                     struct vk_sync *sync);

VkResult MUST_CHECK vk_sync_signal(struct vk_device *device,
                                   struct vk_sync *sync,
                                   uint64_t value);

VkResult MUST_CHECK vk_sync_get_value(struct vk_device *device,
                                      struct vk_sync *sync,
                                      uint64_t *value);

VkResult MUST_CHECK vk_sync_reset(struct vk_device *device,
                                  struct vk_sync *sync);

VkResult MUST_CHECK vk_sync_wait(struct vk_device *device,
                                 struct vk_sync *sync,
                                 uint64_t wait_value,
                                 enum vk_sync_wait_flags wait_flags,
                                 uint64_t abs_timeout_ns);

VkResult MUST_CHECK vk_sync_wait_many(struct vk_device *device,
                                      uint32_t wait_count,
                                      const struct vk_sync_wait *waits,
                                      enum vk_sync_wait_flags wait_flags,
                                      uint64_t abs_timeout_ns);

VkResult MUST_CHECK vk_sync_import_opaque_fd(struct vk_device *device,
                                             struct vk_sync *sync,
                                             int fd);

VkResult MUST_CHECK vk_sync_export_opaque_fd(struct vk_device *device,
                                             struct vk_sync *sync,
                                             int *fd);

VkResult MUST_CHECK vk_sync_import_sync_file(struct vk_device *device,
                                             struct vk_sync *sync,
                                             int sync_file);

VkResult MUST_CHECK vk_sync_export_sync_file(struct vk_device *device,
                                             struct vk_sync *sync,
                                             int *sync_file);

VkResult MUST_CHECK vk_sync_import_win32_handle(struct vk_device *device,
                                                struct vk_sync *sync,
                                                void *handle,
                                                const wchar_t *name);

VkResult MUST_CHECK vk_sync_export_win32_handle(struct vk_device *device,
                                                struct vk_sync *sync,
                                                void **handle);

VkResult MUST_CHECK vk_sync_set_win32_export_params(struct vk_device *device,
                                                    struct vk_sync *sync,
                                                    const void *security_attributes,
                                                    uint32_t access,
                                                    const wchar_t *name);

VkResult MUST_CHECK vk_sync_move(struct vk_device *device,
                                 struct vk_sync *dst,
                                 struct vk_sync *src);

#ifdef __cplusplus
}
#endif

#endif /* VK_SYNC_H */