// Copyright 2021 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

library fuchsia.hardware.goldfish;

using zx;

/// Goldfish sync device provides a simple and lightweight path to let
/// device (or "host") run specific commands (mostly graphics-related, such as
/// waiting on GPU command completion) triggered by Fuchsia (or "guest") and
/// notify Fuchsia once the command finishes.
///
/// A sync device could maintain multiple "Timelines", each of which can wait on
/// multiple commands (i.e. "guest->host" commands) and signal specific Fuchsia
/// events once a command finishes executing on device.
protocol SyncDevice {
    /// Create a new sync timeline.
    ///
    /// A protocol request `timeline_req` provides an interface to the
    /// `SyncTimeline`. Each device can have multiple timelines at the same
    /// time.
    CreateTimeline(request<SyncTimeline> timeline_req) -> ();
};

/// Timelines can run "guest->host" commands and notifies Fuchsia once a
/// command finishes executing.
///
/// The SyncTimeline should be kept alive until both the timeline connection
/// and all events returned from SyncTimeline are closed by clients.
protocol SyncTimeline {
    /// Runs `CMD_TRIGGER_HOST_WAIT` command: Starts a wait on the sync device
    /// ("host") with the given GlSync object and sync thread handles.
    /// Once the command ends, `event` will signal its peer.
    TriggerHostWait(uint64 host_glsync_handle,
                    uint64 host_syncthread_handle,
                    zx.handle:EVENTPAIR event);
};