Documentation/userspace-api/netlink/netlink-raw.rst

   1 .. SPDX-License-Identifier: BSD-3-Clause
   2
   3 ======================================================
   4 Netlink specification support for raw Netlink families
   5 ======================================================
   6
   7 This document describes the additional properties required by raw Netlink
   8 families such as ``NETLINK_ROUTE`` which use the ``netlink-raw`` protocol
   9 specification.
  10
  11 Specification
  12 =============
  13
  14 The netlink-raw schema extends the :doc:`genetlink-legacy <genetlink-legacy>`
  15 schema with properties that are needed to specify the protocol numbers and
  16 multicast IDs used by raw netlink families. See :ref:`classic_netlink` for more
  17 information. The raw netlink families also make use of type-specific
  18 sub-messages.
  19
  20 Globals
  21 -------
  22
  23 protonum
  24 ~~~~~~~~
  25
  26 The ``protonum`` property is used to specify the protocol number to use when
  27 opening 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
  38 Multicast group properties
  39 --------------------------
  40
  41 value
  42 ~~~~~
  43
  44 The ``value`` property is used to specify the group ID to use for multicast
  45 group 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
  61 Sub-messages
  62 ------------
  63
  64 Several raw netlink families such as
  65 :doc:`rt_link<../../networking/netlink_spec/rt_link>` and
  66 :doc:`tc<../../networking/netlink_spec/tc>` use attribute nesting as an
  67 abstraction to carry module specific information.
  68
  69 Conceptually 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
  79 The ``GENERIC ATTRs`` at the outer level are defined in the core (or rt_link or
  80 core TC), while specific drivers, TC classifiers, qdiscs etc. can carry their
  81 own information wrapped in the ``GENERIC ATTR - wrapper``. Even though the
  82 example above shows attributes nesting inside the wrapper, the modules generally
  83 have full freedom to define the format of the nest. In practice the payload of
  84 the wrapper attr has very similar characteristics to a netlink message. It may
  85 contain a fixed header / structure, netlink attributes, or both. Because of
  86 those shared characteristics we refer to the payload of the wrapper attribute as
  87 a sub-message.
  88
  89 A sub-message attribute uses the value of another attribute as a selector key to
  90 choose the right sub-message format. For example if the following attribute has
  91 already been decoded:
  92
  93 .. code-block:: json
  94
  95   { "kind": "gre" }
  96
  97 and 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
 107 Then we look for a sub-message definition called ``linkinfo-data-msg`` and use
 108 the value of the ``kind`` attribute i.e. ``gre`` as the key to choose the
 109 correct 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
 126 This would decode the attribute value as a sub-message with the attribute-set
 127 called ``linkinfo-gre-attrs`` as the attribute space.
 128
 129 A sub-message can have an optional ``fixed-header`` followed by zero or more
 130 attributes 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
 151 Note that a selector attribute must appear in a netlink message before any
 152 sub-message attributes that depend on it.