enforce experimental tag at beginning of declarations

[dpdk.git] / lib / librte_mbuf / rte_mbuf.h

diff --git a/lib/librte_mbuf/rte_mbuf.h b/lib/librte_mbuf/rte_mbuf.h
index f7886dc..9542488 100644 (file)
--- a/lib/librte_mbuf/rte_mbuf.h
+++ b/lib/librte_mbuf/rte_mbuf.h
@@ -210,7 +210,7 @@ extern "C" {
 /**
  * Outer UDP checksum offload flag. This flag is used for enabling
  * outer UDP checksum in PMD. To use outer UDP checksum, the user needs to
- * 1) Enable the following in mbuff,
+ * 1) Enable the following in mbuf,
  * a) Fill outer_l2_len and outer_l3_len in mbuf.
  * b) Set the PKT_TX_OUTER_UDP_CKSUM flag.
  * c) Set the PKT_TX_OUTER_IPV4 or PKT_TX_OUTER_IPV6 flag.
@@ -280,9 +280,11 @@ extern "C" {
 #define PKT_TX_TUNNEL_MASK    (0xFULL << 45)
 
 /**
- * Second VLAN insertion (QinQ) flag.
+ * Double VLAN insertion (QinQ) request to driver, driver may offload the
+ * insertion based on device capability.
+ * mbuf 'vlan_tci' & 'vlan_tci_outer' must be valid when this flag is set.
  */
-#define PKT_TX_QINQ        (1ULL << 49)   /**< TX packet with double VLAN inserted. */
+#define PKT_TX_QINQ        (1ULL << 49)
 /* this old name is deprecated */
 #define PKT_TX_QINQ_PKT    PKT_TX_QINQ
 
@@ -338,7 +340,9 @@ extern "C" {
 #define PKT_TX_IPV6          (1ULL << 56)
 
 /**
- * TX packet is a 802.1q VLAN packet.
+ * VLAN tag insertion request to driver, driver may offload the insertion
+ * based on the device capability.
+ * mbuf 'vlan_tci' field must be valid when this flag is set.
  */
 #define PKT_TX_VLAN          (1ULL << 57)
 /* this old name is deprecated */
@@ -481,7 +485,7 @@ struct rte_mbuf_sched {
 }; /**< Hierarchical scheduler */
 
 /**
- * enum for the tx_offload bit-fields lenghts and offsets.
+ * enum for the tx_offload bit-fields lengths and offsets.
  * defines the layout of rte_mbuf tx_offload field.
  */
 enum {
@@ -500,7 +504,7 @@ enum {
                RTE_MBUF_OUTL2_LEN_BITS,
 #if RTE_BYTE_ORDER == RTE_BIG_ENDIAN
        RTE_MBUF_L2_LEN_OFS =
-               sizeof(uint64_t) * CHAR_BIT - RTE_MBUF_L2_LEN_BITS
+               sizeof(uint64_t) * CHAR_BIT - RTE_MBUF_L2_LEN_BITS,
        RTE_MBUF_L3_LEN_OFS = RTE_MBUF_L2_LEN_OFS - RTE_MBUF_L3_LEN_BITS,
        RTE_MBUF_L4_LEN_OFS = RTE_MBUF_L3_LEN_OFS - RTE_MBUF_L4_LEN_BITS,
        RTE_MBUF_TSO_SEGSZ_OFS = RTE_MBUF_L4_LEN_OFS - RTE_MBUF_TSO_SEGSZ_BITS,
@@ -664,6 +668,8 @@ struct rte_mbuf {
 
        /** Valid if PKT_RX_TIMESTAMP is set. The unit and time reference
         * are not normalized but are always the same for a given port.
+        * Some devices allow to query rte_eth_read_clock that will return the
+        * current device timestamp.
         */
        uint64_t timestamp;
 
@@ -860,7 +866,8 @@ rte_mbuf_from_indirect(struct rte_mbuf *mi)
  * @return
  *   The pointer of the mbuf buffer.
  */
-static inline char * __rte_experimental
+__rte_experimental
+static inline char *
 rte_mbuf_buf_addr(struct rte_mbuf *mb, struct rte_mempool *mp)
 {
        return (char *)mb + sizeof(*mb) + rte_pktmbuf_priv_size(mp);
@@ -877,10 +884,18 @@ rte_mbuf_buf_addr(struct rte_mbuf *mb, struct rte_mempool *mp)
  * @return
  *   The pointer of the beginning of the mbuf data.
  */
-static inline char * __rte_experimental
-rte_mbuf_data_addr_default(struct rte_mbuf *mb)
+__rte_experimental
+static inline char *
+rte_mbuf_data_addr_default(__rte_unused struct rte_mbuf *mb)
 {
+       /* gcc complains about calling this experimental function even
+        * when not using it. Hide it with ALLOW_EXPERIMENTAL_API.
+        */
+#ifdef ALLOW_EXPERIMENTAL_API
        return rte_mbuf_buf_addr(mb, mb->pool) + RTE_PKTMBUF_HEADROOM;
+#else
+       return NULL;
+#endif
 }
 
 /**
@@ -920,7 +935,8 @@ rte_mbuf_to_baddr(struct rte_mbuf *md)
  * @return
  *   The starting address of the private data area of the given mbuf.
  */
-static inline void * __rte_experimental
+__rte_experimental
+static inline void *
 rte_mbuf_to_priv(struct rte_mbuf *m)
 {
        return RTE_PTR_ADD(m, sizeof(struct rte_mbuf));
@@ -1419,7 +1435,7 @@ static inline void rte_pktmbuf_reset_headroom(struct rte_mbuf *m)
  * The given mbuf must have only one segment.
  *
  * @param m
- *   The packet mbuf to be resetted.
+ *   The packet mbuf to be reset.
  */
 #define MBUF_INVALID_PORT UINT16_MAX
 
@@ -1592,7 +1608,7 @@ rte_pktmbuf_ext_shinfo_init_helper(void *buf_addr, uint16_t *buf_len,
  * ``rte_pktmbuf_detach()``.
  *
  * Memory for shared data must be provided and user must initialize all of
- * the content properly, escpecially free callback and refcnt. The pointer
+ * the content properly, especially free callback and refcnt. The pointer
  * of shared data will be stored in m->shinfo.
  * ``rte_pktmbuf_ext_shinfo_init_helper`` can help to simply spare a few
  * bytes at the end of buffer for the shared data, store free callback and