* [PATCH net v2 0/3] netlink: specs: mptcp: fixes for some descriptions
@ 2024-12-21 11:09 Matthieu Baerts (NGI0)
2024-12-21 11:09 ` [PATCH net v2 1/3] netlink: specs: mptcp: add missing 'server-side' attr Matthieu Baerts (NGI0)
` (3 more replies)
0 siblings, 4 replies; 5+ messages in thread
From: Matthieu Baerts (NGI0) @ 2024-12-21 11:09 UTC (permalink / raw)
To: mptcp, Mat Martineau, Geliang Tang, Donald Hunter, Jakub Kicinski,
David S. Miller, Eric Dumazet, Paolo Abeni, Simon Horman,
Davide Caratti
Cc: netdev, linux-kernel, 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!
---
Changes in v2:
- Run ynl-regen.sh and removed Fixes tag. (Jakub)
- Link to v1: https://lore.kernel.org/r/20241219-net-mptcp-netlink-specs-pm-doc-fixes-v1-0-825d3b45f27b@kernel.org
---
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 ++++++++++++++++---------------
include/uapi/linux/mptcp_pm.h | 50 +++++++++++++-------------
2 files changed, 57 insertions(+), 53 deletions(-)
---
base-commit: 30b981796b94b083da8fdded7cb74cb493608760
change-id: 20241219-net-mptcp-netlink-specs-pm-doc-fixes-618a2e8f6aeb
Best regards,
--
Matthieu Baerts (NGI0) <matttbe@kernel.org>
^ permalink raw reply [flat|nested] 5+ messages in thread
* [PATCH net v2 1/3] netlink: specs: mptcp: add missing 'server-side' attr
2024-12-21 11:09 [PATCH net v2 0/3] netlink: specs: mptcp: fixes for some descriptions Matthieu Baerts (NGI0)
@ 2024-12-21 11:09 ` Matthieu Baerts (NGI0)
2024-12-21 11:09 ` [PATCH net v2 2/3] netlink: specs: mptcp: clearly mention attributes Matthieu Baerts (NGI0)
` (2 subsequent siblings)
3 siblings, 0 replies; 5+ messages in thread
From: Matthieu Baerts (NGI0) @ 2024-12-21 11:09 UTC (permalink / raw)
To: mptcp, Mat Martineau, Geliang Tang, Donald Hunter, Jakub Kicinski,
David S. Miller, Eric Dumazet, Paolo Abeni, Simon Horman,
Davide Caratti
Cc: netdev, linux-kernel, Matthieu Baerts (NGI0)
This attribute is added with the 'created' and 'established' events, but
the documentation didn't mention it.
The documentation in the UAPI header has been auto-generated by:
./tools/net/ynl/ynl-regen.sh
Reviewed-by: Geliang Tang <geliang@kernel.org>
Signed-off-by: Matthieu Baerts (NGI0) <matttbe@kernel.org>
---
Notes:
- v2: Regen YNL doc + remove Fixes tag (Jakub).
---
Documentation/netlink/specs/mptcp_pm.yaml | 6 ++++--
include/uapi/linux/mptcp_pm.h | 11 ++++++-----
2 files changed, 10 insertions(+), 7 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
diff --git a/include/uapi/linux/mptcp_pm.h b/include/uapi/linux/mptcp_pm.h
index 50589e5dd6a38a3b4158e2e4092a9b3442b8fe96..b34fd95b6f841529a8c4e8feca20450cb92f8bfc 100644
--- a/include/uapi/linux/mptcp_pm.h
+++ b/include/uapi/linux/mptcp_pm.h
@@ -13,12 +13,13 @@
* enum mptcp_event_type
* @MPTCP_EVENT_UNSPEC: unused event
* @MPTCP_EVENT_CREATED: token, family, saddr4 | saddr6, daddr4 | daddr6,
- * sport, dport 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.
+ * 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
+ * MPTCP_EVENT_ESTABLISHED is sent.
* @MPTCP_EVENT_ESTABLISHED: token, family, saddr4 | saddr6, daddr4 | daddr6,
- * sport, dport A MPTCP connection is established (can start new subflows).
+ * sport, dport, server-side A MPTCP connection is established (can start new
+ * subflows).
* @MPTCP_EVENT_CLOSED: token A MPTCP connection has stopped.
* @MPTCP_EVENT_ANNOUNCED: token, rem_id, family, daddr4 | daddr6 [, dport] A
* new address has been announced by the peer.
--
2.47.1
^ permalink raw reply related [flat|nested] 5+ messages in thread
* [PATCH net v2 2/3] netlink: specs: mptcp: clearly mention attributes
2024-12-21 11:09 [PATCH net v2 0/3] netlink: specs: mptcp: fixes for some descriptions Matthieu Baerts (NGI0)
2024-12-21 11:09 ` [PATCH net v2 1/3] netlink: specs: mptcp: add missing 'server-side' attr Matthieu Baerts (NGI0)
@ 2024-12-21 11:09 ` Matthieu Baerts (NGI0)
2024-12-21 11:09 ` [PATCH net v2 3/3] netlink: specs: mptcp: fix missing doc Matthieu Baerts (NGI0)
2024-12-27 19:30 ` [PATCH net v2 0/3] netlink: specs: mptcp: fixes for some descriptions patchwork-bot+netdevbpf
3 siblings, 0 replies; 5+ messages in thread
From: Matthieu Baerts (NGI0) @ 2024-12-21 11:09 UTC (permalink / raw)
To: mptcp, Mat Martineau, Geliang Tang, Donald Hunter, Jakub Kicinski,
David S. Miller, Eric Dumazet, Paolo Abeni, Simon Horman,
Davide Caratti
Cc: netdev, linux-kernel, 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.
The documentation in the UAPI header has been auto-generated by:
./tools/net/ynl/ynl-regen.sh
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>
---
Notes:
- v2: Regen YNL doc + remove Fixes tag (Jakub).
---
Documentation/netlink/specs/mptcp_pm.yaml | 50 ++++++++++++++---------------
include/uapi/linux/mptcp_pm.h | 53 ++++++++++++++++---------------
2 files changed, 52 insertions(+), 51 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:
-
diff --git a/include/uapi/linux/mptcp_pm.h b/include/uapi/linux/mptcp_pm.h
index b34fd95b6f841529a8c4e8feca20450cb92f8bfc..84fa8a21dfd022a266507371d67f0f00599d8429 100644
--- a/include/uapi/linux/mptcp_pm.h
+++ b/include/uapi/linux/mptcp_pm.h
@@ -12,32 +12,33 @@
/**
* enum mptcp_event_type
* @MPTCP_EVENT_UNSPEC: unused event
- * @MPTCP_EVENT_CREATED: 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
- * MPTCP_EVENT_ESTABLISHED is sent.
- * @MPTCP_EVENT_ESTABLISHED: token, family, saddr4 | saddr6, daddr4 | daddr6,
- * sport, dport, server-side A MPTCP connection is established (can start new
- * subflows).
- * @MPTCP_EVENT_CLOSED: token A MPTCP connection has stopped.
- * @MPTCP_EVENT_ANNOUNCED: token, rem_id, family, daddr4 | daddr6 [, dport] A
- * new address has been announced by the peer.
- * @MPTCP_EVENT_REMOVED: token, rem_id An address has been lost by the peer.
- * @MPTCP_EVENT_SUB_ESTABLISHED: token, family, loc_id, rem_id, saddr4 |
- * saddr6, daddr4 | daddr6, sport, dport, backup, if_idx [, error] A new
- * subflow has been established. 'error' should not be set.
- * @MPTCP_EVENT_SUB_CLOSED: token, family, loc_id, rem_id, saddr4 | saddr6,
- * daddr4 | daddr6, sport, dport, backup, if_idx [, error] A subflow has been
- * closed. An error (copy of sk_err) could be set if an error has been
- * detected for this subflow.
- * @MPTCP_EVENT_SUB_PRIORITY: token, family, loc_id, rem_id, saddr4 | saddr6,
- * daddr4 | daddr6, sport, dport, backup, if_idx [, error] The priority of a
- * subflow has changed. 'error' should not be set.
- * @MPTCP_EVENT_LISTENER_CREATED: family, sport, saddr4 | saddr6 A new PM
- * listener is created.
- * @MPTCP_EVENT_LISTENER_CLOSED: family, sport, saddr4 | saddr6 A PM listener
- * is closed.
+ * @MPTCP_EVENT_CREATED: 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.
+ * @MPTCP_EVENT_ESTABLISHED: A MPTCP connection is established (can start new
+ * subflows). Attributes: token, family, saddr4 | saddr6, daddr4 | daddr6,
+ * sport, dport, server-side.
+ * @MPTCP_EVENT_CLOSED: A MPTCP connection has stopped. Attribute: token.
+ * @MPTCP_EVENT_ANNOUNCED: A new address has been announced by the peer.
+ * Attributes: token, rem_id, family, daddr4 | daddr6 [, dport].
+ * @MPTCP_EVENT_REMOVED: An address has been lost by the peer. Attributes:
+ * token, rem_id.
+ * @MPTCP_EVENT_SUB_ESTABLISHED: 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].
+ * @MPTCP_EVENT_SUB_CLOSED: 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].
+ * @MPTCP_EVENT_SUB_PRIORITY: 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].
+ * @MPTCP_EVENT_LISTENER_CREATED: A new PM listener is created. Attributes:
+ * family, sport, saddr4 | saddr6.
+ * @MPTCP_EVENT_LISTENER_CLOSED: A PM listener is closed. Attributes: family,
+ * sport, saddr4 | saddr6.
*/
enum mptcp_event_type {
MPTCP_EVENT_UNSPEC,
--
2.47.1
^ permalink raw reply related [flat|nested] 5+ messages in thread
* [PATCH net v2 3/3] netlink: specs: mptcp: fix missing doc
2024-12-21 11:09 [PATCH net v2 0/3] netlink: specs: mptcp: fixes for some descriptions Matthieu Baerts (NGI0)
2024-12-21 11:09 ` [PATCH net v2 1/3] netlink: specs: mptcp: add missing 'server-side' attr Matthieu Baerts (NGI0)
2024-12-21 11:09 ` [PATCH net v2 2/3] netlink: specs: mptcp: clearly mention attributes Matthieu Baerts (NGI0)
@ 2024-12-21 11:09 ` Matthieu Baerts (NGI0)
2024-12-27 19:30 ` [PATCH net v2 0/3] netlink: specs: mptcp: fixes for some descriptions patchwork-bot+netdevbpf
3 siblings, 0 replies; 5+ messages in thread
From: Matthieu Baerts (NGI0) @ 2024-12-21 11:09 UTC (permalink / raw)
To: mptcp, Mat Martineau, Geliang Tang, Donald Hunter, Jakub Kicinski,
David S. Miller, Eric Dumazet, Paolo Abeni, Simon Horman,
Davide Caratti
Cc: netdev, linux-kernel, 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".
Reviewed-by: Geliang Tang <geliang@kernel.org>
Signed-off-by: Matthieu Baerts (NGI0) <matttbe@kernel.org>
---
Notes:
- v2: Removed Fixes tag (Jakub).
---
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
^ permalink raw reply related [flat|nested] 5+ messages in thread
* Re: [PATCH net v2 0/3] netlink: specs: mptcp: fixes for some descriptions
2024-12-21 11:09 [PATCH net v2 0/3] netlink: specs: mptcp: fixes for some descriptions Matthieu Baerts (NGI0)
` (2 preceding siblings ...)
2024-12-21 11:09 ` [PATCH net v2 3/3] netlink: specs: mptcp: fix missing doc Matthieu Baerts (NGI0)
@ 2024-12-27 19:30 ` patchwork-bot+netdevbpf
3 siblings, 0 replies; 5+ messages in thread
From: patchwork-bot+netdevbpf @ 2024-12-27 19:30 UTC (permalink / raw)
To: Matthieu Baerts
Cc: mptcp, martineau, geliang, donald.hunter, kuba, davem, edumazet,
pabeni, horms, dcaratti, netdev, linux-kernel
Hello:
This series was applied to netdev/net.git (main)
by Jakub Kicinski <kuba@kernel.org>:
On Sat, 21 Dec 2024 12:09:13 +0100 you 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.
>
> [...]
Here is the summary with links:
- [net,v2,1/3] netlink: specs: mptcp: add missing 'server-side' attr
https://git.kernel.org/netdev/net/c/6b830c6a023f
- [net,v2,2/3] netlink: specs: mptcp: clearly mention attributes
https://git.kernel.org/netdev/net/c/bea87657b5ee
- [net,v2,3/3] netlink: specs: mptcp: fix missing doc
https://git.kernel.org/netdev/net/c/4f363fe9f6b2
You are awesome, thank you!
--
Deet-doot-dot, I am a bot.
https://korg.docs.kernel.org/patchwork/pwbot.html
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2024-12-27 19:30 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2024-12-21 11:09 [PATCH net v2 0/3] netlink: specs: mptcp: fixes for some descriptions Matthieu Baerts (NGI0)
2024-12-21 11:09 ` [PATCH net v2 1/3] netlink: specs: mptcp: add missing 'server-side' attr Matthieu Baerts (NGI0)
2024-12-21 11:09 ` [PATCH net v2 2/3] netlink: specs: mptcp: clearly mention attributes Matthieu Baerts (NGI0)
2024-12-21 11:09 ` [PATCH net v2 3/3] netlink: specs: mptcp: fix missing doc Matthieu Baerts (NGI0)
2024-12-27 19:30 ` [PATCH net v2 0/3] netlink: specs: mptcp: fixes for some descriptions patchwork-bot+netdevbpf
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).