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

NameType
frame Frame

Response

NameType
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

NameType

Response

NameType
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

NameType

Response

NameType
signals handle<eventpair>

GetState

Gets a snapshot of the device's internal state.

Request

NameType

Response

NameType
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

NameType

Response

NameType
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

NameType
online bool

Response

NameType

ConnectProtocols

Connects to the requested protocols for this Device.

Request

NameType
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

NameType
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

NameType
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

NameType
config DevicePairConfig
device_pair request<DevicePair>

STRUCTS

Device_WriteFrame_Response

Defined in fuchsia.net.tun/tun.fidl

NameTypeDescriptionDefault

Device_ReadFrame_Response

Defined in fuchsia.net.tun/tun.fidl

NameTypeDescriptionDefault
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.

NameTypeDescriptionDefault
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.

OrdinalNameTypeDescription
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.

OrdinalNameTypeDescription
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.

OrdinalNameTypeDescription
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.

OrdinalNameTypeDescription
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.

OrdinalNameTypeDescription
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.

OrdinalNameTypeDescription
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.

OrdinalNameTypeDescription
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.

OrdinalNameTypeDescription
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

NameTypeDescription
response Device_WriteFrame_Response
err zx/status

Device_ReadFrame_Result

Defined in fuchsia.net.tun/tun.fidl

NameTypeDescription
response Device_ReadFrame_Response
err zx/status

BITS

Signals

Type: uint32

NameValueDescription
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

NameValueTypeDescription
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.