[PATCH] mbuf: improve mbuf comments

[PATCH] mbuf: improve mbuf comments

[Morten Brørup]

Updated the comment preceding the 'rearm_data' fields to reflect that some
ethdev drivers don't really set the rearm_data fields on RX descriptor
rearm, but rather when pulling the packet from the descriptor.
By doing this, they avoid a store operation into the mbuf when they rearm
the TX descriptor, and instead postpone it to later, where it will be
combined with other store operations into the mbuf.

Updated the comment describing what the second cache line is used for, to
reflect that there are exceptions, where some fields are set on RX too.

Updated comments describing what needs to be updated when adding new RX
and TX offload flags.

Signed-off-by: Morten Brørup <mb@smartsharesystems.com>
---
 lib/mbuf/rte_mbuf_core.h | 29 ++++++++++++++++++++++-------
 1 file changed, 22 insertions(+), 7 deletions(-)

diff --git a/lib/mbuf/rte_mbuf_core.h b/lib/mbuf/rte_mbuf_core.h
index a9caaf4e14..6d66eab11d 100644
--- a/lib/mbuf/rte_mbuf_core.h
+++ b/lib/mbuf/rte_mbuf_core.h
@@ -37,8 +37,8 @@ extern "C" {
  *   added to the right of the previously defined flags i.e. they should count
  *   downwards, not upwards.
  *
- * Keep these flags synchronized with rte_get_rx_ol_flag_name() and
- * rte_get_tx_ol_flag_name().
+ * Keep these flags synchronized with rte_get_rx_ol_flag_name(), rte_get_rx_ol_flag_list(),
+ * rte_get_tx_ol_flag_name(), and rte_get_tx_ol_flag_list().
  */
 
 /**
@@ -180,12 +180,20 @@ extern "C" {
 #define RTE_MBUF_F_RX_OUTER_L4_CKSUM_GOOD	(1ULL << 22)
 #define RTE_MBUF_F_RX_OUTER_L4_CKSUM_INVALID	((1ULL << 21) | (1ULL << 22))
 
-/* add new RX flags here, don't forget to update RTE_MBUF_F_FIRST_FREE */
+/*
+ * Add new RX flags here.
+ * Don't forget to update RTE_MBUF_F_FIRST_FREE,
+ * rte_get_rx_ol_flag_name(), and rte_get_rx_ol_flag_list().
+ */
 
 #define RTE_MBUF_F_FIRST_FREE (1ULL << 23)
 #define RTE_MBUF_F_LAST_FREE (1ULL << 40)
 
-/* add new TX flags here, don't forget to update RTE_MBUF_F_LAST_FREE  */
+/*
+ * Add new TX flags here.
+ * Don't forget to update RTE_MBUF_F_LAST_FREE, RTE_MBUF_F_TX_OFFLOAD_MASK,
+ * rte_get_tx_ol_flag_name(), and rte_get_tx_ol_flag_list().
+ */
 
 /**
  * Outer UDP checksum offload flag. This flag is used for enabling
@@ -485,7 +493,10 @@ struct __rte_cache_aligned rte_mbuf {
 	struct rte_mbuf *next;
 #endif
 
-	/* next 8 bytes are initialised on RX descriptor rearm */
+	/*
+	 * Next 8 bytes are initialised on RX descriptor rearm,
+	 * or on RX when pulling packet from descriptor.
+	 */
 	union {
 		uint64_t rearm_data[1];
 		__extension__
@@ -517,7 +528,7 @@ struct __rte_cache_aligned rte_mbuf {
 
 	uint64_t ol_flags;        /**< Offload features. */
 
-	/* remaining 24 bytes are set on RX when pulling packet from descriptor */
+	/* Remaining 24 bytes are set on RX when pulling packet from descriptor. */
 	union {
 		/* void * type of the array elements is retained for driver compatibility. */
 		void *rx_descriptor_fields1[24 / sizeof(void *)];
@@ -603,7 +614,11 @@ struct __rte_cache_aligned rte_mbuf {
 
 	struct rte_mempool *pool; /**< Pool from which mbuf was allocated. */
 
-	/* second cache line - fields only used in slow path or on TX */
+	/*
+	 * Second cache line - fields only used in slow path or on TX.
+	 * In special cases, some of these fields are also set on RX,
+	 * most notably the 'next' field is set on RX scattered packets.
+	 */
 #if RTE_IOVA_IN_MBUF
 	/**
 	 * Next segment of scattered packet. Must be NULL in the last
-- 
2.43.0

RE: [PATCH] mbuf: improve mbuf comments

[Morten Brørup]

> From: Morten Brørup [mailto:mb@smartsharesystems.com]
> Sent: Wednesday, 5 November 2025 12.28
> 
> Updated the comment preceding the 'rearm_data' fields to reflect that
> some
> ethdev drivers don't really set the rearm_data fields on RX descriptor
> rearm, but rather when pulling the packet from the descriptor.
> By doing this, they avoid a store operation into the mbuf when they
> rearm
> the TX descriptor, and instead postpone it to later, where it will be

Typo: TX descriptor -> RX descriptor.

> combined with other store operations into the mbuf.
> 
> Updated the comment describing what the second cache line is used for,
> to
> reflect that there are exceptions, where some fields are set on RX too.
> 
> Updated comments describing what needs to be updated when adding new RX
> and TX offload flags.
> 
> Signed-off-by: Morten Brørup <mb@smartsharesystems.com>
> ---
>  lib/mbuf/rte_mbuf_core.h | 29 ++++++++++++++++++++++-------
>  1 file changed, 22 insertions(+), 7 deletions(-)
> 
> diff --git a/lib/mbuf/rte_mbuf_core.h b/lib/mbuf/rte_mbuf_core.h
> index a9caaf4e14..6d66eab11d 100644
> --- a/lib/mbuf/rte_mbuf_core.h
> +++ b/lib/mbuf/rte_mbuf_core.h
> @@ -37,8 +37,8 @@ extern "C" {
>   *   added to the right of the previously defined flags i.e. they
> should count
>   *   downwards, not upwards.
>   *
> - * Keep these flags synchronized with rte_get_rx_ol_flag_name() and
> - * rte_get_tx_ol_flag_name().
> + * Keep these flags synchronized with rte_get_rx_ol_flag_name(),
> rte_get_rx_ol_flag_list(),
> + * rte_get_tx_ol_flag_name(), and rte_get_tx_ol_flag_list().
>   */
> 
>  /**
> @@ -180,12 +180,20 @@ extern "C" {
>  #define RTE_MBUF_F_RX_OUTER_L4_CKSUM_GOOD	(1ULL << 22)
>  #define RTE_MBUF_F_RX_OUTER_L4_CKSUM_INVALID	((1ULL << 21) | (1ULL
> << 22))
> 
> -/* add new RX flags here, don't forget to update RTE_MBUF_F_FIRST_FREE
> */
> +/*
> + * Add new RX flags here.
> + * Don't forget to update RTE_MBUF_F_FIRST_FREE,
> + * rte_get_rx_ol_flag_name(), and rte_get_rx_ol_flag_list().
> + */
> 
>  #define RTE_MBUF_F_FIRST_FREE (1ULL << 23)
>  #define RTE_MBUF_F_LAST_FREE (1ULL << 40)
> 
> -/* add new TX flags here, don't forget to update RTE_MBUF_F_LAST_FREE
> */
> +/*
> + * Add new TX flags here.
> + * Don't forget to update RTE_MBUF_F_LAST_FREE,
> RTE_MBUF_F_TX_OFFLOAD_MASK,
> + * rte_get_tx_ol_flag_name(), and rte_get_tx_ol_flag_list().
> + */
> 
>  /**
>   * Outer UDP checksum offload flag. This flag is used for enabling
> @@ -485,7 +493,10 @@ struct __rte_cache_aligned rte_mbuf {
>  	struct rte_mbuf *next;
>  #endif
> 
> -	/* next 8 bytes are initialised on RX descriptor rearm */
> +	/*
> +	 * Next 8 bytes are initialised on RX descriptor rearm,
> +	 * or on RX when pulling packet from descriptor.
> +	 */
>  	union {
>  		uint64_t rearm_data[1];
>  		__extension__
> @@ -517,7 +528,7 @@ struct __rte_cache_aligned rte_mbuf {
> 
>  	uint64_t ol_flags;        /**< Offload features. */
> 
> -	/* remaining 24 bytes are set on RX when pulling packet from
> descriptor */
> +	/* Remaining 24 bytes are set on RX when pulling packet from
> descriptor. */
>  	union {
>  		/* void * type of the array elements is retained for driver
> compatibility. */
>  		void *rx_descriptor_fields1[24 / sizeof(void *)];
> @@ -603,7 +614,11 @@ struct __rte_cache_aligned rte_mbuf {
> 
>  	struct rte_mempool *pool; /**< Pool from which mbuf was
> allocated. */
> 
> -	/* second cache line - fields only used in slow path or on TX */
> +	/*
> +	 * Second cache line - fields only used in slow path or on TX.
> +	 * In special cases, some of these fields are also set on RX,
> +	 * most notably the 'next' field is set on RX scattered packets.
> +	 */
>  #if RTE_IOVA_IN_MBUF
>  	/**
>  	 * Next segment of scattered packet. Must be NULL in the last
> --
> 2.43.0