raw Netlink family 명세 지원

netlink-raw compatibility level

이 문서는 `NETLINK_ROUTE`처럼 `netlink-raw` protocol specification을 사용하는 raw Netlink family에 필요한 추가 속성을 설명합니다.

`netlink-raw` schema는 `genetlink-legacy` schema를 확장하여 raw family의 protocol 번호와 multicast ID를 표현합니다. 또한 raw family가 사용하는 type별 sub-message 형식을 추가로 지원합니다.

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

======================================================
Netlink specification support for raw Netlink families
======================================================

This document describes the additional properties required by raw Netlink
families such as ``NETLINK_ROUTE`` which use the ``netlink-raw`` protocol
specification.

Specification
=============

The netlink-raw schema extends the :doc:`genetlink-legacy <genetlink-legacy>`
schema with properties that are needed to specify the protocol numbers and
multicast IDs used by raw netlink families. See :ref:`classic_netlink` for more
information. The raw netlink families also make use of type-specific
sub-messages.

protonum과 multicast group value

전역 `protonum`은 Netlink socket을 열 때 사용할 protocol 번호입니다. 예제 `rt-addr` 명세는 `protocol: netlink-raw`와 `protonum: 0`을 지정하여 `NETLINK_ROUTE` protocol의 일부임을 나타냅니다.

multicast group의 `value`는 group 등록에 사용할 ID를 명시합니다. Generic Netlink의 동적 group ID와 달리 raw family 명세에는 실제 숫자가 들어갑니다.

Globals
-------

protonum
~~~~~~~~

The ``protonum`` property is used to specify the protocol number to use when
opening a netlink socket.

.. code-block:: yaml

  # SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)

  name: rt-addr
  protocol: netlink-raw
  protonum: 0             # part of the NETLINK_ROUTE protocol


Multicast group properties
--------------------------

value
~~~~~

The ``value`` property is used to specify the group ID to use for multicast
group registration.

.. code-block:: yaml

  mcast-groups:
    list:
      -
        name: rtnlgrp-ipv4-ifaddr
        value: 5
      -
        name: rtnlgrp-ipv6-ifaddr
        value: 9
      -
        name: rtnlgrp-mctp-ifaddr
        value: 34

wrapper attribute와 sub-message selector

`rt-link`와 traffic control 같은 raw family는 module별 정보를 운반하기 위해 attribute nesting을 추상화로 사용합니다. 바깥 message나 nest에는 core가 정의한 일반 attribute가 있고, wrapper attribute 안에는 driver, classifier, qdisc 등이 정의한 module별 payload가 들어갑니다.

module은 wrapper 내부 형식을 자유롭게 정할 수 있습니다. 고정 header나 Netlink attribute 또는 둘 모두를 포함할 수 있어 일반 Netlink message와 성질이 비슷하므로 이 wrapper payload를 sub-message라고 부릅니다.

Sub-messages
------------

Several raw netlink families such as
:ref:`rt-link<netlink-rt-link>` and
:ref:`tc<netlink-tc>` use attribute nesting as an
abstraction to carry module specific information.

Conceptually it looks as follows::

    [OUTER NEST OR MESSAGE LEVEL]
      [GENERIC ATTR 1]
      [GENERIC ATTR 2]
      [GENERIC ATTR 3]
      [GENERIC ATTR - wrapper]
        [MODULE SPECIFIC ATTR 1]
        [MODULE SPECIFIC ATTR 2]

The ``GENERIC ATTRs`` at the outer level are defined in the core (or rt_link or
core TC), while specific drivers, TC classifiers, qdiscs etc. can carry their
own information wrapped in the ``GENERIC ATTR - wrapper``. Even though the
example above shows attributes nesting inside the wrapper, the modules generally
have full freedom to define the format of the nest. In practice the payload of
the wrapper attr has very similar characteristics to a netlink message. It may
contain a fixed header / structure, netlink attributes, or both. Because of
those shared characteristics we refer to the payload of the wrapper attribute as
a sub-message.

A sub-message attribute uses the value of another attribute as a selector key to
choose the right sub-message format. For example if the following attribute has
already been decoded:

.. code-block:: json

  { "kind": "gre" }

and we encounter the following attribute spec:

.. code-block:: yaml

  -
    name: data
    type: sub-message
    sub-message: linkinfo-data-msg
    selector: kind

Then we look for a sub-message definition called ``linkinfo-data-msg`` and use
the value of the ``kind`` attribute i.e. ``gre`` as the key to choose the
correct format for the sub-message:

.. code-block:: yaml

  sub-messages:
    name: linkinfo-data-msg
    formats:
      -
        value: bridge
        attribute-set: linkinfo-bridge-attrs
      -
        value: gre
        attribute-set: linkinfo-gre-attrs
      -
        value: geneve
        attribute-set: linkinfo-geneve-attrs

This would decode the attribute value as a sub-message with the attribute-set
called ``linkinfo-gre-attrs`` as the attribute space.

fixed-header 조합과 selector scope

sub-message는 선택적인 `fixed-header` 뒤에 `attribute-set`의 attribute 0개 이상을 둘 수 있습니다. `tc-options-msg` 예제의 `bfifo`는 고정 header만, `cake`는 attribute set만, `netem`은 둘 모두를 사용합니다.

selector attribute는 이를 참조하는 sub-message attribute보다 Netlink message 안에서 먼저 나와야 합니다.

`kind`처럼 같은 이름의 attribute가 여러 nest 수준에 있으면 selector와 가장 가까운 값, 즉 명세상 selector와 같은 수준의 값을 사용합니다. 그 수준의 실제 message에 값이 없으면 바깥 값으로 대체하지 않고 오류입니다.

A sub-message can have an optional ``fixed-header`` followed by zero or more
attributes from an ``attribute-set``. For example the following
``tc-options-msg`` sub-message defines message formats that use a mixture of
``fixed-header``, ``attribute-set`` or both together:

.. code-block:: yaml

  sub-messages:
    -
      name: tc-options-msg
      formats:
        -
          value: bfifo
          fixed-header: tc-fifo-qopt
        -
          value: cake
          attribute-set: tc-cake-attrs
        -
          value: netem
          fixed-header: tc-netem-qopt
          attribute-set: tc-netem-attrs

Note that a selector attribute must appear in a netlink message before any
sub-message attributes that depend on it.

If an attribute such as ``kind`` is defined at more than one nest level, then a
sub-message selector will be resolved using the value 'closest' to the selector.
For example, if the same attribute name is defined in a nested ``attribute-set``
alongside a sub-message selector and also in a top level ``attribute-set``, then
the selector will be resolved using the value 'closest' to the selector. If the
value is not present in the message at the same level as defined in the spec
then this is an error.

중첩 구조체 정의

traffic control 등 많은 raw family는 구조체 안에 다른 구조체를 포함합니다. `netlink-raw` schema에서는 binary member의 `struct` 속성으로 다른 struct definition을 내장할 수 있습니다.

이 방식은 wire 구조를 평평한 byte array로 취급하지 않고, 재사용 가능한 구조체 definition의 조합으로 정확히 표현합니다.

Nested struct definitions
-------------------------

Many raw netlink families such as :ref:`tc<netlink-tc>`
make use of nested struct definitions. The ``netlink-raw`` schema makes it
possible to embed a struct within a struct definition using the ``struct``
property. For example, the following struct definition embeds the
``tc-ratespec`` struct definition for both the ``rate`` and the ``peakrate``
members of ``struct tc-tbf-qopt``.

.. code-block:: yaml

  -
    name: tc-tbf-qopt
    type: struct
    members:
      -
        name: rate
        type: binary
        struct: tc-ratespec
      -
        name: peakrate
        type: binary
        struct: tc-ratespec
      -
        name: limit
        type: u32
      -
        name: buffer
        type: u32
      -
        name: mtu
        type: u32