userspace-api/netlink/genetlink-legacy.rst

1 .. SPDX-License-Identifier: BSD-3-Clause
9 the ``genetlink-legacy`` protocol level.
15 -------
28 Attribute type nests
29 --------------------
31 New Netlink families should use ``multi-attr`` to define arrays.
33 define array types reusing attribute type to carry information.
35 For reference the ``multi-attr`` array may look like this::
37   [ARRAY-ATTR]
41   [SOME-OTHER-ATTR]
42   [ARRAY-ATTR]
47 where ``ARRAY-ATTR`` is the array entry type.
49 array-nest
52 ``array-nest`` creates the following structure::
54   [SOME-OTHER-ATTR]
55   [ARRAY-ATTR]
63 It wraps the entire array in an extra attribute (hence limiting its size
65 as their type instead of normal attribute type.
67 type-value
70 ``type-value`` is a construct which uses attribute types to carry
72 entry-by-entry).
74 ``type-value`` can have multiple levels of nesting, for example
77   [POLICY-IDX]
78     [ATTR-IDX]
79       [POLICY-INFO-ATTR1]
80       [POLICY-INFO-ATTR2]
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
92 -----------------------
103 .. code-block:: yaml
105   -
109   -
112   -
116   -
121 the requests and responses of ``b`` - 2 (since there is no explicit
133 In this case ``value`` attribute should be specified in the ``request``
135 and ``dump`` the IDs are shared, ``value`` should be set in ``do``).
137 only allocates a ``reply`` (i.e. a "from-kernel" ID). Let's look
140 .. code-block:: yaml
142   -
151   -
154   -
158   -
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
168 the previous operation in the "from-kernel" direction).
174 ----------
177 an attribute and as a fixed message header. Structures are defined in
183  - ``name`` - The attribute name of the struct member
184  - ``type`` - One of the scalar types ``u8``, ``u16``, ``u32``, ``u64``, ``s8``,
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>`
193 .. code-block:: c
201 Any padding must be explicitly added and C-like languages should infer the
206 .. code-block:: yaml
209     -
210       name: message-header
213         -
216         -
219         -
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
230 .. code-block:: yaml
233     fixed-header: message-header
235       -
237         fixed-header: custom-header
238         attribute-set: message-attrs
243 A ``binary`` attribute can be interpreted as a C structure using a
245 ``struct`` property implies ``sub-type: struct`` so it is not necessary to
246 specify a sub-type.
248 .. code-block:: yaml
250   attribute-sets:
251     -
252       name: stats-attrs
254         -
257           struct: vport-stats
260 --------
263 ``sub-type`` is used to identify the type of scalar to extract.
265 .. code-block:: yaml
268     -
271       sub-type: u32
273 Multi-message DO
274 ----------------
277 replies, with ``NLM_F_MULTI`` set. Use a filtered dump instead.
280 perhaps with values of ``combine`` and ``multi-object`` depending