Commit 294f37fc authored by Donald Hunter's avatar Donald Hunter Committed by Jakub Kicinski
Browse files

doc/netlink: Update genetlink-legacy documentation 



Add documentation for recently added genetlink-legacy schema attributes.
Remove statements about 'work in progress' and 'todo'.

Signed-off-by: default avatarDonald Hunter <donald.hunter@gmail.com>
Reviewed-by: default avatarJacob Keller <jacob.e.keller@intel.com>
Link: https://lore.kernel.org/r/20230825122756.7603-4-donald.hunter@gmail.com


Signed-off-by: default avatarJakub Kicinski <kuba@kernel.org>
parent ed68c58c

Documentation/core-api/netlink.rst

+5 −4
Original line number Diff line number Diff line
@@ -67,10 +67,11 @@ Globals 
kernel-policy

~~~~~~~~~~~~~



Defines if the kernel validation policy is per operation (``per-op``)

or for the entire family (``global``). New families should use ``per-op``

(default) to be able to narrow down the attributes accepted by a specific

command.

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/userspace-api/netlink/genetlink-legacy.rst

+17 −9
Original line number Diff line number Diff line
@@ -8,11 +8,8 @@ This document describes the many additional quirks and properties 
required to describe older Generic Netlink families which form

the ``genetlink-legacy`` protocol level.



The spec is a work in progress, some of the quirks are just documented

for future reference.



Specification (defined)

=======================

Specification

=============



Attribute type nests

--------------------
@@ -156,16 +153,27 @@ it will be allocated 3 for the request (``a`` is the previous operation 
with a request section and the value of 2) and 8 for response (``c`` is

the previous operation in the "from-kernel" direction).



Other quirks (todo)

===================

Other quirks

============



Structures

----------



Legacy families can define C structures both to be used as the contents of

an attribute and as a fixed message header. Structures are defined in

``definitions``  and referenced in operations or attributes. Note that

structures defined in YAML are implicitly packed according to C

``definitions``  and referenced in operations or attributes.



members

~~~~~~~



 - ``name`` - The attribute name of the struct member

 - ``type`` - One of the scalar types ``u8``, ``u16``, ``u32``, ``u64``, ``s8``,

   ``s16``, ``s32``, ``s64``, ``string`` or ``binary``.

 - ``byte-order`` - ``big-endian`` or ``little-endian``

 - ``doc``, ``enum``, ``enum-as-flags``, ``display-hint`` - Same as for

   :ref:`attribute definitions <attribute_properties>`



Note that structures defined in YAML are implicitly packed according to C

conventions. For example, the following struct is 4 bytes, not 6 bytes:



.. code-block:: c

Documentation/userspace-api/netlink/specs.rst

+13 −0
Original line number Diff line number Diff line
@@ -68,6 +68,10 @@ The following sections describe the properties of the most modern ``genetlink`` 
schema. See the documentation of :doc:`genetlink-c <c-code-gen>`

for information on how C names are derived from name properties.



See also :ref:`Documentation/core-api/netlink.rst <kernel_netlink>` for

information on the Netlink specification properties that are only relevant to

the kernel space and not part of the user space API.



genetlink

=========
@@ -180,6 +184,8 @@ attributes 


List of attributes in the set.



.. _attribute_properties:



Attribute properties

--------------------
@@ -264,6 +270,13 @@ a C array of u32 values can be specified with ``type: binary`` and 
``sub-type: u32``. Binary types and legacy array formats are described in

more detail in :doc:`genetlink-legacy`.



display-hint

~~~~~~~~~~~~



Optional format indicator that is intended only for choosing the right

formatting mechanism when displaying values of this type. Currently supported

hints are ``hex``, ``mac``, ``fddi``, ``ipv4``, ``ipv6`` and ``uuid``.



operations

----------