src/connectivity/network/testing/netemul/lib/fidl/network.fidl

// 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.netemul.network;

using fuchsia.hardware.ethernet;
using fuchsia.hardware.network;
using fuchsia.net;
using zx;

/// Provides emulated latency configuration.
struct LatencyConfig {
    /// Average latency, in ms.
    uint64 average;
    /// Latency standard deviation, in ms.
    uint64 std_dev;
};

// Note: Loss config is a union to be able to provide other models of packet loss.
/// Provides emulated packet loss configuration.
union LossConfig {
    /// Rate of packet loss expressed as independent drop probability [0-100].
    1: uint8 random_rate;
};

/// Provides emulated packet reordering configuration.
struct ReorderConfig {
    /// Size of buffer, in packets, to store and forward with randomized order.
    uint32 store_buff;
    /// Tick/deadline in ms to empty buffer, regardless of full state.
    /// 0 will cause buffer to flush only when full (dangerous).
    uint64 tick;
};

/// Used to configure a network with emulated adversity conditions.
table NetworkConfig {
    /// Latency configuration.
    1: LatencyConfig latency;
    /// Packet loss configuration.
    2: LossConfig packet_loss;
    /// Packet reordering configuration.
    3: ReorderConfig reorder;
};

/// Manages virtual networks.
protocol NetworkManager {
    /// Lists emulated networks by name.
    ListNetworks() -> (vector<string:MAX>:MAX nets);
    /// Creates a new network with given name and config.
    CreateNetwork(string:MAX name, NetworkConfig config) -> (zx.status status, Network? net);
    /// Gets a handle to a network.
    GetNetwork(string:MAX name) -> (Network? net);
};

/// Backing of an emulated endpoint.
enum EndpointBacking {
    /// Endpoint backed by ethertap device.
    ETHERTAP = 1;
    /// Endpoint backed by a network-tun device.
    /// The created `fuchsia.hardware.network.Device` always acts as a virtual ethernet device.
    NETWORK_DEVICE = 2;
};

/// Configuration used to create an endpoint.
struct EndpointConfig {
    /// Fake ethernet mtu.
    uint16 mtu;
    /// Fake ethernet mac address, if not provided will be set to randomized local mac,
    /// using endpoint name as seed.
    fuchsia.net.MacAddress? mac;
    /// Backing type of emulated endpoint.
    EndpointBacking backing;
};

/// Manages virtual endpoints.
protocol EndpointManager {
    /// Lists endpoints by name.
    ListEndpoints() -> (vector<string:MAX>:MAX endp);
    /// Creates endpoint with given name and config.
    CreateEndpoint(string:MAX name, EndpointConfig config) -> (zx.status status, Endpoint? endpoint);
    /// Gets a handle to an endpoint.
    GetEndpoint(string:MAX name) -> (Endpoint? endpoint);
};

/// Fake endpoint can be added to a network to snoop or inject packets.
protocol FakeEndpoint {
    /// Writes a frame to the network.
    Write(vector<uint8>:MAX data) -> ();
    /// Reads a single frame from the network.
    ///
    /// Blocks until new data is available to be read. FakeEndpoint will keep a limited amount of
    /// frames to be read, dropping the oldest ones if the data is not fetched fast enough. The
    /// number of dropped frames since the last call to `Read` is returned in `dropped_frames`.
    ///
    /// Issuing a second `Read` request when the first one is still pending will cause the channel
    /// to be closed with `ZX_ERR_BAD_STATE`.
    Read() -> (vector<uint8>:MAX data, uint64 dropped_frames);
};

/// Virtual network.
protocol Network {
    /// Gets network configuration.
    GetConfig() -> (NetworkConfig config);
    /// Gets network name.
    GetName() -> (string:MAX name);
    /// Updates network configuration.
    SetConfig(NetworkConfig config) -> (zx.status status);
    /// Attaches endpoint with given name to network.
    AttachEndpoint(string:MAX name) -> (zx.status status);
    /// Removes endpoint with given name from network.
    RemoveEndpoint(string:MAX name) -> (zx.status status);
    /// Injects a fake endpoint.
    CreateFakeEndpoint(request<FakeEndpoint> ep);
};

/// Simple interface to serve devices over fidl.
protocol DeviceProxy {
    /// Fulfills the device request.
    /// The fulfilled requests's protocol is defined by the `Endpoint`'s `EndpointBacking`.
    ServeDevice(zx.handle:CHANNEL req);
};

/// A connection to an endpoint's underlying protocol.
resource union DeviceConnection {
    /// Set if the endpoint's backing is `ETHERTAP`.
    1: fuchsia.hardware.ethernet.Device ethernet;
    /// Set if the endpoint's backing is `NETWORK_DEVICE`.
    // NOTE(brunodalbo) the DeviceInstance protocol is a transient protocol that is exposed by devfs.
    // As documented in its definition, users should avoid passing this forward, but connect to its
    // internal protocols instead.
    2: fuchsia.hardware.network.DeviceInstance network_device;
};

/// Virtual ethernet endpoint.
protocol Endpoint {
    // Gets endpoint configuration.
    GetConfig() -> (EndpointConfig config);
    /// Gets endpoint name.
    GetName() -> (string:MAX name);
    /// Sends link up or down signal
    SetLinkUp(bool up) -> ();
    /// Opens a channel with the underlying device protocol.
    /// The resulting `DeviceConnection` variant is defined by this `Endpoint`'s `EndpointBacking`.
    GetDevice() -> (DeviceConnection device);
    /// Gets a proxy to open requests with zircon ethernet device.
    GetProxy(request<DeviceProxy> proxy);
};

/// Convenience struct for creating entire network setups.
struct NetworkSetup {
    /// Network name, must be unique in network context.
    string:MAX name;
    /// NetworkConfig to use when creating network.
    NetworkConfig config;
    /// Collection of endpoints to create and attach to network.
    vector<EndpointSetup>:MAX endpoints;
};

/// Convenience struct for creating endpoints along with network setup.
struct EndpointSetup {
    /// Endpoint name, must be unique in network context.
    string:MAX name;
    /// Optional endpoint config, if not provided defaults will be used.
    /// Default values are: mtu = 1500, backing = ETHERTAP, mac = randomized.
    EndpointConfig? config;
    /// Start endpoint with link status up.
    bool link_up;
};

/// Handle returned when using NetworkContext.Setup for quick network configuration.
/// Networks and endpoints created by Setup are tied to the lifecycle of the SetupHandle's channel.
protocol SetupHandle {
};

/// Main entry point to manage virtual networks and endpoints.
[Discoverable]
protocol NetworkContext {
    GetNetworkManager(request<NetworkManager> net_manager);
    GetEndpointManager(request<EndpointManager> endp_manager);
    /// Creates a collection of networks described by `networks`.
    /// `status` is `ZX_OK` for success
    /// `setup_handle` is a resource that references and maintains the lifecycle of
    ///                the created networks and endpoints.
    Setup(vector<NetworkSetup>:MAX networks) -> (zx.status status, SetupHandle? setup_handle);
};