fuchsia.net.tun

PROTOCOLS

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.

request config new device configuration.
request device grants control over the device. Closed with an epitaph if config is not valid.

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 config new device pair configuration.
request device_pair grants control over the device pair. Closed with an epitaph if config is not valid.

Request

Name	Type
`config`	`DevicePairConfig`
`device_pair`	`request<DevicePair>`

Device

Defined in fuchsia.net.tun/tun.fidl

Provides control over the created device.

This protocol encodes the underlying object's lifetime in both directions; the underlying object is alive iff both ends of the protocol are open. That is:

Closing the client end causes the object to be destroyed.
Observing a closure of the server end indicates the object no longer exists.

AddPort

Creates a new port on this device.

request config new port configuration.
request port grants control over the port. Closed with an epitaph if config is not valid.

Request

Name	Type
`config`	`DevicePortConfig`
`port`	`request<Port>`

GetDevice

Connects to the underlying device endpoint.

request device device handle.

Request

Name	Type
`device`	`request<fuchsia.hardware.network/Device>`

GetSignals

Retrieves signals eventpair.

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

Request

<EMPTY>

Response

Name	Type
`signals`	`handle<eventpair>`

ReadFrame

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

If the device was created with the fuchsia.net.tun/DeviceConfig.blocking option set to true, calls to ReadFrame block until there is a frame available to be read.

response frame outbound frame data and metadata.

error ZX_ERR_NO_RESOURCES if more than fuchsia.net.tun/MAX_PENDING_OPERATIONS calls to ReadFrame are pending.
error ZX_ERR_SHOULD_WAIT if blocking is set to false and there are no frames to be read.

Request

<EMPTY>

Response

Name	Type
`result`	`Device_ReadFrame_Result`

WriteFrame

Writes a frame to the device (data coming from network-end).

If the device was created with the fuchsia.net.tun/DeviceConfig.blocking option set to true, calls to WriteFrame block until there is one buffer available to fulfill the request.

request frame inbound frame data and metadata.

error ZX_ERR_NOT_FOUND if Frame.port references an unknown port.
error ZX_ERR_INVALID_ARGS if frame is invalid.
error ZX_ERR_BAD_STATE if the device is offline.
error ZX_ERR_BAD_STATE if the device is offline.
error ZX_ERR_NO_RESOURCES if more than fuchsia.net.tun/MAX_PENDING_OPERATIONS calls to WriteFrame are pending.
error ZX_ERR_SHOULD_WAIT if blocking is set to false and there are no buffers available to fulfill the request.

Request

Name	Type
`frame`	`Frame`

Response

Name	Type
`result`	`Device_WriteFrame_Result`

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. The transmit side of each port of the left end is connected to the receive side of the port with the same identifier on the right end, and vice-versa. A DevicePair's port online signal is handled internally (online if any of the ends has an active data session). If MAC addresses are provided on creation, the only supported MAC filtering mode is PROMISCUOUS.

This protocol encodes the underlying object's lifetime in both directions; the underlying object is alive iff both ends of the protocol are open. That is:

Closing the client end causes the object to be destroyed.
Observing a closure of the server end indicates the object no longer exists.

AddPort

Adds a logical port to this device pair.

request config port configuration.

error ZX_ERR_INVALID_ARGS if config is invalid.
error ZX_ERR_ALREADY_EXISTS if the provided port identifier is already in use.

Request

Name	Type
`config`	`DevicePairPortConfig`

Response

Name	Type
`result`	`DevicePair_AddPort_Result`

GetLeft

Connects to the underlying left device endpoint.

request device handle serve the left device endpoint on.

Request

Name	Type
`device`	`request<fuchsia.hardware.network/Device>`

GetRight

Connects to the underlying right device endpoint.

request device handle serve the right device endpoint on.

Request

Name	Type
`device`	`request<fuchsia.hardware.network/Device>`

RemovePort

Removes a logical port created by fuchsia.net.tun/DevicePair.AddPort.

request id identifier of the port to remove.

error ZX_ERR_NOT_FOUND if id does not map to an existing port.

Request

Name	Type
`id`	`fuchsia.hardware.network/port_id`

Response

Name	Type
`result`	`DevicePair_RemovePort_Result`

Port

Defined in fuchsia.net.tun/tun.fidl

A logical port attached to a fuchsia.net.tun/Device.

This protocol encodes the underlying object's lifetime in both directions; the underlying object is alive iff both ends of the protocol are open. That is:

Closing the client end causes the object to be destroyed.
Observing a closure of the server end indicates the object no longer exists.

GetState

Gets the port internal state.

response state a snapshot of the port's internal state.

Request

<EMPTY>

Response

Name	Type
`state`	`InternalState`

SetOnline

Sets the port's online status.

The online status is visible through fuchsia.hardware.network/Port.GetStatus. Once SetOnline returns, the status reported through GetStatus is guaranteed to be the one passed to SetOnline.

request online desired port online state.

Request

Name	Type
`online`	`bool`

Response

<EMPTY>

WatchState

Observes changes to internal state.

The first call always returns the current internal state, subsequent calls 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.

response state the latest observed port internal state.

Request

<EMPTY>

Response

Name	Type
`state`	`InternalState`

STRUCTS

DevicePair_AddPort_Response

Defined in fuchsia.net.tun/tun.fidl

<EMPTY>

DevicePair_RemovePort_Response

Defined in fuchsia.net.tun/tun.fidl

<EMPTY>

Device_ReadFrame_Response

Defined in fuchsia.net.tun/tun.fidl

Field	Type	Description	Default
`frame`	`Frame`		No default

Device_WriteFrame_Response

Defined in fuchsia.net.tun/tun.fidl

<EMPTY>

FrameMetadata

Defined in fuchsia.net.tun/tun.fidl

Field Type Description Default

Field	Type	Description	Default
`info_type`	`fuchsia.hardware.network/InfoType`	Additional frame information type. If not set, interpreted as fuchsia.hardware.network/InfoType.NO_INFO.	No default
`info`	`vector<uint8>[4096]`	Additional frame information value. If not set, interpreted as empty bytes.	No default
`flags`	`uint32`	Frame flags. `RxFlags` for `WriteFrame` and `TxFlags` for `ReadFrame`. If not set, interpreted as zero.	No default

info_type

fuchsia.hardware.network/InfoType

Additional frame information type.

If not set, interpreted as fuchsia.hardware.network/InfoType.NO_INFO.

No default

info

vector<uint8>[4096]

Additional frame information value.

If not set, interpreted as empty bytes.

No default

flags

uint32

Frame flags. RxFlags for WriteFrame and TxFlags for ReadFrame.

If not set, interpreted as zero.

No default

TABLES

BaseDeviceConfig

Defined in fuchsia.net.tun/tun.fidl

Base device configuration.

Ordinal Field Type Description

Ordinal	Field	Type	Description
1	`report_metadata`	`bool`	Report frame metadata on receiving frames. If not set, Interpreted as `false`.
2	`min_tx_buffer_length`	`uint32`	Minimum requested TX buffer length, in bytes. If not set, interpreted as zero.
3	`min_rx_buffer_length`	`uint32`	Minimum requested RX buffer length, in bytes. If not set, interpreted as zero.

report_metadata

bool

Report frame metadata on receiving frames.

If not set, Interpreted as false.

min_tx_buffer_length

uint32

Minimum requested TX buffer length, in bytes.

If not set, interpreted as zero.

min_rx_buffer_length

uint32

Minimum requested RX buffer length, in bytes.

If not set, interpreted as zero.

BasePortConfig

Defined in fuchsia.net.tun/tun.fidl

Logical device port configuration.

Ordinal	Field	Type	Description
1	`id`	`fuchsia.hardware.network/port_id`	Port identifier. Required.
2	`mtu`	`uint32`	Device MTU (maximum transmit unit). Valid iff less than or equal to MAX_MTU. If not set, interpreted as MAX_MTU.
3	`rx_types`	`vector<fuchsia.hardware.network/FrameType>[4]`	Supported Rx frame types for port. Valid iff non-empty. Required.
4	`tx_types`	`vector<fuchsia.hardware.network/FrameTypeSupport>[4]`	Supported Tx frame types on port. Valid iff non-empty. Required.

DeviceConfig

Defined in fuchsia.net.tun/tun.fidl

Ordinal Field Type Description

Ordinal	Field	Type	Description
1	`base`	`BaseDeviceConfig`	Base device configuration. It not set, interpreted as an empty table.
2	`blocking`	`bool`	If `true`, fuchsia.net.tun/Device.WriteFrame and fuchsia.net.tun/Device.ReadFrame blocks returning until the corresponding buffers are available to complete the call. It not set, interpreted as `false`.

base

BaseDeviceConfig

Base device configuration.

It not set, interpreted as an empty table.

blocking

bool

If true, fuchsia.net.tun/Device.WriteFrame and fuchsia.net.tun/Device.ReadFrame blocks returning until the corresponding buffers are available to complete the call.

It not set, interpreted as false.

DevicePairConfig

Defined in fuchsia.net.tun/tun.fidl

Ordinal Field Type Description

Ordinal	Field	Type	Description
1	`base`	`BaseDeviceConfig`	Base device configuration. It not set, interpreted as an empty table.
2	`fallible_transmit_left`	`bool`	If `true`, transmit buffers on the left end are dropped if no receive buffers are available on the right end to receive it. Otherwise, transmit buffers wait until a receive buffer is available to copy them to. It not set, interpreted as `false`.
3	`fallible_transmit_right`	`bool`	Like `fallible_transmit_left` but allows writes to the right end to be fallible. It not set, interpreted as `false`.

base

BaseDeviceConfig

Base device configuration.

It not set, interpreted as an empty table.

fallible_transmit_left

bool

If true, transmit buffers on the left end are dropped if no receive buffers are available on the right end to receive it. Otherwise, transmit buffers wait until a receive buffer is available to copy them to.

It not set, interpreted as false.

fallible_transmit_right

bool

Like fallible_transmit_left but allows writes to the right end to be fallible.

It not set, interpreted as false.

DevicePairPortConfig

Defined in fuchsia.net.tun/tun.fidl

Ordinal Field Type Description

Ordinal	Field	Type	Description
1	`base`	`BasePortConfig`	Base port configuration. Required.
2	`mac_left`	`fuchsia.net/MacAddress`	MAC address to report. If set, left port provides a fuchsia.hardware.network/MacAddressing implementation through fuchsia.hardware.network/Port.GetMac.
3	`mac_right`	`fuchsia.net/MacAddress`	MAC address to report. If set, right port provides a fuchsia.hardware.network/MacAddressing implementation through fuchsia.hardware.network/Port.GetMac.

base

BasePortConfig

Base port configuration.

Required.

mac_left

fuchsia.net/MacAddress

MAC address to report.

If set, left port provides a fuchsia.hardware.network/MacAddressing implementation through fuchsia.hardware.network/Port.GetMac.

mac_right

fuchsia.net/MacAddress

MAC address to report.

If set, right port provides a fuchsia.hardware.network/MacAddressing implementation through fuchsia.hardware.network/Port.GetMac.

DevicePortConfig

Defined in fuchsia.net.tun/tun.fidl

Ordinal Field Type Description

Ordinal	Field	Type	Description
1	`base`	`BasePortConfig`	Base port configuration. Required.
2	`online`	`bool`	Start port with link online. If not set, interpreted as `false`.
3	`mac`	`fuchsia.net/MacAddress`	MAC address to report. If set, the port provides a fuchsia.hardware.network/MacAddressing implementation / through fuchsia.hardware.network/Port.GetMac.

base

BasePortConfig

Base port configuration.

Required.

online

bool

Start port with link online.

If not set, interpreted as false.

mac

fuchsia.net/MacAddress

MAC address to report.

If set, the port provides a fuchsia.hardware.network/MacAddressing implementation / through fuchsia.hardware.network/Port.GetMac.

Frame

Defined in fuchsia.net.tun/tun.fidl

A frame written to or read from a fuchsia.net.tun/Device.

Required fields must always be provided to fuchsia.net.tun/Port.WriteFrame and are always present when returned by fuchsia.net.tun/Port.ReadFrame.

Ordinal	Field	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. Valid iff non-empty. Required.
3	`meta`	`FrameMetadata`	Extra frame metadata. This is an opaque holder for extra information that is associated with Network Device data frames. If not set, interpreted as empty.
4	`port`	`fuchsia.hardware.network/port_id`	Frame's destination or source port identifier. Required.

InternalState

Defined in fuchsia.net.tun/tun.fidl

Internal device state.

Ordinal Field Type Description

Ordinal	Field	Type	Description
1	`mac`	`MacState`	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 fuchsia.net.tun/InternalState structure. Set iff `mac` is provided in the DevicePortConfig or DevicePairPortConfig structures upon creation of the port.
2	`has_session`	`bool`	Whether there is a session currently opened and running with the `Port`. Required.

mac

MacState

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 fuchsia.net.tun/InternalState structure.

Set iff mac is provided in the DevicePortConfig or DevicePairPortConfig structures upon creation of the port.

has_session

bool

Whether there is a session currently opened and running with the Port.

Required.

MacState

Defined in fuchsia.net.tun/tun.fidl

Ordinal Field Type Description

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

mode

fuchsia.hardware.network/MacFilterMode

The currently configured MAC Address filtering mode.

Required.

multicast_filters

vector<fuchsia.net/MacAddress>[64]

The full list of configured multicast address filtering.

Required.

UNIONS

DevicePair_AddPort_Result strict

Defined in fuchsia.net.tun/tun.fidl

Ordinal
Variant	Type	Description
1	`response`	`DevicePair_AddPort_Response`
2	`err`	`zx/status`

DevicePair_RemovePort_Result strict

Defined in fuchsia.net.tun/tun.fidl

Ordinal
Variant	Type	Description
1	`response`	`DevicePair_RemovePort_Response`
2	`err`	`zx/status`

Device_ReadFrame_Result strict

Defined in fuchsia.net.tun/tun.fidl

Ordinal
Variant	Type	Description
1	`response`	`Device_ReadFrame_Response`
2	`err`	`zx/status`

Device_WriteFrame_Result strict

Defined in fuchsia.net.tun/tun.fidl

Ordinal
Variant	Type	Description
1	`response`	`Device_WriteFrame_Response`
2	`err`	`zx/status`

BITS

Signals strict

Type: uint32

Defined in fuchsia.net.tun/tun.fidl

Signals set in the eventpair returned by fuchsia.net.tun/Device.GetSignals.

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

CONSTANTS

Name	Value	Type	Description
MAX_MTU	`16384`	`uint32`	Maximum supported MTU.
MAX_MULTICAST_FILTERS	`64`	`uint32`	Maximum number of multicast filters that a device holds in `MacState`.
MAX_PENDING_OPERATIONS	`32`	`uint32`	Maximum number of pending fuchsia.net.tun/Device.WriteFrame or fuchsia.net.tun/Device.ReadFrame that are allowed.