doc/guides/prog_guide/mbuf_lib.rst

   1 ..  BSD LICENSE
   2     Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
   3     All rights reserved.
   4
   5     Redistribution and use in source and binary forms, with or without
   6     modification, are permitted provided that the following conditions
   7     are met:
   8
   9     * Redistributions of source code must retain the above copyright
  10     notice, this list of conditions and the following disclaimer.
  11     * Redistributions in binary form must reproduce the above copyright
  12     notice, this list of conditions and the following disclaimer in
  13     the documentation and/or other materials provided with the
  14     distribution.
  15     * Neither the name of Intel Corporation nor the names of its
  16     contributors may be used to endorse or promote products derived
  17     from this software without specific prior written permission.
  18
  19     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20     "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  22     A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  23     OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  24     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  25     LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  29     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30
  31 .. _Mbuf_Library:
  32
  33 Mbuf Library
  34 ============
  35
  36 The mbuf library provides the ability to allocate and free buffers (mbufs)
  37 that may be used by the Intel® DPDK application to store message buffers.
  38 The message buffers are stored in a mempool, using the :ref:`Mempool Library <Mempool_Library>`.
  39
  40 A rte_mbuf struct can carry network packet buffers (type is RTE_MBUF_PKT)
  41 or generic control buffers (type is RTE_MBUF_CTRL).
  42 This can be extended to other types.
  43 The rte_mbuf is kept as small as possible (one cache line if possible).
  44
  45 Design of Packet Buffers
  46 ------------------------
  47
  48 For the storage of the packet data (including protocol headers), two approaches were considered:
  49
  50 #.  Embed metadata within a single memory buffer the structure followed by a fixed size area for the packet data.
  51
  52 #.  Use separate memory buffers for the metadata structure and for the packet data.
  53
  54 The advantage of the first method is that it only needs one operation to allocate/free the whole memory representation of a packet.
  55 On the other hand, the second method is more flexible and allows
  56 the complete separation of the allocation of metadata structures from the allocation of packet data buffers.
  57
  58 The first method was chosen for the Intel® DPDK.
  59 The metadata contains control information such as message type, length,
  60 pointer to the start of the data and a pointer for additional mbuf structures allowing buffer chaining.
  61
  62 Message buffers that are used to carry network packets can handle buffer chaining
  63 where multiple buffers are required to hold the complete packet.
  64 This is the case for jumbo frames that are composed of many mbufs linked together through their pkt.next field.
  65
  66 For a newly allocated mbuf, the area at which the data begins in the message buffer is
  67 RTE_PKTMBUF_HEADROOM bytes after the beginning of the buffer, which is cache aligned.
  68 Message buffers may be used to carry control information, packets, events,
  69 and so on between different entities in the system.
  70 Message buffers may also use their data pointers to point to other message buffer data sections or other structures.
  71
  72 Figure 8 and Figure 9 show some of these scenarios.
  73
  74 .. _pg_figure_8:
  75
  76 **Figure 8. An mbuf with One Segment**
  77
  78 .. image22_png  has been replaced
  79
  80 |mbuf1|
  81
  82 .. _pg_figure_9:
  83
  84 **Figure 9. An mbuf with Three Segments**
  85
  86 .. image23_png has been replaced
  87
  88 |mbuf2|
  89
  90 The Buffer Manager implements a fairly standard set of buffer access functions to manipulate network packets.
  91
  92 Buffers Stored in Memory Pools
  93 ------------------------------
  94
  95 The Buffer Manager uses the :ref:`Mempool Library <Mempool_Library>` to allocate buffers.
  96 Therefore, it ensures that the packet header is interleaved optimally across the channels and ranks for L3 processing.
  97 An mbuf contains a field indicating the pool that it originated from.
  98 When calling rte_ctrlmbuf_free(m) or rte_pktmbuf_free(m), the mbuf returns to its original pool.
  99
 100 Constructors
 101 ------------
 102
 103 Packet and control mbuf constructors are provided by the API.
 104 The rte_pktmbuf_init() and rte_ctrlmbuf_init() functions initialize some fields in the mbuf structure that
 105 are not modified by the user once created (mbuf type, origin pool, buffer start address, and so on).
 106 This function is given as a callback function to the rte_mempool_create() function at pool creation time.
 107
 108 Allocating and Freeing mbufs
 109 ----------------------------
 110
 111 Allocating a new mbuf requires the user to specify the mempool from which the mbuf should be taken.
 112 For a packet mbuf, it contains one segment, with a length of 0.
 113 The pointer to data is initialized to have some bytes of headroom in the buffer (RTE_PKTMBUF_HEADROOM).
 114 For a control mbuf, it is initialized with data pointing to the beginning of the buffer and a length of zero.
 115
 116 Freeing a mbuf means returning it into its original mempool.
 117 The content of an mbuf is not modified when it is stored in a pool (as a free mbuf).
 118 Fields initialized by the constructor do not need to be re-initialized at mbuf allocation.
 119
 120 When freeing a packet mbuf that contains several segments, all of them are freed and returned to their original mempool.
 121
 122 Manipulating mbufs
 123 ------------------
 124
 125 This library provides some functions for manipulating the data in a packet mbuf. For instance:
 126
 127     *  Get data length
 128
 129     *  Get a pointer to the start of data
 130
 131     *  Prepend data before data
 132
 133     *   Append data after data
 134
 135     *   Remove data at the beginning of the buffer (rte_pktmbuf_adj())
 136
 137     *   Remove data at the end of the buffer (rte_pktmbuf_trim()) Refer to the *Intel® DPDK API Reference* for details.
 138
 139 Meta Information
 140 ----------------
 141
 142 Some information is retrieved by the network driver and stored in an mbuf to make processing easier.
 143 For instance, the VLAN, the RSS hash result (see :ref:`Poll Mode Driver <Poll_Mode_Driver>`)
 144 and a flag indicating that the checksum was computed by hardware.
 145
 146 An mbuf also contains the input port (where it comes from), and the number of segment mbufs in the chain.
 147
 148 For chained buffers, only the first mbuf of the chain stores this meta information.
 149
 150 Direct and Indirect Buffers
 151 ---------------------------
 152
 153 A direct buffer is a buffer that is completely separate and self-contained.
 154 An indirect buffer behaves like a direct buffer but for the fact that the data pointer it contains points to data in another direct buffer.
 155 This is useful in situations where packets need to be duplicated or fragmented,
 156 since indirect buffers provide the means to reuse the same packet data across multiple buffers.
 157
 158 A buffer becomes indirect when it is "attached" to a direct buffer using the rte_pktmbuf_attach() function.
 159 Each buffer has a reference counter field and whenever an indirect buffer is attached to the direct buffer,
 160 the reference counter on the direct buffer is incremented.
 161 Similarly, whenever the indirect buffer is detached, the reference counter on the direct buffer is decremented.
 162 If the resulting reference counter is equal to 0, the direct buffer is freed since it is no longer in use.
 163
 164 There are a few things to remember when dealing with indirect buffers.
 165 First of all, it is not possible to attach an indirect buffer to another indirect buffer.
 166 Secondly, for a buffer to become indirect, its reference counter must be equal to 1,
 167 that is, it must not be already referenced by another indirect buffer.
 168 Finally, it is not possible to reattach an indirect buffer to the direct buffer (unless it is detached first).
 169
 170 While the attach/detach operations can be invoked directly using the recommended rte_pktmbuf_attach() and rte_pktmbuf_detach() functions,
 171 it is suggested to use the higher-level rte_pktmbuf_clone() function,
 172 which takes care of the correct initialization of an indirect buffer and can clone buffers with multiple segments.
 173
 174 Since indirect buffers are not supposed to actually hold any data,
 175 the memory pool for indirect buffers should be configured to indicate the reduced memory consumption.
 176 Examples of the initialization of a memory pool for indirect buffers (as well as use case examples for indirect buffers)
 177 can be found in several of the sample applications, for example, the IPv4 Multicast sample application.
 178
 179 Debug
 180 -----
 181
 182 In debug mode (CONFIG_RTE_MBUF_DEBUG is enabled),
 183 the functions of the mbuf library perform sanity checks before any operation (such as, buffer corruption, bad type, and so on).
 184
 185 Use Cases
 186 ---------
 187
 188 All networking application should use mbufs to transport network packets.
 189
 190 .. |mbuf1| image:: img/mbuf1.svg
 191
 192 .. |mbuf2| image:: img/mbuf2.svg