sdk/fidl/fuchsia.net.interfaces.admin/control.fidl - fuchsia - Git at Google

 // Copyright 2021 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.interfaces.admin;

 using fuchsia.net;
 using fuchsia.hardware.network;
 using fuchsia.net.interfaces;

 /// The configuration for an interface.
 type Configuration = table {
     /// The IPv4 configuration for an interface.
     1: ipv4 @generated_name("Ipv4Configuration") table {
         /// Controls whether or not IPv4 unicast packets may be forwarded if not
         /// destined to the host.
         /// TODO(https://fxbug.dev/101709): Rename this field to
         /// unicast_forwarding.
         1: forwarding bool;

         /// Controls whether or not IPv4 multicast packets may be forwarded.
         2: multicast_forwarding bool;
     };

     /// The IPv6 configuration for an interface.
     2: ipv6 @generated_name("Ipv6Configuration") table {
         /// Controls whether or not IPv6 unicast packets may be forwarded if not
         /// destined to the host.
         /// TODO(https://fxbug.dev/101709): Rename this field to
         /// unicast_forwarding.
         1: forwarding bool;

         /// Controls whether or not IPv6 multicast packets may be forwarded.
         2: multicast_forwarding bool;
     };
 };

 /// Provides control over an interface.
 ///
 /// This protocol encodes the underlying interface's lifetime in both
 /// directions; the interface exists iff both ends of the protocol are open.
 /// That is:
 ///
 /// - Closing the client end causes the interface to be removed.
 /// - Observing a closure of the server end indicates the interface no longer
 ///   exists.
 protocol Control {
     // TODO(https://fxbug.dev/80621): Currently Netstack2's implementation
     // does not support any values being present in `parameters`, and will
     // cause an event containing `AddressRemovalReason.INVALID` to be sent
     // and the server end of the protocol to be closed.
     // TODO(https://fxbug.dev/100535): Clarify address semantics in regards to
     // adding and removing same address on different subnets and/or interfaces.
     /// Assigns an address to the interface.
     ///
     /// Errors are communicated via
     /// [`fuchsia.net.interfaces.admin/AddressStateProvider.OnAddressRemoved`].
     ///
     /// + request `address` the address to assign to the interface.
     /// + request `parameters` additional address-specific options.
     /// + request `address_state_provider` provides address assignment state
     ///     and enables updating address properties.
     AddAddress(resource struct {
         address fuchsia.net.Subnet;
         parameters AddressParameters;
         address_state_provider server_end:AddressStateProvider;
     });

     /// Removes an address from the interface.
     ///
     /// + request `address` the address to remove.
     /// - response `did_remove` `true` iff `address` was removed from the
     ///  interface as a consequence of this call.
     RemoveAddress(struct {
         address fuchsia.net.Subnet;
     }) -> (struct {
         did_remove bool;
     }) error flexible enum {};

     /// Gets the interface identifier.
     ///
     /// - response `id` the interface identifier.
     GetId() -> (struct {
         id fuchsia.net.interface_id;
     });

     /// Sets the configuration for the interface.
     ///
     /// Only set fields that are supported in the provided [`Configuration`]
     /// will be set; unset fields will be left unmodified. The server will
     /// return a [`Configuration`] which holds the previous configuration for
     /// fields that the interface supports and set, even if the call did not
     /// update the configuration's value.
     ///
     /// + request `config` the configuration fields to update on the interface.
     /// - response `previous_config` a snapshot of the interface's previous
     ///   configuration. Only supported fields present in `config` will be set.
     SetConfiguration(struct {
         config Configuration;
     }) -> (struct {
         previous_config Configuration;
     }) error flexible enum {};

     /// Gets a snapshot of the interface's configuration.
     ///
     /// The server will populate the returned [`Configuration`] with the
     /// configuration for features/protocols that the interface supports. That
     /// is, fields for unsupported configurations will be unset in the returned
     /// [`Configuration`].
     ///
     /// - response `config` a snapshot of the interface's configuration.
     GetConfiguration() -> (struct {
         config Configuration;
     }) error flexible enum {};

     /// Enables the interface.
     ///
     /// - response `did_enable` `true` iff the interface moved from disabled to
     /// enabled as a consequence of this call.
     Enable() -> (struct {
         did_enable bool;
     }) error flexible enum {};

     /// Disables the interface.
     ///
     /// - response `did_disable` `true` iff the interface moved from enabled to
     /// disabled as a consequence of this call.
     Disable() -> (struct {
         did_disable bool;
     }) error flexible enum {};

     /// Detaches the client end from the interface's lifetime.
     ///
     /// After calling `Detach`, closing this client end no longer causes the
     /// interface to be removed.
     Detach();

     /// Terminal event. Immediately precedes the closure of the server end of
     /// the protocol.
     ///
     /// - response `reason` the removal reason.
     -> OnInterfaceRemoved(struct {
         reason @generated_name("InterfaceRemovedReason") flexible enum {
             /// Interface failed to be instantiated because the requested name
             /// is in use.
             DUPLICATE_NAME = 1;
             /// The requested port is already bound to an interface.
             PORT_ALREADY_BOUND = 2;
             /// The provided device port can't be made into an interface because
             /// of incompatible configuration.
             BAD_PORT = 3;
             /// The device port backing this interface has been closed.
             PORT_CLOSED = 4;
             /// Administrative user action removed the interface.
             USER = 5;
         };
     });
 };

 /// Installs devices on the network stack.
 @discoverable
 protocol Installer {
     /// Installs a device on the network stack.
     ///
     /// + request `device` the device to install on the network stack.
     /// + request `device_control` grants access to the installed device.
     InstallDevice(resource struct {
         device client_end:fuchsia.hardware.network.Device;
         device_control server_end:DeviceControl;
     });
 };

 /// Administrative control over an installed device on the network stack.
 ///
 /// An instance of `DeviceControl` maps to an instance of
 /// [`fuchsia.hardware.network/Session`]. All interfaces generated from a single
 /// `DeviceControl` instance share the same `Session` and set of device buffers;
 /// and are therefore subject to backpressure over the same pool of resources.
 ///
 /// By the same measure, creating multiple `DeviceControl` instances attached to
 /// the same underlying device causes data copies, because each `DeviceControl`
 /// starts a new `Session`. For that reason, users should avoid creating
 /// multiple `DeviceControl` instances for the same device and prefer
 /// instantiating ports into interfaces from a single `DeviceControl` instance
 /// per device.
 ///
 /// This protocol encodes the underlying device's lifetime in both
 /// directions; the device exists iff both ends of the protocol are open.
 /// That is:
 ///
 /// - Closing the client end causes the device to be removed, including all
 ///   interfaces created from it.
 /// - Observing a closure of the server end indicates the device (and all
 ///   interfaces created from it) no longer exists.
 protocol DeviceControl {
     /// Creates an interface on the network stack.
     ///
     /// + request `port` the device's port to instantiate as an interface.
     /// + request `control` grants access to the created interface.
     CreateInterface(resource struct {
         port fuchsia.hardware.network.PortId;
         control server_end:Control;
         options table {
             /// New interface name.
             ///
             /// If not set, an implementation-defined name will be selected.
             1: name fuchsia.net.interfaces.name;
             /// The default metric value used for routes through this interface.
             ///
             /// If not set, the server will use a sensible default.
             // TODO(...) alias this type from fuchsia.net.routes
             // when it exists or remove if we decide against it?
             2: metric uint32;
         };
     });

     /// Detaches the client end from the device's lifetime.
     ///
     /// After calling `Detach`, closing this client end no longer causes the
     /// device or any of the interfaces created from it to be removed. Note that
     /// the lifetime of any created interface will continue to be coupled with
     /// the associated [`Control`] client end.
     Detach();
 };
	// Copyright 2021 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.interfaces.admin;

	using fuchsia.net;
	using fuchsia.hardware.network;
	using fuchsia.net.interfaces;

	/// The configuration for an interface.
	type Configuration = table {
	/// The IPv4 configuration for an interface.
	1: ipv4 @generated_name("Ipv4Configuration") table {
	/// Controls whether or not IPv4 unicast packets may be forwarded if not
	/// destined to the host.
	/// TODO(https://fxbug.dev/101709): Rename this field to
	/// unicast_forwarding.
	1: forwarding bool;

	/// Controls whether or not IPv4 multicast packets may be forwarded.
	2: multicast_forwarding bool;
	};

	/// The IPv6 configuration for an interface.
	2: ipv6 @generated_name("Ipv6Configuration") table {
	/// Controls whether or not IPv6 unicast packets may be forwarded if not
	/// destined to the host.
	/// TODO(https://fxbug.dev/101709): Rename this field to
	/// unicast_forwarding.
	1: forwarding bool;

	/// Controls whether or not IPv6 multicast packets may be forwarded.
	2: multicast_forwarding bool;
	};
	};

	/// Provides control over an interface.
	///
	/// This protocol encodes the underlying interface's lifetime in both
	/// directions; the interface exists iff both ends of the protocol are open.
	/// That is:
	///
	/// - Closing the client end causes the interface to be removed.
	/// - Observing a closure of the server end indicates the interface no longer
	/// exists.
	protocol Control {
	// TODO(https://fxbug.dev/80621): Currently Netstack2's implementation
	// does not support any values being present in `parameters`, and will
	// cause an event containing `AddressRemovalReason.INVALID` to be sent
	// and the server end of the protocol to be closed.
	// TODO(https://fxbug.dev/100535): Clarify address semantics in regards to
	// adding and removing same address on different subnets and/or interfaces.
	/// Assigns an address to the interface.
	///
	/// Errors are communicated via
	/// [`fuchsia.net.interfaces.admin/AddressStateProvider.OnAddressRemoved`].
	///
	/// + request `address` the address to assign to the interface.
	/// + request `parameters` additional address-specific options.
	/// + request `address_state_provider` provides address assignment state
	/// and enables updating address properties.
	AddAddress(resource struct {
	address fuchsia.net.Subnet;
	parameters AddressParameters;
	address_state_provider server_end:AddressStateProvider;
	});

	/// Removes an address from the interface.
	///
	/// + request `address` the address to remove.
	/// - response `did_remove` `true` iff `address` was removed from the
	/// interface as a consequence of this call.
	RemoveAddress(struct {
	address fuchsia.net.Subnet;
	}) -> (struct {
	did_remove bool;
	}) error flexible enum {};

	/// Gets the interface identifier.
	///
	/// - response `id` the interface identifier.
	GetId() -> (struct {
	id fuchsia.net.interface_id;
	});

	/// Sets the configuration for the interface.
	///
	/// Only set fields that are supported in the provided [`Configuration`]
	/// will be set; unset fields will be left unmodified. The server will
	/// return a [`Configuration`] which holds the previous configuration for
	/// fields that the interface supports and set, even if the call did not
	/// update the configuration's value.
	///
	/// + request `config` the configuration fields to update on the interface.
	/// - response `previous_config` a snapshot of the interface's previous
	/// configuration. Only supported fields present in `config` will be set.
	SetConfiguration(struct {
	config Configuration;
	}) -> (struct {
	previous_config Configuration;
	}) error flexible enum {};

	/// Gets a snapshot of the interface's configuration.
	///
	/// The server will populate the returned [`Configuration`] with the
	/// configuration for features/protocols that the interface supports. That
	/// is, fields for unsupported configurations will be unset in the returned
	/// [`Configuration`].
	///
	/// - response `config` a snapshot of the interface's configuration.
	GetConfiguration() -> (struct {
	config Configuration;
	}) error flexible enum {};

	/// Enables the interface.
	///
	/// - response `did_enable` `true` iff the interface moved from disabled to
	/// enabled as a consequence of this call.
	Enable() -> (struct {
	did_enable bool;
	}) error flexible enum {};

	/// Disables the interface.
	///
	/// - response `did_disable` `true` iff the interface moved from enabled to
	/// disabled as a consequence of this call.
	Disable() -> (struct {
	did_disable bool;
	}) error flexible enum {};

	/// Detaches the client end from the interface's lifetime.
	///
	/// After calling `Detach`, closing this client end no longer causes the
	/// interface to be removed.
	Detach();

	/// Terminal event. Immediately precedes the closure of the server end of
	/// the protocol.
	///
	/// - response `reason` the removal reason.
	-> OnInterfaceRemoved(struct {
	reason @generated_name("InterfaceRemovedReason") flexible enum {
	/// Interface failed to be instantiated because the requested name
	/// is in use.
	DUPLICATE_NAME = 1;
	/// The requested port is already bound to an interface.
	PORT_ALREADY_BOUND = 2;
	/// The provided device port can't be made into an interface because
	/// of incompatible configuration.
	BAD_PORT = 3;
	/// The device port backing this interface has been closed.
	PORT_CLOSED = 4;
	/// Administrative user action removed the interface.
	USER = 5;
	};
	});
	};

	/// Installs devices on the network stack.
	@discoverable
	protocol Installer {
	/// Installs a device on the network stack.
	///
	/// + request `device` the device to install on the network stack.
	/// + request `device_control` grants access to the installed device.
	InstallDevice(resource struct {
	device client_end:fuchsia.hardware.network.Device;
	device_control server_end:DeviceControl;
	});
	};

	/// Administrative control over an installed device on the network stack.
	///
	/// An instance of `DeviceControl` maps to an instance of
	/// [`fuchsia.hardware.network/Session`]. All interfaces generated from a single
	/// `DeviceControl` instance share the same `Session` and set of device buffers;
	/// and are therefore subject to backpressure over the same pool of resources.
	///
	/// By the same measure, creating multiple `DeviceControl` instances attached to
	/// the same underlying device causes data copies, because each `DeviceControl`
	/// starts a new `Session`. For that reason, users should avoid creating
	/// multiple `DeviceControl` instances for the same device and prefer
	/// instantiating ports into interfaces from a single `DeviceControl` instance
	/// per device.
	///
	/// This protocol encodes the underlying device's lifetime in both
	/// directions; the device exists iff both ends of the protocol are open.
	/// That is:
	///
	/// - Closing the client end causes the device to be removed, including all
	/// interfaces created from it.
	/// - Observing a closure of the server end indicates the device (and all
	/// interfaces created from it) no longer exists.
	protocol DeviceControl {
	/// Creates an interface on the network stack.
	///
	/// + request `port` the device's port to instantiate as an interface.
	/// + request `control` grants access to the created interface.
	CreateInterface(resource struct {
	port fuchsia.hardware.network.PortId;
	control server_end:Control;
	options table {
	/// New interface name.
	///
	/// If not set, an implementation-defined name will be selected.
	1: name fuchsia.net.interfaces.name;
	/// The default metric value used for routes through this interface.
	///
	/// If not set, the server will use a sensible default.
	// TODO(...) alias this type from fuchsia.net.routes
	// when it exists or remove if we decide against it?
	2: metric uint32;
	};
	});

	/// Detaches the client end from the device's lifetime.
	///
	/// After calling `Detach`, closing this client end no longer causes the
	/// device or any of the interfaces created from it to be removed. Note that
	/// the lifetime of any created interface will continue to be coupled with
	/// the associated [`Control`] client end.
	Detach();
	};