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

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