mbuf: remove deprecated timestamp field
[dpdk.git] / lib / librte_mbuf / rte_mbuf.h
1 /* SPDX-License-Identifier: BSD-3-Clause
2  * Copyright(c) 2010-2014 Intel Corporation.
3  * Copyright 2014 6WIND S.A.
4  */
5
6 #ifndef _RTE_MBUF_H_
7 #define _RTE_MBUF_H_
8
9 /**
10  * @file
11  * RTE Mbuf
12  *
13  * The mbuf library provides the ability to create and destroy buffers
14  * that may be used by the RTE application to store message
15  * buffers. The message buffers are stored in a mempool, using the
16  * RTE mempool library.
17  *
18  * The preferred way to create a mbuf pool is to use
19  * rte_pktmbuf_pool_create(). However, in some situations, an
20  * application may want to have more control (ex: populate the pool with
21  * specific memory), in this case it is possible to use functions from
22  * rte_mempool. See how rte_pktmbuf_pool_create() is implemented for
23  * details.
24  *
25  * This library provides an API to allocate/free packet mbufs, which are
26  * used to carry network packets.
27  *
28  * To understand the concepts of packet buffers or mbufs, you
29  * should read "TCP/IP Illustrated, Volume 2: The Implementation,
30  * Addison-Wesley, 1995, ISBN 0-201-63354-X from Richard Stevens"
31  * http://www.kohala.com/start/tcpipiv2.html
32  */
33
34 #include <stdint.h>
35 #include <rte_compat.h>
36 #include <rte_common.h>
37 #include <rte_config.h>
38 #include <rte_mempool.h>
39 #include <rte_memory.h>
40 #include <rte_prefetch.h>
41 #include <rte_branch_prediction.h>
42 #include <rte_byteorder.h>
43 #include <rte_mbuf_ptype.h>
44 #include <rte_mbuf_core.h>
45
46 #ifdef __cplusplus
47 extern "C" {
48 #endif
49
50 /**
51  * Get the name of a RX offload flag
52  *
53  * @param mask
54  *   The mask describing the flag.
55  * @return
56  *   The name of this flag, or NULL if it's not a valid RX flag.
57  */
58 const char *rte_get_rx_ol_flag_name(uint64_t mask);
59
60 /**
61  * Dump the list of RX offload flags in a buffer
62  *
63  * @param mask
64  *   The mask describing the RX flags.
65  * @param buf
66  *   The output buffer.
67  * @param buflen
68  *   The length of the buffer.
69  * @return
70  *   0 on success, (-1) on error.
71  */
72 int rte_get_rx_ol_flag_list(uint64_t mask, char *buf, size_t buflen);
73
74 /**
75  * Get the name of a TX offload flag
76  *
77  * @param mask
78  *   The mask describing the flag. Usually only one bit must be set.
79  *   Several bits can be given if they belong to the same mask.
80  *   Ex: PKT_TX_L4_MASK.
81  * @return
82  *   The name of this flag, or NULL if it's not a valid TX flag.
83  */
84 const char *rte_get_tx_ol_flag_name(uint64_t mask);
85
86 /**
87  * Dump the list of TX offload flags in a buffer
88  *
89  * @param mask
90  *   The mask describing the TX flags.
91  * @param buf
92  *   The output buffer.
93  * @param buflen
94  *   The length of the buffer.
95  * @return
96  *   0 on success, (-1) on error.
97  */
98 int rte_get_tx_ol_flag_list(uint64_t mask, char *buf, size_t buflen);
99
100 /**
101  * Prefetch the first part of the mbuf
102  *
103  * The first 64 bytes of the mbuf corresponds to fields that are used early
104  * in the receive path. If the cache line of the architecture is higher than
105  * 64B, the second part will also be prefetched.
106  *
107  * @param m
108  *   The pointer to the mbuf.
109  */
110 static inline void
111 rte_mbuf_prefetch_part1(struct rte_mbuf *m)
112 {
113         rte_prefetch0(&m->cacheline0);
114 }
115
116 /**
117  * Prefetch the second part of the mbuf
118  *
119  * The next 64 bytes of the mbuf corresponds to fields that are used in the
120  * transmit path. If the cache line of the architecture is higher than 64B,
121  * this function does nothing as it is expected that the full mbuf is
122  * already in cache.
123  *
124  * @param m
125  *   The pointer to the mbuf.
126  */
127 static inline void
128 rte_mbuf_prefetch_part2(struct rte_mbuf *m)
129 {
130 #if RTE_CACHE_LINE_SIZE == 64
131         rte_prefetch0(&m->cacheline1);
132 #else
133         RTE_SET_USED(m);
134 #endif
135 }
136
137
138 static inline uint16_t rte_pktmbuf_priv_size(struct rte_mempool *mp);
139
140 /**
141  * Return the IO address of the beginning of the mbuf data
142  *
143  * @param mb
144  *   The pointer to the mbuf.
145  * @return
146  *   The IO address of the beginning of the mbuf data
147  */
148 static inline rte_iova_t
149 rte_mbuf_data_iova(const struct rte_mbuf *mb)
150 {
151         return mb->buf_iova + mb->data_off;
152 }
153
154 /**
155  * Return the default IO address of the beginning of the mbuf data
156  *
157  * This function is used by drivers in their receive function, as it
158  * returns the location where data should be written by the NIC, taking
159  * the default headroom in account.
160  *
161  * @param mb
162  *   The pointer to the mbuf.
163  * @return
164  *   The IO address of the beginning of the mbuf data
165  */
166 static inline rte_iova_t
167 rte_mbuf_data_iova_default(const struct rte_mbuf *mb)
168 {
169         return mb->buf_iova + RTE_PKTMBUF_HEADROOM;
170 }
171
172 /**
173  * Return the mbuf owning the data buffer address of an indirect mbuf.
174  *
175  * @param mi
176  *   The pointer to the indirect mbuf.
177  * @return
178  *   The address of the direct mbuf corresponding to buffer_addr.
179  */
180 static inline struct rte_mbuf *
181 rte_mbuf_from_indirect(struct rte_mbuf *mi)
182 {
183         return (struct rte_mbuf *)RTE_PTR_SUB(mi->buf_addr, sizeof(*mi) + mi->priv_size);
184 }
185
186 /**
187  * Return address of buffer embedded in the given mbuf.
188  *
189  * The return value shall be same as mb->buf_addr if the mbuf is already
190  * initialized and direct. However, this API is useful if mempool of the
191  * mbuf is already known because it doesn't need to access mbuf contents in
192  * order to get the mempool pointer.
193  *
194  * @warning
195  * @b EXPERIMENTAL: This API may change without prior notice.
196  * This will be used by rte_mbuf_to_baddr() which has redundant code once
197  * experimental tag is removed.
198  *
199  * @param mb
200  *   The pointer to the mbuf.
201  * @param mp
202  *   The pointer to the mempool of the mbuf.
203  * @return
204  *   The pointer of the mbuf buffer.
205  */
206 __rte_experimental
207 static inline char *
208 rte_mbuf_buf_addr(struct rte_mbuf *mb, struct rte_mempool *mp)
209 {
210         return (char *)mb + sizeof(*mb) + rte_pktmbuf_priv_size(mp);
211 }
212
213 /**
214  * Return the default address of the beginning of the mbuf data.
215  *
216  * @warning
217  * @b EXPERIMENTAL: This API may change without prior notice.
218  *
219  * @param mb
220  *   The pointer to the mbuf.
221  * @return
222  *   The pointer of the beginning of the mbuf data.
223  */
224 __rte_experimental
225 static inline char *
226 rte_mbuf_data_addr_default(__rte_unused struct rte_mbuf *mb)
227 {
228         /* gcc complains about calling this experimental function even
229          * when not using it. Hide it with ALLOW_EXPERIMENTAL_API.
230          */
231 #ifdef ALLOW_EXPERIMENTAL_API
232         return rte_mbuf_buf_addr(mb, mb->pool) + RTE_PKTMBUF_HEADROOM;
233 #else
234         return NULL;
235 #endif
236 }
237
238 /**
239  * Return address of buffer embedded in the given mbuf.
240  *
241  * @note: Accessing mempool pointer of a mbuf is expensive because the
242  * pointer is stored in the 2nd cache line of mbuf. If mempool is known, it
243  * is better not to reference the mempool pointer in mbuf but calling
244  * rte_mbuf_buf_addr() would be more efficient.
245  *
246  * @param md
247  *   The pointer to the mbuf.
248  * @return
249  *   The address of the data buffer owned by the mbuf.
250  */
251 static inline char *
252 rte_mbuf_to_baddr(struct rte_mbuf *md)
253 {
254 #ifdef ALLOW_EXPERIMENTAL_API
255         return rte_mbuf_buf_addr(md, md->pool);
256 #else
257         char *buffer_addr;
258         buffer_addr = (char *)md + sizeof(*md) + rte_pktmbuf_priv_size(md->pool);
259         return buffer_addr;
260 #endif
261 }
262
263 /**
264  * Return the starting address of the private data area embedded in
265  * the given mbuf.
266  *
267  * Note that no check is made to ensure that a private data area
268  * actually exists in the supplied mbuf.
269  *
270  * @param m
271  *   The pointer to the mbuf.
272  * @return
273  *   The starting address of the private data area of the given mbuf.
274  */
275 __rte_experimental
276 static inline void *
277 rte_mbuf_to_priv(struct rte_mbuf *m)
278 {
279         return RTE_PTR_ADD(m, sizeof(struct rte_mbuf));
280 }
281
282 /**
283  * Private data in case of pktmbuf pool.
284  *
285  * A structure that contains some pktmbuf_pool-specific data that are
286  * appended after the mempool structure (in private data).
287  */
288 struct rte_pktmbuf_pool_private {
289         uint16_t mbuf_data_room_size; /**< Size of data space in each mbuf. */
290         uint16_t mbuf_priv_size;      /**< Size of private area in each mbuf. */
291         uint32_t flags; /**< reserved for future use. */
292 };
293
294 /**
295  * Return the flags from private data in an mempool structure.
296  *
297  * @param mp
298  *   A pointer to the mempool structure.
299  * @return
300  *   The flags from the private data structure.
301  */
302 static inline uint32_t
303 rte_pktmbuf_priv_flags(struct rte_mempool *mp)
304 {
305         struct rte_pktmbuf_pool_private *mbp_priv;
306
307         mbp_priv = (struct rte_pktmbuf_pool_private *)rte_mempool_get_priv(mp);
308         return mbp_priv->flags;
309 }
310
311 /**
312  * When set, pktmbuf mempool will hold only mbufs with pinned external
313  * buffer. The external buffer will be attached to the mbuf at the
314  * memory pool creation and will never be detached by the mbuf free calls.
315  * mbuf should not contain any room for data after the mbuf structure.
316  */
317 #define RTE_PKTMBUF_POOL_F_PINNED_EXT_BUF (1 << 0)
318
319 /**
320  * Returns non zero if given mbuf has a pinned external buffer, or zero
321  * otherwise. The pinned external buffer is allocated at pool creation
322  * time and should not be freed on mbuf freeing.
323  *
324  * External buffer is a user-provided anonymous buffer.
325  */
326 #define RTE_MBUF_HAS_PINNED_EXTBUF(mb) \
327         (rte_pktmbuf_priv_flags(mb->pool) & RTE_PKTMBUF_POOL_F_PINNED_EXT_BUF)
328
329 #ifdef RTE_LIBRTE_MBUF_DEBUG
330
331 /**  check mbuf type in debug mode */
332 #define __rte_mbuf_sanity_check(m, is_h) rte_mbuf_sanity_check(m, is_h)
333
334 #else /*  RTE_LIBRTE_MBUF_DEBUG */
335
336 /**  check mbuf type in debug mode */
337 #define __rte_mbuf_sanity_check(m, is_h) do { } while (0)
338
339 #endif /*  RTE_LIBRTE_MBUF_DEBUG */
340
341 #ifdef RTE_MBUF_REFCNT_ATOMIC
342
343 /**
344  * Reads the value of an mbuf's refcnt.
345  * @param m
346  *   Mbuf to read
347  * @return
348  *   Reference count number.
349  */
350 static inline uint16_t
351 rte_mbuf_refcnt_read(const struct rte_mbuf *m)
352 {
353         return __atomic_load_n(&m->refcnt, __ATOMIC_RELAXED);
354 }
355
356 /**
357  * Sets an mbuf's refcnt to a defined value.
358  * @param m
359  *   Mbuf to update
360  * @param new_value
361  *   Value set
362  */
363 static inline void
364 rte_mbuf_refcnt_set(struct rte_mbuf *m, uint16_t new_value)
365 {
366         __atomic_store_n(&m->refcnt, new_value, __ATOMIC_RELAXED);
367 }
368
369 /* internal */
370 static inline uint16_t
371 __rte_mbuf_refcnt_update(struct rte_mbuf *m, int16_t value)
372 {
373         return __atomic_add_fetch(&m->refcnt, (uint16_t)value,
374                                  __ATOMIC_ACQ_REL);
375 }
376
377 /**
378  * Adds given value to an mbuf's refcnt and returns its new value.
379  * @param m
380  *   Mbuf to update
381  * @param value
382  *   Value to add/subtract
383  * @return
384  *   Updated value
385  */
386 static inline uint16_t
387 rte_mbuf_refcnt_update(struct rte_mbuf *m, int16_t value)
388 {
389         /*
390          * The atomic_add is an expensive operation, so we don't want to
391          * call it in the case where we know we are the unique holder of
392          * this mbuf (i.e. ref_cnt == 1). Otherwise, an atomic
393          * operation has to be used because concurrent accesses on the
394          * reference counter can occur.
395          */
396         if (likely(rte_mbuf_refcnt_read(m) == 1)) {
397                 ++value;
398                 rte_mbuf_refcnt_set(m, (uint16_t)value);
399                 return (uint16_t)value;
400         }
401
402         return __rte_mbuf_refcnt_update(m, value);
403 }
404
405 #else /* ! RTE_MBUF_REFCNT_ATOMIC */
406
407 /* internal */
408 static inline uint16_t
409 __rte_mbuf_refcnt_update(struct rte_mbuf *m, int16_t value)
410 {
411         m->refcnt = (uint16_t)(m->refcnt + value);
412         return m->refcnt;
413 }
414
415 /**
416  * Adds given value to an mbuf's refcnt and returns its new value.
417  */
418 static inline uint16_t
419 rte_mbuf_refcnt_update(struct rte_mbuf *m, int16_t value)
420 {
421         return __rte_mbuf_refcnt_update(m, value);
422 }
423
424 /**
425  * Reads the value of an mbuf's refcnt.
426  */
427 static inline uint16_t
428 rte_mbuf_refcnt_read(const struct rte_mbuf *m)
429 {
430         return m->refcnt;
431 }
432
433 /**
434  * Sets an mbuf's refcnt to the defined value.
435  */
436 static inline void
437 rte_mbuf_refcnt_set(struct rte_mbuf *m, uint16_t new_value)
438 {
439         m->refcnt = new_value;
440 }
441
442 #endif /* RTE_MBUF_REFCNT_ATOMIC */
443
444 /**
445  * Reads the refcnt of an external buffer.
446  *
447  * @param shinfo
448  *   Shared data of the external buffer.
449  * @return
450  *   Reference count number.
451  */
452 static inline uint16_t
453 rte_mbuf_ext_refcnt_read(const struct rte_mbuf_ext_shared_info *shinfo)
454 {
455         return __atomic_load_n(&shinfo->refcnt, __ATOMIC_RELAXED);
456 }
457
458 /**
459  * Set refcnt of an external buffer.
460  *
461  * @param shinfo
462  *   Shared data of the external buffer.
463  * @param new_value
464  *   Value set
465  */
466 static inline void
467 rte_mbuf_ext_refcnt_set(struct rte_mbuf_ext_shared_info *shinfo,
468         uint16_t new_value)
469 {
470         __atomic_store_n(&shinfo->refcnt, new_value, __ATOMIC_RELAXED);
471 }
472
473 /**
474  * Add given value to refcnt of an external buffer and return its new
475  * value.
476  *
477  * @param shinfo
478  *   Shared data of the external buffer.
479  * @param value
480  *   Value to add/subtract
481  * @return
482  *   Updated value
483  */
484 static inline uint16_t
485 rte_mbuf_ext_refcnt_update(struct rte_mbuf_ext_shared_info *shinfo,
486         int16_t value)
487 {
488         if (likely(rte_mbuf_ext_refcnt_read(shinfo) == 1)) {
489                 ++value;
490                 rte_mbuf_ext_refcnt_set(shinfo, (uint16_t)value);
491                 return (uint16_t)value;
492         }
493
494         return __atomic_add_fetch(&shinfo->refcnt, (uint16_t)value,
495                                  __ATOMIC_ACQ_REL);
496 }
497
498 /** Mbuf prefetch */
499 #define RTE_MBUF_PREFETCH_TO_FREE(m) do {       \
500         if ((m) != NULL)                        \
501                 rte_prefetch0(m);               \
502 } while (0)
503
504
505 /**
506  * Sanity checks on an mbuf.
507  *
508  * Check the consistency of the given mbuf. The function will cause a
509  * panic if corruption is detected.
510  *
511  * @param m
512  *   The mbuf to be checked.
513  * @param is_header
514  *   True if the mbuf is a packet header, false if it is a sub-segment
515  *   of a packet (in this case, some fields like nb_segs are not checked)
516  */
517 void
518 rte_mbuf_sanity_check(const struct rte_mbuf *m, int is_header);
519
520 /**
521  * Sanity checks on a mbuf.
522  *
523  * Almost like rte_mbuf_sanity_check(), but this function gives the reason
524  * if corruption is detected rather than panic.
525  *
526  * @param m
527  *   The mbuf to be checked.
528  * @param is_header
529  *   True if the mbuf is a packet header, false if it is a sub-segment
530  *   of a packet (in this case, some fields like nb_segs are not checked)
531  * @param reason
532  *   A reference to a string pointer where to store the reason why a mbuf is
533  *   considered invalid.
534  * @return
535  *   - 0 if no issue has been found, reason is left untouched.
536  *   - -1 if a problem is detected, reason then points to a string describing
537  *     the reason why the mbuf is deemed invalid.
538  */
539 __rte_experimental
540 int rte_mbuf_check(const struct rte_mbuf *m, int is_header,
541                    const char **reason);
542
543 #define MBUF_RAW_ALLOC_CHECK(m) do {                            \
544         RTE_ASSERT(rte_mbuf_refcnt_read(m) == 1);               \
545         RTE_ASSERT((m)->next == NULL);                          \
546         RTE_ASSERT((m)->nb_segs == 1);                          \
547         __rte_mbuf_sanity_check(m, 0);                          \
548 } while (0)
549
550 /**
551  * Allocate an uninitialized mbuf from mempool *mp*.
552  *
553  * This function can be used by PMDs (especially in RX functions) to
554  * allocate an uninitialized mbuf. The driver is responsible of
555  * initializing all the required fields. See rte_pktmbuf_reset().
556  * For standard needs, prefer rte_pktmbuf_alloc().
557  *
558  * The caller can expect that the following fields of the mbuf structure
559  * are initialized: buf_addr, buf_iova, buf_len, refcnt=1, nb_segs=1,
560  * next=NULL, pool, priv_size. The other fields must be initialized
561  * by the caller.
562  *
563  * @param mp
564  *   The mempool from which mbuf is allocated.
565  * @return
566  *   - The pointer to the new mbuf on success.
567  *   - NULL if allocation failed.
568  */
569 static inline struct rte_mbuf *rte_mbuf_raw_alloc(struct rte_mempool *mp)
570 {
571         struct rte_mbuf *m;
572
573         if (rte_mempool_get(mp, (void **)&m) < 0)
574                 return NULL;
575         MBUF_RAW_ALLOC_CHECK(m);
576         return m;
577 }
578
579 /**
580  * Put mbuf back into its original mempool.
581  *
582  * The caller must ensure that the mbuf is direct and properly
583  * reinitialized (refcnt=1, next=NULL, nb_segs=1), as done by
584  * rte_pktmbuf_prefree_seg().
585  *
586  * This function should be used with care, when optimization is
587  * required. For standard needs, prefer rte_pktmbuf_free() or
588  * rte_pktmbuf_free_seg().
589  *
590  * @param m
591  *   The mbuf to be freed.
592  */
593 static __rte_always_inline void
594 rte_mbuf_raw_free(struct rte_mbuf *m)
595 {
596         RTE_ASSERT(!RTE_MBUF_CLONED(m) &&
597                   (!RTE_MBUF_HAS_EXTBUF(m) || RTE_MBUF_HAS_PINNED_EXTBUF(m)));
598         RTE_ASSERT(rte_mbuf_refcnt_read(m) == 1);
599         RTE_ASSERT(m->next == NULL);
600         RTE_ASSERT(m->nb_segs == 1);
601         __rte_mbuf_sanity_check(m, 0);
602         rte_mempool_put(m->pool, m);
603 }
604
605 /**
606  * The packet mbuf constructor.
607  *
608  * This function initializes some fields in the mbuf structure that are
609  * not modified by the user once created (origin pool, buffer start
610  * address, and so on). This function is given as a callback function to
611  * rte_mempool_obj_iter() or rte_mempool_create() at pool creation time.
612  *
613  * @param mp
614  *   The mempool from which mbufs originate.
615  * @param opaque_arg
616  *   A pointer that can be used by the user to retrieve useful information
617  *   for mbuf initialization. This pointer is the opaque argument passed to
618  *   rte_mempool_obj_iter() or rte_mempool_create().
619  * @param m
620  *   The mbuf to initialize.
621  * @param i
622  *   The index of the mbuf in the pool table.
623  */
624 void rte_pktmbuf_init(struct rte_mempool *mp, void *opaque_arg,
625                       void *m, unsigned i);
626
627 /**
628  * A  packet mbuf pool constructor.
629  *
630  * This function initializes the mempool private data in the case of a
631  * pktmbuf pool. This private data is needed by the driver. The
632  * function must be called on the mempool before it is used, or it
633  * can be given as a callback function to rte_mempool_create() at
634  * pool creation. It can be extended by the user, for example, to
635  * provide another packet size.
636  *
637  * @param mp
638  *   The mempool from which mbufs originate.
639  * @param opaque_arg
640  *   A pointer that can be used by the user to retrieve useful information
641  *   for mbuf initialization. This pointer is the opaque argument passed to
642  *   rte_mempool_create().
643  */
644 void rte_pktmbuf_pool_init(struct rte_mempool *mp, void *opaque_arg);
645
646 /**
647  * Create a mbuf pool.
648  *
649  * This function creates and initializes a packet mbuf pool. It is
650  * a wrapper to rte_mempool functions.
651  *
652  * @param name
653  *   The name of the mbuf pool.
654  * @param n
655  *   The number of elements in the mbuf pool. The optimum size (in terms
656  *   of memory usage) for a mempool is when n is a power of two minus one:
657  *   n = (2^q - 1).
658  * @param cache_size
659  *   Size of the per-core object cache. See rte_mempool_create() for
660  *   details.
661  * @param priv_size
662  *   Size of application private are between the rte_mbuf structure
663  *   and the data buffer. This value must be aligned to RTE_MBUF_PRIV_ALIGN.
664  * @param data_room_size
665  *   Size of data buffer in each mbuf, including RTE_PKTMBUF_HEADROOM.
666  * @param socket_id
667  *   The socket identifier where the memory should be allocated. The
668  *   value can be *SOCKET_ID_ANY* if there is no NUMA constraint for the
669  *   reserved zone.
670  * @return
671  *   The pointer to the new allocated mempool, on success. NULL on error
672  *   with rte_errno set appropriately. Possible rte_errno values include:
673  *    - E_RTE_NO_CONFIG - function could not get pointer to rte_config structure
674  *    - E_RTE_SECONDARY - function was called from a secondary process instance
675  *    - EINVAL - cache size provided is too large, or priv_size is not aligned.
676  *    - ENOSPC - the maximum number of memzones has already been allocated
677  *    - EEXIST - a memzone with the same name already exists
678  *    - ENOMEM - no appropriate memory area found in which to create memzone
679  */
680 struct rte_mempool *
681 rte_pktmbuf_pool_create(const char *name, unsigned n,
682         unsigned cache_size, uint16_t priv_size, uint16_t data_room_size,
683         int socket_id);
684
685 /**
686  * Create a mbuf pool with a given mempool ops name
687  *
688  * This function creates and initializes a packet mbuf pool. It is
689  * a wrapper to rte_mempool functions.
690  *
691  * @param name
692  *   The name of the mbuf pool.
693  * @param n
694  *   The number of elements in the mbuf pool. The optimum size (in terms
695  *   of memory usage) for a mempool is when n is a power of two minus one:
696  *   n = (2^q - 1).
697  * @param cache_size
698  *   Size of the per-core object cache. See rte_mempool_create() for
699  *   details.
700  * @param priv_size
701  *   Size of application private are between the rte_mbuf structure
702  *   and the data buffer. This value must be aligned to RTE_MBUF_PRIV_ALIGN.
703  * @param data_room_size
704  *   Size of data buffer in each mbuf, including RTE_PKTMBUF_HEADROOM.
705  * @param socket_id
706  *   The socket identifier where the memory should be allocated. The
707  *   value can be *SOCKET_ID_ANY* if there is no NUMA constraint for the
708  *   reserved zone.
709  * @param ops_name
710  *   The mempool ops name to be used for this mempool instead of
711  *   default mempool. The value can be *NULL* to use default mempool.
712  * @return
713  *   The pointer to the new allocated mempool, on success. NULL on error
714  *   with rte_errno set appropriately. Possible rte_errno values include:
715  *    - E_RTE_NO_CONFIG - function could not get pointer to rte_config structure
716  *    - E_RTE_SECONDARY - function was called from a secondary process instance
717  *    - EINVAL - cache size provided is too large, or priv_size is not aligned.
718  *    - ENOSPC - the maximum number of memzones has already been allocated
719  *    - EEXIST - a memzone with the same name already exists
720  *    - ENOMEM - no appropriate memory area found in which to create memzone
721  */
722 struct rte_mempool *
723 rte_pktmbuf_pool_create_by_ops(const char *name, unsigned int n,
724         unsigned int cache_size, uint16_t priv_size, uint16_t data_room_size,
725         int socket_id, const char *ops_name);
726
727 /** A structure that describes the pinned external buffer segment. */
728 struct rte_pktmbuf_extmem {
729         void *buf_ptr;          /**< The virtual address of data buffer. */
730         rte_iova_t buf_iova;    /**< The IO address of the data buffer. */
731         size_t buf_len;         /**< External buffer length in bytes. */
732         uint16_t elt_size;      /**< mbuf element size in bytes. */
733 };
734
735 /**
736  * Create a mbuf pool with external pinned data buffers.
737  *
738  * This function creates and initializes a packet mbuf pool that contains
739  * only mbufs with external buffer. It is a wrapper to rte_mempool functions.
740  *
741  * @param name
742  *   The name of the mbuf pool.
743  * @param n
744  *   The number of elements in the mbuf pool. The optimum size (in terms
745  *   of memory usage) for a mempool is when n is a power of two minus one:
746  *   n = (2^q - 1).
747  * @param cache_size
748  *   Size of the per-core object cache. See rte_mempool_create() for
749  *   details.
750  * @param priv_size
751  *   Size of application private are between the rte_mbuf structure
752  *   and the data buffer. This value must be aligned to RTE_MBUF_PRIV_ALIGN.
753  * @param data_room_size
754  *   Size of data buffer in each mbuf, including RTE_PKTMBUF_HEADROOM.
755  * @param socket_id
756  *   The socket identifier where the memory should be allocated. The
757  *   value can be *SOCKET_ID_ANY* if there is no NUMA constraint for the
758  *   reserved zone.
759  * @param ext_mem
760  *   Pointer to the array of structures describing the external memory
761  *   for data buffers. It is caller responsibility to register this memory
762  *   with rte_extmem_register() (if needed), map this memory to appropriate
763  *   physical device, etc.
764  * @param ext_num
765  *   Number of elements in the ext_mem array.
766  * @return
767  *   The pointer to the new allocated mempool, on success. NULL on error
768  *   with rte_errno set appropriately. Possible rte_errno values include:
769  *    - E_RTE_NO_CONFIG - function could not get pointer to rte_config structure
770  *    - E_RTE_SECONDARY - function was called from a secondary process instance
771  *    - EINVAL - cache size provided is too large, or priv_size is not aligned.
772  *    - ENOSPC - the maximum number of memzones has already been allocated
773  *    - EEXIST - a memzone with the same name already exists
774  *    - ENOMEM - no appropriate memory area found in which to create memzone
775  */
776 __rte_experimental
777 struct rte_mempool *
778 rte_pktmbuf_pool_create_extbuf(const char *name, unsigned int n,
779         unsigned int cache_size, uint16_t priv_size,
780         uint16_t data_room_size, int socket_id,
781         const struct rte_pktmbuf_extmem *ext_mem,
782         unsigned int ext_num);
783
784 /**
785  * Get the data room size of mbufs stored in a pktmbuf_pool
786  *
787  * The data room size is the amount of data that can be stored in a
788  * mbuf including the headroom (RTE_PKTMBUF_HEADROOM).
789  *
790  * @param mp
791  *   The packet mbuf pool.
792  * @return
793  *   The data room size of mbufs stored in this mempool.
794  */
795 static inline uint16_t
796 rte_pktmbuf_data_room_size(struct rte_mempool *mp)
797 {
798         struct rte_pktmbuf_pool_private *mbp_priv;
799
800         mbp_priv = (struct rte_pktmbuf_pool_private *)rte_mempool_get_priv(mp);
801         return mbp_priv->mbuf_data_room_size;
802 }
803
804 /**
805  * Get the application private size of mbufs stored in a pktmbuf_pool
806  *
807  * The private size of mbuf is a zone located between the rte_mbuf
808  * structure and the data buffer where an application can store data
809  * associated to a packet.
810  *
811  * @param mp
812  *   The packet mbuf pool.
813  * @return
814  *   The private size of mbufs stored in this mempool.
815  */
816 static inline uint16_t
817 rte_pktmbuf_priv_size(struct rte_mempool *mp)
818 {
819         struct rte_pktmbuf_pool_private *mbp_priv;
820
821         mbp_priv = (struct rte_pktmbuf_pool_private *)rte_mempool_get_priv(mp);
822         return mbp_priv->mbuf_priv_size;
823 }
824
825 /**
826  * Reset the data_off field of a packet mbuf to its default value.
827  *
828  * The given mbuf must have only one segment, which should be empty.
829  *
830  * @param m
831  *   The packet mbuf's data_off field has to be reset.
832  */
833 static inline void rte_pktmbuf_reset_headroom(struct rte_mbuf *m)
834 {
835         m->data_off = (uint16_t)RTE_MIN((uint16_t)RTE_PKTMBUF_HEADROOM,
836                                         (uint16_t)m->buf_len);
837 }
838
839 /**
840  * Reset the fields of a packet mbuf to their default values.
841  *
842  * The given mbuf must have only one segment.
843  *
844  * @param m
845  *   The packet mbuf to be reset.
846  */
847 #define MBUF_INVALID_PORT UINT16_MAX
848
849 static inline void rte_pktmbuf_reset(struct rte_mbuf *m)
850 {
851         m->next = NULL;
852         m->pkt_len = 0;
853         m->tx_offload = 0;
854         m->vlan_tci = 0;
855         m->vlan_tci_outer = 0;
856         m->nb_segs = 1;
857         m->port = MBUF_INVALID_PORT;
858
859         m->ol_flags &= EXT_ATTACHED_MBUF;
860         m->packet_type = 0;
861         rte_pktmbuf_reset_headroom(m);
862
863         m->data_len = 0;
864         __rte_mbuf_sanity_check(m, 1);
865 }
866
867 /**
868  * Allocate a new mbuf from a mempool.
869  *
870  * This new mbuf contains one segment, which has a length of 0. The pointer
871  * to data is initialized to have some bytes of headroom in the buffer
872  * (if buffer size allows).
873  *
874  * @param mp
875  *   The mempool from which the mbuf is allocated.
876  * @return
877  *   - The pointer to the new mbuf on success.
878  *   - NULL if allocation failed.
879  */
880 static inline struct rte_mbuf *rte_pktmbuf_alloc(struct rte_mempool *mp)
881 {
882         struct rte_mbuf *m;
883         if ((m = rte_mbuf_raw_alloc(mp)) != NULL)
884                 rte_pktmbuf_reset(m);
885         return m;
886 }
887
888 /**
889  * Allocate a bulk of mbufs, initialize refcnt and reset the fields to default
890  * values.
891  *
892  *  @param pool
893  *    The mempool from which mbufs are allocated.
894  *  @param mbufs
895  *    Array of pointers to mbufs
896  *  @param count
897  *    Array size
898  *  @return
899  *   - 0: Success
900  *   - -ENOENT: Not enough entries in the mempool; no mbufs are retrieved.
901  */
902 static inline int rte_pktmbuf_alloc_bulk(struct rte_mempool *pool,
903          struct rte_mbuf **mbufs, unsigned count)
904 {
905         unsigned idx = 0;
906         int rc;
907
908         rc = rte_mempool_get_bulk(pool, (void **)mbufs, count);
909         if (unlikely(rc))
910                 return rc;
911
912         /* To understand duff's device on loop unwinding optimization, see
913          * https://en.wikipedia.org/wiki/Duff's_device.
914          * Here while() loop is used rather than do() while{} to avoid extra
915          * check if count is zero.
916          */
917         switch (count % 4) {
918         case 0:
919                 while (idx != count) {
920                         MBUF_RAW_ALLOC_CHECK(mbufs[idx]);
921                         rte_pktmbuf_reset(mbufs[idx]);
922                         idx++;
923                         /* fall-through */
924         case 3:
925                         MBUF_RAW_ALLOC_CHECK(mbufs[idx]);
926                         rte_pktmbuf_reset(mbufs[idx]);
927                         idx++;
928                         /* fall-through */
929         case 2:
930                         MBUF_RAW_ALLOC_CHECK(mbufs[idx]);
931                         rte_pktmbuf_reset(mbufs[idx]);
932                         idx++;
933                         /* fall-through */
934         case 1:
935                         MBUF_RAW_ALLOC_CHECK(mbufs[idx]);
936                         rte_pktmbuf_reset(mbufs[idx]);
937                         idx++;
938                         /* fall-through */
939                 }
940         }
941         return 0;
942 }
943
944 /**
945  * Initialize shared data at the end of an external buffer before attaching
946  * to a mbuf by ``rte_pktmbuf_attach_extbuf()``. This is not a mandatory
947  * initialization but a helper function to simply spare a few bytes at the
948  * end of the buffer for shared data. If shared data is allocated
949  * separately, this should not be called but application has to properly
950  * initialize the shared data according to its need.
951  *
952  * Free callback and its argument is saved and the refcnt is set to 1.
953  *
954  * @warning
955  * The value of buf_len will be reduced to RTE_PTR_DIFF(shinfo, buf_addr)
956  * after this initialization. This shall be used for
957  * ``rte_pktmbuf_attach_extbuf()``
958  *
959  * @param buf_addr
960  *   The pointer to the external buffer.
961  * @param [in,out] buf_len
962  *   The pointer to length of the external buffer. Input value must be
963  *   larger than the size of ``struct rte_mbuf_ext_shared_info`` and
964  *   padding for alignment. If not enough, this function will return NULL.
965  *   Adjusted buffer length will be returned through this pointer.
966  * @param free_cb
967  *   Free callback function to call when the external buffer needs to be
968  *   freed.
969  * @param fcb_opaque
970  *   Argument for the free callback function.
971  *
972  * @return
973  *   A pointer to the initialized shared data on success, return NULL
974  *   otherwise.
975  */
976 static inline struct rte_mbuf_ext_shared_info *
977 rte_pktmbuf_ext_shinfo_init_helper(void *buf_addr, uint16_t *buf_len,
978         rte_mbuf_extbuf_free_callback_t free_cb, void *fcb_opaque)
979 {
980         struct rte_mbuf_ext_shared_info *shinfo;
981         void *buf_end = RTE_PTR_ADD(buf_addr, *buf_len);
982         void *addr;
983
984         addr = RTE_PTR_ALIGN_FLOOR(RTE_PTR_SUB(buf_end, sizeof(*shinfo)),
985                                    sizeof(uintptr_t));
986         if (addr <= buf_addr)
987                 return NULL;
988
989         shinfo = (struct rte_mbuf_ext_shared_info *)addr;
990         shinfo->free_cb = free_cb;
991         shinfo->fcb_opaque = fcb_opaque;
992         rte_mbuf_ext_refcnt_set(shinfo, 1);
993
994         *buf_len = (uint16_t)RTE_PTR_DIFF(shinfo, buf_addr);
995         return shinfo;
996 }
997
998 /**
999  * Attach an external buffer to a mbuf.
1000  *
1001  * User-managed anonymous buffer can be attached to an mbuf. When attaching
1002  * it, corresponding free callback function and its argument should be
1003  * provided via shinfo. This callback function will be called once all the
1004  * mbufs are detached from the buffer (refcnt becomes zero).
1005  *
1006  * The headroom length of the attaching mbuf will be set to zero and this
1007  * can be properly adjusted after attachment. For example, ``rte_pktmbuf_adj()``
1008  * or ``rte_pktmbuf_reset_headroom()`` might be used.
1009  *
1010  * Similarly, the packet length is initialized to 0. If the buffer contains
1011  * data, the user has to adjust ``data_len`` and the ``pkt_len`` field of
1012  * the mbuf accordingly.
1013  *
1014  * More mbufs can be attached to the same external buffer by
1015  * ``rte_pktmbuf_attach()`` once the external buffer has been attached by
1016  * this API.
1017  *
1018  * Detachment can be done by either ``rte_pktmbuf_detach_extbuf()`` or
1019  * ``rte_pktmbuf_detach()``.
1020  *
1021  * Memory for shared data must be provided and user must initialize all of
1022  * the content properly, especially free callback and refcnt. The pointer
1023  * of shared data will be stored in m->shinfo.
1024  * ``rte_pktmbuf_ext_shinfo_init_helper`` can help to simply spare a few
1025  * bytes at the end of buffer for the shared data, store free callback and
1026  * its argument and set the refcnt to 1. The following is an example:
1027  *
1028  *   struct rte_mbuf_ext_shared_info *shinfo =
1029  *          rte_pktmbuf_ext_shinfo_init_helper(buf_addr, &buf_len,
1030  *                                             free_cb, fcb_arg);
1031  *   rte_pktmbuf_attach_extbuf(m, buf_addr, buf_iova, buf_len, shinfo);
1032  *   rte_pktmbuf_reset_headroom(m);
1033  *   rte_pktmbuf_adj(m, data_len);
1034  *
1035  * Attaching an external buffer is quite similar to mbuf indirection in
1036  * replacing buffer addresses and length of a mbuf, but a few differences:
1037  * - When an indirect mbuf is attached, refcnt of the direct mbuf would be
1038  *   2 as long as the direct mbuf itself isn't freed after the attachment.
1039  *   In such cases, the buffer area of a direct mbuf must be read-only. But
1040  *   external buffer has its own refcnt and it starts from 1. Unless
1041  *   multiple mbufs are attached to a mbuf having an external buffer, the
1042  *   external buffer is writable.
1043  * - There's no need to allocate buffer from a mempool. Any buffer can be
1044  *   attached with appropriate free callback and its IO address.
1045  * - Smaller metadata is required to maintain shared data such as refcnt.
1046  *
1047  * @param m
1048  *   The pointer to the mbuf.
1049  * @param buf_addr
1050  *   The pointer to the external buffer.
1051  * @param buf_iova
1052  *   IO address of the external buffer.
1053  * @param buf_len
1054  *   The size of the external buffer.
1055  * @param shinfo
1056  *   User-provided memory for shared data of the external buffer.
1057  */
1058 static inline void
1059 rte_pktmbuf_attach_extbuf(struct rte_mbuf *m, void *buf_addr,
1060         rte_iova_t buf_iova, uint16_t buf_len,
1061         struct rte_mbuf_ext_shared_info *shinfo)
1062 {
1063         /* mbuf should not be read-only */
1064         RTE_ASSERT(RTE_MBUF_DIRECT(m) && rte_mbuf_refcnt_read(m) == 1);
1065         RTE_ASSERT(shinfo->free_cb != NULL);
1066
1067         m->buf_addr = buf_addr;
1068         m->buf_iova = buf_iova;
1069         m->buf_len = buf_len;
1070
1071         m->data_len = 0;
1072         m->data_off = 0;
1073
1074         m->ol_flags |= EXT_ATTACHED_MBUF;
1075         m->shinfo = shinfo;
1076 }
1077
1078 /**
1079  * Detach the external buffer attached to a mbuf, same as
1080  * ``rte_pktmbuf_detach()``
1081  *
1082  * @param m
1083  *   The mbuf having external buffer.
1084  */
1085 #define rte_pktmbuf_detach_extbuf(m) rte_pktmbuf_detach(m)
1086
1087 /**
1088  * Copy dynamic fields from msrc to mdst.
1089  *
1090  * @param mdst
1091  *   The destination mbuf.
1092  * @param msrc
1093  *   The source mbuf.
1094  */
1095 static inline void
1096 rte_mbuf_dynfield_copy(struct rte_mbuf *mdst, const struct rte_mbuf *msrc)
1097 {
1098         memcpy(&mdst->dynfield0, msrc->dynfield0, sizeof(mdst->dynfield0));
1099         memcpy(&mdst->dynfield1, msrc->dynfield1, sizeof(mdst->dynfield1));
1100 }
1101
1102 /* internal */
1103 static inline void
1104 __rte_pktmbuf_copy_hdr(struct rte_mbuf *mdst, const struct rte_mbuf *msrc)
1105 {
1106         mdst->port = msrc->port;
1107         mdst->vlan_tci = msrc->vlan_tci;
1108         mdst->vlan_tci_outer = msrc->vlan_tci_outer;
1109         mdst->tx_offload = msrc->tx_offload;
1110         mdst->hash = msrc->hash;
1111         mdst->packet_type = msrc->packet_type;
1112         rte_mbuf_dynfield_copy(mdst, msrc);
1113 }
1114
1115 /**
1116  * Attach packet mbuf to another packet mbuf.
1117  *
1118  * If the mbuf we are attaching to isn't a direct buffer and is attached to
1119  * an external buffer, the mbuf being attached will be attached to the
1120  * external buffer instead of mbuf indirection.
1121  *
1122  * Otherwise, the mbuf will be indirectly attached. After attachment we
1123  * refer the mbuf we attached as 'indirect', while mbuf we attached to as
1124  * 'direct'.  The direct mbuf's reference counter is incremented.
1125  *
1126  * Right now, not supported:
1127  *  - attachment for already indirect mbuf (e.g. - mi has to be direct).
1128  *  - mbuf we trying to attach (mi) is used by someone else
1129  *    e.g. it's reference counter is greater then 1.
1130  *
1131  * @param mi
1132  *   The indirect packet mbuf.
1133  * @param m
1134  *   The packet mbuf we're attaching to.
1135  */
1136 static inline void rte_pktmbuf_attach(struct rte_mbuf *mi, struct rte_mbuf *m)
1137 {
1138         RTE_ASSERT(RTE_MBUF_DIRECT(mi) &&
1139             rte_mbuf_refcnt_read(mi) == 1);
1140
1141         if (RTE_MBUF_HAS_EXTBUF(m)) {
1142                 rte_mbuf_ext_refcnt_update(m->shinfo, 1);
1143                 mi->ol_flags = m->ol_flags;
1144                 mi->shinfo = m->shinfo;
1145         } else {
1146                 /* if m is not direct, get the mbuf that embeds the data */
1147                 rte_mbuf_refcnt_update(rte_mbuf_from_indirect(m), 1);
1148                 mi->priv_size = m->priv_size;
1149                 mi->ol_flags = m->ol_flags | IND_ATTACHED_MBUF;
1150         }
1151
1152         __rte_pktmbuf_copy_hdr(mi, m);
1153
1154         mi->data_off = m->data_off;
1155         mi->data_len = m->data_len;
1156         mi->buf_iova = m->buf_iova;
1157         mi->buf_addr = m->buf_addr;
1158         mi->buf_len = m->buf_len;
1159
1160         mi->next = NULL;
1161         mi->pkt_len = mi->data_len;
1162         mi->nb_segs = 1;
1163
1164         __rte_mbuf_sanity_check(mi, 1);
1165         __rte_mbuf_sanity_check(m, 0);
1166 }
1167
1168 /**
1169  * @internal used by rte_pktmbuf_detach().
1170  *
1171  * Decrement the reference counter of the external buffer. When the
1172  * reference counter becomes 0, the buffer is freed by pre-registered
1173  * callback.
1174  */
1175 static inline void
1176 __rte_pktmbuf_free_extbuf(struct rte_mbuf *m)
1177 {
1178         RTE_ASSERT(RTE_MBUF_HAS_EXTBUF(m));
1179         RTE_ASSERT(m->shinfo != NULL);
1180
1181         if (rte_mbuf_ext_refcnt_update(m->shinfo, -1) == 0)
1182                 m->shinfo->free_cb(m->buf_addr, m->shinfo->fcb_opaque);
1183 }
1184
1185 /**
1186  * @internal used by rte_pktmbuf_detach().
1187  *
1188  * Decrement the direct mbuf's reference counter. When the reference
1189  * counter becomes 0, the direct mbuf is freed.
1190  */
1191 static inline void
1192 __rte_pktmbuf_free_direct(struct rte_mbuf *m)
1193 {
1194         struct rte_mbuf *md;
1195
1196         RTE_ASSERT(RTE_MBUF_CLONED(m));
1197
1198         md = rte_mbuf_from_indirect(m);
1199
1200         if (rte_mbuf_refcnt_update(md, -1) == 0) {
1201                 md->next = NULL;
1202                 md->nb_segs = 1;
1203                 rte_mbuf_refcnt_set(md, 1);
1204                 rte_mbuf_raw_free(md);
1205         }
1206 }
1207
1208 /**
1209  * Detach a packet mbuf from external buffer or direct buffer.
1210  *
1211  *  - decrement refcnt and free the external/direct buffer if refcnt
1212  *    becomes zero.
1213  *  - restore original mbuf address and length values.
1214  *  - reset pktmbuf data and data_len to their default values.
1215  *
1216  * All other fields of the given packet mbuf will be left intact.
1217  *
1218  * If the packet mbuf was allocated from the pool with pinned
1219  * external buffers the rte_pktmbuf_detach does nothing with the
1220  * mbuf of this kind, because the pinned buffers are not supposed
1221  * to be detached.
1222  *
1223  * @param m
1224  *   The indirect attached packet mbuf.
1225  */
1226 static inline void rte_pktmbuf_detach(struct rte_mbuf *m)
1227 {
1228         struct rte_mempool *mp = m->pool;
1229         uint32_t mbuf_size, buf_len;
1230         uint16_t priv_size;
1231
1232         if (RTE_MBUF_HAS_EXTBUF(m)) {
1233                 /*
1234                  * The mbuf has the external attached buffer,
1235                  * we should check the type of the memory pool where
1236                  * the mbuf was allocated from to detect the pinned
1237                  * external buffer.
1238                  */
1239                 uint32_t flags = rte_pktmbuf_priv_flags(mp);
1240
1241                 if (flags & RTE_PKTMBUF_POOL_F_PINNED_EXT_BUF) {
1242                         /*
1243                          * The pinned external buffer should not be
1244                          * detached from its backing mbuf, just exit.
1245                          */
1246                         return;
1247                 }
1248                 __rte_pktmbuf_free_extbuf(m);
1249         } else {
1250                 __rte_pktmbuf_free_direct(m);
1251         }
1252         priv_size = rte_pktmbuf_priv_size(mp);
1253         mbuf_size = (uint32_t)(sizeof(struct rte_mbuf) + priv_size);
1254         buf_len = rte_pktmbuf_data_room_size(mp);
1255
1256         m->priv_size = priv_size;
1257         m->buf_addr = (char *)m + mbuf_size;
1258         m->buf_iova = rte_mempool_virt2iova(m) + mbuf_size;
1259         m->buf_len = (uint16_t)buf_len;
1260         rte_pktmbuf_reset_headroom(m);
1261         m->data_len = 0;
1262         m->ol_flags = 0;
1263 }
1264
1265 /**
1266  * @internal Handle the packet mbufs with attached pinned external buffer
1267  * on the mbuf freeing:
1268  *
1269  *  - return zero if reference counter in shinfo is one. It means there is
1270  *  no more reference to this pinned buffer and mbuf can be returned to
1271  *  the pool
1272  *
1273  *  - otherwise (if reference counter is not one), decrement reference
1274  *  counter and return non-zero value to prevent freeing the backing mbuf.
1275  *
1276  * Returns non zero if mbuf should not be freed.
1277  */
1278 static inline int __rte_pktmbuf_pinned_extbuf_decref(struct rte_mbuf *m)
1279 {
1280         struct rte_mbuf_ext_shared_info *shinfo;
1281
1282         /* Clear flags, mbuf is being freed. */
1283         m->ol_flags = EXT_ATTACHED_MBUF;
1284         shinfo = m->shinfo;
1285
1286         /* Optimize for performance - do not dec/reinit */
1287         if (likely(rte_mbuf_ext_refcnt_read(shinfo) == 1))
1288                 return 0;
1289
1290         /*
1291          * Direct usage of add primitive to avoid
1292          * duplication of comparing with one.
1293          */
1294         if (likely(__atomic_add_fetch(&shinfo->refcnt, (uint16_t)-1,
1295                                      __ATOMIC_ACQ_REL)))
1296                 return 1;
1297
1298         /* Reinitialize counter before mbuf freeing. */
1299         rte_mbuf_ext_refcnt_set(shinfo, 1);
1300         return 0;
1301 }
1302
1303 /**
1304  * Decrease reference counter and unlink a mbuf segment
1305  *
1306  * This function does the same than a free, except that it does not
1307  * return the segment to its pool.
1308  * It decreases the reference counter, and if it reaches 0, it is
1309  * detached from its parent for an indirect mbuf.
1310  *
1311  * @param m
1312  *   The mbuf to be unlinked
1313  * @return
1314  *   - (m) if it is the last reference. It can be recycled or freed.
1315  *   - (NULL) if the mbuf still has remaining references on it.
1316  */
1317 static __rte_always_inline struct rte_mbuf *
1318 rte_pktmbuf_prefree_seg(struct rte_mbuf *m)
1319 {
1320         __rte_mbuf_sanity_check(m, 0);
1321
1322         if (likely(rte_mbuf_refcnt_read(m) == 1)) {
1323
1324                 if (!RTE_MBUF_DIRECT(m)) {
1325                         rte_pktmbuf_detach(m);
1326                         if (RTE_MBUF_HAS_EXTBUF(m) &&
1327                             RTE_MBUF_HAS_PINNED_EXTBUF(m) &&
1328                             __rte_pktmbuf_pinned_extbuf_decref(m))
1329                                 return NULL;
1330                 }
1331
1332                 if (m->next != NULL) {
1333                         m->next = NULL;
1334                         m->nb_segs = 1;
1335                 }
1336
1337                 return m;
1338
1339         } else if (__rte_mbuf_refcnt_update(m, -1) == 0) {
1340
1341                 if (!RTE_MBUF_DIRECT(m)) {
1342                         rte_pktmbuf_detach(m);
1343                         if (RTE_MBUF_HAS_EXTBUF(m) &&
1344                             RTE_MBUF_HAS_PINNED_EXTBUF(m) &&
1345                             __rte_pktmbuf_pinned_extbuf_decref(m))
1346                                 return NULL;
1347                 }
1348
1349                 if (m->next != NULL) {
1350                         m->next = NULL;
1351                         m->nb_segs = 1;
1352                 }
1353                 rte_mbuf_refcnt_set(m, 1);
1354
1355                 return m;
1356         }
1357         return NULL;
1358 }
1359
1360 /**
1361  * Free a segment of a packet mbuf into its original mempool.
1362  *
1363  * Free an mbuf, without parsing other segments in case of chained
1364  * buffers.
1365  *
1366  * @param m
1367  *   The packet mbuf segment to be freed.
1368  */
1369 static __rte_always_inline void
1370 rte_pktmbuf_free_seg(struct rte_mbuf *m)
1371 {
1372         m = rte_pktmbuf_prefree_seg(m);
1373         if (likely(m != NULL))
1374                 rte_mbuf_raw_free(m);
1375 }
1376
1377 /**
1378  * Free a packet mbuf back into its original mempool.
1379  *
1380  * Free an mbuf, and all its segments in case of chained buffers. Each
1381  * segment is added back into its original mempool.
1382  *
1383  * @param m
1384  *   The packet mbuf to be freed. If NULL, the function does nothing.
1385  */
1386 static inline void rte_pktmbuf_free(struct rte_mbuf *m)
1387 {
1388         struct rte_mbuf *m_next;
1389
1390         if (m != NULL)
1391                 __rte_mbuf_sanity_check(m, 1);
1392
1393         while (m != NULL) {
1394                 m_next = m->next;
1395                 rte_pktmbuf_free_seg(m);
1396                 m = m_next;
1397         }
1398 }
1399
1400 /**
1401  * Free a bulk of packet mbufs back into their original mempools.
1402  *
1403  * Free a bulk of mbufs, and all their segments in case of chained buffers.
1404  * Each segment is added back into its original mempool.
1405  *
1406  *  @param mbufs
1407  *    Array of pointers to packet mbufs.
1408  *    The array may contain NULL pointers.
1409  *  @param count
1410  *    Array size.
1411  */
1412 __rte_experimental
1413 void rte_pktmbuf_free_bulk(struct rte_mbuf **mbufs, unsigned int count);
1414
1415 /**
1416  * Create a "clone" of the given packet mbuf.
1417  *
1418  * Walks through all segments of the given packet mbuf, and for each of them:
1419  *  - Creates a new packet mbuf from the given pool.
1420  *  - Attaches newly created mbuf to the segment.
1421  * Then updates pkt_len and nb_segs of the "clone" packet mbuf to match values
1422  * from the original packet mbuf.
1423  *
1424  * @param md
1425  *   The packet mbuf to be cloned.
1426  * @param mp
1427  *   The mempool from which the "clone" mbufs are allocated.
1428  * @return
1429  *   - The pointer to the new "clone" mbuf on success.
1430  *   - NULL if allocation fails.
1431  */
1432 struct rte_mbuf *
1433 rte_pktmbuf_clone(struct rte_mbuf *md, struct rte_mempool *mp);
1434
1435 /**
1436  * Create a full copy of a given packet mbuf.
1437  *
1438  * Copies all the data from a given packet mbuf to a newly allocated
1439  * set of mbufs. The private data are is not copied.
1440  *
1441  * @param m
1442  *   The packet mbuf to be copiedd.
1443  * @param mp
1444  *   The mempool from which the "clone" mbufs are allocated.
1445  * @param offset
1446  *   The number of bytes to skip before copying.
1447  *   If the mbuf does not have that many bytes, it is an error
1448  *   and NULL is returned.
1449  * @param length
1450  *   The upper limit on bytes to copy.  Passing UINT32_MAX
1451  *   means all data (after offset).
1452  * @return
1453  *   - The pointer to the new "clone" mbuf on success.
1454  *   - NULL if allocation fails.
1455  */
1456 __rte_experimental
1457 struct rte_mbuf *
1458 rte_pktmbuf_copy(const struct rte_mbuf *m, struct rte_mempool *mp,
1459                  uint32_t offset, uint32_t length);
1460
1461 /**
1462  * Adds given value to the refcnt of all packet mbuf segments.
1463  *
1464  * Walks through all segments of given packet mbuf and for each of them
1465  * invokes rte_mbuf_refcnt_update().
1466  *
1467  * @param m
1468  *   The packet mbuf whose refcnt to be updated.
1469  * @param v
1470  *   The value to add to the mbuf's segments refcnt.
1471  */
1472 static inline void rte_pktmbuf_refcnt_update(struct rte_mbuf *m, int16_t v)
1473 {
1474         __rte_mbuf_sanity_check(m, 1);
1475
1476         do {
1477                 rte_mbuf_refcnt_update(m, v);
1478         } while ((m = m->next) != NULL);
1479 }
1480
1481 /**
1482  * Get the headroom in a packet mbuf.
1483  *
1484  * @param m
1485  *   The packet mbuf.
1486  * @return
1487  *   The length of the headroom.
1488  */
1489 static inline uint16_t rte_pktmbuf_headroom(const struct rte_mbuf *m)
1490 {
1491         __rte_mbuf_sanity_check(m, 0);
1492         return m->data_off;
1493 }
1494
1495 /**
1496  * Get the tailroom of a packet mbuf.
1497  *
1498  * @param m
1499  *   The packet mbuf.
1500  * @return
1501  *   The length of the tailroom.
1502  */
1503 static inline uint16_t rte_pktmbuf_tailroom(const struct rte_mbuf *m)
1504 {
1505         __rte_mbuf_sanity_check(m, 0);
1506         return (uint16_t)(m->buf_len - rte_pktmbuf_headroom(m) -
1507                           m->data_len);
1508 }
1509
1510 /**
1511  * Get the last segment of the packet.
1512  *
1513  * @param m
1514  *   The packet mbuf.
1515  * @return
1516  *   The last segment of the given mbuf.
1517  */
1518 static inline struct rte_mbuf *rte_pktmbuf_lastseg(struct rte_mbuf *m)
1519 {
1520         __rte_mbuf_sanity_check(m, 1);
1521         while (m->next != NULL)
1522                 m = m->next;
1523         return m;
1524 }
1525
1526 /**
1527  * A macro that returns the length of the packet.
1528  *
1529  * The value can be read or assigned.
1530  *
1531  * @param m
1532  *   The packet mbuf.
1533  */
1534 #define rte_pktmbuf_pkt_len(m) ((m)->pkt_len)
1535
1536 /**
1537  * A macro that returns the length of the segment.
1538  *
1539  * The value can be read or assigned.
1540  *
1541  * @param m
1542  *   The packet mbuf.
1543  */
1544 #define rte_pktmbuf_data_len(m) ((m)->data_len)
1545
1546 /**
1547  * Prepend len bytes to an mbuf data area.
1548  *
1549  * Returns a pointer to the new
1550  * data start address. If there is not enough headroom in the first
1551  * segment, the function will return NULL, without modifying the mbuf.
1552  *
1553  * @param m
1554  *   The pkt mbuf.
1555  * @param len
1556  *   The amount of data to prepend (in bytes).
1557  * @return
1558  *   A pointer to the start of the newly prepended data, or
1559  *   NULL if there is not enough headroom space in the first segment
1560  */
1561 static inline char *rte_pktmbuf_prepend(struct rte_mbuf *m,
1562                                         uint16_t len)
1563 {
1564         __rte_mbuf_sanity_check(m, 1);
1565
1566         if (unlikely(len > rte_pktmbuf_headroom(m)))
1567                 return NULL;
1568
1569         /* NB: elaborating the subtraction like this instead of using
1570          *     -= allows us to ensure the result type is uint16_t
1571          *     avoiding compiler warnings on gcc 8.1 at least */
1572         m->data_off = (uint16_t)(m->data_off - len);
1573         m->data_len = (uint16_t)(m->data_len + len);
1574         m->pkt_len  = (m->pkt_len + len);
1575
1576         return (char *)m->buf_addr + m->data_off;
1577 }
1578
1579 /**
1580  * Append len bytes to an mbuf.
1581  *
1582  * Append len bytes to an mbuf and return a pointer to the start address
1583  * of the added data. If there is not enough tailroom in the last
1584  * segment, the function will return NULL, without modifying the mbuf.
1585  *
1586  * @param m
1587  *   The packet mbuf.
1588  * @param len
1589  *   The amount of data to append (in bytes).
1590  * @return
1591  *   A pointer to the start of the newly appended data, or
1592  *   NULL if there is not enough tailroom space in the last segment
1593  */
1594 static inline char *rte_pktmbuf_append(struct rte_mbuf *m, uint16_t len)
1595 {
1596         void *tail;
1597         struct rte_mbuf *m_last;
1598
1599         __rte_mbuf_sanity_check(m, 1);
1600
1601         m_last = rte_pktmbuf_lastseg(m);
1602         if (unlikely(len > rte_pktmbuf_tailroom(m_last)))
1603                 return NULL;
1604
1605         tail = (char *)m_last->buf_addr + m_last->data_off + m_last->data_len;
1606         m_last->data_len = (uint16_t)(m_last->data_len + len);
1607         m->pkt_len  = (m->pkt_len + len);
1608         return (char*) tail;
1609 }
1610
1611 /**
1612  * Remove len bytes at the beginning of an mbuf.
1613  *
1614  * Returns a pointer to the start address of the new data area. If the
1615  * length is greater than the length of the first segment, then the
1616  * function will fail and return NULL, without modifying the mbuf.
1617  *
1618  * @param m
1619  *   The packet mbuf.
1620  * @param len
1621  *   The amount of data to remove (in bytes).
1622  * @return
1623  *   A pointer to the new start of the data.
1624  */
1625 static inline char *rte_pktmbuf_adj(struct rte_mbuf *m, uint16_t len)
1626 {
1627         __rte_mbuf_sanity_check(m, 1);
1628
1629         if (unlikely(len > m->data_len))
1630                 return NULL;
1631
1632         /* NB: elaborating the addition like this instead of using
1633          *     += allows us to ensure the result type is uint16_t
1634          *     avoiding compiler warnings on gcc 8.1 at least */
1635         m->data_len = (uint16_t)(m->data_len - len);
1636         m->data_off = (uint16_t)(m->data_off + len);
1637         m->pkt_len  = (m->pkt_len - len);
1638         return (char *)m->buf_addr + m->data_off;
1639 }
1640
1641 /**
1642  * Remove len bytes of data at the end of the mbuf.
1643  *
1644  * If the length is greater than the length of the last segment, the
1645  * function will fail and return -1 without modifying the mbuf.
1646  *
1647  * @param m
1648  *   The packet mbuf.
1649  * @param len
1650  *   The amount of data to remove (in bytes).
1651  * @return
1652  *   - 0: On success.
1653  *   - -1: On error.
1654  */
1655 static inline int rte_pktmbuf_trim(struct rte_mbuf *m, uint16_t len)
1656 {
1657         struct rte_mbuf *m_last;
1658
1659         __rte_mbuf_sanity_check(m, 1);
1660
1661         m_last = rte_pktmbuf_lastseg(m);
1662         if (unlikely(len > m_last->data_len))
1663                 return -1;
1664
1665         m_last->data_len = (uint16_t)(m_last->data_len - len);
1666         m->pkt_len  = (m->pkt_len - len);
1667         return 0;
1668 }
1669
1670 /**
1671  * Test if mbuf data is contiguous.
1672  *
1673  * @param m
1674  *   The packet mbuf.
1675  * @return
1676  *   - 1, if all data is contiguous (one segment).
1677  *   - 0, if there is several segments.
1678  */
1679 static inline int rte_pktmbuf_is_contiguous(const struct rte_mbuf *m)
1680 {
1681         __rte_mbuf_sanity_check(m, 1);
1682         return m->nb_segs == 1;
1683 }
1684
1685 /**
1686  * @internal used by rte_pktmbuf_read().
1687  */
1688 const void *__rte_pktmbuf_read(const struct rte_mbuf *m, uint32_t off,
1689         uint32_t len, void *buf);
1690
1691 /**
1692  * Read len data bytes in a mbuf at specified offset.
1693  *
1694  * If the data is contiguous, return the pointer in the mbuf data, else
1695  * copy the data in the buffer provided by the user and return its
1696  * pointer.
1697  *
1698  * @param m
1699  *   The pointer to the mbuf.
1700  * @param off
1701  *   The offset of the data in the mbuf.
1702  * @param len
1703  *   The amount of bytes to read.
1704  * @param buf
1705  *   The buffer where data is copied if it is not contiguous in mbuf
1706  *   data. Its length should be at least equal to the len parameter.
1707  * @return
1708  *   The pointer to the data, either in the mbuf if it is contiguous,
1709  *   or in the user buffer. If mbuf is too small, NULL is returned.
1710  */
1711 static inline const void *rte_pktmbuf_read(const struct rte_mbuf *m,
1712         uint32_t off, uint32_t len, void *buf)
1713 {
1714         if (likely(off + len <= rte_pktmbuf_data_len(m)))
1715                 return rte_pktmbuf_mtod_offset(m, char *, off);
1716         else
1717                 return __rte_pktmbuf_read(m, off, len, buf);
1718 }
1719
1720 /**
1721  * Chain an mbuf to another, thereby creating a segmented packet.
1722  *
1723  * Note: The implementation will do a linear walk over the segments to find
1724  * the tail entry. For cases when there are many segments, it's better to
1725  * chain the entries manually.
1726  *
1727  * @param head
1728  *   The head of the mbuf chain (the first packet)
1729  * @param tail
1730  *   The mbuf to put last in the chain
1731  *
1732  * @return
1733  *   - 0, on success.
1734  *   - -EOVERFLOW, if the chain segment limit exceeded
1735  */
1736 static inline int rte_pktmbuf_chain(struct rte_mbuf *head, struct rte_mbuf *tail)
1737 {
1738         struct rte_mbuf *cur_tail;
1739
1740         /* Check for number-of-segments-overflow */
1741         if (head->nb_segs + tail->nb_segs > RTE_MBUF_MAX_NB_SEGS)
1742                 return -EOVERFLOW;
1743
1744         /* Chain 'tail' onto the old tail */
1745         cur_tail = rte_pktmbuf_lastseg(head);
1746         cur_tail->next = tail;
1747
1748         /* accumulate number of segments and total length.
1749          * NB: elaborating the addition like this instead of using
1750          *     -= allows us to ensure the result type is uint16_t
1751          *     avoiding compiler warnings on gcc 8.1 at least */
1752         head->nb_segs = (uint16_t)(head->nb_segs + tail->nb_segs);
1753         head->pkt_len += tail->pkt_len;
1754
1755         /* pkt_len is only set in the head */
1756         tail->pkt_len = tail->data_len;
1757
1758         return 0;
1759 }
1760
1761 /*
1762  * @warning
1763  * @b EXPERIMENTAL: This API may change without prior notice.
1764  *
1765  * For given input values generate raw tx_offload value.
1766  * Note that it is caller responsibility to make sure that input parameters
1767  * don't exceed maximum bit-field values.
1768  * @param il2
1769  *   l2_len value.
1770  * @param il3
1771  *   l3_len value.
1772  * @param il4
1773  *   l4_len value.
1774  * @param tso
1775  *   tso_segsz value.
1776  * @param ol3
1777  *   outer_l3_len value.
1778  * @param ol2
1779  *   outer_l2_len value.
1780  * @param unused
1781  *   unused value.
1782  * @return
1783  *   raw tx_offload value.
1784  */
1785 static __rte_always_inline uint64_t
1786 rte_mbuf_tx_offload(uint64_t il2, uint64_t il3, uint64_t il4, uint64_t tso,
1787         uint64_t ol3, uint64_t ol2, uint64_t unused)
1788 {
1789         return il2 << RTE_MBUF_L2_LEN_OFS |
1790                 il3 << RTE_MBUF_L3_LEN_OFS |
1791                 il4 << RTE_MBUF_L4_LEN_OFS |
1792                 tso << RTE_MBUF_TSO_SEGSZ_OFS |
1793                 ol3 << RTE_MBUF_OUTL3_LEN_OFS |
1794                 ol2 << RTE_MBUF_OUTL2_LEN_OFS |
1795                 unused << RTE_MBUF_TXOFLD_UNUSED_OFS;
1796 }
1797
1798 /**
1799  * Validate general requirements for Tx offload in mbuf.
1800  *
1801  * This function checks correctness and completeness of Tx offload settings.
1802  *
1803  * @param m
1804  *   The packet mbuf to be validated.
1805  * @return
1806  *   0 if packet is valid
1807  */
1808 static inline int
1809 rte_validate_tx_offload(const struct rte_mbuf *m)
1810 {
1811         uint64_t ol_flags = m->ol_flags;
1812
1813         /* Does packet set any of available offloads? */
1814         if (!(ol_flags & PKT_TX_OFFLOAD_MASK))
1815                 return 0;
1816
1817         /* IP checksum can be counted only for IPv4 packet */
1818         if ((ol_flags & PKT_TX_IP_CKSUM) && (ol_flags & PKT_TX_IPV6))
1819                 return -EINVAL;
1820
1821         /* IP type not set when required */
1822         if (ol_flags & (PKT_TX_L4_MASK | PKT_TX_TCP_SEG))
1823                 if (!(ol_flags & (PKT_TX_IPV4 | PKT_TX_IPV6)))
1824                         return -EINVAL;
1825
1826         /* Check requirements for TSO packet */
1827         if (ol_flags & PKT_TX_TCP_SEG)
1828                 if ((m->tso_segsz == 0) ||
1829                                 ((ol_flags & PKT_TX_IPV4) &&
1830                                 !(ol_flags & PKT_TX_IP_CKSUM)))
1831                         return -EINVAL;
1832
1833         /* PKT_TX_OUTER_IP_CKSUM set for non outer IPv4 packet. */
1834         if ((ol_flags & PKT_TX_OUTER_IP_CKSUM) &&
1835                         !(ol_flags & PKT_TX_OUTER_IPV4))
1836                 return -EINVAL;
1837
1838         return 0;
1839 }
1840
1841 /**
1842  * @internal used by rte_pktmbuf_linearize().
1843  */
1844 int __rte_pktmbuf_linearize(struct rte_mbuf *mbuf);
1845
1846 /**
1847  * Linearize data in mbuf.
1848  *
1849  * This function moves the mbuf data in the first segment if there is enough
1850  * tailroom. The subsequent segments are unchained and freed.
1851  *
1852  * @param mbuf
1853  *   mbuf to linearize
1854  * @return
1855  *   - 0, on success
1856  *   - -1, on error
1857  */
1858 static inline int
1859 rte_pktmbuf_linearize(struct rte_mbuf *mbuf)
1860 {
1861         if (rte_pktmbuf_is_contiguous(mbuf))
1862                 return 0;
1863         return __rte_pktmbuf_linearize(mbuf);
1864 }
1865
1866 /**
1867  * Dump an mbuf structure to a file.
1868  *
1869  * Dump all fields for the given packet mbuf and all its associated
1870  * segments (in the case of a chained buffer).
1871  *
1872  * @param f
1873  *   A pointer to a file for output
1874  * @param m
1875  *   The packet mbuf.
1876  * @param dump_len
1877  *   If dump_len != 0, also dump the "dump_len" first data bytes of
1878  *   the packet.
1879  */
1880 void rte_pktmbuf_dump(FILE *f, const struct rte_mbuf *m, unsigned dump_len);
1881
1882 /**
1883  * Get the value of mbuf sched queue_id field.
1884  */
1885 static inline uint32_t
1886 rte_mbuf_sched_queue_get(const struct rte_mbuf *m)
1887 {
1888         return m->hash.sched.queue_id;
1889 }
1890
1891 /**
1892  * Get the value of mbuf sched traffic_class field.
1893  */
1894 static inline uint8_t
1895 rte_mbuf_sched_traffic_class_get(const struct rte_mbuf *m)
1896 {
1897         return m->hash.sched.traffic_class;
1898 }
1899
1900 /**
1901  * Get the value of mbuf sched color field.
1902  */
1903 static inline uint8_t
1904 rte_mbuf_sched_color_get(const struct rte_mbuf *m)
1905 {
1906         return m->hash.sched.color;
1907 }
1908
1909 /**
1910  * Get the values of mbuf sched queue_id, traffic_class and color.
1911  *
1912  * @param m
1913  *   Mbuf to read
1914  * @param queue_id
1915  *  Returns the queue id
1916  * @param traffic_class
1917  *  Returns the traffic class id
1918  * @param color
1919  *  Returns the colour id
1920  */
1921 static inline void
1922 rte_mbuf_sched_get(const struct rte_mbuf *m, uint32_t *queue_id,
1923                         uint8_t *traffic_class,
1924                         uint8_t *color)
1925 {
1926         struct rte_mbuf_sched sched = m->hash.sched;
1927
1928         *queue_id = sched.queue_id;
1929         *traffic_class = sched.traffic_class;
1930         *color = sched.color;
1931 }
1932
1933 /**
1934  * Set the mbuf sched queue_id to the defined value.
1935  */
1936 static inline void
1937 rte_mbuf_sched_queue_set(struct rte_mbuf *m, uint32_t queue_id)
1938 {
1939         m->hash.sched.queue_id = queue_id;
1940 }
1941
1942 /**
1943  * Set the mbuf sched traffic_class id to the defined value.
1944  */
1945 static inline void
1946 rte_mbuf_sched_traffic_class_set(struct rte_mbuf *m, uint8_t traffic_class)
1947 {
1948         m->hash.sched.traffic_class = traffic_class;
1949 }
1950
1951 /**
1952  * Set the mbuf sched color id to the defined value.
1953  */
1954 static inline void
1955 rte_mbuf_sched_color_set(struct rte_mbuf *m, uint8_t color)
1956 {
1957         m->hash.sched.color = color;
1958 }
1959
1960 /**
1961  * Set the mbuf sched queue_id, traffic_class and color.
1962  *
1963  * @param m
1964  *   Mbuf to set
1965  * @param queue_id
1966  *  Queue id value to be set
1967  * @param traffic_class
1968  *  Traffic class id value to be set
1969  * @param color
1970  *  Color id to be set
1971  */
1972 static inline void
1973 rte_mbuf_sched_set(struct rte_mbuf *m, uint32_t queue_id,
1974                         uint8_t traffic_class,
1975                         uint8_t color)
1976 {
1977         m->hash.sched = (struct rte_mbuf_sched){
1978                                 .queue_id = queue_id,
1979                                 .traffic_class = traffic_class,
1980                                 .color = color,
1981                                 .reserved = 0,
1982                         };
1983 }
1984
1985 #ifdef __cplusplus
1986 }
1987 #endif
1988
1989 #endif /* _RTE_MBUF_H_ */