sdk/fidl/fuchsia.net.stack/stack.fidl - fuchsia - Git at Google

 // 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.net.stack;

 using fuchsia.hardware.ethernet;
 using fuchsia.hardware.network;
 using fuchsia.logger;
 using fuchsia.net;
 using fuchsia.net.name;
 using fuchsia.posix.socket;

 /// A list of IP addresses for an interface.
 // TODO(fxb/65218): Replace with an alias.
 using interface_address_list = vector<fuchsia.net.Subnet>:MAX;

 /// A path to a device node.
 alias device_path = string:255;

 /// A list of interface descriptors.
 alias interface_list = vector<InterfaceInfo>:255;

 enum PresenceStatus {
     /// The interface is added.
     ADDED = 1;
     /// The interface is removed.
     REMOVED = 2;
 };

 enum PhysicalStatus {
     /// The link is not attached to the medium.
     DOWN = 1;
     /// The link is attached to the medium.
     UP = 2;
 };

 enum AdministrativeStatus {
     /// The interface is administratively disabled.
     DISABLED = 1;
     /// The interface is administratively enabled.
     ENABLED = 2;
 };

 union InterfaceStatus {
     1: PresenceStatus presence;
     2: PhysicalStatus physical;
     3: AdministrativeStatus administrative;
 };

 struct InterfaceInfo {
     /// An opaque identifier for the interface, assigned by the stack.
     /// This identifier will never be 0, and will not be reused even if the device is removed and
     /// subsequently re-added. It is not stable across netstack instances.
     fuchsia.net.interface_id id;

     /// All info of an interface except the interface name.
     InterfaceProperties properties;
 };

 struct InterfaceProperties {
     /// Human-readable name of the interface. eg. eth001, wlanx35.
     fuchsia.posix.socket.interface_name name;

     /// The topological path to the device, representing a stable identifier for the interface
     /// hardware.
     device_path topopath;

     /// An unstable file path corresponding to the interface. Used in watching the creation
     /// and destruction of the interface, or in accessing the interface using netdump.
     device_path filepath;

     /// The MAC address of the interface, if available.
     fuchsia.hardware.ethernet.MacAddress? mac;

     /// The maximum transmission unit for the interface in bytes.
     uint32 mtu;

     /// The features present on the interface.
     fuchsia.hardware.ethernet.Features features;

     /// The administrative status of the interface.
     AdministrativeStatus administrative_status;

     /// The physical link status of the interface.
     PhysicalStatus physical_status;

     /// The list of addresses currently assigned to the interface.
     interface_address_list addresses;
 };

 /// A ForwardingDestination represents either the device that should transmit a packet or the address
 /// of the next hop in the route.
 union ForwardingDestination {
     /// The opaque identifier of the device to which packets should be forwarded.
     1: fuchsia.net.interface_id device_id;

     /// The IP address of the next hop, used to look up the next forwarding entry.
     2: fuchsia.net.IpAddress next_hop;
 };

 /// An entry in the forwarding table for the network stack.
 struct ForwardingEntry {
     /// The subnet is the key for the entry in the table.
     fuchsia.net.Subnet subnet;

     /// The destination that will receive the forwarded packet.
     ForwardingDestination destination;
 };

 struct InterfaceStatusChange {
     /// The opaque identifier of the device that had its status change.
     fuchsia.net.interface_id id;

     /// The new status.
     InterfaceStatus status;
 };

 enum Error {
     INTERNAL = 1;
     NOT_SUPPORTED = 2;
     INVALID_ARGS = 3;
     BAD_STATE = 4;
     TIME_OUT = 5;
     NOT_FOUND = 6;
     ALREADY_EXISTS = 7;
     IO = 8;
 };

 /// An Ethernet device.
 /// The provided `network_device` is expected to support `Ethernet` frames.
 /// Its MAC address and MAC filtering is controlled by the provided `mac` channel.
 resource struct EthernetDeviceDefinition {
     /// The connection to the device's data plane.
     fuchsia.hardware.network.Device network_device;
     /// The connection to the device's addressing control plane.
     fuchsia.hardware.network.MacAddressing mac;
 };

 /// Devices that can be used to back a `Stack` interface.
 resource union DeviceDefinition {
     /// A `fuchsia.hardware.network.Device` that exchanges only IP frames. It either doesn't have a
     /// layer 2 or its layer 2 is irrelevant to the `Stack`.
     1: fuchsia.hardware.network.Device ip;
     /// An Ethernet device.
     2: EthernetDeviceDefinition ethernet;
 };

 /// Base configuration for `Stack` interfaces.
 table InterfaceConfig {
     /// Human-readable name of the interface. eg. eth001, wlanx35.
     /// Will be set to a default generic name if not provided.
     1: fuchsia.posix.socket.interface_name name;

     /// The topological path to the device, representing a stable identifier for the interface
     /// hardware.
     2: device_path topopath;

     /// The default metric value used for routes to this interface.
     3: uint32 metric;
 };

 [Discoverable]
 protocol Stack {
     /// Add an Ethernet interface to the network stack. On success, returns the identifier assigned
     /// by the stack for use in subsequent calls.
     AddEthernetInterface(device_path topological_path, fuchsia.hardware.ethernet.Device device) -> (fuchsia.net.interface_id id) error Error;

     /// Add a new interface to the network stack backed by the provided `DeviceDefinition`. On
     /// success, returns the identifier assigned by the stack for use in subsequent calls.
     AddInterface(InterfaceConfig config, DeviceDefinition device) -> (fuchsia.net.interface_id id) error Error;

     /// Remove an Ethernet interface from the network stack.
     DelEthernetInterface(fuchsia.net.interface_id id) -> () error Error;

     /// List all the interfaces available in the network stack.
     ListInterfaces() -> (interface_list ifs);

     /// Retrieve info about a specific interface.
     GetInterfaceInfo(fuchsia.net.interface_id id) -> (InterfaceInfo info) error Error;

     /// Enable the interface. Packets may be processed by the stack after this call is processed.
     EnableInterface(fuchsia.net.interface_id id) -> () error Error;

     /// Disable the interface. The stack will no longer process packets after this call.
     DisableInterface(fuchsia.net.interface_id id) -> () error Error;

     /// Add an address to the interface. If the interface already has an address of a given type that
     /// does not allow duplicates, this method will return an error.
     AddInterfaceAddress(fuchsia.net.interface_id id, fuchsia.net.Subnet addr) -> () error Error;

     /// Remove the address from the interface. If the address is not assigned to the interface, an
     /// error is returned.
     DelInterfaceAddress(fuchsia.net.interface_id id, fuchsia.net.Subnet addr) -> () error Error;

     /// List all the entries in the forwarding table for the network stack.
     // TODO(fxbug.dev/38528): This is unbounded for now, until we change the API to allow for
     // pagination.
     GetForwardingTable() -> (vector<ForwardingEntry>:MAX table);

     /// Add a new entry to the forwarding table. If the table already contains an entry with the same
     /// subnet, an error is returned. The entry may be deleted using DelForwardingEntry first.
     AddForwardingEntry(ForwardingEntry entry) -> () error Error;

     /// Removes the forwarding entry with the given subnet. This will not affect any overlapping
     /// subnets (superset or subset) so the subnet must exactly match an entry in the forwarding
     /// table. If no entry for the subnet exists, an error is returned.
     DelForwardingEntry(fuchsia.net.Subnet subnet) -> () error Error;

     /// Enable the packet filter on a specific interface.
     EnablePacketFilter(fuchsia.net.interface_id id) -> () error Error;

     /// Disable the packet filter on a specific interface.
     DisablePacketFilter(fuchsia.net.interface_id id) -> () error Error;

     /// Enable IP Forwarding.
     EnableIpForwarding() -> ();

     /// Disable IP Forwarding.
     DisableIpForwarding() -> ();

     /// Get a [`fuchsia.net.name/DnsServerWatcher`].
     GetDnsServerWatcher(request<fuchsia.net.name.DnsServerWatcher> watcher);

     // Events

     /// A status change event is triggered whenever an interface's status changes.
     -> OnInterfaceStatusChange(InterfaceStatusChange info);
 };

 [Discoverable]
 protocol Log {
     /// Dynamically set a syslog level.
     // TODO(fxbug.dev/54198): replace by responding to the system wide
     // fuchsia.logger.LogSink.OnInterestChanged event.
     SetLogLevel(fuchsia.logger.LogLevelFilter level) -> () error Error;

     /// Dynamically set packet logging.
     // TODO(fxbug.dev/42432): replace with optional packet captures in Inspect
     // output.
     SetLogPackets(bool enabled) -> ();
 };
	// 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.net.stack;

	using fuchsia.hardware.ethernet;
	using fuchsia.hardware.network;
	using fuchsia.logger;
	using fuchsia.net;
	using fuchsia.net.name;
	using fuchsia.posix.socket;

	/// A list of IP addresses for an interface.
	// TODO(fxb/65218): Replace with an alias.
	using interface_address_list = vector<fuchsia.net.Subnet>:MAX;

	/// A path to a device node.
	alias device_path = string:255;

	/// A list of interface descriptors.
	alias interface_list = vector<InterfaceInfo>:255;

	enum PresenceStatus {
	/// The interface is added.
	ADDED = 1;
	/// The interface is removed.
	REMOVED = 2;
	};

	enum PhysicalStatus {
	/// The link is not attached to the medium.
	DOWN = 1;
	/// The link is attached to the medium.
	UP = 2;
	};

	enum AdministrativeStatus {
	/// The interface is administratively disabled.
	DISABLED = 1;
	/// The interface is administratively enabled.
	ENABLED = 2;
	};

	union InterfaceStatus {
	1: PresenceStatus presence;
	2: PhysicalStatus physical;
	3: AdministrativeStatus administrative;
	};

	struct InterfaceInfo {
	/// An opaque identifier for the interface, assigned by the stack.
	/// This identifier will never be 0, and will not be reused even if the device is removed and
	/// subsequently re-added. It is not stable across netstack instances.
	fuchsia.net.interface_id id;

	/// All info of an interface except the interface name.
	InterfaceProperties properties;
	};

	struct InterfaceProperties {
	/// Human-readable name of the interface. eg. eth001, wlanx35.
	fuchsia.posix.socket.interface_name name;

	/// The topological path to the device, representing a stable identifier for the interface
	/// hardware.
	device_path topopath;

	/// An unstable file path corresponding to the interface. Used in watching the creation
	/// and destruction of the interface, or in accessing the interface using netdump.
	device_path filepath;

	/// The MAC address of the interface, if available.
	fuchsia.hardware.ethernet.MacAddress? mac;

	/// The maximum transmission unit for the interface in bytes.
	uint32 mtu;

	/// The features present on the interface.
	fuchsia.hardware.ethernet.Features features;

	/// The administrative status of the interface.
	AdministrativeStatus administrative_status;

	/// The physical link status of the interface.
	PhysicalStatus physical_status;

	/// The list of addresses currently assigned to the interface.
	interface_address_list addresses;
	};

	/// A ForwardingDestination represents either the device that should transmit a packet or the address
	/// of the next hop in the route.
	union ForwardingDestination {
	/// The opaque identifier of the device to which packets should be forwarded.
	1: fuchsia.net.interface_id device_id;

	/// The IP address of the next hop, used to look up the next forwarding entry.
	2: fuchsia.net.IpAddress next_hop;
	};

	/// An entry in the forwarding table for the network stack.
	struct ForwardingEntry {
	/// The subnet is the key for the entry in the table.
	fuchsia.net.Subnet subnet;

	/// The destination that will receive the forwarded packet.
	ForwardingDestination destination;
	};

	struct InterfaceStatusChange {
	/// The opaque identifier of the device that had its status change.
	fuchsia.net.interface_id id;

	/// The new status.
	InterfaceStatus status;
	};

	enum Error {
	INTERNAL = 1;
	NOT_SUPPORTED = 2;
	INVALID_ARGS = 3;
	BAD_STATE = 4;
	TIME_OUT = 5;
	NOT_FOUND = 6;
	ALREADY_EXISTS = 7;
	IO = 8;
	};

	/// An Ethernet device.
	/// The provided `network_device` is expected to support `Ethernet` frames.
	/// Its MAC address and MAC filtering is controlled by the provided `mac` channel.
	resource struct EthernetDeviceDefinition {
	/// The connection to the device's data plane.
	fuchsia.hardware.network.Device network_device;
	/// The connection to the device's addressing control plane.
	fuchsia.hardware.network.MacAddressing mac;
	};

	/// Devices that can be used to back a `Stack` interface.
	resource union DeviceDefinition {
	/// A `fuchsia.hardware.network.Device` that exchanges only IP frames. It either doesn't have a
	/// layer 2 or its layer 2 is irrelevant to the `Stack`.
	1: fuchsia.hardware.network.Device ip;
	/// An Ethernet device.
	2: EthernetDeviceDefinition ethernet;
	};

	/// Base configuration for `Stack` interfaces.
	table InterfaceConfig {
	/// Human-readable name of the interface. eg. eth001, wlanx35.
	/// Will be set to a default generic name if not provided.
	1: fuchsia.posix.socket.interface_name name;

	/// The topological path to the device, representing a stable identifier for the interface
	/// hardware.
	2: device_path topopath;

	/// The default metric value used for routes to this interface.
	3: uint32 metric;
	};

	[Discoverable]
	protocol Stack {
	/// Add an Ethernet interface to the network stack. On success, returns the identifier assigned
	/// by the stack for use in subsequent calls.
	AddEthernetInterface(device_path topological_path, fuchsia.hardware.ethernet.Device device) -> (fuchsia.net.interface_id id) error Error;

	/// Add a new interface to the network stack backed by the provided `DeviceDefinition`. On
	/// success, returns the identifier assigned by the stack for use in subsequent calls.
	AddInterface(InterfaceConfig config, DeviceDefinition device) -> (fuchsia.net.interface_id id) error Error;

	/// Remove an Ethernet interface from the network stack.
	DelEthernetInterface(fuchsia.net.interface_id id) -> () error Error;

	/// List all the interfaces available in the network stack.
	ListInterfaces() -> (interface_list ifs);

	/// Retrieve info about a specific interface.
	GetInterfaceInfo(fuchsia.net.interface_id id) -> (InterfaceInfo info) error Error;

	/// Enable the interface. Packets may be processed by the stack after this call is processed.
	EnableInterface(fuchsia.net.interface_id id) -> () error Error;

	/// Disable the interface. The stack will no longer process packets after this call.
	DisableInterface(fuchsia.net.interface_id id) -> () error Error;

	/// Add an address to the interface. If the interface already has an address of a given type that
	/// does not allow duplicates, this method will return an error.
	AddInterfaceAddress(fuchsia.net.interface_id id, fuchsia.net.Subnet addr) -> () error Error;

	/// Remove the address from the interface. If the address is not assigned to the interface, an
	/// error is returned.
	DelInterfaceAddress(fuchsia.net.interface_id id, fuchsia.net.Subnet addr) -> () error Error;

	/// List all the entries in the forwarding table for the network stack.
	// TODO(fxbug.dev/38528): This is unbounded for now, until we change the API to allow for
	// pagination.
	GetForwardingTable() -> (vector<ForwardingEntry>:MAX table);

	/// Add a new entry to the forwarding table. If the table already contains an entry with the same
	/// subnet, an error is returned. The entry may be deleted using DelForwardingEntry first.
	AddForwardingEntry(ForwardingEntry entry) -> () error Error;

	/// Removes the forwarding entry with the given subnet. This will not affect any overlapping
	/// subnets (superset or subset) so the subnet must exactly match an entry in the forwarding
	/// table. If no entry for the subnet exists, an error is returned.
	DelForwardingEntry(fuchsia.net.Subnet subnet) -> () error Error;

	/// Enable the packet filter on a specific interface.
	EnablePacketFilter(fuchsia.net.interface_id id) -> () error Error;

	/// Disable the packet filter on a specific interface.
	DisablePacketFilter(fuchsia.net.interface_id id) -> () error Error;

	/// Enable IP Forwarding.
	EnableIpForwarding() -> ();

	/// Disable IP Forwarding.
	DisableIpForwarding() -> ();

	/// Get a [`fuchsia.net.name/DnsServerWatcher`].
	GetDnsServerWatcher(request<fuchsia.net.name.DnsServerWatcher> watcher);

	// Events

	/// A status change event is triggered whenever an interface's status changes.
	-> OnInterfaceStatusChange(InterfaceStatusChange info);
	};

	[Discoverable]
	protocol Log {
	/// Dynamically set a syslog level.
	// TODO(fxbug.dev/54198): replace by responding to the system wide
	// fuchsia.logger.LogSink.OnInterestChanged event.
	SetLogLevel(fuchsia.logger.LogLevelFilter level) -> () error Error;

	/// Dynamically set packet logging.
	// TODO(fxbug.dev/42432): replace with optional packet captures in Inspect
	// output.
	SetLogPackets(bool enabled) -> ();
	};