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

// TODO(fxb/39732): This should be read as "library zx".
library zz;

using ObjType = uint32;

// TODO(scottmg): ZX_OBJ_TYPE_xyz here.

using HandleOp = uint32;

// TODO(scottmg): ZX_HANDLE_OP_xyz here.

struct HandleInfo {
    handle handle;
    ObjType type;
    rights rights;
    uint32 unused;
};

struct ChannelCallArgs {
    vector<byte> wr_bytes;
    vector<handle> wr_handles;
    // TODO(scottmg): mutable_vector_void
    vector<byte> rd_bytes;
    // TODO(scottmg): mutable_vector_handle
    vector<handle> rd_handles;
};

struct HandleDisposition {
    HandleOp operation;
    handle handle;
    ObjType type;
    rights rights;
    status result;
};

[Transport = "Syscall"]
protocol channel {
    /// Create a channel.
    channel_create(uint32 options) -> (status status, handle out0, handle out1);

    /// Read a message from a channel.
    /// Rights: handle must be of type ZX_OBJ_TYPE_CHANNEL and have ZX_RIGHT_READ.
    [ArgReorder = "handle, options, bytes, handles, num_bytes, num_handles, actual_bytes, actual_handles",
     HandleUnchecked]
    channel_read(handle<channel> handle,
                 uint32 options)
        -> (status status,
            vector_void_u32size bytes,
            vector_handle_u32size handles,
            optional_uint32 actual_bytes,
            optional_uint32 actual_handles);

    /// Read a message from a channel.
    /// Rights: handle must be of type ZX_OBJ_TYPE_CHANNEL and have ZX_RIGHT_READ.
    [ArgReorder = "handle, options, bytes, handles, num_bytes, num_handles, actual_bytes, actual_handles"]
    channel_read_etc(handle<channel> handle,
                     uint32 options)
        -> (status status,
            vector_void_u32size bytes,
            vector_HandleInfo_u32size handles,
            optional_uint32 actual_bytes,
            optional_uint32 actual_handles);

    /// Write a message to a channel.
    /// Rights: handle must be of type ZX_OBJ_TYPE_CHANNEL and have ZX_RIGHT_WRITE.
    /// Rights: Every entry of handles must have ZX_RIGHT_TRANSFER.
    channel_write(handle<channel> handle,
                  uint32 options,
                  vector_void_u32size bytes,
                  vector_handle_u32size handles)
        -> (status status);

    /// Write a message to a channel.
    /// Rights: handle must be of type ZX_OBJ_TYPE_CHANNEL and have ZX_RIGHT_WRITE.
    /// Rights: Every entry of handles must have ZX_RIGHT_TRANSFER.
    channel_write_etc(handle<channel> handle,
                      uint32 options,
                      vector_void_u32size bytes,
                      mutable_vector_HandleDisposition_u32size handles)
        -> (status status);

    /// Rights: handle must be of type ZX_OBJ_TYPE_CHANNEL and have ZX_RIGHT_READ and have ZX_RIGHT_WRITE.
    /// Rights: All wr_handles of args must have ZX_RIGHT_TRANSFER.
    [internal]
    channel_call_noretry(handle<channel> handle,
                         uint32 options,
                         time deadline,
                         ChannelCallArgs args)
        -> (status status, uint32 actual_bytes, uint32 actual_handles);

    [internal]
    channel_call_finish(time deadline, ChannelCallArgs args)
        -> (status status, uint32 actual_bytes, uint32 actual_handles);

    /// Send a message to a channel and await a reply.
    /// Rights: handle must be of type ZX_OBJ_TYPE_CHANNEL and have ZX_RIGHT_READ and have ZX_RIGHT_WRITE.
    /// Rights: All wr_handles of args must have ZX_RIGHT_TRANSFER.
    [blocking,
    vdsocall]
    // TODO(scottmg): Express "All wr_handles of args must have ZX_RIGHT_TRANSFER."
    channel_call(handle handle, uint32 options, time deadline, ChannelCallArgs args)
        -> (status status, uint32 actual_bytes, uint32 actual_handles);
};