Netlink 協議規範（YAML 格式）¶

Netlink 協議規範是使用 YAML 編寫的 Netlink 協議的完整、機器可讀的描述。規範的目標是將 Netlink 解析與使用者空間邏輯分離，並最大程度地減少為每個新族、命令、屬性編寫的手寫 Netlink 程式碼量。Netlink 規範應該是完整的，並且不依賴於任何其他規範或 C 標頭檔案，使其易於在無法直接包含核心標頭檔案的語言中使用。

核心內部使用 YAML 規範來生成

C uAPI 標頭檔案

協議的文件作為 ReST 檔案 - 請參閱 Documentation/networking/netlink_spec/index.rst

輸入屬性驗證的策略表

操作表

YAML 規範可以在 Documentation/netlink/specs/ 下找到

本文件描述了模式的詳細資訊。有關實際的入門指南，請參閱使用 Netlink 協議規範。

所有規範都必須在 ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause) 許可下獲得許可，以便於在使用者空間程式碼中採用。

相容性級別¶

Netlink 規範有四個模式級別，從新系列使用的最簡單級別到涵蓋舊系列所有怪癖的最複雜級別。每個下一個級別都繼承了上一個級別的屬性，這意味著能夠解析更復雜的 genetlink 模式的使用者也與更簡單的模式相容。這些級別是

genetlink - 最精簡，應由所有新系列使用

genetlink-c - genetlink 的超集，具有額外的屬性，允許自定義定義和列舉型別和值的名稱；對於所有不直接與 C uAPI 標頭檔案互動的實現，此模式應等效於 genetlink

genetlink-legacy - 通用 Netlink 全域性模式，支援所有舊的 genetlink 系列、奇怪的屬性格式、二進位制結構等的怪癖。

netlink-raw - 通用模式，支援通用 Netlink 協議之前的協議，例如 NETLINK_ROUTE

模式的定義（在 jsonschema 中）可以在 Documentation/netlink/ 下找到。

模式結構¶

YAML 模式具有以下概念部分

全域性

定義

屬性

操作

多播組

模式中的大多數屬性接受（或者實際上需要）一個記錄已定義物件的 doc 子屬性。

以下部分描述了最新 genetlink 模式的屬性。有關如何從名稱屬性派生 C 名稱的資訊，請參閱 genetlink-c 的文件。

另請參閱 Documentation/core-api/netlink.rst，瞭解僅與核心空間相關而不屬於使用者空間 API 的 Netlink 規範屬性的資訊。

genetlink¶

全域性¶

直接在規範檔案的根級別列出的屬性。

名稱¶

族的名稱。名稱以唯一的方式標識該族，因為族 ID 是動態分配的。

協議¶

模式級別，預設為 genetlink，這是新 genetlink 族允許的唯一值。

定義¶

型別和常量定義的陣列。

名稱¶

型別/常量的名稱。

型別¶

以下型別之一

const - 單個、獨立的常量

enum - 定義一個整數列舉，每個條目的值遞增 1（例如 0、1、2、3）

flags - 定義一個整數列舉，每個條目的值佔用一個位，從位 0 開始（例如 1、2、4、8）

值¶

const 的值。

value-start¶

enum 和 flags 的第一個值，允許覆蓋 0（對於 enum）和起始位（對於 flags）的預設起始值。對於 flags，value-start 選擇起始位，而不是移位後的值。

不支援稀疏列舉。

條目¶

enum 和 flags 的條目名稱陣列。

attribute-sets¶

此屬性包含有關族的 netlink 屬性的資訊。所有族至少有一個屬性集，大多數族有多個。 attribute-sets 是一個數組，每個條目描述一個集合。

請注意，規範是“扁平化的”，並不意味著在視覺上類似於 netlink 訊息的格式（與核心註釋中看到的某些臨時文件格式不同）。在規範中，下級屬性集不會內聯定義為巢狀，而是定義在一個單獨的屬性集中，該屬性集由容器的 nested-attributes 屬性引用。

規範也可能包含部分集合 - 包含 subset-of 屬性的集合。此類集合描述了完整集合的一部分，允許縮小哪個屬性允許在巢狀中使用或細化驗證標準。部分集合只能在巢狀中使用。它們不會以任何方式呈現給 uAPI。

名稱¶

唯一標識屬性集，操作和巢狀屬性透過 name 引用這些集合。

subset-of¶

重新定義另一個集合的一部分（部分集合）。允許縮小欄位並更改驗證標準，甚至根據它們包含的巢狀來更改屬性型別。部分集合中每個屬性的 value 與主集合中的值隱式相同。

屬性¶

集合中屬性的列表。

屬性屬性¶

名稱¶

標識屬性，在集合中是唯一的。

型別¶

Netlink 屬性型別，請參閱屬性型別。

值¶

數值屬性 ID，用於序列化的 Netlink 訊息中。可以跳過 value 屬性，在這種情況下，屬性 ID 將是前一個屬性的值加 1（遞迴地），對於屬性集中的第一個屬性，則為 1。

屬性（和操作）使用 1 作為第一個條目的預設值（與從 0 開始的定義中的列舉不同），因為條目 0 幾乎總是保留為未定義。如果需要，規範可以顯式地將值設定為 0。

請注意，屬性的 value 僅在其主集合中定義（而不是在子集中）。

enum¶

對於整數型別，指定屬性中的值屬於 definitions 部分中的 enum 或 flags。

enum-as-flags¶

將 enum 視為 flags，無論其在 definitions 中的型別如何。當需要 enum 和 flags 形式時，definitions 應包含 enum，並且需要 flags 形式的屬性應使用此屬性。

nested-attributes¶

標識給定屬性中巢狀的屬性的屬性空間。僅對可能具有子屬性的複雜屬性有效。

multi-attr（陣列）¶

布林屬性，表示該屬性可能多次出現。允許屬性重複是實現陣列的推薦方法（沒有額外的巢狀）。

byte-order¶

對於整數型別，指定屬性位元組序 - little-endian 或 big-endian。

檢查¶

核心使用的輸入驗證約束。使用者空間應使用通用 Netlink 內省查詢執行核心的策略，而不是依賴於規範檔案中指定的內容。

核心中的驗證策略是透過組合型別定義（type 和 nested-attributes）和 checks 來形成的。

子型別¶

舊系列有表達陣列的特殊方式。如果陣列元素沒有完全定義為屬性（在一個真正的屬性空間中），則可以使用 sub-type 來定義陣列元素的型別。例如，u32 值的 C 陣列可以使用 type: binary 和 sub-type: u32 來指定。有關二進位制型別和舊陣列格式的更多詳細資訊，請參閱 Netlink 規範對舊通用 Netlink 系列的支援。

display-hint¶

可選的格式指示符，僅用於在顯示此型別的值時選擇正確的格式化機制。當前支援的提示是 hex、mac、fddi、ipv4、ipv6 和 uuid。

操作¶

本節描述了核心和使用者空間之間傳遞的訊息。本節中有三種類型的條目 - 操作、通知和事件。

操作描述了最常見的請求 - 響應通訊。使用者傳送請求，核心回覆。每個操作可能包含 netlink 使用者熟悉的兩種模式的任意組合 - do 和 dump。 do 和 dump 反過來又包含 request 和 response 屬性的組合。如果在給定方向上沒有傳遞帶有屬性的顯式訊息（例如，不接受過濾器的 dump，或者核心僅以 netlink 錯誤程式碼響應的 SET 操作的 do），則可以跳過 request 或 response 部分。 request 和 response 部分列出了訊息中允許的屬性。該列表僅包含屬性集中屬性的名稱，屬性集由 attribute-set 屬性引用。

通知和事件都指核心傳送給多播組成員的非同步訊息。兩者之間的區別在於，通知與其 GET 操作共享其內容（GET 操作的名稱在 notify 屬性中指定）。此安排通常用於有關物件的通知，其中通知攜帶完整的物件定義。

事件更具針對性，並且僅攜帶資訊子集而不是完整的物件狀態（一個虛構的例子是連結狀態更改事件，僅包含介面名稱和新的連結狀態）。事件包含 event 屬性。對於 netlink 而言，事件被認為不太符合慣例，應首選通知。

列表¶

operations 對於 genetlink 的唯一屬性，包含操作、通知等的列表。

操作屬性¶

名稱¶

標識操作。

值¶

數值訊息 ID，用於序列化的 Netlink 訊息中。應用的列舉規則與屬性值相同。

attribute-set¶

指定訊息中包含的屬性集。

do¶

對 doit 請求的規範。應包含 request、reply 或這兩個屬性，每個屬性都包含一個訊息屬性列表。

dump¶

對 dumpit 請求的規範。應包含 request、reply 或這兩個屬性，每個屬性都包含一個訊息屬性列表。

notify¶

將訊息指定為通知。包含與通知共享內容的名稱的操作名稱（可能與包含此屬性的操作相同）（do）。

event¶

事件中屬性的規範，包含一個訊息屬性列表。event 屬性與 notify 互斥。

mcgrp¶

與 event 和 notify 一起使用，指定訊息屬於哪個多播組。

訊息屬性列表¶

request、reply 和 event 屬性具有一個 attributes 屬性，該屬性包含屬性名稱的列表。

訊息還可以定義 pre 和 post 屬性，這些屬性將在核心中呈現為 pre_doit 和 post_doit 呼叫（這些屬性應被使用者空間忽略）。

mcast-groups¶

本節列出了該族的多播組。

列表¶

mcast-groups 對於 genetlink 的唯一屬性，包含組的列表。

多播組屬性¶

名稱¶

唯一標識族中的多播組。與族 ID 類似，多播組 ID 需要在執行時根據名稱進行解析。

屬性型別¶

本節描述了 genetlink 相容性級別支援的屬性型別。有關其他屬性型別，請參閱不同級別的文件。

常見整數型別¶

sint 和 uint 表示有符號和無符號的 64 位整數。如果該值可以容納在 32 位上，則僅在 netlink 訊息中攜帶 32 位，否則攜帶完整的 64 位。請注意，有效負載僅與 4B 對齊，因此完整的 64 位值可能未對齊！

在大多數情況下，應首選常見整數型別而不是固定寬度型別。

固定寬度整數型別¶

固定寬度整數型別包括：u8、u16、u32、u64、s8、s16、s32、s64。

請注意，應避免使用小於 32 位的型別，因為使用它們不會在 Netlink 訊息中節省任何記憶體（由於對齊）。有關 64 位屬性的填充，請參閱 pad。

屬性的有效負載是主機順序的整數，除非 byte-order 另有指定。

64 位值通常由核心對齊，但建議使用者空間能夠處理未對齊的值。

pad¶

特殊屬性型別，用於填充需要大於 netlink 所需的標準 4B 對齊的對齊方式的屬性（例如 64 位整數）。在任何屬性集中只能有一個 pad 型別的屬性，並且在需要時應自動用於填充。

flag¶

沒有有效負載的屬性，其存在是整個資訊。

binary¶

原始二進位制資料屬性，其內容對於通用程式碼是不透明的。

string¶

字元字串。除非 checks 中將 unterminated-ok 設定為 true，否則該字串必須以 null 結尾。checks 中的 max-len 指示字串的最大長度，如果不存在，則字串的長度是無限制的。

請注意，max-len 不計算終止字元。

nest¶

包含其他（巢狀）屬性的屬性。nested-attributes 指定內部使用的屬性集。