103 lines
3.3 KiB
ReStructuredText
103 lines
3.3 KiB
ReStructuredText
.. 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.
|