YAML Netlink 프로토콜 명세

완전한 기계 판독 명세와 라이선스

Netlink protocol specification은 YAML로 작성한 완전한 기계 판독 가능 protocol 설명입니다. Netlink parsing을 사용자 공간 업무 로직과 분리하고 새 family, command, attribute마다 손으로 작성하는 Netlink 코드 양을 줄이는 것이 목표입니다.

명세는 다른 spec이나 C header에 의존하지 않고 자체 완결적이어야 합니다. 따라서 kernel header를 직접 include할 수 없는 언어에서도 쉽게 사용할 수 있습니다.

YAML 파일은 `Documentation/netlink/specs/`에 있습니다. 모든 명세는 사용자 공간 코드가 쉽게 채택할 수 있도록 `((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)`로 허가해야 합니다.

.. 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 level

Netlink 명세에는 새 family용 단순 schema부터 오래된 ABI의 모든 예외를 다루는 복잡한 schema까지 네 단계가 있습니다. 다음 단계는 이전 단계 속성을 상속하므로 복잡한 schema parser는 단순 schema도 읽을 수 있습니다.

C uAPI header와 직접 상호작용하지 않는 구현에서는 `genetlink-c`와 `genetlink`가 동등해야 합니다. 실제 JSON Schema 정의는 `Documentation/netlink/` 아래에 있습니다.

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/``.

YAML schema의 개념적 구성

대부분의 schema 속성은 정의한 객체를 설명하는 `doc` 하위 속성을 허용하거나 요구합니다. 이후 구간은 가장 현대적인 `genetlink` schema를 설명하며 C 이름 파생 규칙은 `c-code-gen`을 참조합니다.

kernel 공간에서만 의미 있고 사용자 공간 API에는 속하지 않는 명세 속성은 core API 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 전역 name과 protocol

root 수준 `name`은 family를 고유하게 식별합니다. Family ID는 runtime에 동적으로 할당되므로 안정적인 이름이 식별 기준입니다.

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.

constant, enum, flags definitions

`definitions`는 type과 constant definition의 배열입니다. 각 항목의 `name`이 type 또는 constant를 식별하고 `type`이 `const`, `enum`, `flags` 중 하나를 고릅니다.

`value-start`는 enum의 첫 값 또는 flags의 첫 bit 번호를 바꿉니다. flags에서는 shift된 값이 아니라 시작 bit를 지정합니다. sparse enumeration은 지원하지 않으며 `entries`가 enum·flags 항목 이름 배열입니다.

`header`는 C 호환 언어에서 해당 값을 이미 정의한 header를 가리킵니다. `IFNAMSIZ`처럼 여러 family가 공유하는 정의라면 generator가 같은 상수를 다시 만들기보다 적절한 include를 추가할 수 있습니다.

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 set과 fractional subset

`attribute-sets`는 family의 Netlink attribute 정보를 담는 배열이며 모든 family에 하나 이상, 대개 여러 set이 있습니다.

명세는 실제 message 중첩 모양을 시각적으로 복제하지 않고 평평하게 작성합니다. subordinate set을 container 안에 inline으로 쓰지 않고 독립 set으로 정의한 뒤 container의 `nested-attributes`에서 참조합니다.

fractional set의 attribute `value`는 main set과 암묵적으로 같고 별도로 정의하지 않습니다. fractional set은 nest 안에서만 쓸 수 있으며 uAPI에는 어떤 형식으로도 렌더링되지 않습니다.

set의 `name`은 고유해야 하며 operation과 nested attribute가 이 이름으로 set을 참조합니다. `attributes`는 set 안의 attribute 목록입니다.

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 이름, type, value와 enum

attribute `name`은 set 안에서 고유하고 `type`은 지원되는 Netlink attribute 자료형을 고릅니다.

숫자 `value`는 직렬화 message에서 쓰는 attribute ID입니다. 생략하면 앞 attribute 값에 1을 더하고 첫 attribute는 1이 됩니다. definitions의 enum이 0부터 시작하는 것과 달리 attribute와 operation은 0을 undefined로 예약하는 관례 때문에 1부터 시작합니다. 필요한 경우 0을 명시할 수 있습니다.

정수 attribute의 `enum`은 `definitions`의 enum 또는 flags 이름을 연결합니다. `enum-as-flags`는 definition이 enum이어도 이 attribute에서 bit flags로 해석합니다. 두 표현이 모두 필요하면 definition은 enum 하나만 두고 flags가 필요한 attribute에 이 속성을 사용합니다.

`nested-attributes`는 복합 attribute 내부의 attribute space를 식별합니다. `multi-attr`은 같은 attribute가 여러 번 나타날 수 있음을 뜻하며 추가 nest 없이 반복 attribute로 배열을 구현하는 권장 방식입니다.

.. _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, checks, sub-type과 display

실행 중 kernel의 실제 validation policy는 Generic Netlink introspection으로 조회해야 하며 명세 파일의 `checks`에만 의존해서는 안 됩니다. kernel policy는 `type`, `nested-attributes`, `checks`를 결합해 형성됩니다.

`sub-type`은 완전한 attribute space로 정의되지 않은 레거시 배열 member를 설명합니다. 예를 들어 `type: binary`, `sub-type: u32`는 C `u32` 배열입니다.

현재 display hint는 `hex`, `mac`, `fddi`, `ipv4`, `ipv6`, `uuid`를 지원하며 validation이 아니라 올바른 출력 형식을 선택하기 위한 정보입니다.

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``.

operation, notification과 event

`operations`는 kernel과 사용자 공간 사이 message를 설명하며 operation, notification, event 세 종류의 항목이 있습니다.

operation은 일반적인 request-response 통신입니다. 각 operation은 `do`와 `dump`를 원하는 조합으로 가질 수 있고, 각각 `request`와 `response` 속성을 조합합니다. filter를 받지 않는 dump나 Netlink error code만 답하는 SET처럼 한 방향에 attribute message가 없으면 해당 request 또는 response 구간을 생략할 수 있습니다.

request와 response의 attribute 목록은 `attribute-set`이 가리키는 set의 이름들만 나열합니다.

`operations.list`가 genetlink operation, notification, event의 전체 목록을 담습니다.

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 세부 속성

`notify`가 가리키는 operation은 자기 자신일 수도 있으며 내용은 해당 operation의 `do`와 공유합니다. `event`와 `notify`는 동시에 지정할 수 없습니다.

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.

message attribute list와 multicast group

`request`, `reply`, `event`에는 attribute 이름 목록을 담는 단일 `attributes` 속성이 있습니다.

message는 kernel에서 `pre_doit`, `post_doit` 호출로 렌더링되는 `pre`, `post` 속성도 정의할 수 있지만 사용자 공간은 이를 무시해야 합니다.

`mcast-groups.list`는 family의 multicast group 목록입니다. 각 group의 `name`은 family 안에서 고유하며 Family ID처럼 multicast Group ID도 이 이름을 기준으로 runtime에 조회해야 합니다.

.. _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.

공통·고정 폭 정수 type

`sint`와 `uint`는 signed·unsigned 64비트 정수를 나타냅니다. 값이 32비트에 들어가면 message에는 32비트만 싣고, 그렇지 않으면 64비트 전체를 싣습니다. payload 정렬은 4바이트뿐이므로 64비트 값이 정렬되지 않을 수 있습니다.

대부분의 경우 고정 폭 type보다 공통 정수 type을 선호해야 합니다.

`byte-order`가 없으면 정수 payload는 host order입니다. kernel은 대개 64비트 값을 정렬하지만 사용자 공간은 unaligned value도 안전하게 처리하는 것이 권장됩니다.

.. _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, flag, binary, string과 nest

attribute set에는 `pad` type을 하나만 둘 수 있고 필요할 때 자동으로 사용해야 합니다. 예를 들어 표준 4바이트보다 큰 정렬이 필요한 64비트 attribute 앞을 맞춥니다.

string은 `checks.unterminated-ok: true`가 아니면 null 종료되어야 합니다. `checks.max-len`은 가능한 가장 긴 문자열 길이이며 없으면 길이 제한이 없습니다. `max-len`에는 종료 문자를 세지 않습니다.

.. _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.