Google is committed to advancing racial equity for Black communities. See how.

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

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

Request

NameType
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

NameType
config DevicePortConfig
port request<Port>

GetDevice

Connects to the underlying device endpoint.

  • request device device handle.

Request

NameType
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

NameType
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

NameType
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

NameType
frame Frame

Response

NameType
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

NameType
config DevicePairPortConfig

Response

NameType
result DevicePair_AddPort_Result

GetLeft

Connects to the underlying left device endpoint.

  • request device handle serve the left device endpoint on.

Request

NameType
device request<fuchsia.hardware.network/Device>

GetRight

Connects to the underlying right device endpoint.

  • request device handle serve the right device endpoint on.

Request

NameType
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

NameType
id fuchsia.hardware.network/port_id

Response

NameType
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

NameType
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

NameType
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

NameType
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

FieldTypeDescriptionDefault
frame Frame No default

Device_WriteFrame_Response

Defined in fuchsia.net.tun/tun.fidl

<EMPTY>

FrameMetadata

Defined in fuchsia.net.tun/tun.fidl

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

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

BasePortConfig

Defined in fuchsia.net.tun/tun.fidl

Logical device port configuration.

OrdinalFieldTypeDescription
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

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

DevicePairConfig

Defined in fuchsia.net.tun/tun.fidl

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

DevicePairPortConfig

Defined in fuchsia.net.tun/tun.fidl

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

DevicePortConfig

Defined in fuchsia.net.tun/tun.fidl

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

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.

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

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

MacState

Defined in fuchsia.net.tun/tun.fidl

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

UNIONS

DevicePair_AddPort_Result strict

Defined in fuchsia.net.tun/tun.fidl

Ordinal
VariantTypeDescription
1 response DevicePair_AddPort_Response
2 err zx/status

DevicePair_RemovePort_Result strict

Defined in fuchsia.net.tun/tun.fidl

Ordinal
VariantTypeDescription
1 response DevicePair_RemovePort_Response
2 err zx/status

Device_ReadFrame_Result strict

Defined in fuchsia.net.tun/tun.fidl

Ordinal
VariantTypeDescription
1 response Device_ReadFrame_Response
2 err zx/status

Device_WriteFrame_Result strict

Defined in fuchsia.net.tun/tun.fidl

Ordinal
VariantTypeDescription
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.

NameValueDescription
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

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