Commit ddccc9ef authored by Jakub Kicinski's avatar Jakub Kicinski
Browse files

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.

Reviewed-by: default avatarDavid Ahern <dsahern@kernel.org>
Signed-off-by: default avatarJakub Kicinski <kuba@kernel.org>
parent be76955d

Documentation/networking/skbuff.rst

0 → 100644
+25 −0
Original line number Diff line number Diff line 
.. 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
Original line number Diff line number Diff line
@@ -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