lib/librte_mbuf/rte_mbuf.h

   1 /*-
   2  *   BSD LICENSE
   3  *
   4  *   Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
   5  *   All rights reserved.
   6  *
   7  *   Redistribution and use in source and binary forms, with or without
   8  *   modification, are permitted provided that the following conditions
   9  *   are met:
  10  *
  11  *     * Redistributions of source code must retain the above copyright
  12  *       notice, this list of conditions and the following disclaimer.
  13  *     * Redistributions in binary form must reproduce the above copyright
  14  *       notice, this list of conditions and the following disclaimer in
  15  *       the documentation and/or other materials provided with the
  16  *       distribution.
  17  *     * Neither the name of Intel Corporation nor the names of its
  18  *       contributors may be used to endorse or promote products derived
  19  *       from this software without specific prior written permission.
  20  *
  21  *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  22  *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  23  *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  24  *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  25  *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  26  *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  27  *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  28  *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  29  *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  30  *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  31  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  32  */
  33
  34 #ifndef _RTE_MBUF_H_
  35 #define _RTE_MBUF_H_
  36
  37 /**
  38  * @file
  39  * RTE Mbuf
  40  *
  41  * The mbuf library provides the ability to create and destroy buffers
  42  * that may be used by the RTE application to store message
  43  * buffers. The message buffers are stored in a mempool, using the
  44  * RTE mempool library.
  45  *
  46  * This library provide an API to allocate/free mbufs, manipulate
  47  * control message buffer (ctrlmbuf), which are generic message
  48  * buffers, and packet buffers (pktmbuf), which are used to carry
  49  * network packets.
  50  *
  51  * To understand the concepts of packet buffers or mbufs, you
  52  * should read "TCP/IP Illustrated, Volume 2: The Implementation,
  53  * Addison-Wesley, 1995, ISBN 0-201-63354-X from Richard Stevens"
  54  * http://www.kohala.com/start/tcpipiv2.html
  55  *
  56  * The main modification of this implementation is the use of mbuf for
  57  * transports other than packets. mbufs can have other types.
  58  */
  59
  60 #include <stdint.h>
  61 #include <rte_mempool.h>
  62 #include <rte_atomic.h>
  63 #include <rte_prefetch.h>
  64 #include <rte_branch_prediction.h>
  65
  66 #ifdef __cplusplus
  67 extern "C" {
  68 #endif
  69
  70 /* deprecated feature, renamed in RTE_MBUF_REFCNT */
  71 #pragma GCC poison RTE_MBUF_SCATTER_GATHER
  72
  73 /**
  74  * A control message buffer.
  75  */
  76 struct rte_ctrlmbuf {
  77         void *data;        /**< Pointer to data. */
  78         uint32_t data_len; /**< Length of data. */
  79 };
  80
  81
  82 /*
  83  * Packet Offload Features Flags. It also carry packet type information.
  84  * Critical resources. Both rx/tx shared these bits. Be cautious on any change
  85  */
  86 #define PKT_RX_VLAN_PKT      0x0001 /**< RX packet is a 802.1q VLAN packet. */
  87 #define PKT_RX_RSS_HASH      0x0002 /**< RX packet with RSS hash result. */
  88 #define PKT_RX_FDIR          0x0004 /**< RX packet with FDIR infos. */
  89 #define PKT_RX_L4_CKSUM_BAD  0x0008 /**< L4 cksum of RX pkt. is not OK. */
  90 #define PKT_RX_IP_CKSUM_BAD  0x0010 /**< IP cksum of RX pkt. is not OK. */
  91 #define PKT_RX_EIP_CKSUM_BAD 0x0000 /**< External IP header checksum error. */
  92 #define PKT_RX_OVERSIZE      0x0000 /**< Num of desc of an RX pkt oversize. */
  93 #define PKT_RX_HBUF_OVERFLOW 0x0000 /**< Header buffer overflow. */
  94 #define PKT_RX_RECIP_ERR     0x0000 /**< Hardware processing error. */
  95 #define PKT_RX_MAC_ERR       0x0000 /**< MAC error. */
  96 #define PKT_RX_IPV4_HDR      0x0020 /**< RX packet with IPv4 header. */
  97 #define PKT_RX_IPV4_HDR_EXT  0x0040 /**< RX packet with extended IPv4 header. */
  98 #define PKT_RX_IPV6_HDR      0x0080 /**< RX packet with IPv6 header. */
  99 #define PKT_RX_IPV6_HDR_EXT  0x0100 /**< RX packet with extended IPv6 header. */
 100 #define PKT_RX_IEEE1588_PTP  0x0200 /**< RX IEEE1588 L2 Ethernet PT Packet. */
 101 #define PKT_RX_IEEE1588_TMST 0x0400 /**< RX IEEE1588 L2/L4 timestamped packet.*/
 102
 103 #define PKT_TX_VLAN_PKT      0x0800 /**< TX packet is a 802.1q VLAN packet. */
 104 #define PKT_TX_IP_CKSUM      0x1000 /**< IP cksum of TX pkt. computed by NIC. */
 105 #define PKT_TX_IPV4_CSUM     0x1000 /**< Alias of PKT_TX_IP_CKSUM. */
 106 #define PKT_TX_IPV4          PKT_RX_IPV4_HDR /**< IPv4 with no IP checksum offload. */
 107 #define PKT_TX_IPV6          PKT_RX_IPV6_HDR /**< IPv6 packet */
 108 /*
 109  * Bit 14~13 used for L4 packet type with checksum enabled.
 110  *     00: Reserved
 111  *     01: TCP checksum
 112  *     10: SCTP checksum
 113  *     11: UDP checksum
 114  */
 115 #define PKT_TX_L4_MASK       0x6000 /**< Mask bits for L4 checksum offload request. */
 116 #define PKT_TX_L4_NO_CKSUM   0x0000 /**< Disable L4 cksum of TX pkt. */
 117 #define PKT_TX_TCP_CKSUM     0x2000 /**< TCP cksum of TX pkt. computed by NIC. */
 118 #define PKT_TX_SCTP_CKSUM    0x4000 /**< SCTP cksum of TX pkt. computed by NIC. */
 119 #define PKT_TX_UDP_CKSUM     0x6000 /**< UDP cksum of TX pkt. computed by NIC. */
 120 /* Bit 15 */
 121 #define PKT_TX_IEEE1588_TMST 0x8000 /**< TX IEEE1588 packet to timestamp. */
 122
 123 /**
 124  * Bit Mask to indicate what bits required for building TX context
 125  */
 126 #define PKT_TX_OFFLOAD_MASK (PKT_TX_VLAN_PKT | PKT_TX_IP_CKSUM | PKT_TX_L4_MASK)
 127
 128 /** Offload features */
 129 union rte_vlan_macip {
 130         uint32_t data;
 131         struct {
 132                 uint16_t l3_len:9; /**< L3 (IP) Header Length. */
 133                 uint16_t l2_len:7; /**< L2 (MAC) Header Length. */
 134                 uint16_t vlan_tci;
 135                 /**< VLAN Tag Control Identifier (CPU order). */
 136         } f;
 137 };
 138
 139 /*
 140  * Compare mask for vlan_macip_len.data,
 141  * should be in sync with rte_vlan_macip.f layout.
 142  * */
 143 #define TX_VLAN_CMP_MASK        0xFFFF0000  /**< VLAN length - 16-bits. */
 144 #define TX_MAC_LEN_CMP_MASK     0x0000FE00  /**< MAC length - 7-bits. */
 145 #define TX_IP_LEN_CMP_MASK      0x000001FF  /**< IP  length - 9-bits. */
 146 /**< MAC+IP  length. */
 147 #define TX_MACIP_LEN_CMP_MASK   (TX_MAC_LEN_CMP_MASK | TX_IP_LEN_CMP_MASK)
 148
 149 /**
 150  * A packet message buffer.
 151  */
 152 struct rte_pktmbuf {
 153         /* valid for any segment */
 154         struct rte_mbuf *next;  /**< Next segment of scattered packet. */
 155         void* data;             /**< Start address of data in segment buffer. */
 156         uint16_t data_len;      /**< Amount of data in segment buffer. */
 157
 158         /* these fields are valid for first segment only */
 159         uint8_t nb_segs;        /**< Number of segments. */
 160         uint8_t in_port;        /**< Input port. */
 161         uint32_t pkt_len;       /**< Total pkt len: sum of all segment data_len. */
 162
 163         /* offload features */
 164         union rte_vlan_macip vlan_macip;
 165         union {
 166                 uint32_t rss;       /**< RSS hash result if RSS enabled */
 167                 struct {
 168                         uint16_t hash;
 169                         uint16_t id;
 170                 } fdir;             /**< Filter identifier if FDIR enabled */
 171                 uint32_t sched;     /**< Hierarchical scheduler */
 172         } hash;                 /**< hash information */
 173 };
 174
 175 /**
 176  * This enum indicates the mbuf type.
 177  */
 178 enum rte_mbuf_type {
 179         RTE_MBUF_CTRL,  /**< Control mbuf. */
 180         RTE_MBUF_PKT,   /**< Packet mbuf. */
 181 };
 182
 183 /**
 184  * The generic rte_mbuf, containing a packet mbuf or a control mbuf.
 185  */
 186 struct rte_mbuf {
 187         struct rte_mempool *pool; /**< Pool from which mbuf was allocated. */
 188         void *buf_addr;           /**< Virtual address of segment buffer. */
 189         phys_addr_t buf_physaddr; /**< Physical address of segment buffer. */
 190         uint16_t buf_len;         /**< Length of segment buffer. */
 191 #ifdef RTE_MBUF_REFCNT
 192         /**
 193          * 16-bit Reference counter.
 194          * It should only be accessed using the following functions:
 195          * rte_mbuf_refcnt_update(), rte_mbuf_refcnt_read(), and
 196          * rte_mbuf_refcnt_set(). The functionality of these functions (atomic,
 197          * or non-atomic) is controlled by the CONFIG_RTE_MBUF_REFCNT_ATOMIC
 198          * config option.
 199          */
 200         union {
 201                 rte_atomic16_t refcnt_atomic;   /**< Atomically accessed refcnt */
 202                 uint16_t refcnt;                /**< Non-atomically accessed refcnt */
 203         };
 204 #else
 205         uint16_t refcnt_reserved;     /**< Do not use this field */
 206 #endif
 207         uint8_t type;                 /**< Type of mbuf. */
 208         uint8_t reserved;             /**< Unused field. Required for padding. */
 209         uint16_t ol_flags;            /**< Offload features. */
 210
 211         union {
 212                 struct rte_ctrlmbuf ctrl;
 213                 struct rte_pktmbuf pkt;
 214         };
 215
 216         union {
 217                 uint8_t metadata[0];
 218                 uint16_t metadata16[0];
 219                 uint32_t metadata32[0];
 220                 uint64_t metadata64[0];
 221         };
 222 } __rte_cache_aligned;
 223
 224 #define RTE_MBUF_METADATA_UINT8(mbuf, offset)              \
 225         (mbuf->metadata[offset])
 226 #define RTE_MBUF_METADATA_UINT16(mbuf, offset)             \
 227         (mbuf->metadata16[offset/sizeof(uint16_t)])
 228 #define RTE_MBUF_METADATA_UINT32(mbuf, offset)             \
 229         (mbuf->metadata32[offset/sizeof(uint32_t)])
 230 #define RTE_MBUF_METADATA_UINT64(mbuf, offset)             \
 231         (mbuf->metadata64[offset/sizeof(uint64_t)])
 232
 233 #define RTE_MBUF_METADATA_UINT8_PTR(mbuf, offset)          \
 234         (&mbuf->metadata[offset])
 235 #define RTE_MBUF_METADATA_UINT16_PTR(mbuf, offset)         \
 236         (&mbuf->metadata16[offset/sizeof(uint16_t)])
 237 #define RTE_MBUF_METADATA_UINT32_PTR(mbuf, offset)         \
 238         (&mbuf->metadata32[offset/sizeof(uint32_t)])
 239 #define RTE_MBUF_METADATA_UINT64_PTR(mbuf, offset)         \
 240         (&mbuf->metadata64[offset/sizeof(uint64_t)])
 241
 242 /**
 243  * Given the buf_addr returns the pointer to corresponding mbuf.
 244  */
 245 #define RTE_MBUF_FROM_BADDR(ba)     (((struct rte_mbuf *)(ba)) - 1)
 246
 247 /**
 248  * Given the pointer to mbuf returns an address where it's  buf_addr
 249  * should point to.
 250  */
 251 #define RTE_MBUF_TO_BADDR(mb)       (((struct rte_mbuf *)(mb)) + 1)
 252
 253 /**
 254  * Returns TRUE if given mbuf is indirect, or FALSE otherwise.
 255  */
 256 #define RTE_MBUF_INDIRECT(mb)   (RTE_MBUF_FROM_BADDR((mb)->buf_addr) != (mb))
 257
 258 /**
 259  * Returns TRUE if given mbuf is direct, or FALSE otherwise.
 260  */
 261 #define RTE_MBUF_DIRECT(mb)     (RTE_MBUF_FROM_BADDR((mb)->buf_addr) == (mb))
 262
 263
 264 /**
 265  * Private data in case of pktmbuf pool.
 266  *
 267  * A structure that contains some pktmbuf_pool-specific data that are
 268  * appended after the mempool structure (in private data).
 269  */
 270 struct rte_pktmbuf_pool_private {
 271         uint16_t mbuf_data_room_size; /**< Size of data space in each mbuf.*/
 272 };
 273
 274 #ifdef RTE_LIBRTE_MBUF_DEBUG
 275
 276 /**  check mbuf type in debug mode */
 277 #define __rte_mbuf_sanity_check(m, t, is_h) rte_mbuf_sanity_check(m, t, is_h)
 278
 279 /**  check mbuf type in debug mode if mbuf pointer is not null */
 280 #define __rte_mbuf_sanity_check_raw(m, t, is_h) do {       \
 281         if ((m) != NULL)                                   \
 282                 rte_mbuf_sanity_check(m, t, is_h);          \
 283 } while (0)
 284
 285 /**  MBUF asserts in debug mode */
 286 #define RTE_MBUF_ASSERT(exp)                                         \
 287 if (!(exp)) {                                                        \
 288         rte_panic("line%d\tassert \"" #exp "\" failed\n", __LINE__); \
 289 }
 290
 291 #else /*  RTE_LIBRTE_MBUF_DEBUG */
 292
 293 /**  check mbuf type in debug mode */
 294 #define __rte_mbuf_sanity_check(m, t, is_h) do { } while(0)
 295
 296 /**  check mbuf type in debug mode if mbuf pointer is not null */
 297 #define __rte_mbuf_sanity_check_raw(m, t, is_h) do { } while(0)
 298
 299 /**  MBUF asserts in debug mode */
 300 #define RTE_MBUF_ASSERT(exp)                do { } while(0)
 301
 302 #endif /*  RTE_LIBRTE_MBUF_DEBUG */
 303
 304 #ifdef RTE_MBUF_REFCNT
 305 #ifdef RTE_MBUF_REFCNT_ATOMIC
 306
 307 /**
 308  * Adds given value to an mbuf's refcnt and returns its new value.
 309  * @param m
 310  *   Mbuf to update
 311  * @param value
 312  *   Value to add/subtract
 313  * @return
 314  *   Updated value
 315  */
 316 static inline uint16_t
 317 rte_mbuf_refcnt_update(struct rte_mbuf *m, int16_t value)
 318 {
 319         return (uint16_t)(rte_atomic16_add_return(&m->refcnt_atomic, value));
 320 }
 321
 322 /**
 323  * Reads the value of an mbuf's refcnt.
 324  * @param m
 325  *   Mbuf to read
 326  * @return
 327  *   Reference count number.
 328  */
 329 static inline uint16_t
 330 rte_mbuf_refcnt_read(const struct rte_mbuf *m)
 331 {
 332         return (uint16_t)(rte_atomic16_read(&m->refcnt_atomic));
 333 }
 334
 335 /**
 336  * Sets an mbuf's refcnt to a defined value.
 337  * @param m
 338  *   Mbuf to update
 339  * @param new_value
 340  *   Value set
 341  */
 342 static inline void
 343 rte_mbuf_refcnt_set(struct rte_mbuf *m, uint16_t new_value)
 344 {
 345         rte_atomic16_set(&m->refcnt_atomic, new_value);
 346 }
 347
 348 #else /* ! RTE_MBUF_REFCNT_ATOMIC */
 349
 350 /**
 351  * Adds given value to an mbuf's refcnt and returns its new value.
 352  */
 353 static inline uint16_t
 354 rte_mbuf_refcnt_update(struct rte_mbuf *m, int16_t value)
 355 {
 356         m->refcnt = (uint16_t)(m->refcnt + value);
 357         return m->refcnt;
 358 }
 359
 360 /**
 361  * Reads the value of an mbuf's refcnt.
 362  */
 363 static inline uint16_t
 364 rte_mbuf_refcnt_read(const struct rte_mbuf *m)
 365 {
 366         return m->refcnt;
 367 }
 368
 369 /**
 370  * Sets an mbuf's refcnt to the defined value.
 371  */
 372 static inline void
 373 rte_mbuf_refcnt_set(struct rte_mbuf *m, uint16_t new_value)
 374 {
 375         m->refcnt = new_value;
 376 }
 377
 378 #endif /* RTE_MBUF_REFCNT_ATOMIC */
 379
 380 /** Mbuf prefetch */
 381 #define RTE_MBUF_PREFETCH_TO_FREE(m) do {       \
 382         if ((m) != NULL)                        \
 383                 rte_prefetch0(m);               \
 384 } while (0)
 385
 386 #else /* ! RTE_MBUF_REFCNT */
 387
 388 /** Mbuf prefetch */
 389 #define RTE_MBUF_PREFETCH_TO_FREE(m) do { } while(0)
 390
 391 #define rte_mbuf_refcnt_set(m,v) do { } while(0)
 392
 393 #endif /* RTE_MBUF_REFCNT */
 394
 395
 396 /**
 397  * Sanity checks on an mbuf.
 398  *
 399  * Check the consistency of the given mbuf. The function will cause a
 400  * panic if corruption is detected.
 401  *
 402  * @param m
 403  *   The mbuf to be checked.
 404  * @param t
 405  *   The expected type of the mbuf.
 406  * @param is_header
 407  *   True if the mbuf is a packet header, false if it is a sub-segment
 408  *   of a packet (in this case, some fields like nb_segs are not checked)
 409  */
 410 void
 411 rte_mbuf_sanity_check(const struct rte_mbuf *m, enum rte_mbuf_type t,
 412                       int is_header);
 413
 414 /**
 415  * @internal Allocate a new mbuf from mempool *mp*.
 416  * The use of that function is reserved for RTE internal needs.
 417  * Please use either rte_ctrlmbuf_alloc() or rte_pktmbuf_alloc().
 418  *
 419  * @param mp
 420  *   The mempool from which mbuf is allocated.
 421  * @return
 422  *   - The pointer to the new mbuf on success.
 423  *   - NULL if allocation failed.
 424  */
 425 static inline struct rte_mbuf *__rte_mbuf_raw_alloc(struct rte_mempool *mp)
 426 {
 427         struct rte_mbuf *m;
 428         void *mb = NULL;
 429         if (rte_mempool_get(mp, &mb) < 0)
 430                 return NULL;
 431         m = (struct rte_mbuf *)mb;
 432 #ifdef RTE_MBUF_REFCNT
 433         RTE_MBUF_ASSERT(rte_mbuf_refcnt_read(m) == 0);
 434         rte_mbuf_refcnt_set(m, 1);
 435 #endif /* RTE_MBUF_REFCNT */
 436         return (m);
 437 }
 438
 439 /**
 440  * @internal Put mbuf back into its original mempool.
 441  * The use of that function is reserved for RTE internal needs.
 442  * Please use either rte_ctrlmbuf_free() or rte_pktmbuf_free().
 443  *
 444  * @param m
 445  *   The mbuf to be freed.
 446  */
 447 static inline void __attribute__((always_inline))
 448 __rte_mbuf_raw_free(struct rte_mbuf *m)
 449 {
 450 #ifdef RTE_MBUF_REFCNT
 451         RTE_MBUF_ASSERT(rte_mbuf_refcnt_read(m) == 0);
 452 #endif /* RTE_MBUF_REFCNT */
 453         rte_mempool_put(m->pool, m);
 454 }
 455
 456 /* Operations on ctrl mbuf */
 457
 458 /**
 459  * The control mbuf constructor.
 460  *
 461  * This function initializes some fields in an mbuf structure that are
 462  * not modified by the user once created (mbuf type, origin pool, buffer
 463  * start address, and so on). This function is given as a callback function
 464  * to rte_mempool_create() at pool creation time.
 465  *
 466  * @param mp
 467  *   The mempool from which the mbuf is allocated.
 468  * @param opaque_arg
 469  *   A pointer that can be used by the user to retrieve useful information
 470  *   for mbuf initialization. This pointer comes from the ``init_arg``
 471  *   parameter of rte_mempool_create().
 472  * @param m
 473  *   The mbuf to initialize.
 474  * @param i
 475  *   The index of the mbuf in the pool table.
 476  */
 477 void rte_ctrlmbuf_init(struct rte_mempool *mp, void *opaque_arg,
 478                        void *m, unsigned i);
 479
 480 /**
 481  * Allocate a new mbuf (type is ctrl) from mempool *mp*.
 482  *
 483  * This new mbuf is initialized with data pointing to the beginning of
 484  * buffer, and with a length of zero.
 485  *
 486  * @param mp
 487  *   The mempool from which the 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_ctrlmbuf_alloc(struct rte_mempool *mp)
 493 {
 494         struct rte_mbuf *m;
 495         if ((m = __rte_mbuf_raw_alloc(mp)) != NULL) {
 496                 m->ctrl.data = m->buf_addr;
 497                 m->ctrl.data_len = 0;
 498                 __rte_mbuf_sanity_check(m, RTE_MBUF_CTRL, 0);
 499         }
 500         return (m);
 501 }
 502
 503 /**
 504  * Free a control mbuf back into its original mempool.
 505  *
 506  * @param m
 507  *   The control mbuf to be freed.
 508  */
 509 static inline void rte_ctrlmbuf_free(struct rte_mbuf *m)
 510 {
 511         __rte_mbuf_sanity_check(m, RTE_MBUF_CTRL, 0);
 512 #ifdef RTE_MBUF_REFCNT
 513         if (rte_mbuf_refcnt_update(m, -1) == 0)
 514 #endif /* RTE_MBUF_REFCNT */
 515                 __rte_mbuf_raw_free(m);
 516 }
 517
 518 /**
 519  * A macro that returns the pointer to the carried data.
 520  *
 521  * The value that can be read or assigned.
 522  *
 523  * @param m
 524  *   The control mbuf.
 525  */
 526 #define rte_ctrlmbuf_data(m) ((m)->ctrl.data)
 527
 528 /**
 529  * A macro that returns the length of the carried data.
 530  *
 531  * The value that can be read or assigned.
 532  *
 533  * @param m
 534  *   The control mbuf.
 535  */
 536 #define rte_ctrlmbuf_len(m) ((m)->ctrl.data_len)
 537
 538 /* Operations on pkt mbuf */
 539
 540 /**
 541  * The packet mbuf constructor.
 542  *
 543  * This function initializes some fields in the mbuf structure that are not
 544  * modified by the user once created (mbuf type, origin pool, buffer start
 545  * address, and so on). This function is given as a callback function to
 546  * rte_mempool_create() at pool creation time.
 547  *
 548  * @param mp
 549  *   The mempool from which mbufs originate.
 550  * @param opaque_arg
 551  *   A pointer that can be used by the user to retrieve useful information
 552  *   for mbuf initialization. This pointer comes from the ``init_arg``
 553  *   parameter of rte_mempool_create().
 554  * @param m
 555  *   The mbuf to initialize.
 556  * @param i
 557  *   The index of the mbuf in the pool table.
 558  */
 559 void rte_pktmbuf_init(struct rte_mempool *mp, void *opaque_arg,
 560                       void *m, unsigned i);
 561
 562
 563 /**
 564  * A  packet mbuf pool constructor.
 565  *
 566  * This function initializes the mempool private data in the case of a
 567  * pktmbuf pool. This private data is needed by the driver. The
 568  * function is given as a callback function to rte_mempool_create() at
 569  * pool creation. It can be extended by the user, for example, to
 570  * provide another packet size.
 571  *
 572  * @param mp
 573  *   The mempool from which mbufs originate.
 574  * @param opaque_arg
 575  *   A pointer that can be used by the user to retrieve useful information
 576  *   for mbuf initialization. This pointer comes from the ``init_arg``
 577  *   parameter of rte_mempool_create().
 578  */
 579 void rte_pktmbuf_pool_init(struct rte_mempool *mp, void *opaque_arg);
 580
 581 /**
 582  * Reset the fields of a packet mbuf to their default values.
 583  *
 584  * The given mbuf must have only one segment.
 585  *
 586  * @param m
 587  *   The packet mbuf to be resetted.
 588  */
 589 static inline void rte_pktmbuf_reset(struct rte_mbuf *m)
 590 {
 591         uint32_t buf_ofs;
 592
 593         m->pkt.next = NULL;
 594         m->pkt.pkt_len = 0;
 595         m->pkt.vlan_macip.data = 0;
 596         m->pkt.nb_segs = 1;
 597         m->pkt.in_port = 0xff;
 598
 599         m->ol_flags = 0;
 600         buf_ofs = (RTE_PKTMBUF_HEADROOM <= m->buf_len) ?
 601                         RTE_PKTMBUF_HEADROOM : m->buf_len;
 602         m->pkt.data = (char*) m->buf_addr + buf_ofs;
 603
 604         m->pkt.data_len = 0;
 605         __rte_mbuf_sanity_check(m, RTE_MBUF_PKT, 1);
 606 }
 607
 608 /**
 609  * Allocate a new mbuf (type is pkt) from a mempool.
 610  *
 611  * This new mbuf contains one segment, which has a length of 0. The pointer
 612  * to data is initialized to have some bytes of headroom in the buffer
 613  * (if buffer size allows).
 614  *
 615  * @param mp
 616  *   The mempool from which the mbuf is allocated.
 617  * @return
 618  *   - The pointer to the new mbuf on success.
 619  *   - NULL if allocation failed.
 620  */
 621 static inline struct rte_mbuf *rte_pktmbuf_alloc(struct rte_mempool *mp)
 622 {
 623         struct rte_mbuf *m;
 624         if ((m = __rte_mbuf_raw_alloc(mp)) != NULL)
 625                 rte_pktmbuf_reset(m);
 626         return (m);
 627 }
 628
 629 #ifdef RTE_MBUF_REFCNT
 630
 631 /**
 632  * Attach packet mbuf to another packet mbuf.
 633  * After attachment we refer the mbuf we attached as 'indirect',
 634  * while mbuf we attached to as 'direct'.
 635  * Right now, not supported:
 636  *  - attachment to indirect mbuf (e.g. - md  has to be direct).
 637  *  - attachment for already indirect mbuf (e.g. - mi has to be direct).
 638  *  - mbuf we trying to attach (mi) is used by someone else
 639  *    e.g. it's reference counter is greater then 1.
 640  *
 641  * @param mi
 642  *   The indirect packet mbuf.
 643  * @param md
 644  *   The direct packet mbuf.
 645  */
 646
 647 static inline void rte_pktmbuf_attach(struct rte_mbuf *mi, struct rte_mbuf *md)
 648 {
 649         RTE_MBUF_ASSERT(RTE_MBUF_DIRECT(md) &&
 650             RTE_MBUF_DIRECT(mi) &&
 651             rte_mbuf_refcnt_read(mi) == 1);
 652
 653         rte_mbuf_refcnt_update(md, 1);
 654         mi->buf_physaddr = md->buf_physaddr;
 655         mi->buf_addr = md->buf_addr;
 656         mi->buf_len = md->buf_len;
 657
 658         mi->pkt = md->pkt;
 659
 660         mi->pkt.next = NULL;
 661         mi->pkt.pkt_len = mi->pkt.data_len;
 662         mi->pkt.nb_segs = 1;
 663         mi->ol_flags = md->ol_flags;
 664
 665         __rte_mbuf_sanity_check(mi, RTE_MBUF_PKT, 1);
 666         __rte_mbuf_sanity_check(md, RTE_MBUF_PKT, 0);
 667 }
 668
 669 /**
 670  * Detach an indirect packet mbuf -
 671  *  - restore original mbuf address and length values.
 672  *  - reset pktmbuf data and data_len to their default values.
 673  *  All other fields of the given packet mbuf will be left intact.
 674  *
 675  * @param m
 676  *   The indirect attached packet mbuf.
 677  */
 678
 679 static inline void rte_pktmbuf_detach(struct rte_mbuf *m)
 680 {
 681         const struct rte_mempool *mp = m->pool;
 682         void *buf = RTE_MBUF_TO_BADDR(m);
 683         uint32_t buf_ofs;
 684         uint32_t buf_len = mp->elt_size - sizeof(*m);
 685         m->buf_physaddr = rte_mempool_virt2phy(mp, m) + sizeof (*m);
 686
 687         m->buf_addr = buf;
 688         m->buf_len = (uint16_t)buf_len;
 689
 690         buf_ofs = (RTE_PKTMBUF_HEADROOM <= m->buf_len) ?
 691                         RTE_PKTMBUF_HEADROOM : m->buf_len;
 692         m->pkt.data = (char*) m->buf_addr + buf_ofs;
 693
 694         m->pkt.data_len = 0;
 695 }
 696
 697 #endif /* RTE_MBUF_REFCNT */
 698
 699
 700 static inline struct rte_mbuf* __attribute__((always_inline))
 701 __rte_pktmbuf_prefree_seg(struct rte_mbuf *m)
 702 {
 703         __rte_mbuf_sanity_check(m, RTE_MBUF_PKT, 0);
 704
 705 #ifdef RTE_MBUF_REFCNT
 706         if (likely (rte_mbuf_refcnt_read(m) == 1) ||
 707                         likely (rte_mbuf_refcnt_update(m, -1) == 0)) {
 708                 struct rte_mbuf *md = RTE_MBUF_FROM_BADDR(m->buf_addr);
 709
 710                 rte_mbuf_refcnt_set(m, 0);
 711
 712                 /* if this is an indirect mbuf, then
 713                  *  - detach mbuf
 714                  *  - free attached mbuf segment
 715                  */
 716                 if (unlikely (md != m)) {
 717                         rte_pktmbuf_detach(m);
 718                         if (rte_mbuf_refcnt_update(md, -1) == 0)
 719                                 __rte_mbuf_raw_free(md);
 720                 }
 721 #endif
 722                 return(m);
 723 #ifdef RTE_MBUF_REFCNT
 724         }
 725         return (NULL);
 726 #endif
 727 }
 728
 729 /**
 730  * Free a segment of a packet mbuf into its original mempool.
 731  *
 732  * Free an mbuf, without parsing other segments in case of chained
 733  * buffers.
 734  *
 735  * @param m
 736  *   The packet mbuf segment to be freed.
 737  */
 738 static inline void __attribute__((always_inline))
 739 rte_pktmbuf_free_seg(struct rte_mbuf *m)
 740 {
 741         if (likely(NULL != (m = __rte_pktmbuf_prefree_seg(m))))
 742                 __rte_mbuf_raw_free(m);
 743 }
 744
 745 /**
 746  * Free a packet mbuf back into its original mempool.
 747  *
 748  * Free an mbuf, and all its segments in case of chained buffers. Each
 749  * segment is added back into its original mempool.
 750  *
 751  * @param m
 752  *   The packet mbuf to be freed.
 753  */
 754 static inline void rte_pktmbuf_free(struct rte_mbuf *m)
 755 {
 756         struct rte_mbuf *m_next;
 757
 758         __rte_mbuf_sanity_check(m, RTE_MBUF_PKT, 1);
 759
 760         while (m != NULL) {
 761                 m_next = m->pkt.next;
 762                 rte_pktmbuf_free_seg(m);
 763                 m = m_next;
 764         }
 765 }
 766
 767 #ifdef RTE_MBUF_REFCNT
 768
 769 /**
 770  * Creates a "clone" of the given packet mbuf.
 771  *
 772  * Walks through all segments of the given packet mbuf, and for each of them:
 773  *  - Creates a new packet mbuf from the given pool.
 774  *  - Attaches newly created mbuf to the segment.
 775  * Then updates pkt_len and nb_segs of the "clone" packet mbuf to match values
 776  * from the original packet mbuf.
 777  *
 778  * @param md
 779  *   The packet mbuf to be cloned.
 780  * @param mp
 781  *   The mempool from which the "clone" mbufs are allocated.
 782  * @return
 783  *   - The pointer to the new "clone" mbuf on success.
 784  *   - NULL if allocation fails.
 785  */
 786 static inline struct rte_mbuf *rte_pktmbuf_clone(struct rte_mbuf *md,
 787                 struct rte_mempool *mp)
 788 {
 789         struct rte_mbuf *mc, *mi, **prev;
 790         uint32_t pktlen;
 791         uint8_t nseg;
 792
 793         if (unlikely ((mc = rte_pktmbuf_alloc(mp)) == NULL))
 794                 return (NULL);
 795
 796         mi = mc;
 797         prev = &mi->pkt.next;
 798         pktlen = md->pkt.pkt_len;
 799         nseg = 0;
 800
 801         do {
 802                 nseg++;
 803                 rte_pktmbuf_attach(mi, md);
 804                 *prev = mi;
 805                 prev = &mi->pkt.next;
 806         } while ((md = md->pkt.next) != NULL &&
 807             (mi = rte_pktmbuf_alloc(mp)) != NULL);
 808
 809         *prev = NULL;
 810         mc->pkt.nb_segs = nseg;
 811         mc->pkt.pkt_len = pktlen;
 812
 813         /* Allocation of new indirect segment failed */
 814         if (unlikely (mi == NULL)) {
 815                 rte_pktmbuf_free(mc);
 816                 return (NULL);
 817         }
 818
 819         __rte_mbuf_sanity_check(mc, RTE_MBUF_PKT, 1);
 820         return (mc);
 821 }
 822
 823 /**
 824  * Adds given value to the refcnt of all packet mbuf segments.
 825  *
 826  * Walks through all segments of given packet mbuf and for each of them
 827  * invokes rte_mbuf_refcnt_update().
 828  *
 829  * @param m
 830  *   The packet mbuf whose refcnt to be updated.
 831  * @param v
 832  *   The value to add to the mbuf's segments refcnt.
 833  */
 834 static inline void rte_pktmbuf_refcnt_update(struct rte_mbuf *m, int16_t v)
 835 {
 836         __rte_mbuf_sanity_check(m, RTE_MBUF_PKT, 1);
 837
 838         do {
 839                 rte_mbuf_refcnt_update(m, v);
 840         } while ((m = m->pkt.next) != NULL);
 841 }
 842
 843 #endif /* RTE_MBUF_REFCNT */
 844
 845 /**
 846  * Get the headroom in a packet mbuf.
 847  *
 848  * @param m
 849  *   The packet mbuf.
 850  * @return
 851  *   The length of the headroom.
 852  */
 853 static inline uint16_t rte_pktmbuf_headroom(const struct rte_mbuf *m)
 854 {
 855         __rte_mbuf_sanity_check(m, RTE_MBUF_PKT, 1);
 856         return (uint16_t) ((char*) m->pkt.data - (char*) m->buf_addr);
 857 }
 858
 859 /**
 860  * Get the tailroom of a packet mbuf.
 861  *
 862  * @param m
 863  *   The packet mbuf.
 864  * @return
 865  *   The length of the tailroom.
 866  */
 867 static inline uint16_t rte_pktmbuf_tailroom(const struct rte_mbuf *m)
 868 {
 869         __rte_mbuf_sanity_check(m, RTE_MBUF_PKT, 1);
 870         return (uint16_t)(m->buf_len - rte_pktmbuf_headroom(m) -
 871                           m->pkt.data_len);
 872 }
 873
 874 /**
 875  * Get the last segment of the packet.
 876  *
 877  * @param m
 878  *   The packet mbuf.
 879  * @return
 880  *   The last segment of the given mbuf.
 881  */
 882 static inline struct rte_mbuf *rte_pktmbuf_lastseg(struct rte_mbuf *m)
 883 {
 884         struct rte_mbuf *m2 = (struct rte_mbuf *)m;
 885
 886         __rte_mbuf_sanity_check(m, RTE_MBUF_PKT, 1);
 887         while (m2->pkt.next != NULL)
 888                 m2 = m2->pkt.next;
 889         return m2;
 890 }
 891
 892 /**
 893  * A macro that points to the start of the data in the mbuf.
 894  *
 895  * The returned pointer is cast to type t. Before using this
 896  * function, the user must ensure that m_headlen(m) is large enough to
 897  * read its data.
 898  *
 899  * @param m
 900  *   The packet mbuf.
 901  * @param t
 902  *   The type to cast the result into.
 903  */
 904 #define rte_pktmbuf_mtod(m, t) ((t)((m)->pkt.data))
 905
 906 /**
 907  * A macro that returns the length of the packet.
 908  *
 909  * The value can be read or assigned.
 910  *
 911  * @param m
 912  *   The packet mbuf.
 913  */
 914 #define rte_pktmbuf_pkt_len(m) ((m)->pkt.pkt_len)
 915
 916 /**
 917  * A macro that returns the length of the segment.
 918  *
 919  * The value can be read or assigned.
 920  *
 921  * @param m
 922  *   The packet mbuf.
 923  */
 924 #define rte_pktmbuf_data_len(m) ((m)->pkt.data_len)
 925
 926 /**
 927  * Prepend len bytes to an mbuf data area.
 928  *
 929  * Returns a pointer to the new
 930  * data start address. If there is not enough headroom in the first
 931  * segment, the function will return NULL, without modifying the mbuf.
 932  *
 933  * @param m
 934  *   The pkt mbuf.
 935  * @param len
 936  *   The amount of data to prepend (in bytes).
 937  * @return
 938  *   A pointer to the start of the newly prepended data, or
 939  *   NULL if there is not enough headroom space in the first segment
 940  */
 941 static inline char *rte_pktmbuf_prepend(struct rte_mbuf *m,
 942                                         uint16_t len)
 943 {
 944         __rte_mbuf_sanity_check(m, RTE_MBUF_PKT, 1);
 945
 946         if (unlikely(len > rte_pktmbuf_headroom(m)))
 947                 return NULL;
 948
 949         m->pkt.data = (char*) m->pkt.data - len;
 950         m->pkt.data_len = (uint16_t)(m->pkt.data_len + len);
 951         m->pkt.pkt_len  = (m->pkt.pkt_len + len);
 952
 953         return (char*) m->pkt.data;
 954 }
 955
 956 /**
 957  * Append len bytes to an mbuf.
 958  *
 959  * Append len bytes to an mbuf and return a pointer to the start address
 960  * of the added data. If there is not enough tailroom in the last
 961  * segment, the function will return NULL, without modifying the mbuf.
 962  *
 963  * @param m
 964  *   The packet mbuf.
 965  * @param len
 966  *   The amount of data to append (in bytes).
 967  * @return
 968  *   A pointer to the start of the newly appended data, or
 969  *   NULL if there is not enough tailroom space in the last segment
 970  */
 971 static inline char *rte_pktmbuf_append(struct rte_mbuf *m, uint16_t len)
 972 {
 973         void *tail;
 974         struct rte_mbuf *m_last;
 975
 976         __rte_mbuf_sanity_check(m, RTE_MBUF_PKT, 1);
 977
 978         m_last = rte_pktmbuf_lastseg(m);
 979         if (unlikely(len > rte_pktmbuf_tailroom(m_last)))
 980                 return NULL;
 981
 982         tail = (char*) m_last->pkt.data + m_last->pkt.data_len;
 983         m_last->pkt.data_len = (uint16_t)(m_last->pkt.data_len + len);
 984         m->pkt.pkt_len  = (m->pkt.pkt_len + len);
 985         return (char*) tail;
 986 }
 987
 988 /**
 989  * Remove len bytes at the beginning of an mbuf.
 990  *
 991  * Returns a pointer to the start address of the new data area. If the
 992  * length is greater than the length of the first segment, then the
 993  * function will fail and return NULL, without modifying the mbuf.
 994  *
 995  * @param m
 996  *   The packet mbuf.
 997  * @param len
 998  *   The amount of data to remove (in bytes).
 999  * @return
1000  *   A pointer to the new start of the data.
1001  */
1002 static inline char *rte_pktmbuf_adj(struct rte_mbuf *m, uint16_t len)
1003 {
1004         __rte_mbuf_sanity_check(m, RTE_MBUF_PKT, 1);
1005
1006         if (unlikely(len > m->pkt.data_len))
1007                 return NULL;
1008
1009         m->pkt.data_len = (uint16_t)(m->pkt.data_len - len);
1010         m->pkt.data = ((char*) m->pkt.data + len);
1011         m->pkt.pkt_len  = (m->pkt.pkt_len - len);
1012         return (char*) m->pkt.data;
1013 }
1014
1015 /**
1016  * Remove len bytes of data at the end of the mbuf.
1017  *
1018  * If the length is greater than the length of the last segment, the
1019  * function will fail and return -1 without modifying the mbuf.
1020  *
1021  * @param m
1022  *   The packet mbuf.
1023  * @param len
1024  *   The amount of data to remove (in bytes).
1025  * @return
1026  *   - 0: On success.
1027  *   - -1: On error.
1028  */
1029 static inline int rte_pktmbuf_trim(struct rte_mbuf *m, uint16_t len)
1030 {
1031         struct rte_mbuf *m_last;
1032
1033         __rte_mbuf_sanity_check(m, RTE_MBUF_PKT, 1);
1034
1035         m_last = rte_pktmbuf_lastseg(m);
1036         if (unlikely(len > m_last->pkt.data_len))
1037                 return -1;
1038
1039         m_last->pkt.data_len = (uint16_t)(m_last->pkt.data_len - len);
1040         m->pkt.pkt_len  = (m->pkt.pkt_len - len);
1041         return 0;
1042 }
1043
1044 /**
1045  * Test if mbuf data is contiguous.
1046  *
1047  * @param m
1048  *   The packet mbuf.
1049  * @return
1050  *   - 1, if all data is contiguous (one segment).
1051  *   - 0, if there is several segments.
1052  */
1053 static inline int rte_pktmbuf_is_contiguous(const struct rte_mbuf *m)
1054 {
1055         __rte_mbuf_sanity_check(m, RTE_MBUF_PKT, 1);
1056         return !!(m->pkt.nb_segs == 1);
1057 }
1058
1059 /**
1060  * Dump an mbuf structure to the console.
1061  *
1062  * Dump all fields for the given packet mbuf and all its associated
1063  * segments (in the case of a chained buffer).
1064  *
1065  * @param f
1066  *   A pointer to a file for output
1067  * @param m
1068  *   The packet mbuf.
1069  * @param dump_len
1070  *   If dump_len != 0, also dump the "dump_len" first data bytes of
1071  *   the packet.
1072  */
1073 void rte_pktmbuf_dump(FILE *f, const struct rte_mbuf *m, unsigned dump_len);
1074
1075 #ifdef __cplusplus
1076 }
1077 #endif
1078
1079 #endif /* _RTE_MBUF_H_ */