// Copyright 2019 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;

/// Signal that will be active on event handle if the Read() method
/// will return data.
const SIGNAL_READABLE uint32 = 0x01000000; // ZX_USER_SIGNAL_0

/// Signal that will be active on event handle if the Write() method
/// will accept data.
const SIGNAL_WRITABLE uint32 = 0x02000000; // ZX_USER_SIGNAL_1

/// Signal that will be active on event handle if the device has been
/// disconnected.
const SIGNAL_HANGUP uint32 = 0x04000000; // ZX_USER_SIGNAL_2

/// This is the interface for the Goldfish pipe driver. It is used
/// to connect to a PipeDevice.
closed protocol Controller {
    /// Opens a new PipeDevice session.
    strict OpenSession(resource struct {
        session server_end:PipeDevice;
    });
};

/// Interface for the Goldfish pipe driver.
closed protocol PipeDevice {
    /// Open pipe. A protocol request `pipe_request` provides an interface
    /// to the pipe. Multiple pipes can be opened for a single device.
    /// Closing the device connection will also close all pipe connections.
    strict OpenPipe(resource struct {
        pipe_request server_end:Pipe;
    });
};

closed protocol Pipe {
    /// Request new IO buffer size. Can fail if out of memory. Discards
    /// contents of existing buffer on success. Leaves existing buffer
    /// intact on failure.
    strict SetBufferSize(struct {
        size uint64;
    }) -> (struct {
        res zx.Status;
    });

    /// Set event used to signal device state. Discards existing event
    /// after having transferred device state to the new event.
    strict SetEvent(resource struct {
        event zx.Handle:EVENT;
    });

    /// Acquire VMO for IO buffer. Can be called multiple times. Each call
    /// returns a new handle to the VMO.
    strict GetBuffer() -> (resource struct {
        res zx.Status;
        vmo zx.Handle:<VMO, optional>;
    });

    /// Attempt to read up to count bytes into IO buffer at specified offset.
    /// Returns `ZX_ERR_SHOULD_WAIT` if pipe device is not readable.
    strict Read(struct {
        count uint64;
        offset uint64;
    }) -> (struct {
        res zx.Status;
        actual uint64;
    });

    /// Writes up to count bytes from the IO buffer at specified offset.
    /// Returns `ZX_ERR_SHOULD_WAIT` if pipe device is not writable.
    strict Write(struct {
        count uint64;
        offset uint64;
    }) -> (struct {
        res zx.Status;
        actual uint64;
    });

    /// Writes `count` bytes from the IO buffer at specified write
    /// `offset`. Returns `ZX_ERR_SHOULD_WAIT` if pipe device is not writable.
    ///
    /// If it writes to device successfully, it subsequently reads `read_count`
    /// bytes into the IO buffer at specified `read_offset`. Returns
    /// `ZX_ERR_SHOULD_WAIT` if pipe device is not readable.
    ///
    /// Return value `actual` is the total bytes read from and written to
    /// the IO buffer.
    ///
    /// The name "DoCall" (instead of "Call") is to avoid collision with LLCPP
    /// generated code "class Call" (generated per protocol).  We don't want
    /// this method attempting to compile as if it were a constructor.
    strict DoCall(struct {
        count uint64;
        offset uint64;
        read_count uint64;
        read_offset uint64;
    }) -> (struct {
        res zx.Status;
        actual uint64;
    });
};