mbuf: remove control mbuf
[dpdk.git] / 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 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 generally carries network packet buffers, but it can actually
41 be any data (control data, events, ...).
42 The rte_mbuf header structure is kept as small as possible and currently uses
43 just two cache lines, with the most frequently used fields being on the first
44 of the two cache lines.
45
46 Design of Packet Buffers
47 ------------------------
48
49 For the storage of the packet data (including protocol headers), two approaches were considered:
50
51 #.  Embed metadata within a single memory buffer the structure followed by a fixed size area for the packet data.
52
53 #.  Use separate memory buffers for the metadata structure and for the packet data.
54
55 The advantage of the first method is that it only needs one operation to allocate/free the whole memory representation of a packet.
56 On the other hand, the second method is more flexible and allows
57 the complete separation of the allocation of metadata structures from the allocation of packet data buffers.
58
59 The first method was chosen for the DPDK.
60 The metadata contains control information such as message type, length,
61 offset to the start of the data and a pointer for additional mbuf structures allowing buffer chaining.
62
63 Message buffers that are used to carry network packets can handle buffer chaining
64 where multiple buffers are required to hold the complete packet.
65 This is the case for jumbo frames that are composed of many mbufs linked together through their next field.
66
67 For a newly allocated mbuf, the area at which the data begins in the message buffer is
68 RTE_PKTMBUF_HEADROOM bytes after the beginning of the buffer, which is cache aligned.
69 Message buffers may be used to carry control information, packets, events,
70 and so on between different entities in the system.
71 Message buffers may also use their buffer pointers to point to other message buffer data sections or other structures.
72
73 :numref:`figure_mbuf1` and :numref:`figure_mbuf2` show some of these scenarios.
74
75 .. _figure_mbuf1:
76
77 .. figure:: img/mbuf1.*
78
79    An mbuf with One Segment
80
81
82 .. _figure_mbuf2:
83
84 .. figure:: img/mbuf2.*
85
86    An mbuf with Three Segments
87
88
89 The Buffer Manager implements a fairly standard set of buffer access functions to manipulate network packets.
90
91 Buffers Stored in Memory Pools
92 ------------------------------
93
94 The Buffer Manager uses the :ref:`Mempool Library <Mempool_Library>` to allocate buffers.
95 Therefore, it ensures that the packet header is interleaved optimally across the channels and ranks for L3 processing.
96 An mbuf contains a field indicating the pool that it originated from.
97 When calling rte_pktmbuf_free(m), the mbuf returns to its original pool.
98
99 Constructors
100 ------------
101
102 Packet mbuf constructors are provided by the API.
103 The rte_pktmbuf_init() function initializes some fields in the mbuf structure that
104 are not modified by the user once created (mbuf type, origin pool, buffer start address, and so on).
105 This function is given as a callback function to the rte_mempool_create() function at pool creation time.
106
107 Allocating and Freeing mbufs
108 ----------------------------
109
110 Allocating a new mbuf requires the user to specify the mempool from which the mbuf should be taken.
111 For any newly-allocated mbuf, it contains one segment, with a length of 0.
112 The offset to data is initialized to have some bytes of headroom in the buffer (RTE_PKTMBUF_HEADROOM).
113
114 Freeing a mbuf means returning it into its original mempool.
115 The content of an mbuf is not modified when it is stored in a pool (as a free mbuf).
116 Fields initialized by the constructor do not need to be re-initialized at mbuf allocation.
117
118 When freeing a packet mbuf that contains several segments, all of them are freed and returned to their original mempool.
119
120 Manipulating mbufs
121 ------------------
122
123 This library provides some functions for manipulating the data in a packet mbuf. For instance:
124
125     *  Get data length
126
127     *  Get a pointer to the start of data
128
129     *  Prepend data before data
130
131     *   Append data after data
132
133     *   Remove data at the beginning of the buffer (rte_pktmbuf_adj())
134
135     *   Remove data at the end of the buffer (rte_pktmbuf_trim()) Refer to the *DPDK API Reference* for details.
136
137 Meta Information
138 ----------------
139
140 Some information is retrieved by the network driver and stored in an mbuf to make processing easier.
141 For instance, the VLAN, the RSS hash result (see :ref:`Poll Mode Driver <Poll_Mode_Driver>`)
142 and a flag indicating that the checksum was computed by hardware.
143
144 An mbuf also contains the input port (where it comes from), and the number of segment mbufs in the chain.
145
146 For chained buffers, only the first mbuf of the chain stores this meta information.
147
148 For instance, this is the case on RX side for the IEEE1588 packet
149 timestamp mechanism, the VLAN tagging and the IP checksum computation.
150
151 On TX side, it is also possible for an application to delegate some
152 processing to the hardware if it supports it. For instance, the
153 PKT_TX_IP_CKSUM flag allows to offload the computation of the IPv4
154 checksum.
155
156 The following examples explain how to configure different TX offloads on
157 a vxlan-encapsulated tcp packet:
158 ``out_eth/out_ip/out_udp/vxlan/in_eth/in_ip/in_tcp/payload``
159
160 - calculate checksum of out_ip::
161
162     mb->l2_len = len(out_eth)
163     mb->l3_len = len(out_ip)
164     mb->ol_flags |= PKT_TX_IPV4 | PKT_TX_IP_CSUM
165     set out_ip checksum to 0 in the packet
166
167   This is supported on hardware advertising DEV_TX_OFFLOAD_IPV4_CKSUM.
168
169 - calculate checksum of out_ip and out_udp::
170
171     mb->l2_len = len(out_eth)
172     mb->l3_len = len(out_ip)
173     mb->ol_flags |= PKT_TX_IPV4 | PKT_TX_IP_CSUM | PKT_TX_UDP_CKSUM
174     set out_ip checksum to 0 in the packet
175     set out_udp checksum to pseudo header using rte_ipv4_phdr_cksum()
176
177   This is supported on hardware advertising DEV_TX_OFFLOAD_IPV4_CKSUM
178   and DEV_TX_OFFLOAD_UDP_CKSUM.
179
180 - calculate checksum of in_ip::
181
182     mb->l2_len = len(out_eth + out_ip + out_udp + vxlan + in_eth)
183     mb->l3_len = len(in_ip)
184     mb->ol_flags |= PKT_TX_IPV4 | PKT_TX_IP_CSUM
185     set in_ip checksum to 0 in the packet
186
187   This is similar to case 1), but l2_len is different. It is supported
188   on hardware advertising DEV_TX_OFFLOAD_IPV4_CKSUM.
189   Note that it can only work if outer L4 checksum is 0.
190
191 - calculate checksum of in_ip and in_tcp::
192
193     mb->l2_len = len(out_eth + out_ip + out_udp + vxlan + in_eth)
194     mb->l3_len = len(in_ip)
195     mb->ol_flags |= PKT_TX_IPV4 | PKT_TX_IP_CSUM | PKT_TX_TCP_CKSUM
196     set in_ip checksum to 0 in the packet
197     set in_tcp checksum to pseudo header using rte_ipv4_phdr_cksum()
198
199   This is similar to case 2), but l2_len is different. It is supported
200   on hardware advertising DEV_TX_OFFLOAD_IPV4_CKSUM and
201   DEV_TX_OFFLOAD_TCP_CKSUM.
202   Note that it can only work if outer L4 checksum is 0.
203
204 - segment inner TCP::
205
206     mb->l2_len = len(out_eth + out_ip + out_udp + vxlan + in_eth)
207     mb->l3_len = len(in_ip)
208     mb->l4_len = len(in_tcp)
209     mb->ol_flags |= PKT_TX_IPV4 | PKT_TX_IP_CKSUM | PKT_TX_TCP_CKSUM |
210       PKT_TX_TCP_SEG;
211     set in_ip checksum to 0 in the packet
212     set in_tcp checksum to pseudo header without including the IP
213       payload length using rte_ipv4_phdr_cksum()
214
215   This is supported on hardware advertising DEV_TX_OFFLOAD_TCP_TSO.
216   Note that it can only work if outer L4 checksum is 0.
217
218 - calculate checksum of out_ip, in_ip, in_tcp::
219
220     mb->outer_l2_len = len(out_eth)
221     mb->outer_l3_len = len(out_ip)
222     mb->l2_len = len(out_udp + vxlan + in_eth)
223     mb->l3_len = len(in_ip)
224     mb->ol_flags |= PKT_TX_OUTER_IPV4 | PKT_TX_OUTER_IP_CKSUM  | \
225       PKT_TX_IP_CKSUM |  PKT_TX_TCP_CKSUM;
226     set out_ip checksum to 0 in the packet
227     set in_ip checksum to 0 in the packet
228     set in_tcp checksum to pseudo header using rte_ipv4_phdr_cksum()
229
230   This is supported on hardware advertising DEV_TX_OFFLOAD_IPV4_CKSUM,
231   DEV_TX_OFFLOAD_UDP_CKSUM and DEV_TX_OFFLOAD_OUTER_IPV4_CKSUM.
232
233 The list of flags and their precise meaning is described in the mbuf API
234 documentation (rte_mbuf.h). Also refer to the testpmd source code
235 (specifically the csumonly.c file) for details.
236
237 .. _direct_indirect_buffer:
238
239 Direct and Indirect Buffers
240 ---------------------------
241
242 A direct buffer is a buffer that is completely separate and self-contained.
243 An indirect buffer behaves like a direct buffer but for the fact that the buffer pointer and
244 data offset in it refer to data in another direct buffer.
245 This is useful in situations where packets need to be duplicated or fragmented,
246 since indirect buffers provide the means to reuse the same packet data across multiple buffers.
247
248 A buffer becomes indirect when it is "attached" to a direct buffer using the rte_pktmbuf_attach() function.
249 Each buffer has a reference counter field and whenever an indirect buffer is attached to the direct buffer,
250 the reference counter on the direct buffer is incremented.
251 Similarly, whenever the indirect buffer is detached, the reference counter on the direct buffer is decremented.
252 If the resulting reference counter is equal to 0, the direct buffer is freed since it is no longer in use.
253
254 There are a few things to remember when dealing with indirect buffers.
255 First of all, an indirect buffer is never attached to another indirect buffer.
256 Attempting to attach buffer A to indirect buffer B that is attached to C, makes rte_pktmbuf_attach() automatically attach A to C, effectively cloning B.
257 Secondly, for a buffer to become indirect, its reference counter must be equal to 1,
258 that is, it must not be already referenced by another indirect buffer.
259 Finally, it is not possible to reattach an indirect buffer to the direct buffer (unless it is detached first).
260
261 While the attach/detach operations can be invoked directly using the recommended rte_pktmbuf_attach() and rte_pktmbuf_detach() functions,
262 it is suggested to use the higher-level rte_pktmbuf_clone() function,
263 which takes care of the correct initialization of an indirect buffer and can clone buffers with multiple segments.
264
265 Since indirect buffers are not supposed to actually hold any data,
266 the memory pool for indirect buffers should be configured to indicate the reduced memory consumption.
267 Examples of the initialization of a memory pool for indirect buffers (as well as use case examples for indirect buffers)
268 can be found in several of the sample applications, for example, the IPv4 Multicast sample application.
269
270 Debug
271 -----
272
273 In debug mode (CONFIG_RTE_MBUF_DEBUG is enabled),
274 the functions of the mbuf library perform sanity checks before any operation (such as, buffer corruption, bad type, and so on).
275
276 Use Cases
277 ---------
278
279 All networking application should use mbufs to transport network packets.