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

Documentation/netlink/genetlink-legacy.yaml

+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

Documentation/netlink/specs/ovs_datapath.yaml

0 → 100644
+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

Documentation/netlink/specs/ovs_vport.yaml

0 → 100644
+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

Documentation/userspace-api/netlink/genetlink-legacy.rst

+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

----------------

Documentation/userspace-api/netlink/specs.rst

+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

----------