1 .. SPDX-License-Identifier: BSD-3-Clause 2 3 .. _kernel_netlink: 4 5 =================================== 6 Netlink notes for kernel developers 7 =================================== 8 9 General guidance 10 ================ 11 12 Attribute enums 13 --------------- 14 15 Older families often define "null" attributes and commands with value 16 of ``0`` and named ``unspec``. This is supported (``type: unused``) 17 but should be avoided in new families. The ``unspec`` enum values are 18 not used in practice, so just set the value of the first attribute to ``1``. 19 20 Message enums 21 ------------- 22 23 Use the same command IDs for requests and replies. This makes it easier 24 to match them up, and we have plenty of ID space. 25 26 Use separate command IDs for notifications. This makes it easier to 27 sort the notifications from replies (and present them to the user 28 application via a different API than replies). 29 30 Answer requests 31 --------------- 32 33 Older families do not reply to all of the commands, especially NEW / ADD 34 commands. User only gets information whether the operation succeeded or 35 not via the ACK. Try to find useful data to return. Once the command is 36 added whether it replies with a full message or only an ACK is uAPI and 37 cannot be changed. It's better to err on the side of replying. 38 39 Specifically NEW and ADD commands should reply with information identifying 40 the created object such as the allocated object's ID (without having to 41 resort to using ``NLM_F_ECHO``). 42 43 NLM_F_ECHO 44 ---------- 45 46 Make sure to pass the request info to genl_notify() to allow ``NLM_F_ECHO`` 47 to take effect. This is useful for programs that need precise feedback 48 from the kernel (for example for logging purposes). 49 50 Support dump consistency 51 ------------------------ 52 53 If iterating over objects during dump may skip over objects or repeat 54 them - make sure to report dump inconsistency with ``NLM_F_DUMP_INTR``. 55 This is usually implemented by maintaining a generation id for the 56 structure and recording it in the ``seq`` member of struct netlink_callback. 57 58 Netlink specification 59 ===================== 60 61 Documentation of the Netlink specification parts which are only relevant 62 to the kernel space. 63 64 Globals 65 ------- 66 67 kernel-policy 68 ~~~~~~~~~~~~~ 69 70 Defines whether the kernel validation policy is ``global`` i.e. the same for all 71 operations of the family, defined for each operation individually - ``per-op``, 72 or separately for each operation and operation type (do vs dump) - ``split``. 73 New families should use ``per-op`` (default) to be able to narrow down the 74 attributes accepted by a specific command. 75 76 checks 77 ------ 78 79 Documentation for the ``checks`` sub-sections of attribute specs. 80 81 unterminated-ok 82 ~~~~~~~~~~~~~~~ 83 84 Accept strings without the null-termination (for legacy families only). 85 Switches from the ``NLA_NUL_STRING`` to ``NLA_STRING`` policy type. 86 87 max-len 88 ~~~~~~~ 89 90 Defines max length for a binary or string attribute (corresponding 91 to the ``len`` member of struct nla_policy). For string attributes terminating 92 null character is not counted towards ``max-len``. 93 94 The field may either be a literal integer value or a name of a defined 95 constant. String types may reduce the constant by one 96 (i.e. specify ``max-len: CONST - 1``) to reserve space for the terminating 97 character so implementations should recognize such pattern. 98 99 min-len 100 ~~~~~~~ 101 102 Similar to ``max-len`` but defines minimum length.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.