Re: [Draft PATCH net-next 1/3] Documentation: netlink: add a YAML spec for team

[Jiri Pirko <jiri@resnulli.us>]

Wed, Dec 13, 2023 at 09:45:00AM CET, liuhangbin@gmail.com wrote:
>Add a YAML specification for team.
>
>Signed-off-by: Hangbin Liu <liuhangbin@gmail.com>
>---
> Documentation/netlink/specs/team.yaml | 205 ++++++++++++++++++++++++++
> MAINTAINERS                           |   1 +
> 2 files changed, 206 insertions(+)
> create mode 100644 Documentation/netlink/specs/team.yaml
>
>diff --git a/Documentation/netlink/specs/team.yaml b/Documentation/netlink/specs/team.yaml
>new file mode 100644
>index 000000000000..5647068bf521
>--- /dev/null
>+++ b/Documentation/netlink/specs/team.yaml
>@@ -0,0 +1,205 @@
>+# SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)
>+
>+name: team
>+
>+protocol: genetlink-legacy
>+
>+doc: |
>+  Network team device driver.
>+
>+c-family-name: team-genl-name
>+c-version-name: team-genl-version
>+kernel-policy: global
>+uapi-header: linux/if_team.h
>+
>+definitions:
>+  -
>+    name: string-max-len
>+    type: const
>+    value: 32
>+  -
>+    name: genl-change-event-mc-grp-name
>+    type: const
>+    value: change_event
>+
>+attribute-sets:
>+  -
>+    name: team
>+    doc:
>+      The team nested layout of get/set msg looks like
>+          [TEAM_ATTR_LIST_OPTION]
>+              [TEAM_ATTR_ITEM_OPTION]
>+                  [TEAM_ATTR_OPTION_*], ...
>+              [TEAM_ATTR_ITEM_OPTION]
>+                  [TEAM_ATTR_OPTION_*], ...
>+              ...
>+          [TEAM_ATTR_LIST_PORT]
>+              [TEAM_ATTR_ITEM_PORT]
>+                  [TEAM_ATTR_PORT_*], ...
>+              [TEAM_ATTR_ITEM_PORT]
>+                  [TEAM_ATTR_PORT_*], ...
>+              ...
>+    name-prefix: team-attr-
>+    attributes:
>+      -
>+        name: unspec
>+        type: unused
>+        value: 0
>+      -
>+        name: team-ifindex
>+        type: u32
>+      -
>+        name: list-option
>+        type: nest
>+        nested-attributes: item-option
>+      -
>+        name: list-port
>+        type: nest
>+        nested-attributes: item-port
>+  -
>+    name: item-option
>+    name-prefix: team-attr-item-
>+    attr-cnt-name: __team-attr-item-option-max
>+    attr-max-name: team-attr-item-option-max
>+    attributes:
>+      -
>+        name: option-unspec
>+        type: unused
>+        value: 0
>+      -
>+        name: option
>+        type: nest
>+        nested-attributes: attr-option
>+  -
>+    name: attr-option
>+    name-prefix: team-attr-option-
>+    attributes:
>+      -
>+        name: unspec
>+        type: unused
>+        value: 0
>+      -
>+        name: name
>+        type: string
>+        checks:
>+          # no unterminated-ok defination?
>+          # do we have to hard code this?
>+          max-len: 32
>+      -
>+        name: changed
>+        type: flag
>+      -
>+        name: type
>+        type: u8
>+      -
>+        name: data
>+        type: binary
>+      -
>+        name: removed
>+        type: flag
>+      -
>+        name: port-ifindex
>+        type: u32
>+        doc: for per-port options
>+      -
>+        name: array-index
>+        type: u32
>+        doc: for for array options
>+  -
>+    name: item-port
>+    name-prefix: team-attr-item-
>+    attr-cnt-name: __team-attr-item-port-max
>+    attr-max-name: team-attr-item-port-max
>+    attributes:
>+      -
>+        name: port-unspec
>+        type: unused
>+        value: 0
>+      -
>+        name: port
>+        type: nest
>+        nested-attributes: attr-port
>+  -
>+    name: attr-port
>+    name-prefix: team-attr-port-
>+    attributes:
>+      -
>+        name: unspec
>+        type: unused
>+        value: 0
>+      -
>+        name: ifindex
>+        type: u32
>+      -
>+        name: changed
>+        type: flag
>+      -
>+        name: linkup
>+        type: flag
>+      -
>+        name: speed
>+        type: u32
>+      -
>+        name: duplex
>+        type: u8
>+      -
>+        name: removed
>+        type: flag
>+
>+operations:
>+  list:
>+    -
>+      name: noop
>+      doc: No operation
>+      value: 0
>+      attribute-set: team
>+      dont-validate: [ strict, dump ]

What is this good for?


>+
>+      do:
>+        # Actually it only reply the team netlink family
>+        reply:
>+          attributes:
>+            - team-ifindex
>+
>+    -
>+      name: options-set
>+      doc: Set team options
>+      attribute-set: team
>+      dont-validate: [ strict, dump ]

There is no dump op. Same below.


>+      flags: [ admin-perm ]
>+
>+      do:
>+        request:
>+          attributes:
>+            - team-ifindex
>+            - list-option
>+
>+    -
>+      name: options-get
>+      doc: Get team options info
>+      attribute-set: team
>+      dont-validate: [ strict, dump ]
>+      flags: [ admin-perm ]
>+
>+      do:
>+        request:
>+          attributes:
>+            - team-ifindex
>+        reply:
>+          attributes:
>+            - list-option
>+
>+    -
>+      name: port-list-get
>+      doc: Get team ports info
>+      attribute-set: team
>+      dont-validate: [ strict, dump ]
>+      flags: [ admin-perm ]
>+
>+      do:
>+        request:
>+          attributes:
>+            - team-ifindex
>+        reply:
>+          attributes:
>+            - list-port
>diff --git a/MAINTAINERS b/MAINTAINERS
>index 7fb66210069b..b64e449f47f9 100644
>--- a/MAINTAINERS
>+++ b/MAINTAINERS
>@@ -21301,6 +21301,7 @@ F:	drivers/net/team/
> F:	include/linux/if_team.h
> F:	include/uapi/linux/if_team.h
> F:	tools/testing/selftests/drivers/net/team/
>+F:	Documentation/netlink/specs/team.yaml
> 
> TECHNICAL ADVISORY BOARD PROCESS DOCS
> M:	"Theodore Ts'o" <tytso@mit.edu>
>-- 
>2.43.0
>