blob: 291464a37d02247b5eea2d133bf1f013a0ae4e11 [file] [log] [blame]
// 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> nets);
/// Creates a new network with given name and config.
CreateNetwork(string name, NetworkConfig config) -> (zx.status status, Network? net);
/// Gets a handle to a network.
GetNetwork(string 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> endp);
/// Creates endpoint with given name and config.
CreateEndpoint(string name, EndpointConfig config) -> (zx.status status, Endpoint? endpoint);
/// Gets a handle to an endpoint.
GetEndpoint(string 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 name);
/// Updates network configuration.
SetConfig(NetworkConfig config) -> (zx.status status);
/// Attaches endpoint with given name to network.
AttachEndpoint(string name) -> (zx.status status);
/// Removes endpoint with given name from network.
RemoveEndpoint(string 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.
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 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 name;
/// NetworkConfig to use when creating network.
NetworkConfig config;
/// Collection of endpoints to create and attach to network.
vector<EndpointSetup> endpoints;
};
/// Convenience struct for creating endpoints along with network setup.
struct EndpointSetup {
/// Endpoint name, must be unique in network context.
string 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> networks) -> (zx.status status, SetupHandle? setup_handle);
};