lib/librte_mbuf/rte_mbuf.h

   1 /*-
   2  *   BSD LICENSE
   3  *
   4  *   Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
   5  *   Copyright 2014 6WIND S.A.
   6  *   All rights reserved.
   7  *
   8  *   Redistribution and use in source and binary forms, with or without
   9  *   modification, are permitted provided that the following conditions
  10  *   are met:
  11  *
  12  *     * Redistributions of source code must retain the above copyright
  13  *       notice, this list of conditions and the following disclaimer.
  14  *     * Redistributions in binary form must reproduce the above copyright
  15  *       notice, this list of conditions and the following disclaimer in
  16  *       the documentation and/or other materials provided with the
  17  *       distribution.
  18  *     * Neither the name of Intel Corporation nor the names of its
  19  *       contributors may be used to endorse or promote products derived
  20  *       from this software without specific prior written permission.
  21  *
  22  *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  23  *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  24  *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  25  *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  26  *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  27  *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  28  *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  29  *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  30  *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  31  *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  32  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  33  */
  34
  35 #ifndef _RTE_MBUF_H_
  36 #define _RTE_MBUF_H_
  37
  38 /**
  39  * @file
  40  * RTE Mbuf
  41  *
  42  * The mbuf library provides the ability to create and destroy buffers
  43  * that may be used by the RTE application to store message
  44  * buffers. The message buffers are stored in a mempool, using the
  45  * RTE mempool library.
  46  *
  47  * This library provide an API to allocate/free packet mbufs, which are
  48  * used to carry network packets.
  49  *
  50  * To understand the concepts of packet buffers or mbufs, you
  51  * should read "TCP/IP Illustrated, Volume 2: The Implementation,
  52  * Addison-Wesley, 1995, ISBN 0-201-63354-X from Richard Stevens"
  53  * http://www.kohala.com/start/tcpipiv2.html
  54  */
  55
  56 #include <stdint.h>
  57 #include <rte_common.h>
  58 #include <rte_mempool.h>
  59 #include <rte_memory.h>
  60 #include <rte_atomic.h>
  61 #include <rte_prefetch.h>
  62 #include <rte_branch_prediction.h>
  63
  64 #ifdef __cplusplus
  65 extern "C" {
  66 #endif
  67
  68 /*
  69  * Packet Offload Features Flags. It also carry packet type information.
  70  * Critical resources. Both rx/tx shared these bits. Be cautious on any change
  71  *
  72  * - RX flags start at bit position zero, and get added to the left of previous
  73  *   flags.
  74  * - The most-significant 3 bits are reserved for generic mbuf flags
  75  * - TX flags therefore start at bit position 60 (i.e. 63-3), and new flags get
  76  *   added to the right of the previously defined flags i.e. they should count
  77  *   downwards, not upwards.
  78  *
  79  * Keep these flags synchronized with rte_get_rx_ol_flag_name() and
  80  * rte_get_tx_ol_flag_name().
  81  */
  82
  83 /**
  84  * RX packet is a 802.1q VLAN packet. This flag was set by PMDs when
  85  * the packet is recognized as a VLAN, but the behavior between PMDs
  86  * was not the same. This flag is kept for some time to avoid breaking
  87  * applications and should be replaced by PKT_RX_VLAN_STRIPPED.
  88  */
  89 #define PKT_RX_VLAN_PKT      (1ULL << 0)
  90
  91 #define PKT_RX_RSS_HASH      (1ULL << 1)  /**< RX packet with RSS hash result. */
  92 #define PKT_RX_FDIR          (1ULL << 2)  /**< RX packet with FDIR match indicate. */
  93 #define PKT_RX_L4_CKSUM_BAD  (1ULL << 3)  /**< L4 cksum of RX pkt. is not OK. */
  94 #define PKT_RX_IP_CKSUM_BAD  (1ULL << 4)  /**< IP cksum of RX pkt. is not OK. */
  95 #define PKT_RX_EIP_CKSUM_BAD (1ULL << 5)  /**< External IP header checksum error. */
  96
  97 /**
  98  * A vlan has been stripped by the hardware and its tci is saved in
  99  * mbuf->vlan_tci. This can only happen if vlan stripping is enabled
 100  * in the RX configuration of the PMD.
 101  */
 102 #define PKT_RX_VLAN_STRIPPED (1ULL << 6)
 103
 104 /* hole, some bits can be reused here  */
 105
 106 #define PKT_RX_IEEE1588_PTP  (1ULL << 9)  /**< RX IEEE1588 L2 Ethernet PT Packet. */
 107 #define PKT_RX_IEEE1588_TMST (1ULL << 10) /**< RX IEEE1588 L2/L4 timestamped packet.*/
 108 #define PKT_RX_FDIR_ID       (1ULL << 13) /**< FD id reported if FDIR match. */
 109 #define PKT_RX_FDIR_FLX      (1ULL << 14) /**< Flexible bytes reported if FDIR match. */
 110
 111 /**
 112  * The 2 vlans have been stripped by the hardware and their tci are
 113  * saved in mbuf->vlan_tci (inner) and mbuf->vlan_tci_outer (outer).
 114  * This can only happen if vlan stripping is enabled in the RX
 115  * configuration of the PMD. If this flag is set, PKT_RX_VLAN_STRIPPED
 116  * must also be set.
 117  */
 118 #define PKT_RX_QINQ_STRIPPED (1ULL << 15)
 119
 120 /**
 121  * Deprecated.
 122  * RX packet with double VLAN stripped.
 123  * This flag is replaced by PKT_RX_QINQ_STRIPPED.
 124  */
 125 #define PKT_RX_QINQ_PKT      PKT_RX_QINQ_STRIPPED
 126
 127 /* add new RX flags here */
 128
 129 /* add new TX flags here */
 130
 131 /**
 132  * Second VLAN insertion (QinQ) flag.
 133  */
 134 #define PKT_TX_QINQ_PKT    (1ULL << 49)   /**< TX packet with double VLAN inserted. */
 135
 136 /**
 137  * TCP segmentation offload. To enable this offload feature for a
 138  * packet to be transmitted on hardware supporting TSO:
 139  *  - set the PKT_TX_TCP_SEG flag in mbuf->ol_flags (this flag implies
 140  *    PKT_TX_TCP_CKSUM)
 141  *  - set the flag PKT_TX_IPV4 or PKT_TX_IPV6
 142  *  - if it's IPv4, set the PKT_TX_IP_CKSUM flag and write the IP checksum
 143  *    to 0 in the packet
 144  *  - fill the mbuf offload information: l2_len, l3_len, l4_len, tso_segsz
 145  *  - calculate the pseudo header checksum without taking ip_len in account,
 146  *    and set it in the TCP header. Refer to rte_ipv4_phdr_cksum() and
 147  *    rte_ipv6_phdr_cksum() that can be used as helpers.
 148  */
 149 #define PKT_TX_TCP_SEG       (1ULL << 50)
 150
 151 #define PKT_TX_IEEE1588_TMST (1ULL << 51) /**< TX IEEE1588 packet to timestamp. */
 152
 153 /**
 154  * Bits 52+53 used for L4 packet type with checksum enabled: 00: Reserved,
 155  * 01: TCP checksum, 10: SCTP checksum, 11: UDP checksum. To use hardware
 156  * L4 checksum offload, the user needs to:
 157  *  - fill l2_len and l3_len in mbuf
 158  *  - set the flags PKT_TX_TCP_CKSUM, PKT_TX_SCTP_CKSUM or PKT_TX_UDP_CKSUM
 159  *  - set the flag PKT_TX_IPV4 or PKT_TX_IPV6
 160  *  - calculate the pseudo header checksum and set it in the L4 header (only
 161  *    for TCP or UDP). See rte_ipv4_phdr_cksum() and rte_ipv6_phdr_cksum().
 162  *    For SCTP, set the crc field to 0.
 163  */
 164 #define PKT_TX_L4_NO_CKSUM   (0ULL << 52) /**< Disable L4 cksum of TX pkt. */
 165 #define PKT_TX_TCP_CKSUM     (1ULL << 52) /**< TCP cksum of TX pkt. computed by NIC. */
 166 #define PKT_TX_SCTP_CKSUM    (2ULL << 52) /**< SCTP cksum of TX pkt. computed by NIC. */
 167 #define PKT_TX_UDP_CKSUM     (3ULL << 52) /**< UDP cksum of TX pkt. computed by NIC. */
 168 #define PKT_TX_L4_MASK       (3ULL << 52) /**< Mask for L4 cksum offload request. */
 169
 170 /**
 171  * Offload the IP checksum in the hardware. The flag PKT_TX_IPV4 should
 172  * also be set by the application, although a PMD will only check
 173  * PKT_TX_IP_CKSUM.
 174  *  - set the IP checksum field in the packet to 0
 175  *  - fill the mbuf offload information: l2_len, l3_len
 176  */
 177 #define PKT_TX_IP_CKSUM      (1ULL << 54)
 178
 179 /**
 180  * Packet is IPv4. This flag must be set when using any offload feature
 181  * (TSO, L3 or L4 checksum) to tell the NIC that the packet is an IPv4
 182  * packet. If the packet is a tunneled packet, this flag is related to
 183  * the inner headers.
 184  */
 185 #define PKT_TX_IPV4          (1ULL << 55)
 186
 187 /**
 188  * Packet is IPv6. This flag must be set when using an offload feature
 189  * (TSO or L4 checksum) to tell the NIC that the packet is an IPv6
 190  * packet. If the packet is a tunneled packet, this flag is related to
 191  * the inner headers.
 192  */
 193 #define PKT_TX_IPV6          (1ULL << 56)
 194
 195 #define PKT_TX_VLAN_PKT      (1ULL << 57) /**< TX packet is a 802.1q VLAN packet. */
 196
 197 /**
 198  * Offload the IP checksum of an external header in the hardware. The
 199  * flag PKT_TX_OUTER_IPV4 should also be set by the application, alto ugh
 200  * a PMD will only check PKT_TX_IP_CKSUM.  The IP checksum field in the
 201  * packet must be set to 0.
 202  *  - set the outer IP checksum field in the packet to 0
 203  *  - fill the mbuf offload information: outer_l2_len, outer_l3_len
 204  */
 205 #define PKT_TX_OUTER_IP_CKSUM   (1ULL << 58)
 206
 207 /**
 208  * Packet outer header is IPv4. This flag must be set when using any
 209  * outer offload feature (L3 or L4 checksum) to tell the NIC that the
 210  * outer header of the tunneled packet is an IPv4 packet.
 211  */
 212 #define PKT_TX_OUTER_IPV4   (1ULL << 59)
 213
 214 /**
 215  * Packet outer header is IPv6. This flag must be set when using any
 216  * outer offload feature (L4 checksum) to tell the NIC that the outer
 217  * header of the tunneled packet is an IPv6 packet.
 218  */
 219 #define PKT_TX_OUTER_IPV6    (1ULL << 60)
 220
 221 #define __RESERVED           (1ULL << 61) /**< reserved for future mbuf use */
 222
 223 #define IND_ATTACHED_MBUF    (1ULL << 62) /**< Indirect attached mbuf */
 224
 225 /* Use final bit of flags to indicate a control mbuf */
 226 #define CTRL_MBUF_FLAG       (1ULL << 63) /**< Mbuf contains control data */
 227
 228 /*
 229  * 32 bits are divided into several fields to mark packet types. Note that
 230  * each field is indexical.
 231  * - Bit 3:0 is for L2 types.
 232  * - Bit 7:4 is for L3 or outer L3 (for tunneling case) types.
 233  * - Bit 11:8 is for L4 or outer L4 (for tunneling case) types.
 234  * - Bit 15:12 is for tunnel types.
 235  * - Bit 19:16 is for inner L2 types.
 236  * - Bit 23:20 is for inner L3 types.
 237  * - Bit 27:24 is for inner L4 types.
 238  * - Bit 31:28 is reserved.
 239  *
 240  * To be compatible with Vector PMD, RTE_PTYPE_L3_IPV4, RTE_PTYPE_L3_IPV4_EXT,
 241  * RTE_PTYPE_L3_IPV6, RTE_PTYPE_L3_IPV6_EXT, RTE_PTYPE_L4_TCP, RTE_PTYPE_L4_UDP
 242  * and RTE_PTYPE_L4_SCTP should be kept as below in a contiguous 7 bits.
 243  *
 244  * Note that L3 types values are selected for checking IPV4/IPV6 header from
 245  * performance point of view. Reading annotations of RTE_ETH_IS_IPV4_HDR and
 246  * RTE_ETH_IS_IPV6_HDR is needed for any future changes of L3 type values.
 247  *
 248  * Note that the packet types of the same packet recognized by different
 249  * hardware may be different, as different hardware may have different
 250  * capability of packet type recognition.
 251  *
 252  * examples:
 253  * <'ether type'=0x0800
 254  * | 'version'=4, 'protocol'=0x29
 255  * | 'version'=6, 'next header'=0x3A
 256  * | 'ICMPv6 header'>
 257  * will be recognized on i40e hardware as packet type combination of,
 258  * RTE_PTYPE_L2_ETHER |
 259  * RTE_PTYPE_L3_IPV4_EXT_UNKNOWN |
 260  * RTE_PTYPE_TUNNEL_IP |
 261  * RTE_PTYPE_INNER_L3_IPV6_EXT_UNKNOWN |
 262  * RTE_PTYPE_INNER_L4_ICMP.
 263  *
 264  * <'ether type'=0x86DD
 265  * | 'version'=6, 'next header'=0x2F
 266  * | 'GRE header'
 267  * | 'version'=6, 'next header'=0x11
 268  * | 'UDP header'>
 269  * will be recognized on i40e hardware as packet type combination of,
 270  * RTE_PTYPE_L2_ETHER |
 271  * RTE_PTYPE_L3_IPV6_EXT_UNKNOWN |
 272  * RTE_PTYPE_TUNNEL_GRENAT |
 273  * RTE_PTYPE_INNER_L3_IPV6_EXT_UNKNOWN |
 274  * RTE_PTYPE_INNER_L4_UDP.
 275  */
 276 #define RTE_PTYPE_UNKNOWN                   0x00000000
 277 /**
 278  * Ethernet packet type.
 279  * It is used for outer packet for tunneling cases.
 280  *
 281  * Packet format:
 282  * <'ether type'=[0x0800|0x86DD]>
 283  */
 284 #define RTE_PTYPE_L2_ETHER                  0x00000001
 285 /**
 286  * Ethernet packet type for time sync.
 287  *
 288  * Packet format:
 289  * <'ether type'=0x88F7>
 290  */
 291 #define RTE_PTYPE_L2_ETHER_TIMESYNC         0x00000002
 292 /**
 293  * ARP (Address Resolution Protocol) packet type.
 294  *
 295  * Packet format:
 296  * <'ether type'=0x0806>
 297  */
 298 #define RTE_PTYPE_L2_ETHER_ARP              0x00000003
 299 /**
 300  * LLDP (Link Layer Discovery Protocol) packet type.
 301  *
 302  * Packet format:
 303  * <'ether type'=0x88CC>
 304  */
 305 #define RTE_PTYPE_L2_ETHER_LLDP             0x00000004
 306 /**
 307  * NSH (Network Service Header) packet type.
 308  *
 309  * Packet format:
 310  * <'ether type'=0x894F>
 311  */
 312 #define RTE_PTYPE_L2_ETHER_NSH              0x00000005
 313 /**
 314  * Mask of layer 2 packet types.
 315  * It is used for outer packet for tunneling cases.
 316  */
 317 #define RTE_PTYPE_L2_MASK                   0x0000000f
 318 /**
 319  * IP (Internet Protocol) version 4 packet type.
 320  * It is used for outer packet for tunneling cases, and does not contain any
 321  * header option.
 322  *
 323  * Packet format:
 324  * <'ether type'=0x0800
 325  * | 'version'=4, 'ihl'=5>
 326  */
 327 #define RTE_PTYPE_L3_IPV4                   0x00000010
 328 /**
 329  * IP (Internet Protocol) version 4 packet type.
 330  * It is used for outer packet for tunneling cases, and contains header
 331  * options.
 332  *
 333  * Packet format:
 334  * <'ether type'=0x0800
 335  * | 'version'=4, 'ihl'=[6-15], 'options'>
 336  */
 337 #define RTE_PTYPE_L3_IPV4_EXT               0x00000030
 338 /**
 339  * IP (Internet Protocol) version 6 packet type.
 340  * It is used for outer packet for tunneling cases, and does not contain any
 341  * extension header.
 342  *
 343  * Packet format:
 344  * <'ether type'=0x86DD
 345  * | 'version'=6, 'next header'=0x3B>
 346  */
 347 #define RTE_PTYPE_L3_IPV6                   0x00000040
 348 /**
 349  * IP (Internet Protocol) version 4 packet type.
 350  * It is used for outer packet for tunneling cases, and may or maynot contain
 351  * header options.
 352  *
 353  * Packet format:
 354  * <'ether type'=0x0800
 355  * | 'version'=4, 'ihl'=[5-15], <'options'>>
 356  */
 357 #define RTE_PTYPE_L3_IPV4_EXT_UNKNOWN       0x00000090
 358 /**
 359  * IP (Internet Protocol) version 6 packet type.
 360  * It is used for outer packet for tunneling cases, and contains extension
 361  * headers.
 362  *
 363  * Packet format:
 364  * <'ether type'=0x86DD
 365  * | 'version'=6, 'next header'=[0x0|0x2B|0x2C|0x32|0x33|0x3C|0x87],
 366  *   'extension headers'>
 367  */
 368 #define RTE_PTYPE_L3_IPV6_EXT               0x000000c0
 369 /**
 370  * IP (Internet Protocol) version 6 packet type.
 371  * It is used for outer packet for tunneling cases, and may or maynot contain
 372  * extension headers.
 373  *
 374  * Packet format:
 375  * <'ether type'=0x86DD
 376  * | 'version'=6, 'next header'=[0x3B|0x0|0x2B|0x2C|0x32|0x33|0x3C|0x87],
 377  *   <'extension headers'>>
 378  */
 379 #define RTE_PTYPE_L3_IPV6_EXT_UNKNOWN       0x000000e0
 380 /**
 381  * Mask of layer 3 packet types.
 382  * It is used for outer packet for tunneling cases.
 383  */
 384 #define RTE_PTYPE_L3_MASK                   0x000000f0
 385 /**
 386  * TCP (Transmission Control Protocol) packet type.
 387  * It is used for outer packet for tunneling cases.
 388  *
 389  * Packet format:
 390  * <'ether type'=0x0800
 391  * | 'version'=4, 'protocol'=6, 'MF'=0>
 392  * or,
 393  * <'ether type'=0x86DD
 394  * | 'version'=6, 'next header'=6>
 395  */
 396 #define RTE_PTYPE_L4_TCP                    0x00000100
 397 /**
 398  * UDP (User Datagram Protocol) packet type.
 399  * It is used for outer packet for tunneling cases.
 400  *
 401  * Packet format:
 402  * <'ether type'=0x0800
 403  * | 'version'=4, 'protocol'=17, 'MF'=0>
 404  * or,
 405  * <'ether type'=0x86DD
 406  * | 'version'=6, 'next header'=17>
 407  */
 408 #define RTE_PTYPE_L4_UDP                    0x00000200
 409 /**
 410  * Fragmented IP (Internet Protocol) packet type.
 411  * It is used for outer packet for tunneling cases.
 412  *
 413  * It refers to those packets of any IP types, which can be recognized as
 414  * fragmented. A fragmented packet cannot be recognized as any other L4 types
 415  * (RTE_PTYPE_L4_TCP, RTE_PTYPE_L4_UDP, RTE_PTYPE_L4_SCTP, RTE_PTYPE_L4_ICMP,
 416  * RTE_PTYPE_L4_NONFRAG).
 417  *
 418  * Packet format:
 419  * <'ether type'=0x0800
 420  * | 'version'=4, 'MF'=1>
 421  * or,
 422  * <'ether type'=0x86DD
 423  * | 'version'=6, 'next header'=44>
 424  */
 425 #define RTE_PTYPE_L4_FRAG                   0x00000300
 426 /**
 427  * SCTP (Stream Control Transmission Protocol) packet type.
 428  * It is used for outer packet for tunneling cases.
 429  *
 430  * Packet format:
 431  * <'ether type'=0x0800
 432  * | 'version'=4, 'protocol'=132, 'MF'=0>
 433  * or,
 434  * <'ether type'=0x86DD
 435  * | 'version'=6, 'next header'=132>
 436  */
 437 #define RTE_PTYPE_L4_SCTP                   0x00000400
 438 /**
 439  * ICMP (Internet Control Message Protocol) packet type.
 440  * It is used for outer packet for tunneling cases.
 441  *
 442  * Packet format:
 443  * <'ether type'=0x0800
 444  * | 'version'=4, 'protocol'=1, 'MF'=0>
 445  * or,
 446  * <'ether type'=0x86DD
 447  * | 'version'=6, 'next header'=1>
 448  */
 449 #define RTE_PTYPE_L4_ICMP                   0x00000500
 450 /**
 451  * Non-fragmented IP (Internet Protocol) packet type.
 452  * It is used for outer packet for tunneling cases.
 453  *
 454  * It refers to those packets of any IP types, while cannot be recognized as
 455  * any of above L4 types (RTE_PTYPE_L4_TCP, RTE_PTYPE_L4_UDP,
 456  * RTE_PTYPE_L4_FRAG, RTE_PTYPE_L4_SCTP, RTE_PTYPE_L4_ICMP).
 457  *
 458  * Packet format:
 459  * <'ether type'=0x0800
 460  * | 'version'=4, 'protocol'!=[6|17|132|1], 'MF'=0>
 461  * or,
 462  * <'ether type'=0x86DD
 463  * | 'version'=6, 'next header'!=[6|17|44|132|1]>
 464  */
 465 #define RTE_PTYPE_L4_NONFRAG                0x00000600
 466 /**
 467  * Mask of layer 4 packet types.
 468  * It is used for outer packet for tunneling cases.
 469  */
 470 #define RTE_PTYPE_L4_MASK                   0x00000f00
 471 /**
 472  * IP (Internet Protocol) in IP (Internet Protocol) tunneling packet type.
 473  *
 474  * Packet format:
 475  * <'ether type'=0x0800
 476  * | 'version'=4, 'protocol'=[4|41]>
 477  * or,
 478  * <'ether type'=0x86DD
 479  * | 'version'=6, 'next header'=[4|41]>
 480  */
 481 #define RTE_PTYPE_TUNNEL_IP                 0x00001000
 482 /**
 483  * GRE (Generic Routing Encapsulation) tunneling packet type.
 484  *
 485  * Packet format:
 486  * <'ether type'=0x0800
 487  * | 'version'=4, 'protocol'=47>
 488  * or,
 489  * <'ether type'=0x86DD
 490  * | 'version'=6, 'next header'=47>
 491  */
 492 #define RTE_PTYPE_TUNNEL_GRE                0x00002000
 493 /**
 494  * VXLAN (Virtual eXtensible Local Area Network) tunneling packet type.
 495  *
 496  * Packet format:
 497  * <'ether type'=0x0800
 498  * | 'version'=4, 'protocol'=17
 499  * | 'destination port'=4798>
 500  * or,
 501  * <'ether type'=0x86DD
 502  * | 'version'=6, 'next header'=17
 503  * | 'destination port'=4798>
 504  */
 505 #define RTE_PTYPE_TUNNEL_VXLAN              0x00003000
 506 /**
 507  * NVGRE (Network Virtualization using Generic Routing Encapsulation) tunneling
 508  * packet type.
 509  *
 510  * Packet format:
 511  * <'ether type'=0x0800
 512  * | 'version'=4, 'protocol'=47
 513  * | 'protocol type'=0x6558>
 514  * or,
 515  * <'ether type'=0x86DD
 516  * | 'version'=6, 'next header'=47
 517  * | 'protocol type'=0x6558'>
 518  */
 519 #define RTE_PTYPE_TUNNEL_NVGRE              0x00004000
 520 /**
 521  * GENEVE (Generic Network Virtualization Encapsulation) tunneling packet type.
 522  *
 523  * Packet format:
 524  * <'ether type'=0x0800
 525  * | 'version'=4, 'protocol'=17
 526  * | 'destination port'=6081>
 527  * or,
 528  * <'ether type'=0x86DD
 529  * | 'version'=6, 'next header'=17
 530  * | 'destination port'=6081>
 531  */
 532 #define RTE_PTYPE_TUNNEL_GENEVE             0x00005000
 533 /**
 534  * Tunneling packet type of Teredo, VXLAN (Virtual eXtensible Local Area
 535  * Network) or GRE (Generic Routing Encapsulation) could be recognized as this
 536  * packet type, if they can not be recognized independently as of hardware
 537  * capability.
 538  */
 539 #define RTE_PTYPE_TUNNEL_GRENAT             0x00006000
 540 /**
 541  * Mask of tunneling packet types.
 542  */
 543 #define RTE_PTYPE_TUNNEL_MASK               0x0000f000
 544 /**
 545  * Ethernet packet type.
 546  * It is used for inner packet type only.
 547  *
 548  * Packet format (inner only):
 549  * <'ether type'=[0x800|0x86DD]>
 550  */
 551 #define RTE_PTYPE_INNER_L2_ETHER            0x00010000
 552 /**
 553  * Ethernet packet type with VLAN (Virtual Local Area Network) tag.
 554  *
 555  * Packet format (inner only):
 556  * <'ether type'=[0x800|0x86DD], vlan=[1-4095]>
 557  */
 558 #define RTE_PTYPE_INNER_L2_ETHER_VLAN       0x00020000
 559 /**
 560  * Mask of inner layer 2 packet types.
 561  */
 562 #define RTE_PTYPE_INNER_L2_MASK             0x000f0000
 563 /**
 564  * IP (Internet Protocol) version 4 packet type.
 565  * It is used for inner packet only, and does not contain any header option.
 566  *
 567  * Packet format (inner only):
 568  * <'ether type'=0x0800
 569  * | 'version'=4, 'ihl'=5>
 570  */
 571 #define RTE_PTYPE_INNER_L3_IPV4             0x00100000
 572 /**
 573  * IP (Internet Protocol) version 4 packet type.
 574  * It is used for inner packet only, and contains header options.
 575  *
 576  * Packet format (inner only):
 577  * <'ether type'=0x0800
 578  * | 'version'=4, 'ihl'=[6-15], 'options'>
 579  */
 580 #define RTE_PTYPE_INNER_L3_IPV4_EXT         0x00200000
 581 /**
 582  * IP (Internet Protocol) version 6 packet type.
 583  * It is used for inner packet only, and does not contain any extension header.
 584  *
 585  * Packet format (inner only):
 586  * <'ether type'=0x86DD
 587  * | 'version'=6, 'next header'=0x3B>
 588  */
 589 #define RTE_PTYPE_INNER_L3_IPV6             0x00300000
 590 /**
 591  * IP (Internet Protocol) version 4 packet type.
 592  * It is used for inner packet only, and may or maynot contain header options.
 593  *
 594  * Packet format (inner only):
 595  * <'ether type'=0x0800
 596  * | 'version'=4, 'ihl'=[5-15], <'options'>>
 597  */
 598 #define RTE_PTYPE_INNER_L3_IPV4_EXT_UNKNOWN 0x00400000
 599 /**
 600  * IP (Internet Protocol) version 6 packet type.
 601  * It is used for inner packet only, and contains extension headers.
 602  *
 603  * Packet format (inner only):
 604  * <'ether type'=0x86DD
 605  * | 'version'=6, 'next header'=[0x0|0x2B|0x2C|0x32|0x33|0x3C|0x87],
 606  *   'extension headers'>
 607  */
 608 #define RTE_PTYPE_INNER_L3_IPV6_EXT         0x00500000
 609 /**
 610  * IP (Internet Protocol) version 6 packet type.
 611  * It is used for inner packet only, and may or maynot contain extension
 612  * headers.
 613  *
 614  * Packet format (inner only):
 615  * <'ether type'=0x86DD
 616  * | 'version'=6, 'next header'=[0x3B|0x0|0x2B|0x2C|0x32|0x33|0x3C|0x87],
 617  *   <'extension headers'>>
 618  */
 619 #define RTE_PTYPE_INNER_L3_IPV6_EXT_UNKNOWN 0x00600000
 620 /**
 621  * Mask of inner layer 3 packet types.
 622  */
 623 #define RTE_PTYPE_INNER_L3_MASK             0x00f00000
 624 /**
 625  * TCP (Transmission Control Protocol) packet type.
 626  * It is used for inner packet only.
 627  *
 628  * Packet format (inner only):
 629  * <'ether type'=0x0800
 630  * | 'version'=4, 'protocol'=6, 'MF'=0>
 631  * or,
 632  * <'ether type'=0x86DD
 633  * | 'version'=6, 'next header'=6>
 634  */
 635 #define RTE_PTYPE_INNER_L4_TCP              0x01000000
 636 /**
 637  * UDP (User Datagram Protocol) packet type.
 638  * It is used for inner packet only.
 639  *
 640  * Packet format (inner only):
 641  * <'ether type'=0x0800
 642  * | 'version'=4, 'protocol'=17, 'MF'=0>
 643  * or,
 644  * <'ether type'=0x86DD
 645  * | 'version'=6, 'next header'=17>
 646  */
 647 #define RTE_PTYPE_INNER_L4_UDP              0x02000000
 648 /**
 649  * Fragmented IP (Internet Protocol) packet type.
 650  * It is used for inner packet only, and may or maynot have layer 4 packet.
 651  *
 652  * Packet format (inner only):
 653  * <'ether type'=0x0800
 654  * | 'version'=4, 'MF'=1>
 655  * or,
 656  * <'ether type'=0x86DD
 657  * | 'version'=6, 'next header'=44>
 658  */
 659 #define RTE_PTYPE_INNER_L4_FRAG             0x03000000
 660 /**
 661  * SCTP (Stream Control Transmission Protocol) packet type.
 662  * It is used for inner packet only.
 663  *
 664  * Packet format (inner only):
 665  * <'ether type'=0x0800
 666  * | 'version'=4, 'protocol'=132, 'MF'=0>
 667  * or,
 668  * <'ether type'=0x86DD
 669  * | 'version'=6, 'next header'=132>
 670  */
 671 #define RTE_PTYPE_INNER_L4_SCTP             0x04000000
 672 /**
 673  * ICMP (Internet Control Message Protocol) packet type.
 674  * It is used for inner packet only.
 675  *
 676  * Packet format (inner only):
 677  * <'ether type'=0x0800
 678  * | 'version'=4, 'protocol'=1, 'MF'=0>
 679  * or,
 680  * <'ether type'=0x86DD
 681  * | 'version'=6, 'next header'=1>
 682  */
 683 #define RTE_PTYPE_INNER_L4_ICMP             0x05000000
 684 /**
 685  * Non-fragmented IP (Internet Protocol) packet type.
 686  * It is used for inner packet only, and may or maynot have other unknown layer
 687  * 4 packet types.
 688  *
 689  * Packet format (inner only):
 690  * <'ether type'=0x0800
 691  * | 'version'=4, 'protocol'!=[6|17|132|1], 'MF'=0>
 692  * or,
 693  * <'ether type'=0x86DD
 694  * | 'version'=6, 'next header'!=[6|17|44|132|1]>
 695  */
 696 #define RTE_PTYPE_INNER_L4_NONFRAG          0x06000000
 697 /**
 698  * Mask of inner layer 4 packet types.
 699  */
 700 #define RTE_PTYPE_INNER_L4_MASK             0x0f000000
 701
 702 /**
 703  * Check if the (outer) L3 header is IPv4. To avoid comparing IPv4 types one by
 704  * one, bit 4 is selected to be used for IPv4 only. Then checking bit 4 can
 705  * determine if it is an IPV4 packet.
 706  */
 707 #define  RTE_ETH_IS_IPV4_HDR(ptype) ((ptype) & RTE_PTYPE_L3_IPV4)
 708
 709 /**
 710  * Check if the (outer) L3 header is IPv4. To avoid comparing IPv4 types one by
 711  * one, bit 6 is selected to be used for IPv4 only. Then checking bit 6 can
 712  * determine if it is an IPV4 packet.
 713  */
 714 #define  RTE_ETH_IS_IPV6_HDR(ptype) ((ptype) & RTE_PTYPE_L3_IPV6)
 715
 716 /* Check if it is a tunneling packet */
 717 #define RTE_ETH_IS_TUNNEL_PKT(ptype) ((ptype) & (RTE_PTYPE_TUNNEL_MASK | \
 718                                                  RTE_PTYPE_INNER_L2_MASK | \
 719                                                  RTE_PTYPE_INNER_L3_MASK | \
 720                                                  RTE_PTYPE_INNER_L4_MASK))
 721
 722 /** Alignment constraint of mbuf private area. */
 723 #define RTE_MBUF_PRIV_ALIGN 8
 724
 725 /**
 726  * Get the name of a RX offload flag
 727  *
 728  * @param mask
 729  *   The mask describing the flag.
 730  * @return
 731  *   The name of this flag, or NULL if it's not a valid RX flag.
 732  */
 733 const char *rte_get_rx_ol_flag_name(uint64_t mask);
 734
 735 /**
 736  * Get the name of a TX offload flag
 737  *
 738  * @param mask
 739  *   The mask describing the flag. Usually only one bit must be set.
 740  *   Several bits can be given if they belong to the same mask.
 741  *   Ex: PKT_TX_L4_MASK.
 742  * @return
 743  *   The name of this flag, or NULL if it's not a valid TX flag.
 744  */
 745 const char *rte_get_tx_ol_flag_name(uint64_t mask);
 746
 747 /**
 748  * Some NICs need at least 2KB buffer to RX standard Ethernet frame without
 749  * splitting it into multiple segments.
 750  * So, for mbufs that planned to be involved into RX/TX, the recommended
 751  * minimal buffer length is 2KB + RTE_PKTMBUF_HEADROOM.
 752  */
 753 #define RTE_MBUF_DEFAULT_DATAROOM       2048
 754 #define RTE_MBUF_DEFAULT_BUF_SIZE       \
 755         (RTE_MBUF_DEFAULT_DATAROOM + RTE_PKTMBUF_HEADROOM)
 756
 757 /* define a set of marker types that can be used to refer to set points in the
 758  * mbuf */
 759 typedef void    *MARKER[0];   /**< generic marker for a point in a structure */
 760 typedef uint8_t  MARKER8[0];  /**< generic marker with 1B alignment */
 761 typedef uint64_t MARKER64[0]; /**< marker that allows us to overwrite 8 bytes
 762                                * with a single assignment */
 763
 764 /**
 765  * The generic rte_mbuf, containing a packet mbuf.
 766  */
 767 struct rte_mbuf {
 768         MARKER cacheline0;
 769
 770         void *buf_addr;           /**< Virtual address of segment buffer. */
 771         phys_addr_t buf_physaddr; /**< Physical address of segment buffer. */
 772
 773         uint16_t buf_len;         /**< Length of segment buffer. */
 774
 775         /* next 6 bytes are initialised on RX descriptor rearm */
 776         MARKER8 rearm_data;
 777         uint16_t data_off;
 778
 779         /**
 780          * 16-bit Reference counter.
 781          * It should only be accessed using the following functions:
 782          * rte_mbuf_refcnt_update(), rte_mbuf_refcnt_read(), and
 783          * rte_mbuf_refcnt_set(). The functionality of these functions (atomic,
 784          * or non-atomic) is controlled by the CONFIG_RTE_MBUF_REFCNT_ATOMIC
 785          * config option.
 786          */
 787         union {
 788                 rte_atomic16_t refcnt_atomic; /**< Atomically accessed refcnt */
 789                 uint16_t refcnt;              /**< Non-atomically accessed refcnt */
 790         };
 791         uint8_t nb_segs;          /**< Number of segments. */
 792         uint8_t port;             /**< Input port. */
 793
 794         uint64_t ol_flags;        /**< Offload features. */
 795
 796         /* remaining bytes are set on RX when pulling packet from descriptor */
 797         MARKER rx_descriptor_fields1;
 798
 799         /*
 800          * The packet type, which is the combination of outer/inner L2, L3, L4
 801          * and tunnel types. The packet_type is about data really present in the
 802          * mbuf. Example: if vlan stripping is enabled, a received vlan packet
 803          * would have RTE_PTYPE_L2_ETHER and not RTE_PTYPE_L2_VLAN because the
 804          * vlan is stripped from the data.
 805          */
 806         union {
 807                 uint32_t packet_type; /**< L2/L3/L4 and tunnel information. */
 808                 struct {
 809                         uint32_t l2_type:4; /**< (Outer) L2 type. */
 810                         uint32_t l3_type:4; /**< (Outer) L3 type. */
 811                         uint32_t l4_type:4; /**< (Outer) L4 type. */
 812                         uint32_t tun_type:4; /**< Tunnel type. */
 813                         uint32_t inner_l2_type:4; /**< Inner L2 type. */
 814                         uint32_t inner_l3_type:4; /**< Inner L3 type. */
 815                         uint32_t inner_l4_type:4; /**< Inner L4 type. */
 816                 };
 817         };
 818
 819         uint32_t pkt_len;         /**< Total pkt len: sum of all segments. */
 820         uint16_t data_len;        /**< Amount of data in segment buffer. */
 821         /** VLAN TCI (CPU order), valid if PKT_RX_VLAN_STRIPPED is set. */
 822         uint16_t vlan_tci;
 823
 824         union {
 825                 uint32_t rss;     /**< RSS hash result if RSS enabled */
 826                 struct {
 827                         union {
 828                                 struct {
 829                                         uint16_t hash;
 830                                         uint16_t id;
 831                                 };
 832                                 uint32_t lo;
 833                                 /**< Second 4 flexible bytes */
 834                         };
 835                         uint32_t hi;
 836                         /**< First 4 flexible bytes or FD ID, dependent on
 837                              PKT_RX_FDIR_* flag in ol_flags. */
 838                 } fdir;           /**< Filter identifier if FDIR enabled */
 839                 struct {
 840                         uint32_t lo;
 841                         uint32_t hi;
 842                 } sched;          /**< Hierarchical scheduler */
 843                 uint32_t usr;     /**< User defined tags. See rte_distributor_process() */
 844         } hash;                   /**< hash information */
 845
 846         uint32_t seqn; /**< Sequence number. See also rte_reorder_insert() */
 847
 848         /** Outer VLAN TCI (CPU order), valid if PKT_RX_QINQ_STRIPPED is set. */
 849         uint16_t vlan_tci_outer;
 850
 851         /* second cache line - fields only used in slow path or on TX */
 852         MARKER cacheline1 __rte_cache_min_aligned;
 853
 854         union {
 855                 void *userdata;   /**< Can be used for external metadata */
 856                 uint64_t udata64; /**< Allow 8-byte userdata on 32-bit */
 857         };
 858
 859         struct rte_mempool *pool; /**< Pool from which mbuf was allocated. */
 860         struct rte_mbuf *next;    /**< Next segment of scattered packet. */
 861
 862         /* fields to support TX offloads */
 863         union {
 864                 uint64_t tx_offload;       /**< combined for easy fetch */
 865                 struct {
 866                         uint64_t l2_len:7; /**< L2 (MAC) Header Length. */
 867                         uint64_t l3_len:9; /**< L3 (IP) Header Length. */
 868                         uint64_t l4_len:8; /**< L4 (TCP/UDP) Header Length. */
 869                         uint64_t tso_segsz:16; /**< TCP TSO segment size */
 870
 871                         /* fields for TX offloading of tunnels */
 872                         uint64_t outer_l3_len:9; /**< Outer L3 (IP) Hdr Length. */
 873                         uint64_t outer_l2_len:7; /**< Outer L2 (MAC) Hdr Length. */
 874
 875                         /* uint64_t unused:8; */
 876                 };
 877         };
 878
 879         /** Size of the application private data. In case of an indirect
 880          * mbuf, it stores the direct mbuf private data size. */
 881         uint16_t priv_size;
 882
 883         /** Timesync flags for use with IEEE1588. */
 884         uint16_t timesync;
 885 } __rte_cache_aligned;
 886
 887 /**
 888  * Prefetch the first part of the mbuf
 889  *
 890  * The first 64 bytes of the mbuf corresponds to fields that are used early
 891  * in the receive path. If the cache line of the architecture is higher than
 892  * 64B, the second part will also be prefetched.
 893  *
 894  * @param m
 895  *   The pointer to the mbuf.
 896  */
 897 static inline void
 898 rte_mbuf_prefetch_part1(struct rte_mbuf *m)
 899 {
 900         rte_prefetch0(&m->cacheline0);
 901 }
 902
 903 /**
 904  * Prefetch the second part of the mbuf
 905  *
 906  * The next 64 bytes of the mbuf corresponds to fields that are used in the
 907  * transmit path. If the cache line of the architecture is higher than 64B,
 908  * this function does nothing as it is expected that the full mbuf is
 909  * already in cache.
 910  *
 911  * @param m
 912  *   The pointer to the mbuf.
 913  */
 914 static inline void
 915 rte_mbuf_prefetch_part2(struct rte_mbuf *m)
 916 {
 917 #if RTE_CACHE_LINE_SIZE == 64
 918         rte_prefetch0(&m->cacheline1);
 919 #else
 920         RTE_SET_USED(m);
 921 #endif
 922 }
 923
 924
 925 static inline uint16_t rte_pktmbuf_priv_size(struct rte_mempool *mp);
 926
 927 /**
 928  * Return the DMA address of the beginning of the mbuf data
 929  *
 930  * @param mb
 931  *   The pointer to the mbuf.
 932  * @return
 933  *   The physical address of the beginning of the mbuf data
 934  */
 935 static inline phys_addr_t
 936 rte_mbuf_data_dma_addr(const struct rte_mbuf *mb)
 937 {
 938         return mb->buf_physaddr + mb->data_off;
 939 }
 940
 941 /**
 942  * Return the default DMA address of the beginning of the mbuf data
 943  *
 944  * This function is used by drivers in their receive function, as it
 945  * returns the location where data should be written by the NIC, taking
 946  * the default headroom in account.
 947  *
 948  * @param mb
 949  *   The pointer to the mbuf.
 950  * @return
 951  *   The physical address of the beginning of the mbuf data
 952  */
 953 static inline phys_addr_t
 954 rte_mbuf_data_dma_addr_default(const struct rte_mbuf *mb)
 955 {
 956         return mb->buf_physaddr + RTE_PKTMBUF_HEADROOM;
 957 }
 958
 959 /**
 960  * Return the mbuf owning the data buffer address of an indirect mbuf.
 961  *
 962  * @param mi
 963  *   The pointer to the indirect mbuf.
 964  * @return
 965  *   The address of the direct mbuf corresponding to buffer_addr.
 966  */
 967 static inline struct rte_mbuf *
 968 rte_mbuf_from_indirect(struct rte_mbuf *mi)
 969 {
 970         return (struct rte_mbuf *)RTE_PTR_SUB(mi->buf_addr, sizeof(*mi) + mi->priv_size);
 971 }
 972
 973 /**
 974  * Return the buffer address embedded in the given mbuf.
 975  *
 976  * @param md
 977  *   The pointer to the mbuf.
 978  * @return
 979  *   The address of the data buffer owned by the mbuf.
 980  */
 981 static inline char *
 982 rte_mbuf_to_baddr(struct rte_mbuf *md)
 983 {
 984         char *buffer_addr;
 985         buffer_addr = (char *)md + sizeof(*md) + rte_pktmbuf_priv_size(md->pool);
 986         return buffer_addr;
 987 }
 988
 989 /**
 990  * Returns TRUE if given mbuf is indirect, or FALSE otherwise.
 991  */
 992 #define RTE_MBUF_INDIRECT(mb)   ((mb)->ol_flags & IND_ATTACHED_MBUF)
 993
 994 /**
 995  * Returns TRUE if given mbuf is direct, or FALSE otherwise.
 996  */
 997 #define RTE_MBUF_DIRECT(mb)     (!RTE_MBUF_INDIRECT(mb))
 998
 999 /**
1000  * Private data in case of pktmbuf pool.
1001  *
1002  * A structure that contains some pktmbuf_pool-specific data that are
1003  * appended after the mempool structure (in private data).
1004  */
1005 struct rte_pktmbuf_pool_private {
1006         uint16_t mbuf_data_room_size; /**< Size of data space in each mbuf. */
1007         uint16_t mbuf_priv_size;      /**< Size of private area in each mbuf. */
1008 };
1009
1010 #ifdef RTE_LIBRTE_MBUF_DEBUG
1011
1012 /**  check mbuf type in debug mode */
1013 #define __rte_mbuf_sanity_check(m, is_h) rte_mbuf_sanity_check(m, is_h)
1014
1015 #else /*  RTE_LIBRTE_MBUF_DEBUG */
1016
1017 /**  check mbuf type in debug mode */
1018 #define __rte_mbuf_sanity_check(m, is_h) do { } while (0)
1019
1020 #endif /*  RTE_LIBRTE_MBUF_DEBUG */
1021
1022 #ifdef RTE_MBUF_REFCNT_ATOMIC
1023
1024 /**
1025  * Reads the value of an mbuf's refcnt.
1026  * @param m
1027  *   Mbuf to read
1028  * @return
1029  *   Reference count number.
1030  */
1031 static inline uint16_t
1032 rte_mbuf_refcnt_read(const struct rte_mbuf *m)
1033 {
1034         return (uint16_t)(rte_atomic16_read(&m->refcnt_atomic));
1035 }
1036
1037 /**
1038  * Sets an mbuf's refcnt to a defined value.
1039  * @param m
1040  *   Mbuf to update
1041  * @param new_value
1042  *   Value set
1043  */
1044 static inline void
1045 rte_mbuf_refcnt_set(struct rte_mbuf *m, uint16_t new_value)
1046 {
1047         rte_atomic16_set(&m->refcnt_atomic, new_value);
1048 }
1049
1050 /**
1051  * Adds given value to an mbuf's refcnt and returns its new value.
1052  * @param m
1053  *   Mbuf to update
1054  * @param value
1055  *   Value to add/subtract
1056  * @return
1057  *   Updated value
1058  */
1059 static inline uint16_t
1060 rte_mbuf_refcnt_update(struct rte_mbuf *m, int16_t value)
1061 {
1062         /*
1063          * The atomic_add is an expensive operation, so we don't want to
1064          * call it in the case where we know we are the uniq holder of
1065          * this mbuf (i.e. ref_cnt == 1). Otherwise, an atomic
1066          * operation has to be used because concurrent accesses on the
1067          * reference counter can occur.
1068          */
1069         if (likely(rte_mbuf_refcnt_read(m) == 1)) {
1070                 rte_mbuf_refcnt_set(m, 1 + value);
1071                 return 1 + value;
1072         }
1073
1074         return (uint16_t)(rte_atomic16_add_return(&m->refcnt_atomic, value));
1075 }
1076
1077 #else /* ! RTE_MBUF_REFCNT_ATOMIC */
1078
1079 /**
1080  * Adds given value to an mbuf's refcnt and returns its new value.
1081  */
1082 static inline uint16_t
1083 rte_mbuf_refcnt_update(struct rte_mbuf *m, int16_t value)
1084 {
1085         m->refcnt = (uint16_t)(m->refcnt + value);
1086         return m->refcnt;
1087 }
1088
1089 /**
1090  * Reads the value of an mbuf's refcnt.
1091  */
1092 static inline uint16_t
1093 rte_mbuf_refcnt_read(const struct rte_mbuf *m)
1094 {
1095         return m->refcnt;
1096 }
1097
1098 /**
1099  * Sets an mbuf's refcnt to the defined value.
1100  */
1101 static inline void
1102 rte_mbuf_refcnt_set(struct rte_mbuf *m, uint16_t new_value)
1103 {
1104         m->refcnt = new_value;
1105 }
1106
1107 #endif /* RTE_MBUF_REFCNT_ATOMIC */
1108
1109 /** Mbuf prefetch */
1110 #define RTE_MBUF_PREFETCH_TO_FREE(m) do {       \
1111         if ((m) != NULL)                        \
1112                 rte_prefetch0(m);               \
1113 } while (0)
1114
1115
1116 /**
1117  * Sanity checks on an mbuf.
1118  *
1119  * Check the consistency of the given mbuf. The function will cause a
1120  * panic if corruption is detected.
1121  *
1122  * @param m
1123  *   The mbuf to be checked.
1124  * @param is_header
1125  *   True if the mbuf is a packet header, false if it is a sub-segment
1126  *   of a packet (in this case, some fields like nb_segs are not checked)
1127  */
1128 void
1129 rte_mbuf_sanity_check(const struct rte_mbuf *m, int is_header);
1130
1131 /**
1132  * Allocate an unitialized mbuf from mempool *mp*.
1133  *
1134  * This function can be used by PMDs (especially in RX functions) to
1135  * allocate an unitialized mbuf. The driver is responsible of
1136  * initializing all the required fields. See rte_pktmbuf_reset().
1137  * For standard needs, prefer rte_pktmbuf_alloc().
1138  *
1139  * @param mp
1140  *   The mempool from which mbuf is allocated.
1141  * @return
1142  *   - The pointer to the new mbuf on success.
1143  *   - NULL if allocation failed.
1144  */
1145 static inline struct rte_mbuf *rte_mbuf_raw_alloc(struct rte_mempool *mp)
1146 {
1147         struct rte_mbuf *m;
1148         void *mb = NULL;
1149
1150         if (rte_mempool_get(mp, &mb) < 0)
1151                 return NULL;
1152         m = (struct rte_mbuf *)mb;
1153         RTE_ASSERT(rte_mbuf_refcnt_read(m) == 0);
1154         rte_mbuf_refcnt_set(m, 1);
1155         __rte_mbuf_sanity_check(m, 0);
1156
1157         return m;
1158 }
1159
1160 /* compat with older versions */
1161 __rte_deprecated static inline struct rte_mbuf *
1162 __rte_mbuf_raw_alloc(struct rte_mempool *mp)
1163 {
1164         return rte_mbuf_raw_alloc(mp);
1165 }
1166
1167 /**
1168  * @internal Put mbuf back into its original mempool.
1169  * The use of that function is reserved for RTE internal needs.
1170  * Please use rte_pktmbuf_free().
1171  *
1172  * @param m
1173  *   The mbuf to be freed.
1174  */
1175 static inline void __attribute__((always_inline))
1176 __rte_mbuf_raw_free(struct rte_mbuf *m)
1177 {
1178         RTE_ASSERT(rte_mbuf_refcnt_read(m) == 0);
1179         rte_mempool_put(m->pool, m);
1180 }
1181
1182 /* Operations on ctrl mbuf */
1183
1184 /**
1185  * The control mbuf constructor.
1186  *
1187  * This function initializes some fields in an mbuf structure that are
1188  * not modified by the user once created (mbuf type, origin pool, buffer
1189  * start address, and so on). This function is given as a callback function
1190  * to rte_mempool_create() at pool creation time.
1191  *
1192  * @param mp
1193  *   The mempool from which the mbuf is allocated.
1194  * @param opaque_arg
1195  *   A pointer that can be used by the user to retrieve useful information
1196  *   for mbuf initialization. This pointer comes from the ``init_arg``
1197  *   parameter of rte_mempool_create().
1198  * @param m
1199  *   The mbuf to initialize.
1200  * @param i
1201  *   The index of the mbuf in the pool table.
1202  */
1203 void rte_ctrlmbuf_init(struct rte_mempool *mp, void *opaque_arg,
1204                 void *m, unsigned i);
1205
1206 /**
1207  * Allocate a new mbuf (type is ctrl) from mempool *mp*.
1208  *
1209  * This new mbuf is initialized with data pointing to the beginning of
1210  * buffer, and with a length of zero.
1211  *
1212  * @param mp
1213  *   The mempool from which the mbuf is allocated.
1214  * @return
1215  *   - The pointer to the new mbuf on success.
1216  *   - NULL if allocation failed.
1217  */
1218 #define rte_ctrlmbuf_alloc(mp) rte_pktmbuf_alloc(mp)
1219
1220 /**
1221  * Free a control mbuf back into its original mempool.
1222  *
1223  * @param m
1224  *   The control mbuf to be freed.
1225  */
1226 #define rte_ctrlmbuf_free(m) rte_pktmbuf_free(m)
1227
1228 /**
1229  * A macro that returns the pointer to the carried data.
1230  *
1231  * The value that can be read or assigned.
1232  *
1233  * @param m
1234  *   The control mbuf.
1235  */
1236 #define rte_ctrlmbuf_data(m) ((char *)((m)->buf_addr) + (m)->data_off)
1237
1238 /**
1239  * A macro that returns the length of the carried data.
1240  *
1241  * The value that can be read or assigned.
1242  *
1243  * @param m
1244  *   The control mbuf.
1245  */
1246 #define rte_ctrlmbuf_len(m) rte_pktmbuf_data_len(m)
1247
1248 /**
1249  * Tests if an mbuf is a control mbuf
1250  *
1251  * @param m
1252  *   The mbuf to be tested
1253  * @return
1254  *   - True (1) if the mbuf is a control mbuf
1255  *   - False(0) otherwise
1256  */
1257 static inline int
1258 rte_is_ctrlmbuf(struct rte_mbuf *m)
1259 {
1260         return !!(m->ol_flags & CTRL_MBUF_FLAG);
1261 }
1262
1263 /* Operations on pkt mbuf */
1264
1265 /**
1266  * The packet mbuf constructor.
1267  *
1268  * This function initializes some fields in the mbuf structure that are
1269  * not modified by the user once created (origin pool, buffer start
1270  * address, and so on). This function is given as a callback function to
1271  * rte_mempool_create() at pool creation time.
1272  *
1273  * @param mp
1274  *   The mempool from which mbufs originate.
1275  * @param opaque_arg
1276  *   A pointer that can be used by the user to retrieve useful information
1277  *   for mbuf initialization. This pointer comes from the ``init_arg``
1278  *   parameter of rte_mempool_create().
1279  * @param m
1280  *   The mbuf to initialize.
1281  * @param i
1282  *   The index of the mbuf in the pool table.
1283  */
1284 void rte_pktmbuf_init(struct rte_mempool *mp, void *opaque_arg,
1285                       void *m, unsigned i);
1286
1287
1288 /**
1289  * A  packet mbuf pool constructor.
1290  *
1291  * This function initializes the mempool private data in the case of a
1292  * pktmbuf pool. This private data is needed by the driver. The
1293  * function is given as a callback function to rte_mempool_create() at
1294  * pool creation. It can be extended by the user, for example, to
1295  * provide another packet size.
1296  *
1297  * @param mp
1298  *   The mempool from which mbufs originate.
1299  * @param opaque_arg
1300  *   A pointer that can be used by the user to retrieve useful information
1301  *   for mbuf initialization. This pointer comes from the ``init_arg``
1302  *   parameter of rte_mempool_create().
1303  */
1304 void rte_pktmbuf_pool_init(struct rte_mempool *mp, void *opaque_arg);
1305
1306 /**
1307  * Create a mbuf pool.
1308  *
1309  * This function creates and initializes a packet mbuf pool. It is
1310  * a wrapper to rte_mempool_create() with the proper packet constructor
1311  * and mempool constructor.
1312  *
1313  * @param name
1314  *   The name of the mbuf pool.
1315  * @param n
1316  *   The number of elements in the mbuf pool. The optimum size (in terms
1317  *   of memory usage) for a mempool is when n is a power of two minus one:
1318  *   n = (2^q - 1).
1319  * @param cache_size
1320  *   Size of the per-core object cache. See rte_mempool_create() for
1321  *   details.
1322  * @param priv_size
1323  *   Size of application private are between the rte_mbuf structure
1324  *   and the data buffer. This value must be aligned to RTE_MBUF_PRIV_ALIGN.
1325  * @param data_room_size
1326  *   Size of data buffer in each mbuf, including RTE_PKTMBUF_HEADROOM.
1327  * @param socket_id
1328  *   The socket identifier where the memory should be allocated. The
1329  *   value can be *SOCKET_ID_ANY* if there is no NUMA constraint for the
1330  *   reserved zone.
1331  * @return
1332  *   The pointer to the new allocated mempool, on success. NULL on error
1333  *   with rte_errno set appropriately. Possible rte_errno values include:
1334  *    - E_RTE_NO_CONFIG - function could not get pointer to rte_config structure
1335  *    - E_RTE_SECONDARY - function was called from a secondary process instance
1336  *    - EINVAL - cache size provided is too large, or priv_size is not aligned.
1337  *    - ENOSPC - the maximum number of memzones has already been allocated
1338  *    - EEXIST - a memzone with the same name already exists
1339  *    - ENOMEM - no appropriate memory area found in which to create memzone
1340  */
1341 struct rte_mempool *
1342 rte_pktmbuf_pool_create(const char *name, unsigned n,
1343         unsigned cache_size, uint16_t priv_size, uint16_t data_room_size,
1344         int socket_id);
1345
1346 /**
1347  * Get the data room size of mbufs stored in a pktmbuf_pool
1348  *
1349  * The data room size is the amount of data that can be stored in a
1350  * mbuf including the headroom (RTE_PKTMBUF_HEADROOM).
1351  *
1352  * @param mp
1353  *   The packet mbuf pool.
1354  * @return
1355  *   The data room size of mbufs stored in this mempool.
1356  */
1357 static inline uint16_t
1358 rte_pktmbuf_data_room_size(struct rte_mempool *mp)
1359 {
1360         struct rte_pktmbuf_pool_private *mbp_priv;
1361
1362         mbp_priv = (struct rte_pktmbuf_pool_private *)rte_mempool_get_priv(mp);
1363         return mbp_priv->mbuf_data_room_size;
1364 }
1365
1366 /**
1367  * Get the application private size of mbufs stored in a pktmbuf_pool
1368  *
1369  * The private size of mbuf is a zone located between the rte_mbuf
1370  * structure and the data buffer where an application can store data
1371  * associated to a packet.
1372  *
1373  * @param mp
1374  *   The packet mbuf pool.
1375  * @return
1376  *   The private size of mbufs stored in this mempool.
1377  */
1378 static inline uint16_t
1379 rte_pktmbuf_priv_size(struct rte_mempool *mp)
1380 {
1381         struct rte_pktmbuf_pool_private *mbp_priv;
1382
1383         mbp_priv = (struct rte_pktmbuf_pool_private *)rte_mempool_get_priv(mp);
1384         return mbp_priv->mbuf_priv_size;
1385 }
1386
1387 /**
1388  * Reset the fields of a packet mbuf to their default values.
1389  *
1390  * The given mbuf must have only one segment.
1391  *
1392  * @param m
1393  *   The packet mbuf to be resetted.
1394  */
1395 static inline void rte_pktmbuf_reset(struct rte_mbuf *m)
1396 {
1397         m->next = NULL;
1398         m->pkt_len = 0;
1399         m->tx_offload = 0;
1400         m->vlan_tci = 0;
1401         m->vlan_tci_outer = 0;
1402         m->nb_segs = 1;
1403         m->port = 0xff;
1404
1405         m->ol_flags = 0;
1406         m->packet_type = 0;
1407         m->data_off = (RTE_PKTMBUF_HEADROOM <= m->buf_len) ?
1408                         RTE_PKTMBUF_HEADROOM : m->buf_len;
1409
1410         m->data_len = 0;
1411         __rte_mbuf_sanity_check(m, 1);
1412 }
1413
1414 /**
1415  * Allocate a new mbuf from a mempool.
1416  *
1417  * This new mbuf contains one segment, which has a length of 0. The pointer
1418  * to data is initialized to have some bytes of headroom in the buffer
1419  * (if buffer size allows).
1420  *
1421  * @param mp
1422  *   The mempool from which the mbuf is allocated.
1423  * @return
1424  *   - The pointer to the new mbuf on success.
1425  *   - NULL if allocation failed.
1426  */
1427 static inline struct rte_mbuf *rte_pktmbuf_alloc(struct rte_mempool *mp)
1428 {
1429         struct rte_mbuf *m;
1430         if ((m = rte_mbuf_raw_alloc(mp)) != NULL)
1431                 rte_pktmbuf_reset(m);
1432         return m;
1433 }
1434
1435 /**
1436  * Allocate a bulk of mbufs, initialize refcnt and reset the fields to default
1437  * values.
1438  *
1439  *  @param pool
1440  *    The mempool from which mbufs are allocated.
1441  *  @param mbufs
1442  *    Array of pointers to mbufs
1443  *  @param count
1444  *    Array size
1445  *  @return
1446  *   - 0: Success
1447  */
1448 static inline int rte_pktmbuf_alloc_bulk(struct rte_mempool *pool,
1449          struct rte_mbuf **mbufs, unsigned count)
1450 {
1451         unsigned idx = 0;
1452         int rc;
1453
1454         rc = rte_mempool_get_bulk(pool, (void **)mbufs, count);
1455         if (unlikely(rc))
1456                 return rc;
1457
1458         /* To understand duff's device on loop unwinding optimization, see
1459          * https://en.wikipedia.org/wiki/Duff's_device.
1460          * Here while() loop is used rather than do() while{} to avoid extra
1461          * check if count is zero.
1462          */
1463         switch (count % 4) {
1464         case 0:
1465                 while (idx != count) {
1466                         RTE_ASSERT(rte_mbuf_refcnt_read(mbufs[idx]) == 0);
1467                         rte_mbuf_refcnt_set(mbufs[idx], 1);
1468                         rte_pktmbuf_reset(mbufs[idx]);
1469                         idx++;
1470         case 3:
1471                         RTE_ASSERT(rte_mbuf_refcnt_read(mbufs[idx]) == 0);
1472                         rte_mbuf_refcnt_set(mbufs[idx], 1);
1473                         rte_pktmbuf_reset(mbufs[idx]);
1474                         idx++;
1475         case 2:
1476                         RTE_ASSERT(rte_mbuf_refcnt_read(mbufs[idx]) == 0);
1477                         rte_mbuf_refcnt_set(mbufs[idx], 1);
1478                         rte_pktmbuf_reset(mbufs[idx]);
1479                         idx++;
1480         case 1:
1481                         RTE_ASSERT(rte_mbuf_refcnt_read(mbufs[idx]) == 0);
1482                         rte_mbuf_refcnt_set(mbufs[idx], 1);
1483                         rte_pktmbuf_reset(mbufs[idx]);
1484                         idx++;
1485                 }
1486         }
1487         return 0;
1488 }
1489
1490 /**
1491  * Attach packet mbuf to another packet mbuf.
1492  *
1493  * After attachment we refer the mbuf we attached as 'indirect',
1494  * while mbuf we attached to as 'direct'.
1495  * The direct mbuf's reference counter is incremented.
1496  *
1497  * Right now, not supported:
1498  *  - attachment for already indirect mbuf (e.g. - mi has to be direct).
1499  *  - mbuf we trying to attach (mi) is used by someone else
1500  *    e.g. it's reference counter is greater then 1.
1501  *
1502  * @param mi
1503  *   The indirect packet mbuf.
1504  * @param m
1505  *   The packet mbuf we're attaching to.
1506  */
1507 static inline void rte_pktmbuf_attach(struct rte_mbuf *mi, struct rte_mbuf *m)
1508 {
1509         struct rte_mbuf *md;
1510
1511         RTE_ASSERT(RTE_MBUF_DIRECT(mi) &&
1512             rte_mbuf_refcnt_read(mi) == 1);
1513
1514         /* if m is not direct, get the mbuf that embeds the data */
1515         if (RTE_MBUF_DIRECT(m))
1516                 md = m;
1517         else
1518                 md = rte_mbuf_from_indirect(m);
1519
1520         rte_mbuf_refcnt_update(md, 1);
1521         mi->priv_size = m->priv_size;
1522         mi->buf_physaddr = m->buf_physaddr;
1523         mi->buf_addr = m->buf_addr;
1524         mi->buf_len = m->buf_len;
1525
1526         mi->next = m->next;
1527         mi->data_off = m->data_off;
1528         mi->data_len = m->data_len;
1529         mi->port = m->port;
1530         mi->vlan_tci = m->vlan_tci;
1531         mi->vlan_tci_outer = m->vlan_tci_outer;
1532         mi->tx_offload = m->tx_offload;
1533         mi->hash = m->hash;
1534
1535         mi->next = NULL;
1536         mi->pkt_len = mi->data_len;
1537         mi->nb_segs = 1;
1538         mi->ol_flags = m->ol_flags | IND_ATTACHED_MBUF;
1539         mi->packet_type = m->packet_type;
1540
1541         __rte_mbuf_sanity_check(mi, 1);
1542         __rte_mbuf_sanity_check(m, 0);
1543 }
1544
1545 /**
1546  * Detach an indirect packet mbuf.
1547  *
1548  *  - restore original mbuf address and length values.
1549  *  - reset pktmbuf data and data_len to their default values.
1550  *  - decrement the direct mbuf's reference counter. When the
1551  *  reference counter becomes 0, the direct mbuf is freed.
1552  *
1553  * All other fields of the given packet mbuf will be left intact.
1554  *
1555  * @param m
1556  *   The indirect attached packet mbuf.
1557  */
1558 static inline void rte_pktmbuf_detach(struct rte_mbuf *m)
1559 {
1560         struct rte_mbuf *md = rte_mbuf_from_indirect(m);
1561         struct rte_mempool *mp = m->pool;
1562         uint32_t mbuf_size, buf_len, priv_size;
1563
1564         priv_size = rte_pktmbuf_priv_size(mp);
1565         mbuf_size = sizeof(struct rte_mbuf) + priv_size;
1566         buf_len = rte_pktmbuf_data_room_size(mp);
1567
1568         m->priv_size = priv_size;
1569         m->buf_addr = (char *)m + mbuf_size;
1570         m->buf_physaddr = rte_mempool_virt2phy(mp, m) + mbuf_size;
1571         m->buf_len = (uint16_t)buf_len;
1572         m->data_off = RTE_MIN(RTE_PKTMBUF_HEADROOM, (uint16_t)m->buf_len);
1573         m->data_len = 0;
1574         m->ol_flags = 0;
1575
1576         if (rte_mbuf_refcnt_update(md, -1) == 0)
1577                 __rte_mbuf_raw_free(md);
1578 }
1579
1580 static inline struct rte_mbuf* __attribute__((always_inline))
1581 __rte_pktmbuf_prefree_seg(struct rte_mbuf *m)
1582 {
1583         __rte_mbuf_sanity_check(m, 0);
1584
1585         if (likely(rte_mbuf_refcnt_update(m, -1) == 0)) {
1586                 /* if this is an indirect mbuf, it is detached. */
1587                 if (RTE_MBUF_INDIRECT(m))
1588                         rte_pktmbuf_detach(m);
1589                 return m;
1590         }
1591         return NULL;
1592 }
1593
1594 /**
1595  * Free a segment of a packet mbuf into its original mempool.
1596  *
1597  * Free an mbuf, without parsing other segments in case of chained
1598  * buffers.
1599  *
1600  * @param m
1601  *   The packet mbuf segment to be freed.
1602  */
1603 static inline void __attribute__((always_inline))
1604 rte_pktmbuf_free_seg(struct rte_mbuf *m)
1605 {
1606         if (likely(NULL != (m = __rte_pktmbuf_prefree_seg(m)))) {
1607                 m->next = NULL;
1608                 __rte_mbuf_raw_free(m);
1609         }
1610 }
1611
1612 /**
1613  * Free a packet mbuf back into its original mempool.
1614  *
1615  * Free an mbuf, and all its segments in case of chained buffers. Each
1616  * segment is added back into its original mempool.
1617  *
1618  * @param m
1619  *   The packet mbuf to be freed.
1620  */
1621 static inline void rte_pktmbuf_free(struct rte_mbuf *m)
1622 {
1623         struct rte_mbuf *m_next;
1624
1625         __rte_mbuf_sanity_check(m, 1);
1626
1627         while (m != NULL) {
1628                 m_next = m->next;
1629                 rte_pktmbuf_free_seg(m);
1630                 m = m_next;
1631         }
1632 }
1633
1634 /**
1635  * Creates a "clone" of the given packet mbuf.
1636  *
1637  * Walks through all segments of the given packet mbuf, and for each of them:
1638  *  - Creates a new packet mbuf from the given pool.
1639  *  - Attaches newly created mbuf to the segment.
1640  * Then updates pkt_len and nb_segs of the "clone" packet mbuf to match values
1641  * from the original packet mbuf.
1642  *
1643  * @param md
1644  *   The packet mbuf to be cloned.
1645  * @param mp
1646  *   The mempool from which the "clone" mbufs are allocated.
1647  * @return
1648  *   - The pointer to the new "clone" mbuf on success.
1649  *   - NULL if allocation fails.
1650  */
1651 static inline struct rte_mbuf *rte_pktmbuf_clone(struct rte_mbuf *md,
1652                 struct rte_mempool *mp)
1653 {
1654         struct rte_mbuf *mc, *mi, **prev;
1655         uint32_t pktlen;
1656         uint8_t nseg;
1657
1658         if (unlikely ((mc = rte_pktmbuf_alloc(mp)) == NULL))
1659                 return NULL;
1660
1661         mi = mc;
1662         prev = &mi->next;
1663         pktlen = md->pkt_len;
1664         nseg = 0;
1665
1666         do {
1667                 nseg++;
1668                 rte_pktmbuf_attach(mi, md);
1669                 *prev = mi;
1670                 prev = &mi->next;
1671         } while ((md = md->next) != NULL &&
1672             (mi = rte_pktmbuf_alloc(mp)) != NULL);
1673
1674         *prev = NULL;
1675         mc->nb_segs = nseg;
1676         mc->pkt_len = pktlen;
1677
1678         /* Allocation of new indirect segment failed */
1679         if (unlikely (mi == NULL)) {
1680                 rte_pktmbuf_free(mc);
1681                 return NULL;
1682         }
1683
1684         __rte_mbuf_sanity_check(mc, 1);
1685         return mc;
1686 }
1687
1688 /**
1689  * Adds given value to the refcnt of all packet mbuf segments.
1690  *
1691  * Walks through all segments of given packet mbuf and for each of them
1692  * invokes rte_mbuf_refcnt_update().
1693  *
1694  * @param m
1695  *   The packet mbuf whose refcnt to be updated.
1696  * @param v
1697  *   The value to add to the mbuf's segments refcnt.
1698  */
1699 static inline void rte_pktmbuf_refcnt_update(struct rte_mbuf *m, int16_t v)
1700 {
1701         __rte_mbuf_sanity_check(m, 1);
1702
1703         do {
1704                 rte_mbuf_refcnt_update(m, v);
1705         } while ((m = m->next) != NULL);
1706 }
1707
1708 /**
1709  * Get the headroom in a packet mbuf.
1710  *
1711  * @param m
1712  *   The packet mbuf.
1713  * @return
1714  *   The length of the headroom.
1715  */
1716 static inline uint16_t rte_pktmbuf_headroom(const struct rte_mbuf *m)
1717 {
1718         __rte_mbuf_sanity_check(m, 1);
1719         return m->data_off;
1720 }
1721
1722 /**
1723  * Get the tailroom of a packet mbuf.
1724  *
1725  * @param m
1726  *   The packet mbuf.
1727  * @return
1728  *   The length of the tailroom.
1729  */
1730 static inline uint16_t rte_pktmbuf_tailroom(const struct rte_mbuf *m)
1731 {
1732         __rte_mbuf_sanity_check(m, 1);
1733         return (uint16_t)(m->buf_len - rte_pktmbuf_headroom(m) -
1734                           m->data_len);
1735 }
1736
1737 /**
1738  * Get the last segment of the packet.
1739  *
1740  * @param m
1741  *   The packet mbuf.
1742  * @return
1743  *   The last segment of the given mbuf.
1744  */
1745 static inline struct rte_mbuf *rte_pktmbuf_lastseg(struct rte_mbuf *m)
1746 {
1747         struct rte_mbuf *m2 = (struct rte_mbuf *)m;
1748
1749         __rte_mbuf_sanity_check(m, 1);
1750         while (m2->next != NULL)
1751                 m2 = m2->next;
1752         return m2;
1753 }
1754
1755 /**
1756  * A macro that points to an offset into the data in the mbuf.
1757  *
1758  * The returned pointer is cast to type t. Before using this
1759  * function, the user must ensure that the first segment is large
1760  * enough to accommodate its data.
1761  *
1762  * @param m
1763  *   The packet mbuf.
1764  * @param o
1765  *   The offset into the mbuf data.
1766  * @param t
1767  *   The type to cast the result into.
1768  */
1769 #define rte_pktmbuf_mtod_offset(m, t, o)        \
1770         ((t)((char *)(m)->buf_addr + (m)->data_off + (o)))
1771
1772 /**
1773  * A macro that points to the start of the data in the mbuf.
1774  *
1775  * The returned pointer is cast to type t. Before using this
1776  * function, the user must ensure that the first segment is large
1777  * enough to accommodate its data.
1778  *
1779  * @param m
1780  *   The packet mbuf.
1781  * @param t
1782  *   The type to cast the result into.
1783  */
1784 #define rte_pktmbuf_mtod(m, t) rte_pktmbuf_mtod_offset(m, t, 0)
1785
1786 /**
1787  * A macro that returns the physical address that points to an offset of the
1788  * start of the data in the mbuf
1789  *
1790  * @param m
1791  *   The packet mbuf.
1792  * @param o
1793  *   The offset into the data to calculate address from.
1794  */
1795 #define rte_pktmbuf_mtophys_offset(m, o) \
1796         (phys_addr_t)((m)->buf_physaddr + (m)->data_off + (o))
1797
1798 /**
1799  * A macro that returns the physical address that points to the start of the
1800  * data in the mbuf
1801  *
1802  * @param m
1803  *   The packet mbuf.
1804  */
1805 #define rte_pktmbuf_mtophys(m) rte_pktmbuf_mtophys_offset(m, 0)
1806
1807 /**
1808  * A macro that returns the length of the packet.
1809  *
1810  * The value can be read or assigned.
1811  *
1812  * @param m
1813  *   The packet mbuf.
1814  */
1815 #define rte_pktmbuf_pkt_len(m) ((m)->pkt_len)
1816
1817 /**
1818  * A macro that returns the length of the segment.
1819  *
1820  * The value can be read or assigned.
1821  *
1822  * @param m
1823  *   The packet mbuf.
1824  */
1825 #define rte_pktmbuf_data_len(m) ((m)->data_len)
1826
1827 /**
1828  * Prepend len bytes to an mbuf data area.
1829  *
1830  * Returns a pointer to the new
1831  * data start address. If there is not enough headroom in the first
1832  * segment, the function will return NULL, without modifying the mbuf.
1833  *
1834  * @param m
1835  *   The pkt mbuf.
1836  * @param len
1837  *   The amount of data to prepend (in bytes).
1838  * @return
1839  *   A pointer to the start of the newly prepended data, or
1840  *   NULL if there is not enough headroom space in the first segment
1841  */
1842 static inline char *rte_pktmbuf_prepend(struct rte_mbuf *m,
1843                                         uint16_t len)
1844 {
1845         __rte_mbuf_sanity_check(m, 1);
1846
1847         if (unlikely(len > rte_pktmbuf_headroom(m)))
1848                 return NULL;
1849
1850         m->data_off -= len;
1851         m->data_len = (uint16_t)(m->data_len + len);
1852         m->pkt_len  = (m->pkt_len + len);
1853
1854         return (char *)m->buf_addr + m->data_off;
1855 }
1856
1857 /**
1858  * Append len bytes to an mbuf.
1859  *
1860  * Append len bytes to an mbuf and return a pointer to the start address
1861  * of the added data. If there is not enough tailroom in the last
1862  * segment, the function will return NULL, without modifying the mbuf.
1863  *
1864  * @param m
1865  *   The packet mbuf.
1866  * @param len
1867  *   The amount of data to append (in bytes).
1868  * @return
1869  *   A pointer to the start of the newly appended data, or
1870  *   NULL if there is not enough tailroom space in the last segment
1871  */
1872 static inline char *rte_pktmbuf_append(struct rte_mbuf *m, uint16_t len)
1873 {
1874         void *tail;
1875         struct rte_mbuf *m_last;
1876
1877         __rte_mbuf_sanity_check(m, 1);
1878
1879         m_last = rte_pktmbuf_lastseg(m);
1880         if (unlikely(len > rte_pktmbuf_tailroom(m_last)))
1881                 return NULL;
1882
1883         tail = (char *)m_last->buf_addr + m_last->data_off + m_last->data_len;
1884         m_last->data_len = (uint16_t)(m_last->data_len + len);
1885         m->pkt_len  = (m->pkt_len + len);
1886         return (char*) tail;
1887 }
1888
1889 /**
1890  * Remove len bytes at the beginning of an mbuf.
1891  *
1892  * Returns a pointer to the start address of the new data area. If the
1893  * length is greater than the length of the first segment, then the
1894  * function will fail and return NULL, without modifying the mbuf.
1895  *
1896  * @param m
1897  *   The packet mbuf.
1898  * @param len
1899  *   The amount of data to remove (in bytes).
1900  * @return
1901  *   A pointer to the new start of the data.
1902  */
1903 static inline char *rte_pktmbuf_adj(struct rte_mbuf *m, uint16_t len)
1904 {
1905         __rte_mbuf_sanity_check(m, 1);
1906
1907         if (unlikely(len > m->data_len))
1908                 return NULL;
1909
1910         m->data_len = (uint16_t)(m->data_len - len);
1911         m->data_off += len;
1912         m->pkt_len  = (m->pkt_len - len);
1913         return (char *)m->buf_addr + m->data_off;
1914 }
1915
1916 /**
1917  * Remove len bytes of data at the end of the mbuf.
1918  *
1919  * If the length is greater than the length of the last segment, the
1920  * function will fail and return -1 without modifying the mbuf.
1921  *
1922  * @param m
1923  *   The packet mbuf.
1924  * @param len
1925  *   The amount of data to remove (in bytes).
1926  * @return
1927  *   - 0: On success.
1928  *   - -1: On error.
1929  */
1930 static inline int rte_pktmbuf_trim(struct rte_mbuf *m, uint16_t len)
1931 {
1932         struct rte_mbuf *m_last;
1933
1934         __rte_mbuf_sanity_check(m, 1);
1935
1936         m_last = rte_pktmbuf_lastseg(m);
1937         if (unlikely(len > m_last->data_len))
1938                 return -1;
1939
1940         m_last->data_len = (uint16_t)(m_last->data_len - len);
1941         m->pkt_len  = (m->pkt_len - len);
1942         return 0;
1943 }
1944
1945 /**
1946  * Test if mbuf data is contiguous.
1947  *
1948  * @param m
1949  *   The packet mbuf.
1950  * @return
1951  *   - 1, if all data is contiguous (one segment).
1952  *   - 0, if there is several segments.
1953  */
1954 static inline int rte_pktmbuf_is_contiguous(const struct rte_mbuf *m)
1955 {
1956         __rte_mbuf_sanity_check(m, 1);
1957         return !!(m->nb_segs == 1);
1958 }
1959
1960 /**
1961  * Chain an mbuf to another, thereby creating a segmented packet.
1962  *
1963  * Note: The implementation will do a linear walk over the segments to find
1964  * the tail entry. For cases when there are many segments, it's better to
1965  * chain the entries manually.
1966  *
1967  * @param head
1968  *   The head of the mbuf chain (the first packet)
1969  * @param tail
1970  *   The mbuf to put last in the chain
1971  *
1972  * @return
1973  *   - 0, on success.
1974  *   - -EOVERFLOW, if the chain is full (256 entries)
1975  */
1976 static inline int rte_pktmbuf_chain(struct rte_mbuf *head, struct rte_mbuf *tail)
1977 {
1978         struct rte_mbuf *cur_tail;
1979
1980         /* Check for number-of-segments-overflow */
1981         if (head->nb_segs + tail->nb_segs >= 1 << (sizeof(head->nb_segs) * 8))
1982                 return -EOVERFLOW;
1983
1984         /* Chain 'tail' onto the old tail */
1985         cur_tail = rte_pktmbuf_lastseg(head);
1986         cur_tail->next = tail;
1987
1988         /* accumulate number of segments and total length. */
1989         head->nb_segs = (uint8_t)(head->nb_segs + tail->nb_segs);
1990         head->pkt_len += tail->pkt_len;
1991
1992         /* pkt_len is only set in the head */
1993         tail->pkt_len = tail->data_len;
1994
1995         return 0;
1996 }
1997
1998 /**
1999  * Dump an mbuf structure to the console.
2000  *
2001  * Dump all fields for the given packet mbuf and all its associated
2002  * segments (in the case of a chained buffer).
2003  *
2004  * @param f
2005  *   A pointer to a file for output
2006  * @param m
2007  *   The packet mbuf.
2008  * @param dump_len
2009  *   If dump_len != 0, also dump the "dump_len" first data bytes of
2010  *   the packet.
2011  */
2012 void rte_pktmbuf_dump(FILE *f, const struct rte_mbuf *m, unsigned dump_len);
2013
2014 #ifdef __cplusplus
2015 }
2016 #endif
2017
2018 #endif /* _RTE_MBUF_H_ */