From a51126424f75a7b44b11f7b821f6abb0b78bd931 Mon Sep 17 00:00:00 2001 From: "Matthieu Baerts (NGI0)" Date: Sat, 13 Sep 2025 15:29:51 +0200 Subject: [PATCH 1/3] tools: ynl: rst: display attribute-set doc Some attribute-set have a documentation (doc:), but it was not displayed in the RST / HTML version. Such field can be found in ethtool, netdev, tcp_metrics and team YAML files. Only the 'name' and 'attributes' fields from an 'attribute-set' section were parsed. Now the content of the 'doc' field, if available, is added as a new paragraph before listing each attribute. This is similar to what is done when parsing the 'operations'. Signed-off-by: Matthieu Baerts (NGI0) Link: https://patch.msgid.link/20250913-net-next-ynl-attr-doc-rst-v3-1-4f06420d87db@kernel.org Signed-off-by: Jakub Kicinski --- tools/net/ynl/pyynl/lib/doc_generator.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/tools/net/ynl/pyynl/lib/doc_generator.py b/tools/net/ynl/pyynl/lib/doc_generator.py index 403abf1a2eda..3a16b8eb01ca 100644 --- a/tools/net/ynl/pyynl/lib/doc_generator.py +++ b/tools/net/ynl/pyynl/lib/doc_generator.py @@ -289,6 +289,10 @@ class YnlDocGenerator: for entry in entries: lines.append(self.fmt.rst_section(namespace, 'attribute-set', entry["name"])) + + if "doc" in entry: + lines.append(self.fmt.rst_paragraph(entry["doc"], 0) + "\n") + for attr in entry["attributes"]: if LINE_STR in attr: lines.append(self.fmt.rst_lineno(attr[LINE_STR])) From 515c0ead788f4118a91b3ae55fe51f95543553ec Mon Sep 17 00:00:00 2001 From: "Matthieu Baerts (NGI0)" Date: Sat, 13 Sep 2025 15:29:52 +0200 Subject: [PATCH 2/3] netlink: specs: team: avoid mangling multilines doc By default, strings defined in YAML at the next line are folded: newlines are replaced by spaces. Here, the newlines are there for a reason, and should be kept in the output. This can be fixed by adding the '|' symbol to use the "literal" style. This issue was introduced by commit 387724cbf415 ("Documentation: netlink: add a YAML spec for team"), but visible in the doc only since the parent commit. To avoid warnings when generating the HTML output, and to look better, the code layout is now in a dedicated code block, which requires '::' and a new blank line. Just for a question of uniformity, a new blank line is also added after the code block. Suggested-by: Donald Hunter Signed-off-by: Matthieu Baerts (NGI0) Link: https://patch.msgid.link/20250913-net-next-ynl-attr-doc-rst-v3-2-4f06420d87db@kernel.org Signed-off-by: Jakub Kicinski --- Documentation/netlink/specs/team.yaml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Documentation/netlink/specs/team.yaml b/Documentation/netlink/specs/team.yaml index cf02d47d12a4..83a275b44c82 100644 --- a/Documentation/netlink/specs/team.yaml +++ b/Documentation/netlink/specs/team.yaml @@ -25,8 +25,9 @@ definitions: attribute-sets: - name: team - doc: - The team nested layout of get/set msg looks like + doc: | + The team nested layout of get/set msg looks like:: + [TEAM_ATTR_LIST_OPTION] [TEAM_ATTR_ITEM_OPTION] [TEAM_ATTR_OPTION_*], ... @@ -39,6 +40,7 @@ attribute-sets: [TEAM_ATTR_ITEM_PORT] [TEAM_ATTR_PORT_*], ... ... + name-prefix: team-attr- attributes: - From 12e74931ee9792b5256f4433efd779cfd0aca443 Mon Sep 17 00:00:00 2001 From: "Matthieu Baerts (NGI0)" Date: Sat, 13 Sep 2025 15:29:53 +0200 Subject: [PATCH 3/3] netlink: specs: explicitly declare block scalar strings In YAML, it is allowed to declare a scalar strings at the next lines without explicitly declaring them as a block. Yet, they looks weird, and can cause issues when ':' or '#' are present. The modified lines didn't have issues with the special characters, but it seems better to explicitly declare such blocks as scalar strings to encourage people to "properly" declare future scalar strings. The right angle bracket is used with a minus sign to indicate that the folded style should be used without adding extra newlines. By doing that, the output is not changed compared to what was done before this patch. Suggested-by: Donald Hunter Signed-off-by: Matthieu Baerts (NGI0) Link: https://patch.msgid.link/20250913-net-next-ynl-attr-doc-rst-v3-3-4f06420d87db@kernel.org Signed-off-by: Jakub Kicinski --- Documentation/netlink/specs/conntrack.yaml | 2 +- Documentation/netlink/specs/netdev.yaml | 22 +++++++++---------- Documentation/netlink/specs/nftables.yaml | 2 +- Documentation/netlink/specs/nl80211.yaml | 2 +- Documentation/netlink/specs/ovs_datapath.yaml | 2 +- Documentation/netlink/specs/ovs_flow.yaml | 2 +- Documentation/netlink/specs/ovs_vport.yaml | 2 +- Documentation/netlink/specs/rt-addr.yaml | 2 +- Documentation/netlink/specs/rt-link.yaml | 2 +- Documentation/netlink/specs/rt-neigh.yaml | 2 +- Documentation/netlink/specs/rt-route.yaml | 2 +- Documentation/netlink/specs/rt-rule.yaml | 2 +- Documentation/netlink/specs/tc.yaml | 2 +- 13 files changed, 23 insertions(+), 23 deletions(-) diff --git a/Documentation/netlink/specs/conntrack.yaml b/Documentation/netlink/specs/conntrack.yaml index c6832633ab7b..642ac859cb7a 100644 --- a/Documentation/netlink/specs/conntrack.yaml +++ b/Documentation/netlink/specs/conntrack.yaml @@ -4,7 +4,7 @@ name: conntrack protocol: netlink-raw protonum: 12 -doc: +doc: >- Netfilter connection tracking subsystem over nfnetlink definitions: diff --git a/Documentation/netlink/specs/netdev.yaml b/Documentation/netlink/specs/netdev.yaml index c035dc0f64fd..e00d3fa1c152 100644 --- a/Documentation/netlink/specs/netdev.yaml +++ b/Documentation/netlink/specs/netdev.yaml @@ -2,7 +2,7 @@ --- name: netdev -doc: +doc: >- netdev configuration over generic netlink. definitions: @@ -13,33 +13,33 @@ definitions: entries: - name: basic - doc: + doc: >- XDP features set supported by all drivers (XDP_ABORTED, XDP_DROP, XDP_PASS, XDP_TX) - name: redirect - doc: + doc: >- The netdev supports XDP_REDIRECT - name: ndo-xmit - doc: + doc: >- This feature informs if netdev implements ndo_xdp_xmit callback. - name: xsk-zerocopy - doc: + doc: >- This feature informs if netdev supports AF_XDP in zero copy mode. - name: hw-offload - doc: + doc: >- This feature informs if netdev supports XDP hw offloading. - name: rx-sg - doc: + doc: >- This feature informs if netdev implements non-linear XDP buffer support in the driver napi callback. - name: ndo-xmit-sg - doc: + doc: >- This feature informs if netdev implements non-linear XDP buffer support in ndo_xdp_xmit callback. - @@ -67,15 +67,15 @@ definitions: entries: - name: tx-timestamp - doc: + doc: >- HW timestamping egress packets is supported by the driver. - name: tx-checksum - doc: + doc: >- L3 checksum HW offload is supported by the driver. - name: tx-launch-time-fifo - doc: + doc: >- Launch time HW offload is supported by the driver. - name: queue-type diff --git a/Documentation/netlink/specs/nftables.yaml b/Documentation/netlink/specs/nftables.yaml index 2ee10d92d644..cce88819ba71 100644 --- a/Documentation/netlink/specs/nftables.yaml +++ b/Documentation/netlink/specs/nftables.yaml @@ -4,7 +4,7 @@ name: nftables protocol: netlink-raw protonum: 12 -doc: +doc: >- Netfilter nftables configuration over netlink. definitions: diff --git a/Documentation/netlink/specs/nl80211.yaml b/Documentation/netlink/specs/nl80211.yaml index 610fdd5e000e..802097128bda 100644 --- a/Documentation/netlink/specs/nl80211.yaml +++ b/Documentation/netlink/specs/nl80211.yaml @@ -3,7 +3,7 @@ name: nl80211 protocol: genetlink-legacy -doc: +doc: >- Netlink API for 802.11 wireless devices definitions: diff --git a/Documentation/netlink/specs/ovs_datapath.yaml b/Documentation/netlink/specs/ovs_datapath.yaml index 0c0abf3f9f05..f7b3671991e6 100644 --- a/Documentation/netlink/specs/ovs_datapath.yaml +++ b/Documentation/netlink/specs/ovs_datapath.yaml @@ -5,7 +5,7 @@ version: 2 protocol: genetlink-legacy uapi-header: linux/openvswitch.h -doc: +doc: >- OVS datapath configuration over generic netlink. definitions: diff --git a/Documentation/netlink/specs/ovs_flow.yaml b/Documentation/netlink/specs/ovs_flow.yaml index 2dac9c8add57..951837b72e1d 100644 --- a/Documentation/netlink/specs/ovs_flow.yaml +++ b/Documentation/netlink/specs/ovs_flow.yaml @@ -5,7 +5,7 @@ version: 1 protocol: genetlink-legacy uapi-header: linux/openvswitch.h -doc: +doc: >- OVS flow configuration over generic netlink. definitions: diff --git a/Documentation/netlink/specs/ovs_vport.yaml b/Documentation/netlink/specs/ovs_vport.yaml index da47e65fd574..fa975f8821b6 100644 --- a/Documentation/netlink/specs/ovs_vport.yaml +++ b/Documentation/netlink/specs/ovs_vport.yaml @@ -5,7 +5,7 @@ version: 2 protocol: genetlink-legacy uapi-header: linux/openvswitch.h -doc: +doc: >- OVS vport configuration over generic netlink. definitions: diff --git a/Documentation/netlink/specs/rt-addr.yaml b/Documentation/netlink/specs/rt-addr.yaml index bafe3bfeabfb..3a582eac1629 100644 --- a/Documentation/netlink/specs/rt-addr.yaml +++ b/Documentation/netlink/specs/rt-addr.yaml @@ -5,7 +5,7 @@ protocol: netlink-raw uapi-header: linux/rtnetlink.h protonum: 0 -doc: +doc: >- Address configuration over rtnetlink. definitions: diff --git a/Documentation/netlink/specs/rt-link.yaml b/Documentation/netlink/specs/rt-link.yaml index 210394c188a3..6ab31f86854d 100644 --- a/Documentation/netlink/specs/rt-link.yaml +++ b/Documentation/netlink/specs/rt-link.yaml @@ -5,7 +5,7 @@ protocol: netlink-raw uapi-header: linux/rtnetlink.h protonum: 0 -doc: +doc: >- Link configuration over rtnetlink. definitions: diff --git a/Documentation/netlink/specs/rt-neigh.yaml b/Documentation/netlink/specs/rt-neigh.yaml index 30a9ee16f128..2f568a6231c9 100644 --- a/Documentation/netlink/specs/rt-neigh.yaml +++ b/Documentation/netlink/specs/rt-neigh.yaml @@ -5,7 +5,7 @@ protocol: netlink-raw uapi-header: linux/rtnetlink.h protonum: 0 -doc: +doc: >- IP neighbour management over rtnetlink. definitions: diff --git a/Documentation/netlink/specs/rt-route.yaml b/Documentation/netlink/specs/rt-route.yaml index 5b514ddeff1d..1ecb3fadc067 100644 --- a/Documentation/netlink/specs/rt-route.yaml +++ b/Documentation/netlink/specs/rt-route.yaml @@ -5,7 +5,7 @@ protocol: netlink-raw uapi-header: linux/rtnetlink.h protonum: 0 -doc: +doc: >- Route configuration over rtnetlink. definitions: diff --git a/Documentation/netlink/specs/rt-rule.yaml b/Documentation/netlink/specs/rt-rule.yaml index 46b1d426e7e8..bebee452a950 100644 --- a/Documentation/netlink/specs/rt-rule.yaml +++ b/Documentation/netlink/specs/rt-rule.yaml @@ -5,7 +5,7 @@ protocol: netlink-raw uapi-header: linux/fib_rules.h protonum: 0 -doc: +doc: >- FIB rule management over rtnetlink. definitions: diff --git a/Documentation/netlink/specs/tc.yaml b/Documentation/netlink/specs/tc.yaml index b1afc7ab3539..b398f7a46dae 100644 --- a/Documentation/netlink/specs/tc.yaml +++ b/Documentation/netlink/specs/tc.yaml @@ -5,7 +5,7 @@ protocol: netlink-raw uapi-header: linux/pkt_cls.h protonum: 0 -doc: +doc: >- Netlink raw family for tc qdisc, chain, class and filter configuration over rtnetlink.