mbuf: allow to clone an indirect mbuf
[dpdk.git] / lib / librte_mbuf / rte_mbuf.h
1 /*-
2  *   BSD LICENSE
3  *
4  *   Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
5  *   Copyright 2014 6WIND S.A.
6  *   All rights reserved.
7  *
8  *   Redistribution and use in source and binary forms, with or without
9  *   modification, are permitted provided that the following conditions
10  *   are met:
11  *
12  *     * Redistributions of source code must retain the above copyright
13  *       notice, this list of conditions and the following disclaimer.
14  *     * Redistributions in binary form must reproduce the above copyright
15  *       notice, this list of conditions and the following disclaimer in
16  *       the documentation and/or other materials provided with the
17  *       distribution.
18  *     * Neither the name of Intel Corporation nor the names of its
19  *       contributors may be used to endorse or promote products derived
20  *       from this software without specific prior written permission.
21  *
22  *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
23  *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
24  *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
25  *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
26  *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
27  *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
28  *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
29  *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
30  *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
31  *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
32  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
33  */
34
35 #ifndef _RTE_MBUF_H_
36 #define _RTE_MBUF_H_
37
38 /**
39  * @file
40  * RTE Mbuf
41  *
42  * The mbuf library provides the ability to create and destroy buffers
43  * that may be used by the RTE application to store message
44  * buffers. The message buffers are stored in a mempool, using the
45  * RTE mempool library.
46  *
47  * This library provide an API to allocate/free packet mbufs, which are
48  * used to carry network packets.
49  *
50  * To understand the concepts of packet buffers or mbufs, you
51  * should read "TCP/IP Illustrated, Volume 2: The Implementation,
52  * Addison-Wesley, 1995, ISBN 0-201-63354-X from Richard Stevens"
53  * http://www.kohala.com/start/tcpipiv2.html
54  */
55
56 #include <stdint.h>
57 #include <rte_mempool.h>
58 #include <rte_memory.h>
59 #include <rte_atomic.h>
60 #include <rte_prefetch.h>
61 #include <rte_branch_prediction.h>
62
63 #ifdef __cplusplus
64 extern "C" {
65 #endif
66
67 /* deprecated options */
68 #pragma GCC poison RTE_MBUF_SCATTER_GATHER
69 #pragma GCC poison RTE_MBUF_REFCNT
70
71 /*
72  * Packet Offload Features Flags. It also carry packet type information.
73  * Critical resources. Both rx/tx shared these bits. Be cautious on any change
74  *
75  * - RX flags start at bit position zero, and get added to the left of previous
76  *   flags.
77  * - The most-significant 8 bits are reserved for generic mbuf flags
78  * - TX flags therefore start at bit position 55 (i.e. 63-8), and new flags get
79  *   added to the right of the previously defined flags
80  *
81  * Keep these flags synchronized with rte_get_rx_ol_flag_name() and
82  * rte_get_tx_ol_flag_name().
83  */
84 #define PKT_RX_VLAN_PKT      (1ULL << 0)  /**< RX packet is a 802.1q VLAN packet. */
85 #define PKT_RX_RSS_HASH      (1ULL << 1)  /**< RX packet with RSS hash result. */
86 #define PKT_RX_FDIR          (1ULL << 2)  /**< RX packet with FDIR match indicate. */
87 #define PKT_RX_L4_CKSUM_BAD  (1ULL << 3)  /**< L4 cksum of RX pkt. is not OK. */
88 #define PKT_RX_IP_CKSUM_BAD  (1ULL << 4)  /**< IP cksum of RX pkt. is not OK. */
89 #define PKT_RX_EIP_CKSUM_BAD (0ULL << 0)  /**< External IP header checksum error. */
90 #define PKT_RX_OVERSIZE      (0ULL << 0)  /**< Num of desc of an RX pkt oversize. */
91 #define PKT_RX_HBUF_OVERFLOW (0ULL << 0)  /**< Header buffer overflow. */
92 #define PKT_RX_RECIP_ERR     (0ULL << 0)  /**< Hardware processing error. */
93 #define PKT_RX_MAC_ERR       (0ULL << 0)  /**< MAC error. */
94 #define PKT_RX_IPV4_HDR      (1ULL << 5)  /**< RX packet with IPv4 header. */
95 #define PKT_RX_IPV4_HDR_EXT  (1ULL << 6)  /**< RX packet with extended IPv4 header. */
96 #define PKT_RX_IPV6_HDR      (1ULL << 7)  /**< RX packet with IPv6 header. */
97 #define PKT_RX_IPV6_HDR_EXT  (1ULL << 8)  /**< RX packet with extended IPv6 header. */
98 #define PKT_RX_IEEE1588_PTP  (1ULL << 9)  /**< RX IEEE1588 L2 Ethernet PT Packet. */
99 #define PKT_RX_IEEE1588_TMST (1ULL << 10) /**< RX IEEE1588 L2/L4 timestamped packet.*/
100 #define PKT_RX_TUNNEL_IPV4_HDR (1ULL << 11) /**< RX tunnel packet with IPv4 header.*/
101 #define PKT_RX_TUNNEL_IPV6_HDR (1ULL << 12) /**< RX tunnel packet with IPv6 header. */
102 #define PKT_RX_FDIR_ID       (1ULL << 13) /**< FD id reported if FDIR match. */
103 #define PKT_RX_FDIR_FLX      (1ULL << 14) /**< Flexible bytes reported if FDIR match. */
104 /* add new RX flags here */
105
106 /* add new TX flags here */
107
108 /**
109  * TCP segmentation offload. To enable this offload feature for a
110  * packet to be transmitted on hardware supporting TSO:
111  *  - set the PKT_TX_TCP_SEG flag in mbuf->ol_flags (this flag implies
112  *    PKT_TX_TCP_CKSUM)
113  *  - set the flag PKT_TX_IPV4 or PKT_TX_IPV6
114  *  - if it's IPv4, set the PKT_TX_IP_CKSUM flag and write the IP checksum
115  *    to 0 in the packet
116  *  - fill the mbuf offload information: l2_len, l3_len, l4_len, tso_segsz
117  *  - calculate the pseudo header checksum without taking ip_len in account,
118  *    and set it in the TCP header. Refer to rte_ipv4_phdr_cksum() and
119  *    rte_ipv6_phdr_cksum() that can be used as helpers.
120  */
121 #define PKT_TX_TCP_SEG       (1ULL << 50)
122
123 #define PKT_TX_IEEE1588_TMST (1ULL << 51) /**< TX IEEE1588 packet to timestamp. */
124
125 /**
126  * Bits 52+53 used for L4 packet type with checksum enabled: 00: Reserved,
127  * 01: TCP checksum, 10: SCTP checksum, 11: UDP checksum. To use hardware
128  * L4 checksum offload, the user needs to:
129  *  - fill l2_len and l3_len in mbuf
130  *  - set the flags PKT_TX_TCP_CKSUM, PKT_TX_SCTP_CKSUM or PKT_TX_UDP_CKSUM
131  *  - set the flag PKT_TX_IPV4 or PKT_TX_IPV6
132  *  - calculate the pseudo header checksum and set it in the L4 header (only
133  *    for TCP or UDP). See rte_ipv4_phdr_cksum() and rte_ipv6_phdr_cksum().
134  *    For SCTP, set the crc field to 0.
135  */
136 #define PKT_TX_L4_NO_CKSUM   (0ULL << 52) /**< Disable L4 cksum of TX pkt. */
137 #define PKT_TX_TCP_CKSUM     (1ULL << 52) /**< TCP cksum of TX pkt. computed by NIC. */
138 #define PKT_TX_SCTP_CKSUM    (2ULL << 52) /**< SCTP cksum of TX pkt. computed by NIC. */
139 #define PKT_TX_UDP_CKSUM     (3ULL << 52) /**< UDP cksum of TX pkt. computed by NIC. */
140 #define PKT_TX_L4_MASK       (3ULL << 52) /**< Mask for L4 cksum offload request. */
141
142 /**
143  * Offload the IP checksum in the hardware. The flag PKT_TX_IPV4 should
144  * also be set by the application, although a PMD will only check
145  * PKT_TX_IP_CKSUM.
146  *  - set the IP checksum field in the packet to 0
147  *  - fill the mbuf offload information: l2_len, l3_len
148  */
149 #define PKT_TX_IP_CKSUM      (1ULL << 54)
150
151 /**
152  * Packet is IPv4. This flag must be set when using any offload feature
153  * (TSO, L3 or L4 checksum) to tell the NIC that the packet is an IPv4
154  * packet. If the packet is a tunneled packet, this flag is related to
155  * the inner headers.
156  */
157 #define PKT_TX_IPV4          (1ULL << 55)
158
159 /**
160  * Packet is IPv6. This flag must be set when using an offload feature
161  * (TSO or L4 checksum) to tell the NIC that the packet is an IPv6
162  * packet. If the packet is a tunneled packet, this flag is related to
163  * the inner headers.
164  */
165 #define PKT_TX_IPV6          (1ULL << 56)
166
167 #define PKT_TX_VLAN_PKT      (1ULL << 57) /**< TX packet is a 802.1q VLAN packet. */
168
169 /**
170  * Offload the IP checksum of an external header in the hardware. The
171  * flag PKT_TX_OUTER_IPV4 should also be set by the application, alto ugh
172  * a PMD will only check PKT_TX_IP_CKSUM.  The IP checksum field in the
173  * packet must be set to 0.
174  *  - set the outer IP checksum field in the packet to 0
175  *  - fill the mbuf offload information: outer_l2_len, outer_l3_len
176  */
177 #define PKT_TX_OUTER_IP_CKSUM   (1ULL << 58)
178
179 /**
180  * Packet outer header is IPv4. This flag must be set when using any
181  * outer offload feature (L3 or L4 checksum) to tell the NIC that the
182  * outer header of the tunneled packet is an IPv4 packet.
183  */
184 #define PKT_TX_OUTER_IPV4   (1ULL << 59)
185
186 /**
187  * Packet outer header is IPv6. This flag must be set when using any
188  * outer offload feature (L4 checksum) to tell the NIC that the outer
189  * header of the tunneled packet is an IPv6 packet.
190  */
191 #define PKT_TX_OUTER_IPV6    (1ULL << 60)
192
193 #define IND_ATTACHED_MBUF    (1ULL << 62) /**< Indirect attached mbuf */
194
195 /* Use final bit of flags to indicate a control mbuf */
196 #define CTRL_MBUF_FLAG       (1ULL << 63) /**< Mbuf contains control data */
197
198 /**
199  * Get the name of a RX offload flag
200  *
201  * @param mask
202  *   The mask describing the flag.
203  * @return
204  *   The name of this flag, or NULL if it's not a valid RX flag.
205  */
206 const char *rte_get_rx_ol_flag_name(uint64_t mask);
207
208 /**
209  * Get the name of a TX offload flag
210  *
211  * @param mask
212  *   The mask describing the flag. Usually only one bit must be set.
213  *   Several bits can be given if they belong to the same mask.
214  *   Ex: PKT_TX_L4_MASK.
215  * @return
216  *   The name of this flag, or NULL if it's not a valid TX flag.
217  */
218 const char *rte_get_tx_ol_flag_name(uint64_t mask);
219
220 /* define a set of marker types that can be used to refer to set points in the
221  * mbuf */
222 typedef void    *MARKER[0];   /**< generic marker for a point in a structure */
223 typedef uint8_t  MARKER8[0];  /**< generic marker with 1B alignment */
224 typedef uint64_t MARKER64[0]; /**< marker that allows us to overwrite 8 bytes
225                                * with a single assignment */
226
227 /**
228  * The generic rte_mbuf, containing a packet mbuf.
229  */
230 struct rte_mbuf {
231         MARKER cacheline0;
232
233         void *buf_addr;           /**< Virtual address of segment buffer. */
234         phys_addr_t buf_physaddr; /**< Physical address of segment buffer. */
235
236         uint16_t buf_len;         /**< Length of segment buffer. */
237
238         /* next 6 bytes are initialised on RX descriptor rearm */
239         MARKER8 rearm_data;
240         uint16_t data_off;
241
242         /**
243          * 16-bit Reference counter.
244          * It should only be accessed using the following functions:
245          * rte_mbuf_refcnt_update(), rte_mbuf_refcnt_read(), and
246          * rte_mbuf_refcnt_set(). The functionality of these functions (atomic,
247          * or non-atomic) is controlled by the CONFIG_RTE_MBUF_REFCNT_ATOMIC
248          * config option.
249          */
250         union {
251                 rte_atomic16_t refcnt_atomic; /**< Atomically accessed refcnt */
252                 uint16_t refcnt;              /**< Non-atomically accessed refcnt */
253         };
254         uint8_t nb_segs;          /**< Number of segments. */
255         uint8_t port;             /**< Input port. */
256
257         uint64_t ol_flags;        /**< Offload features. */
258
259         /* remaining bytes are set on RX when pulling packet from descriptor */
260         MARKER rx_descriptor_fields1;
261
262         /**
263          * The packet type, which is used to indicate ordinary packet and also
264          * tunneled packet format, i.e. each number is represented a type of
265          * packet.
266          */
267         uint16_t packet_type;
268
269         uint16_t data_len;        /**< Amount of data in segment buffer. */
270         uint32_t pkt_len;         /**< Total pkt len: sum of all segments. */
271         uint16_t vlan_tci;        /**< VLAN Tag Control Identifier (CPU order) */
272         uint16_t reserved;
273         union {
274                 uint32_t rss;     /**< RSS hash result if RSS enabled */
275                 struct {
276                         union {
277                                 struct {
278                                         uint16_t hash;
279                                         uint16_t id;
280                                 };
281                                 uint32_t lo;
282                                 /**< Second 4 flexible bytes */
283                         };
284                         uint32_t hi;
285                         /**< First 4 flexible bytes or FD ID, dependent on
286                              PKT_RX_FDIR_* flag in ol_flags. */
287                 } fdir;           /**< Filter identifier if FDIR enabled */
288                 uint32_t sched;   /**< Hierarchical scheduler */
289                 uint32_t usr;     /**< User defined tags. See rte_distributor_process() */
290         } hash;                   /**< hash information */
291
292         uint32_t seqn; /**< Sequence number. See also rte_reorder_insert() */
293
294         /* second cache line - fields only used in slow path or on TX */
295         MARKER cacheline1 __rte_cache_aligned;
296
297         union {
298                 void *userdata;   /**< Can be used for external metadata */
299                 uint64_t udata64; /**< Allow 8-byte userdata on 32-bit */
300         };
301
302         struct rte_mempool *pool; /**< Pool from which mbuf was allocated. */
303         struct rte_mbuf *next;    /**< Next segment of scattered packet. */
304
305         /* fields to support TX offloads */
306         union {
307                 uint64_t tx_offload;       /**< combined for easy fetch */
308                 struct {
309                         uint64_t l2_len:7; /**< L2 (MAC) Header Length. */
310                         uint64_t l3_len:9; /**< L3 (IP) Header Length. */
311                         uint64_t l4_len:8; /**< L4 (TCP/UDP) Header Length. */
312                         uint64_t tso_segsz:16; /**< TCP TSO segment size */
313
314                         /* fields for TX offloading of tunnels */
315                         uint64_t outer_l3_len:9; /**< Outer L3 (IP) Hdr Length. */
316                         uint64_t outer_l2_len:7; /**< Outer L2 (MAC) Hdr Length. */
317
318                         /* uint64_t unused:8; */
319                 };
320         };
321
322         /** Size of the application private data. In case of an indirect
323          * mbuf, it stores the direct mbuf private data size. */
324         uint16_t priv_size;
325 } __rte_cache_aligned;
326
327 static inline uint16_t rte_pktmbuf_priv_size(struct rte_mempool *mp);
328
329 /**
330  * Return the mbuf owning the data buffer address of an indirect mbuf.
331  *
332  * @param mi
333  *   The pointer to the indirect mbuf.
334  * @return
335  *   The address of the direct mbuf corresponding to buffer_addr.
336  */
337 static inline struct rte_mbuf *
338 rte_mbuf_from_indirect(struct rte_mbuf *mi)
339 {
340         struct rte_mbuf *md;
341
342         /* mi->buf_addr and mi->priv_size correspond to buffer and
343          * private size of the direct mbuf */
344         md = (struct rte_mbuf *)((char *)mi->buf_addr - sizeof(*mi) -
345                 mi->priv_size);
346         return md;
347 }
348
349 /**
350  * Return the buffer address embedded in the given mbuf.
351  *
352  * @param md
353  *   The pointer to the mbuf.
354  * @return
355  *   The address of the data buffer owned by the mbuf.
356  */
357 static inline char *
358 rte_mbuf_to_baddr(struct rte_mbuf *md)
359 {
360         char *buffer_addr;
361         buffer_addr = (char *)md + sizeof(*md) + rte_pktmbuf_priv_size(md->pool);
362         return buffer_addr;
363 }
364
365 /**
366  * Returns TRUE if given mbuf is indirect, or FALSE otherwise.
367  */
368 #define RTE_MBUF_INDIRECT(mb)   ((mb)->ol_flags & IND_ATTACHED_MBUF)
369
370 /**
371  * Returns TRUE if given mbuf is direct, or FALSE otherwise.
372  */
373 #define RTE_MBUF_DIRECT(mb)     (!RTE_MBUF_INDIRECT(mb))
374
375 /**
376  * Private data in case of pktmbuf pool.
377  *
378  * A structure that contains some pktmbuf_pool-specific data that are
379  * appended after the mempool structure (in private data).
380  */
381 struct rte_pktmbuf_pool_private {
382         uint16_t mbuf_data_room_size; /**< Size of data space in each mbuf. */
383         uint16_t mbuf_priv_size;      /**< Size of private area in each mbuf. */
384 };
385
386 #ifdef RTE_LIBRTE_MBUF_DEBUG
387
388 /**  check mbuf type in debug mode */
389 #define __rte_mbuf_sanity_check(m, is_h) rte_mbuf_sanity_check(m, is_h)
390
391 /**  check mbuf type in debug mode if mbuf pointer is not null */
392 #define __rte_mbuf_sanity_check_raw(m, is_h)    do {       \
393         if ((m) != NULL)                                   \
394                 rte_mbuf_sanity_check(m, is_h);          \
395 } while (0)
396
397 /**  MBUF asserts in debug mode */
398 #define RTE_MBUF_ASSERT(exp)                                         \
399 if (!(exp)) {                                                        \
400         rte_panic("line%d\tassert \"" #exp "\" failed\n", __LINE__); \
401 }
402
403 #else /*  RTE_LIBRTE_MBUF_DEBUG */
404
405 /**  check mbuf type in debug mode */
406 #define __rte_mbuf_sanity_check(m, is_h) do { } while (0)
407
408 /**  check mbuf type in debug mode if mbuf pointer is not null */
409 #define __rte_mbuf_sanity_check_raw(m, is_h) do { } while (0)
410
411 /**  MBUF asserts in debug mode */
412 #define RTE_MBUF_ASSERT(exp)                do { } while (0)
413
414 #endif /*  RTE_LIBRTE_MBUF_DEBUG */
415
416 #ifdef RTE_MBUF_REFCNT_ATOMIC
417
418 /**
419  * Adds given value to an mbuf's refcnt and returns its new value.
420  * @param m
421  *   Mbuf to update
422  * @param value
423  *   Value to add/subtract
424  * @return
425  *   Updated value
426  */
427 static inline uint16_t
428 rte_mbuf_refcnt_update(struct rte_mbuf *m, int16_t value)
429 {
430         return (uint16_t)(rte_atomic16_add_return(&m->refcnt_atomic, value));
431 }
432
433 /**
434  * Reads the value of an mbuf's refcnt.
435  * @param m
436  *   Mbuf to read
437  * @return
438  *   Reference count number.
439  */
440 static inline uint16_t
441 rte_mbuf_refcnt_read(const struct rte_mbuf *m)
442 {
443         return (uint16_t)(rte_atomic16_read(&m->refcnt_atomic));
444 }
445
446 /**
447  * Sets an mbuf's refcnt to a defined value.
448  * @param m
449  *   Mbuf to update
450  * @param new_value
451  *   Value set
452  */
453 static inline void
454 rte_mbuf_refcnt_set(struct rte_mbuf *m, uint16_t new_value)
455 {
456         rte_atomic16_set(&m->refcnt_atomic, new_value);
457 }
458
459 #else /* ! RTE_MBUF_REFCNT_ATOMIC */
460
461 /**
462  * Adds given value to an mbuf's refcnt and returns its new value.
463  */
464 static inline uint16_t
465 rte_mbuf_refcnt_update(struct rte_mbuf *m, int16_t value)
466 {
467         m->refcnt = (uint16_t)(m->refcnt + value);
468         return m->refcnt;
469 }
470
471 /**
472  * Reads the value of an mbuf's refcnt.
473  */
474 static inline uint16_t
475 rte_mbuf_refcnt_read(const struct rte_mbuf *m)
476 {
477         return m->refcnt;
478 }
479
480 /**
481  * Sets an mbuf's refcnt to the defined value.
482  */
483 static inline void
484 rte_mbuf_refcnt_set(struct rte_mbuf *m, uint16_t new_value)
485 {
486         m->refcnt = new_value;
487 }
488
489 #endif /* RTE_MBUF_REFCNT_ATOMIC */
490
491 /** Mbuf prefetch */
492 #define RTE_MBUF_PREFETCH_TO_FREE(m) do {       \
493         if ((m) != NULL)                        \
494                 rte_prefetch0(m);               \
495 } while (0)
496
497
498 /**
499  * Sanity checks on an mbuf.
500  *
501  * Check the consistency of the given mbuf. The function will cause a
502  * panic if corruption is detected.
503  *
504  * @param m
505  *   The mbuf to be checked.
506  * @param is_header
507  *   True if the mbuf is a packet header, false if it is a sub-segment
508  *   of a packet (in this case, some fields like nb_segs are not checked)
509  */
510 void
511 rte_mbuf_sanity_check(const struct rte_mbuf *m, int is_header);
512
513 /**
514  * @internal Allocate a new mbuf from mempool *mp*.
515  * The use of that function is reserved for RTE internal needs.
516  * Please use rte_pktmbuf_alloc().
517  *
518  * @param mp
519  *   The mempool from which mbuf is allocated.
520  * @return
521  *   - The pointer to the new mbuf on success.
522  *   - NULL if allocation failed.
523  */
524 static inline struct rte_mbuf *__rte_mbuf_raw_alloc(struct rte_mempool *mp)
525 {
526         struct rte_mbuf *m;
527         void *mb = NULL;
528         if (rte_mempool_get(mp, &mb) < 0)
529                 return NULL;
530         m = (struct rte_mbuf *)mb;
531         RTE_MBUF_ASSERT(rte_mbuf_refcnt_read(m) == 0);
532         rte_mbuf_refcnt_set(m, 1);
533         return (m);
534 }
535
536 /**
537  * @internal Put mbuf back into its original mempool.
538  * The use of that function is reserved for RTE internal needs.
539  * Please use rte_pktmbuf_free().
540  *
541  * @param m
542  *   The mbuf to be freed.
543  */
544 static inline void __attribute__((always_inline))
545 __rte_mbuf_raw_free(struct rte_mbuf *m)
546 {
547         RTE_MBUF_ASSERT(rte_mbuf_refcnt_read(m) == 0);
548         rte_mempool_put(m->pool, m);
549 }
550
551 /* Operations on ctrl mbuf */
552
553 /**
554  * The control mbuf constructor.
555  *
556  * This function initializes some fields in an mbuf structure that are
557  * not modified by the user once created (mbuf type, origin pool, buffer
558  * start address, and so on). This function is given as a callback function
559  * to rte_mempool_create() at pool creation time.
560  *
561  * @param mp
562  *   The mempool from which the mbuf is allocated.
563  * @param opaque_arg
564  *   A pointer that can be used by the user to retrieve useful information
565  *   for mbuf initialization. This pointer comes from the ``init_arg``
566  *   parameter of rte_mempool_create().
567  * @param m
568  *   The mbuf to initialize.
569  * @param i
570  *   The index of the mbuf in the pool table.
571  */
572 void rte_ctrlmbuf_init(struct rte_mempool *mp, void *opaque_arg,
573                 void *m, unsigned i);
574
575 /**
576  * Allocate a new mbuf (type is ctrl) from mempool *mp*.
577  *
578  * This new mbuf is initialized with data pointing to the beginning of
579  * buffer, and with a length of zero.
580  *
581  * @param mp
582  *   The mempool from which the mbuf is allocated.
583  * @return
584  *   - The pointer to the new mbuf on success.
585  *   - NULL if allocation failed.
586  */
587 #define rte_ctrlmbuf_alloc(mp) rte_pktmbuf_alloc(mp)
588
589 /**
590  * Free a control mbuf back into its original mempool.
591  *
592  * @param m
593  *   The control mbuf to be freed.
594  */
595 #define rte_ctrlmbuf_free(m) rte_pktmbuf_free(m)
596
597 /**
598  * A macro that returns the pointer to the carried data.
599  *
600  * The value that can be read or assigned.
601  *
602  * @param m
603  *   The control mbuf.
604  */
605 #define rte_ctrlmbuf_data(m) ((char *)((m)->buf_addr) + (m)->data_off)
606
607 /**
608  * A macro that returns the length of the carried data.
609  *
610  * The value that can be read or assigned.
611  *
612  * @param m
613  *   The control mbuf.
614  */
615 #define rte_ctrlmbuf_len(m) rte_pktmbuf_data_len(m)
616
617 /**
618  * Tests if an mbuf is a control mbuf
619  *
620  * @param m
621  *   The mbuf to be tested
622  * @return
623  *   - True (1) if the mbuf is a control mbuf
624  *   - False(0) otherwise
625  */
626 static inline int
627 rte_is_ctrlmbuf(struct rte_mbuf *m)
628 {
629         return (!!(m->ol_flags & CTRL_MBUF_FLAG));
630 }
631
632 /* Operations on pkt mbuf */
633
634 /**
635  * The packet mbuf constructor.
636  *
637  * This function initializes some fields in the mbuf structure that are
638  * not modified by the user once created (origin pool, buffer start
639  * address, and so on). This function is given as a callback function to
640  * rte_mempool_create() at pool creation time.
641  *
642  * @param mp
643  *   The mempool from which mbufs originate.
644  * @param opaque_arg
645  *   A pointer that can be used by the user to retrieve useful information
646  *   for mbuf initialization. This pointer comes from the ``init_arg``
647  *   parameter of rte_mempool_create().
648  * @param m
649  *   The mbuf to initialize.
650  * @param i
651  *   The index of the mbuf in the pool table.
652  */
653 void rte_pktmbuf_init(struct rte_mempool *mp, void *opaque_arg,
654                       void *m, unsigned i);
655
656
657 /**
658  * A  packet mbuf pool constructor.
659  *
660  * This function initializes the mempool private data in the case of a
661  * pktmbuf pool. This private data is needed by the driver. The
662  * function is given as a callback function to rte_mempool_create() at
663  * pool creation. It can be extended by the user, for example, to
664  * provide another packet size.
665  *
666  * @param mp
667  *   The mempool from which mbufs originate.
668  * @param opaque_arg
669  *   A pointer that can be used by the user to retrieve useful information
670  *   for mbuf initialization. This pointer comes from the ``init_arg``
671  *   parameter of rte_mempool_create().
672  */
673 void rte_pktmbuf_pool_init(struct rte_mempool *mp, void *opaque_arg);
674
675 /**
676  * Create a mbuf pool.
677  *
678  * This function creates and initializes a packet mbuf pool. It is
679  * a wrapper to rte_mempool_create() with the proper packet constructor
680  * and mempool constructor.
681  *
682  * @param name
683  *   The name of the mbuf pool.
684  * @param n
685  *   The number of elements in the mbuf pool. The optimum size (in terms
686  *   of memory usage) for a mempool is when n is a power of two minus one:
687  *   n = (2^q - 1).
688  * @param cache_size
689  *   Size of the per-core object cache. See rte_mempool_create() for
690  *   details.
691  * @param priv_size
692  *   Size of application private are between the rte_mbuf structure
693  *   and the data buffer.
694  * @param data_room_size
695  *   Size of data buffer in each mbuf, including RTE_PKTMBUF_HEADROOM.
696  * @param socket_id
697  *   The socket identifier where the memory should be allocated. The
698  *   value can be *SOCKET_ID_ANY* if there is no NUMA constraint for the
699  *   reserved zone.
700  * @return
701  *   The pointer to the new allocated mempool, on success. NULL on error
702  *   with rte_errno set appropriately. Possible rte_errno values include:
703  *    - E_RTE_NO_CONFIG - function could not get pointer to rte_config structure
704  *    - E_RTE_SECONDARY - function was called from a secondary process instance
705  *    - EINVAL - cache size provided is too large
706  *    - ENOSPC - the maximum number of memzones has already been allocated
707  *    - EEXIST - a memzone with the same name already exists
708  *    - ENOMEM - no appropriate memory area found in which to create memzone
709  */
710 struct rte_mempool *
711 rte_pktmbuf_pool_create(const char *name, unsigned n,
712         unsigned cache_size, uint16_t priv_size, uint16_t data_room_size,
713         int socket_id);
714
715 /**
716  * Get the data room size of mbufs stored in a pktmbuf_pool
717  *
718  * The data room size is the amount of data that can be stored in a
719  * mbuf including the headroom (RTE_PKTMBUF_HEADROOM).
720  *
721  * @param mp
722  *   The packet mbuf pool.
723  * @return
724  *   The data room size of mbufs stored in this mempool.
725  */
726 static inline uint16_t
727 rte_pktmbuf_data_room_size(struct rte_mempool *mp)
728 {
729         struct rte_pktmbuf_pool_private *mbp_priv;
730
731         mbp_priv = (struct rte_pktmbuf_pool_private *)rte_mempool_get_priv(mp);
732         return mbp_priv->mbuf_data_room_size;
733 }
734
735 /**
736  * Get the application private size of mbufs stored in a pktmbuf_pool
737  *
738  * The private size of mbuf is a zone located between the rte_mbuf
739  * structure and the data buffer where an application can store data
740  * associated to a packet.
741  *
742  * @param mp
743  *   The packet mbuf pool.
744  * @return
745  *   The private size of mbufs stored in this mempool.
746  */
747 static inline uint16_t
748 rte_pktmbuf_priv_size(struct rte_mempool *mp)
749 {
750         struct rte_pktmbuf_pool_private *mbp_priv;
751
752         mbp_priv = (struct rte_pktmbuf_pool_private *)rte_mempool_get_priv(mp);
753         return mbp_priv->mbuf_priv_size;
754 }
755
756 /**
757  * Reset the fields of a packet mbuf to their default values.
758  *
759  * The given mbuf must have only one segment.
760  *
761  * @param m
762  *   The packet mbuf to be resetted.
763  */
764 static inline void rte_pktmbuf_reset(struct rte_mbuf *m)
765 {
766         m->next = NULL;
767         m->pkt_len = 0;
768         m->tx_offload = 0;
769         m->vlan_tci = 0;
770         m->nb_segs = 1;
771         m->port = 0xff;
772
773         m->ol_flags = 0;
774         m->packet_type = 0;
775         m->data_off = (RTE_PKTMBUF_HEADROOM <= m->buf_len) ?
776                         RTE_PKTMBUF_HEADROOM : m->buf_len;
777
778         m->data_len = 0;
779         __rte_mbuf_sanity_check(m, 1);
780 }
781
782 /**
783  * Allocate a new mbuf from a mempool.
784  *
785  * This new mbuf contains one segment, which has a length of 0. The pointer
786  * to data is initialized to have some bytes of headroom in the buffer
787  * (if buffer size allows).
788  *
789  * @param mp
790  *   The mempool from which the mbuf is allocated.
791  * @return
792  *   - The pointer to the new mbuf on success.
793  *   - NULL if allocation failed.
794  */
795 static inline struct rte_mbuf *rte_pktmbuf_alloc(struct rte_mempool *mp)
796 {
797         struct rte_mbuf *m;
798         if ((m = __rte_mbuf_raw_alloc(mp)) != NULL)
799                 rte_pktmbuf_reset(m);
800         return (m);
801 }
802
803 /**
804  * Attach packet mbuf to another packet mbuf.
805  *
806  * After attachment we refer the mbuf we attached as 'indirect',
807  * while mbuf we attached to as 'direct'.
808  * Right now, not supported:
809  *  - attachment for already indirect mbuf (e.g. - mi has to be direct).
810  *  - mbuf we trying to attach (mi) is used by someone else
811  *    e.g. it's reference counter is greater then 1.
812  *
813  * @param mi
814  *   The indirect packet mbuf.
815  * @param m
816  *   The packet mbuf we're attaching to.
817  */
818 static inline void rte_pktmbuf_attach(struct rte_mbuf *mi, struct rte_mbuf *m)
819 {
820         struct rte_mbuf *md;
821
822         RTE_MBUF_ASSERT(RTE_MBUF_DIRECT(mi) &&
823             rte_mbuf_refcnt_read(mi) == 1);
824
825         /* if m is not direct, get the mbuf that embeds the data */
826         if (RTE_MBUF_DIRECT(m))
827                 md = m;
828         else
829                 md = rte_mbuf_from_indirect(m);
830
831         rte_mbuf_refcnt_update(md, 1);
832         mi->priv_size = m->priv_size;
833         mi->buf_physaddr = m->buf_physaddr;
834         mi->buf_addr = m->buf_addr;
835         mi->buf_len = m->buf_len;
836
837         mi->next = m->next;
838         mi->data_off = m->data_off;
839         mi->data_len = m->data_len;
840         mi->port = m->port;
841         mi->vlan_tci = m->vlan_tci;
842         mi->tx_offload = m->tx_offload;
843         mi->hash = m->hash;
844
845         mi->next = NULL;
846         mi->pkt_len = mi->data_len;
847         mi->nb_segs = 1;
848         mi->ol_flags = m->ol_flags | IND_ATTACHED_MBUF;
849         mi->packet_type = m->packet_type;
850
851         __rte_mbuf_sanity_check(mi, 1);
852         __rte_mbuf_sanity_check(m, 0);
853 }
854
855 /**
856  * Detach an indirect packet mbuf.
857  *
858  *  - restore original mbuf address and length values.
859  *  - reset pktmbuf data and data_len to their default values.
860  *  All other fields of the given packet mbuf will be left intact.
861  *
862  * @param m
863  *   The indirect attached packet mbuf.
864  */
865 static inline void rte_pktmbuf_detach(struct rte_mbuf *m)
866 {
867         struct rte_mempool *mp = m->pool;
868         uint32_t mbuf_size, buf_len, priv_size;
869
870         priv_size = rte_pktmbuf_priv_size(mp);
871         mbuf_size = sizeof(struct rte_mbuf) + priv_size;
872         buf_len = rte_pktmbuf_data_room_size(mp);
873
874         m->priv_size = priv_size;
875         m->buf_addr = (char *)m + mbuf_size;
876         m->buf_physaddr = rte_mempool_virt2phy(mp, m) + mbuf_size;
877         m->buf_len = (uint16_t)buf_len;
878         m->data_off = RTE_MIN(RTE_PKTMBUF_HEADROOM, (uint16_t)m->buf_len);
879         m->data_len = 0;
880         m->ol_flags = 0;
881 }
882
883 static inline struct rte_mbuf* __attribute__((always_inline))
884 __rte_pktmbuf_prefree_seg(struct rte_mbuf *m)
885 {
886         __rte_mbuf_sanity_check(m, 0);
887
888         /*
889          * Check to see if this is the last reference to the mbuf.
890          * Note: the double check here is deliberate. If the ref_cnt is "atomic"
891          * the call to "refcnt_update" is a very expensive operation, so we
892          * don't want to call it in the case where we know we are the holder
893          * of the last reference to this mbuf i.e. ref_cnt == 1.
894          * If however, ref_cnt != 1, it's still possible that we may still be
895          * the final decrementer of the count, so we need to check that
896          * result also, to make sure the mbuf is freed properly.
897          */
898         if (likely (rte_mbuf_refcnt_read(m) == 1) ||
899                         likely (rte_mbuf_refcnt_update(m, -1) == 0)) {
900
901                 rte_mbuf_refcnt_set(m, 0);
902
903                 /* if this is an indirect mbuf, then
904                  *  - detach mbuf
905                  *  - free attached mbuf segment
906                  */
907                 if (RTE_MBUF_INDIRECT(m)) {
908                         struct rte_mbuf *md = rte_mbuf_from_indirect(m);
909                         rte_pktmbuf_detach(m);
910                         if (rte_mbuf_refcnt_update(md, -1) == 0)
911                                 __rte_mbuf_raw_free(md);
912                 }
913                 return(m);
914         }
915         return (NULL);
916 }
917
918 /**
919  * Free a segment of a packet mbuf into its original mempool.
920  *
921  * Free an mbuf, without parsing other segments in case of chained
922  * buffers.
923  *
924  * @param m
925  *   The packet mbuf segment to be freed.
926  */
927 static inline void __attribute__((always_inline))
928 rte_pktmbuf_free_seg(struct rte_mbuf *m)
929 {
930         if (likely(NULL != (m = __rte_pktmbuf_prefree_seg(m)))) {
931                 m->next = NULL;
932                 __rte_mbuf_raw_free(m);
933         }
934 }
935
936 /**
937  * Free a packet mbuf back into its original mempool.
938  *
939  * Free an mbuf, and all its segments in case of chained buffers. Each
940  * segment is added back into its original mempool.
941  *
942  * @param m
943  *   The packet mbuf to be freed.
944  */
945 static inline void rte_pktmbuf_free(struct rte_mbuf *m)
946 {
947         struct rte_mbuf *m_next;
948
949         __rte_mbuf_sanity_check(m, 1);
950
951         while (m != NULL) {
952                 m_next = m->next;
953                 rte_pktmbuf_free_seg(m);
954                 m = m_next;
955         }
956 }
957
958 /**
959  * Creates a "clone" of the given packet mbuf.
960  *
961  * Walks through all segments of the given packet mbuf, and for each of them:
962  *  - Creates a new packet mbuf from the given pool.
963  *  - Attaches newly created mbuf to the segment.
964  * Then updates pkt_len and nb_segs of the "clone" packet mbuf to match values
965  * from the original packet mbuf.
966  *
967  * @param md
968  *   The packet mbuf to be cloned.
969  * @param mp
970  *   The mempool from which the "clone" mbufs are allocated.
971  * @return
972  *   - The pointer to the new "clone" mbuf on success.
973  *   - NULL if allocation fails.
974  */
975 static inline struct rte_mbuf *rte_pktmbuf_clone(struct rte_mbuf *md,
976                 struct rte_mempool *mp)
977 {
978         struct rte_mbuf *mc, *mi, **prev;
979         uint32_t pktlen;
980         uint8_t nseg;
981
982         if (unlikely ((mc = rte_pktmbuf_alloc(mp)) == NULL))
983                 return (NULL);
984
985         mi = mc;
986         prev = &mi->next;
987         pktlen = md->pkt_len;
988         nseg = 0;
989
990         do {
991                 nseg++;
992                 rte_pktmbuf_attach(mi, md);
993                 *prev = mi;
994                 prev = &mi->next;
995         } while ((md = md->next) != NULL &&
996             (mi = rte_pktmbuf_alloc(mp)) != NULL);
997
998         *prev = NULL;
999         mc->nb_segs = nseg;
1000         mc->pkt_len = pktlen;
1001
1002         /* Allocation of new indirect segment failed */
1003         if (unlikely (mi == NULL)) {
1004                 rte_pktmbuf_free(mc);
1005                 return (NULL);
1006         }
1007
1008         __rte_mbuf_sanity_check(mc, 1);
1009         return (mc);
1010 }
1011
1012 /**
1013  * Adds given value to the refcnt of all packet mbuf segments.
1014  *
1015  * Walks through all segments of given packet mbuf and for each of them
1016  * invokes rte_mbuf_refcnt_update().
1017  *
1018  * @param m
1019  *   The packet mbuf whose refcnt to be updated.
1020  * @param v
1021  *   The value to add to the mbuf's segments refcnt.
1022  */
1023 static inline void rte_pktmbuf_refcnt_update(struct rte_mbuf *m, int16_t v)
1024 {
1025         __rte_mbuf_sanity_check(m, 1);
1026
1027         do {
1028                 rte_mbuf_refcnt_update(m, v);
1029         } while ((m = m->next) != NULL);
1030 }
1031
1032 /**
1033  * Get the headroom in a packet mbuf.
1034  *
1035  * @param m
1036  *   The packet mbuf.
1037  * @return
1038  *   The length of the headroom.
1039  */
1040 static inline uint16_t rte_pktmbuf_headroom(const struct rte_mbuf *m)
1041 {
1042         __rte_mbuf_sanity_check(m, 1);
1043         return m->data_off;
1044 }
1045
1046 /**
1047  * Get the tailroom of a packet mbuf.
1048  *
1049  * @param m
1050  *   The packet mbuf.
1051  * @return
1052  *   The length of the tailroom.
1053  */
1054 static inline uint16_t rte_pktmbuf_tailroom(const struct rte_mbuf *m)
1055 {
1056         __rte_mbuf_sanity_check(m, 1);
1057         return (uint16_t)(m->buf_len - rte_pktmbuf_headroom(m) -
1058                           m->data_len);
1059 }
1060
1061 /**
1062  * Get the last segment of the packet.
1063  *
1064  * @param m
1065  *   The packet mbuf.
1066  * @return
1067  *   The last segment of the given mbuf.
1068  */
1069 static inline struct rte_mbuf *rte_pktmbuf_lastseg(struct rte_mbuf *m)
1070 {
1071         struct rte_mbuf *m2 = (struct rte_mbuf *)m;
1072
1073         __rte_mbuf_sanity_check(m, 1);
1074         while (m2->next != NULL)
1075                 m2 = m2->next;
1076         return m2;
1077 }
1078
1079 /**
1080  * A macro that points to the start of the data in the mbuf.
1081  *
1082  * The returned pointer is cast to type t. Before using this
1083  * function, the user must ensure that m_headlen(m) is large enough to
1084  * read its data.
1085  *
1086  * @param m
1087  *   The packet mbuf.
1088  * @param t
1089  *   The type to cast the result into.
1090  */
1091 #define rte_pktmbuf_mtod(m, t) ((t)((char *)(m)->buf_addr + (m)->data_off))
1092
1093 /**
1094  * A macro that returns the length of the packet.
1095  *
1096  * The value can be read or assigned.
1097  *
1098  * @param m
1099  *   The packet mbuf.
1100  */
1101 #define rte_pktmbuf_pkt_len(m) ((m)->pkt_len)
1102
1103 /**
1104  * A macro that returns the length of the segment.
1105  *
1106  * The value can be read or assigned.
1107  *
1108  * @param m
1109  *   The packet mbuf.
1110  */
1111 #define rte_pktmbuf_data_len(m) ((m)->data_len)
1112
1113 /**
1114  * Prepend len bytes to an mbuf data area.
1115  *
1116  * Returns a pointer to the new
1117  * data start address. If there is not enough headroom in the first
1118  * segment, the function will return NULL, without modifying the mbuf.
1119  *
1120  * @param m
1121  *   The pkt mbuf.
1122  * @param len
1123  *   The amount of data to prepend (in bytes).
1124  * @return
1125  *   A pointer to the start of the newly prepended data, or
1126  *   NULL if there is not enough headroom space in the first segment
1127  */
1128 static inline char *rte_pktmbuf_prepend(struct rte_mbuf *m,
1129                                         uint16_t len)
1130 {
1131         __rte_mbuf_sanity_check(m, 1);
1132
1133         if (unlikely(len > rte_pktmbuf_headroom(m)))
1134                 return NULL;
1135
1136         m->data_off -= len;
1137         m->data_len = (uint16_t)(m->data_len + len);
1138         m->pkt_len  = (m->pkt_len + len);
1139
1140         return (char *)m->buf_addr + m->data_off;
1141 }
1142
1143 /**
1144  * Append len bytes to an mbuf.
1145  *
1146  * Append len bytes to an mbuf and return a pointer to the start address
1147  * of the added data. If there is not enough tailroom in the last
1148  * segment, the function will return NULL, without modifying the mbuf.
1149  *
1150  * @param m
1151  *   The packet mbuf.
1152  * @param len
1153  *   The amount of data to append (in bytes).
1154  * @return
1155  *   A pointer to the start of the newly appended data, or
1156  *   NULL if there is not enough tailroom space in the last segment
1157  */
1158 static inline char *rte_pktmbuf_append(struct rte_mbuf *m, uint16_t len)
1159 {
1160         void *tail;
1161         struct rte_mbuf *m_last;
1162
1163         __rte_mbuf_sanity_check(m, 1);
1164
1165         m_last = rte_pktmbuf_lastseg(m);
1166         if (unlikely(len > rte_pktmbuf_tailroom(m_last)))
1167                 return NULL;
1168
1169         tail = (char *)m_last->buf_addr + m_last->data_off + m_last->data_len;
1170         m_last->data_len = (uint16_t)(m_last->data_len + len);
1171         m->pkt_len  = (m->pkt_len + len);
1172         return (char*) tail;
1173 }
1174
1175 /**
1176  * Remove len bytes at the beginning of an mbuf.
1177  *
1178  * Returns a pointer to the start address of the new data area. If the
1179  * length is greater than the length of the first segment, then the
1180  * function will fail and return NULL, without modifying the mbuf.
1181  *
1182  * @param m
1183  *   The packet mbuf.
1184  * @param len
1185  *   The amount of data to remove (in bytes).
1186  * @return
1187  *   A pointer to the new start of the data.
1188  */
1189 static inline char *rte_pktmbuf_adj(struct rte_mbuf *m, uint16_t len)
1190 {
1191         __rte_mbuf_sanity_check(m, 1);
1192
1193         if (unlikely(len > m->data_len))
1194                 return NULL;
1195
1196         m->data_len = (uint16_t)(m->data_len - len);
1197         m->data_off += len;
1198         m->pkt_len  = (m->pkt_len - len);
1199         return (char *)m->buf_addr + m->data_off;
1200 }
1201
1202 /**
1203  * Remove len bytes of data at the end of the mbuf.
1204  *
1205  * If the length is greater than the length of the last segment, the
1206  * function will fail and return -1 without modifying the mbuf.
1207  *
1208  * @param m
1209  *   The packet mbuf.
1210  * @param len
1211  *   The amount of data to remove (in bytes).
1212  * @return
1213  *   - 0: On success.
1214  *   - -1: On error.
1215  */
1216 static inline int rte_pktmbuf_trim(struct rte_mbuf *m, uint16_t len)
1217 {
1218         struct rte_mbuf *m_last;
1219
1220         __rte_mbuf_sanity_check(m, 1);
1221
1222         m_last = rte_pktmbuf_lastseg(m);
1223         if (unlikely(len > m_last->data_len))
1224                 return -1;
1225
1226         m_last->data_len = (uint16_t)(m_last->data_len - len);
1227         m->pkt_len  = (m->pkt_len - len);
1228         return 0;
1229 }
1230
1231 /**
1232  * Test if mbuf data is contiguous.
1233  *
1234  * @param m
1235  *   The packet mbuf.
1236  * @return
1237  *   - 1, if all data is contiguous (one segment).
1238  *   - 0, if there is several segments.
1239  */
1240 static inline int rte_pktmbuf_is_contiguous(const struct rte_mbuf *m)
1241 {
1242         __rte_mbuf_sanity_check(m, 1);
1243         return !!(m->nb_segs == 1);
1244 }
1245
1246 /**
1247  * Dump an mbuf structure to the console.
1248  *
1249  * Dump all fields for the given packet mbuf and all its associated
1250  * segments (in the case of a chained buffer).
1251  *
1252  * @param f
1253  *   A pointer to a file for output
1254  * @param m
1255  *   The packet mbuf.
1256  * @param dump_len
1257  *   If dump_len != 0, also dump the "dump_len" first data bytes of
1258  *   the packet.
1259  */
1260 void rte_pktmbuf_dump(FILE *f, const struct rte_mbuf *m, unsigned dump_len);
1261
1262 #ifdef __cplusplus
1263 }
1264 #endif
1265
1266 #endif /* _RTE_MBUF_H_ */