docs: document some aspects of struct sk_buff
Subsystems (3)
Jakub Kicinski
maintainercover docs: document some aspects of struct sk_buff
This small set creates a place to render sk_buff documentation, documents one random thing (data-only skbs) and converts the big checksum comment to kdoc.
RFC v2 (no changes since then):
- fix type reference in patch 1
- use "payload" and "data" more consistently
- add snippet with calls
https://lore.kernel.org/r/[email protected]/
RFC v1:
https://lore.kernel.org/all/[email protected]/
Jakub Kicinski (3):
skbuff: add a basic intro doc
skbuff: rewrite the doc for data-only skbs
skbuff: render the checksum comment to documentation
Documentation/networking/index.rst | 1 + Documentation/networking/skbuff.rst | 37 ++++ include/linux/skbuff.h | 301 ++++++++++++++++++---------- 3 files changed, 232 insertions(+), 107 deletions(-) create mode 100644 Documentation/networking/skbuff.rst
Signature · 1 line
2.34.3
Jakub Kicinski
maintainerPATCH 1/3 skbuff: add a basic intro doc
Add basic skb documentation. It's mostly an intro to the subsequent patches - it would looks strange if we documented advanced topics without covering the basics in any way.
--- Documentation/networking/skbuff.rst | 25 ++++++++++++++++++ include/linux/skbuff.h | 40 +++++++++++++++++++++++++++++ 2 files changed, 65 insertions(+) create mode 100644 Documentation/networking/skbuff.rst
Documentation/networking/skbuff.rst new file +25 -0
@@ -0,0 +1,25 @@ +.. SPDX-License-Identifier: GPL-2.0 + +struct sk_buff +============== + +:c:type:`sk_buff` is the main networking structure representing +a packet. + +Basic sk_buff geometry +---------------------- + +.. kernel-doc:: include/linux/skbuff.h + :doc: Basic sk_buff geometry + +Shared skbs and skb clones +-------------------------- + +:c:member:`sk_buff.users` is a simple refcount allowing multiple entities +to keep a struct sk_buff alive. skbs with a ``sk_buff.users != 1`` are referred +to as shared skbs (see skb_shared()). + +skb_clone() allows for fast duplication of skbs. None of the data buffers +get copied, but caller gets a new metadata struct (struct sk_buff). +&skb_shared_info.refcount indicates the number of skbs pointing at the same +packet data (i.e. clones).
include/linux/skbuff.h +40 -0
@@ -787,6 +787,46 @@ typedef unsigned int sk_buff_data_t;typedef unsigned char *sk_buff_data_t ;#endif +/** +* DOC: Basic sk_buff geometry +* +* struct sk_buff itself is a metadata structure and does not hold any packet +* data. All the data is held in associated buffers. +* +* &sk_buff.head points to the main "head" buffer. The head buffer is divided +* into two parts: +* +* - data buffer, containing headers and sometimes payload; +* this is the part of the skb operated on by the common helpers +* such as skb_put() or skb_pull(); +* - shared info (struct skb_shared_info) which holds an array of pointers +* to read-only data in the (page, offset, length) format. +* +* Optionally &skb_shared_info.frag_list may point to another skb. +* +* Basic diagram may look like this:: +* +* --------------- +* | sk_buff | +* --------------- +* ,--------------------------- + head +* / ,----------------- + data +* / / ,----------- + tail +* | | | , + end +* | | | | +* v v v v +* ----------------------------------------------- +* | headroom | data | tailroom | skb_shared_info | +* ----------------------------------------------- +* + [page frag] +* + [page frag] +* + [page frag] +* + [page frag] --------- +* + frag_list --> | sk_buff | +* --------- +* +*/ +/** * struct sk_buff - socket buffer * @next: Next buffer in list
Signature · 1 line
2.34.3
Jakub Kicinski
maintainerPATCH 2/3 skbuff: rewrite the doc for data-only skbs
In reply to Jakub KicinskiThe comment about shinfo->dataref split is really unhelpful, at least to me. Rewrite it and render it to skb documentation.
--- Documentation/networking/index.rst | 1 + Documentation/networking/skbuff.rst | 6 +++++ include/linux/skbuff.h | 42 ++++++++++++++++++++--------- 3 files changed, 37 insertions(+), 12 deletions(-)
Documentation/networking/index.rst +1 -0
@@ -97,6 +97,7 @@ Refer to :ref:`netdev-FAQ` for a guide on netdev development process specifics. sctp secid seg6-sysctl + skbuff smc-sysctl statistics strparser
Documentation/networking/skbuff.rst +6 -0
@@ -23,3 +23,9 @@ skb_clone() allows for fast duplication of skbs. None of the data buffers get copied, but caller gets a new metadata struct (struct sk_buff). &skb_shared_info.refcount indicates the number of skbs pointing at the same packet data (i.e. clones). + +dataref and headerless skbs +--------------------------- + +.. kernel-doc:: include/linux/skbuff.h + :doc: dataref and headerless skbs
include/linux/skbuff.h +30 -12
54 lines not on this page · raw message
Signature · 1 line
2.34.3
Jakub Kicinski
maintainerPATCH 3/3 skbuff: render the checksum comment to documentation
In reply to Jakub KicinskiLong time ago Tom added a giant comment to skbuff.h explaining checksums. Now that we have a place in Documentation for skbuff docs we should render it. Sprinkle some markup while at it.
--- Documentation/networking/skbuff.rst | 6 + include/linux/skbuff.h | 219 ++++++++++++++++------------ 2 files changed, 130 insertions(+), 95 deletions(-)
Documentation/networking/skbuff.rst +6 -0
@@ -29,3 +29,9 @@ dataref and headerless skbs .. kernel-doc:: include/linux/skbuff.h :doc: dataref and headerless skbs + +Checksum information +-------------------- + +.. kernel-doc:: include/linux/skbuff.h + :doc: skb checksums
include/linux/skbuff.h +124 -95
291 lines not on this page · raw message
Signature · 1 line
2.34.3
Quoted 18 lines · Jakub Kicinski
This small set creates a place to render
sk_buffdocumentation, documents one random thing (data-only skbs) and converts the big checksum comment to kdoc.RFC v2 (no changes since then):
- fix type reference in patch 1
- use "payload" and "data" more consistently
- add snippet with calls
https://lore.kernel.org/r/[email protected]/RFC v1:
https://lore.kernel.org/all/[email protected]/Jakub Kicinski (3):
skbuff: add a basic intro doc
skbuff: rewrite the doc for data-only skbs
skbuff: render the checksum comment to documentation
Quoted 6 lines
Documentation/networking/index.rst | 1 + Documentation/networking/skbuff.rst | 37 ++++ include/linux/skbuff.h | 301 ++++++++++++++++++---------- 3 files changed, 232 insertions(+), 107 deletions(-) create mode 100644 Documentation/networking/skbuff.rst
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 11 lines · On Mon, 9 May 2022 09:04:53 -0700 you wrote:
This small set creates a place to render
sk_buffdocumentation, documents one random thing (data-only skbs) and converts the big checksum comment to kdoc.RFC v2 (no changes since then):
- fix type reference in patch 1
- use "payload" and "data" more consistently
- add snippet with calls
https://lore.kernel.org/r/[email protected]/[...]
Here is the summary with links:
- [net-next,1/3] skbuff: add a basic intro doc
https://git.kernel.org/netdev/net-next/c/ddccc9ef5599 - [net-next,2/3] skbuff: rewrite the doc for data-only skbs https://git.kernel.org/netdev/net-next/c/9ec7ea146208 - [net-next,3/3] skbuff: render the checksum comment to documentation https://git.kernel.org/netdev/net-next/c/9facd94114b5
You are awesome, thank you!
Signature · 2 lines
Deet-doot-dot, I am a bot. https://korg.docs.kernel.org/patchwork/pwbot.html