Documentation/userspace-api/netlink/genetlink-legacy.rst - linux - Git at Google

 .. SPDX-License-Identifier: BSD-3-Clause

 =================================================================
 Netlink specification support for legacy Generic Netlink families
 =================================================================

 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)
 =======================

 Attribute type nests
 --------------------

 New Netlink families should use ``multi-attr`` to define arrays.
 Older families (e.g. ``genetlink`` control family) attempted to
 define array types reusing attribute type to carry information.

 For reference the ``multi-attr`` array may look like this::

   [ARRAY-ATTR]
     [INDEX (optionally)]
     [MEMBER1]
     [MEMBER2]
   [SOME-OTHER-ATTR]
   [ARRAY-ATTR]
     [INDEX (optionally)]
     [MEMBER1]
     [MEMBER2]

 where ``ARRAY-ATTR`` is the array entry type.

 array-nest
 ~~~~~~~~~~

 ``array-nest`` creates the following structure::

   [SOME-OTHER-ATTR]
   [ARRAY-ATTR]
     [ENTRY]
       [MEMBER1]
       [MEMBER2]
     [ENTRY]
       [MEMBER1]
       [MEMBER2]

 It wraps the entire array in an extra attribute (hence limiting its size
 to 64kB). The ``ENTRY`` nests are special and have the index of the entry
 as their type instead of normal attribute type.

 type-value
 ~~~~~~~~~~

 ``type-value`` is a construct which uses attribute types to carry
 information about a single object (often used when array is dumped
 entry-by-entry).

 ``type-value`` can have multiple levels of nesting, for example
 genetlink's policy dumps create the following structures::

   [POLICY-IDX]
     [ATTR-IDX]
       [POLICY-INFO-ATTR1]
       [POLICY-INFO-ATTR2]

 Where the first level of nest has the policy index as it's attribute
 type, it contains a single nest which has the attribute index as its
 type. Inside the attr-index nest are the policy attributes. Modern
 Netlink families should have instead defined this as a flat structure,
 the nesting serves no good purpose here.

 Operations
 ==========

 Enum (message ID) model
 -----------------------

 unified
 ~~~~~~~

 Modern families use the ``unified`` message ID model, which uses
 a single enumeration for all messages within family. Requests and
 responses share the same message ID. Notifications have separate
 IDs from the same space. For example given the following list
 of operations:

 .. code-block:: yaml

   -
     name: a
     value: 1
     do: ...
   -
     name: b
     do: ...
   -
     name: c
     value: 4
     notify: a
   -
     name: d
     do: ...

 Requests and responses for operation ``a`` will have the ID of 1,
 the requests and responses of ``b`` - 2 (since there is no explicit
 ``value`` it's previous operation ``+ 1``). Notification ``c`` will
 use the ID of 4, operation ``d`` 5 etc.

 directional
 ~~~~~~~~~~~

 The ``directional`` model splits the ID assignment by the direction of
 the message. Messages from and to the kernel can't be confused with
 each other so this conserves the ID space (at the cost of making
 the programming more cumbersome).

 In this case ``value`` attribute should be specified in the ``request``
 ``reply`` sections of the operations (if an operation has both ``do``
 and ``dump`` the IDs are shared, ``value`` should be set in ``do``).
 For notifications the ``value`` is provided at the op level but it
 only allocates a ``reply`` (i.e. a "from-kernel" ID). Let's look
 at an example:

 .. code-block:: yaml

   -
     name: a
     do:
       request:
         value: 2
         attributes: ...
       reply:
         value: 1
         attributes: ...
   -
     name: b
     notify: a
   -
     name: c
     notify: a
     value: 7
   -
     name: d
     do: ...

 In this case ``a`` will use 2 when sending the message to the kernel
 and expects message with ID 1 in response. Notification ``b`` allocates
 a "from-kernel" ID which is 2. ``c`` allocates "from-kernel" ID of 7.
 If operation ``d`` does not set ``values`` explicitly in the spec
 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)
 ===================

 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
 conventions. For example, the following struct is 4 bytes, not 6 bytes:

 .. code-block:: c

   struct {
           u8 a;
           u16 b;
           u8 c;
   }

 Any padding must be explicitly added and C-like languages should infer the
 need for explicit padding from whether the members are naturally aligned.

 Here is the struct definition from above, declared in YAML:

 .. code-block:: yaml

   definitions:
     -
       name: message-header
       type: struct
       members:
         -
           name: a
           type: u8
         -
           name: b
           type: u16
         -
           name: c
           type: u8

 Fixed Headers
 ~~~~~~~~~~~~~

 Fixed message headers can be added to operations using ``fixed-header``.
 The default ``fixed-header`` can be set in ``operations`` and it can be set
 or overridden for each operation.

 .. code-block:: yaml

   operations:
     fixed-header: message-header
     list:
       -
         name: get
         fixed-header: custom-header
         attribute-set: message-attrs

 Attributes
 ~~~~~~~~~~

 A ``binary`` attribute can be interpreted as a C structure using a
 ``struct`` property with the name of the structure definition. The
 ``struct`` property implies ``sub-type: struct`` so it is not necessary to
 specify a sub-type.

 .. code-block:: yaml

   attribute-sets:
     -
       name: stats-attrs
       attributes:
         -
           name: stats
           type: binary
           struct: vport-stats

 C Arrays
 --------

 Legacy families also use ``binary`` attributes to encapsulate C arrays. The
 ``sub-type`` is used to identify the type of scalar to extract.

 .. code-block:: yaml

   attributes:
     -
       name: ports
       type: binary
       sub-type: u32

 Multi-message DO
 ----------------

 New Netlink families should never respond to a DO operation with multiple
 replies, with ``NLM_F_MULTI`` set. Use a filtered dump instead.

 At the spec level we can define a ``dumps`` property for the ``do``,
 perhaps with values of ``combine`` and ``multi-object`` depending
 on how the parsing should be implemented (parse into a single reply
 vs list of objects i.e. pretty much a dump).
	.. SPDX-License-Identifier: BSD-3-Clause

	=================================================================
	Netlink specification support for legacy Generic Netlink families
	=================================================================

	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)
	=======================

	Attribute type nests
	--------------------

	New Netlink families should use ``multi-attr`` to define arrays.
	Older families (e.g. ``genetlink`` control family) attempted to
	define array types reusing attribute type to carry information.

	For reference the ``multi-attr`` array may look like this::

	[ARRAY-ATTR]
	[INDEX (optionally)]
	[MEMBER1]
	[MEMBER2]
	[SOME-OTHER-ATTR]
	[ARRAY-ATTR]
	[INDEX (optionally)]
	[MEMBER1]
	[MEMBER2]

	where ``ARRAY-ATTR`` is the array entry type.

	array-nest
	~~~~~~~~~~

	``array-nest`` creates the following structure::

	[SOME-OTHER-ATTR]
	[ARRAY-ATTR]
	[ENTRY]
	[MEMBER1]
	[MEMBER2]
	[ENTRY]
	[MEMBER1]
	[MEMBER2]

	It wraps the entire array in an extra attribute (hence limiting its size
	to 64kB). The ``ENTRY`` nests are special and have the index of the entry
	as their type instead of normal attribute type.

	type-value
	~~~~~~~~~~

	``type-value`` is a construct which uses attribute types to carry
	information about a single object (often used when array is dumped
	entry-by-entry).

	``type-value`` can have multiple levels of nesting, for example
	genetlink's policy dumps create the following structures::

	[POLICY-IDX]
	[ATTR-IDX]
	[POLICY-INFO-ATTR1]
	[POLICY-INFO-ATTR2]

	Where the first level of nest has the policy index as it's attribute
	type, it contains a single nest which has the attribute index as its
	type. Inside the attr-index nest are the policy attributes. Modern
	Netlink families should have instead defined this as a flat structure,
	the nesting serves no good purpose here.

	Operations
	==========

	Enum (message ID) model
	-----------------------

	unified
	~~~~~~~

	Modern families use the ``unified`` message ID model, which uses
	a single enumeration for all messages within family. Requests and
	responses share the same message ID. Notifications have separate
	IDs from the same space. For example given the following list
	of operations:

	.. code-block:: yaml

	-
	name: a
	value: 1
	do: ...
	-
	name: b
	do: ...
	-
	name: c
	value: 4
	notify: a
	-
	name: d
	do: ...

	Requests and responses for operation ``a`` will have the ID of 1,
	the requests and responses of ``b`` - 2 (since there is no explicit
	``value`` it's previous operation ``+ 1``). Notification ``c`` will
	use the ID of 4, operation ``d`` 5 etc.

	directional
	~~~~~~~~~~~

	The ``directional`` model splits the ID assignment by the direction of
	the message. Messages from and to the kernel can't be confused with
	each other so this conserves the ID space (at the cost of making
	the programming more cumbersome).

	In this case ``value`` attribute should be specified in the ``request``
	``reply`` sections of the operations (if an operation has both ``do``
	and ``dump`` the IDs are shared, ``value`` should be set in ``do``).
	For notifications the ``value`` is provided at the op level but it
	only allocates a ``reply`` (i.e. a "from-kernel" ID). Let's look
	at an example:

	.. code-block:: yaml

	-
	name: a
	do:
	request:
	value: 2
	attributes: ...
	reply:
	value: 1
	attributes: ...
	-
	name: b
	notify: a
	-
	name: c
	notify: a
	value: 7
	-
	name: d
	do: ...

	In this case ``a`` will use 2 when sending the message to the kernel
	and expects message with ID 1 in response. Notification ``b`` allocates
	a "from-kernel" ID which is 2. ``c`` allocates "from-kernel" ID of 7.
	If operation ``d`` does not set ``values`` explicitly in the spec
	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)
	===================

	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
	conventions. For example, the following struct is 4 bytes, not 6 bytes:

	.. code-block:: c

	struct {
	u8 a;
	u16 b;
	u8 c;
	}

	Any padding must be explicitly added and C-like languages should infer the
	need for explicit padding from whether the members are naturally aligned.

	Here is the struct definition from above, declared in YAML:

	.. code-block:: yaml

	definitions:
	-
	name: message-header
	type: struct
	members:
	-
	name: a
	type: u8
	-
	name: b
	type: u16
	-
	name: c
	type: u8

	Fixed Headers
	~~~~~~~~~~~~~

	Fixed message headers can be added to operations using ``fixed-header``.
	The default ``fixed-header`` can be set in ``operations`` and it can be set
	or overridden for each operation.

	.. code-block:: yaml

	operations:
	fixed-header: message-header
	list:
	-
	name: get
	fixed-header: custom-header
	attribute-set: message-attrs

	Attributes
	~~~~~~~~~~

	A ``binary`` attribute can be interpreted as a C structure using a
	``struct`` property with the name of the structure definition. The
	``struct`` property implies ``sub-type: struct`` so it is not necessary to
	specify a sub-type.

	.. code-block:: yaml

	attribute-sets:
	-
	name: stats-attrs
	attributes:
	-
	name: stats
	type: binary
	struct: vport-stats

	C Arrays
	--------

	Legacy families also use ``binary`` attributes to encapsulate C arrays. The
	``sub-type`` is used to identify the type of scalar to extract.

	.. code-block:: yaml

	attributes:
	-
	name: ports
	type: binary
	sub-type: u32

	Multi-message DO
	----------------

	New Netlink families should never respond to a DO operation with multiple
	replies, with ``NLM_F_MULTI`` set. Use a filtered dump instead.

	At the spec level we can define a ``dumps`` property for the ``do``,
	perhaps with values of ``combine`` and ``multi-object`` depending
	on how the parsing should be implemented (parse into a single reply
	vs list of objects i.e. pretty much a dump).