* [PATCH net-next 0/6] Netlink protocol specs
@ 2022-09-29 1:11 Jakub Kicinski
2022-09-29 1:11 ` [PATCH net-next 1/6] docs: add more netlink docs (incl. spec docs) Jakub Kicinski
` (5 more replies)
0 siblings, 6 replies; 17+ messages in thread
From: Jakub Kicinski @ 2022-09-29 1:11 UTC (permalink / raw)
To: davem
Cc: netdev, edumazet, pabeni, robh, johannes, ecree.xilinx, stephen,
sdf, f.fainelli, fw, linux-doc, razor, nicolas.dichtel, gnault,
Jakub Kicinski
Hi!
I think the Netlink proto specs are far along enough to merge.
Filling in all attribute types and quirks will be an ongoing
effort but we have enough to cover FOU so it's somewhat complete.
I fully intend to continue polishing the code but at the same
time I'd like to start helping others base their work on the
specs (e.g. DPLL) and need to start working on some new families
myself.
That's the progress / motivation for merging. The RFC [1] has more
of a high level blurb, plus I created a lot of documentation, I'm
not going to repeat it here. There was also the talk at LPC [2].
[1] https://lore.kernel.org/all/20220811022304.583300-1-kuba@kernel.org/
[2] https://youtu.be/9QkXIQXkaQk?t=2562
Jakub Kicinski (6):
docs: add more netlink docs (incl. spec docs)
netlink: add schemas for YAML specs
net: add basic C code generators for Netlink
netlink: add a proto specification for FOU
net: fou: regenerate the uAPI from the spec
net: fou: use policy and operation tables generated from the spec
Documentation/core-api/index.rst | 1 +
Documentation/core-api/netlink.rst | 99 +
Documentation/netlink/genetlink-c.yaml | 287 +++
Documentation/netlink/genetlink-legacy.yaml | 313 +++
Documentation/netlink/genetlink.yaml | 252 +++
Documentation/netlink/specs/fou.yaml | 128 ++
.../userspace-api/netlink/c-code-gen.rst | 104 +
.../netlink/genetlink-legacy.rst | 96 +
Documentation/userspace-api/netlink/index.rst | 5 +
Documentation/userspace-api/netlink/specs.rst | 410 ++++
MAINTAINERS | 3 +
include/uapi/linux/fou.h | 54 +-
net/ipv4/Makefile | 2 +-
net/ipv4/fou-nl.c | 48 +
net/ipv4/fou-nl.h | 25 +
net/ipv4/fou.c | 51 +-
tools/net/ynl/ynl-gen-c.py | 1998 +++++++++++++++++
tools/net/ynl/ynl-regen.sh | 30 +
18 files changed, 3835 insertions(+), 71 deletions(-)
create mode 100644 Documentation/core-api/netlink.rst
create mode 100644 Documentation/netlink/genetlink-c.yaml
create mode 100644 Documentation/netlink/genetlink-legacy.yaml
create mode 100644 Documentation/netlink/genetlink.yaml
create mode 100644 Documentation/netlink/specs/fou.yaml
create mode 100644 Documentation/userspace-api/netlink/c-code-gen.rst
create mode 100644 Documentation/userspace-api/netlink/genetlink-legacy.rst
create mode 100644 Documentation/userspace-api/netlink/specs.rst
create mode 100644 net/ipv4/fou-nl.c
create mode 100644 net/ipv4/fou-nl.h
create mode 100755 tools/net/ynl/ynl-gen-c.py
create mode 100755 tools/net/ynl/ynl-regen.sh
--
2.37.3
^ permalink raw reply [flat|nested] 17+ messages in thread
* [PATCH net-next 1/6] docs: add more netlink docs (incl. spec docs)
2022-09-29 1:11 [PATCH net-next 0/6] Netlink protocol specs Jakub Kicinski
@ 2022-09-29 1:11 ` Jakub Kicinski
2022-09-29 8:15 ` Bagas Sanjaya
` (2 more replies)
2022-09-29 1:11 ` [PATCH net-next 2/6] netlink: add schemas for YAML specs Jakub Kicinski
` (4 subsequent siblings)
5 siblings, 3 replies; 17+ messages in thread
From: Jakub Kicinski @ 2022-09-29 1:11 UTC (permalink / raw)
To: davem
Cc: netdev, edumazet, pabeni, robh, johannes, ecree.xilinx, stephen,
sdf, f.fainelli, fw, linux-doc, razor, nicolas.dichtel, gnault,
Jakub Kicinski
Add documentation about the upcoming Netlink protocol specs.
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
---
Documentation/core-api/index.rst | 1 +
Documentation/core-api/netlink.rst | 99 +++++
.../userspace-api/netlink/c-code-gen.rst | 104 +++++
.../netlink/genetlink-legacy.rst | 96 ++++
Documentation/userspace-api/netlink/index.rst | 5 +
Documentation/userspace-api/netlink/specs.rst | 410 ++++++++++++++++++
MAINTAINERS | 2 +
7 files changed, 717 insertions(+)
create mode 100644 Documentation/core-api/netlink.rst
create mode 100644 Documentation/userspace-api/netlink/c-code-gen.rst
create mode 100644 Documentation/userspace-api/netlink/genetlink-legacy.rst
create mode 100644 Documentation/userspace-api/netlink/specs.rst
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index dc95df462eea..08d1d1da4077 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -122,6 +122,7 @@ Documents that don't fit elsewhere or which have yet to be categorized.
:maxdepth: 1
librs
+ netlink
.. only:: subproject and html
diff --git a/Documentation/core-api/netlink.rst b/Documentation/core-api/netlink.rst
new file mode 100644
index 000000000000..d0ec83df6b6b
--- /dev/null
+++ b/Documentation/core-api/netlink.rst
@@ -0,0 +1,99 @@
+.. SPDX-License-Identifier: BSD-3-Clause
+
+.. _kernel_netlink:
+
+===================================
+Netlink notes for kernel developers
+===================================
+
+General guidance
+================
+
+Attribute enums
+---------------
+
+Older families often define "null" attributes and commands with value
+of ``0`` and named ``unspec``. This is supported (``type: unspec``)
+but should be avoided in new families. The ``unspec`` enum values are
+not used in practice, so just set the value of the first attribute to ``1``.
+
+Message enums
+-------------
+
+Use the same command IDs for requests and replies. This makes it easier
+to match them up, and we have plenty ID space.
+
+Use separate command IDs for notifications. This makes it easier to
+sort the notifications from replies (and present them to the user
+application via a different API than replies).
+
+Answer requests
+---------------
+
+Older families do not reply to all of the commands, especially NEW / ADD
+commands. User only gets information whether the operation succeeded or
+not via the ACK. Try to find useful data to return. Once the command is
+added whether it replies with a full message or only an ACK is uAPI and
+cannot be changed. It's better to err on the side of replying.
+
+Specifically NEW and ADD commands should reply with information identifying
+the created object such as the allocated object's ID.
+
+Having to rely on ``NLM_F_ECHO`` is a hack, not a valid design.
+
+NLM_F_ECHO
+----------
+
+Make sure to pass the request info to genl_notify() to allow ``NLM_F_ECHO``
+to take effect.
+
+Support dump consistency
+------------------------
+
+If iterating over objects during dump may skip over objects or repeat
+them - make sure to report dump inconsistency with ``NLM_F_DUMP_INTR``.
+
+Netlink specification
+=====================
+
+Documentation of the Netlink specification parts which are only relevant
+to the kernel space.
+
+Globals
+-------
+
+kernel-policy
+~~~~~~~~~~~~~
+
+Defines if the kernel validation policy is per operation (``per-op``)
+or for the entire family (``global``). New families should use ``per-op``
+(default) to be able to narrow down the attributes accepted by a specific
+command.
+
+checks
+------
+
+Documentation for the ``checks`` sub-sections of attribute specs.
+
+unterminated-ok
+~~~~~~~~~~~~~~~
+
+Accept strings without the null-termination (for legacy families only).
+Switches from the ``NLA_NUL_STRING`` to ``NLA_STRING`` policy type.
+
+max-len
+~~~~~~~
+
+Defines max length for a binary or string attribute (corresponding
+to the ``len`` member of struct nla_policy). For string attributes terminating
+null character is not counted towards ``max-len``.
+
+The field may either be a literal integer value or a name of a defined
+constant. String types may reduce the constant by one
+(i.e. specify ``max-len: CONST - 1``) to reserve space for the terminating
+character so implementations should recognize such pattern.
+
+min-len
+~~~~~~~
+
+Similar to ``max-len`` but defines minimum length.
diff --git a/Documentation/userspace-api/netlink/c-code-gen.rst b/Documentation/userspace-api/netlink/c-code-gen.rst
new file mode 100644
index 000000000000..7c6a86f9ceb9
--- /dev/null
+++ b/Documentation/userspace-api/netlink/c-code-gen.rst
@@ -0,0 +1,104 @@
+.. SPDX-License-Identifier: BSD-3-Clause
+
+==============================
+Netlink spec C code generation
+==============================
+
+This document describes how Netlink specifications are used to render
+C code (uAPI, policies etc.). It also defines the additional properties
+allowed in older families by the ``genetlink-c`` protocol level,
+to control the naming.
+
+For brevity this document refers to ``name`` properties of various
+objects by the object type. For example ``$attr`` is the value
+of ``name`` in an attribute, and ``$family`` is the name of the
+family (the global ``name`` property).
+
+The upper case is used to denote literal values, e.g. ``$family-CMD``
+means the concatenation of ``$family``, a dash character, and the literal
+``CMD``.
+
+The names of ``#defines`` and enum values are always converted to upper case,
+and with dashes (``-``) replaced by underscores (``_``).
+
+If the constructured name is a C keyword, an extra underscore is
+appended (``do`` -> ``do_``).
+
+Globals
+=======
+
+``c-family-name`` controls the name of the ``#define`` for the family
+name, default is ``$family-FAMILY-NAME``.
+
+``c-version-name`` controls the name of the ``#define`` for the version
+of the family, default is ``$family-FAMILY-VERSION``.
+
+``max-by-define`` selects if max values for enums are defined as a
+``#define`` rather than inside the enum.
+
+Definitions
+===========
+
+Constants
+---------
+
+Every constant is rendered as a ``#define``.
+The name of the constant is ``$family-$constant`` and the value
+is rendered as a string or integer according to its type in the spec.
+
+Enums and flags
+---------------
+
+Enums are named ``$family-$enum``. The full name can be set directly
+or suppressed by specifying the ``enum-name`` property.
+Default entry name is ``$family-$enum-$entry``.
+If ``name-prefix`` is specified it replaces the ``$family-$enum``
+portion of the entry name.
+
+Attributes
+==========
+
+Each attribute set (excluding fractional sets) is rendered as an enum.
+
+Attribute enums are traditionally unnamed in netlink headers.
+If naming is desired ``enum-name`` can be used to specify the name.
+
+The default attribute name prefix is ``$family-A`` if the name of the set
+is the same as the name of the family and ``$family-A-$set`` if the names
+differ. The prefix can be overridden by the ``name-prefix`` property of a set.
+The rest of the section will refer to the prefix as ``$pfx``.
+
+Attributes are named ``$pfx-$attribute``.
+
+Attribute enums end with two special values ``__$pfx-MAX`` and ``$pfx-MAX``
+which are used for sizing attribute tables.
+These two names can be specified directly with the ``attr-cnt-name``
+and ``attr-max-name`` properties respectively.
+
+If ``max-by-define`` is set to ``true`` at the global level ``attr-max-name``
+will be specified as a ``#define`` rather than an enum value.
+
+Operations
+==========
+
+Operations are named ``$family-CMD-$operation``.
+If ``name-prefix`` is specified it replaces the ``$family-CMD``
+portion of the name.
+
+Similarly to attribute enums operation enums end with special count and max
+attributes. For operations those attributes can be renamed with
+``cmd-cnt-name`` and ``cmd-max-name``. Max will be a define if ``max-by-define``
+is ``true``.
+
+Multicast groups
+================
+
+Each multicast group gets a define rendered into the kernel uAPI header.
+The name of the define is ``$family-MCGRP-$group``, and can be overwritten
+with the ``c-define-name`` property.
+
+Code generation
+===============
+
+uAPI header is assumed to come from ``<linux/$family.h>`` in the default header
+search path. It can be changed using the ``uapi-header`` global property.
diff --git a/Documentation/userspace-api/netlink/genetlink-legacy.rst b/Documentation/userspace-api/netlink/genetlink-legacy.rst
new file mode 100644
index 000000000000..65cbbffee0bf
--- /dev/null
+++ b/Documentation/userspace-api/netlink/genetlink-legacy.rst
@@ -0,0 +1,96 @@
+.. 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.
+
+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. The plan is to define
+the structs in ``definitions`` and link the appropriate attrs.
+
+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).
diff --git a/Documentation/userspace-api/netlink/index.rst b/Documentation/userspace-api/netlink/index.rst
index b0c21538d97d..be250110c8f6 100644
--- a/Documentation/userspace-api/netlink/index.rst
+++ b/Documentation/userspace-api/netlink/index.rst
@@ -10,3 +10,8 @@ Netlink documentation for users.
:maxdepth: 2
intro
+ specs
+ c-code-gen
+ genetlink-legacy
+
+See also :ref:`Documentation/core-api/netlink.rst <kernel_netlink>`.
diff --git a/Documentation/userspace-api/netlink/specs.rst b/Documentation/userspace-api/netlink/specs.rst
new file mode 100644
index 000000000000..49f2f782f537
--- /dev/null
+++ b/Documentation/userspace-api/netlink/specs.rst
@@ -0,0 +1,410 @@
+.. 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
+ - policy tables for input attribute validation
+ - operation tables
+
+YAML specifications can be found under ``Documentation/netlink/specs/``
+
+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.
+
+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.
+
+version
+~~~~~~~
+
+Generic Netlink family version, default is 1.
+
+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-compabile 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
+--------------------
+
+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 ``0`` for the first attribute in the attribute set.
+
+Note that the ``value`` of an attribute is defined only in its main set.
+
+enum
+~~~~
+
+For integer types specifies that values in the attribute belong to a defined
+``enum``. Note that in case of ``flags`` the values may be combined.
+
+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``.
+
+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.
+
+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.
+
+Scalar integer types
+--------------------
+
+Fixed-width integer types:
+``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.
+
+.. _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.
diff --git a/MAINTAINERS b/MAINTAINERS
index 5d58b55c5ae5..93b7b6000654 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -14187,8 +14187,10 @@ Q: https://patchwork.kernel.org/project/netdevbpf/list/
B: mailto:netdev@vger.kernel.org
T: git git://git.kernel.org/pub/scm/linux/kernel/git/netdev/net.git
T: git git://git.kernel.org/pub/scm/linux/kernel/git/netdev/net-next.git
+F: Documentation/core-api/netlink.rst
F: Documentation/networking/
F: Documentation/process/maintainer-netdev.rst
+F: Documentation/userspace-api/netlink/
F: include/linux/in.h
F: include/linux/net.h
F: include/linux/netdevice.h
--
2.37.3
^ permalink raw reply related [flat|nested] 17+ messages in thread
* [PATCH net-next 2/6] netlink: add schemas for YAML specs
2022-09-29 1:11 [PATCH net-next 0/6] Netlink protocol specs Jakub Kicinski
2022-09-29 1:11 ` [PATCH net-next 1/6] docs: add more netlink docs (incl. spec docs) Jakub Kicinski
@ 2022-09-29 1:11 ` Jakub Kicinski
2022-09-29 1:11 ` [PATCH net-next 3/6] net: add basic C code generators for Netlink Jakub Kicinski
` (3 subsequent siblings)
5 siblings, 0 replies; 17+ messages in thread
From: Jakub Kicinski @ 2022-09-29 1:11 UTC (permalink / raw)
To: davem
Cc: netdev, edumazet, pabeni, robh, johannes, ecree.xilinx, stephen,
sdf, f.fainelli, fw, linux-doc, razor, nicolas.dichtel, gnault,
Jakub Kicinski
Add schemas for Netlink spec files. As described in the docs
we have 4 "protocols" or compatibility levels, and each one
comes with its own schema, but the more general / legacy
schemas are superset of more modern ones: genetlink is
the smallest followed by genetlink-c and genetlink-legacy.
There is no schema for raw netlink, yet, I haven't found the time..
I don't know enough jsonschema to do inheritance or something
but the repetition is not too bad. I hope.
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
---
Documentation/netlink/genetlink-c.yaml | 287 ++++++++++++++++++
Documentation/netlink/genetlink-legacy.yaml | 313 ++++++++++++++++++++
Documentation/netlink/genetlink.yaml | 252 ++++++++++++++++
3 files changed, 852 insertions(+)
create mode 100644 Documentation/netlink/genetlink-c.yaml
create mode 100644 Documentation/netlink/genetlink-legacy.yaml
create mode 100644 Documentation/netlink/genetlink.yaml
diff --git a/Documentation/netlink/genetlink-c.yaml b/Documentation/netlink/genetlink-c.yaml
new file mode 100644
index 000000000000..4ce4f31de845
--- /dev/null
+++ b/Documentation/netlink/genetlink-c.yaml
@@ -0,0 +1,287 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: "http://kernel.org/schemas/netlink/genetlink-c.yaml#"
+$schema: "http://kernel.org/meta-schemas/netlink/core.yaml#"
+
+title: Protocol
+description: Specification of a genetlink protocol
+type: object
+required: [ name, doc, attribute-sets, operations ]
+additionalProperties: False
+properties:
+ name:
+ description: Name of the genetlink family.
+ type: string
+ doc:
+ type: string
+ version:
+ description: Generic Netlink family version. Default is 1.
+ type: integer
+ protocol:
+ description: Schema compatibility level. Default is "genetlink".
+ enum: [ genetlink, genetlink-c]
+ # Start genetlink-c
+ uapi-header:
+ description: Path to the uAPI header, default is linux/${family-name}.h
+ type: string
+ c-family-name:
+ description: Name of the define for the family name.
+ type: string
+ c-version-name:
+ description: Name of the define for the verion of the family.
+ type: string
+ max-by-define:
+ description: Makes the number of attributes and commands be specified by a define, not an enum value.
+ type: boolean
+ # End genetlink-c
+
+ definitions:
+ description: Array of type and constant definitions.
+ type: array
+ items:
+ type: object
+ required: [ type, name ]
+ additionalProperties: False
+ properties:
+ name:
+ type: string
+ header:
+ description: For C-compatible languages, header which already defines this value.
+ type: string
+ type:
+ enum: [ const, enum, flags ]
+ # For const
+ value:
+ description: For const - the value.
+ type: [ string, integer ]
+ # For enum and flags
+ value-start:
+ description: For enum or flags the literal initializer for the first value.
+ type: [ string, integer ]
+ entries:
+ description: For enum or flags array of values
+ type: array
+ items:
+ type: string
+ # Start genetlink-c
+ enum-name:
+ description: Name for enum, if empty no name will be used.
+ type: [ string, "null" ]
+ name-prefix:
+ description: For enum the prefix of the values, optional.
+ type: string
+ # End genetlink-c
+
+ attribute-sets:
+ description: Definition of attribute spaces for this family.
+ type: array
+ items:
+ description: Definition of a single attribute space.
+ type: object
+ required: [ name, attributes ]
+ additionalProperties: False
+ properties:
+ name:
+ description: |
+ Name used when referring to this space in other definitions, not used outside of YAML.
+ type: string
+ # Strictly speaking 'name-prefix' and 'subset-of' should be mutually exclusive.
+ name-prefix:
+ description: |
+ Prefix for the C enum name of the attributes. Default family[name]-set[name]-a-
+ type: string
+ enum-name:
+ description: Name for the enum type of the attribute.
+ type: string
+ doc:
+ description: Documentation of the space.
+ type: string
+ subset-of:
+ description: |
+ Name of another space which this is a logical part of. Sub-spaces can be used to define
+ a limited group of attributes which are used in a nest.
+ type: string
+ # Start genetlink-c
+ attr-cnt-name:
+ description: The explicit name for constant holding the count of attributes (last attr + 1).
+ type: string
+ attr-max-name:
+ description: The explicit name for last member of attribute enum.
+ type: string
+ # End genetlink-c
+ attributes:
+ description: List of attributes in the space.
+ type: array
+ items:
+ type: object
+ required: [ name, type ]
+ additionalProperties: False
+ properties:
+ name:
+ type: string
+ type: &attr-type
+ enum: [ unused, pad, flag, binary, u8, u16, u32, u64, s32, s64,
+ string, nest, array-nest, nest-type-value ]
+ doc:
+ description: Documentation of the attribute.
+ type: string
+ value:
+ description: Value for the enum item representing this attribute in the uAPI.
+ type: integer
+ type-value:
+ description: Name of the value extracted from the type of a nest-type-value attribute.
+ type: array
+ items:
+ type: string
+ byte-order:
+ enum: [little-endian, big-endian]
+ multi-attr:
+ type: boolean
+ nested-attributes:
+ description: Name of the space (sub-space) used inside the attribute.
+ type: string
+ enum:
+ description: Name of the enum type used for the atttribute.
+ type: string
+ checks:
+ description: Kernel input validation.
+ type: object
+ additionalProperties: False
+ properties:
+ flags-mask:
+ description: Name of the flags constant on which to base mask (unsigned scalar types only).
+ type: string
+ min-len:
+ description: Min length for a binary attribute.
+ oneOf:
+ - type: string
+ pattern: ^[0-9A-Za-z_-]*( - 1)?$
+ - type: integer
+ max-len:
+ description: Max length for a string or a binary attribute.
+ oneOf:
+ - type: string
+ pattern: ^[0-9A-Za-z_-]*( - 1)?$
+ - type: integer
+ sub-type: *attr-type
+ operations:
+ description: Operations supported by the protocol.
+ type: object
+ required: [ list ]
+ additionalProperties: False
+ properties:
+ enum-model:
+ description: |
+ The model of assigning values to the operations.
+ "unified" is the recommended model where all message types belong
+ to a single enum.
+ "directional" has the messages sent to the kernel and from the kernel
+ enumerated separately.
+ "notify-split" has the notifications and request-response types in
+ different enums.
+ enum: [ unified, directional, notify-split ]
+ name-prefix:
+ description: |
+ Prefix for the C enum name of the command. The name is formed by concatenating
+ the prefix with the upper case name of the command, with dashes replaced by underscores.
+ type: string
+ enum-name:
+ description: Name for the enum type with commands.
+ type: string
+ async-prefix:
+ description: Same as name-prefix but used to render notifications and events to separate enum.
+ type: string
+ async-enum:
+ description: Name for the enum type with notifications/events.
+ type: string
+ list:
+ description: List of commands
+ type: array
+ items:
+ type: object
+ additionalProperties: False
+ required: [ name, doc ]
+ properties:
+ name:
+ description: Name of the operation, also defining its C enum value in uAPI.
+ type: string
+ doc:
+ description: Documentation for the command.
+ type: string
+ value:
+ description: Value for the enum in the uAPI.
+ type: integer
+ attribute-set:
+ description: |
+ Attribute space from which attributes directly in the requests and replies
+ to this command are defined.
+ type: string
+ flags: &cmd_flags
+ description: Command flags.
+ type: array
+ items:
+ enum: [ admin-perm ]
+ dont-validate:
+ description: Kernel attribute validation flags.
+ type: array
+ items:
+ enum: [ strict, dump ]
+ do: &subop-type
+ description: Main command handler.
+ type: object
+ additionalProperties: False
+ properties:
+ request: &subop-attr-list
+ description: Definition of the request message for a given command.
+ type: object
+ additionalProperties: False
+ properties:
+ attributes:
+ description: |
+ Names of attributes from the attribute-set (not full attribute
+ definitions, just names).
+ type: array
+ items:
+ type: string
+ reply: *subop-attr-list
+ dump: *subop-type
+ notify:
+ description: Name of the command sharing the reply type with this notification.
+ type: string
+ event:
+ type: object
+ additionalProperties: False
+ properties:
+ attributes:
+ description: Explicit list of the attributes for the notification.
+ type: array
+ items:
+ type: string
+ mcgrp:
+ description: Name of the multicast group generating given notification.
+ type: string
+ mcast-groups:
+ description: List of multicast groups.
+ type: object
+ required: [ list ]
+ additionalProperties: False
+ properties:
+ list:
+ description: List of groups.
+ type: array
+ items:
+ type: object
+ required: [ name ]
+ additionalProperties: False
+ properties:
+ name:
+ description: |
+ The name for the group, used to form the define and the value of the define.
+ type: string
+ # Start genetlink-c
+ c-define-name:
+ description: Override for the name of the define in C uAPI.
+ type: string
+ # End genetlink-c
+ flags: *cmd_flags
diff --git a/Documentation/netlink/genetlink-legacy.yaml b/Documentation/netlink/genetlink-legacy.yaml
new file mode 100644
index 000000000000..c5c9fa8994e4
--- /dev/null
+++ b/Documentation/netlink/genetlink-legacy.yaml
@@ -0,0 +1,313 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: "http://kernel.org/schemas/netlink/genetlink-legacy.yaml#"
+$schema: "http://kernel.org/meta-schemas/netlink/core.yaml#"
+
+title: Protocol
+description: Specification of a genetlink protocol
+type: object
+required: [ name, doc, attribute-sets, operations ]
+additionalProperties: False
+properties:
+ name:
+ description: Name of the genetlink family.
+ type: string
+ doc:
+ type: string
+ version:
+ description: Generic Netlink family version. Default is 1.
+ type: integer
+ protocol:
+ description: Schema compatibility level. Default is "genetlink".
+ enum: [ genetlink, genetlink-c, genetlink-legacy, netlink-raw ] # Trim
+ # Start genetlink-c
+ uapi-header:
+ description: Path to the uAPI header, default is linux/${family-name}.h
+ type: string
+ c-family-name:
+ description: Name of the define for the family name.
+ type: string
+ c-version-name:
+ description: Name of the define for the verion of the family.
+ type: string
+ max-by-define:
+ description: Makes the number of attributes and commands be specified by a define, not an enum value.
+ type: boolean
+ # End genetlink-c
+ # Start genetlink-legacy
+ kernel-policy:
+ description: Defines if the input policy in the kernel is global or per-operation, default is per-op.
+ enum: [per-op, global]
+ # End genetlink-legacy
+
+ definitions:
+ description: Array of type and constant definitions.
+ type: array
+ items:
+ type: object
+ required: [ type, name ]
+ additionalProperties: False
+ properties:
+ name:
+ type: string
+ header:
+ description: For C-compatible languages, header which already defines this value.
+ type: string
+ type:
+ enum: [ const, enum, flags, struct ] # Trim
+ # For const
+ value:
+ description: For const - the value.
+ type: [ string, integer ]
+ # For enum and flags
+ value-start:
+ description: For enum or flags the literal initializer for the first value.
+ type: [ string, integer ]
+ entries:
+ description: For enum or flags array of values
+ type: array
+ items:
+ type: string
+ # Start genetlink-c
+ enum-name:
+ description: Name for enum, if empty no name will be used.
+ type: [ string, "null" ]
+ name-prefix:
+ description: For enum the prefix of the values, optional.
+ type: string
+ # End genetlink-c
+ # Start genetlink-legacy
+ members:
+ description: List of struct members. Only scalars and strings members allowed.
+ type: array
+ items:
+ type: object
+ required: [ name, type ]
+ additionalProperties: False
+ properties:
+ name:
+ type: string
+ type:
+ enum: [ u8, u16, u32, u64, s8, s16, s32, s64, string ]
+ len:
+ oneOf:
+ -
+ type: string
+ pattern: ^[0-9A-Za-z_-]*( - 1)?$
+ -
+ type: integer
+ # End genetlink-legacy
+
+ attribute-sets:
+ description: Definition of attribute spaces for this family.
+ type: array
+ items:
+ description: Definition of a single attribute space.
+ type: object
+ required: [ name, attributes ]
+ additionalProperties: False
+ properties:
+ name:
+ description: |
+ Name used when referring to this space in other definitions, not used outside of YAML.
+ type: string
+ # Strictly speaking 'name-prefix' and 'subset-of' should be mutually exclusive.
+ name-prefix:
+ description: |
+ Prefix for the C enum name of the attributes. Default family[name]-set[name]-a-
+ type: string
+ enum-name:
+ description: Name for the enum type of the attribute.
+ type: string
+ doc:
+ description: Documentation of the space.
+ type: string
+ subset-of:
+ description: |
+ Name of another space which this is a logical part of. Sub-spaces can be used to define
+ a limited group of attributes which are used in a nest.
+ type: string
+ # Start genetlink-c
+ attr-cnt-name:
+ description: The explicit name for constant holding the count of attributes (last attr + 1).
+ type: string
+ attr-max-name:
+ description: The explicit name for last member of attribute enum.
+ type: string
+ # End genetlink-c
+ attributes:
+ description: List of attributes in the space.
+ type: array
+ items:
+ type: object
+ required: [ name, type ]
+ additionalProperties: False
+ properties:
+ name:
+ type: string
+ type: &attr-type
+ enum: [ unused, pad, flag, binary, u8, u16, u32, u64, s32, s64,
+ string, nest, array-nest, nest-type-value ]
+ doc:
+ description: Documentation of the attribute.
+ type: string
+ value:
+ description: Value for the enum item representing this attribute in the uAPI.
+ type: integer
+ type-value:
+ description: Name of the value extracted from the type of a nest-type-value attribute.
+ type: array
+ items:
+ type: string
+ byte-order:
+ enum: [little-endian, big-endian]
+ multi-attr:
+ type: boolean
+ nested-attributes:
+ description: Name of the space (sub-space) used inside the attribute.
+ type: string
+ enum:
+ description: Name of the enum type used for the atttribute.
+ type: string
+ checks:
+ description: Kernel input validation.
+ type: object
+ additionalProperties: False
+ properties:
+ flags-mask:
+ description: Name of the flags constant on which to base mask (unsigned scalar types only).
+ type: string
+ min-len:
+ description: Min length for a binary attribute.
+ oneOf:
+ - type: string
+ pattern: ^[0-9A-Za-z_-]*( - 1)?$
+ - type: integer
+ max-len:
+ description: Max length for a string or a binary attribute.
+ oneOf:
+ - type: string
+ pattern: ^[0-9A-Za-z_-]*( - 1)?$
+ - type: integer
+ sub-type: *attr-type
+ operations:
+ description: Operations supported by the protocol.
+ type: object
+ required: [ list ]
+ additionalProperties: False
+ properties:
+ enum-model:
+ description: |
+ The model of assigning values to the operations.
+ "unified" is the recommended model where all message types belong
+ to a single enum.
+ "directional" has the messages sent to the kernel and from the kernel
+ enumerated separately.
+ "notify-split" has the notifications and request-response types in
+ different enums.
+ enum: [ unified, directional, notify-split ]
+ name-prefix:
+ description: |
+ Prefix for the C enum name of the command. The name is formed by concatenating
+ the prefix with the upper case name of the command, with dashes replaced by underscores.
+ type: string
+ enum-name:
+ description: Name for the enum type with commands.
+ type: string
+ async-prefix:
+ description: Same as name-prefix but used to render notifications and events to separate enum.
+ type: string
+ async-enum:
+ description: Name for the enum type with notifications/events.
+ type: string
+ list:
+ description: List of commands
+ type: array
+ items:
+ type: object
+ additionalProperties: False
+ required: [ name, doc ]
+ properties:
+ name:
+ description: Name of the operation, also defining its C enum value in uAPI.
+ type: string
+ doc:
+ description: Documentation for the command.
+ type: string
+ value:
+ description: Value for the enum in the uAPI.
+ type: integer
+ attribute-set:
+ description: |
+ Attribute space from which attributes directly in the requests and replies
+ to this command are defined.
+ type: string
+ flags: &cmd_flags
+ description: Command flags.
+ type: array
+ items:
+ enum: [ admin-perm ]
+ dont-validate:
+ description: Kernel attribute validation flags.
+ type: array
+ items:
+ enum: [ strict, dump ]
+ do: &subop-type
+ description: Main command handler.
+ type: object
+ additionalProperties: False
+ properties:
+ request: &subop-attr-list
+ description: Definition of the request message for a given command.
+ type: object
+ additionalProperties: False
+ properties:
+ attributes:
+ description: |
+ Names of attributes from the attribute-set (not full attribute
+ definitions, just names).
+ type: array
+ items:
+ type: string
+ reply: *subop-attr-list
+ dump: *subop-type
+ notify:
+ description: Name of the command sharing the reply type with this notification.
+ type: string
+ event:
+ type: object
+ additionalProperties: False
+ properties:
+ attributes:
+ description: Explicit list of the attributes for the notification.
+ type: array
+ items:
+ type: string
+ mcgrp:
+ description: Name of the multicast group generating given notification.
+ type: string
+ mcast-groups:
+ description: List of multicast groups.
+ type: object
+ required: [ list ]
+ additionalProperties: False
+ properties:
+ list:
+ description: List of groups.
+ type: array
+ items:
+ type: object
+ required: [ name ]
+ additionalProperties: False
+ properties:
+ name:
+ description: |
+ The name for the group, used to form the define and the value of the define.
+ type: string
+ # Start genetlink-c
+ c-define-name:
+ description: Override for the name of the define in C uAPI.
+ type: string
+ # End genetlink-c
+ flags: *cmd_flags
diff --git a/Documentation/netlink/genetlink.yaml b/Documentation/netlink/genetlink.yaml
new file mode 100644
index 000000000000..6ea3d5a5d41f
--- /dev/null
+++ b/Documentation/netlink/genetlink.yaml
@@ -0,0 +1,252 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: "http://kernel.org/schemas/netlink/genetlink.yaml#"
+$schema: "http://kernel.org/meta-schemas/netlink/core.yaml#"
+
+title: Protocol
+description: Specification of a genetlink protocol
+type: object
+required: [ name, doc, attribute-sets, operations ]
+additionalProperties: False
+properties:
+ name:
+ description: Name of the genetlink family.
+ type: string
+ doc:
+ type: string
+ version:
+ description: Generic Netlink family version. Default is 1.
+ type: integer
+ protocol:
+ description: Schema compatibility level. Default is "genetlink".
+ enum: [ genetlink ]
+
+ definitions:
+ description: Array of type and constant definitions.
+ type: array
+ items:
+ type: object
+ required: [ type, name ]
+ additionalProperties: False
+ properties:
+ name:
+ type: string
+ header:
+ description: For C-compatible languages, header which already defines this value.
+ type: string
+ type:
+ enum: [ const, enum, flags ]
+ # For const
+ value:
+ description: For const - the value.
+ type: [ string, integer ]
+ # For enum and flags
+ value-start:
+ description: For enum or flags the literal initializer for the first value.
+ type: [ string, integer ]
+ entries:
+ description: For enum or flags array of values
+ type: array
+ items:
+ type: string
+
+ attribute-sets:
+ description: Definition of attribute spaces for this family.
+ type: array
+ items:
+ description: Definition of a single attribute space.
+ type: object
+ required: [ name, attributes ]
+ additionalProperties: False
+ properties:
+ name:
+ description: |
+ Name used when referring to this space in other definitions, not used outside of YAML.
+ type: string
+ # Strictly speaking 'name-prefix' and 'subset-of' should be mutually exclusive.
+ name-prefix:
+ description: |
+ Prefix for the C enum name of the attributes. Default family[name]-set[name]-a-
+ type: string
+ enum-name:
+ description: Name for the enum type of the attribute.
+ type: string
+ doc:
+ description: Documentation of the space.
+ type: string
+ subset-of:
+ description: |
+ Name of another space which this is a logical part of. Sub-spaces can be used to define
+ a limited group of attributes which are used in a nest.
+ type: string
+ attributes:
+ description: List of attributes in the space.
+ type: array
+ items:
+ type: object
+ required: [ name, type ]
+ additionalProperties: False
+ properties:
+ name:
+ type: string
+ type: &attr-type
+ enum: [ unused, pad, flag, binary, u8, u16, u32, u64, s32, s64,
+ string, nest, array-nest, nest-type-value ]
+ doc:
+ description: Documentation of the attribute.
+ type: string
+ value:
+ description: Value for the enum item representing this attribute in the uAPI.
+ type: integer
+ type-value:
+ description: Name of the value extracted from the type of a nest-type-value attribute.
+ type: array
+ items:
+ type: string
+ byte-order:
+ enum: [little-endian, big-endian]
+ multi-attr:
+ type: boolean
+ nested-attributes:
+ description: Name of the space (sub-space) used inside the attribute.
+ type: string
+ enum:
+ description: Name of the enum type used for the atttribute.
+ type: string
+ checks:
+ description: Kernel input validation.
+ type: object
+ additionalProperties: False
+ properties:
+ flags-mask:
+ description: Name of the flags constant on which to base mask (unsigned scalar types only).
+ type: string
+ min-len:
+ description: Min length for a binary attribute.
+ oneOf:
+ - type: string
+ pattern: ^[0-9A-Za-z_-]*( - 1)?$
+ - type: integer
+ max-len:
+ description: Max length for a string or a binary attribute.
+ oneOf:
+ - type: string
+ pattern: ^[0-9A-Za-z_-]*( - 1)?$
+ - type: integer
+ sub-type: *attr-type
+ operations:
+ description: Operations supported by the protocol.
+ type: object
+ required: [ list ]
+ additionalProperties: False
+ properties:
+ enum-model:
+ description: |
+ The model of assigning values to the operations.
+ "unified" is the recommended model where all message types belong
+ to a single enum.
+ "directional" has the messages sent to the kernel and from the kernel
+ enumerated separately.
+ "notify-split" has the notifications and request-response types in
+ different enums.
+ enum: [ unified, directional, notify-split ]
+ name-prefix:
+ description: |
+ Prefix for the C enum name of the command. The name is formed by concatenating
+ the prefix with the upper case name of the command, with dashes replaced by underscores.
+ type: string
+ enum-name:
+ description: Name for the enum type with commands.
+ type: string
+ async-prefix:
+ description: Same as name-prefix but used to render notifications and events to separate enum.
+ type: string
+ async-enum:
+ description: Name for the enum type with notifications/events.
+ type: string
+ list:
+ description: List of commands
+ type: array
+ items:
+ type: object
+ additionalProperties: False
+ required: [ name, doc ]
+ properties:
+ name:
+ description: Name of the operation, also defining its C enum value in uAPI.
+ type: string
+ doc:
+ description: Documentation for the command.
+ type: string
+ value:
+ description: Value for the enum in the uAPI.
+ type: integer
+ attribute-set:
+ description: |
+ Attribute space from which attributes directly in the requests and replies
+ to this command are defined.
+ type: string
+ flags: &cmd_flags
+ description: Command flags.
+ type: array
+ items:
+ enum: [ admin-perm ]
+ dont-validate:
+ description: Kernel attribute validation flags.
+ type: array
+ items:
+ enum: [ strict, dump ]
+ do: &subop-type
+ description: Main command handler.
+ type: object
+ additionalProperties: False
+ properties:
+ request: &subop-attr-list
+ description: Definition of the request message for a given command.
+ type: object
+ additionalProperties: False
+ properties:
+ attributes:
+ description: |
+ Names of attributes from the attribute-set (not full attribute
+ definitions, just names).
+ type: array
+ items:
+ type: string
+ reply: *subop-attr-list
+ dump: *subop-type
+ notify:
+ description: Name of the command sharing the reply type with this notification.
+ type: string
+ event:
+ type: object
+ additionalProperties: False
+ properties:
+ attributes:
+ description: Explicit list of the attributes for the notification.
+ type: array
+ items:
+ type: string
+ mcgrp:
+ description: Name of the multicast group generating given notification.
+ type: string
+ mcast-groups:
+ description: List of multicast groups.
+ type: object
+ required: [ list ]
+ additionalProperties: False
+ properties:
+ list:
+ description: List of groups.
+ type: array
+ items:
+ type: object
+ required: [ name ]
+ additionalProperties: False
+ properties:
+ name:
+ description: |
+ The name for the group, used to form the define and the value of the define.
+ type: string
+ flags: *cmd_flags
--
2.37.3
^ permalink raw reply related [flat|nested] 17+ messages in thread
* [PATCH net-next 3/6] net: add basic C code generators for Netlink
2022-09-29 1:11 [PATCH net-next 0/6] Netlink protocol specs Jakub Kicinski
2022-09-29 1:11 ` [PATCH net-next 1/6] docs: add more netlink docs (incl. spec docs) Jakub Kicinski
2022-09-29 1:11 ` [PATCH net-next 2/6] netlink: add schemas for YAML specs Jakub Kicinski
@ 2022-09-29 1:11 ` Jakub Kicinski
2022-09-29 1:11 ` [PATCH net-next 4/6] netlink: add a proto specification for FOU Jakub Kicinski
` (2 subsequent siblings)
5 siblings, 0 replies; 17+ messages in thread
From: Jakub Kicinski @ 2022-09-29 1:11 UTC (permalink / raw)
To: davem
Cc: netdev, edumazet, pabeni, robh, johannes, ecree.xilinx, stephen,
sdf, f.fainelli, fw, linux-doc, razor, nicolas.dichtel, gnault,
Jakub Kicinski
Code generators to turn Netlink specs into C code.
I'm definitely not proud of it.
The main generator is in Python, there's a bash script
to regen all code-gen'ed files in tree after making
spec changes.
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
---
MAINTAINERS | 1 +
tools/net/ynl/ynl-gen-c.py | 1998 ++++++++++++++++++++++++++++++++++++
tools/net/ynl/ynl-regen.sh | 30 +
3 files changed, 2029 insertions(+)
create mode 100755 tools/net/ynl/ynl-gen-c.py
create mode 100755 tools/net/ynl/ynl-regen.sh
diff --git a/MAINTAINERS b/MAINTAINERS
index 93b7b6000654..e03123d776cd 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -14202,6 +14202,7 @@ F: include/uapi/linux/netdevice.h
F: lib/net_utils.c
F: lib/random32.c
F: net/
+F: tools/net/
F: tools/testing/selftests/net/
NETWORKING [IPSEC]
diff --git a/tools/net/ynl/ynl-gen-c.py b/tools/net/ynl/ynl-gen-c.py
new file mode 100755
index 000000000000..69800aecd45b
--- /dev/null
+++ b/tools/net/ynl/ynl-gen-c.py
@@ -0,0 +1,1998 @@
+#!/usr/bin/env python
+
+import argparse
+import jsonschema
+import os
+import yaml
+
+
+def c_upper(name):
+ return name.upper().replace('-', '_')
+
+
+def c_lower(name):
+ return name.lower().replace('-', '_')
+
+
+class BaseNlLib:
+ def __init__(self):
+ pass
+
+ def get_family_id(self):
+ return 'ys->family_id'
+
+ def parse_cb_run(self, cb, data, is_dump=False, indent=1):
+ ind = '\n\t\t' + '\t' * indent + ' '
+ if is_dump:
+ return f"mnl_cb_run2(ys->rx_buf, len, 0, 0, {cb}, {data},{ind}ynl_cb_array, NLMSG_MIN_TYPE)"
+ else:
+ return f"mnl_cb_run2(ys->rx_buf, len, ys->seq, ys->portid,{ind}{cb}, {data},{ind}" + \
+ "ynl_cb_array, NLMSG_MIN_TYPE)"
+
+
+class Type:
+ def __init__(self, family, attr_set, attr):
+ self.family = family
+ self.attr = attr
+ self.value = attr['value']
+ self.name = attr['name'].replace('-', '_')
+ self.type = attr['type']
+ self.checks = attr.get('checks', {})
+
+ if 'len' in attr:
+ self.len = attr['len']
+ if 'nested-attributes' in attr:
+ self.nested_attrs = attr['nested-attributes']
+ if self.nested_attrs == family.name:
+ self.nested_render_name = f"{family.name}"
+ else:
+ self.nested_render_name = f"{family.name}_{self.nested_attrs.replace('-', '_')}"
+
+ self.enum_name = f"{attr_set.name_prefix}{self.name}"
+ self.enum_name = self.enum_name.upper().replace('-', '_')
+ self.c_name = self.name.replace('-', '_')
+ if self.c_name in c_kw:
+ self.c_name += '_'
+
+ def __getitem__(self, key):
+ return self.attr[key]
+
+ def __contains__(self, key):
+ return key in self.attr
+
+ def is_multi_val(self):
+ return None
+
+ def is_scalar(self):
+ return self.type in {'u8', 'u16', 'u32', 'u64', 's32', 's64'}
+
+ def presence_type(self):
+ return 'bit'
+
+ def presence_member(self, space, type_filter):
+ if self.presence_type() != type_filter:
+ return
+
+ if self.presence_type() == 'bit':
+ pfx = '__' if space == 'user' else ''
+ return f"{pfx}u32 {self.c_name}:1;"
+
+ if self.presence_type() == 'len':
+ pfx = '__' if space == 'user' else ''
+ return f"{pfx}u32 {self.c_name}_len;"
+
+ def _complex_member_type(self, ri):
+ return None
+
+ def free_needs_iter(self):
+ return False
+
+ def free(self, ri, var, ref):
+ if self.is_multi_val() or self.presence_type() == 'len':
+ ri.cw.p(f'free({var}->{ref}{self.c_name});')
+
+ def arg_member(self, ri):
+ member = self._complex_member_type(ri)
+ if member:
+ return [member + ' *' + self.c_name]
+ raise Exception(f"Struct member not implemented for class type {self.type}")
+
+ def struct_member(self, ri):
+ if self.is_multi_val():
+ ri.cw.p(f"unsigned int n_{self.c_name};")
+ member = self._complex_member_type(ri)
+ if member:
+ ptr = ''
+ if self. is_multi_val():
+ ptr = '*'
+ ri.cw.p(f"{member} {ptr}{self.c_name};")
+ return
+ members = self.arg_member(ri)
+ for one in members:
+ ri.cw.p(one + ';')
+
+ def _attr_policy(self, policy):
+ return '{ .type = ' + policy + ', }'
+
+ def attr_policy(self, cw):
+ policy = 'NLA_' + self.attr['type'].upper()
+ policy = policy.replace('-', '_')
+
+ spec = self._attr_policy(policy)
+ cw.p(f"\t[{self.enum_name}] = {spec},")
+
+ def _attr_typol(self):
+ raise Exception(f"Type policy not implemented for class type {self.type}")
+
+ def attr_typol(self, cw):
+ typol = self._attr_typol()
+ cw.p(f'[{self.enum_name}] = {"{"} .name = "{self.name}", {typol}{"}"},')
+
+ def _attr_put_line(self, ri, var, line):
+ if self.presence_type() == 'bit':
+ ri.cw.p(f"if ({var}->_present.{self.c_name})")
+ elif self.presence_type() == 'len':
+ ri.cw.p(f"if ({var}->_present.{self.c_name}_len)")
+ ri.cw.p(f"{line};")
+
+ def _attr_put_simple(self, ri, var, put_type):
+ line = f"mnl_attr_put_{put_type}(nlh, {self.enum_name}, {var}->{self.c_name})"
+ self._attr_put_line(ri, var, line)
+
+ def attr_put(self, ri, var):
+ raise Exception(f"Put not implemented for class type {self.type}")
+
+ def _attr_get(self, ri, var):
+ raise Exception(f"Attr get not implemented for class type {self.type}")
+
+ def attr_get(self, ri, var, first):
+ lines, init_lines, local_vars = self._attr_get(ri, var)
+ if type(lines) is str:
+ lines = [lines]
+ if type(init_lines) is str:
+ init_lines = [init_lines]
+
+ kw = 'if' if first else 'else if'
+ ri.cw.block_start(line=f"{kw} (mnl_attr_get_type(attr) == {self.enum_name})")
+ if local_vars:
+ for local in local_vars:
+ ri.cw.p(local)
+ ri.cw.nl()
+
+ if not self.is_multi_val():
+ ri.cw.p(f"if (ynl_attr_validate(yarg, attr))")
+ ri.cw.p(f"return MNL_CB_ERROR;")
+ if self.presence_type() == 'bit':
+ ri.cw.p(f"{var}->_present.{self.c_name} = 1;")
+
+ if init_lines:
+ ri.cw.nl()
+ for line in init_lines:
+ ri.cw.p(line)
+
+ for line in lines:
+ ri.cw.p(line)
+ ri.cw.block_end()
+
+ def _setter_lines(self, ri, member, presence):
+ raise Exception(f"Setter not implemented for class type {self.type}")
+
+ def setter(self, ri, space, direction, deref=False, ref=None):
+ ref = (ref if ref else []) + [self.c_name]
+ var = "req"
+ member = f"{var}->{'.'.join(ref)}"
+
+ code = []
+ presence = ''
+ for i in range(0, len(ref)):
+ presence = f"{var}->{'.'.join(ref[:i] + [''])}_present.{ref[i]}"
+ if self.presence_type() == 'bit':
+ code.append(presence + ' = 1;')
+ code += self._setter_lines(ri, member, presence)
+
+ ri.cw.write_func('static inline void',
+ f"{op_prefix(ri, direction, deref=deref)}_set_{'_'.join(ref)}",
+ body=code,
+ args=[f'{type_name(ri, direction, deref=deref)} *{var}'] + self.arg_member(ri))
+
+
+class TypeUnused(Type):
+ def presence_type(self):
+ return ''
+
+ def _attr_typol(self):
+ return '.type = YNL_PT_REJECT, '
+
+ def attr_policy(self, cw):
+ pass
+
+class TypeScalar(Type):
+ def __init__(self, family, attr_set, attr):
+ super().__init__(family, attr_set, attr)
+
+ if 'enum' in self.attr:
+ self.type_name = f"enum {family.name}_{self.attr['enum'].replace('-', '_')}"
+ else:
+ self.type_name = '__' + self.type
+
+ self.byte_order_comment = ''
+ if 'byte-order' in attr:
+ self.byte_order_comment = f" /* {attr['byte-order']} */"
+
+ def _mnl_type(self):
+ t = self.type
+ # mnl does not have a helper for signed types
+ if t[0] == 's':
+ t = 'u' + t[1:]
+ return t
+
+ def _attr_policy(self, policy):
+ if 'flags-mask' in self.checks:
+ flags = self.family.consts[self.checks['flags-mask']]
+ flag_cnt = len(flags['entries'])
+ return f"NLA_POLICY_MASK({policy}, 0x{(1 << flag_cnt) - 1:x})"
+ elif 'enum' in self.attr:
+ enum = self.family.consts[self.attr['enum']]
+ cnt = len(enum['entries'])
+ return f"NLA_POLICY_MAX({policy}, {cnt})"
+ return super()._attr_policy(policy)
+
+ def _attr_typol(self):
+ return f'.type = YNL_PT_U{self.type[1:]}, '
+
+ def arg_member(self, ri):
+ return [f'{self.type_name} {self.c_name}{self.byte_order_comment}']
+
+ def attr_put(self, ri, var):
+ self._attr_put_simple(ri, var, self._mnl_type())
+
+ def _attr_get(self, ri, var):
+ return f"{var}->{self.c_name} = mnl_attr_get_{self._mnl_type()}(attr);", None, None
+
+ def _setter_lines(self, ri, member, presence):
+ return [f"{member} = {self.c_name};"]
+
+
+class TypeFlag(Type):
+ def arg_member(self, ri):
+ return []
+
+ def _attr_typol(self):
+ return '.type = YNL_PT_FLAG, '
+
+ def attr_put(self, ri, var):
+ self._attr_put_line(ri, var, f"mnl_attr_put(nlh, {self.enum_name}, 0, NULL)")
+
+ def _attr_get(self, ri, var):
+ return [], None, None
+
+ def _setter_lines(self, ri, member, presence):
+ return []
+
+
+class TypeString(Type):
+ def arg_member(self, ri):
+ return [f"const char *{self.c_name}"]
+
+ def presence_type(self):
+ return 'len'
+
+ def struct_member(self, ri):
+ ri.cw.p(f"char *{self.c_name};")
+
+ def _attr_typol(self):
+ return f'.type = YNL_PT_NUL_STR, '
+
+ def _attr_policy(self, policy):
+ mem = '{ .type = ' + policy
+ if 'max-len' in self.checks:
+ mem += ', .len = ' + str(self.checks['max-len'])
+ mem += ', }'
+ return mem
+
+ def attr_policy(self, cw):
+ if 'unterminated-ok' in self.checks and self.checks['unterminated-ok']:
+ policy = 'NLA_STRING'
+ else:
+ policy = 'NLA_NUL_STRING'
+
+ spec = self._attr_policy(policy)
+ cw.p(f"\t[{self.enum_name}] = {spec},")
+
+ def attr_put(self, ri, var):
+ self._attr_put_simple(ri, var, 'strz')
+
+ def _attr_get(self, ri, var):
+ len_mem = var + '->_present.' + self.c_name + '_len'
+ return [f"{len_mem} = len;",
+ f"{var}->{self.c_name} = malloc(len + 1);",
+ f"memcpy({var}->{self.c_name}, mnl_attr_get_str(attr), len);",
+ f"{var}->{self.c_name}[len] = 0;"], \
+ ['len = strnlen(mnl_attr_get_str(attr), mnl_attr_get_payload_len(attr));'], \
+ ['unsigned int len;']
+
+ def _setter_lines(self, ri, member, presence):
+ return [f"free({member});",
+ f"{presence}_len = strlen({self.c_name});",
+ f"{member} = malloc({presence}_len + 1);",
+ f'memcpy({member}, {self.c_name}, {presence}_len);',
+ f'{member}[{presence}_len] = 0;']
+
+
+class TypeBinary(Type):
+ def arg_member(self, ri):
+ return [f"const void *{self.c_name}", 'size_t len']
+
+ def presence_type(self):
+ return 'len'
+
+ def struct_member(self, ri):
+ ri.cw.p(f"void *{self.c_name};")
+
+ def _attr_typol(self):
+ return f'.type = YNL_PT_BINARY,'
+
+ def _attr_policy(self, policy):
+ mem = '{ '
+ if len(self.checks) == 1 and 'min-len' in self.checks:
+ mem += '.len = ' + str(self.checks['min-len'])
+ else:
+ raise Exception('Binary type not implemented, yet')
+ mem += ', }'
+ return mem
+
+ def attr_put(self, ri, var):
+ self._attr_put_line(ri, var, f"mnl_attr_put(nlh, {self.enum_name}, " +
+ f"{var}->_present.{self.c_name}_len, {var}->{self.c_name})")
+
+ def _attr_get(self, ri, var):
+ len_mem = var + '->_present.' + self.c_name + '_len'
+ return [f"{len_mem} = len;",
+ f"{var}->{self.c_name} = malloc(len);",
+ f"memcpy({var}->{self.c_name}, mnl_attr_get_payload(attr), len);"], \
+ ['len = mnl_attr_get_payload_len(attr);'], \
+ ['unsigned int len;']
+
+ def _setter_lines(self, ri, member, presence):
+ return [f"free({member});",
+ f"{member} = malloc({presence}_len);",
+ f'memcpy({member}, {self.c_name}, {presence}_len);']
+
+
+class TypeNest(Type):
+ def _complex_member_type(self, ri):
+ return f"struct {self.nested_render_name}"
+
+ def free(self, ri, var, ref):
+ ri.cw.p(f'{self.nested_render_name}_free(&{var}->{ref}{self.c_name});')
+
+ def _attr_typol(self):
+ return f'.type = YNL_PT_NEST, .nest = &{self.nested_render_name}_nest, '
+
+ def attr_put(self, ri, var):
+ self._attr_put_line(ri, var, f"{self.nested_render_name}_put(nlh, " +
+ f"{self.enum_name}, &{var}->{self.c_name})")
+
+ def _attr_get(self, ri, var):
+ get_lines = [f"{self.nested_render_name}_parse(&parg, attr);"]
+ init_lines = [f"parg.rsp_policy = &{self.nested_render_name}_nest;",
+ f"parg.data = &{var}->{self.c_name};"]
+ return get_lines, init_lines, None
+
+ def setter(self, ri, space, direction, deref=False, ref=None):
+ ref = (ref if ref else []) + [self.c_name]
+
+ for _, attr in ri.family.pure_nested_structs[self.nested_attrs].member_list():
+ attr.setter(ri, self.nested_attrs, direction, deref=deref, ref=ref)
+
+
+class TypeMultiAttr(Type):
+ def is_multi_val(self):
+ return True
+
+ def presence_type(self):
+ return 'count'
+
+ def _complex_member_type(self, ri):
+ if 'type' not in self.attr or self.attr['type'] == 'nest':
+ return f"struct {self.nested_render_name}"
+ elif self.attr['type'] in scalars:
+ scalar_pfx = '__' if ri.ku_space == 'user' else ''
+ return scalar_pfx + self.attr['type']
+ else:
+ raise Exception(f"Sub-type {self.attr['type']} not supported yet")
+
+ def free_needs_iter(self):
+ return 'type' not in self.attr or self.attr['type'] == 'nest'
+
+ def free(self, ri, var, ref):
+ if 'type' not in self.attr or self.attr['type'] == 'nest':
+ ri.cw.p(f"for (i = 0; i < {var}->{ref}n_{self.c_name}; i++)")
+ ri.cw.p(f'{self.nested_render_name}_free(&{var}->{ref}{self.c_name}[i]);')
+
+ def _attr_typol(self):
+ if 'type' not in self.attr or self.attr['type'] == 'nest':
+ return f'.type = YNL_PT_NEST, .nest = &{self.nested_render_name}_nest, '
+ elif self.attr['type'] in scalars:
+ return f".type = YNL_PT_U{self.attr['type'][1:]}, "
+ else:
+ raise Exception(f"Sub-type {self.attr['type']} not supported yet")
+
+ def _attr_get(self, ri, var):
+ return f'{var}->n_{self.c_name}++;', None, None
+
+
+class TypeArrayNest(Type):
+ def is_multi_val(self):
+ return True
+
+ def presence_type(self):
+ return 'count'
+
+ def _complex_member_type(self, ri):
+ if 'sub-type' not in self.attr or self.attr['sub-type'] == 'nest':
+ return f"struct {self.nested_render_name}"
+ elif self.attr['sub-type'] in scalars:
+ scalar_pfx = '__' if ri.ku_space == 'user' else ''
+ return scalar_pfx + self.attr['sub-type']
+ else:
+ raise Exception(f"Sub-type {self.attr['sub-type']} not supported yet")
+
+ def _attr_typol(self):
+ return f'.type = YNL_PT_NEST, .nest = &{self.nested_render_name}_nest, '
+
+ def _attr_get(self, ri, var):
+ local_vars = ['const struct nlattr *attr2;']
+ get_lines = [f'attr_{self.c_name} = attr;',
+ 'mnl_attr_for_each_nested(attr2, attr)',
+ f'\t{var}->n_{self.c_name}++;']
+ return get_lines, None, local_vars
+
+
+class TypeNestTypeValue(Type):
+ def _complex_member_type(self, ri):
+ return f"struct {self.nested_render_name}"
+
+ def _attr_typol(self):
+ return f'.type = YNL_PT_NEST, .nest = &{self.nested_render_name}_nest, '
+
+ def _attr_get(self, ri, var):
+ prev = 'attr'
+ tv_args = ''
+ get_lines = []
+ local_vars = []
+ init_lines = [f"parg.rsp_policy = &{self.nested_render_name}_nest;",
+ f"parg.data = &{var}->{self.c_name};"]
+ if 'type-value' in self.attr:
+ tv_names = [x.replace('-', '_') for x in self.attr["type-value"]]
+ local_vars += [f'const struct nlattr *attr_{", *attr_".join(tv_names)};']
+ local_vars += [f'__u32 {", ".join(tv_names)};']
+ for level in self.attr["type-value"]:
+ level = level.replace('-', '_')
+ get_lines += [f'attr_{level} = mnl_attr_get_payload({prev});']
+ get_lines += [f'{level} = mnl_attr_get_type(attr_{level});']
+ prev = 'attr_' + level
+
+ tv_args = f", {', '.join(tv_names)}"
+
+ get_lines += [f"{self.nested_render_name}_parse(&parg, {prev}{tv_args});"]
+ return get_lines, init_lines, local_vars
+
+
+class Struct:
+ def __init__(self, family, space_name, type_list=None, inherited=None):
+ self.family = family
+ self.space_name = space_name
+ self.attr_set = family.attr_sets[space_name]
+ # Use list to catch comparisons with empty sets
+ self._inherited = inherited if inherited is not None else []
+ self.inherited = []
+
+ self.nested = type_list is None
+ if family.name == space_name.replace('-', '_'):
+ self.render_name = f"{family.name}"
+ else:
+ self.render_name = f"{family.name}_{space_name.replace('-', '_')}"
+ self.struct_name = 'struct ' + self.render_name
+ self.ptr_name = self.struct_name + ' *'
+
+ self.request = False
+ self.reply = False
+
+ self.attr_list = []
+ self.attrs = dict()
+ if type_list:
+ for t in type_list:
+ self.attr_list.append((t, self.attr_set[t]),)
+ else:
+ for t in self.attr_set:
+ self.attr_list.append((t, self.attr_set[t]),)
+
+ max_val = 0
+ self.attr_max_val = None
+ for name, attr in self.attr_list:
+ if attr.value > max_val:
+ max_val = attr.value
+ self.attr_max_val = attr
+ self.attrs[name] = attr
+
+ def __iter__(self):
+ yield from self.attrs
+
+ def __getitem__(self, key):
+ return self.attrs[key]
+
+ def member_list(self):
+ return self.attr_list
+
+ def set_inherited(self, new_inherited):
+ if self._inherited != new_inherited:
+ raise Exception("Inheriting different members not supported")
+ self.inherited = [x.replace('-', '_') for x in sorted(self._inherited)]
+
+
+class AttrSet:
+ def __init__(self, family, yaml):
+ self.yaml = yaml
+
+ self.attrs = dict()
+ self.name = self.yaml['name']
+ if 'subset-of' not in yaml:
+ self.subset_of = None
+ if 'name-prefix' in yaml:
+ pfx = yaml['name-prefix']
+ elif self.name == family.name:
+ pfx = family.name + '-a-'
+ else:
+ pfx = f"{family.name}-a-{self.name}-"
+ self.name_prefix = c_upper(pfx)
+ self.max_name = c_upper(self.yaml.get('attr-max-name', f"{self.name_prefix}max"))
+ else:
+ self.subset_of = self.yaml['subset-of']
+ self.name_prefix = family.attr_sets[self.subset_of].name_prefix
+ self.max_name = family.attr_sets[self.subset_of].max_name
+
+ self.c_name = self.name.replace('-', '_')
+ if self.c_name in c_kw:
+ self.c_name += '_'
+ if self.c_name == family.c_name:
+ self.c_name = ''
+
+ val = 0
+ for elem in self.yaml['attributes']:
+ if 'value' in elem:
+ val = elem['value']
+ else:
+ elem['value'] = val
+ val += 1
+
+ if 'multi-attr' in elem and elem['multi-attr']:
+ attr = TypeMultiAttr(family, self, elem)
+ elif elem['type'] in scalars:
+ attr = TypeScalar(family, self, elem)
+ elif elem['type'] == 'unused':
+ attr = TypeUnused(family, self, elem)
+ elif elem['type'] == 'flag':
+ attr = TypeFlag(family, self, elem)
+ elif elem['type'] == 'string':
+ attr = TypeString(family, self, elem)
+ elif elem['type'] == 'binary':
+ attr = TypeBinary(family, self, elem)
+ elif elem['type'] == 'nest':
+ attr = TypeNest(family, self, elem)
+ elif elem['type'] == 'array-nest':
+ attr = TypeArrayNest(family, self, elem)
+ elif elem['type'] == 'nest-type-value':
+ attr = TypeNestTypeValue(family, self, elem)
+ else:
+ raise Exception(f"No typed class for type {elem['type']}")
+
+ self.attrs[elem['name']] = attr
+
+ def __getitem__(self, key):
+ return self.attrs[key]
+
+ def __contains__(self, key):
+ return key in self.yaml
+
+ def __iter__(self):
+ yield from self.attrs
+
+ def items(self):
+ return self.attrs.items()
+
+
+class Operation:
+ def __init__(self, family, yaml, value):
+ self.yaml = yaml
+ self.value = value
+
+ self.name = self.yaml['name']
+ self.render_name = family.name + '_' + self.name.replace('-', '_')
+ self.is_async = 'notify' in yaml or 'event' in yaml
+ if not self.is_async:
+ self.enum_name = family.op_prefix + self.name.upper().replace('-', '_')
+ else:
+ self.enum_name = family.async_op_prefix + self.name.upper().replace('-', '_')
+
+ def __getitem__(self, key):
+ return self.yaml[key]
+
+ def __contains__(self, key):
+ return key in self.yaml
+
+ def add_notification(self, op):
+ if 'notify' not in self.yaml:
+ self.yaml['notify'] = dict()
+ self.yaml['notify']['reply'] = self.yaml['do']['reply']
+ self.yaml['notify']['cmds'] = []
+ self.yaml['notify']['cmds'].append(op)
+
+
+class Family:
+ def __init__(self, file_name):
+ with open(file_name, "r") as stream:
+ self.yaml = yaml.safe_load(stream)
+
+ proto = self.yaml.get('protocol', 'genetlink')
+
+ with open(os.path.dirname(os.path.dirname(file_name)) + f'/{proto}.yaml', "r") as stream:
+ schema = yaml.safe_load(stream)
+
+ jsonschema.validate(self.yaml, schema)
+
+ if self.yaml.get('protocol', 'genetlink') not in {'genetlink', 'genetlink-c', 'genetlink-legacy'}:
+ raise Exception("Codegen only supported for genetlink")
+
+ if 'definitions' not in self.yaml:
+ self.yaml['definitions'] = []
+
+ self.name = self.yaml['name']
+ self.c_name = self.name.replace('-', '_')
+ if 'uapi-header' in self.yaml:
+ self.uapi_header = self.yaml['uapi-header']
+ else:
+ self.uapi_header = f"linux/{self.name}.h"
+ if 'name-prefix' in self.yaml['operations']:
+ self.op_prefix = self.yaml['operations']['name-prefix'].upper().replace('-', '_')
+ else:
+ self.op_prefix = (self.yaml['name'] + '-cmd-').upper().replace('-', '_')
+ if 'async-prefix' in self.yaml['operations']:
+ self.async_op_prefix = self.yaml['operations']['async-prefix'].upper().replace('-', '_')
+ else:
+ self.async_op_prefix = self.op_prefix
+
+ self.consts = dict()
+ self.ops = dict()
+ self.ops_list = []
+ self.attr_sets = dict()
+ self.attr_sets_list = []
+
+ # dict space-name -> 'request': set(attrs), 'reply': set(attrs)
+ self.root_sets = dict()
+ # dict space-name -> set('request', 'reply')
+ self.pure_nested_structs = dict()
+ self.all_notify = dict()
+
+ self._mock_up_events()
+
+ self._dictify()
+ self._load_root_sets()
+ self._load_nested_sets()
+ self._load_all_notify()
+
+ self.kernel_policy = self.yaml.get('kernel-policy', 'per-op')
+ if self.kernel_policy == 'global':
+ self._load_global_policy()
+
+ def __getitem__(self, key):
+ return self.yaml[key]
+
+ def get(self, key, default=None):
+ return self.yaml.get(key, default)
+
+ # Fake a 'do' equivalent of all events, so that we can render their response parsing
+ def _mock_up_events(self):
+ for op in self.yaml['operations']['list']:
+ if 'event' in op:
+ op['do'] = {
+ 'reply': {
+ 'attributes': op['event']['attributes']
+ }
+ }
+
+ def _dictify(self):
+ for elem in self.yaml['definitions']:
+ self.consts[elem['name']] = elem
+
+ for elem in self.yaml['attribute-sets']:
+ attr_set = AttrSet(self, elem)
+ self.attr_sets[elem['name']] = attr_set
+ self.attr_sets_list.append((elem['name'], attr_set), )
+
+ ntf = []
+ val = 0
+ for elem in self.yaml['operations']['list']:
+ if 'value' in elem:
+ val = elem['value']
+
+ op = Operation(self, elem, val)
+ val += 1
+
+ self.ops_list.append((elem['name'], op),)
+ if 'notify' in elem:
+ ntf.append(op)
+ continue
+ if 'attribute-set' not in elem:
+ continue
+ self.ops[elem['name']] = op
+ for n in ntf:
+ self.ops[n['notify']].add_notification(n)
+
+ def _load_root_sets(self):
+ for op_name, op in self.ops.items():
+ if 'attribute-set' not in op:
+ continue
+
+ req_attrs = set()
+ rsp_attrs = set()
+ for op_mode in ['do', 'dump']:
+ if op_mode in op and 'request' in op[op_mode]:
+ req_attrs.update(set(op[op_mode]['request']['attributes']))
+ if op_mode in op and 'reply' in op[op_mode]:
+ rsp_attrs.update(set(op[op_mode]['reply']['attributes']))
+
+ if op['attribute-set'] not in self.root_sets:
+ self.root_sets[op['attribute-set']] = {'request': req_attrs, 'reply': rsp_attrs}
+ else:
+ self.root_sets[op['attribute-set']]['request'].update(req_attrs)
+ self.root_sets[op['attribute-set']]['reply'].update(rsp_attrs)
+
+ def _load_nested_sets(self):
+ for root_set, rs_members in self.root_sets.items():
+ for attr, spec in self.attr_sets[root_set].items():
+ if 'nested-attributes' in spec:
+ inherit = set()
+ nested = spec['nested-attributes']
+ if nested not in self.root_sets:
+ self.pure_nested_structs[nested] = Struct(self, nested, inherited=inherit)
+ if attr in rs_members['request']:
+ self.pure_nested_structs[nested].request = True
+ if attr in rs_members['reply']:
+ self.pure_nested_structs[nested].reply = True
+
+ if 'type-value' in spec:
+ if nested in self.root_sets:
+ raise Exception("Inheriting members to a space used as root not supported")
+ inherit.update(set(spec['type-value']))
+ elif spec['type'] == 'array-nest':
+ inherit.add('idx')
+ self.pure_nested_structs[nested].set_inherited(inherit)
+
+ def _load_all_notify(self):
+ for op_name, op in self.ops.items():
+ if not op:
+ continue
+
+ if 'notify' in op:
+ self.all_notify[op_name] = op['notify']['cmds']
+
+ def _load_global_policy(self):
+ global_set = set()
+ attr_set_name = None
+ for op_name, op in self.ops.items():
+ if not op:
+ continue
+ if 'attribute-set' not in op:
+ continue
+
+ if attr_set_name is None:
+ attr_set_name = op['attribute-set']
+ if attr_set_name != op['attribute-set']:
+ raise Exception('For a global policy all ops must use the same set')
+
+ for op_mode in {'do', 'dump'}:
+ if op_mode in op:
+ global_set.update(op[op_mode].get('request', []))
+
+ self.global_policy = []
+ self.global_policy_set = attr_set_name
+ for attr in self.attr_sets[attr_set_name]:
+ if attr in global_set:
+ self.global_policy.append(attr)
+
+
+class RenderInfo:
+ def __init__(self, cw, family, ku_space, op, op_name, op_mode, attr_set=None):
+ self.family = family
+ self.nl = cw.nlib
+ self.ku_space = ku_space
+ self.op = op
+ self.op_name = op_name
+ self.op_mode = op_mode
+
+ # 'do' and 'dump' response parsing is identical
+ if op_mode != 'do' and 'dump' in op and 'do' in op and 'reply' in op['do'] and \
+ op["do"]["reply"] == op["dump"]["reply"]:
+ self.type_consistent = True
+ else:
+ self.type_consistent = op_mode == 'event'
+
+ self.attr_set = attr_set
+ if not self.attr_set:
+ self.attr_set = op['attribute-set']
+
+ if op:
+ self.type_name = op_name.replace('-', '_')
+ else:
+ self.type_name = attr_set.replace('-', '_')
+
+ self.cw = cw
+
+ self.struct = dict()
+ for op_dir in ['request', 'reply']:
+ if op and op_dir in op[op_mode]:
+ self.struct[op_dir] = Struct(family, self.attr_set,
+ type_list=op[op_mode][op_dir]['attributes'])
+ if op_mode == 'event':
+ self.struct['reply'] = Struct(family, self.attr_set, type_list=op['event']['attributes'])
+
+
+class CodeWriter:
+ def __init__(self, nlib):
+ self.nlib = nlib
+
+ self._nl = False
+ self._silent_block = False
+ self._ind = 0
+
+ @classmethod
+ def _is_cond(cls, line):
+ return line.startswith('if') or line.startswith('while') or line.startswith('for')
+
+ def p(self, line, add_ind=0):
+ if self._nl:
+ print()
+ self._nl = False
+ ind = self._ind
+ if line[-1] == ':':
+ ind -= 1
+ if self._silent_block:
+ ind += 1
+ self._silent_block = line.endswith(')') and CodeWriter._is_cond(line)
+ if add_ind:
+ ind += add_ind
+ print('\t' * ind + line)
+
+ def nl(self):
+ self._nl = True
+
+ def block_start(self, line=''):
+ if line:
+ line = line + ' '
+ self.p(line + '{')
+ self._ind += 1
+
+ def block_end(self, line=''):
+ if line and line[0] not in {';', ','}:
+ line = ' ' + line
+ self._ind -= 1
+ self.p('}' + line)
+
+ def write_func_prot(self, qual_ret, name, args=None, doc=None, suffix=''):
+ if not args:
+ args = ['void']
+
+ if doc:
+ self.p('/*')
+ self.p(' * ' + doc)
+ self.p(' */')
+
+ oneline = qual_ret
+ if qual_ret[-1] != '*':
+ oneline += ' '
+ oneline += f"{name}({', '.join(args)}){suffix}"
+
+ if len(oneline) < 80:
+ self.p(oneline)
+ return
+
+ v = qual_ret
+ if len(v) > 3:
+ self.p(v)
+ v = ''
+ elif qual_ret[-1] != '*':
+ v += ' '
+ v += name + '('
+ ind = '\t' * (len(v) // 8) + ' ' * (len(v) % 8)
+ delta_ind = len(v) - len(ind)
+ v += args[0]
+ i = 1
+ while i < len(args):
+ next_len = len(v) + len(args[i])
+ if v[0] == '\t':
+ next_len += delta_ind
+ if next_len > 76:
+ self.p(v + ',')
+ v = ind
+ else:
+ v += ', '
+ v += args[i]
+ i += 1
+ self.p(v + ')' + suffix)
+
+ def write_func_lvar(self, local_vars):
+ if not local_vars:
+ return
+
+ if type(local_vars) is str:
+ local_vars = [local_vars]
+
+ local_vars.sort(key=len, reverse=True)
+ for var in local_vars:
+ self.p(var)
+ self.nl()
+
+ def write_func(self, qual_ret, name, body, args=None, local_vars=None):
+ self.write_func_prot(qual_ret=qual_ret, name=name, args=args)
+ self.write_func_lvar(local_vars=local_vars)
+
+ self.block_start()
+ for line in body:
+ self.p(line)
+ self.block_end()
+
+ def writes_defines(self, defines):
+ longest = 0
+ for define in defines:
+ if len(define[0]) > longest:
+ longest = len(define[0])
+ longest = ((longest + 8) // 8) * 8
+ for define in defines:
+ line = '#define ' + define[0]
+ line += '\t' * ((longest - len(define[0]) + 7) // 8)
+ if type(define[1]) is int:
+ line += str(define[1])
+ elif type(define[1]) is str:
+ line += '"' + define[1] + '"'
+ self.p(line)
+
+
+scalars = {'u8', 'u16', 'u32', 'u64', 's32', 's64'}
+
+direction_to_suffix = {
+ 'reply': '_rsp',
+ 'request': '_req',
+ '': ''
+}
+
+op_mode_to_wrapper = {
+ 'do': '',
+ 'dump': '_list',
+ 'notify': '_ntf',
+ 'event': '',
+}
+
+c_kw = {
+ 'do'
+}
+
+
+def rdir(direction):
+ if direction == 'reply':
+ return 'request'
+ if direction == 'request':
+ return 'reply'
+ return direction
+
+
+def op_prefix(ri, direction, deref=False):
+ suffix = f"_{ri.type_name}"
+
+ if not ri.op_mode or ri.op_mode == 'do':
+ suffix += f"{direction_to_suffix[direction]}"
+ else:
+ if direction == 'request':
+ suffix += '_req_dump'
+ else:
+ if ri.type_consistent:
+ if deref:
+ suffix += f"{direction_to_suffix[direction]}"
+ else:
+ suffix += op_mode_to_wrapper[ri.op_mode]
+ else:
+ suffix += '_rsp'
+ suffix += '_dump' if deref else '_list'
+
+ return f"{ri.family['name']}{suffix}"
+
+
+def type_name(ri, direction, deref=False):
+ return f"struct {op_prefix(ri, direction, deref=deref)}"
+
+
+def print_prototype(ri, direction, terminate=True, doc=None):
+ suffix = ';' if terminate else ''
+
+ fname = ri.op.render_name
+ if ri.op_mode == 'dump':
+ fname += '_dump'
+
+ args = ['struct ynl_sock *ys']
+ if 'request' in ri.op[ri.op_mode]:
+ args.append(f"{type_name(ri, direction)} *" + f"{direction_to_suffix[direction][1:]}")
+
+ ret = 'int'
+ if 'reply' in ri.op[ri.op_mode]:
+ ret = f"{type_name(ri, rdir(direction))} *"
+
+ ri.cw.write_func_prot(ret, fname, args, doc=doc, suffix=suffix)
+
+
+def print_req_prototype(ri):
+ print_prototype(ri, "request", doc=ri.op['doc'])
+
+
+def print_dump_prototype(ri):
+ print_prototype(ri, "request")
+
+
+def put_typol_fwd(cw, struct):
+ cw.p(f'extern struct ynl_policy_nest {struct.render_name}_nest;')
+
+
+def put_typol(cw, struct):
+ type_max = struct.attr_set.max_name
+ cw.block_start(line=f'struct ynl_policy_attr {struct.render_name}_policy[{type_max} + 1] =')
+
+ for _, arg in struct.member_list():
+ arg.attr_typol(cw)
+
+ cw.block_end(line=';')
+ cw.nl()
+
+ cw.block_start(line=f'struct ynl_policy_nest {struct.render_name}_nest =')
+ cw.p(f'.max_attr = {type_max},')
+ cw.p(f'.table = {struct.render_name}_policy,')
+ cw.block_end(line=';')
+ cw.nl()
+
+
+def put_req_nested(ri, struct):
+ func_args = ['struct nlmsghdr *nlh',
+ 'unsigned int attr_type',
+ f'{struct.ptr_name}obj']
+
+ ri.cw.write_func_prot('int', f'{struct.render_name}_put', func_args)
+ ri.cw.block_start()
+ ri.cw.write_func_lvar('struct nlattr *nest;')
+
+ ri.cw.p("nest = mnl_attr_nest_start(nlh, attr_type);")
+
+ for _, arg in struct.member_list():
+ arg.attr_put(ri, "obj")
+
+ ri.cw.p("mnl_attr_nest_end(nlh, nest);")
+
+ ri.cw.nl()
+ ri.cw.p('return 0;')
+ ri.cw.block_end()
+ ri.cw.nl()
+
+
+def _multi_parse(ri, struct, init_lines, local_vars):
+ if struct.nested:
+ iter_line = "mnl_attr_for_each_nested(attr, nested)"
+ else:
+ iter_line = "mnl_attr_for_each(attr, nlh, sizeof(struct genlmsghdr))"
+
+ array_nests = set()
+ multi_attrs = set()
+ needs_parg = False
+ for arg, aspec in struct.member_list():
+ if aspec['type'] == 'array-nest':
+ local_vars.append(f'const struct nlattr *attr_{aspec.c_name};')
+ array_nests.add(arg)
+ if 'multi-attr' in aspec:
+ multi_attrs.add(arg)
+ needs_parg |= 'nested-attributes' in aspec
+ if array_nests or multi_attrs:
+ local_vars.append('int i;')
+ if needs_parg:
+ local_vars.append('struct ynl_parse_arg parg;')
+ init_lines.append('parg.ys = yarg->ys;')
+
+ ri.cw.block_start()
+ ri.cw.write_func_lvar(local_vars)
+
+ for line in init_lines:
+ ri.cw.p(line)
+ ri.cw.nl()
+
+ for arg in struct.inherited:
+ ri.cw.p(f'dst->{arg} = {arg};')
+
+ ri.cw.nl()
+ ri.cw.block_start(line=iter_line)
+
+ first = True
+ for _, arg in struct.member_list():
+ arg.attr_get(ri, 'dst', first=first)
+ first = False
+
+ ri.cw.block_end()
+ ri.cw.nl()
+
+ for anest in sorted(array_nests):
+ aspec = struct[anest]
+
+ ri.cw.block_start(line=f"if (dst->n_{aspec.c_name})")
+ ri.cw.p(f"dst->{aspec.c_name} = calloc(dst->n_{aspec.c_name}, sizeof(*dst->{aspec.c_name}));")
+ ri.cw.p('i = 0;')
+ ri.cw.p(f"parg.rsp_policy = &{aspec.nested_render_name}_nest;")
+ ri.cw.block_start(line=f"mnl_attr_for_each_nested(attr, attr_{aspec.c_name})")
+ ri.cw.p(f"parg.data = &dst->{aspec.c_name}[i];")
+ ri.cw.p(f"if ({aspec.nested_render_name}_parse(&parg, attr, mnl_attr_get_type(attr)))")
+ ri.cw.p('return MNL_CB_ERROR;')
+ ri.cw.p('i++;')
+ ri.cw.block_end()
+ ri.cw.block_end()
+ ri.cw.nl()
+
+ for anest in sorted(multi_attrs):
+ aspec = struct[anest]
+ ri.cw.block_start(line=f"if (dst->n_{aspec.c_name})")
+ ri.cw.p(f"dst->{aspec.c_name} = calloc(dst->n_{aspec.c_name}, sizeof(*dst->{aspec.c_name}));")
+ ri.cw.p('i = 0;')
+ if 'nested-attributes' in aspec:
+ ri.cw.p(f"parg.rsp_policy = &{aspec.nested_render_name}_nest;")
+ ri.cw.block_start(line=iter_line)
+ ri.cw.block_start(line=f"if (mnl_attr_get_type(attr) == {aspec.enum_name})")
+ if 'nested-attributes' in aspec:
+ ri.cw.p(f"parg.data = &dst->{aspec.c_name}[i];")
+ ri.cw.p(f"if ({aspec.nested_render_name}_parse(&parg, attr))")
+ ri.cw.p('return MNL_CB_ERROR;')
+ elif aspec['type'] in scalars:
+ t = aspec['type']
+ if t[0] == 's':
+ t = 'u' + t[1:]
+ ri.cw.p(f"dst->{aspec.c_name}[i] = mnl_attr_get_{t}(attr);")
+ else:
+ raise Exception('Nest parsing type not supported yet')
+ ri.cw.p('i++;')
+ ri.cw.block_end()
+ ri.cw.block_end()
+ ri.cw.block_end()
+ ri.cw.nl()
+
+ if struct.nested:
+ ri.cw.p('return 0;')
+ else:
+ ri.cw.p('return MNL_CB_OK;')
+ ri.cw.block_end()
+ ri.cw.nl()
+
+
+def parse_rsp_nested(ri, struct):
+ func_args = ['struct ynl_parse_arg *yarg',
+ 'const struct nlattr *nested']
+ for arg in struct.inherited:
+ func_args.append('__u32 ' + arg)
+
+ local_vars = ['const struct nlattr *attr;',
+ f'{struct.ptr_name}dst = yarg->data;']
+ init_lines = []
+
+ ri.cw.write_func_prot('int', f'{struct.render_name}_parse', func_args)
+
+ _multi_parse(ri, struct, init_lines, local_vars)
+
+
+def parse_rsp_msg(ri, deref=False):
+ if 'reply' not in ri.op[ri.op_mode] and ri.op_mode != 'event':
+ return
+
+ func_args = ['const struct nlmsghdr *nlh',
+ 'void *data']
+
+ local_vars = [f'{type_name(ri, "reply", deref=deref)} *dst;',
+ 'struct ynl_parse_arg *yarg = data;',
+ 'const struct nlattr *attr;']
+ init_lines = ['dst = yarg->data;']
+
+ ri.cw.write_func_prot('int', f'{op_prefix(ri, "reply", deref=deref)}_parse', func_args)
+
+ _multi_parse(ri, ri.struct["reply"], init_lines, local_vars)
+
+
+def print_req(ri):
+ ret_ok = '0'
+ ret_err = '-1'
+ direction = "request"
+ local_vars = ['struct nlmsghdr *nlh;',
+ 'int len, err;']
+
+ if 'reply' in ri.op[ri.op_mode]:
+ ret_ok = 'rsp'
+ ret_err = 'NULL'
+ local_vars += [f'{type_name(ri, rdir(direction))} *rsp;',
+ 'struct ynl_parse_arg yarg = { .ys = ys, };']
+
+ print_prototype(ri, direction, terminate=False)
+ ri.cw.block_start()
+ ri.cw.write_func_lvar(local_vars)
+
+ ri.cw.p(f"nlh = ynl_gemsg_start_req(ys, {ri.nl.get_family_id()}, {ri.op.enum_name}, 1);")
+
+ ri.cw.p(f"ys->req_policy = &{ri.struct['request'].render_name}_nest;")
+ if 'reply' in ri.op[ri.op_mode]:
+ ri.cw.p(f"yarg.rsp_policy = &{ri.struct['reply'].render_name}_nest;")
+ ri.cw.nl()
+ for _, attr in ri.struct["request"].member_list():
+ attr.attr_put(ri, "req")
+ ri.cw.nl()
+
+ ri.cw.p('err = mnl_socket_sendto(ys->sock, nlh, nlh->nlmsg_len);')
+ ri.cw.p('if (err < 0)')
+ ri.cw.p(f"return {ret_err};")
+ ri.cw.nl()
+ ri.cw.p('len = mnl_socket_recvfrom(ys->sock, ys->rx_buf, MNL_SOCKET_BUFFER_SIZE);')
+ ri.cw.p('if (len < 0)')
+ ri.cw.p(f"return {ret_err};")
+ ri.cw.nl()
+
+ if 'reply' in ri.op[ri.op_mode]:
+ ri.cw.p('rsp = calloc(1, sizeof(*rsp));')
+ ri.cw.p('yarg.data = rsp;')
+ ri.cw.nl()
+ ri.cw.p(f"err = {ri.nl.parse_cb_run(op_prefix(ri, 'reply') + '_parse', '&yarg', False)};")
+ ri.cw.p('if (err < 0)')
+ ri.cw.p('goto err_free;')
+ ri.cw.nl()
+
+ ri.cw.p('err = ynl_recv_ack(ys, err);')
+ ri.cw.p('if (err)')
+ ri.cw.p('goto err_free;')
+ ri.cw.nl()
+ ri.cw.p(f"return {ret_ok};")
+ ri.cw.nl()
+ ri.cw.p('err_free:')
+
+ if 'reply' in ri.op[ri.op_mode]:
+ ri.cw.p(f"{call_free(ri, rdir(direction), 'rsp')}")
+ ri.cw.p(f"return {ret_err};")
+ ri.cw.block_end()
+
+
+def print_dump(ri):
+ direction = "request"
+ print_prototype(ri, direction, terminate=False)
+ ri.cw.block_start()
+ local_vars = ['struct ynl_dump_state yds = {};',
+ 'struct nlmsghdr *nlh;',
+ 'int len, err;']
+
+ for var in local_vars:
+ ri.cw.p(f'{var}')
+ ri.cw.nl()
+
+ ri.cw.p('yds.ys = ys;')
+ ri.cw.p(f"yds.alloc_sz = sizeof({type_name(ri, rdir(direction))});")
+ ri.cw.p(f"yds.cb = {op_prefix(ri, 'reply', deref=True)}_parse;")
+ ri.cw.p(f"yds.rsp_policy = &{ri.struct['reply'].render_name}_nest;")
+ ri.cw.nl()
+ ri.cw.p(f"nlh = ynl_gemsg_start_dump(ys, {ri.nl.get_family_id()}, {ri.op.enum_name}, 1);")
+
+ if "request" in ri.op[ri.op_mode]:
+ ri.cw.p(f"ys->req_policy = &{ri.struct['request'].render_name}_nest;")
+ ri.cw.nl()
+ for _, attr in ri.struct["request"].member_list():
+ attr.attr_put(ri, "req")
+ ri.cw.nl()
+
+ ri.cw.p('err = mnl_socket_sendto(ys->sock, nlh, nlh->nlmsg_len);')
+ ri.cw.p('if (err < 0)')
+ ri.cw.p('return NULL;')
+ ri.cw.nl()
+
+ ri.cw.block_start(line='do')
+ ri.cw.p('len = mnl_socket_recvfrom(ys->sock, ys->rx_buf, MNL_SOCKET_BUFFER_SIZE);')
+ ri.cw.p('if (len < 0)')
+ ri.cw.p('goto free_list;')
+ ri.cw.nl()
+ ri.cw.p(f"err = {ri.nl.parse_cb_run('ynl_dump_trampoline', '&yds', False, indent=2)};")
+ ri.cw.p('if (err < 0)')
+ ri.cw.p('goto free_list;')
+ ri.cw.block_end(line='while (err > 0);')
+ ri.cw.nl()
+
+ ri.cw.p('return yds.first;')
+ ri.cw.nl()
+ ri.cw.p('free_list:')
+ ri.cw.p(call_free(ri, rdir(direction), 'yds.first'))
+ ri.cw.p('return NULL;')
+ ri.cw.block_end()
+
+
+def call_free(ri, direction, var):
+ return f"{op_prefix(ri, direction)}_free({var});"
+
+
+def free_arg_name(direction):
+ if direction:
+ return direction_to_suffix[direction][1:]
+ return 'obj'
+
+
+def print_free_prototype(ri, direction, suffix=';'):
+ name = op_prefix(ri, direction)
+ arg = free_arg_name(direction)
+ ri.cw.write_func_prot('void', f"{name}_free", [f"struct {name} *{arg}"], suffix=suffix)
+
+
+def _print_type(ri, direction, struct):
+ suffix = f'_{ri.type_name}{direction_to_suffix[direction]}'
+
+ if ri.op_mode == 'dump':
+ suffix += '_dump'
+
+ ri.cw.block_start(line=f"struct {ri.family['name']}{suffix}")
+
+ meta_started = False
+ for _, attr in struct.member_list():
+ for type_filter in ['len', 'bit']:
+ line = attr.presence_member(ri.ku_space, type_filter)
+ if line:
+ if not meta_started:
+ ri.cw.block_start(line=f"struct")
+ meta_started = True
+ ri.cw.p(line)
+ if meta_started:
+ ri.cw.block_end(line='_present;')
+ ri.cw.nl()
+
+ for arg in struct.inherited:
+ ri.cw.p(f"__u32 {arg};")
+
+ for _, attr in struct.member_list():
+ attr.struct_member(ri)
+
+ ri.cw.block_end(line=';')
+ ri.cw.nl()
+
+
+def print_type(ri, direction):
+ _print_type(ri, direction, ri.struct[direction])
+
+
+def print_type_full(ri, struct):
+ _print_type(ri, "", struct)
+
+
+def print_type_helpers(ri, direction, deref=False):
+ print_free_prototype(ri, direction)
+
+ if ri.ku_space == 'user' and direction == 'request':
+ for _, attr in ri.struct[direction].member_list():
+ attr.setter(ri, ri.attr_set, direction, deref=deref)
+ ri.cw.nl()
+
+
+def print_req_type_helpers(ri):
+ print_type_helpers(ri, "request")
+
+
+def print_rsp_type_helpers(ri):
+ if 'reply' not in ri.op[ri.op_mode]:
+ return
+ print_type_helpers(ri, "reply")
+
+
+def print_parse_prototype(ri, direction, terminate=True):
+ suffix = "_rsp" if direction == "reply" else "_req"
+ term = ';' if terminate else ''
+
+ ri.cw.write_func_prot('void', f"{ri.op.render_name}{suffix}_parse",
+ ['const struct nlattr **tb',
+ f"struct {ri.op.render_name}{suffix} *req"],
+ suffix=term)
+
+
+def print_req_type(ri):
+ print_type(ri, "request")
+
+
+def print_rsp_type(ri):
+ if (ri.op_mode == 'do' or ri.op_mode == 'dump') and 'reply' in ri.op[ri.op_mode]:
+ direction = 'reply'
+ elif ri.op_mode == 'event':
+ direction = 'reply'
+ else:
+ return
+ print_type(ri, direction)
+
+
+def print_wrapped_type(ri):
+ ri.cw.block_start(line=f"{type_name(ri, 'reply')}")
+ if ri.op_mode == 'dump':
+ ri.cw.p(f"{type_name(ri, 'reply')} *next;")
+ elif ri.op_mode == 'notify' or ri.op_mode == 'event':
+ ri.cw.p('__u16 family;')
+ ri.cw.p('__u8 cmd;')
+ ri.cw.p(f"void (*free)({type_name(ri, 'reply')} *ntf);")
+ ri.cw.p(f"{type_name(ri, 'reply', deref=True)} obj __attribute__ ((aligned (8)));")
+ ri.cw.block_end(line=';')
+ ri.cw.nl()
+ print_free_prototype(ri, 'reply')
+ ri.cw.nl()
+
+
+def _free_type_members_iter(ri, struct):
+ for _, attr in struct.member_list():
+ if attr.free_needs_iter():
+ ri.cw.p('unsigned int i;')
+ ri.cw.nl()
+ break
+
+
+def _free_type_members(ri, var, struct, ref=''):
+ for _, attr in struct.member_list():
+ attr.free(ri, var, ref)
+
+
+def _free_type(ri, direction, struct):
+ var = free_arg_name(direction)
+
+ print_free_prototype(ri, direction, suffix='')
+ ri.cw.block_start()
+ _free_type_members_iter(ri, struct)
+ _free_type_members(ri, var, struct)
+ if direction:
+ ri.cw.p(f'free({var});')
+ ri.cw.block_end()
+ ri.cw.nl()
+
+
+def free_rsp_nested(ri, struct):
+ _free_type(ri, "", struct)
+
+
+def print_rsp_free(ri):
+ if 'reply' not in ri.op[ri.op_mode]:
+ return
+ _free_type(ri, 'reply', ri.struct['reply'])
+
+
+def print_dump_type_free(ri):
+ sub_type = type_name(ri, 'reply')
+
+ print_free_prototype(ri, 'reply', suffix='')
+ ri.cw.block_start()
+ ri.cw.p(f"{sub_type} *next = rsp;")
+ ri.cw.nl()
+ ri.cw.block_start(line='while (next)')
+ _free_type_members_iter(ri, ri.struct['reply'])
+ ri.cw.p('rsp = next;')
+ ri.cw.p('next = rsp->next;')
+ ri.cw.nl()
+
+ _free_type_members(ri, 'rsp', ri.struct['reply'], ref='obj.')
+ ri.cw.p(f'free(rsp);')
+ ri.cw.block_end()
+ ri.cw.block_end()
+ ri.cw.nl()
+
+
+def print_ntf_type_free(ri):
+ print_free_prototype(ri, 'reply', suffix='')
+ ri.cw.block_start()
+ _free_type_members_iter(ri, ri.struct['reply'])
+ _free_type_members(ri, 'rsp', ri.struct['reply'], ref='obj.')
+ ri.cw.p(f'free(rsp);')
+ ri.cw.block_end()
+ ri.cw.nl()
+
+
+def print_ntf_parse_prototype(family, cw, suffix=';'):
+ cw.write_func_prot('struct ynl_ntf_base_type *', f"{family['name']}_ntf_parse",
+ ['struct ynl_sock *ys'], suffix=suffix)
+
+
+def print_ntf_type_parse(family, cw, ku_mode):
+ print_ntf_parse_prototype(family, cw, suffix='')
+ cw.block_start()
+ cw.write_func_lvar(['struct genlmsghdr *genlh;',
+ 'struct nlmsghdr *nlh;',
+ 'struct ynl_parse_arg yarg = { .ys = ys, };',
+ 'struct ynl_ntf_base_type *rsp;',
+ 'int len, err;',
+ 'mnl_cb_t parse;'])
+ cw.p('len = mnl_socket_recvfrom(ys->sock, ys->rx_buf, MNL_SOCKET_BUFFER_SIZE);')
+ cw.p('if (len < (ssize_t)(sizeof(*nlh) + sizeof(*genlh)))')
+ cw.p('return NULL;')
+ cw.nl()
+ cw.p('nlh = (struct nlmsghdr *)ys->rx_buf;')
+ cw.p('genlh = mnl_nlmsg_get_payload(nlh);')
+ cw.nl()
+ cw.block_start(line='switch (genlh->cmd)')
+ for ntf_op in sorted(family.all_notify.keys()):
+ op = family.ops[ntf_op]
+ ri = RenderInfo(cw, family, ku_mode, op, ntf_op, "notify")
+ for ntf in op['notify']['cmds']:
+ cw.p(f"case {ntf.enum_name}:")
+ cw.p(f"rsp = calloc(1, sizeof({type_name(ri, 'notify')}));")
+ cw.p(f"parse = {op_prefix(ri, 'reply', deref=True)}_parse;")
+ cw.p(f"yarg.rsp_policy = &{ri.struct['reply'].render_name}_nest;")
+ cw.p(f"rsp->free = (void *){op_prefix(ri, 'notify')}_free;")
+ cw.p('break;')
+ for op_name, op in family.ops.items():
+ if 'event' not in op:
+ continue
+ ri = RenderInfo(cw, family, ku_mode, op, op_name, "event")
+ cw.p(f"case {op.enum_name}:")
+ cw.p(f"rsp = calloc(1, sizeof({type_name(ri, 'event')}));")
+ cw.p(f"parse = {op_prefix(ri, 'reply', deref=True)}_parse;")
+ cw.p(f"yarg.rsp_policy = &{ri.struct['reply'].render_name}_nest;")
+ cw.p(f"rsp->free = (void *){op_prefix(ri, 'notify')}_free;")
+ cw.p('break;')
+ cw.p('default:')
+ cw.p('ynl_error_unknown_notification(ys, genlh->cmd);')
+ cw.p('return NULL;')
+ cw.block_end()
+ cw.nl()
+ cw.p('yarg.data = rsp->data;')
+ cw.nl()
+ cw.p(f"err = {cw.nlib.parse_cb_run('parse', '&yarg', True)};")
+ cw.p('if (err < 0)')
+ cw.p('goto err_free;')
+ cw.nl()
+ cw.p('rsp->family = nlh->nlmsg_type;')
+ cw.p('rsp->cmd = genlh->cmd;')
+ cw.p('return rsp;')
+ cw.nl()
+ cw.p('err_free:')
+ cw.p('free(rsp);')
+ cw.p('return NULL;')
+ cw.block_end()
+ cw.nl()
+
+
+def print_req_policy_fwd(cw, struct, op=None, terminate=True):
+ prefix = 'extern ' if terminate else ''
+ suffix = ';' if terminate else ' = {'
+ max_attr = struct.attr_max_val
+ name = op.render_name if op else struct.render_name
+ cw.p(f"{prefix}const struct nla_policy {name}_policy[{max_attr.enum_name} + 1]{suffix}")
+
+
+def print_req_policy(cw, struct, op=None):
+ print_req_policy_fwd(cw, struct, op=op, terminate=False)
+ for _, arg in struct.member_list():
+ arg.attr_policy(cw)
+ cw.p("};")
+
+
+def print_kernel_op_table_fwd(family, cw, terminate=True):
+ cw.p(f"// Ops table for {family.name}")
+
+ struct_type = 'genl_small_ops' if family.kernel_policy == 'global' else 'genl_ops'
+ cnt = len(family.ops)
+
+ line = f"const struct {struct_type} {family.name}_ops[{cnt}]"
+ if terminate:
+ cw.p(f"extern {line};")
+ else:
+ cw.block_start(line=line + ' =')
+
+ if not terminate:
+ return
+
+ cw.nl()
+ for op_name, op in family.ops.items():
+ if op.is_async:
+ continue
+
+ if 'do' in op:
+ name = c_lower(f"{family.name}-{op_name}-doit")
+ cw.write_func_prot('int', name,
+ ['struct sk_buff *skb', 'struct genl_info *info'], suffix=';')
+
+ if 'dump' in op:
+ name = c_lower(f"{family.name}-{op_name}-dumpit")
+ cw.write_func_prot('int', name,
+ ['struct sk_buff *skb', 'struct netlink_callback *cb'], suffix=';')
+ cw.nl()
+
+
+def print_kernel_op_table(family, cw):
+ print_kernel_op_table_fwd(family, cw, terminate=False)
+ for op_name, op in family.ops.items():
+ if op.is_async:
+ continue
+
+ cw.block_start()
+ cw.p(f".cmd = {op.enum_name},")
+ if 'dont-validate' in op:
+ cw.p(f".validate = {' | '.join([c_upper('genl-dont-validate-' + x) for x in op['dont-validate']])},")
+ for op_mode in ['do', 'dump']:
+ if op_mode in op:
+ name = c_lower(f"{family.name}-{op_name}-{op_mode}it")
+ cw.p(f".{op_mode}it = {name},")
+ if family.kernel_policy == 'per-op':
+ name = c_lower(f"{family.name}-{op_name}-policy")
+ cw.p(f".policy = {name},")
+ if 'flags' in op:
+ cw.p(f".flags = {' | '.join([c_upper('genl-' + x) for x in op['flags']])},")
+ cw.block_end(line=',')
+ cw.block_end(line=';')
+ cw.nl()
+
+
+def uapi_enum_start(family, cw, obj, ckey='', enum_name='enum-name'):
+ start_line = 'enum'
+ if enum_name in obj:
+ if obj[enum_name]:
+ start_line = 'enum ' + obj[enum_name].replace('-', '_')
+ elif ckey and ckey in obj:
+ start_line = 'enum ' + family.name + '_' + obj[ckey].replace('-', '_')
+ cw.block_start(line=start_line)
+
+
+def render_uapi(family, cw):
+ hdr_prot = f"_UAPI_LINUX_{family.name.upper()}_H"
+ cw.p('#ifndef ' + hdr_prot)
+ cw.p('#define ' + hdr_prot)
+ cw.nl()
+
+ fam_key = c_upper(family.get('c-family-name', family["name"] + '_FAMILY_NAME'))
+ ver_key = c_upper(family.get('c-version-name', family["name"] + '_FAMILY_VERSION'))
+ defines = [(fam_key, family["name"]),
+ (ver_key, family.get('version', 1))]
+ cw.writes_defines(defines)
+ cw.nl()
+
+ for const in family['definitions']:
+ if const['type'] == 'enum':
+ uapi_enum_start(family, cw, const, 'name')
+ first = True
+ for item in const['entries']:
+ suffix = ','
+ if first and 'value-start' in const:
+ suffix = f" = {const['value-start']}" + suffix
+ first = False
+ item_name = item
+ if 'name-prefix' in const:
+ item_name = c_upper(const['name-prefix'] + item)
+ cw.p(item_name + suffix)
+ cw.block_end(line=';')
+ cw.nl()
+ elif const['type'] == 'flags':
+ uapi_enum_start(family, cw, const, 'name')
+ i = const.get('value-start', 0)
+ for item in const['entries']:
+ item_name = item
+ if 'name-prefix' in const:
+ item_name = c_upper(const['name-prefix'] + item)
+ cw.p(f'{item_name} = {1 << i},')
+ i += 1
+ cw.block_end(line=';')
+ cw.nl()
+
+ max_by_define = family.get('max-by-define', False)
+
+ for _, attr_set in family.attr_sets_list:
+ if attr_set.subset_of:
+ continue
+
+ cnt_name = c_upper(family.get('attr-cnt-name', f"__{attr_set.name_prefix}MAX"))
+ max_value = f"({cnt_name} - 1)"
+
+ val = 0
+ uapi_enum_start(family, cw, attr_set.yaml, 'enum-name')
+ for _, attr in attr_set.items():
+ suffix = ','
+ if attr['value'] != val:
+ suffix = f" = {attr['value']},"
+ val = attr['value']
+ val += 1
+ cw.p(attr.enum_name + suffix)
+ cw.nl()
+ cw.p(cnt_name + ('' if max_by_define else ','))
+ if not max_by_define:
+ cw.p(f"{attr_set.max_name} = {max_value}")
+ cw.block_end(line=';')
+ if max_by_define:
+ cw.p(f"#define {attr_set.max_name} {max_value}")
+ cw.nl()
+
+ # Commands
+ separate_ntf = 'async-prefix' in family['operations']
+
+ max_name = c_upper(family.get('cmd-max-name', f"{family.op_prefix}MAX"))
+ cnt_name = c_upper(family.get('cmd-cnt-name', f"__{family.op_prefix}MAX"))
+ max_value = f"({cnt_name} - 1)"
+
+ uapi_enum_start(family, cw, family['operations'], 'enum-name')
+ for _, op in family.ops_list:
+ if separate_ntf and ('notify' in op or 'event' in op):
+ continue
+
+ suffix = ','
+ if 'value' in op:
+ suffix = f" = {op['value']},"
+ cw.p(op.enum_name + suffix)
+ cw.nl()
+ cw.p(cnt_name + ('' if max_by_define else ','))
+ if not max_by_define:
+ cw.p(f"{max_name} = {max_value}")
+ cw.block_end(line=';')
+ if max_by_define:
+ cw.p(f"#define {max_name} {max_value}")
+ cw.nl()
+
+ if separate_ntf:
+ uapi_enum_start(family, cw, family['operations'], enum_name='async-enum')
+ for _, op in family.ops_list:
+ if separate_ntf and not ('notify' in op or 'event' in op):
+ continue
+
+ suffix = ','
+ if 'value' in op:
+ suffix = f" = {op['value']},"
+ cw.p(op.enum_name + suffix)
+ cw.block_end(line=';')
+ cw.nl()
+
+ # Multicast
+ grps = family.get('mcast-groups', {'list': []})
+ defines = []
+ for grp in grps['list']:
+ name = grp['name']
+ defines.append([c_upper(grp.get('c-define-name', f"{family.name}-mcgrp-{name}")),
+ f'{name}'])
+ cw.nl()
+ if defines:
+ cw.writes_defines(defines)
+ cw.nl()
+
+ cw.p(f'#endif /* {hdr_prot} */')
+
+
+def find_kernel_root(full_path):
+ sub_path = ''
+ while True:
+ sub_path = os.path.join(os.path.basename(full_path), sub_path)
+ full_path = os.path.dirname(full_path)
+ maintainers = os.path.join(full_path, "MAINTAINERS")
+ if os.path.exists(maintainers):
+ return full_path, sub_path[:-1]
+
+
+def main():
+ parser = argparse.ArgumentParser(description='Netlink simple parsing generator')
+ parser.add_argument('--mode', dest='mode', type=str, required=True)
+ parser.add_argument('--spec', dest='spec', type=str, required=True)
+ parser.add_argument('--header', dest='header', action='store_true', default=None)
+ parser.add_argument('--source', dest='header', action='store_false')
+ parser.add_argument('--user-header', nargs='+', default=[])
+ args = parser.parse_args()
+
+ if args.header is None:
+ parser.error("--header or --source is required")
+
+ try:
+ parsed = Family(args.spec)
+ except yaml.YAMLError as exc:
+ print(exc)
+ os.sys.exit(1)
+ return
+
+ cw = CodeWriter(BaseNlLib())
+
+ _, spec_kernel = find_kernel_root(args.spec)
+ if args.mode == 'uapi':
+ cw.p('/* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */')
+ else:
+ cw.p('// SPDX-License-Identifier: BSD-3-Clause')
+ cw.p("// Do not edit directly, auto-generated from:")
+ cw.p(f"//\t{spec_kernel}")
+ cw.p(f"// YNL-GEN {args.mode} {'header' if args.header else 'source'}")
+ cw.nl()
+
+ if args.mode == 'uapi':
+ render_uapi(parsed, cw)
+ return
+
+ hdr_prot = f"_LINUX_{parsed.name.upper()}_GEN_H"
+ if args.header:
+ cw.p('#ifndef ' + hdr_prot)
+ cw.p('#define ' + hdr_prot)
+ cw.nl()
+
+ if args.mode == 'kernel':
+ cw.p('#include <net/netlink.h>')
+ cw.p('#include <net/genetlink.h>')
+ cw.nl()
+ if not args.header:
+ cw.p(f'#include "{parsed.name}-nl.h"')
+ cw.nl()
+ headers = [parsed.uapi_header]
+ for definition in parsed['definitions']:
+ if 'header' in definition:
+ headers.append(definition['header'])
+ for one in headers:
+ cw.p(f"#include <{one}>")
+ cw.nl()
+
+ if args.mode == "user":
+ if not args.header:
+ cw.p("#include <stdlib.h>")
+ cw.p("#include <stdio.h>")
+ cw.p("#include <string.h>")
+ cw.p("#include <libmnl/libmnl.h>")
+ cw.p("#include <linux/genetlink.h>")
+ cw.nl()
+ for one in args.user_header:
+ cw.p(f'#include "{one}"')
+ else:
+ cw.p('struct ynl_sock;')
+ cw.nl()
+
+ if args.mode == "kernel":
+ if args.header:
+ if parsed.kernel_policy == 'global':
+ cw.p(f"// Global operation policy for {parsed.name}")
+
+ struct = Struct(parsed, parsed.global_policy_set, type_list=parsed.global_policy)
+ print_req_policy_fwd(cw, struct)
+ cw.nl()
+
+ for op_name, op in parsed.ops.items():
+ if parsed.kernel_policy == 'per-op' and 'do' in op and 'event' not in op:
+ cw.p(f"// {op.enum_name} - do")
+ ri = RenderInfo(cw, parsed, args.mode, op, op_name, "do")
+ print_req_policy_fwd(cw, ri.struct['request'], op=op)
+ cw.nl()
+
+ print_kernel_op_table_fwd(parsed, cw)
+ else:
+ if parsed.kernel_policy == 'global':
+ cw.p(f"// Global operation policy for {parsed.name}")
+
+ struct = Struct(parsed, parsed.global_policy_set, type_list=parsed.global_policy)
+ print_req_policy(cw, struct)
+ cw.nl()
+
+ for op_name, op in parsed.ops.items():
+ if parsed.kernel_policy == 'per-op':
+ for op_mode in {'do', 'dump'}:
+ if op_mode in op and 'request' in op[op_mode]:
+ cw.p(f"// {op.enum_name} - {op_mode}")
+ ri = RenderInfo(cw, parsed, args.mode, op, op_name, op_mode)
+ print_req_policy(cw, ri.struct['request'], op=op)
+ cw.nl()
+
+ print_kernel_op_table(parsed, cw)
+
+ if args.mode == "user":
+ has_ntf = False
+ if args.header:
+ cw.p('// Common nested types')
+ for attr_set, struct in sorted(parsed.pure_nested_structs.items()):
+ ri = RenderInfo(cw, parsed, args.mode, "", "", "", attr_set)
+ print_type_full(ri, struct)
+
+ for op_name, op in parsed.ops.items():
+ cw.p(f"/* ============== {op.enum_name} ============== */")
+
+ if 'do' in op and 'event' not in op:
+ cw.p(f"// {op.enum_name} - do")
+ ri = RenderInfo(cw, parsed, args.mode, op, op_name, "do")
+ print_req_type(ri)
+ print_req_type_helpers(ri)
+ cw.nl()
+ print_rsp_type(ri)
+ print_rsp_type_helpers(ri)
+ cw.nl()
+ print_req_prototype(ri)
+ cw.nl()
+
+ if 'dump' in op:
+ cw.p(f"// {op.enum_name} - dump")
+ ri = RenderInfo(cw, parsed, args.mode, op, op_name, 'dump')
+ if 'request' in op['dump']:
+ print_req_type(ri)
+ print_req_type_helpers(ri)
+ if not ri.type_consistent:
+ print_rsp_type(ri)
+ print_wrapped_type(ri)
+ print_dump_prototype(ri)
+ cw.nl()
+
+ if 'notify' in op:
+ cw.p(f"// {op.enum_name} - notify")
+ ri = RenderInfo(cw, parsed, args.mode, op, op_name, 'notify')
+ has_ntf = True
+ if not ri.type_consistent:
+ raise Exception('Only notifications with consistent types supported')
+ print_wrapped_type(ri)
+
+ if 'event' in op:
+ ri = RenderInfo(cw, parsed, args.mode, op, op_name, 'event')
+ cw.p(f"// {op.enum_name} - event")
+ print_rsp_type(ri)
+ cw.nl()
+ print_wrapped_type(ri)
+
+ if has_ntf:
+ cw.p('// --------------- Common notification parsing --------------- //')
+ print_ntf_parse_prototype(parsed, cw)
+ cw.nl()
+ else:
+ cw.p('// Policies')
+ for name, _ in parsed.attr_sets.items():
+ struct = Struct(parsed, name)
+ put_typol_fwd(cw, struct)
+ cw.nl()
+
+ for name, _ in parsed.attr_sets.items():
+ struct = Struct(parsed, name)
+ put_typol(cw, struct)
+
+ cw.p('// Common nested types')
+ for attr_set, struct in sorted(parsed.pure_nested_structs.items()):
+ ri = RenderInfo(cw, parsed, args.mode, "", "", "", attr_set)
+
+ free_rsp_nested(ri, struct)
+ if struct.request:
+ put_req_nested(ri, struct)
+ if struct.reply:
+ parse_rsp_nested(ri, struct)
+
+ for op_name, op in parsed.ops.items():
+ cw.p(f"/* ============== {op.enum_name} ============== */")
+ if 'do' in op and 'event' not in op:
+ cw.p(f"// {op.enum_name} - do")
+ ri = RenderInfo(cw, parsed, args.mode, op, op_name, "do")
+ print_rsp_free(ri)
+ parse_rsp_msg(ri)
+ print_req(ri)
+ cw.nl()
+
+ if 'dump' in op:
+ cw.p(f"// {op.enum_name} - dump")
+ ri = RenderInfo(cw, parsed, args.mode, op, op_name, "dump")
+ if not ri.type_consistent:
+ parse_rsp_msg(ri, deref=True)
+ print_dump_type_free(ri)
+ print_dump(ri)
+ cw.nl()
+
+ if 'notify' in op:
+ cw.p(f"// {op.enum_name} - notify")
+ ri = RenderInfo(cw, parsed, args.mode, op, op_name, 'notify')
+ has_ntf = True
+ if not ri.type_consistent:
+ raise Exception('Only notifications with consistent types supported')
+ print_ntf_type_free(ri)
+
+ if 'event' in op:
+ cw.p(f"// {op.enum_name} - event")
+ has_ntf = True
+
+ ri = RenderInfo(cw, parsed, args.mode, op, op_name, "do")
+ parse_rsp_msg(ri)
+
+ ri = RenderInfo(cw, parsed, args.mode, op, op_name, "event")
+ print_ntf_type_free(ri)
+
+ if has_ntf:
+ cw.p('// --------------- Common notification parsing --------------- //')
+ print_ntf_type_parse(parsed, cw, args.mode)
+
+ if args.header:
+ cw.p(f'#endif /* {hdr_prot} */')
+
+
+if __name__ == "__main__":
+ main()
diff --git a/tools/net/ynl/ynl-regen.sh b/tools/net/ynl/ynl-regen.sh
new file mode 100755
index 000000000000..5664c60f0964
--- /dev/null
+++ b/tools/net/ynl/ynl-regen.sh
@@ -0,0 +1,30 @@
+#!/bin/bash
+# SPDX-License-Identifier: BSD-3-Clause
+
+TOOL=$(dirname $(realpath $0))/ynl-gen-c.py
+
+force=
+
+while [ ! -z "$1" ]; do
+ case "$1" in
+ -f ) force=yes; shift ;;
+ * ) echo "Unrecognized option '$1'"; exit 1 ;;
+ esac
+done
+
+KDIR=$(dirname $(dirname $(dirname $(dirname $(realpath $0)))))
+
+files=$(git grep --files-with-matches '^// YNL-GEN \(kernel\|uapi\)')
+for f in $files; do
+ # params: 0 1 2 3 4 5
+ # // $YAML // YNL-GEN kernel $mode
+ params=( $(git grep -B1 -h '// YNL-GEN' $f) )
+
+ if [ $f -nt ${params[1]} -a -z "$force" ]; then
+ echo -e "\tSKIP $f"
+ continue
+ fi
+
+ echo -e "\tGEN ${params[4]}\t$f"
+ $TOOL --mode ${params[4]} --${params[5]} --spec $KDIR/${params[1]} > $f
+done
--
2.37.3
^ permalink raw reply related [flat|nested] 17+ messages in thread
* [PATCH net-next 4/6] netlink: add a proto specification for FOU
2022-09-29 1:11 [PATCH net-next 0/6] Netlink protocol specs Jakub Kicinski
` (2 preceding siblings ...)
2022-09-29 1:11 ` [PATCH net-next 3/6] net: add basic C code generators for Netlink Jakub Kicinski
@ 2022-09-29 1:11 ` Jakub Kicinski
2022-09-29 9:02 ` Nicolas Dichtel
2022-09-29 1:11 ` [PATCH net-next 5/6] net: fou: regenerate the uAPI from the spec Jakub Kicinski
2022-09-29 1:11 ` [PATCH net-next 6/6] net: fou: use policy and operation tables generated " Jakub Kicinski
5 siblings, 1 reply; 17+ messages in thread
From: Jakub Kicinski @ 2022-09-29 1:11 UTC (permalink / raw)
To: davem
Cc: netdev, edumazet, pabeni, robh, johannes, ecree.xilinx, stephen,
sdf, f.fainelli, fw, linux-doc, razor, nicolas.dichtel, gnault,
Jakub Kicinski
FOU has a reasonably modern Genetlink family. Add a spec.
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
---
Documentation/netlink/specs/fou.yaml | 128 +++++++++++++++++++++++++++
1 file changed, 128 insertions(+)
create mode 100644 Documentation/netlink/specs/fou.yaml
diff --git a/Documentation/netlink/specs/fou.yaml b/Documentation/netlink/specs/fou.yaml
new file mode 100644
index 000000000000..266c386eedf3
--- /dev/null
+++ b/Documentation/netlink/specs/fou.yaml
@@ -0,0 +1,128 @@
+name: fou
+
+protocol: genetlink-legacy
+
+doc: |
+ Foo-over-UDP.
+
+c-family-name: fou-genl-name
+c-version-name: fou-genl-version
+max-by-define: true
+kernel-policy: global
+
+definitions:
+ -
+ type: enum
+ name: encap_type
+ name-prefix: fou-encap-
+ enum-name:
+ entries: [ unspec, direct, gue ]
+
+attribute-sets:
+ -
+ name: fou
+ name-prefix: fou-attr-
+ attributes:
+ -
+ name: unspec
+ type: unused
+ -
+ name: port
+ type: u16
+ byte-order: big-endian
+ -
+ name: af
+ type: u8
+ -
+ name: ipproto
+ type: u8
+ -
+ name: type
+ type: u8
+ -
+ name: remcsum_nopartial
+ type: flag
+ -
+ name: local_v4
+ type: u32
+ -
+ name: local_v6
+ type: binary
+ checks:
+ min-len: 16
+ -
+ name: peer_v4
+ type: u32
+ -
+ name: peer_v6
+ type: binary
+ checks:
+ min-len: 16
+ -
+ name: peer_port
+ type: u16
+ byte-order: big-endian
+ -
+ name: ifindex
+ type: s32
+
+operations:
+ list:
+ -
+ name: unspec
+ doc: unused
+
+ -
+ name: add
+ doc: Add port.
+ attribute-set: fou
+
+ dont-validate: [ strict, dump ]
+ flags: [ admin-perm ]
+
+ do:
+ request: &all_attrs
+ attributes:
+ - port
+ - ipproto
+ - type
+ - remcsum_nopartial
+ - local_v4
+ - peer_v4
+ - local_v6
+ - peer_v6
+ - peer_port
+ - ifindex
+
+ -
+ name: del
+ doc: Delete port.
+ attribute-set: fou
+
+ dont-validate: [ strict, dump ]
+ flags: [ admin-perm ]
+
+ do:
+ request: &select_attrs
+ attributes:
+ - af
+ - ifindex
+ - port
+ - peer_port
+ - local_v4
+ - peer_v4
+ - local_v6
+ - peer_v6
+
+ -
+ name: get
+ doc: Get tunnel info.
+ attribute-set: fou
+ dont-validate: [ strict, dump ]
+
+ do:
+ request: *select_attrs
+ reply: *all_attrs
+
+ dump:
+ reply: *all_attrs
--
2.37.3
^ permalink raw reply related [flat|nested] 17+ messages in thread
* [PATCH net-next 5/6] net: fou: regenerate the uAPI from the spec
2022-09-29 1:11 [PATCH net-next 0/6] Netlink protocol specs Jakub Kicinski
` (3 preceding siblings ...)
2022-09-29 1:11 ` [PATCH net-next 4/6] netlink: add a proto specification for FOU Jakub Kicinski
@ 2022-09-29 1:11 ` Jakub Kicinski
2022-09-29 1:11 ` [PATCH net-next 6/6] net: fou: use policy and operation tables generated " Jakub Kicinski
5 siblings, 0 replies; 17+ messages in thread
From: Jakub Kicinski @ 2022-09-29 1:11 UTC (permalink / raw)
To: davem
Cc: netdev, edumazet, pabeni, robh, johannes, ecree.xilinx, stephen,
sdf, f.fainelli, fw, linux-doc, razor, nicolas.dichtel, gnault,
Jakub Kicinski
Regenerate the FOU uAPI header from the YAML spec.
The flags now come before attributes which use them,
and the comments for type disappear (coders should look
at the spec instead).
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
---
include/uapi/linux/fou.h | 54 +++++++++++++++++++---------------------
1 file changed, 26 insertions(+), 28 deletions(-)
diff --git a/include/uapi/linux/fou.h b/include/uapi/linux/fou.h
index 87c2c9f08803..c7d90d4e1428 100644
--- a/include/uapi/linux/fou.h
+++ b/include/uapi/linux/fou.h
@@ -1,32 +1,37 @@
/* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
-/* fou.h - FOU Interface */
+// Do not edit directly, auto-generated from:
+// Documentation/netlink/specs/fou.yaml
+// YNL-GEN uapi header
#ifndef _UAPI_LINUX_FOU_H
#define _UAPI_LINUX_FOU_H
-/* NETLINK_GENERIC related info
- */
#define FOU_GENL_NAME "fou"
-#define FOU_GENL_VERSION 0x1
+#define FOU_GENL_VERSION 1
enum {
- FOU_ATTR_UNSPEC,
- FOU_ATTR_PORT, /* u16 */
- FOU_ATTR_AF, /* u8 */
- FOU_ATTR_IPPROTO, /* u8 */
- FOU_ATTR_TYPE, /* u8 */
- FOU_ATTR_REMCSUM_NOPARTIAL, /* flag */
- FOU_ATTR_LOCAL_V4, /* u32 */
- FOU_ATTR_LOCAL_V6, /* in6_addr */
- FOU_ATTR_PEER_V4, /* u32 */
- FOU_ATTR_PEER_V6, /* in6_addr */
- FOU_ATTR_PEER_PORT, /* u16 */
- FOU_ATTR_IFINDEX, /* s32 */
-
- __FOU_ATTR_MAX,
+ FOU_ENCAP_UNSPEC,
+ FOU_ENCAP_DIRECT,
+ FOU_ENCAP_GUE,
};
-#define FOU_ATTR_MAX (__FOU_ATTR_MAX - 1)
+enum {
+ FOU_ATTR_UNSPEC,
+ FOU_ATTR_PORT,
+ FOU_ATTR_AF,
+ FOU_ATTR_IPPROTO,
+ FOU_ATTR_TYPE,
+ FOU_ATTR_REMCSUM_NOPARTIAL,
+ FOU_ATTR_LOCAL_V4,
+ FOU_ATTR_LOCAL_V6,
+ FOU_ATTR_PEER_V4,
+ FOU_ATTR_PEER_V6,
+ FOU_ATTR_PEER_PORT,
+ FOU_ATTR_IFINDEX,
+
+ __FOU_ATTR_MAX
+};
+#define FOU_ATTR_MAX (__FOU_ATTR_MAX - 1)
enum {
FOU_CMD_UNSPEC,
@@ -34,15 +39,8 @@ enum {
FOU_CMD_DEL,
FOU_CMD_GET,
- __FOU_CMD_MAX,
+ __FOU_CMD_MAX
};
-
-enum {
- FOU_ENCAP_UNSPEC,
- FOU_ENCAP_DIRECT,
- FOU_ENCAP_GUE,
-};
-
-#define FOU_CMD_MAX (__FOU_CMD_MAX - 1)
+#define FOU_CMD_MAX (__FOU_CMD_MAX - 1)
#endif /* _UAPI_LINUX_FOU_H */
--
2.37.3
^ permalink raw reply related [flat|nested] 17+ messages in thread
* [PATCH net-next 6/6] net: fou: use policy and operation tables generated from the spec
2022-09-29 1:11 [PATCH net-next 0/6] Netlink protocol specs Jakub Kicinski
` (4 preceding siblings ...)
2022-09-29 1:11 ` [PATCH net-next 5/6] net: fou: regenerate the uAPI from the spec Jakub Kicinski
@ 2022-09-29 1:11 ` Jakub Kicinski
5 siblings, 0 replies; 17+ messages in thread
From: Jakub Kicinski @ 2022-09-29 1:11 UTC (permalink / raw)
To: davem
Cc: netdev, edumazet, pabeni, robh, johannes, ecree.xilinx, stephen,
sdf, f.fainelli, fw, linux-doc, razor, nicolas.dichtel, gnault,
Jakub Kicinski
Generate and plug in the spec-based tables.
A little bit of renaming is needed in the FOU code.
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
---
net/ipv4/Makefile | 2 +-
net/ipv4/fou-nl.c | 48 ++++++++++++++++++++++++++++++++++++++++++++
net/ipv4/fou-nl.h | 25 +++++++++++++++++++++++
net/ipv4/fou.c | 51 +++++++++--------------------------------------
4 files changed, 83 insertions(+), 43 deletions(-)
create mode 100644 net/ipv4/fou-nl.c
create mode 100644 net/ipv4/fou-nl.h
diff --git a/net/ipv4/Makefile b/net/ipv4/Makefile
index bbdd9c44f14e..7c6bfc035cf3 100644
--- a/net/ipv4/Makefile
+++ b/net/ipv4/Makefile
@@ -26,7 +26,7 @@ obj-$(CONFIG_IP_MROUTE) += ipmr.o
obj-$(CONFIG_IP_MROUTE_COMMON) += ipmr_base.o
obj-$(CONFIG_NET_IPIP) += ipip.o
gre-y := gre_demux.o
-obj-$(CONFIG_NET_FOU) += fou.o
+obj-$(CONFIG_NET_FOU) += fou.o fou-nl.o
obj-$(CONFIG_NET_IPGRE_DEMUX) += gre.o
obj-$(CONFIG_NET_IPGRE) += ip_gre.o
udp_tunnel-y := udp_tunnel_core.o udp_tunnel_nic.o
diff --git a/net/ipv4/fou-nl.c b/net/ipv4/fou-nl.c
new file mode 100644
index 000000000000..cc872b40dd78
--- /dev/null
+++ b/net/ipv4/fou-nl.c
@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: BSD-3-Clause
+// Do not edit directly, auto-generated from:
+// Documentation/netlink/specs/fou.yaml
+// YNL-GEN kernel source
+
+#include <net/netlink.h>
+#include <net/genetlink.h>
+
+#include "fou-nl.h"
+
+#include <linux/fou.h>
+
+// Global operation policy for fou
+const struct nla_policy fou_policy[FOU_ATTR_IFINDEX + 1] = {
+ [FOU_ATTR_PORT] = { .type = NLA_U16, },
+ [FOU_ATTR_AF] = { .type = NLA_U8, },
+ [FOU_ATTR_IPPROTO] = { .type = NLA_U8, },
+ [FOU_ATTR_TYPE] = { .type = NLA_U8, },
+ [FOU_ATTR_REMCSUM_NOPARTIAL] = { .type = NLA_FLAG, },
+ [FOU_ATTR_LOCAL_V4] = { .type = NLA_U32, },
+ [FOU_ATTR_LOCAL_V6] = { .len = 16, },
+ [FOU_ATTR_PEER_V4] = { .type = NLA_U32, },
+ [FOU_ATTR_PEER_V6] = { .len = 16, },
+ [FOU_ATTR_PEER_PORT] = { .type = NLA_U16, },
+ [FOU_ATTR_IFINDEX] = { .type = NLA_S32, },
+};
+
+// Ops table for fou
+const struct genl_small_ops fou_ops[3] = {
+ {
+ .cmd = FOU_CMD_ADD,
+ .validate = GENL_DONT_VALIDATE_STRICT | GENL_DONT_VALIDATE_DUMP,
+ .doit = fou_add_doit,
+ .flags = GENL_ADMIN_PERM,
+ },
+ {
+ .cmd = FOU_CMD_DEL,
+ .validate = GENL_DONT_VALIDATE_STRICT | GENL_DONT_VALIDATE_DUMP,
+ .doit = fou_del_doit,
+ .flags = GENL_ADMIN_PERM,
+ },
+ {
+ .cmd = FOU_CMD_GET,
+ .validate = GENL_DONT_VALIDATE_STRICT | GENL_DONT_VALIDATE_DUMP,
+ .doit = fou_get_doit,
+ .dumpit = fou_get_dumpit,
+ },
+};
diff --git a/net/ipv4/fou-nl.h b/net/ipv4/fou-nl.h
new file mode 100644
index 000000000000..1610396a18bb
--- /dev/null
+++ b/net/ipv4/fou-nl.h
@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: BSD-3-Clause
+// Do not edit directly, auto-generated from:
+// Documentation/netlink/specs/fou.yaml
+// YNL-GEN kernel header
+
+#ifndef _LINUX_FOU_GEN_H
+#define _LINUX_FOU_GEN_H
+
+#include <net/netlink.h>
+#include <net/genetlink.h>
+
+#include <linux/fou.h>
+
+// Global operation policy for fou
+extern const struct nla_policy fou_policy[FOU_ATTR_IFINDEX + 1];
+
+// Ops table for fou
+extern const struct genl_small_ops fou_ops[3];
+
+int fou_add_doit(struct sk_buff *skb, struct genl_info *info);
+int fou_del_doit(struct sk_buff *skb, struct genl_info *info);
+int fou_get_doit(struct sk_buff *skb, struct genl_info *info);
+int fou_get_dumpit(struct sk_buff *skb, struct netlink_callback *cb);
+
+#endif /* _LINUX_FOU_GEN_H */
diff --git a/net/ipv4/fou.c b/net/ipv4/fou.c
index 0c3c6d0cee29..6f934ae82d1d 100644
--- a/net/ipv4/fou.c
+++ b/net/ipv4/fou.c
@@ -19,6 +19,8 @@
#include <uapi/linux/fou.h>
#include <uapi/linux/genetlink.h>
+#include "fou-nl.h"
+
struct fou {
struct socket *sock;
u8 protocol;
@@ -640,20 +642,6 @@ static int fou_destroy(struct net *net, struct fou_cfg *cfg)
static struct genl_family fou_nl_family;
-static const struct nla_policy fou_nl_policy[FOU_ATTR_MAX + 1] = {
- [FOU_ATTR_PORT] = { .type = NLA_U16, },
- [FOU_ATTR_AF] = { .type = NLA_U8, },
- [FOU_ATTR_IPPROTO] = { .type = NLA_U8, },
- [FOU_ATTR_TYPE] = { .type = NLA_U8, },
- [FOU_ATTR_REMCSUM_NOPARTIAL] = { .type = NLA_FLAG, },
- [FOU_ATTR_LOCAL_V4] = { .type = NLA_U32, },
- [FOU_ATTR_PEER_V4] = { .type = NLA_U32, },
- [FOU_ATTR_LOCAL_V6] = { .len = sizeof(struct in6_addr), },
- [FOU_ATTR_PEER_V6] = { .len = sizeof(struct in6_addr), },
- [FOU_ATTR_PEER_PORT] = { .type = NLA_U16, },
- [FOU_ATTR_IFINDEX] = { .type = NLA_S32, },
-};
-
static int parse_nl_config(struct genl_info *info,
struct fou_cfg *cfg)
{
@@ -745,7 +733,7 @@ static int parse_nl_config(struct genl_info *info,
return 0;
}
-static int fou_nl_cmd_add_port(struct sk_buff *skb, struct genl_info *info)
+int fou_add_doit(struct sk_buff *skb, struct genl_info *info)
{
struct net *net = genl_info_net(info);
struct fou_cfg cfg;
@@ -758,7 +746,7 @@ static int fou_nl_cmd_add_port(struct sk_buff *skb, struct genl_info *info)
return fou_create(net, &cfg, NULL);
}
-static int fou_nl_cmd_rm_port(struct sk_buff *skb, struct genl_info *info)
+int fou_del_doit(struct sk_buff *skb, struct genl_info *info)
{
struct net *net = genl_info_net(info);
struct fou_cfg cfg;
@@ -827,7 +815,7 @@ static int fou_dump_info(struct fou *fou, u32 portid, u32 seq,
return -EMSGSIZE;
}
-static int fou_nl_cmd_get_port(struct sk_buff *skb, struct genl_info *info)
+int fou_get_doit(struct sk_buff *skb, struct genl_info *info)
{
struct net *net = genl_info_net(info);
struct fou_net *fn = net_generic(net, fou_net_id);
@@ -874,7 +862,7 @@ static int fou_nl_cmd_get_port(struct sk_buff *skb, struct genl_info *info)
return ret;
}
-static int fou_nl_dump(struct sk_buff *skb, struct netlink_callback *cb)
+int fou_get_dumpit(struct sk_buff *skb, struct netlink_callback *cb)
{
struct net *net = sock_net(skb->sk);
struct fou_net *fn = net_generic(net, fou_net_id);
@@ -897,37 +885,16 @@ static int fou_nl_dump(struct sk_buff *skb, struct netlink_callback *cb)
return skb->len;
}
-static const struct genl_small_ops fou_nl_ops[] = {
- {
- .cmd = FOU_CMD_ADD,
- .validate = GENL_DONT_VALIDATE_STRICT | GENL_DONT_VALIDATE_DUMP,
- .doit = fou_nl_cmd_add_port,
- .flags = GENL_ADMIN_PERM,
- },
- {
- .cmd = FOU_CMD_DEL,
- .validate = GENL_DONT_VALIDATE_STRICT | GENL_DONT_VALIDATE_DUMP,
- .doit = fou_nl_cmd_rm_port,
- .flags = GENL_ADMIN_PERM,
- },
- {
- .cmd = FOU_CMD_GET,
- .validate = GENL_DONT_VALIDATE_STRICT | GENL_DONT_VALIDATE_DUMP,
- .doit = fou_nl_cmd_get_port,
- .dumpit = fou_nl_dump,
- },
-};
-
static struct genl_family fou_nl_family __ro_after_init = {
.hdrsize = 0,
.name = FOU_GENL_NAME,
.version = FOU_GENL_VERSION,
.maxattr = FOU_ATTR_MAX,
- .policy = fou_nl_policy,
+ .policy = fou_policy,
.netnsok = true,
.module = THIS_MODULE,
- .small_ops = fou_nl_ops,
- .n_small_ops = ARRAY_SIZE(fou_nl_ops),
+ .small_ops = fou_ops,
+ .n_small_ops = ARRAY_SIZE(fou_ops),
.resv_start_op = FOU_CMD_GET + 1,
};
--
2.37.3
^ permalink raw reply related [flat|nested] 17+ messages in thread
* Re: [PATCH net-next 1/6] docs: add more netlink docs (incl. spec docs)
2022-09-29 1:11 ` [PATCH net-next 1/6] docs: add more netlink docs (incl. spec docs) Jakub Kicinski
@ 2022-09-29 8:15 ` Bagas Sanjaya
2022-09-29 9:43 ` Nicolas Dichtel
2022-09-29 13:34 ` Guillaume Nault
2 siblings, 0 replies; 17+ messages in thread
From: Bagas Sanjaya @ 2022-09-29 8:15 UTC (permalink / raw)
To: Jakub Kicinski
Cc: davem, netdev, edumazet, pabeni, robh, johannes, ecree.xilinx,
stephen, sdf, f.fainelli, fw, linux-doc, razor, nicolas.dichtel,
gnault
[-- Attachment #1: Type: text/plain, Size: 26217 bytes --]
On Wed, Sep 28, 2022 at 06:11:17PM -0700, Jakub Kicinski wrote:
> diff --git a/Documentation/core-api/netlink.rst b/Documentation/core-api/netlink.rst
> new file mode 100644
> index 000000000000..d0ec83df6b6b
> --- /dev/null
> +++ b/Documentation/core-api/netlink.rst
> @@ -0,0 +1,99 @@
> +.. SPDX-License-Identifier: BSD-3-Clause
> +
> +.. _kernel_netlink:
> +
> +===================================
> +Netlink notes for kernel developers
> +===================================
> +
> +General guidance
> +================
> +
> +Attribute enums
> +---------------
> +
> +Older families often define "null" attributes and commands with value
> +of ``0`` and named ``unspec``. This is supported (``type: unspec``)
> +but should be avoided in new families. The ``unspec`` enum values are
> +not used in practice, so just set the value of the first attribute to ``1``.
> +
> +Message enums
> +-------------
> +
> +Use the same command IDs for requests and replies. This makes it easier
> +to match them up, and we have plenty ID space.
> +
s/plenty/plenty of/
> +Use separate command IDs for notifications. This makes it easier to
> +sort the notifications from replies (and present them to the user
> +application via a different API than replies).
> +
> +Answer requests
> +---------------
> +
> +Older families do not reply to all of the commands, especially NEW / ADD
> +commands. User only gets information whether the operation succeeded or
> +not via the ACK. Try to find useful data to return. Once the command is
> +added whether it replies with a full message or only an ACK is uAPI and
> +cannot be changed. It's better to err on the side of replying.
> +
> +Specifically NEW and ADD commands should reply with information identifying
> +the created object such as the allocated object's ID.
> +
> +Having to rely on ``NLM_F_ECHO`` is a hack, not a valid design.
> +
> +NLM_F_ECHO
> +----------
> +
> +Make sure to pass the request info to genl_notify() to allow ``NLM_F_ECHO``
> +to take effect.
> +
> +Support dump consistency
> +------------------------
> +
> +If iterating over objects during dump may skip over objects or repeat
> +them - make sure to report dump inconsistency with ``NLM_F_DUMP_INTR``.
> +
> +Netlink specification
> +=====================
> +
> +Documentation of the Netlink specification parts which are only relevant
> +to the kernel space.
> +
> +Globals
> +-------
> +
> +kernel-policy
> +~~~~~~~~~~~~~
> +
> +Defines if the kernel validation policy is per operation (``per-op``)
> +or for the entire family (``global``). New families should use ``per-op``
> +(default) to be able to narrow down the attributes accepted by a specific
> +command.
> +
> +checks
> +------
> +
> +Documentation for the ``checks`` sub-sections of attribute specs.
> +
> +unterminated-ok
> +~~~~~~~~~~~~~~~
> +
> +Accept strings without the null-termination (for legacy families only).
> +Switches from the ``NLA_NUL_STRING`` to ``NLA_STRING`` policy type.
> +
> +max-len
> +~~~~~~~
> +
> +Defines max length for a binary or string attribute (corresponding
> +to the ``len`` member of struct nla_policy). For string attributes terminating
> +null character is not counted towards ``max-len``.
> +
> +The field may either be a literal integer value or a name of a defined
> +constant. String types may reduce the constant by one
> +(i.e. specify ``max-len: CONST - 1``) to reserve space for the terminating
> +character so implementations should recognize such pattern.
> +
> +min-len
> +~~~~~~~
> +
> +Similar to ``max-len`` but defines minimum length.
Otherwise this doc is LGTM.
> diff --git a/Documentation/userspace-api/netlink/c-code-gen.rst b/Documentation/userspace-api/netlink/c-code-gen.rst
> new file mode 100644
> index 000000000000..7c6a86f9ceb9
> --- /dev/null
> +++ b/Documentation/userspace-api/netlink/c-code-gen.rst
> @@ -0,0 +1,104 @@
> +.. SPDX-License-Identifier: BSD-3-Clause
> +
> +==============================
> +Netlink spec C code generation
> +==============================
> +
> +This document describes how Netlink specifications are used to render
> +C code (uAPI, policies etc.). It also defines the additional properties
> +allowed in older families by the ``genetlink-c`` protocol level,
> +to control the naming.
> +
> +For brevity this document refers to ``name`` properties of various
> +objects by the object type. For example ``$attr`` is the value
> +of ``name`` in an attribute, and ``$family`` is the name of the
> +family (the global ``name`` property).
> +
> +The upper case is used to denote literal values, e.g. ``$family-CMD``
> +means the concatenation of ``$family``, a dash character, and the literal
> +``CMD``.
> +
> +The names of ``#defines`` and enum values are always converted to upper case,
> +and with dashes (``-``) replaced by underscores (``_``).
> +
> +If the constructured name is a C keyword, an extra underscore is
> +appended (``do`` -> ``do_``).
> +
> +Globals
> +=======
> +
> +``c-family-name`` controls the name of the ``#define`` for the family
> +name, default is ``$family-FAMILY-NAME``.
> +
> +``c-version-name`` controls the name of the ``#define`` for the version
> +of the family, default is ``$family-FAMILY-VERSION``.
> +
> +``max-by-define`` selects if max values for enums are defined as a
> +``#define`` rather than inside the enum.
> +
> +Definitions
> +===========
> +
> +Constants
> +---------
> +
> +Every constant is rendered as a ``#define``.
> +The name of the constant is ``$family-$constant`` and the value
> +is rendered as a string or integer according to its type in the spec.
> +
> +Enums and flags
> +---------------
> +
> +Enums are named ``$family-$enum``. The full name can be set directly
> +or suppressed by specifying the ``enum-name`` property.
> +Default entry name is ``$family-$enum-$entry``.
> +If ``name-prefix`` is specified it replaces the ``$family-$enum``
> +portion of the entry name.
> +
> +Attributes
> +==========
> +
> +Each attribute set (excluding fractional sets) is rendered as an enum.
> +
> +Attribute enums are traditionally unnamed in netlink headers.
> +If naming is desired ``enum-name`` can be used to specify the name.
> +
> +The default attribute name prefix is ``$family-A`` if the name of the set
> +is the same as the name of the family and ``$family-A-$set`` if the names
> +differ. The prefix can be overridden by the ``name-prefix`` property of a set.
> +The rest of the section will refer to the prefix as ``$pfx``.
> +
> +Attributes are named ``$pfx-$attribute``.
> +
> +Attribute enums end with two special values ``__$pfx-MAX`` and ``$pfx-MAX``
> +which are used for sizing attribute tables.
> +These two names can be specified directly with the ``attr-cnt-name``
> +and ``attr-max-name`` properties respectively.
> +
> +If ``max-by-define`` is set to ``true`` at the global level ``attr-max-name``
> +will be specified as a ``#define`` rather than an enum value.
> +
> +Operations
> +==========
> +
> +Operations are named ``$family-CMD-$operation``.
> +If ``name-prefix`` is specified it replaces the ``$family-CMD``
> +portion of the name.
> +
> +Similarly to attribute enums operation enums end with special count and max
> +attributes. For operations those attributes can be renamed with
> +``cmd-cnt-name`` and ``cmd-max-name``. Max will be a define if ``max-by-define``
> +is ``true``.
> +
> +Multicast groups
> +================
> +
> +Each multicast group gets a define rendered into the kernel uAPI header.
> +The name of the define is ``$family-MCGRP-$group``, and can be overwritten
> +with the ``c-define-name`` property.
> +
> +Code generation
> +===============
> +
> +uAPI header is assumed to come from ``<linux/$family.h>`` in the default header
> +search path. It can be changed using the ``uapi-header`` global property.
LGTM (grammar and formatting).
> diff --git a/Documentation/userspace-api/netlink/genetlink-legacy.rst b/Documentation/userspace-api/netlink/genetlink-legacy.rst
> new file mode 100644
> index 000000000000..65cbbffee0bf
> --- /dev/null
> +++ b/Documentation/userspace-api/netlink/genetlink-legacy.rst
> @@ -0,0 +1,96 @@
> +.. 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.
> +
> +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. The plan is to define
> +the structs in ``definitions`` and link the appropriate attrs.
> +
> +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).
LGTM (grammar and formatting).
> diff --git a/Documentation/userspace-api/netlink/index.rst b/Documentation/userspace-api/netlink/index.rst
> index b0c21538d97d..be250110c8f6 100644
> --- a/Documentation/userspace-api/netlink/index.rst
> +++ b/Documentation/userspace-api/netlink/index.rst
> @@ -10,3 +10,8 @@ Netlink documentation for users.
> :maxdepth: 2
>
> intro
> + specs
> + c-code-gen
> + genetlink-legacy
> +
> +See also :ref:`Documentation/core-api/netlink.rst <kernel_netlink>`.
> diff --git a/Documentation/userspace-api/netlink/specs.rst b/Documentation/userspace-api/netlink/specs.rst
> new file mode 100644
> index 000000000000..49f2f782f537
> --- /dev/null
> +++ b/Documentation/userspace-api/netlink/specs.rst
> @@ -0,0 +1,410 @@
> +.. 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
> + - policy tables for input attribute validation
> + - operation tables
> +
> +YAML specifications can be found under ``Documentation/netlink/specs/``
> +
> +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.
> +
> +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.
> +
> +version
> +~~~~~~~
> +
> +Generic Netlink family version, default is 1.
> +
> +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-compabile 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
> +--------------------
> +
> +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 ``0`` for the first attribute in the attribute set.
> +
> +Note that the ``value`` of an attribute is defined only in its main set.
> +
> +enum
> +~~~~
> +
> +For integer types specifies that values in the attribute belong to a defined
> +``enum``. Note that in case of ``flags`` the values may be combined.
> +
> +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``.
> +
> +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.
> +
> +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.
> +
> +Scalar integer types
> +--------------------
> +
> +Fixed-width integer types:
> +``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.
> +
> +.. _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.
LGTM (grammar and formatting).
All docs have been reviewed, thanks.
Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>
--
An old man doll... just what I always wanted! - Clara
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH net-next 4/6] netlink: add a proto specification for FOU
2022-09-29 1:11 ` [PATCH net-next 4/6] netlink: add a proto specification for FOU Jakub Kicinski
@ 2022-09-29 9:02 ` Nicolas Dichtel
2022-09-29 9:06 ` Nicolas Dichtel
2022-09-29 14:41 ` Jakub Kicinski
0 siblings, 2 replies; 17+ messages in thread
From: Nicolas Dichtel @ 2022-09-29 9:02 UTC (permalink / raw)
To: Jakub Kicinski, davem
Cc: netdev, edumazet, pabeni, robh, johannes, ecree.xilinx, stephen,
sdf, f.fainelli, fw, linux-doc, razor, gnault
Le 29/09/2022 à 03:11, Jakub Kicinski a écrit :
> FOU has a reasonably modern Genetlink family. Add a spec.
>
> Signed-off-by: Jakub Kicinski <kuba@kernel.org>
> ---
> Documentation/netlink/specs/fou.yaml | 128 +++++++++++++++++++++++++++
> 1 file changed, 128 insertions(+)
> create mode 100644 Documentation/netlink/specs/fou.yaml
>
> diff --git a/Documentation/netlink/specs/fou.yaml b/Documentation/netlink/specs/fou.yaml
> new file mode 100644
> index 000000000000..266c386eedf3
> --- /dev/null
> +++ b/Documentation/netlink/specs/fou.yaml
> @@ -0,0 +1,128 @@
> +name: fou
> +
> +protocol: genetlink-legacy
> +
> +doc: |
> + Foo-over-UDP.
> +
> +c-family-name: fou-genl-name
> +c-version-name: fou-genl-version
> +max-by-define: true
> +kernel-policy: global
> +
> +definitions:
> + -
> + type: enum
> + name: encap_type
> + name-prefix: fou-encap-
> + enum-name:
> + entries: [ unspec, direct, gue ]
> +
> +attribute-sets:
> + -
> + name: fou
> + name-prefix: fou-attr-
> + attributes:
> + -
> + name: unspec
> + type: unused
The first attribute should always be unspec/unused. Maybe it could be
automatically generated?
> + -
> + name: port
> + type: u16
> + byte-order: big-endian
> + -
> + name: af
> + type: u8
> + -
> + name: ipproto
> + type: u8
> + -
> + name: type
> + type: u8
> + -
> + name: remcsum_nopartial
> + type: flag
> + -
> + name: local_v4
> + type: u32
> + -
> + name: local_v6
> + type: binary
> + checks:
> + min-len: 16
> + -
> + name: peer_v4
> + type: u32
> + -
> + name: peer_v6
> + type: binary
> + checks:
> + min-len: 16
> + -
> + name: peer_port
> + type: u16
> + byte-order: big-endian
> + -
> + name: ifindex
> + type: s32
> +
> +operations:
> + list:
> + -
> + name: unspec
> + doc: unused
To what correspond this name?
It helps to name the generated operations array?
Something else than 'const struct genl_small_ops fou_ops[3]'?
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH net-next 4/6] netlink: add a proto specification for FOU
2022-09-29 9:02 ` Nicolas Dichtel
@ 2022-09-29 9:06 ` Nicolas Dichtel
2022-09-29 14:41 ` Jakub Kicinski
1 sibling, 0 replies; 17+ messages in thread
From: Nicolas Dichtel @ 2022-09-29 9:06 UTC (permalink / raw)
To: Jakub Kicinski, davem
Cc: netdev, edumazet, pabeni, robh, johannes, ecree.xilinx, stephen,
sdf, f.fainelli, fw, linux-doc, razor, gnault
Le 29/09/2022 à 11:02, Nicolas Dichtel a écrit :
>
> Le 29/09/2022 à 03:11, Jakub Kicinski a écrit :
>> FOU has a reasonably modern Genetlink family. Add a spec.
>>
>> Signed-off-by: Jakub Kicinski <kuba@kernel.org>
>> ---
>> Documentation/netlink/specs/fou.yaml | 128 +++++++++++++++++++++++++++
>> 1 file changed, 128 insertions(+)
>> create mode 100644 Documentation/netlink/specs/fou.yaml
>>
>> diff --git a/Documentation/netlink/specs/fou.yaml b/Documentation/netlink/specs/fou.yaml
>> new file mode 100644
>> index 000000000000..266c386eedf3
>> --- /dev/null
>> +++ b/Documentation/netlink/specs/fou.yaml
>> @@ -0,0 +1,128 @@
>> +name: fou
>> +
>> +protocol: genetlink-legacy
>> +
>> +doc: |
>> + Foo-over-UDP.
>> +
>> +c-family-name: fou-genl-name
>> +c-version-name: fou-genl-version
>> +max-by-define: true
>> +kernel-policy: global
>> +
>> +definitions:
>> + -
>> + type: enum
>> + name: encap_type
>> + name-prefix: fou-encap-
>> + enum-name:
>> + entries: [ unspec, direct, gue ]
>> +
>> +attribute-sets:
>> + -
>> + name: fou
>> + name-prefix: fou-attr-
>> + attributes:
>> + -
>> + name: unspec
>> + type: unused
> The first attribute should always be unspec/unused. Maybe it could be
> automatically generated?
I read the doc after the code :)
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH net-next 1/6] docs: add more netlink docs (incl. spec docs)
2022-09-29 1:11 ` [PATCH net-next 1/6] docs: add more netlink docs (incl. spec docs) Jakub Kicinski
2022-09-29 8:15 ` Bagas Sanjaya
@ 2022-09-29 9:43 ` Nicolas Dichtel
2022-09-29 13:34 ` Guillaume Nault
2 siblings, 0 replies; 17+ messages in thread
From: Nicolas Dichtel @ 2022-09-29 9:43 UTC (permalink / raw)
To: Jakub Kicinski, davem
Cc: netdev, edumazet, pabeni, robh, johannes, ecree.xilinx, stephen,
sdf, f.fainelli, fw, linux-doc, razor, gnault
Le 29/09/2022 à 03:11, Jakub Kicinski a écrit :
> Add documentation about the upcoming Netlink protocol specs.
>
> Signed-off-by: Jakub Kicinski <kuba@kernel.org>
[snip]
> +Attribute enums
> +---------------
> +
> +Older families often define "null" attributes and commands with value
> +of ``0`` and named ``unspec``. This is supported (``type: unspec``)
> +but should be avoided in new families. The ``unspec`` enum values are
> +not used in practice, so just set the value of the first attribute to ``1``.
[snip]
> +The payload of the attribute is the integer in host order unless ``byte-order``
> +specifies otherwise.
> +
> +.. _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.
This answers my question.
Nice job!
Reviewed-by: Nicolas Dichtel <nicolas.dichtel@6wind.com>
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH net-next 1/6] docs: add more netlink docs (incl. spec docs)
2022-09-29 1:11 ` [PATCH net-next 1/6] docs: add more netlink docs (incl. spec docs) Jakub Kicinski
2022-09-29 8:15 ` Bagas Sanjaya
2022-09-29 9:43 ` Nicolas Dichtel
@ 2022-09-29 13:34 ` Guillaume Nault
2022-09-29 14:32 ` Jakub Kicinski
2 siblings, 1 reply; 17+ messages in thread
From: Guillaume Nault @ 2022-09-29 13:34 UTC (permalink / raw)
To: Jakub Kicinski
Cc: davem, netdev, edumazet, pabeni, robh, johannes, ecree.xilinx,
stephen, sdf, f.fainelli, fw, linux-doc, razor, nicolas.dichtel
On Wed, Sep 28, 2022 at 06:11:17PM -0700, Jakub Kicinski wrote:
> +Answer requests
> +---------------
> +
> +Older families do not reply to all of the commands, especially NEW / ADD
> +commands. User only gets information whether the operation succeeded or
> +not via the ACK. Try to find useful data to return. Once the command is
> +added whether it replies with a full message or only an ACK is uAPI and
> +cannot be changed. It's better to err on the side of replying.
> +
> +Specifically NEW and ADD commands should reply with information identifying
> +the created object such as the allocated object's ID.
> +
> +Having to rely on ``NLM_F_ECHO`` is a hack, not a valid design.
> +
> +NLM_F_ECHO
> +----------
> +
> +Make sure to pass the request info to genl_notify() to allow ``NLM_F_ECHO``
> +to take effect.
Do you mean that netlink commands should properly handle NLM_F_ECHO,
although they should also design their API so that users don't need it?
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH net-next 1/6] docs: add more netlink docs (incl. spec docs)
2022-09-29 13:34 ` Guillaume Nault
@ 2022-09-29 14:32 ` Jakub Kicinski
2022-09-29 15:11 ` Guillaume Nault
0 siblings, 1 reply; 17+ messages in thread
From: Jakub Kicinski @ 2022-09-29 14:32 UTC (permalink / raw)
To: Guillaume Nault
Cc: davem, netdev, edumazet, pabeni, robh, johannes, ecree.xilinx,
stephen, sdf, f.fainelli, fw, linux-doc, razor, nicolas.dichtel
On Thu, 29 Sep 2022 15:34:13 +0200 Guillaume Nault wrote:
> > +Make sure to pass the request info to genl_notify() to allow ``NLM_F_ECHO``
> > +to take effect.
>
> Do you mean that netlink commands should properly handle NLM_F_ECHO,
> although they should also design their API so that users don't need it?
Yes, ECHO should be supported but as an extra, not something that
is crucial to write a basic script without assuming full ownership
of the system...
IOW support the logging use case you mentioned but don't do the NEWLINK
thing.
Should I clarify or rephrase? The ECHO section needs to be read with
the one above it to get the full answer.
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH net-next 4/6] netlink: add a proto specification for FOU
2022-09-29 9:02 ` Nicolas Dichtel
2022-09-29 9:06 ` Nicolas Dichtel
@ 2022-09-29 14:41 ` Jakub Kicinski
1 sibling, 0 replies; 17+ messages in thread
From: Jakub Kicinski @ 2022-09-29 14:41 UTC (permalink / raw)
To: Nicolas Dichtel
Cc: davem, netdev, edumazet, pabeni, robh, johannes, ecree.xilinx,
stephen, sdf, f.fainelli, fw, linux-doc, razor, gnault
On Thu, 29 Sep 2022 11:02:51 +0200 Nicolas Dichtel wrote:
> > +operations:
> > + list:
> > + -
> > + name: unspec
> > + doc: unused
>
> To what correspond this name?
> It helps to name the generated operations array?
> Something else than 'const struct genl_small_ops fou_ops[3]'?
Same as the attr, it just reserves zero FWIW, never actually used in
the code I've grepped:
linux$ git grep FOU_CMD_UNSPEC
include/uapi/linux/fou.h: FOU_CMD_UNSPEC,
iproute2$ git grep FOU_CMD_UNSPEC
include/uapi/linux/fou.h: FOU_CMD_UNSPEC,
BTW thanks for asking, I noticed I mistyped the documentation,
type is 'unused', in the docs I said 'unspec'.
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH net-next 1/6] docs: add more netlink docs (incl. spec docs)
2022-09-29 14:32 ` Jakub Kicinski
@ 2022-09-29 15:11 ` Guillaume Nault
2022-09-29 15:47 ` Jakub Kicinski
0 siblings, 1 reply; 17+ messages in thread
From: Guillaume Nault @ 2022-09-29 15:11 UTC (permalink / raw)
To: Jakub Kicinski
Cc: davem, netdev, edumazet, pabeni, robh, johannes, ecree.xilinx,
stephen, sdf, f.fainelli, fw, linux-doc, razor, nicolas.dichtel
On Thu, Sep 29, 2022 at 07:32:24AM -0700, Jakub Kicinski wrote:
> On Thu, 29 Sep 2022 15:34:13 +0200 Guillaume Nault wrote:
> > > +Make sure to pass the request info to genl_notify() to allow ``NLM_F_ECHO``
> > > +to take effect.
> >
> > Do you mean that netlink commands should properly handle NLM_F_ECHO,
> > although they should also design their API so that users don't need it?
>
> Yes, ECHO should be supported but as an extra, not something that
> is crucial to write a basic script without assuming full ownership
> of the system...
>
> IOW support the logging use case you mentioned but don't do the NEWLINK
> thing.
>
> Should I clarify or rephrase? The ECHO section needs to be read with
> the one above it to get the full answer.
Maybe we can make this more explicit.
Something like:
-Having to rely on ``NLM_F_ECHO`` is a hack, not a valid design.
+Users shouldn't have to use ``NLM_F_ECHO`` to get a handle on the created
+object.
(or keep both sentences, I feel they fit well together).
Then maybe explain in the next section why support for NLM_F_ECHO is
desirable anyway:
Make sure to pass the request info to genl_notify() to allow ``NLM_F_ECHO``
-to take effect.
+to take effect. This is usefull for programs that need precise feedback from
+ the kernel (for example for logging purpose).
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH net-next 1/6] docs: add more netlink docs (incl. spec docs)
2022-09-29 15:11 ` Guillaume Nault
@ 2022-09-29 15:47 ` Jakub Kicinski
2022-09-29 15:52 ` Guillaume Nault
0 siblings, 1 reply; 17+ messages in thread
From: Jakub Kicinski @ 2022-09-29 15:47 UTC (permalink / raw)
To: Guillaume Nault
Cc: davem, netdev, edumazet, pabeni, robh, johannes, ecree.xilinx,
stephen, sdf, f.fainelli, fw, linux-doc, razor, nicolas.dichtel
On Thu, 29 Sep 2022 17:11:45 +0200 Guillaume Nault wrote:
> Maybe we can make this more explicit.
> Something like:
>
> -Having to rely on ``NLM_F_ECHO`` is a hack, not a valid design.
> +Users shouldn't have to use ``NLM_F_ECHO`` to get a handle on the created
> +object.
>
> (or keep both sentences, I feel they fit well together).
>
> Then maybe explain in the next section why support for NLM_F_ECHO is
> desirable anyway:
>
> Make sure to pass the request info to genl_notify() to allow ``NLM_F_ECHO``
> -to take effect.
> +to take effect. This is usefull for programs that need precise feedback from
> + the kernel (for example for logging purpose).
Folded it a little bit:
diff --git a/Documentation/core-api/netlink.rst b/Documentation/core-api/netlink.rst
index 2a97f765d0d2..7b98dd48a6af 100644
--- a/Documentation/core-api/netlink.rst
+++ b/Documentation/core-api/netlink.rst
@@ -37,15 +37,15 @@ added whether it replies with a full message or only an ACK is uAPI and
cannot be changed. It's better to err on the side of replying.
Specifically NEW and ADD commands should reply with information identifying
-the created object such as the allocated object's ID.
-
-Having to rely on ``NLM_F_ECHO`` is a hack, not a valid design.
+the created object such as the allocated object's ID (without having to
+resort to using ``NLM_F_ECHO``).
NLM_F_ECHO
----------
Make sure to pass the request info to genl_notify() to allow ``NLM_F_ECHO``
-to take effect.
+to take effect. This is useful for programs that need precise feedback
+from the kernel (for example for logging purposes).
Support dump consistency
------------------------
^ permalink raw reply related [flat|nested] 17+ messages in thread
* Re: [PATCH net-next 1/6] docs: add more netlink docs (incl. spec docs)
2022-09-29 15:47 ` Jakub Kicinski
@ 2022-09-29 15:52 ` Guillaume Nault
0 siblings, 0 replies; 17+ messages in thread
From: Guillaume Nault @ 2022-09-29 15:52 UTC (permalink / raw)
To: Jakub Kicinski
Cc: davem, netdev, edumazet, pabeni, robh, johannes, ecree.xilinx,
stephen, sdf, f.fainelli, fw, linux-doc, razor, nicolas.dichtel
On Thu, Sep 29, 2022 at 08:47:15AM -0700, Jakub Kicinski wrote:
> Folded it a little bit:
>
> diff --git a/Documentation/core-api/netlink.rst b/Documentation/core-api/netlink.rst
> index 2a97f765d0d2..7b98dd48a6af 100644
> --- a/Documentation/core-api/netlink.rst
> +++ b/Documentation/core-api/netlink.rst
> @@ -37,15 +37,15 @@ added whether it replies with a full message or only an ACK is uAPI and
> cannot be changed. It's better to err on the side of replying.
>
> Specifically NEW and ADD commands should reply with information identifying
> -the created object such as the allocated object's ID.
> -
> -Having to rely on ``NLM_F_ECHO`` is a hack, not a valid design.
> +the created object such as the allocated object's ID (without having to
> +resort to using ``NLM_F_ECHO``).
>
> NLM_F_ECHO
> ----------
>
> Make sure to pass the request info to genl_notify() to allow ``NLM_F_ECHO``
> -to take effect.
> +to take effect. This is useful for programs that need precise feedback
> +from the kernel (for example for logging purposes).
That's very clear, thanks!
^ permalink raw reply [flat|nested] 17+ messages in thread
end of thread, other threads:[~2022-09-29 15:52 UTC | newest]
Thread overview: 17+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-09-29 1:11 [PATCH net-next 0/6] Netlink protocol specs Jakub Kicinski
2022-09-29 1:11 ` [PATCH net-next 1/6] docs: add more netlink docs (incl. spec docs) Jakub Kicinski
2022-09-29 8:15 ` Bagas Sanjaya
2022-09-29 9:43 ` Nicolas Dichtel
2022-09-29 13:34 ` Guillaume Nault
2022-09-29 14:32 ` Jakub Kicinski
2022-09-29 15:11 ` Guillaume Nault
2022-09-29 15:47 ` Jakub Kicinski
2022-09-29 15:52 ` Guillaume Nault
2022-09-29 1:11 ` [PATCH net-next 2/6] netlink: add schemas for YAML specs Jakub Kicinski
2022-09-29 1:11 ` [PATCH net-next 3/6] net: add basic C code generators for Netlink Jakub Kicinski
2022-09-29 1:11 ` [PATCH net-next 4/6] netlink: add a proto specification for FOU Jakub Kicinski
2022-09-29 9:02 ` Nicolas Dichtel
2022-09-29 9:06 ` Nicolas Dichtel
2022-09-29 14:41 ` Jakub Kicinski
2022-09-29 1:11 ` [PATCH net-next 5/6] net: fou: regenerate the uAPI from the spec Jakub Kicinski
2022-09-29 1:11 ` [PATCH net-next 6/6] net: fou: use policy and operation tables generated " Jakub Kicinski
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.