diff mbox series

[net-next] docs: netlink: add NLMSG_DONE message format for doit actions

Message ID 20231128151916.780588-1-jiri@resnulli.us (mailing list archive)
State Superseded
Delegated to: Netdev Maintainers
Headers show
Series [net-next] docs: netlink: add NLMSG_DONE message format for doit actions | expand

Checks

Context Check Description
netdev/series_format success Single patches do not need cover letters
netdev/codegen success Generated files up to date
netdev/tree_selection success Clearly marked for net-next
netdev/fixes_present success Fixes tag not required for -next series
netdev/header_inline success No static functions without inline keyword in header files
netdev/build_32bit success Errors and warnings before: 8 this patch: 8
netdev/cc_maintainers warning 1 maintainers not CCed: linux-doc@vger.kernel.org
netdev/build_clang success Errors and warnings before: 8 this patch: 8
netdev/verify_signedoff success Signed-off-by tag matches author and committer
netdev/deprecated_api success None detected
netdev/check_selftest success No net selftest shell script
netdev/verify_fixes success No Fixes tag
netdev/build_allmodconfig_warn success Errors and warnings before: 8 this patch: 8
netdev/checkpatch success total: 0 errors, 0 warnings, 0 checks, 13 lines checked
netdev/build_clang_rust success No Rust files in patch. Skipping build
netdev/kdoc success Errors and warnings before: 0 this patch: 0
netdev/source_inline success Was 0 now: 0

Commit Message

Jiri Pirko Nov. 28, 2023, 3:19 p.m. UTC 
From: Jiri Pirko <jiri@nvidia.com>

In case NLMSG_DONE message is sent as a reply to doit action, multiple
kernel implementation do not send anything else than struct nlmsghdr.
Add this note to the Netlink intro documentation.

Signed-off-by: Jiri Pirko <jiri@nvidia.com>
---
 Documentation/userspace-api/netlink/intro.rst | 7 +++++++
 1 file changed, 7 insertions(+)

Comments

Jakub Kicinski Nov. 28, 2023, 3:30 p.m. UTC | #1 
On Tue, 28 Nov 2023 16:19:16 +0100 Jiri Pirko wrote:
> From: Jiri Pirko <jiri@nvidia.com>
> 
> In case NLMSG_DONE message is sent as a reply to doit action, multiple
> kernel implementation do not send anything else than struct nlmsghdr.
> Add this note to the Netlink intro documentation.

You mean when the reply has F_MULTI set, correct?
Jiri Pirko Nov. 29, 2023, 2:46 p.m. UTC | #2 
Tue, Nov 28, 2023 at 04:30:59PM CET, kuba@kernel.org wrote:
>On Tue, 28 Nov 2023 16:19:16 +0100 Jiri Pirko wrote:
>> From: Jiri Pirko <jiri@nvidia.com>
>> 
>> In case NLMSG_DONE message is sent as a reply to doit action, multiple
>> kernel implementation do not send anything else than struct nlmsghdr.
>> Add this note to the Netlink intro documentation.
>
>You mean when the reply has F_MULTI set, correct?

Well, that would be ideal. However, that flag is parallel to NLMSG_DONE.
I see that at least drivers/connector/connector.c does not set this flag
when sending NLMSG_DONE type.
Jakub Kicinski Nov. 29, 2023, 3:16 p.m. UTC | #3 
On Wed, 29 Nov 2023 15:46:15 +0100 Jiri Pirko wrote:
> >> In case NLMSG_DONE message is sent as a reply to doit action, multiple
> >> kernel implementation do not send anything else than struct nlmsghdr.
> >> Add this note to the Netlink intro documentation.  
> >
> >You mean when the reply has F_MULTI set, correct?  
> 
> Well, that would be ideal. However, that flag is parallel to NLMSG_DONE.
> I see that at least drivers/connector/connector.c does not set this flag
> when sending NLMSG_DONE type.

connector is a really bad example, the doc would have to say "some
families use NLMSG_DONE as an actual message type which may have pretty
much anything attached to it". It's not worth it, sorry.
Jiri Pirko Nov. 30, 2023, 1:30 p.m. UTC | #4 
Wed, Nov 29, 2023 at 04:16:56PM CET, kuba@kernel.org wrote:
>On Wed, 29 Nov 2023 15:46:15 +0100 Jiri Pirko wrote:
>> >> In case NLMSG_DONE message is sent as a reply to doit action, multiple
>> >> kernel implementation do not send anything else than struct nlmsghdr.
>> >> Add this note to the Netlink intro documentation.  
>> >
>> >You mean when the reply has F_MULTI set, correct?  
>> 
>> Well, that would be ideal. However, that flag is parallel to NLMSG_DONE.
>> I see that at least drivers/connector/connector.c does not set this flag
>> when sending NLMSG_DONE type.
>
>connector is a really bad example, the doc would have to say "some
>families use NLMSG_DONE as an actual message type which may have pretty
>much anything attached to it". It's not worth it, sorry.

The existing documentation confuses uapi users (I have sample).
They expect error with NLMSG_DONE.


>-- 
>pw-bot: reject
Jakub Kicinski Nov. 30, 2023, 5:39 p.m. UTC | #5 
On Thu, 30 Nov 2023 14:30:36 +0100 Jiri Pirko wrote:
> >connector is a really bad example, the doc would have to say "some
> >families use NLMSG_DONE as an actual message type which may have pretty
> >much anything attached to it". It's not worth it, sorry.  
> 
> The existing documentation confuses uapi users (I have sample).
> They expect error with NLMSG_DONE.

I hate this so much.

How about we say:

  Note that some families may issue custom NLMSG_DONE messages,
  in which case the payload is implementation-specific.
Jiri Pirko Dec. 1, 2023, 7:51 a.m. UTC | #6 
Thu, Nov 30, 2023 at 06:39:39PM CET, kuba@kernel.org wrote:
>On Thu, 30 Nov 2023 14:30:36 +0100 Jiri Pirko wrote:
>> >connector is a really bad example, the doc would have to say "some
>> >families use NLMSG_DONE as an actual message type which may have pretty
>> >much anything attached to it". It's not worth it, sorry.  
>> 
>> The existing documentation confuses uapi users (I have sample).
>> They expect error with NLMSG_DONE.
>
>I hate this so much.

Unfortunatelly, Netlink has a lot of burden of misuse...


>
>How about we say:
>
>  Note that some families may issue custom NLMSG_DONE messages,
>  in which case the payload is implementation-specific.

I'm fine with that. Will send v2.
diff mbox series

Patch

diff --git a/Documentation/userspace-api/netlink/intro.rst b/Documentation/userspace-api/netlink/intro.rst
index 7b1d401210ef..92e19bf49e9d 100644
--- a/Documentation/userspace-api/netlink/intro.rst
+++ b/Documentation/userspace-api/netlink/intro.rst
@@ -234,6 +234,13 @@  ACK attributes may be present::
   | ** optionally extended ACK                 |
   ----------------------------------------------
 
+If ``NLMSG_DONE`` is sent as a reply to ``do`` action request, the error
+and extended ACK may be omitted::
+
+  ----------------------------------------------
+  | struct nlmsghdr - response header          |
+  ----------------------------------------------
+
 .. _res_fam:
 
 Resolving the Family ID