// Copyright 2018 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.overnet.protocol;

using zx;

/// A single message proxied from a Zircon channel over an Overnet stream.
struct ZirconChannelMessage {
    /// Bytes part of the payload.
    vector<uint8>:zx.CHANNEL_MAX_MSG_BYTES bytes;
    /// Handles part of the payload.
    vector<ZirconHandle>:zx.CHANNEL_MAX_MSG_HANDLES handles;
};

/// A single handle to be proxied.
/// Not all Zircon types are supported.
union ZirconHandle {
    /// A proxied channel.
    1: ChannelHandle channel;
    /// A proxied socket.
    2: SocketHandle socket;
    /// A proxied eventpair.
    3: EventPairHandle event_pair;
};

/// A proxied channel.
struct ChannelHandle {
    /// The handle rights that are given to this handle.
    ChannelRights rights;
    /// The Overnet proxy stream that was created to carry this channel.
    /// The protocol over said stream will be a `ZirconChannel`.
    StreamRef stream_ref;
};

/// The type of socket being communicated via [`fuchsia.overnet.protocol/SocketHandle`].
enum SocketType {
    /// A datagram oriented socket.
    DATAGRAM = 0;
    /// A stream oriented socket.
    STREAM = 1;
};

/// A proxied socket.
struct SocketHandle {
    /// The handle rights that are given to this handle.
    SocketRights rights;
    /// The Overnet proxy stream that was created to carry this socket.
    /// The protocol over said stream will be a `ZirconSocket`.
    StreamRef stream_ref;
    /// Socket options, per `zx_socket_create`.
    SocketType socket_type;
};

/// A proxied eventpair.
struct EventPairHandle {
    /// The handle rights that are given to this handle.
    EventPairRights rights;
    /// The Overnet proxy stream that was created to carry this eventpair.
    /// No payloads will be sent over this stream, however transport and signal control messages
    /// will be per the normal StreamControl/SignalUpdate protocols used for all handle types.
    StreamRef stream_ref;
};

/// Channel rights.
/// Overnet treats rights as per-object type, to reduce the space of things that can be communicated
/// over its wire format. Transfer rights are always assumed present.
bits ChannelRights : uint32 {
    READ = 0x01;
    WRITE = 0x02;
};

/// Socket rights.
/// Overnet treats rights as per-object type, to reduce the space of things that can be communicated
/// over its wire format. Transfer rights are always assumed present.
bits SocketRights : uint32 {
    READ = 0x01;
    WRITE = 0x02;
};

/// EventPair rights.
/// Overnet treats rights as per-object type, to reduce the space of things that can be communicated
/// over its wire format. Transfer rights are always assumed present.
bits EventPairRights : uint32 {
    DO_NOT_USE = 0x80000000;
};

/// Signals that can be propagated.
/// These are deliberately chosen to be different bits than defined in Zircon, to force mapping code
/// to exist, and minimize the chance that Zircon ABI accidentally becomes Overnet protocol.
bits Signals : uint32 {
    USER_0 = 0x01;
    USER_1 = 0x02;
    USER_2 = 0x04;
    USER_3 = 0x08;
    USER_4 = 0x10;
    USER_5 = 0x20;
    USER_6 = 0x40;
    USER_7 = 0x80;
};

/// Signal state updates.
/// Transported as a side channel for each handle type, these propagate some signal bits.
table SignalUpdate {
    /// Update some signals
    1: Signals assert_signals;
};