fuchsia.hardware.network.driver

一般網路裝置介面。

本文中的定義提供 API 介面，可透過 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 將可用的 rx 緩衝區空間推送至 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 會將傳輸作業標示為完成，並將緩衝區的 ID 參照至 NetworkDeviceIfc.CompleteTx。
新增：HEAD

通訊協定

MacAddr

定義於 fuchsia.hardware.network.driver/network-mac.fidl

GetAddress

取得這部裝置的 MAC 位址。

要求

<EMPTY>

回應

名稱類型
mac fuchsia.net/MacAddress

GetFeatures

取得這部裝置的功能。

要求

<EMPTY>

回應

名稱類型
features Features

SetMode

設定這部裝置的運作模式。

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 即可重複使用。

通訊埠 ID 不必在例項化或重新啟動時保持穩定。只要不超過 MAX_PORTS，就不必按照特定順序分配通訊埠 ID。

  • 要求 id 個新的通訊埠 ID。
  • 要求 port 處理網路通訊埠實作。

要求

名稱類型
id fuchsia.hardware.network/BasePortId
port client_end:NetworkPort

回應

名稱類型
status zx/Result

CompleteRx

通知介面有傳入的 rx 資料，包含在 RxBuffer 中。

呼叫端應嘗試在單一呼叫中批次處理盡可能多的緩衝區。單一呼叫中的緩衝區數量必須限制在 DeviceInfo.rx_depth，由傳回緩衝區的 NetworkDeviceImpl 回報。

長度為零的緩衝區會視為「未完成」。系統不會向任何工作階段回報這些資料，且包含這些資料的緩衝區空間可能會重複使用。裝置應在停止時，將任何未完成的緩衝區空間傳回為未完成。請參閱 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 連接埠 ID。
  • 要求new_status新通訊埠的狀態。

要求

名稱類型
id fuchsia.hardware.network/BasePortId
new_status fuchsia.hardware.network/PortStatus

RemovePort

使用 id 破壞港口。

注意：在呼叫 NetworkPort.Removed 之前，不得釋出與通訊埠相關聯的資源。

  • 要求 id 移除通訊埠 ID。

要求

名稱類型
id fuchsia.hardware.network/BasePortId

RequestRxSpace

通知網路裝置緩衝區資源不足。

這個通訊協定的伺服器需要將更多 RX 緩衝區排入實作佇列。網路裝置 impl 可以要求多個緩衝區，但這只是提示，伺服器會盡可能滿足要求。

這是盡力而為的方法，如果網路裝置也用盡 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 為止。

  • 要求 id ID，用於參照這個 VMO。
  • 要求 vmo VMO，用於儲存影格資料。
  • s 回應 VMO 註冊狀態。ZX_OK 表示 VMO 準備成功。任何其他狀態值都表示實作特定錯誤，並導致擁有 VMO 的用戶端工作階段關閉。

要求

名稱類型
id fuchsia.hardware.network/VmoId
vmo handle<vmo>

回應

名稱類型
s zx/Result

QueueRxSpace

將網路裝置上的 rx 緩衝區空間清單排入佇列。

驅動程式會取得緩衝區的擁有權，且必須使用 NetworkDeviceIfc.CompleteRx 完成交易 (網路資料送達後)。

提供給裝置的未完成 rx 緩衝區總數，一律不會超過回報的 DeviceInfo.rx_depth 值。這也表示，在單次呼叫 QueueRxSpace 時，最多只會通知 rx_depth 個緩衝區。

裝置處於停止狀態時排入佇列的緩衝區，必須以零長度傳回。

  • 要求 buffers rx 空間緩衝區在網路資料抵達時填入資料。

要求

名稱類型
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。

要求

名稱類型
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

這個緩衝區的目的地或來源通訊埠 ID。

 無預設值
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

已填滿這個影格的接收緩衝區空間。

至少須有一個部分。

 無預設值
full_csums_verified uint16

裝置驗證的完整核對和數量減一。

只有在 meta.flags 包含 RxFlags::FULL_CHECKSUMS_VERIFIED 時，這個值才有意義。

 無預設值

RxBufferPart

定義於 fuchsia.hardware.network.driver/network-device.fidl

RxBuffer 的單一連續部分，由 RxSpaceBuffer 建立。

欄位類型說明預設
id BufferId

RxSpaceBuffer 中通知的緩衝區 ID，該緩衝區是這個 RxBuffer 的來源。

 無預設值
offset uint32

從 RxSpaceBuffer 開頭到傳入資料開頭的偏移量 (以位元組為單位)。

這是原始空間定義區域內的相對偏移，而非空間 VMO 中的絕對偏移。

 無預設值
length uint32

寫入 id 參照的 RxSpaceBuffer 的總長度 (以位元組為單位)，不含任何 offset 位元組。

 無預設值

RxSpaceBuffer

定義於 fuchsia.hardware.network.driver/network-device.fidl

已分配空間的緩衝區，用於接收影格。RxSpaceBuffer 必須一律以 RxBuffer 中的 RxBufferPart 形式傳回。

欄位類型說明預設
id BufferId

緩衝區的專屬 ID。

 無預設值
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。更實際地說，這是緩衝區在裝置介面處理前，在裝置 impl 佇列中等待的平均時間上限。

驅動程式庫程式導入人員指南：

  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

緩衝區的專屬 ID。

 無預設值
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

TxBuffer 中通知的緩衝區 ID，該緩衝區產生了這個 TxResult。

 無預設值
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 緩衝區。

如果實作保留的 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

緩衝區總長度上限。如設為零，則無上限。

不支援分散收集 DMA 的裝置，可將這個值設為小於頁面大小的值，以確保相容性。必填。
buffer_alignment uint32

緩衝區相對於 VMO 起點的對齊要求。

必須大於 0。 必填。
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

這部裝置支援的篩選作業模式。

可能 SupportedMacFilterMode 值的位元欄位，可傳遞至 MacAddr.SetMode。

UNIONS

NetworkDeviceIfc_UpdateRxBufferParams_Result strict

定義於 fuchsia.hardware.network.driver/network-device.fidl

序數Variant類型說明
response NetworkDeviceIfc_UpdateRxBufferParams_Response
err zx/Status

RxBufferManagement 彈性

定義於 fuchsia.hardware.network.driver/network-device.fidl

Rx 緩衝區管理參數。

序數Variant類型說明
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

緩衝區 ID。

在介面和實作之間交換時，系統會透過這些緩衝區識別 Rx 空間緩衝區和 tx 緩衝區。

服務

服務

定義於 fuchsia.hardware.network.driver/network-device.fidl

名稱類型傳輸
network_device_impl fuchsia.hardware.network.driver/NetworkDeviceImpl 駕駛