162306a36Sopenharmony_ci.. SPDX-License-Identifier: BSD-3-Clause 262306a36Sopenharmony_ci 362306a36Sopenharmony_ci.. _kernel_netlink: 462306a36Sopenharmony_ci 562306a36Sopenharmony_ci=================================== 662306a36Sopenharmony_ciNetlink notes for kernel developers 762306a36Sopenharmony_ci=================================== 862306a36Sopenharmony_ci 962306a36Sopenharmony_ciGeneral guidance 1062306a36Sopenharmony_ci================ 1162306a36Sopenharmony_ci 1262306a36Sopenharmony_ciAttribute enums 1362306a36Sopenharmony_ci--------------- 1462306a36Sopenharmony_ci 1562306a36Sopenharmony_ciOlder families often define "null" attributes and commands with value 1662306a36Sopenharmony_ciof ``0`` and named ``unspec``. This is supported (``type: unused``) 1762306a36Sopenharmony_cibut should be avoided in new families. The ``unspec`` enum values are 1862306a36Sopenharmony_cinot used in practice, so just set the value of the first attribute to ``1``. 1962306a36Sopenharmony_ci 2062306a36Sopenharmony_ciMessage enums 2162306a36Sopenharmony_ci------------- 2262306a36Sopenharmony_ci 2362306a36Sopenharmony_ciUse the same command IDs for requests and replies. This makes it easier 2462306a36Sopenharmony_cito match them up, and we have plenty of ID space. 2562306a36Sopenharmony_ci 2662306a36Sopenharmony_ciUse separate command IDs for notifications. This makes it easier to 2762306a36Sopenharmony_cisort the notifications from replies (and present them to the user 2862306a36Sopenharmony_ciapplication via a different API than replies). 2962306a36Sopenharmony_ci 3062306a36Sopenharmony_ciAnswer requests 3162306a36Sopenharmony_ci--------------- 3262306a36Sopenharmony_ci 3362306a36Sopenharmony_ciOlder families do not reply to all of the commands, especially NEW / ADD 3462306a36Sopenharmony_cicommands. User only gets information whether the operation succeeded or 3562306a36Sopenharmony_cinot via the ACK. Try to find useful data to return. Once the command is 3662306a36Sopenharmony_ciadded whether it replies with a full message or only an ACK is uAPI and 3762306a36Sopenharmony_cicannot be changed. It's better to err on the side of replying. 3862306a36Sopenharmony_ci 3962306a36Sopenharmony_ciSpecifically NEW and ADD commands should reply with information identifying 4062306a36Sopenharmony_cithe created object such as the allocated object's ID (without having to 4162306a36Sopenharmony_ciresort to using ``NLM_F_ECHO``). 4262306a36Sopenharmony_ci 4362306a36Sopenharmony_ciNLM_F_ECHO 4462306a36Sopenharmony_ci---------- 4562306a36Sopenharmony_ci 4662306a36Sopenharmony_ciMake sure to pass the request info to genl_notify() to allow ``NLM_F_ECHO`` 4762306a36Sopenharmony_cito take effect. This is useful for programs that need precise feedback 4862306a36Sopenharmony_cifrom the kernel (for example for logging purposes). 4962306a36Sopenharmony_ci 5062306a36Sopenharmony_ciSupport dump consistency 5162306a36Sopenharmony_ci------------------------ 5262306a36Sopenharmony_ci 5362306a36Sopenharmony_ciIf iterating over objects during dump may skip over objects or repeat 5462306a36Sopenharmony_cithem - make sure to report dump inconsistency with ``NLM_F_DUMP_INTR``. 5562306a36Sopenharmony_ciThis is usually implemented by maintaining a generation id for the 5662306a36Sopenharmony_cistructure and recording it in the ``seq`` member of struct netlink_callback. 5762306a36Sopenharmony_ci 5862306a36Sopenharmony_ciNetlink specification 5962306a36Sopenharmony_ci===================== 6062306a36Sopenharmony_ci 6162306a36Sopenharmony_ciDocumentation of the Netlink specification parts which are only relevant 6262306a36Sopenharmony_cito the kernel space. 6362306a36Sopenharmony_ci 6462306a36Sopenharmony_ciGlobals 6562306a36Sopenharmony_ci------- 6662306a36Sopenharmony_ci 6762306a36Sopenharmony_cikernel-policy 6862306a36Sopenharmony_ci~~~~~~~~~~~~~ 6962306a36Sopenharmony_ci 7062306a36Sopenharmony_ciDefines whether the kernel validation policy is ``global`` i.e. the same for all 7162306a36Sopenharmony_cioperations of the family, defined for each operation individually - ``per-op``, 7262306a36Sopenharmony_cior separately for each operation and operation type (do vs dump) - ``split``. 7362306a36Sopenharmony_ciNew families should use ``per-op`` (default) to be able to narrow down the 7462306a36Sopenharmony_ciattributes accepted by a specific command. 7562306a36Sopenharmony_ci 7662306a36Sopenharmony_cichecks 7762306a36Sopenharmony_ci------ 7862306a36Sopenharmony_ci 7962306a36Sopenharmony_ciDocumentation for the ``checks`` sub-sections of attribute specs. 8062306a36Sopenharmony_ci 8162306a36Sopenharmony_ciunterminated-ok 8262306a36Sopenharmony_ci~~~~~~~~~~~~~~~ 8362306a36Sopenharmony_ci 8462306a36Sopenharmony_ciAccept strings without the null-termination (for legacy families only). 8562306a36Sopenharmony_ciSwitches from the ``NLA_NUL_STRING`` to ``NLA_STRING`` policy type. 8662306a36Sopenharmony_ci 8762306a36Sopenharmony_cimax-len 8862306a36Sopenharmony_ci~~~~~~~ 8962306a36Sopenharmony_ci 9062306a36Sopenharmony_ciDefines max length for a binary or string attribute (corresponding 9162306a36Sopenharmony_cito the ``len`` member of struct nla_policy). For string attributes terminating 9262306a36Sopenharmony_cinull character is not counted towards ``max-len``. 9362306a36Sopenharmony_ci 9462306a36Sopenharmony_ciThe field may either be a literal integer value or a name of a defined 9562306a36Sopenharmony_ciconstant. String types may reduce the constant by one 9662306a36Sopenharmony_ci(i.e. specify ``max-len: CONST - 1``) to reserve space for the terminating 9762306a36Sopenharmony_cicharacter so implementations should recognize such pattern. 9862306a36Sopenharmony_ci 9962306a36Sopenharmony_cimin-len 10062306a36Sopenharmony_ci~~~~~~~ 10162306a36Sopenharmony_ci 10262306a36Sopenharmony_ciSimilar to ``max-len`` but defines minimum length. 103