103 lines · plain
1.. SPDX-License-Identifier: BSD-3-Clause2 3.. _kernel_netlink:4 5===================================6Netlink notes for kernel developers7===================================8 9General guidance10================11 12Attribute enums13---------------14 15Older families often define "null" attributes and commands with value16of ``0`` and named ``unspec``. This is supported (``type: unused``)17but should be avoided in new families. The ``unspec`` enum values are18not used in practice, so just set the value of the first attribute to ``1``.19 20Message enums21-------------22 23Use the same command IDs for requests and replies. This makes it easier24to match them up, and we have plenty of ID space.25 26Use separate command IDs for notifications. This makes it easier to27sort the notifications from replies (and present them to the user28application via a different API than replies).29 30Answer requests31---------------32 33Older families do not reply to all of the commands, especially NEW / ADD34commands. User only gets information whether the operation succeeded or35not via the ACK. Try to find useful data to return. Once the command is36added whether it replies with a full message or only an ACK is uAPI and37cannot be changed. It's better to err on the side of replying.38 39Specifically NEW and ADD commands should reply with information identifying40the created object such as the allocated object's ID (without having to41resort to using ``NLM_F_ECHO``).42 43NLM_F_ECHO44----------45 46Make sure to pass the request info to genl_notify() to allow ``NLM_F_ECHO``47to take effect. This is useful for programs that need precise feedback48from the kernel (for example for logging purposes).49 50Support dump consistency51------------------------52 53If iterating over objects during dump may skip over objects or repeat54them - make sure to report dump inconsistency with ``NLM_F_DUMP_INTR``.55This is usually implemented by maintaining a generation id for the56structure and recording it in the ``seq`` member of struct netlink_callback.57 58Netlink specification59=====================60 61Documentation of the Netlink specification parts which are only relevant62to the kernel space.63 64Globals65-------66 67kernel-policy68~~~~~~~~~~~~~69 70Defines whether the kernel validation policy is ``global`` i.e. the same for all71operations of the family, defined for each operation individually - ``per-op``,72or separately for each operation and operation type (do vs dump) - ``split``.73New families should use ``per-op`` (default) to be able to narrow down the74attributes accepted by a specific command.75 76checks77------78 79Documentation for the ``checks`` sub-sections of attribute specs.80 81unterminated-ok82~~~~~~~~~~~~~~~83 84Accept strings without the null-termination (for legacy families only).85Switches from the ``NLA_NUL_STRING`` to ``NLA_STRING`` policy type.86 87max-len88~~~~~~~89 90Defines max length for a binary or string attribute (corresponding91to the ``len`` member of struct nla_policy). For string attributes terminating92null character is not counted towards ``max-len``.93 94The field may either be a literal integer value or a name of a defined95constant. String types may reduce the constant by one96(i.e. specify ``max-len: CONST - 1``) to reserve space for the terminating97character so implementations should recognize such pattern.98 99min-len100~~~~~~~101 102Similar to ``max-len`` but defines minimum length.103