Skip to content

Commit

Permalink
skbuff: add a basic intro doc
Browse files Browse the repository at this point in the history
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.

Reviewed-by: David Ahern <dsahern@kernel.org>
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
  • Loading branch information
Jakub Kicinski committed May 11, 2022
1 parent be76955 commit ddccc9e
Show file tree
Hide file tree
Showing 2 changed files with 65 additions and 0 deletions.
25 changes: 25 additions & 0 deletions Documentation/networking/skbuff.rst
Original file line number Diff line number Diff line change
@@ -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).
40 changes: 40 additions & 0 deletions include/linux/skbuff.h
Original file line number Diff line number Diff line change
Expand Up @@ -800,6 +800,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
Expand Down

0 comments on commit ddccc9e

Please sign in to comment.