[PATCH net 0/3] netlink: specs: mptcp: fixes for some descriptions

[PATCH net 0/3] netlink: specs: mptcp: fixes for some descriptions

[Matthieu Baerts (NGI0)]

When looking at the MPTCP PM Netlink specs rendered version [1], a few
small issues have been found with the descriptions, and fixed here:

- Patch 1: add a missing attribute for two events. For >= v5.19.

- Patch 2: clearly mention the attributes. For >= v6.7.

- Patch 3: fix missing descriptions and replace a wrong one. For >= v6.7.

Link: https://docs.kernel.org/networking/netlink_spec/mptcp_pm.html [1]
Signed-off-by: Matthieu Baerts (NGI0) <matttbe@kernel.org>
---
Please note that there is no urgency here: this can of course be sent to
Linus next year!

Enjoy this holiday period!

---
Matthieu Baerts (NGI0) (3):
      netlink: specs: mptcp: add missing 'server-side' attr
      netlink: specs: mptcp: clearly mention attributes
      netlink: specs: mptcp: fix missing doc

 Documentation/netlink/specs/mptcp_pm.yaml | 60 ++++++++++++++++---------------
 1 file changed, 31 insertions(+), 29 deletions(-)
---
base-commit: ce1219c3f76bb131d095e90521506d3c6ccfa086
change-id: 20241219-net-mptcp-netlink-specs-pm-doc-fixes-618a2e8f6aeb

Best regards,
-- 
Matthieu Baerts (NGI0) <matttbe@kernel.org>

[PATCH net 1/3] netlink: specs: mptcp: add missing 'server-side' attr

[Matthieu Baerts (NGI0)]

This attribute is added with the 'created' and 'established' events, but
the documentation didn't mention it.

Fixes: 41b3c69bf941 ("mptcp: expose server_side attribute in MPTCP netlink events")
Cc: stable@vger.kernel.org
Reviewed-by: Geliang Tang <geliang@kernel.org>
Signed-off-by: Matthieu Baerts (NGI0) <matttbe@kernel.org>
---
 Documentation/netlink/specs/mptcp_pm.yaml | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/Documentation/netlink/specs/mptcp_pm.yaml b/Documentation/netlink/specs/mptcp_pm.yaml
index dc190bf838fec6add28b61e5e2cac8dee601b012..fc0603f51665a6260fb4dc78bc641c4175a8577e 100644
--- a/Documentation/netlink/specs/mptcp_pm.yaml
+++ b/Documentation/netlink/specs/mptcp_pm.yaml
@@ -23,7 +23,8 @@ definitions:
      -
       name: created
       doc:
-        token, family, saddr4 | saddr6, daddr4 | daddr6, sport, dport
+        token, family, saddr4 | saddr6, daddr4 | daddr6, sport, dport,
+        server-side
         A new MPTCP connection has been created. It is the good time to
         allocate memory and send ADD_ADDR if needed. Depending on the
         traffic-patterns it can take a long time until the
@@ -31,7 +32,8 @@ definitions:
      -
       name: established
       doc:
-        token, family, saddr4 | saddr6, daddr4 | daddr6, sport, dport
+        token, family, saddr4 | saddr6, daddr4 | daddr6, sport, dport,
+        server-side
         A MPTCP connection is established (can start new subflows).
      -
       name: closed

-- 
2.47.1

[PATCH net 2/3] netlink: specs: mptcp: clearly mention attributes

[Matthieu Baerts (NGI0)]

The rendered version of the MPTCP events [1] looked strange, because the
whole content of the 'doc' was displayed in the same block.

It was then not clear that the first words, not even ended by a period,
were the attributes that are defined when such events are emitted. These
attributes have now been moved to the end, prefixed by 'Attributes:' and
ended with a period. Note that '>-' has been added after 'doc:' to allow
':' in the text below.

Fixes: bc8aeb2045e2 ("Documentation: netlink: add a YAML spec for mptcp")
Cc: stable@vger.kernel.org
Link: https://docs.kernel.org/networking/netlink_spec/mptcp_pm.html#event-type [1]
Reviewed-by: Geliang Tang <geliang@kernel.org>
Signed-off-by: Matthieu Baerts (NGI0) <matttbe@kernel.org>
---
 Documentation/netlink/specs/mptcp_pm.yaml | 50 +++++++++++++++----------------
 1 file changed, 25 insertions(+), 25 deletions(-)

diff --git a/Documentation/netlink/specs/mptcp_pm.yaml b/Documentation/netlink/specs/mptcp_pm.yaml
index fc0603f51665a6260fb4dc78bc641c4175a8577e..59087a23056510dfb939b702e231b6e97ae042c7 100644
--- a/Documentation/netlink/specs/mptcp_pm.yaml
+++ b/Documentation/netlink/specs/mptcp_pm.yaml
@@ -22,67 +22,67 @@ definitions:
       doc: unused event
      -
       name: created
-      doc:
-        token, family, saddr4 | saddr6, daddr4 | daddr6, sport, dport,
-        server-side
+      doc: >-
         A new MPTCP connection has been created. It is the good time to
         allocate memory and send ADD_ADDR if needed. Depending on the
         traffic-patterns it can take a long time until the
         MPTCP_EVENT_ESTABLISHED is sent.
+        Attributes: token, family, saddr4 | saddr6, daddr4 | daddr6, sport,
+        dport, server-side.
      -
       name: established
-      doc:
-        token, family, saddr4 | saddr6, daddr4 | daddr6, sport, dport,
-        server-side
+      doc: >-
         A MPTCP connection is established (can start new subflows).
+        Attributes: token, family, saddr4 | saddr6, daddr4 | daddr6, sport,
+        dport, server-side.
      -
       name: closed
-      doc:
-        token
+      doc: >-
         A MPTCP connection has stopped.
+        Attribute: token.
      -
       name: announced
       value: 6
-      doc:
-        token, rem_id, family, daddr4 | daddr6 [, dport]
+      doc: >-
         A new address has been announced by the peer.
+        Attributes: token, rem_id, family, daddr4 | daddr6 [, dport].
      -
       name: removed
-      doc:
-        token, rem_id
+      doc: >-
         An address has been lost by the peer.
+        Attributes: token, rem_id.
      -
       name: sub-established
       value: 10
-      doc:
-        token, family, loc_id, rem_id, saddr4 | saddr6, daddr4 | daddr6, sport,
-        dport, backup, if_idx [, error]
+      doc: >-
         A new subflow has been established. 'error' should not be set.
+        Attributes: token, family, loc_id, rem_id, saddr4 | saddr6, daddr4 |
+        daddr6, sport, dport, backup, if_idx [, error].
      -
       name: sub-closed
-      doc:
-        token, family, loc_id, rem_id, saddr4 | saddr6, daddr4 | daddr6, sport,
-        dport, backup, if_idx [, error]
+      doc: >-
         A subflow has been closed. An error (copy of sk_err) could be set if an
         error has been detected for this subflow.
+        Attributes: token, family, loc_id, rem_id, saddr4 | saddr6, daddr4 |
+        daddr6, sport, dport, backup, if_idx [, error].
      -
       name: sub-priority
       value: 13
-      doc:
-        token, family, loc_id, rem_id, saddr4 | saddr6, daddr4 | daddr6, sport,
-        dport, backup, if_idx [, error]
+      doc: >-
         The priority of a subflow has changed. 'error' should not be set.
+        Attributes: token, family, loc_id, rem_id, saddr4 | saddr6, daddr4 |
+        daddr6, sport, dport, backup, if_idx [, error].
      -
       name: listener-created
       value: 15
-      doc:
-        family, sport, saddr4 | saddr6
+      doc: >-
         A new PM listener is created.
+        Attributes: family, sport, saddr4 | saddr6.
      -
       name: listener-closed
-      doc:
-        family, sport, saddr4 | saddr6
+      doc: >-
         A PM listener is closed.
+        Attributes: family, sport, saddr4 | saddr6.
 
 attribute-sets:
   -

-- 
2.47.1

[PATCH net 3/3] netlink: specs: mptcp: fix missing doc

[Matthieu Baerts (NGI0)]

Two operations didn't have a small description. It looks like something
that has been missed in the original commit introducing this file.

Replace the two "todo" by a small and simple description: Create/Destroy
subflow.

While at it, also uniform the capital letters, avoid double spaces, and
fix the "announce" event description: a new "address" has been
announced, not a new "subflow".

Fixes: bc8aeb2045e2 ("Documentation: netlink: add a YAML spec for mptcp")
Cc: stable@vger.kernel.org
Reviewed-by: Geliang Tang <geliang@kernel.org>
Signed-off-by: Matthieu Baerts (NGI0) <matttbe@kernel.org>
---
 Documentation/netlink/specs/mptcp_pm.yaml | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/Documentation/netlink/specs/mptcp_pm.yaml b/Documentation/netlink/specs/mptcp_pm.yaml
index 59087a23056510dfb939b702e231b6e97ae042c7..dfd017780d2f942eefd6e5ab0f1edd3fba653172 100644
--- a/Documentation/netlink/specs/mptcp_pm.yaml
+++ b/Documentation/netlink/specs/mptcp_pm.yaml
@@ -308,8 +308,8 @@ operations:
          attributes:
            - addr
     -
-      name:  flush-addrs
-      doc: flush addresses
+      name: flush-addrs
+      doc: Flush addresses
       attribute-set: endpoint
       dont-validate: [ strict ]
       flags: [ uns-admin-perm ]
@@ -353,7 +353,7 @@ operations:
             - addr-remote
     -
       name: announce
-      doc: announce new sf
+      doc: Announce new address
       attribute-set: attr
       dont-validate: [ strict ]
       flags: [ uns-admin-perm ]
@@ -364,7 +364,7 @@ operations:
             - token
     -
       name: remove
-      doc: announce removal
+      doc: Announce removal
       attribute-set: attr
       dont-validate: [ strict ]
       flags: [ uns-admin-perm ]
@@ -375,7 +375,7 @@ operations:
            - loc-id
     -
       name: subflow-create
-      doc: todo
+      doc: Create subflow
       attribute-set: attr
       dont-validate: [ strict ]
       flags: [ uns-admin-perm ]
@@ -387,7 +387,7 @@ operations:
             - addr-remote
     -
       name: subflow-destroy
-      doc: todo
+      doc: Destroy subflow
       attribute-set: attr
       dont-validate: [ strict ]
       flags: [ uns-admin-perm ]

-- 
2.47.1

Re: [PATCH net 0/3] netlink: specs: mptcp: fixes for some descriptions

[Jakub Kicinski]

On Thu, 19 Dec 2024 12:45:26 +0100 Matthieu Baerts (NGI0) wrote:
> When looking at the MPTCP PM Netlink specs rendered version [1], a few
> small issues have been found with the descriptions, and fixed here:
> 
> - Patch 1: add a missing attribute for two events. For >= v5.19.
> 
> - Patch 2: clearly mention the attributes. For >= v6.7.
> 
> - Patch 3: fix missing descriptions and replace a wrong one. For >= v6.7.

I'm going to treat this as documentation fixes, so perfectly fine for
net but they don't need Fixes tags. Hope that's okay, and that I'm
not missing anything.

> Link: https://docs.kernel.org/networking/netlink_spec/mptcp_pm.html [1]
> Signed-off-by: Matthieu Baerts (NGI0) <matttbe@kernel.org>
> ---
> Please note that there is no urgency here: this can of course be sent to
> Linus next year!
> 
> Enjoy this holiday period!

Thank you! You too!

Re: [PATCH net 0/3] netlink: specs: mptcp: fixes for some descriptions

[Jakub Kicinski]

On Fri, 20 Dec 2024 11:54:06 -0800 Jakub Kicinski wrote:
> On Thu, 19 Dec 2024 12:45:26 +0100 Matthieu Baerts (NGI0) wrote:
> > When looking at the MPTCP PM Netlink specs rendered version [1], a few
> > small issues have been found with the descriptions, and fixed here:
> > 
> > - Patch 1: add a missing attribute for two events. For >= v5.19.
> > 
> > - Patch 2: clearly mention the attributes. For >= v6.7.
> > 
> > - Patch 3: fix missing descriptions and replace a wrong one. For >= v6.7.  
> 
> I'm going to treat this as documentation fixes, so perfectly fine for
> net but they don't need Fixes tags. Hope that's okay, and that I'm
> not missing anything.

Ah, these also need a regen since the kdoc has changed!

please run ./tools/net/ynl/ynl-regen.sh

Re: [PATCH net 0/3] netlink: specs: mptcp: fixes for some descriptions

[Matthieu Baerts]

Hi Jakub,

Thank you for the review!

On 20/12/2024 20:56, Jakub Kicinski wrote:
> On Fri, 20 Dec 2024 11:54:06 -0800 Jakub Kicinski wrote:
>> On Thu, 19 Dec 2024 12:45:26 +0100 Matthieu Baerts (NGI0) wrote:
>>> When looking at the MPTCP PM Netlink specs rendered version [1], a few
>>> small issues have been found with the descriptions, and fixed here:
>>>
>>> - Patch 1: add a missing attribute for two events. For >= v5.19.
>>>
>>> - Patch 2: clearly mention the attributes. For >= v6.7.
>>>
>>> - Patch 3: fix missing descriptions and replace a wrong one. For >= v6.7.  
>>
>> I'm going to treat this as documentation fixes, so perfectly fine for
>> net but they don't need Fixes tags. Hope that's okay, and that I'm
>> not missing anything.
> 
> Ah, these also need a regen since the kdoc has changed!
> 
> please run ./tools/net/ynl/ynl-regen.sh

Oh, sorry, I didn't know. I will fix that in a v2 without the Fixes and
cc stable.

Cheers,
Matt
-- 
Sponsored by the NGI0 Core fund.