// 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.pipe;

using zx;

/// Maximum number of buffers that can be used for read/write commands.
const MAX_BUFFERS_PER_COMMAND uint32 = 336;

/// Codes for supported pipe commands.
type PipeCmdCode = strict enum : int32 {
    OPEN = 1;
    CLOSE = 2;
    POLL = 3;
    WRITE = 4;
    WAKE_ON_WRITE = 5;
    READ = 6;
    WAKE_ON_READ = 7;
    CALL = 11;
};

/// Pipe device wake flags.
type PipeWakeFlag = strict enum : int32 {
    CLOSED = 1;
    READ = 2;
    WRITE = 4;
};

/// Pipe command errors. 0 is success.
type PipeError = strict enum : int32 {
    INVAL = -1;
    AGAIN = -2;
    NOMEM = -3;
    IO = -4;
};

/// Additional command parameters used for read/write commands.
/// Note: This structure is known to both the virtual device and driver.
@packed
type PipeCmdReadWriteParams = struct {
    buffers_count uint32;
    consumed_size int32;
    ptrs array<uint64, MAX_BUFFERS_PER_COMMAND>;
    sizes array<uint32, MAX_BUFFERS_PER_COMMAND>;
    read_index uint32;
};

/// Pipe command structure used for all commands.
/// Note: This structure is known to both the virtual device and driver.
@packed
type PipeCmdBuffer = struct {
    cmd int32;
    id int32;
    status int32;
    reserved int32;
    rw_params PipeCmdReadWriteParams;
};

/// This interface can be used to establish a goldfish pipe connection. The
/// client is responsible for managing the command structure associated with
/// the pipe and should issue a 'close' command before destroying a previously
/// opened pipe. Failure to do so may result in host side resources that are
/// not cleaned up properly.
@transport("Banjo")
@banjo_layout("ddk-protocol")
protocol GoldfishPipe {
    /// Create a new pipe connection. The |id| identifies the pipe and must be
    /// used for all subsequent commands. The memory that will be used as
    /// command structure is returned in |vmo|.
    Create() -> (resource struct {
        s zx.status;
        id int32;
        vmo zx.handle:VMO;
    });

    /// Destroy a previously created pipe connection.
    Destroy(struct {
        id int32;
    });

    /// Set event used to signal device state. Discards existing event
    /// after having transferred device state to the new event, if event
    /// exists.
    ///
    /// Return error states from `zx_object_wait_one` and `zx_object_signal`
    /// if existing events on `pipe_event` cannot be transferred to the call.
    /// Otherwise returns `ZX_OK`.
    SetEvent(resource struct {
        id int32;
        pipe_event zx.handle:EVENT;
    }) -> (struct {
        s zx.status;
    });

    /// Open pipe connection. This must be called before any other
    /// commands are issued and will cause the physical address of the
    /// command structure to be a associated with the pipe. The command
    /// structure must contain {.cmd = OPEN, .id = id} at the time this
    /// request is issued.
    Open(struct {
        id int32;
    });

    /// Execute pipe command stored in associated command structure.
    Exec(struct {
        id int32;
    });

    /// Get BTI that can be used create IO buffers for read/write commands.
    GetBti() -> (resource struct {
        s zx.status;
        bti zx.handle:BTI;
    });

    /// Create a sysmem connection - used to implement fuchsia.hardware.sysmem.
    ConnectSysmem(resource struct {
        connection zx.handle:CHANNEL;
    }) -> (struct {
        s zx.status;
    });

    /// Register a sysmem heap.
    RegisterSysmemHeap(resource struct {
        heap uint64;
        connection zx.handle:CHANNEL;
    }) -> (struct {
        s zx.status;
    });
};