1 .. SPDX-License-Identifier: BSD-3-Clause
2 Copyright(c) 2010-2014 Intel Corporation.
9 The mbuf library provides the ability to allocate and free buffers (mbufs)
10 that may be used by the DPDK application to store message buffers.
11 The message buffers are stored in a mempool, using the :ref:`Mempool Library <Mempool_Library>`.
13 A rte_mbuf struct can carry network packet buffers
14 or generic control buffers (indicated by the CTRL_MBUF_FLAG).
15 This can be extended to other types.
16 The rte_mbuf header structure is kept as small as possible and currently uses
17 just two cache lines, with the most frequently used fields being on the first
18 of the two cache lines.
20 Design of Packet Buffers
21 ------------------------
23 For the storage of the packet data (including protocol headers), two approaches were considered:
25 #. Embed metadata within a single memory buffer the structure followed by a fixed size area for the packet data.
27 #. Use separate memory buffers for the metadata structure and for the packet data.
29 The advantage of the first method is that it only needs one operation to allocate/free the whole memory representation of a packet.
30 On the other hand, the second method is more flexible and allows
31 the complete separation of the allocation of metadata structures from the allocation of packet data buffers.
33 The first method was chosen for the DPDK.
34 The metadata contains control information such as message type, length,
35 offset to the start of the data and a pointer for additional mbuf structures allowing buffer chaining.
37 Message buffers that are used to carry network packets can handle buffer chaining
38 where multiple buffers are required to hold the complete packet.
39 This is the case for jumbo frames that are composed of many mbufs linked together through their next field.
41 For a newly allocated mbuf, the area at which the data begins in the message buffer is
42 RTE_PKTMBUF_HEADROOM bytes after the beginning of the buffer, which is cache aligned.
43 Message buffers may be used to carry control information, packets, events,
44 and so on between different entities in the system.
45 Message buffers may also use their buffer pointers to point to other message buffer data sections or other structures.
47 :numref:`figure_mbuf1` and :numref:`figure_mbuf2` show some of these scenarios.
51 .. figure:: img/mbuf1.*
53 An mbuf with One Segment
58 .. figure:: img/mbuf2.*
60 An mbuf with Three Segments
63 The Buffer Manager implements a fairly standard set of buffer access functions to manipulate network packets.
65 Buffers Stored in Memory Pools
66 ------------------------------
68 The Buffer Manager uses the :ref:`Mempool Library <Mempool_Library>` to allocate buffers.
69 Therefore, it ensures that the packet header is interleaved optimally across the channels and ranks for L3 processing.
70 An mbuf contains a field indicating the pool that it originated from.
71 When calling rte_ctrlmbuf_free(m) or rte_pktmbuf_free(m), the mbuf returns to its original pool.
76 Packet and control mbuf constructors are provided by the API.
77 The rte_pktmbuf_init() and rte_ctrlmbuf_init() functions initialize some fields in the mbuf structure that
78 are not modified by the user once created (mbuf type, origin pool, buffer start address, and so on).
79 This function is given as a callback function to the rte_mempool_create() function at pool creation time.
81 Allocating and Freeing mbufs
82 ----------------------------
84 Allocating a new mbuf requires the user to specify the mempool from which the mbuf should be taken.
85 For any newly-allocated mbuf, it contains one segment, with a length of 0.
86 The offset to data is initialized to have some bytes of headroom in the buffer (RTE_PKTMBUF_HEADROOM).
88 Freeing a mbuf means returning it into its original mempool.
89 The content of an mbuf is not modified when it is stored in a pool (as a free mbuf).
90 Fields initialized by the constructor do not need to be re-initialized at mbuf allocation.
92 When freeing a packet mbuf that contains several segments, all of them are freed and returned to their original mempool.
97 This library provides some functions for manipulating the data in a packet mbuf. For instance:
101 * Get a pointer to the start of data
103 * Prepend data before data
105 * Append data after data
107 * Remove data at the beginning of the buffer (rte_pktmbuf_adj())
109 * Remove data at the end of the buffer (rte_pktmbuf_trim()) Refer to the *DPDK API Reference* for details.
114 Some information is retrieved by the network driver and stored in an mbuf to make processing easier.
115 For instance, the VLAN, the RSS hash result (see :ref:`Poll Mode Driver <Poll_Mode_Driver>`)
116 and a flag indicating that the checksum was computed by hardware.
118 An mbuf also contains the input port (where it comes from), and the number of segment mbufs in the chain.
120 For chained buffers, only the first mbuf of the chain stores this meta information.
122 For instance, this is the case on RX side for the IEEE1588 packet
123 timestamp mechanism, the VLAN tagging and the IP checksum computation.
125 On TX side, it is also possible for an application to delegate some
126 processing to the hardware if it supports it. For instance, the
127 PKT_TX_IP_CKSUM flag allows to offload the computation of the IPv4
130 The following examples explain how to configure different TX offloads on
131 a vxlan-encapsulated tcp packet:
132 ``out_eth/out_ip/out_udp/vxlan/in_eth/in_ip/in_tcp/payload``
134 - calculate checksum of out_ip::
136 mb->l2_len = len(out_eth)
137 mb->l3_len = len(out_ip)
138 mb->ol_flags |= PKT_TX_IPV4 | PKT_TX_IP_CSUM
139 set out_ip checksum to 0 in the packet
141 This is supported on hardware advertising DEV_TX_OFFLOAD_IPV4_CKSUM.
143 - calculate checksum of out_ip and out_udp::
145 mb->l2_len = len(out_eth)
146 mb->l3_len = len(out_ip)
147 mb->ol_flags |= PKT_TX_IPV4 | PKT_TX_IP_CSUM | PKT_TX_UDP_CKSUM
148 set out_ip checksum to 0 in the packet
149 set out_udp checksum to pseudo header using rte_ipv4_phdr_cksum()
151 This is supported on hardware advertising DEV_TX_OFFLOAD_IPV4_CKSUM
152 and DEV_TX_OFFLOAD_UDP_CKSUM.
154 - calculate checksum of in_ip::
156 mb->l2_len = len(out_eth + out_ip + out_udp + vxlan + in_eth)
157 mb->l3_len = len(in_ip)
158 mb->ol_flags |= PKT_TX_IPV4 | PKT_TX_IP_CSUM
159 set in_ip checksum to 0 in the packet
161 This is similar to case 1), but l2_len is different. It is supported
162 on hardware advertising DEV_TX_OFFLOAD_IPV4_CKSUM.
163 Note that it can only work if outer L4 checksum is 0.
165 - calculate checksum of in_ip and in_tcp::
167 mb->l2_len = len(out_eth + out_ip + out_udp + vxlan + in_eth)
168 mb->l3_len = len(in_ip)
169 mb->ol_flags |= PKT_TX_IPV4 | PKT_TX_IP_CSUM | PKT_TX_TCP_CKSUM
170 set in_ip checksum to 0 in the packet
171 set in_tcp checksum to pseudo header using rte_ipv4_phdr_cksum()
173 This is similar to case 2), but l2_len is different. It is supported
174 on hardware advertising DEV_TX_OFFLOAD_IPV4_CKSUM and
175 DEV_TX_OFFLOAD_TCP_CKSUM.
176 Note that it can only work if outer L4 checksum is 0.
178 - segment inner TCP::
180 mb->l2_len = len(out_eth + out_ip + out_udp + vxlan + in_eth)
181 mb->l3_len = len(in_ip)
182 mb->l4_len = len(in_tcp)
183 mb->ol_flags |= PKT_TX_IPV4 | PKT_TX_IP_CKSUM | PKT_TX_TCP_CKSUM |
185 set in_ip checksum to 0 in the packet
186 set in_tcp checksum to pseudo header without including the IP
187 payload length using rte_ipv4_phdr_cksum()
189 This is supported on hardware advertising DEV_TX_OFFLOAD_TCP_TSO.
190 Note that it can only work if outer L4 checksum is 0.
192 - calculate checksum of out_ip, in_ip, in_tcp::
194 mb->outer_l2_len = len(out_eth)
195 mb->outer_l3_len = len(out_ip)
196 mb->l2_len = len(out_udp + vxlan + in_eth)
197 mb->l3_len = len(in_ip)
198 mb->ol_flags |= PKT_TX_OUTER_IPV4 | PKT_TX_OUTER_IP_CKSUM | \
199 PKT_TX_IP_CKSUM | PKT_TX_TCP_CKSUM;
200 set out_ip checksum to 0 in the packet
201 set in_ip checksum to 0 in the packet
202 set in_tcp checksum to pseudo header using rte_ipv4_phdr_cksum()
204 This is supported on hardware advertising DEV_TX_OFFLOAD_IPV4_CKSUM,
205 DEV_TX_OFFLOAD_UDP_CKSUM and DEV_TX_OFFLOAD_OUTER_IPV4_CKSUM.
207 The list of flags and their precise meaning is described in the mbuf API
208 documentation (rte_mbuf.h). Also refer to the testpmd source code
209 (specifically the csumonly.c file) for details.
211 .. _direct_indirect_buffer:
213 Direct and Indirect Buffers
214 ---------------------------
216 A direct buffer is a buffer that is completely separate and self-contained.
217 An indirect buffer behaves like a direct buffer but for the fact that the buffer pointer and
218 data offset in it refer to data in another direct buffer.
219 This is useful in situations where packets need to be duplicated or fragmented,
220 since indirect buffers provide the means to reuse the same packet data across multiple buffers.
222 A buffer becomes indirect when it is "attached" to a direct buffer using the rte_pktmbuf_attach() function.
223 Each buffer has a reference counter field and whenever an indirect buffer is attached to the direct buffer,
224 the reference counter on the direct buffer is incremented.
225 Similarly, whenever the indirect buffer is detached, the reference counter on the direct buffer is decremented.
226 If the resulting reference counter is equal to 0, the direct buffer is freed since it is no longer in use.
228 There are a few things to remember when dealing with indirect buffers.
229 First of all, an indirect buffer is never attached to another indirect buffer.
230 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.
231 Secondly, for a buffer to become indirect, its reference counter must be equal to 1,
232 that is, it must not be already referenced by another indirect buffer.
233 Finally, it is not possible to reattach an indirect buffer to the direct buffer (unless it is detached first).
235 While the attach/detach operations can be invoked directly using the recommended rte_pktmbuf_attach() and rte_pktmbuf_detach() functions,
236 it is suggested to use the higher-level rte_pktmbuf_clone() function,
237 which takes care of the correct initialization of an indirect buffer and can clone buffers with multiple segments.
239 Since indirect buffers are not supposed to actually hold any data,
240 the memory pool for indirect buffers should be configured to indicate the reduced memory consumption.
241 Examples of the initialization of a memory pool for indirect buffers (as well as use case examples for indirect buffers)
242 can be found in several of the sample applications, for example, the IPv4 Multicast sample application.
247 In debug mode (CONFIG_RTE_MBUF_DEBUG is enabled),
248 the functions of the mbuf library perform sanity checks before any operation (such as, buffer corruption, bad type, and so on).
253 All networking application should use mbufs to transport network packets.