RE: [PATCH] mbuf: improve mbuf comments

Morten Brørup
2025-11-05T11:34:00Z

> 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