468 lines
14 KiB
ReStructuredText
468 lines
14 KiB
ReStructuredText
.. SPDX-License-Identifier: BSD-3-Clause
|
|
|
|
=========================================
|
|
Netlink protocol specifications (in YAML)
|
|
=========================================
|
|
|
|
Netlink protocol specifications are complete, machine readable descriptions of
|
|
Netlink protocols written in YAML. The goal of the specifications is to allow
|
|
separating Netlink parsing from user space logic and minimize the amount of
|
|
hand written Netlink code for each new family, command, attribute.
|
|
Netlink specs should be complete and not depend on any other spec
|
|
or C header file, making it easy to use in languages which can't include
|
|
kernel headers directly.
|
|
|
|
Internally kernel uses the YAML specs to generate:
|
|
|
|
- the C uAPI header
|
|
- documentation of the protocol as a ReST file - see :ref:`Documentation/networking/netlink_spec/index.rst <specs>`
|
|
- policy tables for input attribute validation
|
|
- operation tables
|
|
|
|
YAML specifications can be found under ``Documentation/netlink/specs/``
|
|
|
|
This document describes details of the schema.
|
|
See :doc:`intro-specs` for a practical starting guide.
|
|
|
|
All specs must be licensed under
|
|
``((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)``
|
|
to allow for easy adoption in user space code.
|
|
|
|
Compatibility levels
|
|
====================
|
|
|
|
There are four schema levels for Netlink specs, from the simplest used
|
|
by new families to the most complex covering all the quirks of the old ones.
|
|
Each next level inherits the attributes of the previous level, meaning that
|
|
user capable of parsing more complex ``genetlink`` schemas is also compatible
|
|
with simpler ones. The levels are:
|
|
|
|
- ``genetlink`` - most streamlined, should be used by all new families
|
|
- ``genetlink-c`` - superset of ``genetlink`` with extra attributes allowing
|
|
customization of define and enum type and value names; this schema should
|
|
be equivalent to ``genetlink`` for all implementations which don't interact
|
|
directly with C uAPI headers
|
|
- ``genetlink-legacy`` - Generic Netlink catch all schema supporting quirks of
|
|
all old genetlink families, strange attribute formats, binary structures etc.
|
|
- ``netlink-raw`` - catch all schema supporting pre-Generic Netlink protocols
|
|
such as ``NETLINK_ROUTE``
|
|
|
|
The definition of the schemas (in ``jsonschema``) can be found
|
|
under ``Documentation/netlink/``.
|
|
|
|
Schema structure
|
|
================
|
|
|
|
YAML schema has the following conceptual sections:
|
|
|
|
- globals
|
|
- definitions
|
|
- attributes
|
|
- operations
|
|
- multicast groups
|
|
|
|
Most properties in the schema accept (or in fact require) a ``doc``
|
|
sub-property documenting the defined object.
|
|
|
|
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
|
|
=========
|
|
|
|
Globals
|
|
-------
|
|
|
|
Attributes listed directly at the root level of the spec file.
|
|
|
|
name
|
|
~~~~
|
|
|
|
Name of the family. Name identifies the family in a unique way, since
|
|
the Family IDs are allocated dynamically.
|
|
|
|
protocol
|
|
~~~~~~~~
|
|
|
|
The schema level, default is ``genetlink``, which is the only value
|
|
allowed for new ``genetlink`` families.
|
|
|
|
definitions
|
|
-----------
|
|
|
|
Array of type and constant definitions.
|
|
|
|
name
|
|
~~~~
|
|
|
|
Name of the type / constant.
|
|
|
|
type
|
|
~~~~
|
|
|
|
One of the following types:
|
|
|
|
- const - a single, standalone constant
|
|
- enum - defines an integer enumeration, with values for each entry
|
|
incrementing by 1, (e.g. 0, 1, 2, 3)
|
|
- flags - defines an integer enumeration, with values for each entry
|
|
occupying a bit, starting from bit 0, (e.g. 1, 2, 4, 8)
|
|
|
|
value
|
|
~~~~~
|
|
|
|
The value for the ``const``.
|
|
|
|
value-start
|
|
~~~~~~~~~~~
|
|
|
|
The first value for ``enum`` and ``flags``, allows overriding the default
|
|
start value of ``0`` (for ``enum``) and starting bit (for ``flags``).
|
|
For ``flags`` ``value-start`` selects the starting bit, not the shifted value.
|
|
|
|
Sparse enumerations are not supported.
|
|
|
|
entries
|
|
~~~~~~~
|
|
|
|
Array of names of the entries for ``enum`` and ``flags``.
|
|
|
|
header
|
|
~~~~~~
|
|
|
|
For C-compatible languages, header which already defines this value.
|
|
In case the definition is shared by multiple families (e.g. ``IFNAMSIZ``)
|
|
code generators for C-compatible languages may prefer to add an appropriate
|
|
include instead of rendering a new definition.
|
|
|
|
attribute-sets
|
|
--------------
|
|
|
|
This property contains information about netlink attributes of the family.
|
|
All families have at least one attribute set, most have multiple.
|
|
``attribute-sets`` is an array, with each entry describing a single set.
|
|
|
|
Note that the spec is "flattened" and is not meant to visually resemble
|
|
the format of the netlink messages (unlike certain ad-hoc documentation
|
|
formats seen in kernel comments). In the spec subordinate attribute sets
|
|
are not defined inline as a nest, but defined in a separate attribute set
|
|
referred to with a ``nested-attributes`` property of the container.
|
|
|
|
Spec may also contain fractional sets - sets which contain a ``subset-of``
|
|
property. Such sets describe a section of a full set, allowing narrowing down
|
|
which attributes are allowed in a nest or refining the validation criteria.
|
|
Fractional sets can only be used in nests. They are not rendered to the uAPI
|
|
in any fashion.
|
|
|
|
name
|
|
~~~~
|
|
|
|
Uniquely identifies the attribute set, operations and nested attributes
|
|
refer to the sets by the ``name``.
|
|
|
|
subset-of
|
|
~~~~~~~~~
|
|
|
|
Re-defines a portion of another set (a fractional set).
|
|
Allows narrowing down fields and changing validation criteria
|
|
or even types of attributes depending on the nest in which they
|
|
are contained. The ``value`` of each attribute in the fractional
|
|
set is implicitly the same as in the main set.
|
|
|
|
attributes
|
|
~~~~~~~~~~
|
|
|
|
List of attributes in the set.
|
|
|
|
.. _attribute_properties:
|
|
|
|
Attribute properties
|
|
--------------------
|
|
|
|
name
|
|
~~~~
|
|
|
|
Identifies the attribute, unique within the set.
|
|
|
|
type
|
|
~~~~
|
|
|
|
Netlink attribute type, see :ref:`attr_types`.
|
|
|
|
.. _assign_val:
|
|
|
|
value
|
|
~~~~~
|
|
|
|
Numerical attribute ID, used in serialized Netlink messages.
|
|
The ``value`` property can be skipped, in which case the attribute ID
|
|
will be the value of the previous attribute plus one (recursively)
|
|
and ``1`` for the first attribute in the attribute set.
|
|
|
|
Attributes (and operations) use ``1`` as the default value for the first
|
|
entry (unlike enums in definitions which start from ``0``) because
|
|
entry ``0`` is almost always reserved as undefined. Spec can explicitly
|
|
set value to ``0`` if needed.
|
|
|
|
Note that the ``value`` of an attribute is defined only in its main set
|
|
(not in subsets).
|
|
|
|
enum
|
|
~~~~
|
|
|
|
For integer types specifies that values in the attribute belong
|
|
to an ``enum`` or ``flags`` from the ``definitions`` section.
|
|
|
|
enum-as-flags
|
|
~~~~~~~~~~~~~
|
|
|
|
Treat ``enum`` as ``flags`` regardless of its type in ``definitions``.
|
|
When both ``enum`` and ``flags`` forms are needed ``definitions`` should
|
|
contain an ``enum`` and attributes which need the ``flags`` form should
|
|
use this attribute.
|
|
|
|
nested-attributes
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
Identifies the attribute space for attributes nested within given attribute.
|
|
Only valid for complex attributes which may have sub-attributes.
|
|
|
|
multi-attr (arrays)
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
Boolean property signifying that the attribute may be present multiple times.
|
|
Allowing an attribute to repeat is the recommended way of implementing arrays
|
|
(no extra nesting).
|
|
|
|
byte-order
|
|
~~~~~~~~~~
|
|
|
|
For integer types specifies attribute byte order - ``little-endian``
|
|
or ``big-endian``.
|
|
|
|
checks
|
|
~~~~~~
|
|
|
|
Input validation constraints used by the kernel. User space should query
|
|
the policy of the running kernel using Generic Netlink introspection,
|
|
rather than depend on what is specified in the spec file.
|
|
|
|
The validation policy in the kernel is formed by combining the type
|
|
definition (``type`` and ``nested-attributes``) and the ``checks``.
|
|
|
|
sub-type
|
|
~~~~~~~~
|
|
|
|
Legacy families have special ways of expressing arrays. ``sub-type`` can be
|
|
used to define the type of array members in case array members are not
|
|
fully defined as attributes (in a bona fide attribute space). For instance
|
|
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
|
|
----------
|
|
|
|
This section describes messages passed between the kernel and the user space.
|
|
There are three types of entries in this section - operations, notifications
|
|
and events.
|
|
|
|
Operations describe the most common request - response communication. User
|
|
sends a request and kernel replies. Each operation may contain any combination
|
|
of the two modes familiar to netlink users - ``do`` and ``dump``.
|
|
``do`` and ``dump`` in turn contain a combination of ``request`` and
|
|
``response`` properties. If no explicit message with attributes is passed
|
|
in a given direction (e.g. a ``dump`` which does not accept filter, or a ``do``
|
|
of a SET operation to which the kernel responds with just the netlink error
|
|
code) ``request`` or ``response`` section can be skipped.
|
|
``request`` and ``response`` sections list the attributes allowed in a message.
|
|
The list contains only the names of attributes from a set referred
|
|
to by the ``attribute-set`` property.
|
|
|
|
Notifications and events both refer to the asynchronous messages sent by
|
|
the kernel to members of a multicast group. The difference between the
|
|
two is that a notification shares its contents with a GET operation
|
|
(the name of the GET operation is specified in the ``notify`` property).
|
|
This arrangement is commonly used for notifications about
|
|
objects where the notification carries the full object definition.
|
|
|
|
Events are more focused and carry only a subset of information rather than full
|
|
object state (a made up example would be a link state change event with just
|
|
the interface name and the new link state). Events contain the ``event``
|
|
property. Events are considered less idiomatic for netlink and notifications
|
|
should be preferred.
|
|
|
|
list
|
|
~~~~
|
|
|
|
The only property of ``operations`` for ``genetlink``, holds the list of
|
|
operations, notifications etc.
|
|
|
|
Operation properties
|
|
--------------------
|
|
|
|
name
|
|
~~~~
|
|
|
|
Identifies the operation.
|
|
|
|
value
|
|
~~~~~
|
|
|
|
Numerical message ID, used in serialized Netlink messages.
|
|
The same enumeration rules are applied as to
|
|
:ref:`attribute values<assign_val>`.
|
|
|
|
attribute-set
|
|
~~~~~~~~~~~~~
|
|
|
|
Specifies the attribute set contained within the message.
|
|
|
|
do
|
|
~~~
|
|
|
|
Specification for the ``doit`` request. Should contain ``request``, ``reply``
|
|
or both of these properties, each holding a :ref:`attr_list`.
|
|
|
|
dump
|
|
~~~~
|
|
|
|
Specification for the ``dumpit`` request. Should contain ``request``, ``reply``
|
|
or both of these properties, each holding a :ref:`attr_list`.
|
|
|
|
notify
|
|
~~~~~~
|
|
|
|
Designates the message as a notification. Contains the name of the operation
|
|
(possibly the same as the operation holding this property) which shares
|
|
the contents with the notification (``do``).
|
|
|
|
event
|
|
~~~~~
|
|
|
|
Specification of attributes in the event, holds a :ref:`attr_list`.
|
|
``event`` property is mutually exclusive with ``notify``.
|
|
|
|
mcgrp
|
|
~~~~~
|
|
|
|
Used with ``event`` and ``notify``, specifies which multicast group
|
|
message belongs to.
|
|
|
|
.. _attr_list:
|
|
|
|
Message attribute list
|
|
----------------------
|
|
|
|
``request``, ``reply`` and ``event`` properties have a single ``attributes``
|
|
property which holds the list of attribute names.
|
|
|
|
Messages can also define ``pre`` and ``post`` properties which will be rendered
|
|
as ``pre_doit`` and ``post_doit`` calls in the kernel (these properties should
|
|
be ignored by user space).
|
|
|
|
mcast-groups
|
|
------------
|
|
|
|
This section lists the multicast groups of the family.
|
|
|
|
list
|
|
~~~~
|
|
|
|
The only property of ``mcast-groups`` for ``genetlink``, holds the list
|
|
of groups.
|
|
|
|
Multicast group properties
|
|
--------------------------
|
|
|
|
name
|
|
~~~~
|
|
|
|
Uniquely identifies the multicast group in the family. Similarly to
|
|
Family ID, Multicast Group ID needs to be resolved at runtime, based
|
|
on the name.
|
|
|
|
.. _attr_types:
|
|
|
|
Attribute types
|
|
===============
|
|
|
|
This section describes the attribute types supported by the ``genetlink``
|
|
compatibility level. Refer to documentation of different levels for additional
|
|
attribute types.
|
|
|
|
Common integer types
|
|
--------------------
|
|
|
|
``sint`` and ``uint`` represent signed and unsigned 64 bit integers.
|
|
If the value can fit on 32 bits only 32 bits are carried in netlink
|
|
messages, otherwise full 64 bits are carried. Note that the payload
|
|
is only aligned to 4B, so the full 64 bit value may be unaligned!
|
|
|
|
Common integer types should be preferred over fix-width types in majority
|
|
of cases.
|
|
|
|
Fix-width integer types
|
|
-----------------------
|
|
|
|
Fixed-width integer types include:
|
|
``u8``, ``u16``, ``u32``, ``u64``, ``s8``, ``s16``, ``s32``, ``s64``.
|
|
|
|
Note that types smaller than 32 bit should be avoided as using them
|
|
does not save any memory in Netlink messages (due to alignment).
|
|
See :ref:`pad_type` for padding of 64 bit attributes.
|
|
|
|
The payload of the attribute is the integer in host order unless ``byte-order``
|
|
specifies otherwise.
|
|
|
|
64 bit values are usually aligned by the kernel but it is recommended
|
|
that the user space is able to deal with unaligned values.
|
|
|
|
.. _pad_type:
|
|
|
|
pad
|
|
---
|
|
|
|
Special attribute type used for padding attributes which require alignment
|
|
bigger than standard 4B alignment required by netlink (e.g. 64 bit integers).
|
|
There can only be a single attribute of the ``pad`` type in any attribute set
|
|
and it should be automatically used for padding when needed.
|
|
|
|
flag
|
|
----
|
|
|
|
Attribute with no payload, its presence is the entire information.
|
|
|
|
binary
|
|
------
|
|
|
|
Raw binary data attribute, the contents are opaque to generic code.
|
|
|
|
string
|
|
------
|
|
|
|
Character string. Unless ``checks`` has ``unterminated-ok`` set to ``true``
|
|
the string is required to be null terminated.
|
|
``max-len`` in ``checks`` indicates the longest possible string,
|
|
if not present the length of the string is unbounded.
|
|
|
|
Note that ``max-len`` does not count the terminating character.
|
|
|
|
nest
|
|
----
|
|
|
|
Attribute containing other (nested) attributes.
|
|
``nested-attributes`` specifies which attribute set is used inside.
|