Skip to contentSkip to conversation

tcp_metrics: add netlink protocol spec in YAML

PATCH Applied Jakub Kicinski 3 participants 6 messages Jun 27, 2024 – Jul 1, 2024

Subsystems (3)
lore
Share & tools
lore

Jakub Kicinski

author maintainer
#0 lore raw

v2 cover tcp_metrics: add netlink protocol spec in YAML

Add a netlink protocol spec for the tcp_metrics generic netlink family. First patch adjusts the uAPI header guards to make it easier to build tools/ with non-system headers.

v1: https://lore.kernel.org/all/[email protected]

Jakub Kicinski (2):
tcp_metrics: add UAPI to the header guard
tcp_metrics: add netlink protocol spec in YAML

 Documentation/netlink/specs/tcp_metrics.yaml | 169 +++++++++++++++++++
 include/uapi/linux/tcp_metrics.h             |  22 ++-
 tools/net/ynl/Makefile.deps                  |   1 +
 3 files changed, 189 insertions(+), 3 deletions(-)
 create mode 100644 Documentation/netlink/specs/tcp_metrics.yaml
Signature · 1 line
2.45.2
author maintainer
#1 lore raw

PATCH v2 1/2 tcp_metrics: add UAPI to the header guard

tcp_metrics' header lacks the customary _UAPI in the header guard. This makes YNL build rules work less seamlessly.
We can easily fix that on YNL side, but this could also be problematic if we ever needed to create a kernel-only tcp_metrics.h.

---
 include/uapi/linux/tcp_metrics.h | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)
include/uapi/linux/tcp_metrics.h +3 -3
index 7cb4a172feed..c48841076998 100644
@@ -1,8 +1,8 @@
 /* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
 /* tcp_metrics.h - TCP Metrics Interface */
 
-#ifndef _LINUX_TCP_METRICS_H
-#define _LINUX_TCP_METRICS_H
+#ifndef _UAPI_LINUX_TCP_METRICS_H
+#define _UAPI_LINUX_TCP_METRICS_H
 
 #include <linux/types.h>
 
@@ -58,4 +58,4 @@ enum {
 
 #define TCP_METRICS_CMD_MAX	(__TCP_METRICS_CMD_MAX - 1)
 
-#endif /* _LINUX_TCP_METRICS_H */
+#endif /* _UAPI_LINUX_TCP_METRICS_H */
Signature · 1 line
2.45.2
maintainer Reviewed-by on v2 1/2
#2 lore raw

Re: [PATCH net-next v2 1/2] tcp_metrics: add UAPI to the header guard

Quoted 6 lines · Jakub Kicinski

tcp_metrics' header lacks the customary _UAPI in the header guard. This makes YNL build rules work less seamlessly.
We can easily fix that on YNL side, but this could also be problematic if we ever needed to create a kernel-only tcp_metrics.h.

author maintainer
#3 lore raw

PATCH v2 2/2 tcp_metrics: add netlink protocol spec in YAML

In reply to Jakub Kicinski

Add a protocol spec for tcp_metrics, so that it's accessible via YNL. Useful at the very least for testing fixes.

In this episode of "10,000 ways to complicate netlink" the metric nest has defines which are off by 1. iproute2 does:

        struct rtattr *m[TCP_METRIC_MAX + 1 + 1];

        parse_rtattr_nested(m, TCP_METRIC_MAX + 1, a);

        for (i = 0; i < TCP_METRIC_MAX + 1; i++) {
                // ...
                attr = m[i + 1];

This is too weird to support in YNL, add a new set of defines with _correct_ values to the official kernel header.

---
CC: [email protected]

v2:
- remove unused unspec op and attr (TCP_METRICS_ATTR_UNSPEC and TCP_METRICS_CMD_UNSPEC exist, but we can't generate uAPI, anyway)
- fix typos
- s/_/-/ on metric names
- correct doc on rttvar-us (like rttvar there are 2 fractional bits)

---
 Documentation/netlink/specs/tcp_metrics.yaml | 169 +++++++++++++++++++
 include/uapi/linux/tcp_metrics.h             |  16 ++
 tools/net/ynl/Makefile.deps                  |   1 +
 3 files changed, 186 insertions(+)
 create mode 100644 Documentation/netlink/specs/tcp_metrics.yaml
Documentation/netlink/specs/tcp_metrics.yaml new file +169 -0
new file mode 100644
index 000000000000..1bd94f43e526
@@ -0,0 +1,169 @@
+# SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)
+
+name: tcp_metrics
+
+protocol: genetlink-legacy
+
+doc: |
+  Management interface for TCP metrics.
+
+c-family-name: tcp-metrics-genl-name
+c-version-name: tcp-metrics-genl-version
+max-by-define: true
+kernel-policy: global
+
+definitions:
+  -
+    name: tcp-fastopen-cookie-max
+    type: const
+    value: 16
+
+attribute-sets:
+  -
+    name: tcp-metrics
+    name-prefix: tcp-metrics-attr-
+    attributes:
+      -
+        name: addr-ipv4
+        type: u32
+        byte-order: big-endian
+        display-hint: ipv4
+      -
+        name: addr-ipv6
+        type: binary
+        checks:
+          min-len: 16
+        byte-order: big-endian
+        display-hint: ipv6
+      -
+        name: age
+        type: u64
+      -
+        name: tw-tsval
+        type: u32
+        doc: unused
+      -
+        name: tw-ts-stamp
+        type: s32
+        doc: unused
+      -
+        name: vals
+        type: nest
+        nested-attributes: metrics
+      -
+        name: fopen-mss
+        type: u16
+      -
+        name: fopen-syn-drops
+        type: u16
+      -
+        name: fopen-syn-drop-ts
+        type: u64
+      -
+        name: fopen-cookie
+        type: binary
+        checks:
+          min-len: tcp-fastopen-cookie-max
+      -
+        name: saddr-ipv4
+        type: u32
+        byte-order: big-endian
+        display-hint: ipv4
+      -
+        name: saddr-ipv6
+        type: binary
+        checks:
+          min-len: 16
+        byte-order: big-endian
+        display-hint: ipv6
+      -
+        name: pad
+        type: pad
+
+  -
+    name: metrics
+    # Intentionally don't define the name-prefix, see below.
+    doc: |
+      Attributes with metrics. Note that the values here do not match
+      the TCP_METRIC_* defines in the kernel, because kernel defines
+      are off-by one (e.g. rtt is defined as enum 0, while netlink carries
+      attribute type 1).
+    attributes:
+      -
+        name: rtt
+        type: u32
+        doc: |
+          Round Trip Time (RTT), in msecs with 3 bits fractional
+          (left-shift by 3 to get the msec value).
+      -
+        name: rttvar
+        type: u32
+        doc: |
+          Round Trip Time VARiance (RTT), in msecs with 2 bits fractional
+          (left-shift by 2 to get the msec value).
+      -
+        name: ssthresh
+        type: u32
+        doc: Slow Start THRESHold.
+      -
+        name: cwnd
+        type: u32
+        doc: Congestion Window.
+      -
+        name: reodering
+        type: u32
+        doc: Reodering metric.
+      -
+        name: rtt-us
+        type: u32
+        doc: |
+          Round Trip Time (RTT), in usecs, with 3 bits fractional
+          (left-shift by 3 to get the msec value).
+      -
+        name: rttvar-us
+        type: u32
+        doc: |
+          Round Trip Time (RTT), in usecs, with 2 bits fractional
+          (left-shift by 3 to get the msec value).
+
+operations:
+  list:
+    -
+      name: get
+      doc: Retrieve metrics.
+      attribute-set: tcp-metrics
+
+      dont-validate: [ strict, dump ]
+
+      do:
+        request: &sel_attrs
+          attributes:
+            - addr-ipv4
+            - addr-ipv6
+            - saddr-ipv4
+            - saddr-ipv6
+        reply: &all_attrs
+          attributes:
+            - addr-ipv4
+            - addr-ipv6
+            - saddr-ipv4
+            - saddr-ipv6
+            - age
+            - vals
+            - fopen-mss
+            - fopen-syn-drops
+            - fopen-syn-drop-ts
+            - fopen-cookie
+      dump:
+        reply: *all_attrs
+
+    -
+      name: del
+      doc: Delete metrics.
+      attribute-set: tcp-metrics
+
+      dont-validate: [ strict, dump ]
+      flags: [ admin-perm ]
+
+      do:
+        request: *sel_attrs
include/uapi/linux/tcp_metrics.h +16 -0
index c48841076998..927c735a5b0e 100644
@@ -27,6 +27,22 @@ enum tcp_metric_index {
 
 #define TCP_METRIC_MAX	(__TCP_METRIC_MAX - 1)
 
+/* Re-define enum tcp_metric_index, again, using the values carried
+ * as netlink attribute types.
+ */
+enum {
+	TCP_METRICS_A_METRICS_RTT = 1,
+	TCP_METRICS_A_METRICS_RTTVAR,
+	TCP_METRICS_A_METRICS_SSTHRESH,
+	TCP_METRICS_A_METRICS_CWND,
+	TCP_METRICS_A_METRICS_REODERING,
+	TCP_METRICS_A_METRICS_RTT_US,
+	TCP_METRICS_A_METRICS_RTTVAR_US,
+
+	__TCP_METRICS_A_METRICS_MAX
+};
+#define TCP_METRICS_A_METRICS_MAX (__TCP_METRICS_A_METRICS_MAX - 1)
+
 enum {
 	TCP_METRICS_ATTR_UNSPEC,
 	TCP_METRICS_ATTR_ADDR_IPV4,		/* u32 */
tools/net/ynl/Makefile.deps +1 -0
index f4e8eb79c1b8..33399fbe9851 100644
@@ -25,3 +25,4 @@ CFLAGS_nfsd:=$(call get_hdr_inc,_LINUX_NFSD_NETLINK_H,nfsd_netlink.h)
 CFLAGS_ovs_datapath:=$(call get_hdr_inc,__LINUX_OPENVSWITCH_H,openvswitch.h)
 CFLAGS_ovs_flow:=$(call get_hdr_inc,__LINUX_OPENVSWITCH_H,openvswitch.h)
 CFLAGS_ovs_vport:=$(call get_hdr_inc,__LINUX_OPENVSWITCH_H,openvswitch.h)
+CFLAGS_tcp_metrics:=$(call get_hdr_inc,_LINUX_TCP_METRICS_H,tcp_metrics.h)
Signature · 1 line
2.45.2
maintainer Reviewed-by on v2 2/2
#4 lore raw
Quoted 14 lines · Jakub Kicinski

Add a protocol spec for tcp_metrics, so that it's accessible via YNL. Useful at the very least for testing fixes.

In this episode of "10,000 ways to complicate netlink" the metric nest has defines which are off by 1. iproute2 does:

        struct rtattr *m[TCP_METRIC_MAX + 1 + 1];

        parse_rtattr_nested(m, TCP_METRIC_MAX + 1, a);

        for (i = 0; i < TCP_METRIC_MAX + 1; i++) {
                // ...
                attr = m[i + 1];
Quoted 4 lines

This is too weird to support in YNL, add a new set of defines with _correct_ values to the official kernel header.

#5 lore raw
In reply to Jakub Kicinski
This series was applied to netdev/net-next.git (main) by David S. Miller <[email protected]>:

Hello:

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

Quoted 11 lines · On Thu, 27 Jun 2024 14:35:49 -0700 you wrote:

Add a netlink protocol spec for the tcp_metrics generic netlink family. First patch adjusts the uAPI header guards to make it easier to build tools/ with non-system headers.

v1: https://lore.kernel.org/all/[email protected]

Jakub Kicinski (2):
tcp_metrics: add UAPI to the header guard
tcp_metrics: add netlink protocol spec in YAML

[...]

Here is the summary with links:
- [net-next,v2,1/2] tcp_metrics: add UAPI to the header guard

    https://git.kernel.org/netdev/net-next/c/7c8110057b1b
  - [net-next,v2,2/2] tcp_metrics: add netlink protocol spec in YAML
    https://git.kernel.org/netdev/net-next/c/85674625e0bc

You are awesome, thank you!

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