| .. SPDX-License-Identifier: BSD-3-Clause |
| |
| .. _kernel_netlink: |
| |
| =================================== |
| Netlink notes for kernel developers |
| =================================== |
| |
| General guidance |
| ================ |
| |
| Attribute enums |
| --------------- |
| |
| Older families often define "null" attributes and commands with value |
| of ``0`` and named ``unspec``. This is supported (``type: unused``) |
| but should be avoided in new families. The ``unspec`` enum values are |
| not used in practice, so just set the value of the first attribute to ``1``. |
| |
| Message enums |
| ------------- |
| |
| Use the same command IDs for requests and replies. This makes it easier |
| to match them up, and we have plenty of ID space. |
| |
| Use separate command IDs for notifications. This makes it easier to |
| sort the notifications from replies (and present them to the user |
| application via a different API than replies). |
| |
| Answer requests |
| --------------- |
| |
| Older families do not reply to all of the commands, especially NEW / ADD |
| commands. User only gets information whether the operation succeeded or |
| not via the ACK. Try to find useful data to return. Once the command is |
| added whether it replies with a full message or only an ACK is uAPI and |
| cannot be changed. It's better to err on the side of replying. |
| |
| Specifically NEW and ADD commands should reply with information identifying |
| the created object such as the allocated object's ID (without having to |
| resort to using ``NLM_F_ECHO``). |
| |
| NLM_F_ECHO |
| ---------- |
| |
| Make sure to pass the request info to genl_notify() to allow ``NLM_F_ECHO`` |
| to take effect. This is useful for programs that need precise feedback |
| from the kernel (for example for logging purposes). |
| |
| Support dump consistency |
| ------------------------ |
| |
| If iterating over objects during dump may skip over objects or repeat |
| them - make sure to report dump inconsistency with ``NLM_F_DUMP_INTR``. |
| This is usually implemented by maintaining a generation id for the |
| structure and recording it in the ``seq`` member of struct netlink_callback. |
| |
| Netlink specification |
| ===================== |
| |
| Documentation of the Netlink specification parts which are only relevant |
| to the kernel space. |
| |
| Globals |
| ------- |
| |
| kernel-policy |
| ~~~~~~~~~~~~~ |
| |
| Defines whether the kernel validation policy is ``global`` i.e. the same for all |
| operations of the family, defined for each operation individually - ``per-op``, |
| or separately for each operation and operation type (do vs dump) - ``split``. |
| New families should use ``per-op`` (default) to be able to narrow down the |
| attributes accepted by a specific command. |
| |
| checks |
| ------ |
| |
| Documentation for the ``checks`` sub-sections of attribute specs. |
| |
| unterminated-ok |
| ~~~~~~~~~~~~~~~ |
| |
| Accept strings without the null-termination (for legacy families only). |
| Switches from the ``NLA_NUL_STRING`` to ``NLA_STRING`` policy type. |
| |
| max-len |
| ~~~~~~~ |
| |
| Defines max length for a binary or string attribute (corresponding |
| to the ``len`` member of struct nla_policy). For string attributes terminating |
| null character is not counted towards ``max-len``. |
| |
| The field may either be a literal integer value or a name of a defined |
| constant. String types may reduce the constant by one |
| (i.e. specify ``max-len: CONST - 1``) to reserve space for the terminating |
| character so implementations should recognize such pattern. |
| |
| min-len |
| ~~~~~~~ |
| |
| Similar to ``max-len`` but defines minimum length. |
