Skip to contentSkip to conversation

docs: document some aspects of struct sk_buff

RFC New Jakub Kicinski 1 participant 4 messages Mar 24, 2022

Subsystems (3)
lore
Share & tools
lore

Jakub Kicinski

author maintainer
#0 lore raw

v2 cover 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.

v2:
- fix type reference in patch 1
- use "payload" and "data" more consistently
- add snippet with calls

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.1
author maintainer
#1 lore raw

RFC v2 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
new file mode 100644
index 000000000000..b4a008feceb4
@@ -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
index 3a30cae8b0a5..3951071f2bb4 100644
@@ -764,6 +764,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.1
author maintainer
#2 lore raw

RFC v2 2/3 skbuff: rewrite the doc for data-only skbs

In reply to Jakub Kicinski

The 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
index ce017136ab05..1b3c45add20d 100644
@@ -96,6 +96,7 @@ Linux Networking Documentation
    sctp
    secid
    seg6-sysctl
+   skbuff
    smc-sysctl
    statistics
    strparser
Documentation/networking/skbuff.rst +6 -0
index b4a008feceb4..94681523e345 100644
@@ -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.1
author maintainer
#3 lore raw

RFC v2 3/3 skbuff: render the checksum comment to documentation

In reply to Jakub Kicinski

Long 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
index 94681523e345..5b74275a73a3 100644
@@ -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.1