45f73c2b6e4262f572b4fd1f074e607df95b7782
[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 } __rte_cache_aligned;
322
323 /**
324  * Given the buf_addr returns the pointer to corresponding mbuf.
325  */
326 #define RTE_MBUF_FROM_BADDR(ba)     (((struct rte_mbuf *)(ba)) - 1)
327
328 /**
329  * Given the pointer to mbuf returns an address where it's  buf_addr
330  * should point to.
331  */
332 #define RTE_MBUF_TO_BADDR(mb)       (((struct rte_mbuf *)(mb)) + 1)
333
334 /**
335  * Returns TRUE if given mbuf is indirect, or FALSE otherwise.
336  */
337 #define RTE_MBUF_INDIRECT(mb)   ((mb)->ol_flags & IND_ATTACHED_MBUF)
338
339 /**
340  * Returns TRUE if given mbuf is direct, or FALSE otherwise.
341  */
342 #define RTE_MBUF_DIRECT(mb)     (!RTE_MBUF_INDIRECT(mb))
343
344 /**
345  * Private data in case of pktmbuf pool.
346  *
347  * A structure that contains some pktmbuf_pool-specific data that are
348  * appended after the mempool structure (in private data).
349  */
350 struct rte_pktmbuf_pool_private {
351         uint16_t mbuf_data_room_size; /**< Size of data space in each mbuf.*/
352 };
353
354 #ifdef RTE_LIBRTE_MBUF_DEBUG
355
356 /**  check mbuf type in debug mode */
357 #define __rte_mbuf_sanity_check(m, is_h) rte_mbuf_sanity_check(m, is_h)
358
359 /**  check mbuf type in debug mode if mbuf pointer is not null */
360 #define __rte_mbuf_sanity_check_raw(m, is_h)    do {       \
361         if ((m) != NULL)                                   \
362                 rte_mbuf_sanity_check(m, is_h);          \
363 } while (0)
364
365 /**  MBUF asserts in debug mode */
366 #define RTE_MBUF_ASSERT(exp)                                         \
367 if (!(exp)) {                                                        \
368         rte_panic("line%d\tassert \"" #exp "\" failed\n", __LINE__); \
369 }
370
371 #else /*  RTE_LIBRTE_MBUF_DEBUG */
372
373 /**  check mbuf type in debug mode */
374 #define __rte_mbuf_sanity_check(m, is_h) do { } while (0)
375
376 /**  check mbuf type in debug mode if mbuf pointer is not null */
377 #define __rte_mbuf_sanity_check_raw(m, is_h) do { } while (0)
378
379 /**  MBUF asserts in debug mode */
380 #define RTE_MBUF_ASSERT(exp)                do { } while (0)
381
382 #endif /*  RTE_LIBRTE_MBUF_DEBUG */
383
384 #ifdef RTE_MBUF_REFCNT_ATOMIC
385
386 /**
387  * Adds given value to an mbuf's refcnt and returns its new value.
388  * @param m
389  *   Mbuf to update
390  * @param value
391  *   Value to add/subtract
392  * @return
393  *   Updated value
394  */
395 static inline uint16_t
396 rte_mbuf_refcnt_update(struct rte_mbuf *m, int16_t value)
397 {
398         return (uint16_t)(rte_atomic16_add_return(&m->refcnt_atomic, value));
399 }
400
401 /**
402  * Reads the value of an mbuf's refcnt.
403  * @param m
404  *   Mbuf to read
405  * @return
406  *   Reference count number.
407  */
408 static inline uint16_t
409 rte_mbuf_refcnt_read(const struct rte_mbuf *m)
410 {
411         return (uint16_t)(rte_atomic16_read(&m->refcnt_atomic));
412 }
413
414 /**
415  * Sets an mbuf's refcnt to a defined value.
416  * @param m
417  *   Mbuf to update
418  * @param new_value
419  *   Value set
420  */
421 static inline void
422 rte_mbuf_refcnt_set(struct rte_mbuf *m, uint16_t new_value)
423 {
424         rte_atomic16_set(&m->refcnt_atomic, new_value);
425 }
426
427 #else /* ! RTE_MBUF_REFCNT_ATOMIC */
428
429 /**
430  * Adds given value to an mbuf's refcnt and returns its new value.
431  */
432 static inline uint16_t
433 rte_mbuf_refcnt_update(struct rte_mbuf *m, int16_t value)
434 {
435         m->refcnt = (uint16_t)(m->refcnt + value);
436         return m->refcnt;
437 }
438
439 /**
440  * Reads the value of an mbuf's refcnt.
441  */
442 static inline uint16_t
443 rte_mbuf_refcnt_read(const struct rte_mbuf *m)
444 {
445         return m->refcnt;
446 }
447
448 /**
449  * Sets an mbuf's refcnt to the defined value.
450  */
451 static inline void
452 rte_mbuf_refcnt_set(struct rte_mbuf *m, uint16_t new_value)
453 {
454         m->refcnt = new_value;
455 }
456
457 #endif /* RTE_MBUF_REFCNT_ATOMIC */
458
459 /** Mbuf prefetch */
460 #define RTE_MBUF_PREFETCH_TO_FREE(m) do {       \
461         if ((m) != NULL)                        \
462                 rte_prefetch0(m);               \
463 } while (0)
464
465
466 /**
467  * Sanity checks on an mbuf.
468  *
469  * Check the consistency of the given mbuf. The function will cause a
470  * panic if corruption is detected.
471  *
472  * @param m
473  *   The mbuf to be checked.
474  * @param is_header
475  *   True if the mbuf is a packet header, false if it is a sub-segment
476  *   of a packet (in this case, some fields like nb_segs are not checked)
477  */
478 void
479 rte_mbuf_sanity_check(const struct rte_mbuf *m, int is_header);
480
481 /**
482  * @internal Allocate a new mbuf from mempool *mp*.
483  * The use of that function is reserved for RTE internal needs.
484  * Please use rte_pktmbuf_alloc().
485  *
486  * @param mp
487  *   The mempool from which mbuf is allocated.
488  * @return
489  *   - The pointer to the new mbuf on success.
490  *   - NULL if allocation failed.
491  */
492 static inline struct rte_mbuf *__rte_mbuf_raw_alloc(struct rte_mempool *mp)
493 {
494         struct rte_mbuf *m;
495         void *mb = NULL;
496         if (rte_mempool_get(mp, &mb) < 0)
497                 return NULL;
498         m = (struct rte_mbuf *)mb;
499         RTE_MBUF_ASSERT(rte_mbuf_refcnt_read(m) == 0);
500         rte_mbuf_refcnt_set(m, 1);
501         return (m);
502 }
503
504 /**
505  * @internal Put mbuf back into its original mempool.
506  * The use of that function is reserved for RTE internal needs.
507  * Please use rte_pktmbuf_free().
508  *
509  * @param m
510  *   The mbuf to be freed.
511  */
512 static inline void __attribute__((always_inline))
513 __rte_mbuf_raw_free(struct rte_mbuf *m)
514 {
515         RTE_MBUF_ASSERT(rte_mbuf_refcnt_read(m) == 0);
516         rte_mempool_put(m->pool, m);
517 }
518
519 /* Operations on ctrl mbuf */
520
521 /**
522  * The control mbuf constructor.
523  *
524  * This function initializes some fields in an mbuf structure that are
525  * not modified by the user once created (mbuf type, origin pool, buffer
526  * start address, and so on). This function is given as a callback function
527  * to rte_mempool_create() at pool creation time.
528  *
529  * @param mp
530  *   The mempool from which the mbuf is allocated.
531  * @param opaque_arg
532  *   A pointer that can be used by the user to retrieve useful information
533  *   for mbuf initialization. This pointer comes from the ``init_arg``
534  *   parameter of rte_mempool_create().
535  * @param m
536  *   The mbuf to initialize.
537  * @param i
538  *   The index of the mbuf in the pool table.
539  */
540 void rte_ctrlmbuf_init(struct rte_mempool *mp, void *opaque_arg,
541                 void *m, unsigned i);
542
543 /**
544  * Allocate a new mbuf (type is ctrl) from mempool *mp*.
545  *
546  * This new mbuf is initialized with data pointing to the beginning of
547  * buffer, and with a length of zero.
548  *
549  * @param mp
550  *   The mempool from which the mbuf is allocated.
551  * @return
552  *   - The pointer to the new mbuf on success.
553  *   - NULL if allocation failed.
554  */
555 #define rte_ctrlmbuf_alloc(mp) rte_pktmbuf_alloc(mp)
556
557 /**
558  * Free a control mbuf back into its original mempool.
559  *
560  * @param m
561  *   The control mbuf to be freed.
562  */
563 #define rte_ctrlmbuf_free(m) rte_pktmbuf_free(m)
564
565 /**
566  * A macro that returns the pointer to the carried data.
567  *
568  * The value that can be read or assigned.
569  *
570  * @param m
571  *   The control mbuf.
572  */
573 #define rte_ctrlmbuf_data(m) ((char *)((m)->buf_addr) + (m)->data_off)
574
575 /**
576  * A macro that returns the length of the carried data.
577  *
578  * The value that can be read or assigned.
579  *
580  * @param m
581  *   The control mbuf.
582  */
583 #define rte_ctrlmbuf_len(m) rte_pktmbuf_data_len(m)
584
585 /**
586  * Tests if an mbuf is a control mbuf
587  *
588  * @param m
589  *   The mbuf to be tested
590  * @return
591  *   - True (1) if the mbuf is a control mbuf
592  *   - False(0) otherwise
593  */
594 static inline int
595 rte_is_ctrlmbuf(struct rte_mbuf *m)
596 {
597         return (!!(m->ol_flags & CTRL_MBUF_FLAG));
598 }
599
600 /* Operations on pkt mbuf */
601
602 /**
603  * The packet mbuf constructor.
604  *
605  * This function initializes some fields in the mbuf structure that are
606  * not modified by the user once created (origin pool, buffer start
607  * address, and so on). This function is given as a callback function to
608  * rte_mempool_create() at pool creation time.
609  *
610  * @param mp
611  *   The mempool from which mbufs originate.
612  * @param opaque_arg
613  *   A pointer that can be used by the user to retrieve useful information
614  *   for mbuf initialization. This pointer comes from the ``init_arg``
615  *   parameter of rte_mempool_create().
616  * @param m
617  *   The mbuf to initialize.
618  * @param i
619  *   The index of the mbuf in the pool table.
620  */
621 void rte_pktmbuf_init(struct rte_mempool *mp, void *opaque_arg,
622                       void *m, unsigned i);
623
624
625 /**
626  * A  packet mbuf pool constructor.
627  *
628  * This function initializes the mempool private data in the case of a
629  * pktmbuf pool. This private data is needed by the driver. The
630  * function is given as a callback function to rte_mempool_create() at
631  * pool creation. It can be extended by the user, for example, to
632  * provide another packet size.
633  *
634  * @param mp
635  *   The mempool from which mbufs originate.
636  * @param opaque_arg
637  *   A pointer that can be used by the user to retrieve useful information
638  *   for mbuf initialization. This pointer comes from the ``init_arg``
639  *   parameter of rte_mempool_create().
640  */
641 void rte_pktmbuf_pool_init(struct rte_mempool *mp, void *opaque_arg);
642
643 /**
644  * Reset the fields of a packet mbuf to their default values.
645  *
646  * The given mbuf must have only one segment.
647  *
648  * @param m
649  *   The packet mbuf to be resetted.
650  */
651 static inline void rte_pktmbuf_reset(struct rte_mbuf *m)
652 {
653         m->next = NULL;
654         m->pkt_len = 0;
655         m->tx_offload = 0;
656         m->vlan_tci = 0;
657         m->nb_segs = 1;
658         m->port = 0xff;
659
660         m->ol_flags = 0;
661         m->packet_type = 0;
662         m->data_off = (RTE_PKTMBUF_HEADROOM <= m->buf_len) ?
663                         RTE_PKTMBUF_HEADROOM : m->buf_len;
664
665         m->data_len = 0;
666         __rte_mbuf_sanity_check(m, 1);
667 }
668
669 /**
670  * Allocate a new mbuf from a mempool.
671  *
672  * This new mbuf contains one segment, which has a length of 0. The pointer
673  * to data is initialized to have some bytes of headroom in the buffer
674  * (if buffer size allows).
675  *
676  * @param mp
677  *   The mempool from which the mbuf is allocated.
678  * @return
679  *   - The pointer to the new mbuf on success.
680  *   - NULL if allocation failed.
681  */
682 static inline struct rte_mbuf *rte_pktmbuf_alloc(struct rte_mempool *mp)
683 {
684         struct rte_mbuf *m;
685         if ((m = __rte_mbuf_raw_alloc(mp)) != NULL)
686                 rte_pktmbuf_reset(m);
687         return (m);
688 }
689
690 /**
691  * Attach packet mbuf to another packet mbuf.
692  * After attachment we refer the mbuf we attached as 'indirect',
693  * while mbuf we attached to as 'direct'.
694  * Right now, not supported:
695  *  - attachment to indirect mbuf (e.g. - md  has to be direct).
696  *  - attachment for already indirect mbuf (e.g. - mi has to be direct).
697  *  - mbuf we trying to attach (mi) is used by someone else
698  *    e.g. it's reference counter is greater then 1.
699  *
700  * @param mi
701  *   The indirect packet mbuf.
702  * @param md
703  *   The direct packet mbuf.
704  */
705
706 static inline void rte_pktmbuf_attach(struct rte_mbuf *mi, struct rte_mbuf *md)
707 {
708         RTE_MBUF_ASSERT(RTE_MBUF_DIRECT(md) &&
709             RTE_MBUF_DIRECT(mi) &&
710             rte_mbuf_refcnt_read(mi) == 1);
711
712         rte_mbuf_refcnt_update(md, 1);
713         mi->buf_physaddr = md->buf_physaddr;
714         mi->buf_addr = md->buf_addr;
715         mi->buf_len = md->buf_len;
716
717         mi->next = md->next;
718         mi->data_off = md->data_off;
719         mi->data_len = md->data_len;
720         mi->port = md->port;
721         mi->vlan_tci = md->vlan_tci;
722         mi->tx_offload = md->tx_offload;
723         mi->hash = md->hash;
724
725         mi->next = NULL;
726         mi->pkt_len = mi->data_len;
727         mi->nb_segs = 1;
728         mi->ol_flags = md->ol_flags | IND_ATTACHED_MBUF;
729         mi->packet_type = md->packet_type;
730
731         __rte_mbuf_sanity_check(mi, 1);
732         __rte_mbuf_sanity_check(md, 0);
733 }
734
735 /**
736  * Detach an indirect packet mbuf -
737  *  - restore original mbuf address and length values.
738  *  - reset pktmbuf data and data_len to their default values.
739  *  All other fields of the given packet mbuf will be left intact.
740  *
741  * @param m
742  *   The indirect attached packet mbuf.
743  */
744
745 static inline void rte_pktmbuf_detach(struct rte_mbuf *m)
746 {
747         const struct rte_mempool *mp = m->pool;
748         void *buf = RTE_MBUF_TO_BADDR(m);
749         uint32_t buf_len = mp->elt_size - sizeof(*m);
750         m->buf_physaddr = rte_mempool_virt2phy(mp, m) + sizeof (*m);
751
752         m->buf_addr = buf;
753         m->buf_len = (uint16_t)buf_len;
754
755         m->data_off = (RTE_PKTMBUF_HEADROOM <= m->buf_len) ?
756                         RTE_PKTMBUF_HEADROOM : m->buf_len;
757
758         m->data_len = 0;
759
760         m->ol_flags = 0;
761 }
762
763 static inline struct rte_mbuf* __attribute__((always_inline))
764 __rte_pktmbuf_prefree_seg(struct rte_mbuf *m)
765 {
766         __rte_mbuf_sanity_check(m, 0);
767
768         /*
769          * Check to see if this is the last reference to the mbuf.
770          * Note: the double check here is deliberate. If the ref_cnt is "atomic"
771          * the call to "refcnt_update" is a very expensive operation, so we
772          * don't want to call it in the case where we know we are the holder
773          * of the last reference to this mbuf i.e. ref_cnt == 1.
774          * If however, ref_cnt != 1, it's still possible that we may still be
775          * the final decrementer of the count, so we need to check that
776          * result also, to make sure the mbuf is freed properly.
777          */
778         if (likely (rte_mbuf_refcnt_read(m) == 1) ||
779                         likely (rte_mbuf_refcnt_update(m, -1) == 0)) {
780
781                 rte_mbuf_refcnt_set(m, 0);
782
783                 /* if this is an indirect mbuf, then
784                  *  - detach mbuf
785                  *  - free attached mbuf segment
786                  */
787                 if (RTE_MBUF_INDIRECT(m)) {
788                         struct rte_mbuf *md = RTE_MBUF_FROM_BADDR(m->buf_addr);
789                         rte_pktmbuf_detach(m);
790                         if (rte_mbuf_refcnt_update(md, -1) == 0)
791                                 __rte_mbuf_raw_free(md);
792                 }
793                 return(m);
794         }
795         return (NULL);
796 }
797
798 /**
799  * Free a segment of a packet mbuf into its original mempool.
800  *
801  * Free an mbuf, without parsing other segments in case of chained
802  * buffers.
803  *
804  * @param m
805  *   The packet mbuf segment to be freed.
806  */
807 static inline void __attribute__((always_inline))
808 rte_pktmbuf_free_seg(struct rte_mbuf *m)
809 {
810         if (likely(NULL != (m = __rte_pktmbuf_prefree_seg(m)))) {
811                 m->next = NULL;
812                 __rte_mbuf_raw_free(m);
813         }
814 }
815
816 /**
817  * Free a packet mbuf back into its original mempool.
818  *
819  * Free an mbuf, and all its segments in case of chained buffers. Each
820  * segment is added back into its original mempool.
821  *
822  * @param m
823  *   The packet mbuf to be freed.
824  */
825 static inline void rte_pktmbuf_free(struct rte_mbuf *m)
826 {
827         struct rte_mbuf *m_next;
828
829         __rte_mbuf_sanity_check(m, 1);
830
831         while (m != NULL) {
832                 m_next = m->next;
833                 rte_pktmbuf_free_seg(m);
834                 m = m_next;
835         }
836 }
837
838 /**
839  * Creates a "clone" of the given packet mbuf.
840  *
841  * Walks through all segments of the given packet mbuf, and for each of them:
842  *  - Creates a new packet mbuf from the given pool.
843  *  - Attaches newly created mbuf to the segment.
844  * Then updates pkt_len and nb_segs of the "clone" packet mbuf to match values
845  * from the original packet mbuf.
846  *
847  * @param md
848  *   The packet mbuf to be cloned.
849  * @param mp
850  *   The mempool from which the "clone" mbufs are allocated.
851  * @return
852  *   - The pointer to the new "clone" mbuf on success.
853  *   - NULL if allocation fails.
854  */
855 static inline struct rte_mbuf *rte_pktmbuf_clone(struct rte_mbuf *md,
856                 struct rte_mempool *mp)
857 {
858         struct rte_mbuf *mc, *mi, **prev;
859         uint32_t pktlen;
860         uint8_t nseg;
861
862         if (unlikely ((mc = rte_pktmbuf_alloc(mp)) == NULL))
863                 return (NULL);
864
865         mi = mc;
866         prev = &mi->next;
867         pktlen = md->pkt_len;
868         nseg = 0;
869
870         do {
871                 nseg++;
872                 rte_pktmbuf_attach(mi, md);
873                 *prev = mi;
874                 prev = &mi->next;
875         } while ((md = md->next) != NULL &&
876             (mi = rte_pktmbuf_alloc(mp)) != NULL);
877
878         *prev = NULL;
879         mc->nb_segs = nseg;
880         mc->pkt_len = pktlen;
881
882         /* Allocation of new indirect segment failed */
883         if (unlikely (mi == NULL)) {
884                 rte_pktmbuf_free(mc);
885                 return (NULL);
886         }
887
888         __rte_mbuf_sanity_check(mc, 1);
889         return (mc);
890 }
891
892 /**
893  * Adds given value to the refcnt of all packet mbuf segments.
894  *
895  * Walks through all segments of given packet mbuf and for each of them
896  * invokes rte_mbuf_refcnt_update().
897  *
898  * @param m
899  *   The packet mbuf whose refcnt to be updated.
900  * @param v
901  *   The value to add to the mbuf's segments refcnt.
902  */
903 static inline void rte_pktmbuf_refcnt_update(struct rte_mbuf *m, int16_t v)
904 {
905         __rte_mbuf_sanity_check(m, 1);
906
907         do {
908                 rte_mbuf_refcnt_update(m, v);
909         } while ((m = m->next) != NULL);
910 }
911
912 /**
913  * Get the headroom in a packet mbuf.
914  *
915  * @param m
916  *   The packet mbuf.
917  * @return
918  *   The length of the headroom.
919  */
920 static inline uint16_t rte_pktmbuf_headroom(const struct rte_mbuf *m)
921 {
922         __rte_mbuf_sanity_check(m, 1);
923         return m->data_off;
924 }
925
926 /**
927  * Get the tailroom of a packet mbuf.
928  *
929  * @param m
930  *   The packet mbuf.
931  * @return
932  *   The length of the tailroom.
933  */
934 static inline uint16_t rte_pktmbuf_tailroom(const struct rte_mbuf *m)
935 {
936         __rte_mbuf_sanity_check(m, 1);
937         return (uint16_t)(m->buf_len - rte_pktmbuf_headroom(m) -
938                           m->data_len);
939 }
940
941 /**
942  * Get the last segment of the packet.
943  *
944  * @param m
945  *   The packet mbuf.
946  * @return
947  *   The last segment of the given mbuf.
948  */
949 static inline struct rte_mbuf *rte_pktmbuf_lastseg(struct rte_mbuf *m)
950 {
951         struct rte_mbuf *m2 = (struct rte_mbuf *)m;
952
953         __rte_mbuf_sanity_check(m, 1);
954         while (m2->next != NULL)
955                 m2 = m2->next;
956         return m2;
957 }
958
959 /**
960  * A macro that points to the start of the data in the mbuf.
961  *
962  * The returned pointer is cast to type t. Before using this
963  * function, the user must ensure that m_headlen(m) is large enough to
964  * read its data.
965  *
966  * @param m
967  *   The packet mbuf.
968  * @param t
969  *   The type to cast the result into.
970  */
971 #define rte_pktmbuf_mtod(m, t) ((t)((char *)(m)->buf_addr + (m)->data_off))
972
973 /**
974  * A macro that returns the length of the packet.
975  *
976  * The value can be read or assigned.
977  *
978  * @param m
979  *   The packet mbuf.
980  */
981 #define rte_pktmbuf_pkt_len(m) ((m)->pkt_len)
982
983 /**
984  * A macro that returns the length of the segment.
985  *
986  * The value can be read or assigned.
987  *
988  * @param m
989  *   The packet mbuf.
990  */
991 #define rte_pktmbuf_data_len(m) ((m)->data_len)
992
993 /**
994  * Prepend len bytes to an mbuf data area.
995  *
996  * Returns a pointer to the new
997  * data start address. If there is not enough headroom in the first
998  * segment, the function will return NULL, without modifying the mbuf.
999  *
1000  * @param m
1001  *   The pkt mbuf.
1002  * @param len
1003  *   The amount of data to prepend (in bytes).
1004  * @return
1005  *   A pointer to the start of the newly prepended data, or
1006  *   NULL if there is not enough headroom space in the first segment
1007  */
1008 static inline char *rte_pktmbuf_prepend(struct rte_mbuf *m,
1009                                         uint16_t len)
1010 {
1011         __rte_mbuf_sanity_check(m, 1);
1012
1013         if (unlikely(len > rte_pktmbuf_headroom(m)))
1014                 return NULL;
1015
1016         m->data_off -= len;
1017         m->data_len = (uint16_t)(m->data_len + len);
1018         m->pkt_len  = (m->pkt_len + len);
1019
1020         return (char *)m->buf_addr + m->data_off;
1021 }
1022
1023 /**
1024  * Append len bytes to an mbuf.
1025  *
1026  * Append len bytes to an mbuf and return a pointer to the start address
1027  * of the added data. If there is not enough tailroom in the last
1028  * segment, the function will return NULL, without modifying the mbuf.
1029  *
1030  * @param m
1031  *   The packet mbuf.
1032  * @param len
1033  *   The amount of data to append (in bytes).
1034  * @return
1035  *   A pointer to the start of the newly appended data, or
1036  *   NULL if there is not enough tailroom space in the last segment
1037  */
1038 static inline char *rte_pktmbuf_append(struct rte_mbuf *m, uint16_t len)
1039 {
1040         void *tail;
1041         struct rte_mbuf *m_last;
1042
1043         __rte_mbuf_sanity_check(m, 1);
1044
1045         m_last = rte_pktmbuf_lastseg(m);
1046         if (unlikely(len > rte_pktmbuf_tailroom(m_last)))
1047                 return NULL;
1048
1049         tail = (char *)m_last->buf_addr + m_last->data_off + m_last->data_len;
1050         m_last->data_len = (uint16_t)(m_last->data_len + len);
1051         m->pkt_len  = (m->pkt_len + len);
1052         return (char*) tail;
1053 }
1054
1055 /**
1056  * Remove len bytes at the beginning of an mbuf.
1057  *
1058  * Returns a pointer to the start address of the new data area. If the
1059  * length is greater than the length of the first segment, then the
1060  * function will fail and return NULL, without modifying the mbuf.
1061  *
1062  * @param m
1063  *   The packet mbuf.
1064  * @param len
1065  *   The amount of data to remove (in bytes).
1066  * @return
1067  *   A pointer to the new start of the data.
1068  */
1069 static inline char *rte_pktmbuf_adj(struct rte_mbuf *m, uint16_t len)
1070 {
1071         __rte_mbuf_sanity_check(m, 1);
1072
1073         if (unlikely(len > m->data_len))
1074                 return NULL;
1075
1076         m->data_len = (uint16_t)(m->data_len - len);
1077         m->data_off += len;
1078         m->pkt_len  = (m->pkt_len - len);
1079         return (char *)m->buf_addr + m->data_off;
1080 }
1081
1082 /**
1083  * Remove len bytes of data at the end of the mbuf.
1084  *
1085  * If the length is greater than the length of the last segment, the
1086  * function will fail and return -1 without modifying the mbuf.
1087  *
1088  * @param m
1089  *   The packet mbuf.
1090  * @param len
1091  *   The amount of data to remove (in bytes).
1092  * @return
1093  *   - 0: On success.
1094  *   - -1: On error.
1095  */
1096 static inline int rte_pktmbuf_trim(struct rte_mbuf *m, uint16_t len)
1097 {
1098         struct rte_mbuf *m_last;
1099
1100         __rte_mbuf_sanity_check(m, 1);
1101
1102         m_last = rte_pktmbuf_lastseg(m);
1103         if (unlikely(len > m_last->data_len))
1104                 return -1;
1105
1106         m_last->data_len = (uint16_t)(m_last->data_len - len);
1107         m->pkt_len  = (m->pkt_len - len);
1108         return 0;
1109 }
1110
1111 /**
1112  * Test if mbuf data is contiguous.
1113  *
1114  * @param m
1115  *   The packet mbuf.
1116  * @return
1117  *   - 1, if all data is contiguous (one segment).
1118  *   - 0, if there is several segments.
1119  */
1120 static inline int rte_pktmbuf_is_contiguous(const struct rte_mbuf *m)
1121 {
1122         __rte_mbuf_sanity_check(m, 1);
1123         return !!(m->nb_segs == 1);
1124 }
1125
1126 /**
1127  * Dump an mbuf structure to the console.
1128  *
1129  * Dump all fields for the given packet mbuf and all its associated
1130  * segments (in the case of a chained buffer).
1131  *
1132  * @param f
1133  *   A pointer to a file for output
1134  * @param m
1135  *   The packet mbuf.
1136  * @param dump_len
1137  *   If dump_len != 0, also dump the "dump_len" first data bytes of
1138  *   the packet.
1139  */
1140 void rte_pktmbuf_dump(FILE *f, const struct rte_mbuf *m, unsigned dump_len);
1141
1142 #ifdef __cplusplus
1143 }
1144 #endif
1145
1146 #endif /* _RTE_MBUF_H_ */