| 1 | |
| 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.
|