diff mbox series

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

Message ID 20231213084502.4042718-2-liuhangbin@gmail.com (mailing list archive)
State RFC
Delegated to: Netdev Maintainers
Headers show
Series add YAML spec for team | expand

Checks

Context Check Description
netdev/series_format success Posting correctly formatted
netdev/tree_selection success Clearly marked for net-next
netdev/ynl success Generated files up to date; no warnings/errors; no diff in generated;
netdev/fixes_present success Fixes tag not required for -next series
netdev/header_inline success No static functions without inline keyword in header files
netdev/build_32bit success Errors and warnings before: 8 this patch: 8
netdev/cc_maintainers warning 1 maintainers not CCed: edumazet@google.com
netdev/build_clang success Errors and warnings before: 8 this patch: 8
netdev/verify_signedoff success Signed-off-by tag matches author and committer
netdev/deprecated_api success None detected
netdev/check_selftest success No net selftest shell script
netdev/verify_fixes success No Fixes tag
netdev/build_allmodconfig_warn success Errors and warnings before: 8 this patch: 8
netdev/checkpatch warning WARNING: Misordered MAINTAINERS entry - list file patterns in alphabetic order WARNING: Possible repeated word: 'for'
netdev/build_clang_rust success No Rust files in patch. Skipping build
netdev/kdoc success Errors and warnings before: 0 this patch: 0
netdev/source_inline success Was 0 now: 0

Commit Message

Hangbin Liu Dec. 13, 2023, 8:45 a.m. UTC 
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

Comments

Jiri Pirko Dec. 13, 2023, 3:36 p.m. UTC | #1 
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
>
Jakub Kicinski Dec. 13, 2023, 4:18 p.m. UTC | #2 
On Wed, 13 Dec 2023 16:45:00 +0800 Hangbin Liu wrote:
> +    -
> +      name: noop
> +      doc: No operation
> +      value: 0
> +      attribute-set: team
> +      dont-validate: [ strict, dump ]
> +
> +      do:
> +        # Actually it only reply the team netlink family
> +        reply:
> +          attributes:
> +            - team-ifindex

Oh my. Does it actually take team-ifindex or its an op with no input
and no output?
Hangbin Liu Dec. 14, 2023, 3:44 a.m. UTC | #3 
On Wed, Dec 13, 2023 at 04:36:32PM +0100, Jiri Pirko wrote:
> >+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.
> 
Hi Jiri,

I just copied this from the current team.c code. e.g.

static const struct genl_small_ops team_nl_ops[] = {
        {
                .cmd = TEAM_CMD_NOOP,
                .validate = GENL_DONT_VALIDATE_STRICT | GENL_DONT_VALIDATE_DUMP,
                .doit = team_nl_cmd_noop,
        },
        {
                .cmd = TEAM_CMD_OPTIONS_SET,
                .validate = GENL_DONT_VALIDATE_STRICT | GENL_DONT_VALIDATE_DUMP,
                .doit = team_nl_cmd_options_set,
                .flags = GENL_ADMIN_PERM,
        },

Do you want to remove all the GENL_DONT_VALIDATE_DUMP flags from team_nl_ops?

Thanks
Hangbin
Hangbin Liu Dec. 14, 2023, 3:52 a.m. UTC | #4 
On Wed, Dec 13, 2023 at 08:18:18AM -0800, Jakub Kicinski wrote:
> On Wed, 13 Dec 2023 16:45:00 +0800 Hangbin Liu wrote:
> > +    -
> > +      name: noop
> > +      doc: No operation
> > +      value: 0
> > +      attribute-set: team
> > +      dont-validate: [ strict, dump ]
> > +
> > +      do:
> > +        # Actually it only reply the team netlink family
> > +        reply:
> > +          attributes:
> > +            - team-ifindex
> 
> Oh my. Does it actually take team-ifindex or its an op with no input
> and no output?

No, it doesn't take team-ifindex. It's an option with no input
and just reply the team_nl_family.

I added this reply attribute just to make sure the TEAM_CMD_NOOP show in the
cmd enum to not break uAPI.

Thanks
Hangbin
Jiri Pirko Dec. 14, 2023, 8:25 a.m. UTC | #5 
Thu, Dec 14, 2023 at 04:44:10AM CET, liuhangbin@gmail.com wrote:
>On Wed, Dec 13, 2023 at 04:36:32PM +0100, Jiri Pirko wrote:
>> >+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.
>> 
>Hi Jiri,
>
>I just copied this from the current team.c code. e.g.

Right, it is something which is not looked at. Remove it during the
conversion.

>
>static const struct genl_small_ops team_nl_ops[] = {
>        {
>                .cmd = TEAM_CMD_NOOP,
>                .validate = GENL_DONT_VALIDATE_STRICT | GENL_DONT_VALIDATE_DUMP,
>                .doit = team_nl_cmd_noop,
>        },
>        {
>                .cmd = TEAM_CMD_OPTIONS_SET,
>                .validate = GENL_DONT_VALIDATE_STRICT | GENL_DONT_VALIDATE_DUMP,
>                .doit = team_nl_cmd_options_set,
>                .flags = GENL_ADMIN_PERM,
>        },
>
>Do you want to remove all the GENL_DONT_VALIDATE_DUMP flags from team_nl_ops?
>
>Thanks
>Hangbin
Jakub Kicinski Dec. 14, 2023, 7:14 p.m. UTC | #6 
On Thu, 14 Dec 2023 11:52:50 +0800 Hangbin Liu wrote:
> > Oh my. Does it actually take team-ifindex or its an op with no input
> > and no output?  
> 
> No, it doesn't take team-ifindex. It's an option with no input
> and just reply the team_nl_family.
> 
> I added this reply attribute just to make sure the TEAM_CMD_NOOP show in the
> cmd enum to not break uAPI.

Another todo for the codegen, I guess.
diff mbox series

Patch

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 ]
+
+      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 ]
+      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>