Linux/Documentation/userspace-api/netlink/genetlink-legacy.rst

Version: ~ [ linux-6.12-rc7 ] ~ [ linux-6.11.7 ] ~ [ linux-6.10.14 ] ~ [ linux-6.9.12 ] ~ [ linux-6.8.12 ] ~ [ linux-6.7.12 ] ~ [ linux-6.6.60 ] ~ [ linux-6.5.13 ] ~ [ linux-6.4.16 ] ~ [ linux-6.3.13 ] ~ [ linux-6.2.16 ] ~ [ linux-6.1.116 ] ~ [ linux-6.0.19 ] ~ [ linux-5.19.17 ] ~ [ linux-5.18.19 ] ~ [ linux-5.17.15 ] ~ [ linux-5.16.20 ] ~ [ linux-5.15.171 ] ~ [ linux-5.14.21 ] ~ [ linux-5.13.19 ] ~ [ linux-5.12.19 ] ~ [ linux-5.11.22 ] ~ [ linux-5.10.229 ] ~ [ linux-5.9.16 ] ~ [ linux-5.8.18 ] ~ [ linux-5.7.19 ] ~ [ linux-5.6.19 ] ~ [ linux-5.5.19 ] ~ [ linux-5.4.285 ] ~ [ linux-5.3.18 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.323 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.336 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.337 ] ~ [ linux-4.4.302 ] ~ [ linux-3.10.108 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.12 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

Diff markup

1 .. SPDX-License-Identifier: BSD-3-Clause 1 .. SPDX-License-Identifier: BSD-3-Clause 2 2 3 ============================================== 3 ================================================================= 4 Netlink specification support for legacy Gener 4 Netlink specification support for legacy Generic Netlink families 5 ============================================== 5 ================================================================= 6 6 7 This document describes the many additional qu 7 This document describes the many additional quirks and properties 8 required to describe older Generic Netlink fam 8 required to describe older Generic Netlink families which form 9 the ``genetlink-legacy`` protocol level. 9 the ``genetlink-legacy`` protocol level. 10 10 11 Specification !! 11 The spec is a work in progress, some of the quirks are just documented 12 ============= !! 12 for future reference. 13 13 14 Globals !! 14 Specification (defined) 15 ------- !! 15 ======================= 16 << 17 Attributes listed directly at the root level o << 18 << 19 version << 20 ~~~~~~~ << 21 << 22 Generic Netlink family version, default is 1. << 23 << 24 ``version`` has historically been used to intr << 25 which may break backwards compatibility. Since << 26 are generally not allowed ``version`` is very << 27 16 28 Attribute type nests 17 Attribute type nests 29 -------------------- 18 -------------------- 30 19 31 New Netlink families should use ``multi-attr`` 20 New Netlink families should use ``multi-attr`` to define arrays. 32 Older families (e.g. ``genetlink`` control fam 21 Older families (e.g. ``genetlink`` control family) attempted to 33 define array types reusing attribute type to c 22 define array types reusing attribute type to carry information. 34 23 35 For reference the ``multi-attr`` array may loo 24 For reference the ``multi-attr`` array may look like this:: 36 25 37 [ARRAY-ATTR] 26 [ARRAY-ATTR] 38 [INDEX (optionally)] 27 [INDEX (optionally)] 39 [MEMBER1] 28 [MEMBER1] 40 [MEMBER2] 29 [MEMBER2] 41 [SOME-OTHER-ATTR] 30 [SOME-OTHER-ATTR] 42 [ARRAY-ATTR] 31 [ARRAY-ATTR] 43 [INDEX (optionally)] 32 [INDEX (optionally)] 44 [MEMBER1] 33 [MEMBER1] 45 [MEMBER2] 34 [MEMBER2] 46 35 47 where ``ARRAY-ATTR`` is the array entry type. 36 where ``ARRAY-ATTR`` is the array entry type. 48 37 49 indexed-array !! 38 array-nest 50 ~~~~~~~~~~~~~ !! 39 ~~~~~~~~~~ 51 40 52 ``indexed-array`` wraps the entire array in an !! 41 ``array-nest`` creates the following structure:: 53 limiting its size to 64kB). The ``ENTRY`` nest << 54 index of the entry as their type instead of no << 55 << 56 A ``sub-type`` is needed to describe what type << 57 ``sub-type`` means there are nest arrays in th << 58 looks like:: << 59 42 60 [SOME-OTHER-ATTR] 43 [SOME-OTHER-ATTR] 61 [ARRAY-ATTR] 44 [ARRAY-ATTR] 62 [ENTRY] 45 [ENTRY] 63 [MEMBER1] 46 [MEMBER1] 64 [MEMBER2] 47 [MEMBER2] 65 [ENTRY] 48 [ENTRY] 66 [MEMBER1] 49 [MEMBER1] 67 [MEMBER2] 50 [MEMBER2] 68 51 69 Other ``sub-type`` like ``u32`` means there is !! 52 It wraps the entire array in an extra attribute (hence limiting its size 70 in ``sub-type`` in the ``ENTRY``. The structur !! 53 to 64kB). The ``ENTRY`` nests are special and have the index of the entry 71 !! 54 as their type instead of normal attribute type. 72 [SOME-OTHER-ATTR] << 73 [ARRAY-ATTR] << 74 [ENTRY u32] << 75 [ENTRY u32] << 76 55 77 type-value 56 type-value 78 ~~~~~~~~~~ 57 ~~~~~~~~~~ 79 58 80 ``type-value`` is a construct which uses attri 59 ``type-value`` is a construct which uses attribute types to carry 81 information about a single object (often used 60 information about a single object (often used when array is dumped 82 entry-by-entry). 61 entry-by-entry). 83 62 84 ``type-value`` can have multiple levels of nes 63 ``type-value`` can have multiple levels of nesting, for example 85 genetlink's policy dumps create the following 64 genetlink's policy dumps create the following structures:: 86 65 87 [POLICY-IDX] 66 [POLICY-IDX] 88 [ATTR-IDX] 67 [ATTR-IDX] 89 [POLICY-INFO-ATTR1] 68 [POLICY-INFO-ATTR1] 90 [POLICY-INFO-ATTR2] 69 [POLICY-INFO-ATTR2] 91 70 92 Where the first level of nest has the policy i 71 Where the first level of nest has the policy index as it's attribute 93 type, it contains a single nest which has the 72 type, it contains a single nest which has the attribute index as its 94 type. Inside the attr-index nest are the polic 73 type. Inside the attr-index nest are the policy attributes. Modern 95 Netlink families should have instead defined t 74 Netlink families should have instead defined this as a flat structure, 96 the nesting serves no good purpose here. 75 the nesting serves no good purpose here. 97 76 98 Operations 77 Operations 99 ========== 78 ========== 100 79 101 Enum (message ID) model 80 Enum (message ID) model 102 ----------------------- 81 ----------------------- 103 82 104 unified 83 unified 105 ~~~~~~~ 84 ~~~~~~~ 106 85 107 Modern families use the ``unified`` message ID 86 Modern families use the ``unified`` message ID model, which uses 108 a single enumeration for all messages within f 87 a single enumeration for all messages within family. Requests and 109 responses share the same message ID. Notificat 88 responses share the same message ID. Notifications have separate 110 IDs from the same space. For example given the 89 IDs from the same space. For example given the following list 111 of operations: 90 of operations: 112 91 113 .. code-block:: yaml 92 .. code-block:: yaml 114 93 115 - 94 - 116 name: a 95 name: a 117 value: 1 96 value: 1 118 do: ... 97 do: ... 119 - 98 - 120 name: b 99 name: b 121 do: ... 100 do: ... 122 - 101 - 123 name: c 102 name: c 124 value: 4 103 value: 4 125 notify: a 104 notify: a 126 - 105 - 127 name: d 106 name: d 128 do: ... 107 do: ... 129 108 130 Requests and responses for operation ``a`` wil 109 Requests and responses for operation ``a`` will have the ID of 1, 131 the requests and responses of ``b`` - 2 (since 110 the requests and responses of ``b`` - 2 (since there is no explicit 132 ``value`` it's previous operation ``+ 1``). No 111 ``value`` it's previous operation ``+ 1``). Notification ``c`` will 133 use the ID of 4, operation ``d`` 5 etc. 112 use the ID of 4, operation ``d`` 5 etc. 134 113 135 directional 114 directional 136 ~~~~~~~~~~~ 115 ~~~~~~~~~~~ 137 116 138 The ``directional`` model splits the ID assign 117 The ``directional`` model splits the ID assignment by the direction of 139 the message. Messages from and to the kernel c 118 the message. Messages from and to the kernel can't be confused with 140 each other so this conserves the ID space (at 119 each other so this conserves the ID space (at the cost of making 141 the programming more cumbersome). 120 the programming more cumbersome). 142 121 143 In this case ``value`` attribute should be spe 122 In this case ``value`` attribute should be specified in the ``request`` 144 ``reply`` sections of the operations (if an op 123 ``reply`` sections of the operations (if an operation has both ``do`` 145 and ``dump`` the IDs are shared, ``value`` sho 124 and ``dump`` the IDs are shared, ``value`` should be set in ``do``). 146 For notifications the ``value`` is provided at 125 For notifications the ``value`` is provided at the op level but it 147 only allocates a ``reply`` (i.e. a "from-kerne 126 only allocates a ``reply`` (i.e. a "from-kernel" ID). Let's look 148 at an example: 127 at an example: 149 128 150 .. code-block:: yaml 129 .. code-block:: yaml 151 130 152 - 131 - 153 name: a 132 name: a 154 do: 133 do: 155 request: 134 request: 156 value: 2 135 value: 2 157 attributes: ... 136 attributes: ... 158 reply: 137 reply: 159 value: 1 138 value: 1 160 attributes: ... 139 attributes: ... 161 - 140 - 162 name: b 141 name: b 163 notify: a 142 notify: a 164 - 143 - 165 name: c 144 name: c 166 notify: a 145 notify: a 167 value: 7 146 value: 7 168 - 147 - 169 name: d 148 name: d 170 do: ... 149 do: ... 171 150 172 In this case ``a`` will use 2 when sending the 151 In this case ``a`` will use 2 when sending the message to the kernel 173 and expects message with ID 1 in response. Not 152 and expects message with ID 1 in response. Notification ``b`` allocates 174 a "from-kernel" ID which is 2. ``c`` allocates 153 a "from-kernel" ID which is 2. ``c`` allocates "from-kernel" ID of 7. 175 If operation ``d`` does not set ``values`` exp 154 If operation ``d`` does not set ``values`` explicitly in the spec 176 it will be allocated 3 for the request (``a`` 155 it will be allocated 3 for the request (``a`` is the previous operation 177 with a request section and the value of 2) and 156 with a request section and the value of 2) and 8 for response (``c`` is 178 the previous operation in the "from-kernel" di 157 the previous operation in the "from-kernel" direction). 179 158 180 Other quirks !! 159 Other quirks (todo) 181 ============ !! 160 =================== 182 161 183 Structures 162 Structures 184 ---------- 163 ---------- 185 164 186 Legacy families can define C structures both t !! 165 Legacy families can define C structures both to be used as the contents 187 an attribute and as a fixed message header. St !! 166 of an attribute and as a fixed message header. The plan is to define 188 ``definitions`` and referenced in operations !! 167 the structs in ``definitions`` and link the appropriate attrs. 189 << 190 members << 191 ~~~~~~~ << 192 << 193 - ``name`` - The attribute name of the struct << 194 - ``type`` - One of the scalar types ``u8``, << 195 ``s16``, ``s32``, ``s64``, ``string``, ``bi << 196 - ``byte-order`` - ``big-endian`` or ``little << 197 - ``doc``, ``enum``, ``enum-as-flags``, ``dis << 198 :ref:`attribute definitions <attribute_prop << 199 << 200 Note that structures defined in YAML are impli << 201 conventions. For example, the following struct << 202 << 203 .. code-block:: c << 204 << 205 struct { << 206 u8 a; << 207 u16 b; << 208 u8 c; << 209 } << 210 << 211 Any padding must be explicitly added and C-lik << 212 need for explicit padding from whether the mem << 213 << 214 Here is the struct definition from above, decl << 215 << 216 .. code-block:: yaml << 217 << 218 definitions: << 219 - << 220 name: message-header << 221 type: struct << 222 members: << 223 - << 224 name: a << 225 type: u8 << 226 - << 227 name: b << 228 type: u16 << 229 - << 230 name: c << 231 type: u8 << 232 << 233 Fixed Headers << 234 ~~~~~~~~~~~~~ << 235 << 236 Fixed message headers can be added to operatio << 237 The default ``fixed-header`` can be set in ``o << 238 or overridden for each operation. << 239 << 240 .. code-block:: yaml << 241 << 242 operations: << 243 fixed-header: message-header << 244 list: << 245 - << 246 name: get << 247 fixed-header: custom-header << 248 attribute-set: message-attrs << 249 << 250 Attributes << 251 ~~~~~~~~~~ << 252 << 253 A ``binary`` attribute can be interpreted as a << 254 ``struct`` property with the name of the struc << 255 ``struct`` property implies ``sub-type: struct << 256 specify a sub-type. << 257 << 258 .. code-block:: yaml << 259 << 260 attribute-sets: << 261 - << 262 name: stats-attrs << 263 attributes: << 264 - << 265 name: stats << 266 type: binary << 267 struct: vport-stats << 268 << 269 C Arrays << 270 -------- << 271 << 272 Legacy families also use ``binary`` attributes << 273 ``sub-type`` is used to identify the type of s << 274 << 275 .. code-block:: yaml << 276 << 277 attributes: << 278 - << 279 name: ports << 280 type: binary << 281 sub-type: u32 << 282 168 283 Multi-message DO 169 Multi-message DO 284 ---------------- 170 ---------------- 285 171 286 New Netlink families should never respond to a 172 New Netlink families should never respond to a DO operation with multiple 287 replies, with ``NLM_F_MULTI`` set. Use a filte 173 replies, with ``NLM_F_MULTI`` set. Use a filtered dump instead. 288 174 289 At the spec level we can define a ``dumps`` pr 175 At the spec level we can define a ``dumps`` property for the ``do``, 290 perhaps with values of ``combine`` and ``multi 176 perhaps with values of ``combine`` and ``multi-object`` depending 291 on how the parsing should be implemented (pars 177 on how the parsing should be implemented (parse into a single reply 292 vs list of objects i.e. pretty much a dump). 178 vs list of objects i.e. pretty much a dump).

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.

TOMOYO Linux Cross Reference
Linux/Documentation/userspace-api/netlink/genetlink-legacy.rst

Diff markup

Differences between /Documentation/userspace-api/netlink/genetlink-legacy.rst (Version linux-6.12-rc7) and /Documentation/userspace-api/netlink/genetlink-legacy.rst (Version linux-6.3.13)

TOMOYO Linux Cross Reference Linux/Documentation/userspace-api/netlink/genetlink-legacy.rst

Diff markup

Differences between /Documentation/userspace-api/netlink/genetlink-legacy.rst (Version linux-6.12-rc7) and /Documentation/userspace-api/netlink/genetlink-legacy.rst (Version linux-6.3.13)

TOMOYO Linux Cross Reference
Linux/Documentation/userspace-api/netlink/genetlink-legacy.rst