netlink-raw.rst

  1.. SPDX-License-Identifier: BSD-3-Clause
  2
  3======================================================
  4Netlink specification support for raw Netlink families
  5======================================================
  6
  7This document describes the additional properties required by raw Netlink
  8families such as ``NETLINK_ROUTE`` which use the ``netlink-raw`` protocol
  9specification.
 10
 11Specification
 12=============
 13
 14The netlink-raw schema extends the :doc:`genetlink-legacy <genetlink-legacy>`
 15schema with properties that are needed to specify the protocol numbers and
 16multicast IDs used by raw netlink families. See :ref:`classic_netlink` for more
 17information. The raw netlink families also make use of type-specific
 18sub-messages.
 19
 20Globals
 21-------
 22
 23protonum
 24~~~~~~~~
 25
 26The ``protonum`` property is used to specify the protocol number to use when
 27opening a netlink socket.
 28
 29.. code-block:: yaml
 30
 31  # SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)
 32
 33  name: rt-addr
 34  protocol: netlink-raw
 35  protonum: 0             # part of the NETLINK_ROUTE protocol
 36
 37
 38Multicast group properties
 39--------------------------
 40
 41value
 42~~~~~
 43
 44The ``value`` property is used to specify the group ID to use for multicast
 45group registration.
 46
 47.. code-block:: yaml
 48
 49  mcast-groups:
 50    list:
 51      -
 52        name: rtnlgrp-ipv4-ifaddr
 53        value: 5
 54      -
 55        name: rtnlgrp-ipv6-ifaddr
 56        value: 9
 57      -
 58        name: rtnlgrp-mctp-ifaddr
 59        value: 34
 60
 61Sub-messages
 62------------
 63
 64Several raw netlink families such as
 65:ref:`rt-link<netlink-rt-link>` and
 66:ref:`tc<netlink-tc>` use attribute nesting as an
 67abstraction to carry module specific information.
 68
 69Conceptually it looks as follows::
 70
 71    [OUTER NEST OR MESSAGE LEVEL]
 72      [GENERIC ATTR 1]
 73      [GENERIC ATTR 2]
 74      [GENERIC ATTR 3]
 75      [GENERIC ATTR - wrapper]
 76        [MODULE SPECIFIC ATTR 1]
 77        [MODULE SPECIFIC ATTR 2]
 78
 79The ``GENERIC ATTRs`` at the outer level are defined in the core (or rt_link or
 80core TC), while specific drivers, TC classifiers, qdiscs etc. can carry their
 81own information wrapped in the ``GENERIC ATTR - wrapper``. Even though the
 82example above shows attributes nesting inside the wrapper, the modules generally
 83have full freedom to define the format of the nest. In practice the payload of
 84the wrapper attr has very similar characteristics to a netlink message. It may
 85contain a fixed header / structure, netlink attributes, or both. Because of
 86those shared characteristics we refer to the payload of the wrapper attribute as
 87a sub-message.
 88
 89A sub-message attribute uses the value of another attribute as a selector key to
 90choose the right sub-message format. For example if the following attribute has
 91already been decoded:
 92
 93.. code-block:: json
 94
 95  { "kind": "gre" }
 96
 97and we encounter the following attribute spec:
 98
 99.. code-block:: yaml
100
101  -
102    name: data
103    type: sub-message
104    sub-message: linkinfo-data-msg
105    selector: kind
106
107Then we look for a sub-message definition called ``linkinfo-data-msg`` and use
108the value of the ``kind`` attribute i.e. ``gre`` as the key to choose the
109correct format for the sub-message:
110
111.. code-block:: yaml
112
113  sub-messages:
114    name: linkinfo-data-msg
115    formats:
116      -
117        value: bridge
118        attribute-set: linkinfo-bridge-attrs
119      -
120        value: gre
121        attribute-set: linkinfo-gre-attrs
122      -
123        value: geneve
124        attribute-set: linkinfo-geneve-attrs
125
126This would decode the attribute value as a sub-message with the attribute-set
127called ``linkinfo-gre-attrs`` as the attribute space.
128
129A sub-message can have an optional ``fixed-header`` followed by zero or more
130attributes from an ``attribute-set``. For example the following
131``tc-options-msg`` sub-message defines message formats that use a mixture of
132``fixed-header``, ``attribute-set`` or both together:
133
134.. code-block:: yaml
135
136  sub-messages:
137    -
138      name: tc-options-msg
139      formats:
140        -
141          value: bfifo
142          fixed-header: tc-fifo-qopt
143        -
144          value: cake
145          attribute-set: tc-cake-attrs
146        -
147          value: netem
148          fixed-header: tc-netem-qopt
149          attribute-set: tc-netem-attrs
150
151Note that a selector attribute must appear in a netlink message before any
152sub-message attributes that depend on it.
153
154If an attribute such as ``kind`` is defined at more than one nest level, then a
155sub-message selector will be resolved using the value 'closest' to the selector.
156For example, if the same attribute name is defined in a nested ``attribute-set``
157alongside a sub-message selector and also in a top level ``attribute-set``, then
158the selector will be resolved using the value 'closest' to the selector. If the
159value is not present in the message at the same level as defined in the spec
160then this is an error.
161
162Nested struct definitions
163-------------------------
164
165Many raw netlink families such as :ref:`tc<netlink-tc>`
166make use of nested struct definitions. The ``netlink-raw`` schema makes it
167possible to embed a struct within a struct definition using the ``struct``
168property. For example, the following struct definition embeds the
169``tc-ratespec`` struct definition for both the ``rate`` and the ``peakrate``
170members of ``struct tc-tbf-qopt``.
171
172.. code-block:: yaml
173
174  -
175    name: tc-tbf-qopt
176    type: struct
177    members:
178      -
179        name: rate
180        type: binary
181        struct: tc-ratespec
182      -
183        name: peakrate
184        type: binary
185        struct: tc-ratespec
186      -
187        name: limit
188        type: u32
189      -
190        name: buffer
191        type: u32
192      -
193        name: mtu
194        type: u32