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.net.interfaces;
 using fuchsia.net.name;
 using fuchsia.net;

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

 // TODO(https://fxbug.dev/75554): Migrate callers and remove this.
 @deprecated("Use fuchsia.net.interfaces/Watcher")
 type InterfaceInfo = struct {
     /// 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.
     id fuchsia.net.interface_id;

     /// All info of an interface except the interface name.
     properties @generated_name("InterfaceProperties") struct {
         /// Human-readable name of the interface. eg. eth001, wlanx35.
         name fuchsia.net.interfaces.name;

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

         /// 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.
         filepath device_path;

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

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

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

         /// The administrative status of the interface.
         administrative_status strict enum {
             /// The interface is administratively disabled.
             DISABLED = 1;
             /// The interface is administratively enabled.
             ENABLED = 2;
         };

         /// The physical link status of the interface.
         physical_status strict enum {
             /// The link is not attached to the medium.
             DOWN = 1;
             /// The link is attached to the medium.
             UP = 2;
         };

         /// The list of addresses currently assigned to the interface.
         addresses vector<fuchsia.net.Subnet>:MAX;
     };
 };

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

     /// The destination that will receive the forwarded packet.
     destination @generated_name("ForwardingDestination") strict union {
         /// The opaque identifier of the device to which packets should be
         /// forwarded.
         1: device_id fuchsia.net.interface_id;

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

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

 @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(resource struct {
         topological_path device_path;
         device client_end:fuchsia.hardware.ethernet.Device;
     }) -> (struct {
         id fuchsia.net.interface_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(resource struct {
         config @generated_name("InterfaceConfig") table {
             /// Human-readable name of the interface. eg. eth001, wlanx35.
             /// Will be set to a default generic name if not provided.
             1: name fuchsia.net.interfaces.name;

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

             /// The default metric value used for routes to this interface.
             3: metric uint32;
         };
         device @generated_name("DeviceDefinition") strict resource union {
             /// 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: ip client_end:fuchsia.hardware.network.Device;
             /// An Ethernet device.
             ///
             /// The provided `network_device` is expected to support `Ethernet`
             /// frames. Its MAC address and MAC filtering is controlled by
             /// `mac`.
             2: ethernet @generated_name("EthernetDeviceDefinition") resource struct {
                 /// The connection to the device's data plane.
                 network_device client_end:fuchsia.hardware.network.Device;
                 /// The connection to the device's addressing control plane.
                 mac client_end:fuchsia.hardware.network.MacAddressing;
             };
         };
     }) -> (struct {
         id fuchsia.net.interface_id;
     }) error Error;

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

     // TODO(https://fxbug.dev/75554): Migrate callers and remove this.
     /// List all the interfaces available in the network stack.
     @deprecated("Use fuchsia.net.interfaces/Watcher")
     ListInterfaces() -> (struct {
         ifs vector<InterfaceInfo>:255;
     });

     // TODO(https://fxbug.dev/75554): Migrate callers and remove this.
     /// Retrieve info about a specific interface.
     @deprecated("Use fuchsia.net.interfaces/Watcher")
     GetInterfaceInfo(struct {
         id fuchsia.net.interface_id;
     }) -> (struct {
         info InterfaceInfo;
     }) error Error;

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

     /// Disable the interface. The stack will no longer process packets after
     /// this call.
     DisableInterface(struct {
         id fuchsia.net.interface_id;
     }) -> (struct {}) 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.
     @deprecated("Use fuchsia.net.interfaces.admin/Control.AddAddress")
     AddInterfaceAddress(struct {
         id fuchsia.net.interface_id;
         addr fuchsia.net.Subnet;
     }) -> (struct {}) error Error;

     /// Remove the address from the interface. If the address is not assigned to
     /// the interface, an error is returned.
     @deprecated("Use fuchsia.net.interfaces.admin/Control.RemoveAddress")
     DelInterfaceAddress(struct {
         id fuchsia.net.interface_id;
         addr fuchsia.net.Subnet;
     }) -> (struct {}) error Error;

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

     /// Add a new entry to the forwarding table.
     ///
     /// If the table already contains an entry with the same subnet and
     /// destination, an already exists error is returned.
     AddForwardingEntry(struct {
         entry ForwardingEntry;
     }) -> (struct {}) 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(struct {
         subnet fuchsia.net.Subnet;
     }) -> (struct {}) error Error;

     /// Enable IP Forwarding for all interfaces and IP versions.
     EnableIpForwarding() -> ();

     /// Disable IP Forwarding for all interfaces and IP versions.
     DisableIpForwarding() -> ();

     /// Returns the IP forwarding state for an interface.
     GetInterfaceIpForwarding(struct {
         id fuchsia.net.interface_id;
         ip_version fuchsia.net.IpVersion;
     }) -> (struct {
         enabled bool;
     }) error Error;

     /// Sets the IP forwarding state for an interface.
     SetInterfaceIpForwarding(struct {
         id fuchsia.net.interface_id;
         ip_version fuchsia.net.IpVersion;
         enabled bool;
     }) -> (struct {}) error Error;

     /// Get a [`fuchsia.net.name/DnsServerWatcher`].
     GetDnsServerWatcher(resource struct {
         watcher server_end:fuchsia.net.name.DnsServerWatcher;
     });
 };

 @discoverable
 protocol Log {
     /// Dynamically set packet logging.
     // TODO(fxbug.dev/42432): replace with optional packet captures in Inspect
     // output.
     SetLogPackets(struct {
         enabled bool;
     }) -> ();
 };
	// 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.net.interfaces;
	using fuchsia.net.name;
	using fuchsia.net;

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

	// TODO(https://fxbug.dev/75554): Migrate callers and remove this.
	@deprecated("Use fuchsia.net.interfaces/Watcher")
	type InterfaceInfo = struct {
	/// 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.
	id fuchsia.net.interface_id;

	/// All info of an interface except the interface name.
	properties @generated_name("InterfaceProperties") struct {
	/// Human-readable name of the interface. eg. eth001, wlanx35.
	name fuchsia.net.interfaces.name;

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

	/// 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.
	filepath device_path;

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

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

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

	/// The administrative status of the interface.
	administrative_status strict enum {
	/// The interface is administratively disabled.
	DISABLED = 1;
	/// The interface is administratively enabled.
	ENABLED = 2;
	};

	/// The physical link status of the interface.
	physical_status strict enum {
	/// The link is not attached to the medium.
	DOWN = 1;
	/// The link is attached to the medium.
	UP = 2;
	};

	/// The list of addresses currently assigned to the interface.
	addresses vector<fuchsia.net.Subnet>:MAX;
	};
	};

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

	/// The destination that will receive the forwarded packet.
	destination @generated_name("ForwardingDestination") strict union {
	/// The opaque identifier of the device to which packets should be
	/// forwarded.
	1: device_id fuchsia.net.interface_id;

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

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

	@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(resource struct {
	topological_path device_path;
	device client_end:fuchsia.hardware.ethernet.Device;
	}) -> (struct {
	id fuchsia.net.interface_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(resource struct {
	config @generated_name("InterfaceConfig") table {
	/// Human-readable name of the interface. eg. eth001, wlanx35.
	/// Will be set to a default generic name if not provided.
	1: name fuchsia.net.interfaces.name;

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

	/// The default metric value used for routes to this interface.
	3: metric uint32;
	};
	device @generated_name("DeviceDefinition") strict resource union {
	/// 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: ip client_end:fuchsia.hardware.network.Device;
	/// An Ethernet device.
	///
	/// The provided `network_device` is expected to support `Ethernet`
	/// frames. Its MAC address and MAC filtering is controlled by
	/// `mac`.
	2: ethernet @generated_name("EthernetDeviceDefinition") resource struct {
	/// The connection to the device's data plane.
	network_device client_end:fuchsia.hardware.network.Device;
	/// The connection to the device's addressing control plane.
	mac client_end:fuchsia.hardware.network.MacAddressing;
	};
	};
	}) -> (struct {
	id fuchsia.net.interface_id;
	}) error Error;

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

	// TODO(https://fxbug.dev/75554): Migrate callers and remove this.
	/// List all the interfaces available in the network stack.
	@deprecated("Use fuchsia.net.interfaces/Watcher")
	ListInterfaces() -> (struct {
	ifs vector<InterfaceInfo>:255;
	});

	// TODO(https://fxbug.dev/75554): Migrate callers and remove this.
	/// Retrieve info about a specific interface.
	@deprecated("Use fuchsia.net.interfaces/Watcher")
	GetInterfaceInfo(struct {
	id fuchsia.net.interface_id;
	}) -> (struct {
	info InterfaceInfo;
	}) error Error;

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

	/// Disable the interface. The stack will no longer process packets after
	/// this call.
	DisableInterface(struct {
	id fuchsia.net.interface_id;
	}) -> (struct {}) 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.
	@deprecated("Use fuchsia.net.interfaces.admin/Control.AddAddress")
	AddInterfaceAddress(struct {
	id fuchsia.net.interface_id;
	addr fuchsia.net.Subnet;
	}) -> (struct {}) error Error;

	/// Remove the address from the interface. If the address is not assigned to
	/// the interface, an error is returned.
	@deprecated("Use fuchsia.net.interfaces.admin/Control.RemoveAddress")
	DelInterfaceAddress(struct {
	id fuchsia.net.interface_id;
	addr fuchsia.net.Subnet;
	}) -> (struct {}) error Error;

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

	/// Add a new entry to the forwarding table.
	///
	/// If the table already contains an entry with the same subnet and
	/// destination, an already exists error is returned.
	AddForwardingEntry(struct {
	entry ForwardingEntry;
	}) -> (struct {}) 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(struct {
	subnet fuchsia.net.Subnet;
	}) -> (struct {}) error Error;

	/// Enable IP Forwarding for all interfaces and IP versions.
	EnableIpForwarding() -> ();

	/// Disable IP Forwarding for all interfaces and IP versions.
	DisableIpForwarding() -> ();

	/// Returns the IP forwarding state for an interface.
	GetInterfaceIpForwarding(struct {
	id fuchsia.net.interface_id;
	ip_version fuchsia.net.IpVersion;
	}) -> (struct {
	enabled bool;
	}) error Error;

	/// Sets the IP forwarding state for an interface.
	SetInterfaceIpForwarding(struct {
	id fuchsia.net.interface_id;
	ip_version fuchsia.net.IpVersion;
	enabled bool;
	}) -> (struct {}) error Error;

	/// Get a [`fuchsia.net.name/DnsServerWatcher`].
	GetDnsServerWatcher(resource struct {
	watcher server_end:fuchsia.net.name.DnsServerWatcher;
	});
	};

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