fuchsia.hardware.network.driver

通用网络设备接口。

此处的定义提供了 API Surface，用于通过 FIDL 协议 fuchsia.hardware.network/Device 将硬件设备作为网络设备接口向系统公开。网络设备接口是数据平面协定，允许网络栈在物理或虚拟网络上发送和接收帧。设备通过实现 NetworkDeviceImpl 协议来公开此功能，从而允许中间件实现绑定到该功能并向应用提供 FIDL 协议。

API 协定基于三个关键概念：

  • 帧类型
  • 接收和传输缓冲区
  • 内存布局

帧类型是向应用公开的已定义协定，用于传达 tx 或 rx 缓冲区中包含的数据类型。支持的帧类型在 fuchsia.hardware.network/FrameType 中定义。初始化后，中间件实现将通过 GetInfo 调用从设备提取支持的帧类型。

接收和传输缓冲区是流向不同方向的缓冲区：接收缓冲区是从网络接收并流向应用层的数据。传输缓冲区则沿相反方向传输：它源自应用层，并进入网络。设备实现从 NetworkDeviceIfc 接收缓冲区，该接口由中间件实现提供。

接收缓冲区通过 NetworkDeviceImpl.QueueRxSpace 方法从 NetworkDeviceIfc 流入 NetworkDeviceImpl，该方法可用于访问接收缓冲区。下图说明了该机制：

 ++++++++++++++++++++                      +++++++++++++++++++++
 |       (1)        |  => RxSpaceBuffer => |       (2)         |
 | NetworkDeviceIfc |                      | NetworkDeviceImpl |
 |       (4)        |  <=    RxBuffer   <= |       (3)         |  <= Network data
 ++++++++++++++++++++                      +++++++++++++++++++++
  • (1) NetworkDeviceIfc 通过 NetworkDeviceImpl.QueueRxSpace 将可用的接收缓冲区空间推送到 NetworkDeviceImpl。
  • (2) NetworkDeviceImpl 会保留可用空间缓冲区，直到网络数据传入。
  • (3) NetworkDeviceImpl 从网络接收数据，将其存储在其中一个可用的 RxSpaceBuffers 中，使其成为 NetworkDeviceImpl.RxBuffer。
  • (4) NetworkDeviceImpl 通过 NetworkDeviceIfc.CompleteRx 将已填充的 RxBuffer 发送到 NetworkDeviceIfc，后者又将该数据发送到应用。

传输缓冲区通过 NetworkDeviceImpl.QueueTx 方法从 NetworkDeviceIfc 流入 NetworkDeviceImpl，并作为 TxResult 返回到 NetworkDeviceIfc。下图说明了该机制：

 ++++++++++++++++++++                 +++++++++++++++++++++
 |       (1)        |  => TxBuffer => |       (2)         |
 | NetworkDeviceIfc |                 | NetworkDeviceImpl |
 |       (4)        |  <= TxResult <= |       (3)         |  => Network data
 ++++++++++++++++++++                 +++++++++++++++++++++
  • (1) NetworkDeviceIfc 从应用接收一个传输缓冲区，其中填充了要传送到网络的数据。
  • (2) NetworkDeviceIfc 通过 NetworkDeviceImpl.QueueTx 调用将缓冲区推送到 NetworkDeviceImpl。
  • (3) NetworkDeviceImpl 将缓冲区中包含的数据发送到网络中。
  • (4) 数据成功传输后，NetworkDeviceImpl 会将传输标记为完成，并将缓冲区的标识符引用到 NetworkDeviceIfc.CompleteTx。
Added: HEAD

协议

MacAddr

在 fuchsia.hardware.network.driver/network-mac.fidl 中定义

GetAddress

获取此设备的 MAC 地址。

请求

<EMPTY>

响应

名称类型
mac fuchsia.net/MacAddress

GetFeatures

获取此设备的功能。

请求

<EMPTY>

响应

名称类型
features Features

SetMode

设置此设备的运行模式。

mode 是 Mode 中的一个变体，保证是此设备报告的功能中报告的模式之一。只有当 mode 为 MULTICAST_FILTER 时，才会提供 multicast_macs（尽管它仍可能为空）。multicast_macs 始终保证最多包含 multicast_filter_count 个条目。

请求

名称类型
mode fuchsia.hardware.network/MacFilterMode
multicast_macs vector<fuchsia.net/MacAddress>:64

响应

<EMPTY>

NetworkDeviceIfc

在 fuchsia.hardware.network.driver/network-device.fidl 中定义

AddPort

使用 id 实例化新端口。

id 当前不得被任何其他端口使用。一旦提供的端口被 NetworkPort.Removed 销毁，id 就可以重复使用。

端口标识符无需在实例化或重新启动期间保持稳定。只要不超过 MAX_PORTS，就不需要按任何特定顺序分配端口标识符。

  • 请求 id 个新端口标识符。
  • 请求 port 句柄以实现网络端口。

请求

名称类型
id fuchsia.hardware.network/BasePortId
port client_end:NetworkPort

响应

名称类型
status zx/Result

CompleteRx

向接口通知 RxBuffer 中包含的传入 rx 数据。

调用方应尝试在单次调用中批量处理尽可能多的缓冲区。单次调用中的缓冲区数量必须限制为返回缓冲区的 NetworkDeviceImpl 报告的 DeviceInfo.rx_depth。

长度为零的缓冲区会被视为“未填充”。它们不会报告给任何会话，并且包含它们的缓冲区空间可能会被重复使用。设备应在停止时将所有未完成的缓冲区空间作为未完成空间返回。请参阅 NetworkDeviceImpl.Stop。

通过调用 CompleteRx，调用方会放弃对所有标记为完成的缓冲区的所有权。

  • 请求包含传入数据的 rx 缓冲区。

请求

名称类型
rx vector<RxBuffer>:744

CompleteTx

向接口通知完整的传输缓冲区。

调用方应尝试在单次调用中批量处理尽可能多的缓冲区。

单次调用中的缓冲区数量必须限制为返回缓冲区的 NetworkDeviceImpl 报告的 DeviceInfo.tx_depth。

通过调用 CompleteTx，调用方会放弃所返回的所有缓冲区的所有权。

  • 请求 tx 传输结果。

请求

名称类型
tx vector<TxResult>:8188

DelegateRxLease

将接收唤醒租约转移到应用。

如果设备允许应用在从网络流量唤醒后完全处理帧，则可以使用此方法作为“租约接力”策略。支持唤醒处理的应用会保留租用，直到 rx 流量完全处理完毕。

设备必须跟踪通过 NetworkDeviceIfc.CompleteRx 发送的 rx 帧数，并使用最新发出的帧数作为 fuchsia.hardware.network/DelegatedRxLease.hold_until_frame，以保证处理。成功提供给 CompleteRx 的每个帧都应增加 rx 帧计数。请注意，帧编号从 1 开始，如需了解详情，请参阅 hold_until_frame 文档。

请注意，这是一种单向方法，流控制通过常规 rx 空间 -> rx 完成流强制执行。

请求

名称类型
delegated fuchsia.hardware.network/DelegatedRxLease

PortStatusChanged

向接口发送通知，告知具有 id 的端口的状态变化。

必须始终通过 StatusChanged 通知端口状态变化。该接口不会通过 NetworkPort.GetStatus 轮询端口以获取状态。

  • 请求 id 端口标识符。
  • 请求 new_status 个新端口的状态。

请求

名称类型
id fuchsia.hardware.network/BasePortId
new_status fuchsia.hardware.network/PortStatus

RemovePort

使用 id 销毁端口。

注意：在调用 NetworkPort.Removed 之前，不得释放与端口关联的资源。

  • 请求 id 移除了端口标识符。

请求

名称类型
id fuchsia.hardware.network/BasePortId

RequestRxSpace

向网络设备通知缓冲区耗尽。

此协议的服务器需要将更多 RX 缓冲区加入实现队列。网络设备实现可以请求一定数量的缓冲区，但这只是一个提示，服务器会尽力满足请求。

这是一种尽力而为的方法，如果网络设备也用尽了 Rx 空间缓冲区，那么我们就无能为力了。

请注意，这是一个单向异步调用，仅用作平台驱动程序的信号方法，队列操作可能不会与中断处理内嵌发生。数据包可能会在此时间范围内被丢弃。当达到特定阈值时，NetworkDeviceImpl 可以发出此信号，而不是等待缓冲区空间实际为空。

请求

名称类型
requested uint64

UpdateRxBufferParams

为 NetworkDeviceIfc 提供一组用于缓冲区管理的参数。

  • 如果给定参数无效，则返回 ZX_ERR_INVALID_VALUE。

请求

名称类型
param RxBufferManagement

响应

名称类型
payload NetworkDeviceIfc_UpdateRxBufferParams_Result

NetworkDeviceImpl

在 fuchsia.hardware.network.driver/network-device.fidl 中定义

GetInfo

获取设备的相关信息。

设备信息在设备的生命周期内不得更改。

  • 响应 info 设备信息。

请求

<EMPTY>

响应

名称类型
info DeviceImplInfo

Init

初始化网络设备。

在设备的生命周期内，Init 仅调用一次，以将 iface 注册为网络设备实现的回调目标。

初始化后，设备应处于“已停止”状态，一旦需要打开数据路径，系统就会调用 Start 方法。

  • 请求设备接口的 iface 句柄。
  • 响应 s 初始化状态。ZX_OK 以外的值会导致设备解除绑定。

请求

名称类型
iface client_end:NetworkDeviceIfc

响应

名称类型
s zx/Result

PrepareVmo

通知设备正在使用新的 VMO 来存储帧数据。

实现者必须存储 id 引用的 VMO 句柄，直到使用相同的 id 调用 NetworkDeviceImpl.ReleaseVmo。

  • 用于引用此 VMO 的请求 id 标识符。
  • 请求 vmo VMO，其中将存储帧数据。
  • 响应 s VMO 注册状态。ZX_OK 表示 VMO 准备成功。任何其他状态值都表示特定于实现的错误，并会导致拥有 VMO 的客户端会话关闭。

请求

名称类型
id fuchsia.hardware.network/VmoId
vmo handle<vmo>

响应

名称类型
s zx/Result

QueueRxSpace

在网络设备上将接收缓冲区空间列表加入队列。

驱动程序会获取缓冲区的所有权，并且必须使用 NetworkDeviceIfc.CompleteRx 完成事务（在网络数据到达后）。

提供给设备的未完成 rx 缓冲区总数绝不会超过报告的 DeviceInfo.rx_depth 值。这也意味着，在对 QueueRxSpace 的单次调用中，一次最多会通知 rx_depth 个缓冲区。

当设备处于停止状态时，加入队列的缓冲区必须返回零长度。

  • 请求 buffers 个接收空间缓冲区，以便在网络数据到达时填充这些缓冲区。

请求

名称类型
buffers vector<RxSpaceBuffer>:2047

QueueTx

将缓冲区列表加入队列，以便在网络设备上传输。

驱动程序会获取缓冲区的所有权，并且在处理完 buffers 中的每个缓冲区后，必须使用 NetworkDeviceIfc.CompleteTx 操作完成 tx 事务。

提供给设备的未完成 tx 缓冲区总数绝不会超过报告的 DeviceInfo.tx_depth 值。这也意味着，在对 QueueTx 的单次调用中，一次最多会通知 tx_depth 个缓冲区。

当设备处于停止状态时，必须返回排队的缓冲区，并显示相应的错误。如需了解具体的错误代码，请参阅 TxResult.status。

  • 请求 buffers 个 tx 缓冲区加入队列以进行发送。

请求

名称类型
buffers vector<TxBuffer>:454

ReleaseVmo

设备可能会处置对 id 引用的 VMO 的所有引用。

系统不会再发送带有此 id 的缓冲区。

只有在实现不包含引用该 id 的缓冲区时，系统才会调用 ReleaseVmo。

  • 请求 id VMO 标识符。

请求

名称类型
id fuchsia.hardware.network/VmoId

响应

<EMPTY>

开始

启动设备的数据路径。

start 会向设备实现发出信号，指示其应启动数据路径并准备好接收 tx 帧，并且 iface 将开始接受 rx 帧。

只有在 Start 成功返回后，设备才会被视为已启动。 在此之前，该协定保证不会对设备进行其他数据路径调用（QueueTx、RxAvailable、Stop 或对 Start 的第二次调用），因此实现者可以安全地假设或断言此协定得到遵守。

  • 响应 s 启动状态。ZX_OK 表示成功启动。 ZX_ERR_ALREADY_BOUND 表示设备已成功启动。任何其他状态值都表示实现特定错误。

请求

<EMPTY>

响应

名称类型
s zx/Result

停止

停止网络设备。

设备实现必须在收到此调用后返回所有未完成的 Tx 和 Rx 缓冲区。在停止状态下收到的任何新缓冲区都必须返回适当的错误 (tx) 或未完成 (rx)。如需了解详情，请参阅 NetworkDeviceIfc.CompleteTx 和 NetworkDeviceIfc.CompleteRx。

设备实现可在观察到停止后执行任何节能措施。

请求

<EMPTY>

响应

<EMPTY>

NetworkPort

在 fuchsia.hardware.network.driver/network-device.fidl 中定义

GetInfo

获取端口的相关信息。

端口信息在端口的生命周期内不得更改。

  • 响应 info 端口信息。

请求

<EMPTY>

响应

名称类型
info fuchsia.hardware.network/PortBaseInfo

GetMac

获取端口的 MAC 寻址层的接口。

不支持 MAC 地址寻址的端口必须返回空接口。

  • 响应 mac_ifc MAC 地址处理。

请求

<EMPTY>

响应

名称类型
mac_ifc client_end:MacAddr?

GetPowerDependencyToken

获取此端口电源元素的 Power Broker 依赖项令牌。

该令牌公开了两个级别：0（关闭）和 1（开启）。每当需要端口的数据路径时，客户端都会租用级别 1，并根据需要保留租约。驱动程序可以自由地对已租用但空闲的端口进行内部电源管理，只要上层看不到该端口即可。

该令牌在端口的生命周期内是固定的。

  • 如果此端口不参与电源管理，则响应 token 不存在。

请求

<EMPTY>

响应

名称类型
token fuchsia.power.broker/DependencyToken

GetStatus

获取端口的运行状态。

必须通过 NetworkDeviceIfc.StatusChanged 报告操作状态的变化

  • 响应 status 端口运行状态的快照。

请求

<EMPTY>

响应

名称类型
status fuchsia.hardware.network/PortStatus

已移除

通知此端口已从接口中移除。

只有在收到 Removed 调用时，才能释放与端口关联的资源。请注意，只有在 AddPort 返回并指示成功时，系统才会调用 Removed。如果 AddPort 失败，则不会调用此方法，而是检查 AddPort 的返回状态。

请求

<EMPTY>

SetActive

通知端口有会话对其感兴趣。

活跃端口具有与其关联的会话。实现可能会在停用的端口上采用节能或其他策略。采用此类策略的实现：

  • 不应报告非活动端口的入站帧；
  • 必须针对发往非活跃端口的出站帧返回错误。

所有端口在创建时均处于非活跃状态。

  • 如果端口有会话连接到它，则请求 active true，否则请求 false。

请求

名称类型
active bool

STRUCTS

BufferMetadata

在 fuchsia.hardware.network.driver/network-device.fidl 中定义

与 TxBuffer 或 RxBuffer 关联的元数据。

字段类型说明默认
port fuchsia.hardware.network/BasePortId

此缓冲区的目标或源端口标识符。

 无默认应用
flags uint32

帧 tx 或 rx 标志，如 fuchsia.hardware.network/RxFlags、fuchsia.hardware.network/TxFlags 和 fuchsia.hardware.network/TxReturnFlags 中所定义。

 无默认应用
frame_type fuchsia.hardware.network/FrameType

此缓冲区中包含的帧类型，如 fuchsia.hardware.network/FrameType 中所定义。

 无默认应用

BufferRegion

在 fuchsia.hardware.network.driver/network-device.fidl 中定义

VMO 中的连续内存区域。

请注意，BufferRegion 仅在其引用的 VMO 方面是连续的，不一定会转换为连续的物理内存。

字段类型说明默认
vmo fuchsia.hardware.network/VmoId

支持此区域的 VMO。

 无默认应用
offset uint64

VMO 中数据块的偏移量（以字节为单位）。

 无默认应用
length uint64

VMO 中数据块的长度（以字节为单位）。

 无默认应用

NetworkDeviceIfc_UpdateRxBufferParams_Response

在 fuchsia.hardware.network.driver/network-device.fidl 中定义

<EMPTY>

RxBuffer

在 fuchsia.hardware.network.driver/network-device.fidl 中定义

包含设备接收的单个帧的缓冲区。

字段类型说明默认
meta BufferMetadata

与缓冲区关联的元数据。

 无默认应用
data vector<RxBufferPart>:4

包含此帧的已填充 rx 缓冲区空间。

必须至少有一个部分。

 无默认应用
full_csums_verified uint16

设备验证的完整校验和数量减一。

仅当 meta.flags 包含 RxFlags::FULL_CHECKSUMS_VERIFIED 时才有意义。

 无默认应用

RxBufferPart

在 fuchsia.hardware.network.driver/network-device.fidl 中定义

RxBuffer 的单个连续部分，由 RxSpaceBuffer 创建。

字段类型说明默认
id BufferId

在产生此 RxBuffer 的 RxSpaceBuffer 中通知的缓冲区标识符。

 无默认应用
offset uint32

从 RxSpaceBuffer 的开头到入站数据开始处的偏移量（以字节为单位）。

这是源空间定义的区域内的相对偏移量，而不是空间 VMO 中的绝对偏移量。

 无默认应用
length uint32

id 引用的 RxSpaceBuffer 中写入的总长度（以字节为单位），不包括任何 offset 字节。

 无默认应用

RxSpaceBuffer

在 fuchsia.hardware.network.driver/network-device.fidl 中定义

具有已分配空间的缓冲区，用于接收帧。RxSpaceBuffer 必须始终作为 RxBuffer 中的 RxBufferPart 返回。

字段类型说明默认
id BufferId

唯一缓冲区标识符。

 无默认应用
region BufferRegion

缓冲区空间所在的 VMO 区域。

 无默认应用

简单

在 fuchsia.hardware.network.driver/network-device.fidl 中定义

字段类型说明默认
alpha float64

此值用于计算到达率： Rate_n = alpha * Sample_n + (1 - alpha) * Rate_(n-1) 此值越大，对最新样本越敏感。

必须在 (0, 1] 范围内。如果为零，则默认为服务器分配的值。

 无默认应用
delay_budget zx/Duration

驱动程序中的等待时间预算。

这相当于利特尔法则中的 W。更实际地说，这是缓冲区在设备实现队列中等待设备接口处理的平均时间的上限。

面向驱动程序实现者的指南：

  1. 如果您的驱动程序使用中断合并超时，则此 W 应仅为该值或略大一些，以考虑处理时间。
  2. 如果您的驱动程序不使用调节功能，则可以调整此值：首先，使用（比特率、MTU、Rx 深度）来推导最大压力下的 W。作为参考，(1Gbps, 1500, 256) 会导致 W 为 3.0 毫秒（256 / (10**9 / 8 / 1500) 秒）。超过该值没有任何意义，您可以减小该值并监控丢包情况。您可以将该值与常见的中断合并配置进行比较，以供参考。

如果为零，则默认为服务器分配的值。

 无默认应用
intercept uint16

设备持有的 Rx 缓冲区数量，无论到达速率如何。

这是恒定偏移量（L = lambda * W + intercept 中的 intercept）。delay_budget 仅考虑因排队延迟而处于传输状态的缓冲区；它无法考虑设备因结构原因而停放的缓冲区，例如保持固定大小的硬件描述符环填充或让固件保留主机缓冲区。无论流量有多慢，这些缓冲区都不会返回到设备接口，因此必须单独考虑。

针对驱动程序实现者的指南：将此值设置为设备在不完成缓冲区的情况下可以容纳的缓冲区数量。如果设备在停放缓冲区时将该值设为零，则设备会一直处于饥饿状态，直到 min_rx_buffers 弥补了不足。

请注意，这与 fuchsia.hardware.network.driver/DeviceImplInfo.min_rx_buffers 不同，后者是应用于最终目标的下限。下限会使目标保持平缓，直到依赖于费率的项超过该下限，而 intercept 会使整条曲线向上移动。

 无默认应用
sample_interval zx/Duration

用于估算数据包到达速率的采样间隔。

确定到达率的采样和更新频率。

如果为零，则默认为服务器分配的值。

 无默认应用
variance_threshold float64

触发即时缓冲区请求时要考虑的方差倍数。

当当前数据包到达率超过平均到达率 variance_threshold 倍以上时，队列将立即请求额外的缓冲区。

必须为正值。如果为零，则默认为服务器分配的值。

 无默认应用

静态

在 fuchsia.hardware.network.driver/network-device.fidl 中定义

<EMPTY>

TxBuffer

在 fuchsia.hardware.network.driver/network-device.fidl 中定义

包含单个帧的传输缓冲区。

字段类型说明默认
id BufferId

唯一缓冲区标识符。

 无默认应用
data vector<BufferRegion>:4

保存帧数据的 VMO 区域。

 无默认应用
meta BufferMetadata

与此缓冲区关联的元数据。

 无默认应用
head_length uint16

此缓冲区所含数据中的标头字节长度。

始终为 0 或请求的 DeviceInfo.tx_head_length 值。头部字节始终位于缓冲区的开头。

 无默认应用
tail_length uint16

此缓冲区中包含的数据的尾部字节长度。

始终为 0 或请求的 DeviceInfo.tx_tail_length 值。尾部字节始终位于缓冲区的末尾。

 无默认应用
partial_csum_metadata TxPartialCsumMetadata

由堆栈发送的元数据，用于请求通用校验和分流。

仅当 meta.flags 包含 TxFlags::COMPUTE_GENERIC_CHECKSUM 时才有意义。

 无默认应用

TxPartialCsumMetadata

在 fuchsia.hardware.network.driver/network-device.fidl 中定义

部分校验和元数据。

字段类型说明默认
start uint16

从帧开头到设备必须开始计算校验和的位置的字节偏移量。

 无默认应用
offset uint16

从缓冲区中已校验和部分的开头到设备必须放置校验和结果的位置之间的偏移量（以字节为单位）。校验和字段本身包含在校验和中。

 无默认应用

TxResult

在 fuchsia.hardware.network.driver/network-device.fidl 中定义

tx 操作的结果，通过 NetworkDeviceIfc.CompleteTx 报告给 NetworkDeviceIfc。

字段类型说明默认
id BufferId

在发起此 TxResult 的 TxBuffer 中通知的缓冲区标识符。

 无默认应用
status zx/Result

要报告的结果状态。

错误结果会映射到 fuchsia.hardware.network/TxReturnFlags 中的等效结果。

  • 如果帧发送成功，则为 ZX_OK。
  • ZX_ERR_NOT_SUPPORTED（如果帧的任何标志不受支持）。
  • ZX_ERR_NO_RESOURCES（如果传输未能为其输出队列中的帧分配空间）。
  • 如果设备处于离线状态（或在收到帧已发送的确认之前离线）或已停止，则为 ZX_ERR_UNAVAILABLE。
  • ZX_ERR_INTERNAL 或任何其他未列出的错误都将报告为通用 fuchsia.hardware.network/TxReturnFlags.TX_RET_ERROR。
 无默认应用

TABLES

DeviceImplInfo

在 fuchsia.hardware.network.driver/network-device.fidl 中定义

静态设备信息。 DeviceImplInfo 在设备的整个生命周期内不得更改。

序数字段类型说明
device_features uint32

设备功能 必需。
tx_depth uint16

设备传出队列中 tx 帧的最大深度。 必填。
rx_depth uint16

设备传入队列中的 rx 帧数上限。 必填。
rx_threshold uint16

应向设备馈送新接收缓冲区的接收深度阈值。

当实现持有的 rx 缓冲区数量大于 rx_threshold 时，系统可能会跳过来自 NetworkDeviceIfc 的新缓冲区通知。提供大于 rx_depth 的值无效。 rx_threshold = rx_depth 在功能上等同于 rx_threshold = rx_depth - 1。

对于较小的 rx 完成事务大小，较大的值（接近 rx_depth）可能会导致严重的 CPU 抖动，而较小的值可能会导致实现缺少缓冲区。典型值选择为 rx_depth / 2。 必填。
max_buffer_parts uint8

设备接受的最大虚拟不连续缓冲区部分。

无法执行分散-收集操作的设备必须将 max_buffer_parts 设置为 1。

必须在 [1, MAX_BUFFER_PARTS] 范围内。 必需。
max_buffer_length uint32

缓冲区的最大总长度。可设置为 0，表示不设上限。

不支持分散-收集 DMA 的设备可以将此值设置为小于页面大小的值，以确保兼容性。 必填。
buffer_alignment uint32

缓冲区相对于 VMO 开头的对齐要求。

必须大于零。 必填。
min_rx_buffer_length uint32

确保正常运行所需的最小 rx 缓冲区长度（以字节为单位）。 必填。
min_tx_buffer_length uint32

确保正常运行所需的最小 tx 缓冲区长度（以字节为单位）。

此长度仅考虑缓冲区的主体，不应考虑 tx_head_length 或 tx_tail_length。 必填。
tx_head_length uint16

在 tx 缓冲区中作为标头字节请求的字节数。

如果设置为零，tx 缓冲区将永远不会包含标头空间。否则，tx 缓冲区将从标头空间的开头开始，并且系统会通知标头区域。 必填。
tx_tail_length uint16

在 tx 缓冲区上作为尾部字节请求的字节数。

如果设置为零，则 tx 缓冲区将永远不会包含尾部空间。否则，tx 缓冲区将在尾部空间末尾结束，并且系统会通知尾部区域。 必填。
min_rx_buffers uint16

要排队的 Rx 缓冲区数量下限。如果未设置，则假定 rx_threshold 为最小值。
rx_buffer_management RxBufferManagement

初始 Rx 缓冲区管理参数。 如果未设置，则假定使用 static 进行 Rx 缓冲区管理。

功能

在 fuchsia.hardware.network.driver/network-mac.fidl 中定义

MacAddr.GetFeatures 报告的设备功能。

序数字段类型说明
multicast_filter_count uint32

此设备上可用的多播过滤条目数上限。

如果不支持多播过滤，实现必须设置为 0。 值将始终饱和到 MAX_MAC_FILTER。 可选，如果不存在，则解读为零。
supported_modes SupportedMacFilterMode

此设备支持的过滤操作模式。

可传递给 MacAddr.SetMode 的可能 SupportedMacFilterMode 值的位字段。

UNIONS

NetworkDeviceIfc_UpdateRxBufferParams_Result strict

在 fuchsia.hardware.network.driver/network-device.fidl 中定义

序数变体类型说明
response NetworkDeviceIfc_UpdateRxBufferParams_Response
err zx/Status

RxBufferManagement flexible

在 fuchsia.hardware.network.driver/network-device.fidl 中定义

Rx 缓冲区管理参数。

序数变体类型说明
static Static

没有动态管理，所有内容都会排队。默认算法。
simple Simple

使用利特尔法则：队列大小是数据包到达速率与每个数据包在队列中花费的平均时间的乘积，再加上一个常数项，表示设备持有的缓冲区，无论到达速率如何 (L = lambda * W + intercept)。

BITS

SupportedMacFilterMode flexible

类型：uint32

在 fuchsia.hardware.network.driver/network-mac.fidl 中定义

支持的设备 MAC 过滤模式。

此类型的变体应与 fuchsia.hardware.network.MacFilterMode 匹配。

名称值说明
1

设备仅接受发送到其自身单播地址的单播帧，或属于多播地址过滤条件列表的多播帧。
2

设备接受发送到其自身单播地址的单播帧或任何多播帧。
4

设备接受所有帧。

常量

名称值类型说明
MAC_SIZE 6 uint64

IEEE 802 MAC 地址的长度（以字节为单位）。
MAX_BUFFER_PARTS 4 uint32

缓冲区可能具有的不相交部分的最大数量。
MAX_MAC_FILTER 64 uint64

设置为过滤的多播 MAC 地址的数量上限。
MAX_RX_BUFFERS 744 uint32

在不超过绑定强制执行的消息大小上限的情况下，可在单个 FIDL 消息中发送的 RxBuffer 结构体的数量上限。

在撰写本文时，FIDL 消息的大小上限为 65 KiB。在当前的 FIDL 传输格式中，RxBuffer 的大小为 88 字节，CompleteRx 请求的固定开销为 32 字节（FIDL 消息标头为 16 字节 + 向量为 16 字节），因此我们选择了最大 N，其中 32

  • N * 88 <= 65 KiB。
MAX_RX_SPACE_BUFFERS 2047 uint32

在遵守绑定强制执行的消息大小上限的前提下，单个 FIDL 消息中可发送的 RxSpaceBuffer 结构体的数量上限。

在撰写本文时，FIDL 消息的大小上限为 65 KiB。在当前的 FIDL 传输格式中，RxSpaceBuffer 的大小上限为 32 字节，QueueRxSpace 请求的固定开销为 32 字节（FIDL 消息标头为 16 字节 + 向量为 16 字节），因此我们选择了最大 N，其中 32 + N * 32 <= 65 KiB。
MAX_TX_BUFFERS 454 uint32

在不超过绑定强制执行的消息大小上限的情况下，可在单个 FIDL 消息中发送的 TxBuffer 结构体的数量上限。

在撰写本文时，FIDL 消息的大小上限为 65 KiB。在当前的 FIDL 传输格式中，TxBuffer 的大小为 144 字节，QueueTx 请求的固定开销为 32 字节（FIDL 消息标头为 16 字节 + 向量为 16 字节），因此我们选择了最大 N，其中 32 + N * 144 <= 65 KiB。
MAX_TX_RESULTS 8188 uint32

在单个 FIDL 消息中可发送的 TxResult 结构体的数量上限，同时保持在绑定强制执行的消息大小上限内。

在撰写本文时，FIDL 消息的大小上限为 65 KiB。在当前的 FIDL 传输格式中，每个 TxResult 的大小为 8 字节，CompleteTx 请求的固定开销为 32 字节（FIDL 消息标头为 16 字节 + 向量为 16 字节），因此我们选择了最大 N，其中 32 + N * 8 <= 65 KiB。

别名

名称值说明
BufferId uint32

缓冲区标识符。

在接口和实现之间交换时，Rx 空间缓冲区和 Tx 缓冲区由这些标识。

服务

服务

在 fuchsia.hardware.network.driver/network-device.fidl 中定义

名称类型传输
network_device_impl fuchsia.hardware.network.driver/NetworkDeviceImpl 驱动程序