PROTOCOLS
Control
Defined in fuchsia.net.tun/tun.fidl
Control interface.
Control
allows creating an arbitrary number of Device
s and DevicePair
s.
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>
|
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.
ConnectProtocols
Connects to the requested protocols for this Device
.
Request
Name | Type |
---|---|
protos |
Protocols
|
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
|
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
|
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 |
---|
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
|
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
|
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
|
STRUCTS
Device_ReadFrame_Response
Defined in fuchsia.net.tun/tun.fidl
Name | Type | Description | Default |
---|---|---|---|
frame |
Frame
|
No default |
Device_WriteFrame_Response
Defined in fuchsia.net.tun/tun.fidl
Name | Type | Description | 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. |
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 |
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 |
5 | min_tx_buffer_length |
uint32
|
Minimum requested TX buffer length, in bytes. Defaults to zero. |
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 |
3 | blocking |
bool
|
If |
4 | mac |
fuchsia.net/MacAddress
|
MAC address to report. If provided, device will support the
fuchsia.hardware.network/MacAddressing protocol through |
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 |
3 | fallible_transmit_right |
bool
|
Like |
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 |
5 | mac_right |
fuchsia.net/MacAddress
|
Same as |
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. |
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. |
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 |
2 | has_session |
bool
|
|
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. |
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. |
UNIONS
Device_ReadFrame_Result
Defined in fuchsia.net.tun/tun.fidl
Name | Type | Description |
---|---|---|
response |
Device_ReadFrame_Response
|
|
err |
zx/status
|
Device_WriteFrame_Result
Defined in fuchsia.net.tun/tun.fidl
Name | Type | Description |
---|---|---|
response |
Device_WriteFrame_Response
|
|
err |
zx/status
|
BITS
Signals
Type: uint32
Defined in fuchsia.net.tun/tun.fidl
Signals set in the eventpair
returned by Device.GetSignals.
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_MTU |
16384
|
uint32 |
Maximum supported MTU. |
MAX_MULTICAST_FILTERS |
64
|
uint32 |
Maximum number of multicast filters that a device will hold in |
MAX_PENDING_OPERATIONS |
32
|
uint32 |
Maximum number of pending Device.WriteFrame or Device.ReadFrame that are allowed. |