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: Donald Hunter <donald.hunter@gmail.com>
Reviewed-by: Jacob Keller <jacob.e.keller@intel.com>
Link: https://lore.kernel.org/r/20230825122756.7603-4-donald.hunter@gmail.com
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
This commit is contained in:
Donald Hunter 2023-08-25 13:27:46 +01:00 committed by Jakub Kicinski
parent ed68c58c0e
commit 294f37fc87
3 changed files with 35 additions and 13 deletions

View File

@ -67,10 +67,11 @@ Globals
kernel-policy kernel-policy
~~~~~~~~~~~~~ ~~~~~~~~~~~~~
Defines if the kernel validation policy is per operation (``per-op``) Defines whether the kernel validation policy is ``global`` i.e. the same for all
or for the entire family (``global``). New families should use ``per-op`` operations of the family, defined for each operation individually - ``per-op``,
(default) to be able to narrow down the attributes accepted by a specific or separately for each operation and operation type (do vs dump) - ``split``.
command. New families should use ``per-op`` (default) to be able to narrow down the
attributes accepted by a specific command.
checks checks
------ ------

View File

@ -8,11 +8,8 @@ This document describes the many additional quirks and properties
required to describe older Generic Netlink families which form required to describe older Generic Netlink families which form
the ``genetlink-legacy`` protocol level. the ``genetlink-legacy`` protocol level.
The spec is a work in progress, some of the quirks are just documented Specification
for future reference. =============
Specification (defined)
=======================
Attribute type nests 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 with a request section and the value of 2) and 8 for response (``c`` is
the previous operation in the "from-kernel" direction). the previous operation in the "from-kernel" direction).
Other quirks (todo) Other quirks
=================== ============
Structures Structures
---------- ----------
Legacy families can define C structures both to be used as the contents of 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 an attribute and as a fixed message header. Structures are defined in
``definitions`` and referenced in operations or attributes. Note that ``definitions`` and referenced in operations or attributes.
structures defined in YAML are implicitly packed according to C
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: conventions. For example, the following struct is 4 bytes, not 6 bytes:
.. code-block:: c .. code-block:: c

View File

@ -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>` schema. See the documentation of :doc:`genetlink-c <c-code-gen>`
for information on how C names are derived from name properties. 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 genetlink
========= =========
@ -180,6 +184,8 @@ attributes
List of attributes in the set. List of attributes in the set.
.. _attribute_properties:
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 ``sub-type: u32``. Binary types and legacy array formats are described in
more detail in :doc:`genetlink-legacy`. 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 operations
---------- ----------