net: improve and fix netlink kdoc
Subsystems (3)
Jakub Kicinski
maintainerPATCH v2 1/2 net: improve and fix netlink kdoc
Subsequent patch will render the kdoc frominclude/uapi/linux/netlink.h into Documentation.
We need to fix the warnings. While at it move
the comments on struct nlmsghdr to a proper
kdoc comment.
--- include/uapi/linux/netlink.h | 21 ++++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-)
include/uapi/linux/netlink.h +16 -5
@@ -41,12 +41,20 @@ struct sockaddr_nl {__u32 nl_groups;/* multicast groups mask */ }; +/** +* struct nlmsghdr - fixed format metadata header of Netlink messages +* @nlmsg_len: Length of message including header +* @nlmsg_type: Message content type +* @nlmsg_flags: Additional flags +* @nlmsg_seq: Sequence number +* @nlmsg_pid: Sending process port ID +*/ struct nlmsghdr { -__u32 nlmsg_len;/* Length of message including header */ -__u16 nlmsg_type;/* Message content */ -__u16 nlmsg_flags;/* Additional flags */ -__u32 nlmsg_seq;/* Sequence number */ -__u32 nlmsg_pid;/* Sending process port ID */ +__u32 nlmsg_len; +__u16 nlmsg_type; +__u16 nlmsg_flags; +__u32 nlmsg_seq; +__u32 nlmsg_pid; };/* Flags values */
@@ -337,6 +345,9 @@ enum netlink_attribute_type {* bitfield32 type (U32) * @NL_POLICY_TYPE_ATTR_MASK: mask of valid bits for unsigned integers (U64) * @NL_POLICY_TYPE_ATTR_PAD: pad attribute for 64-bit alignment +* +* @__NL_POLICY_TYPE_ATTR_MAX: number of attributes +* @NL_POLICY_TYPE_ATTR_MAX: highest attribute number */ enum netlink_policy_type_attr {NL_POLICY_TYPE_ATTR_UNSPEC ,
Signature · 1 line
2.37.2
Jakub Kicinski
maintainerPATCH v2 2/2 docs: netlink: basic introduction to Netlink
Provide a bit of a brain dump of netlink related information as documentation. Hopefully this will be useful to people trying to navigate implementing YAML based parsing in languages we won't be able to help with.
I started writing this doc while trying to figure out what it'd take to widen the applicability of YAML to good old rtnl, but the doc grew beyond that as it usually happens.
In all honesty a lot of this information is new to me as I usually follow the "copy an existing example, drink to forget" process of writing netlink user space, so reviews will be much appreciated.
--
Jon, I'm putting this in userspace-api/ I think it fits reasonably well there but please don't hesitate to suggest a better home.
I put all the code on https://github.com/kuba-moo/ynl
if anyone wants to help!
v2: - mark NLMSG_OVERRUN as unsed today
- fix spelling (Stan)
- Endpoint ID -> Port ID (Johannes)
- refocus nlmsg_pid on Port ID a bit (Johannes..)
- mention align only of attr headers
- don't talk about the end of message
- drop rare
- add the multicast section
- add buffer sizing
- add a "Advanced topics" header half way thru Generic Netlink since the doc keeps growing :)
--- Documentation/userspace-api/index.rst | 1 + Documentation/userspace-api/netlink/index.rst | 12 + Documentation/userspace-api/netlink/intro.rst | 643 ++++++++++++++++++ 3 files changed, 656 insertions(+) create mode 100644 Documentation/userspace-api/netlink/index.rst create mode 100644 Documentation/userspace-api/netlink/intro.rst
Documentation/userspace-api/index.rst +1 -0
@@ -26,6 +26,7 @@ place where this information is gathered. ioctl/index iommu media/index + netlink/index sysfs-platform_profile vduse futex2
Documentation/userspace-api/netlink/index.rst new file +12 -0
@@ -0,0 +1,12 @@ +.. SPDX-License-Identifier: BSD-3-Clause + +================ +Netlink Handbook +================ + +Netlink documentation for users. + +.. toctree:: + :maxdepth: 2 + + intro
Documentation/userspace-api/netlink/intro.rst new file +643 -0
643 lines not on this page · raw message
Signature · 1 line
2.37.2
Re: [PATCH v2 2/2] docs: netlink: basic introduction to Netlink
Quoted 13 lines · Jakub Kicinski
Provide a bit of a brain dump of netlink related information as documentation. Hopefully this will be useful to people trying to navigate implementing YAML based parsing in languages we won't be able to help with.
I started writing this doc while trying to figure out what it'd take to widen the applicability of YAML to good old rtnl, but the doc grew beyond that as it usually happens.
In all honesty a lot of this information is new to me as I usually follow the "copy an existing example, drink to forget" process of writing netlink user space, so reviews will be much appreciated.
Quoted 5 lines
Reviewed-by Jacob Keller <[email protected]>Signed-off-by Jakub Kicinski <[email protected]>--
Jon, I'm putting this in userspace-api/ I think it fits reasonably well there but please don't hesitate to suggest a better home.
That seems like a fine place for it - this is an addition that, I think, a lot of people will welcome.
A couple of nits, feel free to ignore them:
- Do you plan to add other netlink documents to that directory in the future? If not, I'd just make a netlink.rst and not bother with the directory and index.rst.
- I'm not sure that all the :c:member markup buys enough to be worth the clutter.
Regardless, should it be worth something:
Thanks for doing this; I've been meaning for years to reverse-engineer netlink and write something like this, now I don't have to :)
jon
Jakub Kicinski
maintainerRe: [PATCH v2 2/2] docs: netlink: basic introduction to Netlink
Quoted 21 lines · On Fri, 19 Aug 2022 14:54:48 -0600 Jonathan Corbet wrote:
Quoted 13 lines · Jakub Kicinski
Provide a bit of a brain dump of netlink related information as documentation. Hopefully this will be useful to people trying to navigate implementing YAML based parsing in languages we won't be able to help with.
I started writing this doc while trying to figure out what it'd take to widen the applicability of YAML to good old rtnl, but the doc grew beyond that as it usually happens.
In all honesty a lot of this information is new to me as I usually follow the "copy an existing example, drink to forget" process of writing netlink user space, so reviews will be much appreciated.
Quoted 5 lines
Reviewed-by Jacob Keller <[email protected]>Signed-off-by Jakub Kicinski <[email protected]>--
Jon, I'm putting this in userspace-api/ I think it fits reasonably well there but please don't hesitate to suggest a better home.
Quoted 8 lines
That seems like a fine place for it - this is an addition that, I think, a lot of people will welcome.
A couple of nits, feel free to ignore them:
- Do you plan to add other netlink documents to that directory in the future? If not, I'd just make a
netlink.rstand not bother with the directory andindex.rst.
I do - I'm working on creating protocol specifications (what operations and attributes family has) in YAML, and at the very least I'll have to document how to use those specs. And there needs to be some documentation for the attribute formats.
I've also enlisted help of Peter of the pyroute2 fame to write a Sphinx plugin which would render the documentation from the YAML specs into this directory...
Quoted 2 lines
- I'm not sure that all the :c:member markup buys enough to be worth the clutter.
Right :( I could swear it worked for me in the sk_buff docs, here it does not actually link to the documentation of the type :S I do like the consistent formatting tho, so I think I'll keep it either way.
Quoted 6 lines
Regardless, should it be worth something:
Acked-by Jonathan Corbet <[email protected]>Thanks for doing this; I've been meaning for years to reverse-engineer netlink and write something like this, now I don't have to :)
Thank you! :)
This series was applied to netdev/net-next.git (master) by Jakub Kicinski <[email protected]>:
Hello:
This series was applied to netdev/net-next.git (master) by Jakub Kicinski <[email protected]>:
Quoted 9 lines · On Fri, 19 Aug 2022 13:02:20 -0700 you wrote:
Subsequent patch will render the kdoc from
include/uapi/linux/netlink.hinto Documentation.
We need to fix the warnings. While at it move
the comments on struct nlmsghdr to a proper
kdoc comment.Signed-off-by Jakub Kicinski <[email protected]>[...]
Here is the summary with links:
- [v2,1/2] net: improve and fix netlink kdoc
https://git.kernel.org/netdev/net-next/c/30b6055428a9 - [v2,2/2] docs: netlink: basic introduction to Netlink https://git.kernel.org/netdev/net-next/c/510156a7f0cb
You are awesome, thank you!
Signature · 2 lines
Deet-doot-dot, I am a bot. https://korg.docs.kernel.org/patchwork/pwbot.html