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

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

[Jiri Pirko]

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(+)

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
-- 
2.41.0

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

[Jakub Kicinski]

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?

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

[Jiri Pirko]

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.

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

[Jakub Kicinski]

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.
-- 
pw-bot: reject

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

[Jiri Pirko]

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

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

[Jakub Kicinski]

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.

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

[Jiri Pirko]

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.