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

// WARNING: The overnet protocol is considered frozen and should not be
// modified. Future development will likely occur in a new protocol, such as
// is proposed in RFC-0228

using zx;

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

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

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

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

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

/// A proxied eventpair.
type EventPairHandle = struct {
    /// The handle rights that are given to this handle.
    rights EventPairRights;
    /// 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.
    stream_ref StreamRef;
};

/// 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.
type ChannelRights = strict bits : 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.
type SocketRights = strict bits : 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.
type EventPairRights = strict bits : 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.
type Signals = strict bits : 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.
type SignalUpdate = table {
    /// Update some signals
    1: assert_signals Signals;
};