Skip to contentSkip to conversation

tools/net/ynl: Add support for netlink-raw families

PATCH Superseded Donald Hunter 4 participants 29 messages Aug 15, 2023 – Aug 21, 2023

Subsystems (4)

v2 of 6 Superseded Latest is v6 →

lore
Share & tools
lore

Donald Hunter

author maintainer
#0 lore raw

v2 cover tools/net/ynl: Add support for netlink-raw families

This patchset adds support for netlink-raw families such as rtnetlink.

Patch 1 contains the schema definition
Patches 2 & 3 update the schema documentation
Patches 4 - 7 extends ynl
Patches 8 - 10 add several netlink-raw specs

The netlink-raw schema is very similar to genetlink-legacy and I thought about making the changes there and symlinking to it. On balance I thought that might be problematic for accurate schema validation.

rtnetlink doesn't seem to fit into unified or directional message enumeration models. It seems like an 'explicit' model would be useful, to force the schema author to specify the message ids directly.

There is not yet support for notifications because ynl currently doesn't support defining 'event' properties on a 'do' operation. I plan to look at this in a future patch.

The link and route messages contain different nested attributes dependent on the type of link or route. Decoding these will need some kind of attr-space selection that uses the value of another attribute as the selector key. These nested attributes have been left with type 'binary' for now.

v1 -> v2:
- Put mcast-group changes in separate patch
- Put decode_fixed_header refactoring in separate patch
- Avoid refactoring decode_enum
- Rename NetlinkProtocolFamily -> NetlinkProtocol and

    GenlProtocolFamily -> GenlProtocol and store in self.nlproto

- Add spec for rt link.

Donald Hunter (10):
doc/netlink: Add a schema for netlink-raw families doc/netlink: Document the genetlink-legacy schema extensions doc/netlink: Document the netlink-raw schema extensions tools/ynl: Add mcast-group schema parsing to ynl tools/net/ynl: Refactor decode_fixed_header into NlMsg tools/net/ynl: Add support for netlink-raw families tools/net/ynl: Implement nlattr array-nest decoding in ynl doc/netlink: Add spec for rt addr messages doc/netlink: Add spec for rt link messages doc/netlink: Add spec for rt route messages

 Documentation/netlink/netlink-raw.yaml        |  414 +++++
 Documentation/netlink/specs/rt_addr.yaml      |  179 +++
 Documentation/netlink/specs/rt_link.yaml      | 1374 +++++++++++++++++
 Documentation/netlink/specs/rt_route.yaml     |  288 ++++
 Documentation/userspace-api/netlink/intro.rst |    2 +
 Documentation/userspace-api/netlink/specs.rst |   64 +
 tools/net/ynl/lib/nlspec.py                   |   26 +
 tools/net/ynl/lib/ynl.py                      |  153 +-
 8 files changed, 2461 insertions(+), 39 deletions(-)
 create mode 100644 Documentation/netlink/netlink-raw.yaml
 create mode 100644 Documentation/netlink/specs/rt_addr.yaml
 create mode 100644 Documentation/netlink/specs/rt_link.yaml
 create mode 100644 Documentation/netlink/specs/rt_route.yaml
Signature · 1 line
2.41.0
author maintainer
#1 lore raw

PATCH v2 1/10 doc/netlink: Add a schema for netlink-raw families

This schema is largely a copy of the genetlink-legacy schema with the following additions:

- a top-level protonum property, e.g. 0 (for NETLINK_ROUTE)
- add netlink-raw to the list of protocols supported by the schema
- add a value property to mcast-group definitions

This schema is very similar to genetlink-legacy and I considered making the changes there and symlinking to it. On balance I felt that might be problematic for accurate schema validation.

---
 Documentation/netlink/netlink-raw.yaml | 414 +++++++++++++++++++++++++
 1 file changed, 414 insertions(+)
 create mode 100644 Documentation/netlink/netlink-raw.yaml
Documentation/netlink/netlink-raw.yaml new file +414 -0
new file mode 100644
index 000000000000..a5ec6f3e41cc
@@ -0,0 +1,414 @@
+# SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)
+%YAML 1.2
+---
+$id: http://kernel.org/schemas/netlink/genetlink-legacy.yaml#
+$schema: https://json-schema.org/draft-07/schema
+
+# Common defines
+$defs:
+  uint:
+    type: integer
+    minimum: 0
+  len-or-define:
+    type: [ string, integer ]
+    pattern: ^[0-9A-Za-z_]+( - 1)?$
+    minimum: 0
+
+# Schema for specs
+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
+    minimum: 1
+  protocol:
+    description: Schema compatibility level. Default is "genetlink".
+    enum: [ genetlink, genetlink-c, genetlink-legacy, netlink-raw ] # Trim
+  # Start netlink-raw
+  protonum:
+    description: Protocol number to use for netlink-raw
+    type: integer
+  # End netlink-raw
+  uapi-header:
+    description: Path to the uAPI header, default is linux/${family-name}.h
+    type: string
+  # Start genetlink-c
+  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, per-operation, or split per operation type.
+      Default is split.
+    enum: [ split, per-op, global ]
+  # End genetlink-legacy
+
+  definitions:
+    description: List of type and constant definitions (enums, flags, defines).
+    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
+        doc:
+          type: string
+        # 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:
+            oneOf:
+              - type: string
+              - type: object
+                required: [ name ]
+                additionalProperties: False
+                properties:
+                  name:
+                    type: string
+                  value:
+                    type: integer
+                  doc:
+                    type: string
+        render-max:
+          description: Render the max members for this enum.
+          type: boolean
+        # 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:
+                description: The netlink attribute type
+                enum: [ u8, u16, u32, u64, s8, s16, s32, s64, string, binary ]
+              len:
+                $ref: '#/$defs/len-or-define'
+              byte-order:
+                enum: [ little-endian, big-endian ]
+              doc:
+                description: Documentation for the struct member attribute.
+                type: string
+              enum:
+                description: Name of the enum type used for the attribute.
+                type: string
+              enum-as-flags:
+                description: |
+                  Treat the enum as flags. In most cases enum is either used as flags or as values.
+                  Sometimes, however, both forms are necessary, in which case header contains the enum
+                  form while specific attributes may request to convert the values into a bitfield.
+                type: boolean
+              display-hint: &display-hint
+                description: |
+                  Optional format indicator that is intended only for choosing
+                  the right formatting mechanism when displaying values of this
+                  type.
+                enum: [ hex, mac, fddi, ipv4, ipv6, uuid ]
+        # 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 the spec.
+          type: string
+        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
+                description: The netlink attribute 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.
+                $ref: '#/$defs/uint'
+              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 attribute.
+                type: string
+              enum-as-flags:
+                description: |
+                  Treat the enum as flags. In most cases enum is either used as flags or as values.
+                  Sometimes, however, both forms are necessary, in which case header contains the enum
+                  form while specific attributes may request to convert the values into a bitfield.
+                type: boolean
+              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:
+                    description: Min value for an integer attribute.
+                    type: integer
+                  min-len:
+                    description: Min length for a binary attribute.
+                    $ref: '#/$defs/len-or-define'
+                  max-len:
+                    description: Max length for a string or a binary attribute.
+                    $ref: '#/$defs/len-or-define'
+              sub-type: *attr-type
+              display-hint: *display-hint
+              # Start genetlink-c
+              name-prefix:
+                type: string
+              # End genetlink-c
+              # Start genetlink-legacy
+              struct:
+                description: Name of the struct type used for the attribute.
+                type: string
+              # End genetlink-legacy
+
+      # Make sure name-prefix does not appear in subsets (subsets inherit naming)
+      dependencies:
+        name-prefix:
+          not:
+            required: [ subset-of ]
+        subset-of:
+          not:
+            required: [ name-prefix ]
+
+  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.
+        enum: [ unified, directional ] # Trim
+      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
+      # Start genetlink-legacy
+      fixed-header: &fixed-header
+        description: |
+          Name of the structure defining the optional fixed-length protocol
+          header. This header is placed in a message after the netlink and
+          genetlink headers and before any attributes.
+        type: string
+      # End genetlink-legacy
+      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.
+              $ref: '#/$defs/uint'
+            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 ]
+            # Start genetlink-legacy
+            fixed-header: *fixed-header
+            # End genetlink-legacy
+            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
+                    # Start genetlink-legacy
+                    value:
+                      description: |
+                        ID of this message if value for request and response differ,
+                        i.e. requests and responses have different message enums.
+                      $ref: '#/$defs/uint'
+                    # End genetlink-legacy
+                reply: *subop-attr-list
+                pre:
+                  description: Hook for a function to run before the main callback (pre_doit or start).
+                  type: string
+                post:
+                  description: Hook for a function to run after the main callback (post_doit or done).
+                  type: string
+            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
+            # Start netlink-raw
+            value:
+              description: Value of the netlink multicast group in the uAPI.
+              type: integer
+            # End netlink-raw
Signature · 1 line
2.41.0
author maintainer
#4 lore raw

PATCH v2 2/10 doc/netlink: Document the genetlink-legacy schema extensions

In reply to Donald Hunter

Add description of genetlink-legacy specific attributes to the ynl spec documentation.

---
 Documentation/userspace-api/netlink/specs.rst | 47 +++++++++++++++++++
 1 file changed, 47 insertions(+)
Documentation/userspace-api/netlink/specs.rst +47 -0
index 2e4acde890b7..dde70f9674d4 100644
@@ -443,3 +443,50 @@ nest
 
 Attribute containing other (nested) attributes.
 ``nested-attributes`` specifies which attribute set is used inside.
+
+genetlink-legacy
+================
+
+The genetlink-legacy schema extends the genetlink schema with some additional
+properties that are needed to support legacy genetlink families.
+
+Globals
+-------
+
+ - ``kernel-policy`` - Specify whether the kernel input policy is ``global``,
+   ``per-op`` or ``split``.
+
+Struct definitions
+------------------
+
+There is a new type of definition called ``struct`` which is used for declaring
+the C struct format of fixed headers and binary attributes.
+
+members
+~~~~~~~
+
+ - ``name`` - The attribute name of the struct member
+ - ``type`` - One of the scalar types ``u8``, ``u16``, ``u32``, ``u64``, ``s8``,
+   ``s16``, ``s32``, ``s64``, ``string`` or ``binary``.
+ - ``byte-order`` - ``big-endian`` or ``little-endian``
+ - ``doc``, ``enum``, ``enum-as-flags``, ``display-hint`` - Same as for
+   attribute definitions.
+
+Attributes
+----------
+
+The genetlink-legacy families can use binary attributes that contain C struct
+data. This is specified using a ``struct`` property containing the name of the
+struct definition.
+
+ - ``struct`` - Name of the struct definition to be used for the attribute.
+
+Operations
+----------
+
+The genetlink-legacy families can use a binary fixed header that contains C
+struct data.
+
+ - ``fixed-header`` - name of the struct definition to be used for the fixed
+   header data. This can be specified as a default for all operations and on a
+   per-operation basis.
Signature · 1 line
2.41.0
author maintainer
#9 lore raw

PATCH v2 3/10 doc/netlink: Document the netlink-raw schema extensions

In reply to Donald Hunter

Add description of netlink-raw specific attributes to the ynl spec documentation and refer to the classic netlink documentation.

---
 Documentation/userspace-api/netlink/intro.rst |  2 ++
 Documentation/userspace-api/netlink/specs.rst | 17 +++++++++++++++++
 2 files changed, 19 insertions(+)
Documentation/userspace-api/netlink/intro.rst +2 -0
index 0955e9f203d3..3ea70ad53c58 100644
@@ -528,6 +528,8 @@ families may, however, require a larger buffer. 32kB buffer is recommended
 for most efficient handling of dumps (larger buffer fits more dumped
 objects and therefore fewer recvmsg() calls are needed).
 
+.. _classic_netlink:
+
 Classic Netlink
 ===============
 
Documentation/userspace-api/netlink/specs.rst +17 -0
index dde70f9674d4..98978a014488 100644
@@ -490,3 +490,20 @@ struct data.
  - ``fixed-header`` - name of the struct definition to be used for the fixed
    header data. This can be specified as a default for all operations and on a
    per-operation basis.
+
+netlink-raw
+===========
+
+The netlink-raw schema extends the genetlink-legacy schema with properties that
+are needed to specify the protocol numbers and multicast IDs used by raw netlink
+families. See :ref:`classic_netlink` for more information.
+
+Globals
+-------
+
+ - ``protonum`` - Protocol number to use when opening a netlink socket.
+
+Multicast group properties
+--------------------------
+
+ - ``value`` - ID to use for multicast group registration.
Signature · 1 line
2.41.0
author maintainer
#12 lore raw

PATCH v2 4/10 tools/ynl: Add mcast-group schema parsing to ynl

In reply to Donald Hunter

Add a SpecMcastGroup class to the nlspec lib.

---
 tools/net/ynl/lib/nlspec.py | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)
tools/net/ynl/lib/nlspec.py +26 -0
index 0ff0d18666b2..a41ad89eb369 100644
@@ -322,6 +322,21 @@ class SpecOperation(SpecElement):
             self.attr_set = self.family.attr_sets[attr_set_name]
 
 
+class SpecMcastGroup(SpecElement):
+    """Netlink Multicast Group
+
+    Information about a multicast group.
+
+    Attributes:
+        name      name of the mulitcast group
+        value     numerical id of this multicast group for netlink-raw
+        yaml      raw spec as loaded from the spec file
+    """
+    def __init__(self, family, yaml):
+        super().__init__(family, yaml)
+        self.value = self.yaml.get('value')
+
+
 class SpecFamily(SpecElement):
     """ Netlink Family Spec class.
 
@@ -343,6 +358,7 @@ class SpecFamily(SpecElement):
         ntfs       dict of all async events
         consts     dict of all constants/enums
         fixed_header  string, optional name of family default fixed header struct
+        mcast_groups  dict of all multicast groups (index by name)
     """
     def __init__(self, spec_path, schema_path=None, exclude_ops=None):
         with open(spec_path, "r") as stream:
@@ -384,6 +400,7 @@ class SpecFamily(SpecElement):
         self.ops = collections.OrderedDict()
         self.ntfs = collections.OrderedDict()
         self.consts = collections.OrderedDict()
+        self.mcast_groups = collections.OrderedDict()
 
         last_exception = None
         while len(self._resolution_list) > 0:
@@ -416,6 +433,9 @@ class SpecFamily(SpecElement):
     def new_operation(self, elem, req_val, rsp_val):
         return SpecOperation(self, elem, req_val, rsp_val)
 
+    def new_mcast_group(self, elem):
+        return SpecMcastGroup(self, elem)
+
     def add_unresolved(self, elem):
         self._resolution_list.append(elem)
 
@@ -512,3 +532,9 @@ class SpecFamily(SpecElement):
                 self.ops[op.name] = op
             elif op.is_async:
                 self.ntfs[op.name] = op
+
+        mcgs = self.yaml.get('mcast-groups')
+        if mcgs:
+            for elem in mcgs['list']:
+                mcg = self.new_mcast_group(elem)
+                self.mcast_groups[elem['name']] = mcg
Signature · 1 line
2.41.0
author maintainer
#14 lore raw

PATCH v2 5/10 tools/net/ynl: Refactor decode_fixed_header into NlMsg

In reply to Donald Hunter

Move decode_fixed_header into NlMsg in preparation for adding netlink-raw support.

---
 tools/net/ynl/lib/ynl.py | 39 ++++++++++++++++++++++++---------------
 1 file changed, 24 insertions(+), 15 deletions(-)
tools/net/ynl/lib/ynl.py +24 -15
index 3ca28d4bcb18..4fa42a7c5955 100644
@@ -189,6 +189,7 @@ class NlMsg:
 
         self.error = 0
         self.done = 0
+        self.fixed_header_attrs = []
 
         extack_off = None
         if self.nl_type == Netlink.NLMSG_ERROR:
@@ -228,6 +229,19 @@ class NlMsg:
                             desc += f" ({spec['doc']})"
                         self.extack['miss-type'] = desc
 
+    def decode_fixed_header(self, ynl, name):
+        fixed_header_members = ynl.consts[name].members
+        self.fixed_header_attrs = dict()
+        offset = 0
+        for m in fixed_header_members:
+            format = NlAttr.get_format(m.type, m.byte_order)
+            [ value ] = format.unpack_from(self.raw, offset)
+            offset += format.size
+            if m.enum:
+                value = ynl._decode_enum(value, m)
+            self.fixed_header_attrs[m.name] = value
+        self.raw = self.raw[offset:]
+
     def __repr__(self):
         msg = f"nl_len = {self.nl_len} ({len(self.raw)}) nl_flags = 0x{self.nl_flags:x} nl_type = {self.nl_type}\n"
         if self.error:
@@ -317,23 +331,18 @@ def _genl_load_families():
 
 
 class GenlMsg:
-    def __init__(self, nl_msg, fixed_header_members=[]):
-        self.nl = nl_msg
+    def __init__(self, nl_msg, ynl=None):
+        self.genl_cmd, self.genl_version, _ = struct.unpack_from("BBH", nl_msg.raw, 0)
+        nl_msg.raw = nl_msg.raw[4:]
 
-        self.hdr = nl_msg.raw[0:4]
-        offset = 4
-
-        self.genl_cmd, self.genl_version, _ = struct.unpack("BBH", self.hdr)
-
-        self.fixed_header_attrs = dict()
-        for m in fixed_header_members:
-            format = NlAttr.get_format(m.type, m.byte_order)
-            decoded = format.unpack_from(nl_msg.raw, offset)
-            offset += format.size
-            self.fixed_header_attrs[m.name] = decoded[0]
+        if ynl:
+            op = ynl.rsp_by_value[self.genl_cmd]
+            if op.fixed_header:
+                nl_msg.decode_fixed_header(ynl, op.fixed_header)
 
-        self.raw = nl_msg.raw[offset:]
+        self.raw = nl_msg.raw
         self.raw_attrs = NlAttrs(self.raw)
+        self.fixed_header_attrs = nl_msg.fixed_header_attrs
 
     def __repr__(self):
         msg = repr(self.nl)
@@ -596,7 +605,7 @@ class YnlFamily(SpecFamily):
                     done = True
                     break
 
-                gm = GenlMsg(nl_msg, fixed_header_members)
+                gm = GenlMsg(nl_msg, self)
                 # Check if this is a reply to our request
                 if nl_msg.nl_seq != req_seq or gm.genl_cmd != op.rsp_value:
                     if gm.genl_cmd in self.async_msg_ids:
Signature · 1 line
2.41.0
author maintainer
#19 lore raw

PATCH v2 6/10 tools/net/ynl: Add support for netlink-raw families

In reply to Donald Hunter

Refactor the ynl code to encapsulate protocol specifics into NetlinkProtocol and GenlProtocol.

---
 tools/net/ynl/lib/ynl.py | 103 +++++++++++++++++++++++++++++----------
 1 file changed, 78 insertions(+), 25 deletions(-)
tools/net/ynl/lib/ynl.py +78 -25
index 4fa42a7c5955..325dc0d9c5b5 100644
@@ -25,6 +25,7 @@ class Netlink:
     NETLINK_ADD_MEMBERSHIP = 1
     NETLINK_CAP_ACK = 10
     NETLINK_EXT_ACK = 11
+    NETLINK_GET_STRICT_CHK = 12
 
     # Netlink message
     NLMSG_ERROR = 2
@@ -242,6 +243,9 @@ class NlMsg:
             self.fixed_header_attrs[m.name] = value
         self.raw = self.raw[offset:]
 
+    def cmd(self):
+        return self.nl_type
+
     def __repr__(self):
         msg = f"nl_len = {self.nl_len} ({len(self.raw)}) nl_flags = 0x{self.nl_flags:x} nl_type = {self.nl_type}\n"
         if self.error:
@@ -344,6 +348,9 @@ class GenlMsg:
         self.raw_attrs = NlAttrs(self.raw)
         self.fixed_header_attrs = nl_msg.fixed_header_attrs
 
+    def cmd(self):
+        return self.genl_cmd
+
     def __repr__(self):
         msg = repr(self.nl)
         msg += f"\tgenl_cmd = {self.genl_cmd} genl_ver = {self.genl_version}\n"
@@ -352,9 +359,35 @@ class GenlMsg:
         return msg
 
 
-class GenlFamily:
-    def __init__(self, family_name):
+class NetlinkProtocol:
+    def __init__(self, family_name, proto_num):
         self.family_name = family_name
+        self.proto_num = proto_num
+
+    def _message(self, nl_type, nl_flags, seq=None):
+        if seq is None:
+            seq = random.randint(1, 1024)
+        nlmsg = struct.pack("HHII", nl_type, nl_flags, seq, 0)
+        return nlmsg
+
+    def message(self, flags, command, version, seq=None):
+        return self._message(command, flags, seq)
+
+    def decode(self, ynl, nl_msg):
+        op = ynl.rsp_by_value[nl_msg.nl_type]
+        if op.fixed_header:
+            nl_msg.decode_fixed_header(ynl, op.fixed_header)
+        nl_msg.raw_attrs = NlAttrs(nl_msg.raw)
+        return nl_msg
+
+    def get_mcast_id(self, mcast_name, mcast_groups):
+        if mcast_name not in mcast_groups:
+            raise Exception(f'Multicast group "{mcast_name}" not present in the spec')
+        return mcast_groups[mcast_name].id
+
+class GenlProtocol(NetlinkProtocol):
+    def __init__(self, family_name):
+        super().__init__(family_name, Netlink.NETLINK_GENERIC)
 
         global genl_family_name_to_id
         if genl_family_name_to_id is None:
@@ -363,6 +396,18 @@ class GenlFamily:
         self.genl_family = genl_family_name_to_id[family_name]
         self.family_id = genl_family_name_to_id[family_name]['id']
 
+    def message(self, flags, command, version, seq=None):
+        nlmsg = self._message(self.family_id, flags, seq)
+        genlmsg = struct.pack("BBH", command, version, 0)
+        return nlmsg + genlmsg
+
+    def decode(self, ynl, nl_msg):
+        return GenlMsg(nl_msg, ynl)
+
+    def get_mcast_id(self, mcast_name, mcast_groups):
+        if mcast_name not in self.genl_family['mcast']:
+            raise Exception(f'Multicast group "{mcast_name}" not present in the family')
+        return self.genl_family['mcast'][mcast_name]
 
 #
 # YNL implementation details.
@@ -375,9 +420,19 @@ class YnlFamily(SpecFamily):
 
         self.include_raw = False
 
-        self.sock = socket.socket(socket.AF_NETLINK, socket.SOCK_RAW, Netlink.NETLINK_GENERIC)
+        try:
+            if self.proto == "netlink-raw":
+                self.nlproto = NetlinkProtocol(self.yaml['name'],
+                                               self.yaml['protonum'])
+            else:
+                self.nlproto = GenlProtocol(self.yaml['name'])
+        except KeyError:
+            raise Exception(f"Family '{self.yaml['name']}' not supported by the kernel")
+
+        self.sock = socket.socket(socket.AF_NETLINK, socket.SOCK_RAW, self.nlproto.proto_num)
         self.sock.setsockopt(Netlink.SOL_NETLINK, Netlink.NETLINK_CAP_ACK, 1)
         self.sock.setsockopt(Netlink.SOL_NETLINK, Netlink.NETLINK_EXT_ACK, 1)
+        self.sock.setsockopt(Netlink.SOL_NETLINK, Netlink.NETLINK_GET_STRICT_CHK, 1)
 
         self.async_msg_ids = set()
         self.async_msg_queue = []
@@ -390,18 +445,12 @@ class YnlFamily(SpecFamily):
             bound_f = functools.partial(self._op, op_name)
             setattr(self, op.ident_name, bound_f)
 
-        try:
-            self.family = GenlFamily(self.yaml['name'])
-        except KeyError:
-            raise Exception(f"Family '{self.yaml['name']}' not supported by the kernel")
 
     def ntf_subscribe(self, mcast_name):
-        if mcast_name not in self.family.genl_family['mcast']:
-            raise Exception(f'Multicast group "{mcast_name}" not present in the family')
-
+        mcast_id = self.nlproto.get_mcast_id(mcast_name, self.mcast_groups)
         self.sock.bind((0, 0))
         self.sock.setsockopt(Netlink.SOL_NETLINK, Netlink.NETLINK_ADD_MEMBERSHIP,
-                             self.family.genl_family['mcast'][mcast_name])
+                             mcast_id)
 
     def _add_attr(self, space, name, value):
         attr = self.attr_sets[space][name]
@@ -525,9 +574,12 @@ class YnlFamily(SpecFamily):
         if self.include_raw:
             msg['nlmsg'] = nl_msg
             msg['genlmsg'] = genl_msg
-        op = self.rsp_by_value[genl_msg.genl_cmd]
+        op = self.rsp_by_value[genl_msg.cmd()]
+        decoded = self._decode(genl_msg.raw_attrs, op.attr_set.name)
+        decoded.update(genl_msg.fixed_header_attrs)
+
         msg['name'] = op['name']
-        msg['msg'] = self._decode(genl_msg.raw_attrs, op.attr_set.name)
+        msg['msg'] = decoded
         self.async_msg_queue.append(msg)
 
     def check_ntf(self):
@@ -547,12 +599,12 @@ class YnlFamily(SpecFamily):
                     print("Netlink done while checking for ntf!?")
                     continue
 
-                gm = GenlMsg(nl_msg)
-                if gm.genl_cmd not in self.async_msg_ids:
-                    print("Unexpected msg id done while checking for ntf", gm)
+                decoded = self.nlproto.decode(self, nl_msg)
+                if decoded.cmd() not in self.async_msg_ids:
+                    print("Unexpected msg id done while checking for ntf", decoded)
                     continue
 
-                self.handle_ntf(nl_msg, gm)
+                self.handle_ntf(nl_msg, decoded)
 
     def operation_do_attributes(self, name):
       """
@@ -573,7 +625,7 @@ class YnlFamily(SpecFamily):
             nl_flags |= Netlink.NLM_F_DUMP
 
         req_seq = random.randint(1024, 65535)
-        msg = _genl_msg(self.family.family_id, nl_flags, op.req_value, 1, req_seq)
+        msg = self.nlproto.message(nl_flags, op.req_value, 1, req_seq)
         fixed_header_members = []
         if op.fixed_header:
             fixed_header_members = self.consts[op.fixed_header].members
@@ -605,18 +657,19 @@ class YnlFamily(SpecFamily):
                     done = True
                     break
 
-                gm = GenlMsg(nl_msg, self)
+                decoded = self.nlproto.decode(self, nl_msg)
+
                 # Check if this is a reply to our request
-                if nl_msg.nl_seq != req_seq or gm.genl_cmd != op.rsp_value:
-                    if gm.genl_cmd in self.async_msg_ids:
-                        self.handle_ntf(nl_msg, gm)
+                if nl_msg.nl_seq != req_seq or decoded.cmd() != op.rsp_value:
+                    if decoded.cmd() in self.async_msg_ids:
+                        self.handle_ntf(nl_msg, decoded)
                         continue
                     else:
-                        print('Unexpected message: ' + repr(gm))
+                        print('Unexpected message: ' + repr(decoded))
                         continue
 
-                rsp_msg = self._decode(gm.raw_attrs, op.attr_set.name)
-                rsp_msg.update(gm.fixed_header_attrs)
+                rsp_msg = self._decode(decoded.raw_attrs, op.attr_set.name)
+                rsp_msg.update(decoded.fixed_header_attrs)
                 rsp.append(rsp_msg)
 
         if not rsp:
Signature · 1 line
2.41.0
author maintainer
#24 lore raw

PATCH v2 7/10 tools/net/ynl: Implement nlattr array-nest decoding in ynl

In reply to Donald Hunter

Add support for the 'array-nest' attribute type that is used by several netlink-raw families.

---
 tools/net/ynl/lib/ynl.py | 13 +++++++++++++
 1 file changed, 13 insertions(+)
tools/net/ynl/lib/ynl.py +13 -0
index 325dc0d9c5b5..cd983d1f2ee6 100644
@@ -504,6 +504,17 @@ class YnlFamily(SpecFamily):
                 decoded = NlAttr.formatted_string(decoded, attr_spec.display_hint)
         return decoded
 
+    def _decode_array_nest(self, attr, attr_spec):
+        decoded = []
+        offset = 0
+        while offset < len(attr.raw):
+            item = NlAttr(attr.raw, offset)
+            offset += item.full_len
+
+            subattrs = self._decode(NlAttrs(item.raw), attr_spec['nested-attributes'])
+            decoded.append({ item.type: subattrs })
+        return decoded
+
     def _decode(self, attrs, space):
         attr_space = self.attr_sets[space]
         rsp = dict()
@@ -520,6 +531,8 @@ class YnlFamily(SpecFamily):
                 decoded = True
             elif attr_spec["type"] in NlAttr.type_formats:
                 decoded = attr.as_scalar(attr_spec['type'], attr_spec.byte_order)
+            elif attr_spec["type"] == 'array-nest':
+                decoded = self._decode_array_nest(attr, attr_spec)
             else:
                 raise Exception(f'Unknown {attr_spec["type"]} with name {attr_spec["name"]}')
 
Signature · 1 line
2.41.0
author maintainer
#26 lore raw

PATCH v2 8/10 doc/netlink: Add spec for rt addr messages

In reply to Donald Hunter

Add schema for rt addr with support for:
- newaddr, deladdr, getaddr (dump)

---
 Documentation/netlink/specs/rt_addr.yaml | 179 +++++++++++++++++++++++
 1 file changed, 179 insertions(+)
 create mode 100644 Documentation/netlink/specs/rt_addr.yaml
Documentation/netlink/specs/rt_addr.yaml new file +179 -0
new file mode 100644
index 000000000000..cbee1cedb177
@@ -0,0 +1,179 @@
+# SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)
+
+name: rt-addr
+protocol: netlink-raw
+protonum: 0
+
+doc:
+  Address configuration over rtnetlink.
+
+definitions:
+  -
+    name: ifaddrmsg
+    type: struct
+    members:
+      -
+        name: ifa-family
+        type: u8
+      -
+        name: ifa-prefixlen
+        type: u8
+      -
+        name: ifa-flags
+        type: u8
+        enum: ifa-flags
+        enum-as-flags: true
+      -
+        name: ifa-scope
+        type: u8
+      -
+        name: ifa-index
+        type: u32
+  -
+    name: ifa-cacheinfo
+    type: struct
+    members:
+      -
+        name: ifa-prefered
+        type: u32
+      -
+        name: ifa-valid
+        type: u32
+      -
+        name: cstamp
+        type: u32
+      -
+        name: tstamp
+        type: u32
+
+  -
+    name: ifa-flags
+    type: flags
+    entries:
+      -
+        name: secondary
+      -
+        name: nodad
+      -
+        name: optimistic
+      -
+        name: dadfailed
+      -
+        name: homeaddress
+      -
+        name: deprecated
+      -
+        name: tentative
+      -
+        name: permanent
+      -
+        name: managetempaddr
+      -
+        name: noprefixroute
+      -
+        name: mcautojoin
+      -
+        name: stable-privacy
+
+attribute-sets:
+  -
+    name: addr-attrs
+    attributes:
+      -
+        name: ifa-address
+        type: binary
+        display-hint: ipv4
+      -
+        name: ifa-local
+        type: binary
+        display-hint: ipv4
+      -
+        name: ifa-label
+        type: string
+      -
+        name: ifa-broadcast
+        type: binary
+        display-hint: ipv4
+      -
+        name: ifa-anycast
+        type: binary
+      -
+        name: ifa-cacheinfo
+        type: binary
+        struct: ifa-cacheinfo
+      -
+        name: ifa-multicast
+        type: binary
+      -
+        name: ifa-flags
+        type: u32
+        enum: ifa-flags
+        enum-as-flags: true
+      -
+        name: ifa-rt-priority
+        type: u32
+      -
+        name: ifa-target-netnsid
+        type: binary
+      -
+        name: ifa-proto
+        type: u8
+
+
+operations:
+  fixed-header: ifaddrmsg
+  enum-model: directional
+  list:
+    -
+      name: newaddr
+      doc: Add new address
+      attribute-set: addr-attrs
+      do:
+        request:
+          value: 20
+          attributes: &ifaddr-all
+            - ifa-family
+            - ifa-flags
+            - ifa-prefixlen
+            - ifa-scope
+            - ifa-index
+            - ifa-address
+            - ifa-label
+            - ifa-local
+            - ifa-cacheinfo
+    -
+      name: deladdr
+      doc: Remove address
+      attribute-set: addr-attrs
+      do:
+        request:
+          value: 21
+          attributes:
+            - ifa-family
+            - ifa-flags
+            - ifa-prefixlen
+            - ifa-scope
+            - ifa-index
+            - ifa-address
+            - ifa-local
+    -
+      name: getaddr
+      doc: Dump address information.
+      attribute-set: addr-attrs
+      dump:
+        request:
+          value: 22
+          attributes:
+            - ifa-index
+        reply:
+          value: 20
+          attributes: *ifaddr-all
+
+mcast-groups:
+  list:
+    -
+      name: rtnlgrp-ipv4-ifaddr
+      value: 5
+    -
+      name: rtnlgrp-ipv6-ifaddr
+      value: 9
Signature · 1 line
2.41.0
author maintainer
#27 lore raw

PATCH v2 9/10 doc/netlink: Add spec for rt link messages

In reply to Donald Hunter

Add schema for rt link with support for newlink, dellink, getlink, setlink and getstats.

For example, offload stats can be fetched like this:

./tools/net/ynl/cli.py \
    --spec Documentation/netlink/specs/rt_link.yaml \
    --dump getstats --json '{ "filter-mask": 8 }'
---
 Documentation/netlink/specs/rt_link.yaml | 1374 ++++++++++++++++++++++
 1 file changed, 1374 insertions(+)
 create mode 100644 Documentation/netlink/specs/rt_link.yaml
Documentation/netlink/specs/rt_link.yaml new file +1374 -0
new file mode 100644
index 000000000000..f9b7aedbc0ac
@@ -0,0 +1,1374 @@
+# SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)
+
+name: rt-link
+protocol: netlink-raw
+protonum: 0
+
+doc:
+  Link configuration over rtnetlink.
+
+definitions:
+  -
+    name: ifinfo-flags
+    type: flags
+    entries:
+      -
+        name: up
+      -
+        name: broadcast
+      -
+        name: debug
+      -
+        name: loopback
+      -
+        name: point-to-point
+      -
+        name: no-trailers
+      -
+        name: running
+      -
+        name: no-arp
+      -
+        name: promisc
+      -
+        name: all-multi
+      -
+        name: master
+      -
+        name: slave
+      -
+        name: multicast
+      -
+        name: portsel
+      -
+        name: auto-media
+      -
+        name: dynamic
+      -
+        name: lower-up
+      -
+        name: dormant
+      -
+        name: echo
+
+  -
+    name: rtgenmsg
+    type: struct
+    members:
+      -
+        name: family
+        type: u8
+  -
+    name: ifinfomsg
+    type: struct
+    members:
+      -
+        name: ifi-family
+        type: u8
+      -
+        name: padding
+        type: u8
+      -
+        name: ifi-type
+        type: u16
+      -
+        name: ifi-index
+        type: s32
+      -
+        name: ifi-flags
+        type: u32
+        enum: ifinfo-flags
+        enum-as-flags: true
+      -
+        name: ifi-change
+        type: u32
+  -
+    name: ifla-cacheinfo
+    type: struct
+    members:
+      -
+        name: max-reasm-len
+        type: u32
+      -
+        name: tstamp
+        type: u32
+      -
+        name: reachable-time
+        type: s32
+      -
+        name: retrans-time
+        type: u32
+  -
+    name: rtnl-link-stats
+    type: struct
+    members:
+      -
+        name: rx-packets
+        type: u32
+      -
+        name: tx-packets
+        type: u32
+      -
+        name: rx-bytes
+        type: u32
+      -
+        name: tx-bytes
+        type: u32
+      -
+        name: rx-errors
+        type: u32
+      -
+        name: tx-errors
+        type: u32
+      -
+        name: rx-dropped
+        type: u32
+      -
+        name: tx-dropped
+        type: u32
+      -
+        name: multicast
+        type: u32
+      -
+        name: collisions
+        type: u32
+      -
+        name: rx-length-errors
+        type: u32
+      -
+        name: rx-over-errors
+        type: u32
+      -
+        name: rx-crc-errors
+        type: u32
+      -
+        name: rx-frame-errors
+        type: u32
+      -
+        name: rx-fifo-errors
+        type: u32
+      -
+        name: rx-missed-errors
+        type: u32
+      -
+        name: tx-aborted-errors
+        type: u32
+      -
+        name: tx-carrier-errors
+        type: u32
+      -
+        name: tx-fifo-errors
+        type: u32
+      -
+        name: tx-heartbeat-errors
+        type: u32
+      -
+        name: tx-window-errors
+        type: u32
+      -
+        name: rx-compressed
+        type: u32
+      -
+        name: tx-compressed
+        type: u32
+      -
+        name: rx-nohandler
+        type: u32
+  -
+    name: rtnl-link-stats64
+    type: struct
+    members:
+      -
+        name: rx-packets
+        type: u64
+      -
+        name: tx-packets
+        type: u64
+      -
+        name: rx-bytes
+        type: u64
+      -
+        name: tx-bytes
+        type: u64
+      -
+        name: rx-errors
+        type: u64
+      -
+        name: tx-errors
+        type: u64
+      -
+        name: rx-dropped
+        type: u64
+      -
+        name: tx-dropped
+        type: u64
+      -
+        name: multicast
+        type: u64
+      -
+        name: collisions
+        type: u64
+      -
+        name: rx-length-errors
+        type: u64
+      -
+        name: rx-over-errors
+        type: u64
+      -
+        name: rx-crc-errors
+        type: u64
+      -
+        name: rx-frame-errors
+        type: u64
+      -
+        name: rx-fifo-errors
+        type: u64
+      -
+        name: rx-missed-errors
+        type: u64
+      -
+        name: tx-aborted-errors
+        type: u64
+      -
+        name: tx-carrier-errors
+        type: u64
+      -
+        name: tx-fifo-errors
+        type: u64
+      -
+        name: tx-heartbeat-errors
+        type: u64
+      -
+        name: tx-window-errors
+        type: u64
+      -
+        name: rx-compressed
+        type: u64
+      -
+        name: tx-compressed
+        type: u64
+      -
+        name: rx-nohandler
+        type: u64
+      -
+        name: rx-otherhost-dropped
+        type: u64
+  -
+    name: rtnl-link-ifmap
+    type: struct
+    members:
+      -
+        name: mem-start
+        type: u64
+      -
+        name: mem-end
+        type: u64
+      -
+        name: base-addr
+        type: u64
+      -
+        name: irq
+        type: u16
+      -
+        name: dma
+        type: u8
+      -
+        name: port
+        type: u8
+  -
+    name: ipv4-devconf
+    type: struct
+    members:
+      -
+        name: forwarding
+        type: u32
+      -
+        name: mc-forwarding
+        type: u32
+      -
+        name: proxy-arp
+        type: u32
+      -
+        name: accept-redirects
+        type: u32
+      -
+        name: secure-redirects
+        type: u32
+      -
+        name: send-redirects
+        type: u32
+      -
+        name: shared-media
+        type: u32
+      -
+        name: rp-filter
+        type: u32
+      -
+        name: accept-source-route
+        type: u32
+      -
+        name: bootp-relay
+        type: u32
+      -
+        name: log-martians
+        type: u32
+      -
+        name: tag
+        type: u32
+      -
+        name: arpfilter
+        type: u32
+      -
+        name: medium-id
+        type: u32
+      -
+        name: noxfrm
+        type: u32
+      -
+        name: nopolicy
+        type: u32
+      -
+        name: force-igmp-version
+        type: u32
+      -
+        name: arp-announce
+        type: u32
+      -
+        name: arp-ignore
+        type: u32
+      -
+        name: promote-secondaries
+        type: u32
+      -
+        name: arp-accept
+        type: u32
+      -
+        name: arp-notify
+        type: u32
+      -
+        name: accept-local
+        type: u32
+      -
+        name: src-vmark
+        type: u32
+      -
+        name: proxy-arp-pvlan
+        type: u32
+      -
+        name: route-localnet
+        type: u32
+      -
+        name: igmpv2-unsolicited-report-interval
+        type: u32
+      -
+        name: igmpv3-unsolicited-report-interval
+        type: u32
+      -
+        name: ignore-routes-with-linkdown
+        type: u32
+      -
+        name: drop-unicast-in-l2-multicast
+        type: u32
+      -
+        name: drop-gratuitous-arp
+        type: u32
+      -
+        name: bc-forwarding
+        type: u32
+      -
+        name: arp-evict-nocarrier
+        type: u32
+  -
+    name: ipv6-devconf
+    type: struct
+    members:
+      -
+        name: forwarding
+        type: u32
+      -
+        name: hoplimit
+        type: u32
+      -
+        name: mtu6
+        type: u32
+      -
+        name: accept-ra
+        type: u32
+      -
+        name: accept-redirects
+        type: u32
+      -
+        name: autoconf
+        type: u32
+      -
+        name: dad-transmits
+        type: u32
+      -
+        name: rtr-solicits
+        type: u32
+      -
+        name: rtr-solicit-interval
+        type: u32
+      -
+        name: rtr-solicit-delay
+        type: u32
+      -
+        name: use-tempaddr
+        type: u32
+      -
+        name: temp-valid-lft
+        type: u32
+      -
+        name: temp-prefered-lft
+        type: u32
+      -
+        name: regen-max-retry
+        type: u32
+      -
+        name: max-desync-factor
+        type: u32
+      -
+        name: max-addresses
+        type: u32
+      -
+        name: force-mld-version
+        type: u32
+      -
+        name: accept-ra-defrtr
+        type: u32
+      -
+        name: accept-ra-pinfo
+        type: u32
+      -
+        name: accept-ra-rtr-pref
+        type: u32
+      -
+        name: rtr-probe-interval
+        type: u32
+      -
+        name: accept-ra-rt-info-max-plen
+        type: u32
+      -
+        name: proxy-ndp
+        type: u32
+      -
+        name: optimistic-dad
+        type: u32
+      -
+        name: accept-source-route
+        type: u32
+      -
+        name: mc-forwarding
+        type: u32
+      -
+        name: disable-ipv6
+        type: u32
+      -
+        name: accept-dad
+        type: u32
+      -
+        name: force-tllao
+        type: u32
+      -
+        name: ndisc-notify
+        type: u32
+      -
+        name: mldv1-unsolicited-report-interval
+        type: u32
+      -
+        name: mldv2-unsolicited-report-interval
+        type: u32
+      -
+        name: suppress-frag-ndisc
+        type: u32
+      -
+        name: accept-ra-from-local
+        type: u32
+      -
+        name: use-optimistic
+        type: u32
+      -
+        name: accept-ra-mtu
+        type: u32
+      -
+        name: stable-secret
+        type: u32
+      -
+        name: use-oif-addrs-only
+        type: u32
+      -
+        name: accept-ra-min-hop-limit
+        type: u32
+      -
+        name: ignore-routes-with-linkdown
+        type: u32
+      -
+        name: drop-unicast-in-l2-multicast
+        type: u32
+      -
+        name: drop-unsolicited-na
+        type: u32
+      -
+        name: keep-addr-on-down
+        type: u32
+      -
+        name: rtr-solicit-max-interval
+        type: u32
+      -
+        name: seg6-enabled
+        type: u32
+      -
+        name: seg6-require-hmac
+        type: u32
+      -
+        name: enhanced-dad
+        type: u32
+      -
+        name: addr-gen-mode
+        type: u32
+      -
+        name: disable-policy
+        type: u32
+      -
+        name: accept-ra-rt-info-min-plen
+        type: u32
+      -
+        name: ndisc-tclass
+        type: u32
+      -
+        name: rpl-seg-enabled
+        type: u32
+      -
+        name: ra-defrtr-metric
+        type: u32
+      -
+        name: ioam6-enabled
+        type: u32
+      -
+        name: ioam6-id
+        type: u32
+      -
+        name: ioam6-id-wide
+        type: u32
+      -
+        name: ndisc-evict-nocarrier
+        type: u32
+      -
+        name: accept-untracked-na
+        type: u32
+  -
+    name: ifla-icmp6-stats
+    type: struct
+    members:
+      -
+        name: inmsgs
+        type: u64
+      -
+        name: inerrors
+        type: u64
+      -
+        name: outmsgs
+        type: u64
+      -
+        name: outerrors
+        type: u64
+      -
+        name: csumerrors
+        type: u64
+      -
+        name: ratelimithost
+        type: u64
+  -
+    name: ifla-inet6-stats
+    type: struct
+    members:
+      -
+        name: inpkts
+        type: u64
+      -
+        name: inoctets
+        type: u64
+      -
+        name: indelivers
+        type: u64
+      -
+        name: outforwdatagrams
+        type: u64
+      -
+        name: outpkts
+        type: u64
+      -
+        name: outoctets
+        type: u64
+      -
+        name: inhdrerrors
+        type: u64
+      -
+        name: intoobigerrors
+        type: u64
+      -
+        name: innoroutes
+        type: u64
+      -
+        name: inaddrerrors
+        type: u64
+      -
+        name: inunknownprotos
+        type: u64
+      -
+        name: intruncatedpkts
+        type: u64
+      -
+        name: indiscards
+        type: u64
+      -
+        name: outdiscards
+        type: u64
+      -
+        name: outnoroutes
+        type: u64
+      -
+        name: reasmtimeout
+        type: u64
+      -
+        name: reasmreqds
+        type: u64
+      -
+        name: reasmoks
+        type: u64
+      -
+        name: reasmfails
+        type: u64
+      -
+        name: fragoks
+        type: u64
+      -
+        name: fragfails
+        type: u64
+      -
+        name: fragcreates
+        type: u64
+      -
+        name: inmcastpkts
+        type: u64
+      -
+        name: outmcastpkts
+        type: u64
+      -
+        name: inbcastpkts
+        type: u64
+      -
+        name: outbcastpkts
+        type: u64
+      -
+        name: inmcastoctets
+        type: u64
+      -
+        name: outmcastoctets
+        type: u64
+      -
+        name: inbcastoctets
+        type: u64
+      -
+        name: outbcastoctets
+        type: u64
+      -
+        name: csumerrors
+        type: u64
+      -
+        name: noectpkts
+        type: u64
+      -
+        name: ect1-pkts
+        type: u64
+      -
+        name: ect0-pkts
+        type: u64
+      -
+        name: cepkts
+        type: u64
+      -
+        name: reasm-overlaps
+        type: u64
+  - name: br-boolopt-multi
+    type: struct
+    members:
+      -
+        name: optval
+        type: u32
+      -
+        name: optmask
+        type: u32
+  -
+    name: if_stats_msg
+    type: struct
+    members:
+      -
+        name: family
+        type: u8
+      -
+        name: pad1
+        type: u8
+      -
+        name: pad2
+        type: u16
+      -
+        name: ifindex
+        type: u32
+      -
+        name: filter-mask
+        type: u32
+
+
+attribute-sets:
+  -
+    name: link-attrs
+    name-prefix: ifla-
+    attributes:
+      -
+        name: address
+        type: binary
+        display-hint: mac
+        value: 1
+      -
+        name: broadcast
+        type: binary
+        display-hint: mac
+        value: 2
+      -
+        name: ifname
+        type: string
+        value: 3
+      -
+        name: mtu
+        type: u32
+        value: 4
+      -
+        name: link
+        type: u32
+        value: 5
+      -
+        name: qdisc
+        type: string
+        value: 6
+      -
+        name: stats
+        type: binary
+        value: 7
+        struct: rtnl-link-stats
+      -
+        name: cost
+        type: string
+        value: 8
+      -
+        name: priority
+        type: string
+        value: 9
+      -
+        name: master
+        type: u32
+        value: 10
+      -
+        name: wireless
+        type: string
+        value: 11
+      -
+        name: protinfo
+        type: string
+        value: 12
+      -
+        name: txqlen
+        type: u32
+        value: 13
+      -
+        name: map
+        type: binary
+        value: 14
+        struct: rtnl-link-ifmap
+      -
+        name: weight
+        type: u32
+        value: 15
+      -
+        name: operstate
+        type: u8
+        value: 16
+      -
+        name: linkmode
+        type: u8
+        value: 17
+      -
+        name: linkinfo
+        type: nest
+        value: 18
+        nested-attributes: linkinfo-attrs
+      -
+        name: net-ns-pid
+        type: u32
+        value: 19
+      -
+        name: ifalias
+        type: string
+        value: 20
+      -
+        name: num-vf
+        type: u32
+        value: 21
+      -
+        name: vfinfo-list
+        type: nest
+        value: 22
+        nested-attributes: vfinfo-attrs
+      -
+        name: stats64
+        type: binary
+        value: 23
+        struct: rtnl-link-stats64
+      -
+        name: vf-ports
+        type: nest
+        value: 24
+        nested-attributes: vf-ports-attrs
+      -
+        name: port-self
+        type: nest
+        value: 25
+        nested-attributes: port-self-attrs
+      -
+        name: af-spec
+        type: nest
+        value: 26
+        nested-attributes: af-spec-attrs
+      -
+        name: group
+        type: u32
+        value: 27
+      -
+        name: net-ns-fd
+        type: u32
+        value: 28
+      -
+        name: ext-mask
+        type: u32
+        value: 29
+      -
+        name: promiscuity
+        type: u32
+        value: 30
+      -
+        name: num-tx-queues
+        type: u32
+        value: 31
+      -
+        name: num-rx-queues
+        type: u32
+        value: 32
+      -
+        name: carrier
+        type: u8
+        value: 33
+      -
+        name: phys-port-id
+        type: binary
+        value: 34
+      -
+        name: carrier-changes
+        type: u32
+        value: 35
+      -
+        name: phys-switch-id
+        type: binary
+        value: 36
+      -
+        name: link-netnsid
+        type: s32
+        value: 37
+      -
+        name: phys-port-name
+        type: string
+        value: 38
+      -
+        name: proto-down
+        type: u8
+        value: 39
+      -
+        name: gso-max-segs
+        type: u32
+        value: 40
+      -
+        name: gso-max-size
+        type: u32
+        value: 41
+      -
+        name: pad
+        type: string
+        value: 42
+      -
+        name: xdp
+        type: nest
+        value: 43
+        nested-attributes: xdp-attrs
+      -
+        name: event
+        type: u32
+        value: 44
+      -
+        name: new-netnsid
+        type: s32
+        value: 45
+      -
+        name: if-netnsid
+        type: s32
+        value: 46
+      -
+        name: target-netnsid
+        type: s32
+        value: 46
+      -
+        name: carrier-up-count
+        type: u32
+        value: 47
+      -
+        name: carrier-down-count
+        type: u32
+        value: 48
+      -
+        name: new-ifindex
+        type: s32
+        value: 49
+      -
+        name: min-mtu
+        type: u32
+        value: 50
+      -
+        name: max-mtu
+        type: u32
+        value: 51
+      -
+        name: prop-list
+        type: string
+        value: 52
+      -
+        name: alt-ifname
+        type: string
+        value: 53
+      -
+        name: perm-address
+        type: string
+        value: 54
+      -
+        name: proto-down-reason
+        type: string
+        value: 55
+      -
+        name: parent-dev-name
+        type: string
+        value: 56
+      -
+        name: parent-dev-bus-name
+        type: string
+        value: 57
+      -
+        name: gro-max-size
+        type: u32
+        value: 58
+      -
+        name: tso-max-size
+        type: u32
+        value: 59
+      -
+        name: tso-max-segs
+        type: u32
+        value: 60
+      -
+        name: allmulti
+        type: u32
+      -
+        name: devlink-port
+        type: binary
+      -
+        name: gso-ipv4-max-size
+        type: u32
+      -
+        name: gro-ipv4-max-size
+        type: u32
+  -
+    name: af-spec-attrs
+    attributes:
+      -
+        name: "inet"
+        type: nest
+        value: 2
+        nested-attributes: ifla-attrs
+      -
+        name: "inet6"
+        type: nest
+        value: 10
+        nested-attributes: ifla6-attrs
+      -
+        name: "mctp"
+        type: nest
+        value: 45
+        nested-attributes: mctp-attrs
+  -
+    name: vfinfo-attrs
+    attributes: []
+  -
+    name: vf-ports-attrs
+    attributes: []
+  -
+    name: port-self-attrs
+    attributes: []
+  -
+    name: linkinfo-attrs
+    attributes:
+      -
+        name: kind
+        type: string
+      -
+        name: data
+        type: binary
+        nested-attributes: linkinfo-bridge-attrs
+      -
+        name: xstats
+        type: binary
+      -
+        name: slave-kind
+        type: string
+      -
+        name: slave-data
+        type: nest
+        nested-attributes: linkinfo-slave-data-attrs
+  -
+    name: linkinfo-bridge-attrs
+    attributes:
+      -
+        name: forward-delay
+        type: u32
+      -
+        name: hello-time
+        type: u32
+      -
+        name: max-age
+        type: u32
+      -
+        name: ageing-time
+        type: u32
+      -
+        name: stp-state
+        type: u32
+      -
+        name: priority
+        type: u16
+      -
+        name: vlan-filtering
+        type: u8
+      -
+        name: vlan-protocol
+        type: u16
+      -
+        name: group-fwd-mask
+        type: u16
+      -
+        name: root-id
+        type: binary
+      -
+        name: bridge-id
+        type: binary
+      -
+        name: root-port
+        type: u16
+      -
+        name: root-path-cost
+        type: u32
+      -
+        name: topology-change
+        type: u8
+      -
+        name: topology-change-detected
+        type: u8
+      -
+        name: hello-timer
+        type: u64
+      -
+        name: tcn-timer
+        type: u64
+      -
+        name: topology-change-timer
+        type: u64
+      -
+        name: gc-timer
+        type: u64
+      -
+        name: group-addr
+        type: binary
+      -
+        name: fdb-flush
+        type: binary
+      -
+        name: mcast-router
+        type: u8
+      -
+        name: mcast-snooping
+        type: u8
+      -
+        name: mcast-query-use-ifaddr
+        type: u8
+      -
+        name: mcast-querier
+        type: u8
+      -
+        name: mcast-hash-elasticity
+        type: u32
+      -
+        name: mcast-hash-max
+        type: u32
+      -
+        name: mcast-last-member-cnt
+        type: u32
+      -
+        name: mcast-startup-query-cnt
+        type: u32
+      -
+        name: mcast-last-member-intvl
+        type: u64
+      -
+        name: mcast-membership-intvl
+        type: u64
+      -
+        name: mcast-querier-intvl
+        type: u64
+      -
+        name: mcast-query-intvl
+        type: u64
+      -
+        name: mcast-query-response-intvl
+        type: u64
+      -
+        name: mcast-startup-query-intvl
+        type: u64
+      -
+        name: nf-call-iptables
+        type: u8
+      -
+        name: nf-call-ip6-tables
+        type: u8
+      -
+        name: nf-call-arptables
+        type: u8
+      -
+        name: vlan-default-pvid
+        type: u16
+      -
+        name: pad
+        type: u32
+      -
+        name: vlan-stats-enabled
+        type: u8
+      -
+        name: mcast-stats-enabled
+        type: u8
+      -
+        name: mcast-igmp-version
+        type: u8
+      -
+        name: mcast-mld-version
+        type: u8
+      -
+        name: vlan-stats-per-port
+        type: u8
+      -
+        name: multi-boolopt
+        type: binary
+        struct: br-boolopt-multi
+      -
+        name: mcast-querier-state
+        type: binary
+  -
+    name: linkinfo-slave-data-attrs
+    attributes: []
+  -
+    name: xdp-attrs
+    attributes:
+      -
+        name: fd
+        type: s32
+      -
+        name: attached
+        type: u8
+      -
+        name: flags
+        type: u32
+      -
+        name: prog-id
+        type: u32
+      -
+        name: drv-prog-id
+        type: u32
+      -
+        name: skb-prog-id
+        type: u32
+      -
+        name: hw-prog-id
+        type: u32
+      -
+        name: expected-fd
+        type: s32
+  -
+    name: ifla-attrs
+    attributes:
+      -
+        name: conf
+        type: binary
+        struct: ipv4-devconf
+  -
+    name: ifla6-attrs
+    attributes:
+      -
+        name: flags
+        type: u32
+      -
+        name: conf
+        type: binary
+        struct: ipv6-devconf
+      -
+        name: stats
+        type: binary
+        struct: ifla-inet6-stats
+      -
+        name: mcast
+        type: binary
+      -
+        name: cacheinfo
+        type: binary
+        struct: ifla-cacheinfo
+      -
+        name: icmp6-stats
+        type: binary
+        struct: ifla-icmp6-stats
+      -
+        name: token
+        type: binary
+      -
+        name: addr-gen-mode
+        type: u8
+      -
+        name: ra-mtu
+        type: u32
+  -
+    name: mctp-attrs
+    attributes:
+      -
+        name: mctp-net
+        type: u32
+  -
+    name: stats-attrs
+    name-prefix: ifla-stats-
+    attributes:
+      -
+        name: link-64
+        type: binary
+        struct: rtnl-link-stats64
+      -
+        name: link-xstats
+        type: binary
+      -
+        name: link-xstats-slave
+        type: binary
+      -
+        name: link-offload-xstats
+        type: nest
+        nested-attributes: link-offload-xstats
+      -
+        name: af-spec
+        type: binary
+  -
+    name: link-offload-xstats
+    attributes:
+      -
+        name: cpu-hit
+        type: binary
+      -
+        name: hw-s-info
+        type: array-nest
+        nested-attributes: hw-s-info-one
+      -
+        name: l3-stats
+        type: binary
+  -
+    name: hw-s-info-one
+    attributes:
+      -
+        name: request
+        type: u8
+      -
+        name: used
+        type: u8
+
+
+operations:
+  enum-model: directional
+  list:
+    -
+      name: newlink
+      doc: Create a new link.
+      attribute-set: link-attrs
+      fixed-header: ifinfomsg
+      do:
+        request:
+          value: 16
+          attributes:
+            - ifi-index
+    -
+      name: dellink
+      doc: Delete an existing link.
+      attribute-set: link-attrs
+      fixed-header: ifinfomsg
+      do:
+        request:
+          value: 16
+          attributes:
+            - ifi-index
+    -
+      name: getlink
+      doc: Get / dump information about a link.
+      attribute-set: link-attrs
+      fixed-header: ifinfomsg
+      do:
+        request:
+          value: 18
+          attributes:
+            - ifi-index
+        reply:
+          value: 16
+          attributes:
+            - ifi-index
+    -
+      name: setlink
+      doc: Set information about a link.
+      value: 19
+      attribute-set: link-attrs
+      fixed-header: ifinfomsg
+      do:
+        request:
+          attributes:
+            - ifname
+    -
+      name: getstats
+      doc: Get / dump link stats.
+      attribute-set: stats-attrs
+      fixed-header: if_stats_msg
+      dump:
+        request:
+          value: 94
+          attributes:
+            - ifindex
+        reply:
+          value: 92
+
+
+mcast-groups:
+  list:
+    -
+      name: rtnlgrp-link
+      value: 1
Signature · 1 line
2.41.0
author maintainer
#28 lore raw

PATCH v2 10/10 doc/netlink: Add spec for rt route messages

In reply to Donald Hunter

Add schema for rt route with support for getroute.

---
 Documentation/netlink/specs/rt_route.yaml | 288 ++++++++++++++++++++++
 1 file changed, 288 insertions(+)
 create mode 100644 Documentation/netlink/specs/rt_route.yaml
Documentation/netlink/specs/rt_route.yaml new file +288 -0
new file mode 100644
index 000000000000..eb4f6bb80100
@@ -0,0 +1,288 @@
+# SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)
+
+name: rt-route
+protocol: netlink-raw
+protonum: 0
+
+doc:
+  Route configuration over rtnetlink.
+
+definitions:
+  -
+    name: rtm-type
+    name-prefix: rtn-
+    type: enum
+    entries:
+      - unspec
+      - unicast
+      - local
+      - broadcast
+      - anycast
+      - multicast
+      - blackhole
+      - unreachable
+      - prohibit
+      - throw
+      - nat
+      - xresolve
+  -
+    name: rtmsg
+    type: struct
+    members:
+      -
+        name: rtm-family
+        type: u8
+      -
+        name: rtm-dst-len
+        type: u8
+      -
+        name: rtm-src-len
+        type: u8
+      -
+        name: rtm-tos
+        type: u8
+      -
+        name: rtm-table
+        type: u8
+      -
+        name: rtm-protocol
+        type: u8
+      -
+        name: rtm-scope
+        type: u8
+      -
+        name: rtm-type
+        type: u8
+        enum: rtm-type
+      -
+        name: rtm-flags
+        type: u32
+  -
+    name: rta-cacheinfo
+    type: struct
+    members:
+      -
+        name: rta-clntref
+        type: u32
+      -
+        name: rta-lastuse
+        type: u32
+      -
+        name: rta-expires
+        type: u32
+      -
+        name: rta-error
+        type: u32
+      -
+        name: rta-used
+        type: u32
+
+attribute-sets:
+  -
+    name: route-attrs
+    attributes:
+      -
+        name: rta-dst
+        type: binary
+        display-hint: ipv4
+      -
+        name: rta-src
+        type: binary
+        display-hint: ipv4
+      -
+        name: rta-iif
+        type: u32
+      -
+        name: rta-oif
+        type: u32
+      -
+        name: rta-gateway
+        type: binary
+        display-hint: ipv4
+      -
+        name: rta-priority
+        type: u32
+      -
+        name: rta-prefsrc
+        type: binary
+        display-hint: ipv4
+      -
+        name: rta-metrics
+        type: nest
+        nested-attributes: rta-metrics
+      -
+        name: rta-multipath
+        type: binary
+      -
+        name: rta-protoinfo # not used
+        type: binary
+      -
+        name: rta-flow
+        type: u32
+      -
+        name: rta-cacheinfo
+        type: binary
+        struct: rta-cacheinfo
+      -
+        name: rta-session # not used
+        type: binary
+      -
+        name: rta-mp-algo # not used
+        type: binary
+      -
+        name: rta-table
+        type: u32
+      -
+        name: rta-mark
+        type: u32
+      -
+        name: rta-mfc-stats
+        type: binary
+      -
+        name: rta-via
+        type: binary
+      -
+        name: rta-newdst
+        type: binary
+      -
+        name: rta-pref
+        type: u8
+      -
+        name: rta-encap-type
+        type: u16
+      -
+        name: rta-encap
+        type: binary # tunnel specific nest
+      -
+        name: rta-expires
+        type: u32
+      -
+        name: rta-pad
+        type: binary
+      -
+        name: rta-uid
+        type: u32
+      -
+        name: rta-ttl-propagate
+        type: u8
+      -
+        name: rta-ip-proto
+        type: u8
+      -
+        name: rta-sport
+        type: u16
+      -
+        name: rta-dport
+        type: u16
+      -
+        name: rta-nh-id
+        type: u32
+  -
+    name: rta-metrics
+    attributes:
+      -
+        name: rtax-unspec
+        type: unused
+        value: 0
+      -
+        name: rtax-lock
+        type: u32
+      -
+        name: rtax-mtu
+        type: u32
+      -
+        name: rtax-window
+        type: u32
+      -
+        name: rtax-rtt
+        type: u32
+      -
+        name: rtax-rttvar
+        type: u32
+      -
+        name: rtax-ssthresh
+        type: u32
+      -
+        name: rtax-cwnd
+        type: u32
+      -
+        name: rtax-advmss
+        type: u32
+      -
+        name: rtax-reordering
+        type: u32
+      -
+        name: rtax-hoplimit
+        type: u32
+      -
+        name: rtax-initcwnd
+        type: u32
+      -
+        name: rtax-features
+        type: u32
+      -
+        name: rtax-rto-min
+        type: u32
+      -
+        name: rtax-initrwnd
+        type: u32
+      -
+        name: rtax-quickack
+        type: u32
+      -
+        name: rtax-cc-algo
+        type: string
+      -
+        name: rtax-fastopen-no-cookie
+        type: u32
+
+operations:
+  enum-model: directional
+  list:
+    -
+      name: getroute
+      doc: Dump route information.
+      attribute-set: route-attrs
+      fixed-header: rtmsg
+      dump:
+        request:
+          value: 26
+        reply:
+          value: 24
+          attributes:
+            - rtm-family
+            - rtm-dst-len
+            - rtm-src-len
+            - rtm-tos
+            - rtm-table
+            - rtm-protocol
+            - rtm-scope
+            - rtm-type
+            - rtm-flags
+            - rta-dst
+            - rta-src
+            - rta-iif
+            - rta-oif
+            - rta-gateway
+            - rta-priority
+            - rta-prefsrc
+            - rta-metrics
+            - rta-multipath
+            - rta-flow
+            - rta-cacheinfo
+            - rta-table
+            - rta-mark
+            - rta-mfc-stats
+            - rta-via
+            - rta-newdst
+            - rta-pref
+            - rta-encap-type
+            - rta-encap
+            - rta-expires
+            - rta-pad
+            - rta-uid
+            - rta-ttl-propagate
+            - rta-ip-proto
+            - rta-sport
+            - rta-dport
+            - rta-nh-id
Signature · 1 line
2.41.0
maintainer
#5 lore raw

Re: [PATCH net-next v2 02/10] doc/netlink: Document the genetlink-legacy schema extensions

In reply to Donald Hunter
Quoted 7 lines · On Tue, 15 Aug 2023 20:42:46 +0100 Donald Hunter wrote:

Add description of genetlink-legacy specific attributes to the ynl spec documentation.

---
 Documentation/userspace-api/netlink/specs.rst | 47 +++++++++++++++++++
 1 file changed, 47 insertions(+)

Should we merge this with genetlink-legacy.rst?

Quoted 10 lines
Documentation/userspace-api/netlink/specs.rst +2 -0
index 2e4acde890b7..dde70f9674d4 100644
@@ -443,3 +443,50 @@ nest
 
 Attribute containing other (nested) attributes.
 ``nested-attributes`` specifies which attribute set is used inside.
+
+genetlink-legacy

Documentation/userspace-api/netlink/specs.rst nest · line 457

Quoted 10 lines
Documentation/userspace-api/netlink/specs.rst +10 -0
+================
+
+The genetlink-legacy schema extends the genetlink schema with some additional
+properties that are needed to support legacy genetlink families.
+
+Globals
+-------
+
+ - ``kernel-policy`` - Specify whether the kernel input policy is ``global``,
+   ``per-op`` or ``split``.

Maybe a few more words:

Specify whether the kernel input policy is ``global`` i.e. the same for all operation of the family, defined for each operation individually (``per-op``), or separately for each operation and operation type (do vs dump) - ``split``.

Quoted 7 lines
Documentation/userspace-api/netlink/specs.rst +6 -0
+   ``per-op`` or ``split``.
 
+Struct definitions
+------------------
+
+There is a new type of definition called ``struct`` which is used for declaring
+the C struct format of fixed headers and binary attributes.

Documentation/userspace-api/netlink/specs.rst nest · line 473

Quoted 10 lines
Documentation/userspace-api/netlink/specs.rst +10 -0
+
+members
+~~~~~~~
+
+ - ``name`` - The attribute name of the struct member
+ - ``type`` - One of the scalar types ``u8``, ``u16``, ``u32``, ``u64``, ``s8``,
+   ``s16``, ``s32``, ``s64``, ``string`` or ``binary``.
+ - ``byte-order`` - ``big-endian`` or ``little-endian``
+ - ``doc``, ``enum``, ``enum-as-flags``, ``display-hint`` - Same as for
+   attribute definitions.

Hm, genetlink-legacy.rst has this:

https://docs.kernel.org/next/userspace-api/netlink/genetlink-legacy.html#structures

But the larger section is called "Other quirks (todo)" I guess you have tackled most of the items in this section so we shouldn't call it "todo" ?

maintainer
#10 lore raw

Re: [PATCH net-next v2 03/10] doc/netlink: Document the netlink-raw schema extensions

In reply to Donald Hunter
Quoted 2 lines · On Tue, 15 Aug 2023 20:42:47 +0100 Donald Hunter wrote:

Add description of netlink-raw specific attributes to the ynl spec documentation and refer to the classic netlink documentation.

I wonder if we should make this a separate doc, similarly to genetlink-legacy. Keep the specs.rst focused on newer stuff?

reviewer
#2 lore raw

Re: [PATCH net-next v2 01/10] doc/netlink: Add a schema for netlink-raw families

In reply to Donald Hunter
Quoted 62 lines · Donald Hunter

This schema is largely a copy of the genetlink-legacy schema with the following additions:

- a top-level protonum property, e.g. 0 (for NETLINK_ROUTE)
- add netlink-raw to the list of protocols supported by the schema
- add a value property to mcast-group definitions

This schema is very similar to genetlink-legacy and I considered making the changes there and symlinking to it. On balance I felt that might be problematic for accurate schema validation.

---
 Documentation/netlink/netlink-raw.yaml | 414 +++++++++++++++++++++++++
 1 file changed, 414 insertions(+)
 create mode 100644 Documentation/netlink/netlink-raw.yaml
Documentation/netlink/netlink-raw.yaml new file +39 -0
new file mode 100644
index 000000000000..a5ec6f3e41cc
@@ -0,0 +1,414 @@
+# SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)
+%YAML 1.2
+---
+$id: http://kernel.org/schemas/netlink/genetlink-legacy.yaml#
+$schema: https://json-schema.org/draft-07/schema
+
+# Common defines
+$defs:
+  uint:
+    type: integer
+    minimum: 0
+  len-or-define:
+    type: [ string, integer ]
+    pattern: ^[0-9A-Za-z_]+( - 1)?$
+    minimum: 0
+
+# Schema for specs
+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
+    minimum: 1
+  protocol:
+    description: Schema compatibility level. Default is "genetlink".
+    enum: [ genetlink, genetlink-c, genetlink-legacy, netlink-raw ] # Trim
+  # Start netlink-raw
+  protonum:
+    description: Protocol number to use for netlink-raw
+    type: integer

Documentation/netlink/netlink-raw.yaml line 49

Quoted 10 lines
Documentation/netlink/netlink-raw.yaml new file +10 -0
+  # End netlink-raw
+  uapi-header:
+    description: Path to the uAPI header, default is linux/${family-name}.h
+    type: string
+  # Start genetlink-c
+  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.

Hi Donald,

a minor nit from my side: verion -> version

Quoted 1 line
Documentation/netlink/netlink-raw.yaml new file +1 -0
+    type: string

...

author maintainer
#6 lore raw

Re: [PATCH net-next v2 02/10] doc/netlink: Document the genetlink-legacy schema extensions

In reply to Jakub Kicinski
Quoted 10 lines · Jakub Kicinski
Quoted 7 lines · On Tue, 15 Aug 2023 20:42:46 +0100 Donald Hunter wrote:

Add description of genetlink-legacy specific attributes to the ynl spec documentation.

---
 Documentation/userspace-api/netlink/specs.rst | 47 +++++++++++++++++++
 1 file changed, 47 insertions(+)

Should we merge this with genetlink-legacy.rst?

Sure, I can do that.

Quoted 24 lines
Quoted 11 lines
Documentation/userspace-api/netlink/specs.rst +2 -0
index 2e4acde890b7..dde70f9674d4 100644
@@ -443,3 +443,50 @@ nest
 
 Attribute containing other (nested) attributes.
 ``nested-attributes`` specifies which attribute set is used inside.
+
+genetlink-legacy

Documentation/userspace-api/netlink/specs.rst nest · line 457

Quoted 10 lines
Documentation/userspace-api/netlink/specs.rst +10 -0
+================
+
+The genetlink-legacy schema extends the genetlink schema with some additional
+properties that are needed to support legacy genetlink families.
+
+Globals
+-------
+
+ - ``kernel-policy`` - Specify whether the kernel input policy is ``global``,
+   ``per-op`` or ``split``.

Maybe a few more words:

Quoted 4 lines

Specify whether the kernel input policy is ``global`` i.e. the same for all operation of the family, defined for each operation individually (``per-op``), or separately for each operation and operation type (do vs dump) - ``split``.

Ack. As an aside, what do we mean by "kernel input policy"?

Quoted 20 lines
Quoted 7 lines
Documentation/userspace-api/netlink/specs.rst +6 -0
+   ``per-op`` or ``split``.
 
+Struct definitions
+------------------
+
+There is a new type of definition called ``struct`` which is used for declaring
+the C struct format of fixed headers and binary attributes.

Documentation/userspace-api/netlink/specs.rst nest · line 473

Quoted 10 lines
Documentation/userspace-api/netlink/specs.rst +10 -0
+
+members
+~~~~~~~
+
+ - ``name`` - The attribute name of the struct member
+ - ``type`` - One of the scalar types ``u8``, ``u16``, ``u32``, ``u64``, ``s8``,
+   ``s16``, ``s32``, ``s64``, ``string`` or ``binary``.
+ - ``byte-order`` - ``big-endian`` or ``little-endian``
+ - ``doc``, ``enum``, ``enum-as-flags``, ``display-hint`` - Same as for
+   attribute definitions.

Hm, genetlink-legacy.rst has this:

Quoted 5 lines

https://docs.kernel.org/next/userspace-api/netlink/genetlink-legacy.html#structures

But the larger section is called "Other quirks (todo)" I guess you have tackled most of the items in this section so we shouldn't call it "todo" ?

I'll clean up genetlink-legacy.rst when I merge these changes.

Thanks for the review!

author maintainer
#11 lore raw

Re: [PATCH net-next v2 03/10] doc/netlink: Document the netlink-raw schema extensions

In reply to Jakub Kicinski
Quoted 6 lines · Jakub Kicinski
Quoted 2 lines · On Tue, 15 Aug 2023 20:42:47 +0100 Donald Hunter wrote:

Add description of netlink-raw specific attributes to the ynl spec documentation and refer to the classic netlink documentation.

I wonder if we should make this a separate doc, similarly to genetlink-legacy. Keep the specs.rst focused on newer stuff?

Sure. I could also include examples, like genetlink-legacy does.

Thanks!

author maintainer
#7 lore raw

Re: [PATCH net-next v2 02/10] doc/netlink: Document the genetlink-legacy schema extensions

In reply to Donald Hunter
Quoted 12 lines · Donald Hunter
Quoted 10 lines · Jakub Kicinski

Documentation/userspace-api/netlink/specs.rst nest · line 457

Quoted 6 lines · On Tue, 15 Aug 2023 20:42:46 +0100 Donald Hunter wrote:
Documentation/userspace-api/netlink/specs.rst +6 -0
+
+Globals
+-------
+
+ - ``kernel-policy`` - Specify whether the kernel input policy is ``global``,
+   ``per-op`` or ``split``.

Maybe a few more words:

Quoted 6 lines
Quoted 4 lines

Specify whether the kernel input policy is ``global`` i.e. the same for all operation of the family, defined for each operation individually (``per-op``), or separately for each operation and operation type (do vs dump) - ``split``.

Ack. As an aside, what do we mean by "kernel input policy"?

So I've just spotted that kernel-policy is already documented in core-api/netlink.rst and I guess I shouldn't be documenting it in the userspace-api at all? I could add a reference to the core-api docs so that it's easier to find the kernel side docs when reading the userspace-api?

author maintainer
#3 lore raw

Re: [PATCH net-next v2 01/10] doc/netlink: Add a schema for netlink-raw families

In reply to Simon Horman
Quoted 10 lines · Simon Horman

Documentation/netlink/netlink-raw.yaml line 49

Quoted 5 lines · Donald Hunter
Documentation/netlink/netlink-raw.yaml new file +5 -0
+  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.

Hi Donald,

a minor nit from my side: verion -> version

Good catch. This typo was copied over from genetlink-legacy.yaml so I'll fix it there and in genetlink-c.yaml as well.

Thanks!

maintainer
#8 lore raw

Re: [PATCH net-next v2 02/10] doc/netlink: Document the genetlink-legacy schema extensions

In reply to Donald Hunter
Quoted 7 lines · On Wed, 16 Aug 2023 14:16:33 +0100 Donald Hunter wrote:
Quoted 1 line

Ack. As an aside, what do we mean by "kernel input policy"?

So I've just spotted that kernel-policy is already documented in core-api/netlink.rst and I guess I shouldn't be documenting it in the userspace-api at all? I could add a reference to the core-api docs so that it's easier to find the kernel side docs when reading the userspace-api?

Ah, yes, reference sounds good.
But we should also add split to the doc, I only see ``global`` and ``per-op`` described?

maintainer
#13 lore raw

Re: [PATCH net-next v2 04/10] tools/ynl: Add mcast-group schema parsing to ynl

In reply to Donald Hunter

tools/net/ynl/lib/nlspec.py class SpecOperation(SpecElement): · line 328

Quoted 4 lines · On Tue, 15 Aug 2023 20:42:48 +0100 Donald Hunter wrote:
tools/net/ynl/lib/nlspec.py +4 -0
+class SpecMcastGroup(SpecElement):
+    """Netlink Multicast Group
+
+    Information about a multicast group.

I'd add more info about value here. Say something along the lines of value is specified in the spec only for classic netlink (netlink-raw) families, genetlink families use dynamic ID allocation so the ids of multicast groups need to be resolved at runtime. value will be None for genetlink families.

Quoted 9 lines
tools/net/ynl/lib/nlspec.py +9 -0
+
+    Attributes:
+        name      name of the mulitcast group
+        value     numerical id of this multicast group for netlink-raw
+        yaml      raw spec as loaded from the spec file
+    """
+    def __init__(self, family, yaml):
+        super().__init__(family, yaml)
+        self.value = self.yaml.get('value')
maintainer
#15 lore raw

Re: [PATCH net-next v2 05/10] tools/net/ynl: Refactor decode_fixed_header into NlMsg

In reply to Donald Hunter

tools/net/ynl/lib/ynl.py def _genl_load_families(): · line 336

Quoted 3 lines · On Tue, 15 Aug 2023 20:42:49 +0100 Donald Hunter wrote:
tools/net/ynl/lib/ynl.py +3 -0
+    def __init__(self, nl_msg, ynl=None):
+        self.genl_cmd, self.genl_version, _ = struct.unpack_from("BBH", nl_msg.raw, 0)
+        nl_msg.raw = nl_msg.raw[4:]

It's a bit of a layering violation that we are futzing with the raw member of NlMsg inside GenlMsg, no?

Should we add "fixed hdrs len" argument to NlMsg? Either directly or pass ynl and let get the expected len from ynl? That way NlMsg can split itself into hdr, userhdrs and attrs without GenlMsg "fixing it up"?

Quoted 18 lines
tools/net/ynl/lib/ynl.py +5 -12
-        self.hdr = nl_msg.raw[0:4]
-        offset = 4
-
-        self.genl_cmd, self.genl_version, _ = struct.unpack("BBH", self.hdr)
-
-        self.fixed_header_attrs = dict()
-        for m in fixed_header_members:
-            format = NlAttr.get_format(m.type, m.byte_order)
-            decoded = format.unpack_from(nl_msg.raw, offset)
-            offset += format.size
-            self.fixed_header_attrs[m.name] = decoded[0]
+        if ynl:
+            op = ynl.rsp_by_value[self.genl_cmd]
+            if op.fixed_header:
+                nl_msg.decode_fixed_header(ynl, op.fixed_header)
 
-        self.raw = nl_msg.raw[offset:]
+        self.raw = nl_msg.raw
maintainer
#20 lore raw
In reply to Donald Hunter
Quoted 2 lines · On Tue, 15 Aug 2023 20:42:50 +0100 Donald Hunter wrote:

Refactor the ynl code to encapsulate protocol specifics into NetlinkProtocol and GenlProtocol.

Looks good, but do we also need some extra plumbing to decode extack for classic netlink correctly? Basically shouldn't _decode_extack() also move to proto? Or we can parameterize it? All we really need there is to teach it how much of fixed headers parser needs to skip to get to attributes, really (which, BTW is already kinda buggy for genl families with fixed headers).

author maintainer
#21 lore raw
In reply to Jakub Kicinski
Quoted 10 lines · Jakub Kicinski
Quoted 2 lines · On Tue, 15 Aug 2023 20:42:50 +0100 Donald Hunter wrote:

Refactor the ynl code to encapsulate protocol specifics into NetlinkProtocol and GenlProtocol.

Looks good, but do we also need some extra plumbing to decode extack for classic netlink correctly? Basically shouldn't _decode_extack() also move to proto? Or we can parameterize it? All we really need there is to teach it how much of fixed headers parser needs to skip to get to attributes, really (which, BTW is already kinda buggy for genl families with fixed headers).

I have been working on the assumption that extack responses don't include any fixed headers. I have seen extack messages decoded correctly for classic netlink, here with RTM_NEWROUTE:

lib.ynl.NlError: Netlink error: Invalid argument
nl_len = 80 (64) nl_flags = 0x300 nl_type = 2
error: -22 extack: {'msg': 'Invalid prefix for given prefix length'}

Is there something I am missing?

#16 lore raw

Re: [PATCH net-next v2 05/10] tools/net/ynl: Refactor decode_fixed_header into NlMsg

In reply to Jakub Kicinski
Quoted 6 lines · Jakub Kicinski

tools/net/ynl/lib/ynl.py def _genl_load_families(): · line 336

Quoted 3 lines · On Tue, 15 Aug 2023 20:42:49 +0100 Donald Hunter wrote:
tools/net/ynl/lib/ynl.py +3 -0
+    def __init__(self, nl_msg, ynl=None):
+        self.genl_cmd, self.genl_version, _ = struct.unpack_from("BBH", nl_msg.raw, 0)
+        nl_msg.raw = nl_msg.raw[4:]
Quoted 7 lines

It's a bit of a layering violation that we are futzing with the raw member of NlMsg inside GenlMsg, no?

Should we add "fixed hdrs len" argument to NlMsg? Either directly or pass ynl and let get the expected len from ynl? That way NlMsg can split itself into hdr, userhdrs and attrs without GenlMsg "fixing it up"?

I agree, it breaks the layering. The issue is that GenlMsg gets created at some point after NlMsg, only when we know the nl_msg is suitable for decoding. The fixed header bit is quite well encapsulated in NlMsg, it's the genl header that needs pulled out and NlMsg shouldn't know anything about it. How about I add a take_bytes(length) method or a generic decode_subheader(format, length) method to NlMsg?

maintainer
#22 lore raw
In reply to Donald Hunter
Quoted 11 lines · On Thu, 17 Aug 2023 10:10:35 +0100 Donald Hunter wrote:
Quoted 6 lines

Looks good, but do we also need some extra plumbing to decode extack for classic netlink correctly? Basically shouldn't _decode_extack() also move to proto? Or we can parameterize it? All we really need there is to teach it how much of fixed headers parser needs to skip to get to attributes, really (which, BTW is already kinda buggy for genl families with fixed headers).

I have been working on the assumption that extack responses don't include any fixed headers. I have seen extack messages decoded correctly for classic netlink, here with RTM_NEWROUTE:

Quoted 5 lines

lib.ynl.NlError: Netlink error: Invalid argument
nl_len = 80 (64) nl_flags = 0x300 nl_type = 2
error: -22 extack: {'msg': 'Invalid prefix for given prefix length'}

Is there something I am missing?

I'm thinking of extack messages carrying offsets in addition to the textual error message. NLMSGERR_ATTR_OFFS or NLMSGERR_ATTR_MISS_NEST.

In that case ynl will try to re-parse its own message via _decode_extack_path() to resolve from the offset to what attribute was there. See the commit message on a552bfa16:

    lib.ynl.NlError: Netlink error: Numerical result out of range
    nl_len = 108 (92) nl_flags = 0x300 nl_type = 2
            error: -34      extack: {'msg': 'integer out of range',...
                                     'bad-attr': '.ifindex'}

I mean the "bad-attr" thing.

I think it works out of sheer luck here, we happen to skip over the fixed header because it looks like a 0-length attribute?

maintainer
#17 lore raw

Re: [PATCH net-next v2 05/10] tools/net/ynl: Refactor decode_fixed_header into NlMsg

In reply to Donald Hunter
Quoted 8 lines · On Thu, 17 Aug 2023 16:14:35 +0100 Donald Hunter wrote:
Quoted 7 lines

It's a bit of a layering violation that we are futzing with the raw member of NlMsg inside GenlMsg, no?

Should we add "fixed hdrs len" argument to NlMsg? Either directly or pass ynl and let get the expected len from ynl? That way NlMsg can split itself into hdr, userhdrs and attrs without GenlMsg "fixing it up"?

Quoted 6 lines

I agree, it breaks the layering. The issue is that GenlMsg gets created at some point after NlMsg, only when we know the nl_msg is suitable for decoding. The fixed header bit is quite well encapsulated in NlMsg, it's the genl header that needs pulled out and NlMsg shouldn't know anything about it. How about I add a take_bytes(length) method or a generic decode_subheader(format, length) method to NlMsg?

Why do we need to fix up the .raw of NlMsg underlying the GenlMsg in the first place? GenlMsg by itself didn't need to do that until now.

Another option to consider which would make things more symmetric between raw and genetlink would be to add a wrapper class for old families, too. ClassicMsg? CnlMsg? That way we could retain the separation of NlMsg is just a raw message which could be a NLM_DONE or some other control thing, and higher level class being used to pull fixed headers and separate out attrs. Just a thought, not sure it helps.

#18 lore raw

Re: [PATCH net-next v2 05/10] tools/net/ynl: Refactor decode_fixed_header into NlMsg

Quoted 17 lines · Jakub Kicinski
Quoted 8 lines · On Thu, 17 Aug 2023 16:14:35 +0100 Donald Hunter wrote:
Quoted 7 lines

It's a bit of a layering violation that we are futzing with the raw member of NlMsg inside GenlMsg, no?

Should we add "fixed hdrs len" argument to NlMsg? Either directly or pass ynl and let get the expected len from ynl? That way NlMsg can split itself into hdr, userhdrs and attrs without GenlMsg "fixing it up"?

Quoted 6 lines

I agree, it breaks the layering. The issue is that GenlMsg gets created at some point after NlMsg, only when we know the nl_msg is suitable for decoding. The fixed header bit is quite well encapsulated in NlMsg, it's the genl header that needs pulled out and NlMsg shouldn't know anything about it. How about I add a take_bytes(length) method or a generic decode_subheader(format, length) method to NlMsg?

Quoted 2 lines

Why do we need to fix up the .raw of NlMsg underlying the GenlMsg in the first place? GenlMsg by itself didn't need to do that until now.

Fair point. I will refactor to leave nl_msg.raw untouched.

Quoted 6 lines

Another option to consider which would make things more symmetric between raw and genetlink would be to add a wrapper class for old families, too. ClassicMsg? CnlMsg? That way we could retain the separation of NlMsg is just a raw message which could be a NLM_DONE or some other control thing, and higher level class being used to pull fixed headers and separate out attrs. Just a thought, not sure it helps.

I _think_ I can avoid doing this. There's an asymmetry to the way the NlAttrs get created that I need to fix. When I do that, the rest should be a bit cleaner.

author maintainer
#23 lore raw
In reply to Jakub Kicinski
Quoted 30 lines · Jakub Kicinski
Quoted 11 lines · On Thu, 17 Aug 2023 10:10:35 +0100 Donald Hunter wrote:
Quoted 6 lines

Looks good, but do we also need some extra plumbing to decode extack for classic netlink correctly? Basically shouldn't _decode_extack() also move to proto? Or we can parameterize it? All we really need there is to teach it how much of fixed headers parser needs to skip to get to attributes, really (which, BTW is already kinda buggy for genl families with fixed headers).

I have been working on the assumption that extack responses don't include any fixed headers. I have seen extack messages decoded correctly for classic netlink, here with RTM_NEWROUTE:

Quoted 5 lines

lib.ynl.NlError: Netlink error: Invalid argument
nl_len = 80 (64) nl_flags = 0x300 nl_type = 2
error: -22 extack: {'msg': 'Invalid prefix for given prefix length'}

Is there something I am missing?

I'm thinking of extack messages carrying offsets in addition to the textual error message. NLMSGERR_ATTR_OFFS or NLMSGERR_ATTR_MISS_NEST.

In that case ynl will try to re-parse its own message via _decode_extack_path() to resolve from the offset to what attribute was there. See the commit message on a552bfa16:

    lib.ynl.NlError: Netlink error: Numerical result out of range
    nl_len = 108 (92) nl_flags = 0x300 nl_type = 2
            error: -34      extack: {'msg': 'integer out of range',...
                                     'bad-attr': '.ifindex'}
Quoted 4 lines

I mean the "bad-attr" thing.

I think it works out of sheer luck here, we happen to skip over the fixed header because it looks like a 0-length attribute?

You're right, sheer luck, and maybe only for some values of dp-ifindex. When I tried to reproduce your test in commit a552bfa16, with a value of dp-ifindex = 5, then ynl goes into an infinite loop trying to read a zero length nlattr.

As you say, I'll need to rework the extack handling to account for fixed headers. At a minimum _decode_extack will need to use nlproto.decode() and needs to learn to skip the fixed header.

Apologies for being slow to catch up with you on this. Failing to grok that _decode_extack is decoding the request, not the response.