fuchsia.net.tun

PROTOCOLS

Device

Defined in fuchsia.net.tun/tun.fidl

Provides control over the created device.

The lifetime of the device is tied to the channel over which this protocol is served; closing a Device channel will trigger the destruction and deallocation of the underlying device, as well as all associated endpoints.

WriteFrame

Writes a frame to the device (data coming from network-end). Returns ZX_ERR_BAD_STATE if the device is offline.

If the device was created with the DeviceConfig.blocking option set to true, calls to WriteFrame will block until there is one buffer available to fulfill the request. Up to MAX_PENDING_OPERATIONS calls to WriteFrame may be enqueued in such a way, after which ZX_ERR_NO_RESOURCES is returned.

Alternatively, if blocking is set to false calls to WriteFrame will return ZX_ERR_SHOULD_WAIT if there are no buffers available to fulfill the request.

Request

Name	Type
frame	Frame

Response

Name	Type
result	Device_WriteFrame_Result

ReadFrame

Gets the next frame from the device (data coming from host-end).

If the device was created with the DeviceConfig.blocking option set to true, calls to ReadFrame will block until there is a frame available to be read. Up to MAX_PENDING_OPERATIONS calls to ReadFrame may be enqueued in such a way, after which ZX_ERR_NO_RESOURCES is returned.

Alternatively, if blocking is set to false calls to ReadFrame will return ZX_ERR_SHOULD_WAIT if there are no frames to be read.

Request

Name	Type

Response

Name	Type
result	Device_ReadFrame_Result

GetSignals

Retrieves an eventpair that is signalled with SIGNAL_READABLE and SIGNAL_WRITABLE when read and write buffers are available, respectively.

Request

Name	Type

Response

Name	Type
signals	handle<eventpair>

GetState

Gets a snapshot of the device's internal state.

Request

Name	Type

Response

Name	Type
state	InternalState

WatchState

Observes changes to internal state.

The first call will always return the current internal state, subsequent calls will block until the internal state differs from the last one returned from a WatchState call.

WatchState does not provide full history of internal state changes. It is possible that intermediary internal state changes are missed in between WatchState calls.

Request

Name	Type

Response

Name	Type
state	InternalState

SetOnline

Sets the device's online status.

The online status is visible through fuchsia.hardware.network/Device.GetStatus. Once SetOnline returns, the status reported through GetStatus is guaranteed to be the one passed to SetOnline, no guarantees can be made otherwise due to the asynchronous nature of multi-channel operations.

Request

Name	Type
online	bool

Response

Name	Type

ConnectProtocols

Connects to the requested protocols for this Device.

Request

Name	Type
protos	Protocols

DevicePair

Defined in fuchsia.net.tun/tun.fidl

Provides control over a pair of network devices.

A DevicePair is a simpler version of Device that "shorts" two network device interfaces, named its "left" and "right" ends. The internal state of a DevicePair is not accessible, like it is for Device and it provides a more streamlined (and considerably faster) pair of fuchsia.hardware.network/Devices (and optionally fuchsia.hardware.network/MacAddressings). The transmit side of the left end is connected to the receive side of the right end, and vice-versa. A DevicePair's online signal is handled internally (online if any of the ends has an active data session), and if MAC addresses are provided on creation, the only supported MAC filtering mode is PROMISCUOUS. The lifetime of the underlying devices is tied to the DevicePair channel, closing a DevicePair channel will trigger the destruction and deallocation of the underlying devices.

ConnectProtocols

Connects to the requested protocols of this DevicePair.

Request

Name	Type
requests	DevicePairEnds

Control

Defined in fuchsia.net.tun/tun.fidl

Control interface. Control allows creating an arbitrary number of Devices and DevicePairs.

CreateDevice

Creates a Device with given config. If config is not valid or the device could not be created, device is closed with an error epitaph.

Request

Name	Type
config	DeviceConfig
device	request<Device>

CreatePair

Creates a DevicePair with given config. If config is not valid or the device could not be created, device_pair is closed with an error epitaph.

Request

Name	Type
config	DevicePairConfig
device_pair	request<DevicePair>

STRUCTS

Device_WriteFrame_Response

Defined in fuchsia.net.tun/tun.fidl

Name	Type	Description	Default

Device_ReadFrame_Response

Defined in fuchsia.net.tun/tun.fidl

Name	Type	Description	Default
frame	Frame		No default

FrameMetadata

Defined in fuchsia.net.tun/tun.fidl

Extra frame metadata.

This is an opaque holder for extra information that is associated with Network Device data frames.

Name	Type	Description	Default
info_type	fuchsia.hardware.network/InfoType	Additional frame information type.	No default
info	vector<uint8>[4096]	Additional frame information value.	No default
flags	uint32	Frame flags. RxFlags for WriteFrame and TxFlags for ReadFrame.	No default

TABLES

BaseConfig

Defined in fuchsia.net.tun/tun.fidl

Common configuration used to create a Device or DevicePair.

Ordinal	Name	Type	Description
1	mtu	uint32	Device MTU (maximum transmit unit). If a value greater than MAX_MTU is provided, creating a device will fail. Defaults to MAX_MTU.
2	rx_types	vector<fuchsia.hardware.network/FrameType>[4]	Supported Rx frame types for device. Required. Must be non-empty, otherwise creating the device will fail.
3	tx_types	vector<fuchsia.hardware.network/FrameTypeSupport>[4]	Supported Tx frame types on device. Required. Must be non-empty, otherwise creating the device will fail.
4	report_metadata	bool	Report frame metadata on receiving frames. Defaults to false.

DeviceConfig

Defined in fuchsia.net.tun/tun.fidl

Configuration used to create a Device.

Ordinal	Name	Type	Description
1	base	BaseConfig	Common configuration. Required.
2	online	bool	Start device with link online. Defaults to false.
3	blocking	bool	If true, Device.WriteFrame and Device.ReadFrame will block returning until the corresponding buffers are available to complete the call. Defaults to false.
4	mac	fuchsia.net/MacAddress	MAC address to report. If provided, device will support the fuchsia.hardware.network/MacAddressing protocol through ConnectProtocols.

DevicePairConfig

Defined in fuchsia.net.tun/tun.fidl

Configuration used to create a DevicePair.

Ordinal	Name	Type	Description
1	base	BaseConfig	Common configuration. Required.
2	fallible_transmit_left	bool	If true, transmit buffers on the left end will be dropped if no receive buffers are available on the right end to receive it. Otherwise, transmit buffers will wait until a receive buffer is available to copy them to. Defaults to false.
3	fallible_transmit_right	bool	Like fallible_transmit_left but allows writes to the right end to be fallible.
4	mac_left	fuchsia.net/MacAddress	MAC address to report on the left side of the pair. If provided, the left device will support the fuchsia.hardware.network/MacAddressing protocol through ConnectProtocols.
5	mac_right	fuchsia.net/MacAddress	Same as mac_left, but for the right side of the pair.

MacState

Defined in fuchsia.net.tun/tun.fidl

State associated with Mac Address filtering.

Devices never perform any MAC address filtering, but they implement the fuchsia.hardware.network/MacAddressing interface and store the values to be retrieved through the InternalState structure.

Ordinal	Name	Type	Description
1	mode	fuchsia.hardware.network/MacFilterMode	The currently configured MAC Address filtering mode.
2	multicast_filters	vector<fuchsia.net/MacAddress>[64]	The full list of configured multicast address filtering.

InternalState

Defined in fuchsia.net.tun/tun.fidl

Internal device state.

Ordinal	Name	Type	Description
1	mac	MacState	Mac addressing state. Will only be provided if mac is provided in the Config structure upon creation of the device.
2	has_session	bool	true if there is a session currently opened and running with the Device's network device endpoint.

Protocols

Defined in fuchsia.net.tun/tun.fidl

Collection of request protocols that tun devices can offer.

Ordinal	Name	Type	Description
1	network_device	request<fuchsia.hardware.network/Device>	Connection request to the fuchsia.hardware.network/Device protocol. The request is always fulfilled.
2	mac_addressing	request<fuchsia.hardware.network/MacAddressing>	Connection request to the fuchsia.hardware.network/MacAddressing protocol. The request will be immediately closed if the device was not created with a MAC address.

Frame

Defined in fuchsia.net.tun/tun.fidl

A frame written to or read from a Device.

Required fields must always be provided to Device.WriteFrame and are always present when returned by Device.ReadFrame.

Ordinal	Name	Type	Description
1	frame_type	fuchsia.hardware.network/FrameType	The type identifying this frame's payload. Required.
2	data	vector<uint8>[16384]	The frame's payload. Required. Must be non-empty.
3	meta	FrameMetadata	Metadata associated with the frame.

DevicePairEnds

Defined in fuchsia.net.tun/tun.fidl

A collection of connection requests to ends of a DevicePair.

Used to connect to a DevicePair through DevicePair.ConnectProtocols.

Ordinal	Name	Type	Description
1	left	Protocols	Connection request to protocols on the left end.
2	right	Protocols	Connection request to protocols on the right end.

UNIONS

Device_WriteFrame_Result

Defined in fuchsia.net.tun/tun.fidl

Name	Type	Description
response	Device_WriteFrame_Response
err	zx/status

Device_ReadFrame_Result

Defined in fuchsia.net.tun/tun.fidl

Name	Type	Description
response	Device_ReadFrame_Response
err	zx/status

BITS

Signals

Type: uint32

Name	Value	Description
WRITABLE	16777216	Indicates that write buffers are available to be used through Device.WriteFrame.
READABLE	33554432	Indicates that read buffers are available to be used through Device.ReadFrame.

CONSTANTS

Name	Value	Type	Description
MAX_MULTICAST_FILTERS	64	uint32	Maximum number of multicast filters that a device will hold in MacState.
MAX_PENDING_OPERATIONS	32	uint32	Maximum number of pending Device.WriteFrame or Device.ReadFrame that are allowed.
MAX_MTU	16384	uint32	Maximum supported MTU.