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