Documentation/userspace-api/netlink/specs.rst

Source file repositories/reference/linux-study-clean/Documentation/userspace-api/netlink/specs.rst

File Facts

System
Linux kernel
Corpus path
Documentation/userspace-api/netlink/specs.rst
Extension
.rst
Size
14399 bytes
Lines
468
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. 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/netlink/specs/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.

Annotation

Implementation Notes