Skip to contentSkip to conversation

doc/netlink: add a YAML spec for team

PATCH Applied Hangbin Liu 4 participants 11 messages Apr 1, 2024 – Apr 3, 2024

Subsystems (4)
lore
Share & tools
lore
#0 lore raw

v4 cover doc/netlink: add a YAML spec for team

Add a YAML spec for team. As we need to link two objects together to form the team module, rename team to team_core for linking.

v4:
1. fix the wrong squashe changes (Jakub Kicinski)
v3:
1. remove item/list-option from request as they are not attributes (Jakub Kicinski)
v2:
1. adjust the continuation line (Jakub Kicinski)
2. adjust the family maxattr (Jakub Kicinski)
v1:
1. remove dump from team options. (Jiri Pirko)

Hangbin Liu (4):
Documentation: netlink: add a YAML spec for team
net: team: rename team to team_core for linking
net: team: use policy generated by YAML spec
uapi: team: use header file generated from YAML spec

 Documentation/netlink/specs/team.yaml    | 204 +++++++++++++++++++++++
 MAINTAINERS                              |   1 +
 drivers/net/team/Makefile                |   1 +
 drivers/net/team/{team.c => team_core.c} |  63 +------
 drivers/net/team/team_nl.c               |  59 +++++++
 drivers/net/team/team_nl.h               |  29 ++++
 include/uapi/linux/if_team.h             | 116 +++++--------
 7 files changed, 346 insertions(+), 127 deletions(-)
 create mode 100644 Documentation/netlink/specs/team.yaml
 rename drivers/net/team/{team.c => team_core.c} (97%)
 create mode 100644 drivers/net/team/team_nl.c
 create mode 100644 drivers/net/team/team_nl.h
Signature · 1 line
2.43.0
#1 lore raw

PATCH v4 1/4 Documentation: netlink: add a YAML spec for team

Add a YAML specification for team.

---
 Documentation/netlink/specs/team.yaml | 204 ++++++++++++++++++++++++++
 MAINTAINERS                           |   1 +
 2 files changed, 205 insertions(+)
 create mode 100644 Documentation/netlink/specs/team.yaml
Documentation/netlink/specs/team.yaml new file +204 -0
new file mode 100644
index 000000000000..c13529e011c9
@@ -0,0 +1,204 @@
+# 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:
+          max-len: string-max-len
+          unterminated-ok: true
+      -
+        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 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 ]
+
+      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 ]
+      flags: [ admin-perm ]
+
+      do:
+        request: &option_attrs
+          attributes:
+            - team-ifindex
+            - list-option
+        reply: *option_attrs
+
+    -
+      name: options-get
+      doc: Get team options info
+      attribute-set: team
+      dont-validate: [ strict ]
+      flags: [ admin-perm ]
+
+      do:
+        request:
+          attributes:
+            - team-ifindex
+        reply: *option_attrs
+
+    -
+      name: port-list-get
+      doc: Get team ports info
+      attribute-set: team
+      dont-validate: [ strict ]
+      flags: [ admin-perm ]
+
+      do:
+        request:
+          attributes:
+            - team-ifindex
+        reply: &port_attrs
+          attributes:
+            - team-ifindex
+            - list-port
MAINTAINERS +1 -0
index 6a233e1a3cf2..909c2c531d8e 100644
@@ -21665,6 +21665,7 @@ TEAM DRIVER
 M:	Jiri Pirko <[email protected]>
 L:	[email protected]
 S:	Supported
+F:	Documentation/netlink/specs/team.yaml
 F:	drivers/net/team/
 F:	include/linux/if_team.h
 F:	include/uapi/linux/if_team.h
Signature · 1 line
2.43.0
maintainer Reviewed-by on v4 1/4
#2 lore raw

Re: [PATCHv4 net-next 1/4] Documentation: netlink: add a YAML spec for team

Quoted 3 lines · Mon, Apr 01, 2024 at 05:10:01AM CEST, [email protected] wrote:

Add a YAML specification for team.

Small note/question below.

[..]

Quoted 12 lines
Documentation/netlink/specs/team.yaml new file +12 -0
+    name: attr-option
+    name-prefix: team-attr-option-
+    attributes:
+      -
+        name: unspec
+        type: unused
+        value: 0
+      -
+        name: name
+        type: string
+        checks:
+          max-len: string-max-len

Documentation/netlink/specs/team.yaml line 95

Quoted 10 lines
Documentation/netlink/specs/team.yaml new file +10 -0
+          unterminated-ok: true
+      -
+        name: changed
+        type: flag
+      -
+        name: type
+        type: u8
+      -
+        name: data
+        type: binary

For the record, this is incomplete as this is not of type "binary" but rather a type determined by TEAM_ATTR_OPTION_TYPE.
My rejected patch:
https://lore.kernel.org/all/[email protected]/
Makes that possible to be implemented in ynl.

Jakub, still not willing to pull this in?

[..]

maintainer
#3 lore raw

Re: [PATCHv4 net-next 1/4] Documentation: netlink: add a YAML spec for team

Quoted 7 lines · On Tue, 2 Apr 2024 14:22:53 +0200 Jiri Pirko wrote:

For the record, this is incomplete as this is not of type "binary" but rather a type determined by TEAM_ATTR_OPTION_TYPE.
My rejected patch:
https://lore.kernel.org/all/[email protected]/
Makes that possible to be implemented in ynl.

Jakub, still not willing to pull this in?

Yes, I think I said this in the first LPC talk about YNL. My main goal is to make support for higher level languages seamless. That means someone needs to write a code gen or ynl.py-like integration for Go, Rust or C++ (proper C++ one not just a copy of the C code gen). Complicating the specs makes that less likely.

#4 lore raw

PATCH v4 2/4 net: team: rename team to team_core for linking

In reply to Hangbin Liu

Similar with commit 08d323234d10 ("net: fou: rename the source for linking"), We'll need to link two objects together to form the team module. This means the source can't be called team, the build system expects team.o to be the combined object.

---
 drivers/net/team/Makefile                | 1 +
 drivers/net/team/{team.c => team_core.c} | 0
 2 files changed, 1 insertion(+)
 rename drivers/net/team/{team.c => team_core.c} (100%)
drivers/net/team/Makefile +1 -0
index f582d81a5091..244db32c1060 100644
@@ -3,6 +3,7 @@
 # Makefile for the network team driver
 #
 
+team-y:= team_core.o
 obj-$(CONFIG_NET_TEAM) += team.o
 obj-$(CONFIG_NET_TEAM_MODE_BROADCAST) += team_mode_broadcast.o
 obj-$(CONFIG_NET_TEAM_MODE_ROUNDROBIN) += team_mode_roundrobin.o
drivers/net/team/team_core.c renamed from drivers/net/team/team.c +0 -0
similarity index 100%
rename from drivers/net/team/team.c
rename to drivers/net/team/team_core.c
Signature · 1 line
2.43.0
maintainer Reviewed-by on v4 2/4
#5 lore raw

Re: [PATCH net v1] dpll: indent DPLL option type by a tab

Quoted 6 lines · Mon, Apr 01, 2024 at 05:10:02AM CEST, [email protected] wrote:

Similar with commit 08d323234d10 ("net: fou: rename the source for linking"), We'll need to link two objects together to form the team module. This means the source can't be called team, the build system expects team.o to be the combined object.

#6 lore raw

PATCH v4 3/4 net: team: use policy generated by YAML spec

In reply to Hangbin Liu

generated with:

 $ ./tools/net/ynl/ynl-gen-c.py --mode kernel \
Quoted 2 lines

--spec Documentation/netlink/specs/team.yaml --source \
-o drivers/net/team/team_nl.c

 $ ./tools/net/ynl/ynl-gen-c.py --mode kernel \
Quoted 2 lines

--spec Documentation/netlink/specs/team.yaml --header \
-o drivers/net/team/team_nl.h

The TEAM_ATTR_LIST_PORT in team_nl_policy is removed as it is only in the port list reply attributes.

---
 drivers/net/team/Makefile    |  2 +-
 drivers/net/team/team_core.c | 63 ++++++------------------------------
 drivers/net/team/team_nl.c   | 59 +++++++++++++++++++++++++++++++++
 drivers/net/team/team_nl.h   | 29 +++++++++++++++++
 4 files changed, 98 insertions(+), 55 deletions(-)
 create mode 100644 drivers/net/team/team_nl.c
 create mode 100644 drivers/net/team/team_nl.h
drivers/net/team/Makefile +1 -1
index 244db32c1060..7a5aa20d286b 100644
@@ -3,7 +3,7 @@
 # Makefile for the network team driver
 #
 
-team-y:= team_core.o
+team-y:= team_core.o team_nl.o
 obj-$(CONFIG_NET_TEAM) += team.o
 obj-$(CONFIG_NET_TEAM_MODE_BROADCAST) += team_mode_broadcast.o
 obj-$(CONFIG_NET_TEAM_MODE_ROUNDROBIN) += team_mode_roundrobin.o
drivers/net/team/team_core.c +9 -54

111 lines not on this page · raw message

drivers/net/team/team_nl.c new file +59 -0

59 lines not on this page · raw message

drivers/net/team/team_nl.h new file +29 -0
new file mode 100644
index 000000000000..c9ec1b22ac4d
@@ -0,0 +1,29 @@
+/* SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause) */
+/* Do not edit directly, auto-generated from: */
+/*	Documentation/netlink/specs/team.yaml */
+/* YNL-GEN kernel header */
+
+#ifndef _LINUX_TEAM_GEN_H
+#define _LINUX_TEAM_GEN_H
+
+#include <net/netlink.h>
+#include <net/genetlink.h>
+
+#include <uapi/linux/if_team.h>
+
+/* Common nested types */
+extern const struct nla_policy team_attr_option_nl_policy[TEAM_ATTR_OPTION_ARRAY_INDEX + 1];
+extern const struct nla_policy team_item_option_nl_policy[TEAM_ATTR_ITEM_OPTION + 1];
+
+/* Global operation policy for team */
+extern const struct nla_policy team_nl_policy[TEAM_ATTR_LIST_OPTION + 1];
+
+/* Ops table for team */
+extern const struct genl_small_ops team_nl_ops[4];
+
+int team_nl_noop_doit(struct sk_buff *skb, struct genl_info *info);
+int team_nl_options_set_doit(struct sk_buff *skb, struct genl_info *info);
+int team_nl_options_get_doit(struct sk_buff *skb, struct genl_info *info);
+int team_nl_port_list_get_doit(struct sk_buff *skb, struct genl_info *info);
+
+#endif /* _LINUX_TEAM_GEN_H */
Signature · 1 line
2.43.0
maintainer Reviewed-by on v4 3/4
#7 lore raw

Re: [PATCHv4 net-next 3/4] net: team: use policy generated by YAML spec

Quoted 5 lines · Mon, Apr 01, 2024 at 05:10:03AM CEST, [email protected] wrote:

generated with:

$ ./tools/net/ynl/ynl-gen-c.py --mode kernel \
Quoted 2 lines

--spec Documentation/netlink/specs/team.yaml --source \
-o drivers/net/team/team_nl.c

Quoted 8 lines
$ ./tools/net/ynl/ynl-gen-c.py --mode kernel \
Quoted 2 lines

--spec Documentation/netlink/specs/team.yaml --header \
-o drivers/net/team/team_nl.h

The TEAM_ATTR_LIST_PORT in team_nl_policy is removed as it is only in the port list reply attributes.

#8 lore raw

PATCH v4 4/4 uapi: team: use header file generated from YAML spec

In reply to Hangbin Liu

generated with:

 $ ./tools/net/ynl/ynl-gen-c.py --mode uapi \
Quoted 2 lines

--spec Documentation/netlink/specs/team.yaml \
--header -o include/uapi/linux/if_team.h

---
 include/uapi/linux/if_team.h | 116 +++++++++++++----------------------
 1 file changed, 43 insertions(+), 73 deletions(-)
include/uapi/linux/if_team.h +43 -73
index 13c61fecb78b..a5c06243a435 100644
@@ -1,108 +1,78 @@
-/* SPDX-License-Identifier: GPL-2.0+ WITH Linux-syscall-note */
-/*
- * include/linux/if_team.h - Network team device driver header
- * Copyright (c) 2011 Jiri Pirko <[email protected]>
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- */
+/* SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause) */
+/* Do not edit directly, auto-generated from: */
+/*	Documentation/netlink/specs/team.yaml */
+/* YNL-GEN uapi header */
 
-#ifndef _UAPI_LINUX_IF_TEAM_H_
-#define _UAPI_LINUX_IF_TEAM_H_
+#ifndef _UAPI_LINUX_IF_TEAM_H
+#define _UAPI_LINUX_IF_TEAM_H
 
+#define TEAM_GENL_NAME		"team"
+#define TEAM_GENL_VERSION	1
 
-#define TEAM_STRING_MAX_LEN 32
-
-/**********************************
- * NETLINK_GENERIC netlink family.
- **********************************/
-
-enum {
-	TEAM_CMD_NOOP,
-	TEAM_CMD_OPTIONS_SET,
-	TEAM_CMD_OPTIONS_GET,
-	TEAM_CMD_PORT_LIST_GET,
-
-	__TEAM_CMD_MAX,
-	TEAM_CMD_MAX = (__TEAM_CMD_MAX - 1),
-};
+#define TEAM_STRING_MAX_LEN			32
+#define TEAM_GENL_CHANGE_EVENT_MC_GRP_NAME	"change_event"
 
 enum {
 	TEAM_ATTR_UNSPEC,
-	TEAM_ATTR_TEAM_IFINDEX,		/* u32 */
-	TEAM_ATTR_LIST_OPTION,		/* nest */
-	TEAM_ATTR_LIST_PORT,		/* nest */
+	TEAM_ATTR_TEAM_IFINDEX,
+	TEAM_ATTR_LIST_OPTION,
+	TEAM_ATTR_LIST_PORT,
 
 	__TEAM_ATTR_MAX,
-	TEAM_ATTR_MAX = __TEAM_ATTR_MAX - 1,
+	TEAM_ATTR_MAX = (__TEAM_ATTR_MAX - 1)
 };
 
-/* Nested layout of get/set msg:
- *
- *	[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_*], ...
- *		...
- */
-
 enum {
 	TEAM_ATTR_ITEM_OPTION_UNSPEC,
-	TEAM_ATTR_ITEM_OPTION,		/* nest */
+	TEAM_ATTR_ITEM_OPTION,
 
 	__TEAM_ATTR_ITEM_OPTION_MAX,
-	TEAM_ATTR_ITEM_OPTION_MAX = __TEAM_ATTR_ITEM_OPTION_MAX - 1,
+	TEAM_ATTR_ITEM_OPTION_MAX = (__TEAM_ATTR_ITEM_OPTION_MAX - 1)
 };
 
 enum {
 	TEAM_ATTR_OPTION_UNSPEC,
-	TEAM_ATTR_OPTION_NAME,		/* string */
-	TEAM_ATTR_OPTION_CHANGED,	/* flag */
-	TEAM_ATTR_OPTION_TYPE,		/* u8 */
-	TEAM_ATTR_OPTION_DATA,		/* dynamic */
-	TEAM_ATTR_OPTION_REMOVED,	/* flag */
-	TEAM_ATTR_OPTION_PORT_IFINDEX,	/* u32 */ /* for per-port options */
-	TEAM_ATTR_OPTION_ARRAY_INDEX,	/* u32 */ /* for array options */
+	TEAM_ATTR_OPTION_NAME,
+	TEAM_ATTR_OPTION_CHANGED,
+	TEAM_ATTR_OPTION_TYPE,
+	TEAM_ATTR_OPTION_DATA,
+	TEAM_ATTR_OPTION_REMOVED,
+	TEAM_ATTR_OPTION_PORT_IFINDEX,
+	TEAM_ATTR_OPTION_ARRAY_INDEX,
 
 	__TEAM_ATTR_OPTION_MAX,
-	TEAM_ATTR_OPTION_MAX = __TEAM_ATTR_OPTION_MAX - 1,
+	TEAM_ATTR_OPTION_MAX = (__TEAM_ATTR_OPTION_MAX - 1)
 };
 
 enum {
 	TEAM_ATTR_ITEM_PORT_UNSPEC,
-	TEAM_ATTR_ITEM_PORT,		/* nest */
+	TEAM_ATTR_ITEM_PORT,
 
 	__TEAM_ATTR_ITEM_PORT_MAX,
-	TEAM_ATTR_ITEM_PORT_MAX = __TEAM_ATTR_ITEM_PORT_MAX - 1,
+	TEAM_ATTR_ITEM_PORT_MAX = (__TEAM_ATTR_ITEM_PORT_MAX - 1)
 };
 
 enum {
 	TEAM_ATTR_PORT_UNSPEC,
-	TEAM_ATTR_PORT_IFINDEX,		/* u32 */
-	TEAM_ATTR_PORT_CHANGED,		/* flag */
-	TEAM_ATTR_PORT_LINKUP,		/* flag */
-	TEAM_ATTR_PORT_SPEED,		/* u32 */
-	TEAM_ATTR_PORT_DUPLEX,		/* u8 */
-	TEAM_ATTR_PORT_REMOVED,		/* flag */
+	TEAM_ATTR_PORT_IFINDEX,
+	TEAM_ATTR_PORT_CHANGED,
+	TEAM_ATTR_PORT_LINKUP,
+	TEAM_ATTR_PORT_SPEED,
+	TEAM_ATTR_PORT_DUPLEX,
+	TEAM_ATTR_PORT_REMOVED,
 
 	__TEAM_ATTR_PORT_MAX,
-	TEAM_ATTR_PORT_MAX = __TEAM_ATTR_PORT_MAX - 1,
+	TEAM_ATTR_PORT_MAX = (__TEAM_ATTR_PORT_MAX - 1)
 };
 
-/*
- * NETLINK_GENERIC related info
- */
-#define TEAM_GENL_NAME "team"
-#define TEAM_GENL_VERSION 0x1
-#define TEAM_GENL_CHANGE_EVENT_MC_GRP_NAME "change_event"
+enum {
+	TEAM_CMD_NOOP,
+	TEAM_CMD_OPTIONS_SET,
+	TEAM_CMD_OPTIONS_GET,
+	TEAM_CMD_PORT_LIST_GET,
+
+	__TEAM_CMD_MAX,
+	TEAM_CMD_MAX = (__TEAM_CMD_MAX - 1)
+};
 
-#endif /* _UAPI_LINUX_IF_TEAM_H_ */
+#endif /* _UAPI_LINUX_IF_TEAM_H */
Signature · 1 line
2.43.0
#10 lore raw
In reply to Hangbin Liu
This series was applied to netdev/net-next.git (main) by Jakub Kicinski <[email protected]>:

Hello:

This series was applied to netdev/net-next.git (main) by Jakub Kicinski <[email protected]>:

Quoted 13 lines · On Mon, 1 Apr 2024 11:10:00 +0800 you wrote:

Add a YAML spec for team. As we need to link two objects together to form the team module, rename team to team_core for linking.

v4:
1. fix the wrong squashe changes (Jakub Kicinski)
v3:
1. remove item/list-option from request as they are not attributes (Jakub Kicinski)
v2:
1. adjust the continuation line (Jakub Kicinski)
2. adjust the family maxattr (Jakub Kicinski)
v1:
1. remove dump from team options. (Jiri Pirko)

Quoted 1 line

[...]

Here is the summary with links:
- [PATCHv4,net-next,1/4] Documentation: netlink: add a YAML spec for team

    https://git.kernel.org/netdev/net-next/c/387724cbf415
  - [PATCHv4,net-next,2/4] net: team: rename team to team_core for linking
    https://git.kernel.org/netdev/net-next/c/a0393e3e3ddb
  - [PATCHv4,net-next,3/4] net: team: use policy generated by YAML spec
    https://git.kernel.org/netdev/net-next/c/948dbafc15da
  - [PATCHv4,net-next,4/4] uapi: team: use header file generated from YAML spec
    https://git.kernel.org/netdev/net-next/c/e57ba7e3d7bc

You are awesome, thank you!

Signature · 2 lines
Deet-doot-dot, I am a bot.
https://korg.docs.kernel.org/patchwork/pwbot.html