Commit 35fae44e authored by Jakub Kicinski's avatar Jakub Kicinski
Browse files

Merge branch 'ynl-add-support-for-user-headers-and-struct-attrs'

Donald Hunter says:

====================
ynl: add support for user headers and struct attrs

Add support for user headers and struct attrs to YNL. This patchset adds
features to ynl and add a partial spec for openvswitch that demonstrates
use of the features.

Patch 1-4 add features to ynl
Patch 5 adds partial openvswitch specs that demonstrate the new features
Patch 6-7 add documentation for legacy structs and for sub-type
====================

Link: https://lore.kernel.org/r/20230327083138.96044-1-donald.hunter@gmail.com


Signed-off-by: default avatarJakub Kicinski <kuba@kernel.org>
parents de749452 04eac393
Loading
Loading
Loading
Loading
+16 −0
Original line number Diff line number Diff line
@@ -218,6 +218,11 @@ properties:
                    description: Max length for a string or a binary attribute.
                    $ref: '#/$defs/len-or-define'
              sub-type: *attr-type
              # 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:
@@ -256,6 +261,14 @@ properties:
      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
@@ -288,6 +301,9 @@ properties:
              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
+153 −0
Original line number Diff line number Diff line
# SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)

name: ovs_datapath
version: 2
protocol: genetlink-legacy

doc:
  OVS datapath configuration over generic netlink.

definitions:
  -
    name: ovs-header
    type: struct
    members:
      -
        name: dp-ifindex
        type: u32
  -
    name: user-features
    type: flags
    entries:
      -
        name: unaligned
        doc: Allow last Netlink attribute to be unaligned
      -
        name: vport-pids
        doc: Allow datapath to associate multiple Netlink PIDs to each vport
      -
        name: tc-recirc-sharing
        doc: Allow tc offload recirc sharing
      -
        name: dispatch-upcall-per-cpu
        doc: Allow per-cpu dispatch of upcalls
  -
    name: datapath-stats
    type: struct
    members:
      -
        name: hit
        type: u64
      -
        name: missed
        type: u64
      -
        name: lost
        type: u64
      -
        name: flows
        type: u64
  -
    name: megaflow-stats
    type: struct
    members:
      -
        name: mask-hit
        type: u64
      -
        name: masks
        type: u32
      -
        name: padding
        type: u32
      -
        name: cache-hits
        type: u64
      -
        name: pad1
        type: u64

attribute-sets:
  -
    name: datapath
    attributes:
      -
        name: name
        type: string
      -
        name: upcall-pid
        doc: upcall pid
        type: u32
      -
        name: stats
        type: binary
        struct: datapath-stats
      -
        name: megaflow-stats
        type: binary
        struct: megaflow-stats
      -
        name: user-features
        type: u32
        enum: user-features
        enum-as-flags: true
      -
        name: pad
        type: unused
      -
        name: masks-cache-size
        type: u32
      -
        name: per-cpu-pids
        type: binary
        sub-type: u32

operations:
  fixed-header: ovs-header
  list:
    -
      name: dp-get
      doc: Get / dump OVS data path configuration and state
      value: 3
      attribute-set: datapath
      do: &dp-get-op
        request:
          attributes:
            - name
        reply:
          attributes:
            - name
            - upcall-pid
            - stats
            - megaflow-stats
            - user-features
            - masks-cache-size
            - per-cpu-pids
      dump: *dp-get-op
    -
      name: dp-new
      doc: Create new OVS data path
      value: 1
      attribute-set: datapath
      do:
        request:
          attributes:
            - dp-ifindex
            - name
            - upcall-pid
            - user-features
    -
      name: dp-del
      doc: Delete existing OVS data path
      value: 2
      attribute-set: datapath
      do:
        request:
          attributes:
            - dp-ifindex
            - name

mcast-groups:
  list:
    -
      name: ovs_datapath
+139 −0
Original line number Diff line number Diff line
# SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)

name: ovs_vport
version: 2
protocol: genetlink-legacy

doc:
  OVS vport configuration over generic netlink.

definitions:
  -
    name: ovs-header
    type: struct
    members:
      -
        name: dp-ifindex
        type: u32
  -
    name: vport-type
    type: enum
    entries: [ unspec, netdev, internal, gre, vxlan, geneve ]
  -
    name: vport-stats
    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

attribute-sets:
  -
    name: vport-options
    attributes:
      -
        name: dst-port
        type: u32
      -
        name: extension
        type: u32
  -
    name: upcall-stats
    attributes:
      -
        name: success
        type: u64
        value: 0
      -
        name: fail
        type: u64
  -
    name: vport
    attributes:
      -
        name: port-no
        type: u32
      -
        name: type
        type: u32
        enum: vport-type
      -
        name: name
        type: string
      -
        name: options
        type: nest
        nested-attributes: vport-options
      -
        name: upcall-pid
        type: binary
        sub-type: u32
      -
        name: stats
        type: binary
        struct: vport-stats
      -
        name: pad
        type: unused
      -
        name: ifindex
        type: u32
      -
        name: netnsid
        type: u32
      -
        name: upcall-stats
        type: nest
        nested-attributes: upcall-stats

operations:
  list:
    -
      name: vport-get
      doc: Get / dump OVS vport configuration and state
      value: 3
      attribute-set: vport
      fixed-header: ovs-header
      do: &vport-get-op
        request:
          attributes:
            - dp-ifindex
            - name
        reply: &dev-all
          attributes:
            - dp-ifindex
            - port-no
            - type
            - name
            - upcall-pid
            - stats
            - ifindex
            - netnsid
            - upcall-stats
      dump: *vport-get-op

mcast-groups:
  list:
    -
      name: ovs_vport
+85 −3
Original line number Diff line number Diff line
@@ -162,9 +162,91 @@ Other quirks (todo)
Structures
----------

Legacy families can define C structures both to be used as the contents
of an attribute and as a fixed message header. The plan is to define
the structs in ``definitions`` and link the appropriate attrs.
Legacy families can define C structures both to be used as the contents of
an attribute and as a fixed message header. Structures are defined in
``definitions``  and referenced in operations or attributes. Note that
structures defined in YAML are implicitly packed according to C
conventions. For example, the following struct is 4 bytes, not 6 bytes:

.. code-block:: c

  struct {
          u8 a;
          u16 b;
          u8 c;
  }

Any padding must be explicitly added and C-like languages should infer the
need for explicit padding from whether the members are naturally aligned.

Here is the struct definition from above, declared in YAML:

.. code-block:: yaml

  definitions:
    -
      name: message-header
      type: struct
      members:
        -
          name: a
          type: u8
        -
          name: b
          type: u16
        -
          name: c
          type: u8

Fixed Headers
~~~~~~~~~~~~~

Fixed message headers can be added to operations using ``fixed-header``.
The default ``fixed-header`` can be set in ``operations`` and it can be set
or overridden for each operation.

.. code-block:: yaml

  operations:
    fixed-header: message-header
    list:
      -
        name: get
        fixed-header: custom-header
        attribute-set: message-attrs

Attributes
~~~~~~~~~~

A ``binary`` attribute can be interpreted as a C structure using a
``struct`` property with the name of the structure definition. The
``struct`` property implies ``sub-type: struct`` so it is not necessary to
specify a sub-type.

.. code-block:: yaml

  attribute-sets:
    -
      name: stats-attrs
      attributes:
        -
          name: stats
          type: binary
          struct: vport-stats

C Arrays
--------

Legacy families also use ``binary`` attributes to encapsulate C arrays. The
``sub-type`` is used to identify the type of scalar to extract.

.. code-block:: yaml

  attributes:
    -
      name: ports
      type: binary
      sub-type: u32

Multi-message DO
----------------
+10 −0
Original line number Diff line number Diff line
@@ -254,6 +254,16 @@ rather than depend on what is specified in the spec file.
The validation policy in the kernel is formed by combining the type
definition (``type`` and ``nested-attributes``) and the ``checks``.

sub-type
~~~~~~~~

Legacy families have special ways of expressing arrays. ``sub-type`` can be
used to define the type of array members in case array members are not
fully defined as attributes (in a bona fide attribute space). For instance
a C array of u32 values can be specified with ``type: binary`` and
``sub-type: u32``. Binary types and legacy array formats are described in
more detail in :doc:`genetlink-legacy`.

operations
----------

Loading