1.. SPDX-License-Identifier: BSD-3-Clause 2 3================================================================= 4Netlink specification support for legacy Generic Netlink families 5================================================================= 6 7This document describes the many additional quirks and properties 8required to describe older Generic Netlink families which form 9the ``genetlink-legacy`` protocol level. 10 11The spec is a work in progress, some of the quirks are just documented 12for future reference. 13 14Specification (defined) 15======================= 16 17Attribute type nests 18-------------------- 19 20New Netlink families should use ``multi-attr`` to define arrays. 21Older families (e.g. ``genetlink`` control family) attempted to 22define array types reusing attribute type to carry information. 23 24For reference the ``multi-attr`` array may look like this:: 25 26 [ARRAY-ATTR] 27 [INDEX (optionally)] 28 [MEMBER1] 29 [MEMBER2] 30 [SOME-OTHER-ATTR] 31 [ARRAY-ATTR] 32 [INDEX (optionally)] 33 [MEMBER1] 34 [MEMBER2] 35 36where ``ARRAY-ATTR`` is the array entry type. 37 38array-nest 39~~~~~~~~~~ 40 41``array-nest`` creates the following structure:: 42 43 [SOME-OTHER-ATTR] 44 [ARRAY-ATTR] 45 [ENTRY] 46 [MEMBER1] 47 [MEMBER2] 48 [ENTRY] 49 [MEMBER1] 50 [MEMBER2] 51 52It wraps the entire array in an extra attribute (hence limiting its size 53to 64kB). The ``ENTRY`` nests are special and have the index of the entry 54as their type instead of normal attribute type. 55 56type-value 57~~~~~~~~~~ 58 59``type-value`` is a construct which uses attribute types to carry 60information about a single object (often used when array is dumped 61entry-by-entry). 62 63``type-value`` can have multiple levels of nesting, for example 64genetlink's policy dumps create the following structures:: 65 66 [POLICY-IDX] 67 [ATTR-IDX] 68 [POLICY-INFO-ATTR1] 69 [POLICY-INFO-ATTR2] 70 71Where the first level of nest has the policy index as it's attribute 72type, it contains a single nest which has the attribute index as its 73type. Inside the attr-index nest are the policy attributes. Modern 74Netlink families should have instead defined this as a flat structure, 75the nesting serves no good purpose here. 76 77Other quirks (todo) 78=================== 79 80Structures 81---------- 82 83Legacy families can define C structures both to be used as the contents 84of an attribute and as a fixed message header. The plan is to define 85the structs in ``definitions`` and link the appropriate attrs. 86 87Multi-message DO 88---------------- 89 90New Netlink families should never respond to a DO operation with multiple 91replies, with ``NLM_F_MULTI`` set. Use a filtered dump instead. 92 93At the spec level we can define a ``dumps`` property for the ``do``, 94perhaps with values of ``combine`` and ``multi-object`` depending 95on how the parsing should be implemented (parse into a single reply 96vs list of objects i.e. pretty much a dump). 97