RE: [RFC PATCH] doc: clarify VLAN and QinQ stripping behaviour

["Morten Brørup" <mb@smartsharesystems.com>]

> From: Bruce Richardson [mailto:bruce.richardson@intel.com]
> Sent: Monday, 14 July 2025 15.30
> 
> The behaviour of VLAN tag stripping Rx offloads is unclear in DPDK, and
> not very well documented. Even the documentation that does exist appears
> contradictory.
> 
> For example, the doxygen docs for the mbuf flag
> RTE_MBUF_F_RX_QINQ_STRIPPED says:
> 
>   "If RTE_MBUF_F_RX_QINQ_STRIPPED is set and RTE_MBUF_F_RX_VLAN_STRIPPED
>   is unset, only the outer VLAN is removed from packet data,..."
> 
> but the docs for RTE_MBUF_F_RX_QINQ says:
> 
>   "If the flag RTE_MBUF_F_RX_QINQ_STRIPPED is also present, both VLANs
>   headers have been stripped from mbuf data, ..."
> 
> Without a good definition of what the correct behaviour is, it's not
> possible to assess and ensure conformance across drivers. Update the
> documentation for NIC features, ethdev and mbuf library to all report
> the same information: that VLAN strip feature is stripping one flag, and
> QinQ strip feature is removing two.
> 
> Summary of VLAN and QinQ stripping behaviour as reported in docs after
> this patch:
> 
> +-------------------+----------------------+----------------------------
> +
> | Input Traffic     | VLAN-strip on        | QinQ strip on
> |
> +===================+======================+============================
> +
> | Single VLAN pkts  | Tag in vlan_tci      | Tag in vlan_tci
> |
> +-------------------+----------------------+----------------------------
> +
> | Double VLAN pkts  | Outer tag in vlan_tci| Outer tag in
> vlan_tci_outer|
> |                   |                      | Inner tag in vlan_tci
> |
> +-------------------+----------------------+----------------------------
> +
> 
> Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
> ---

I think your RFC is not a description of originally intended behavior.
However, I think your last thought in the previous discussion, speculating about the original intention, was correct:

The QINQ flag and the VLAN flag are completely independent.

The QINQ flag refers to EtherType 0x88a8 (QinQ) tags, and vlan_tci_outer holds the ID of such a tag.
It can be the outer tag of a double-tagged packet (i.e. the S-TAG of a packet with a C-TAG (C-TAG = Customer's VLAN tag)), or
the only tag of a single EtherType 0x88a8 tagged packet (i.e. the S-TAG of a customer packet with no VLAN tag).

The VLAN flag refers to EtherType 0x8100 (VLAN) tags, and vlan_tci holds the ID of such a tag.
It can be the only tag of a single EtherType 0x8100 tagged packet (i.e. a normal VLAN tag), or
the inner tag (i.e. the C-TAG) of a double-tagged packet with an outer EtherType 0x88a8 tag (the S-TAG).

On RX, RTE_MBUF_F_RX_QINQ (and vlan_tci_outer) should be set if the packet has an EtherType 0x88a8 tag (as the only tag, or as the outer tag).
If it was stripped, RTE_MBUF_F_RX_QINQ_STRIPPED should also be set.
Similarly on RX, RTE_MBUF_F_RX_VLAN (and vlan_tci) should be set if the packet has an EtherType 0x8100 tag (as the only tag, or after the QinQ tag).
If it was stripped, RTE_MBUF_F_RX_VLAN_STRIPPED should also be set.

Same goes for TX: If RTE_MBUF_F_TX_VLAN_INSERT is set, an EtherType 0x8100 tag should be inserted with the ID coming from vlan_tci.
Similarly for TX, if RTE_MBUF_F_TX_QINQ_INSERT is set, an EtherType 0x88a8 tag should be inserted with the ID coming from vlan_tci_outer.
Any HW inserted tags are inserted as the outermost tag, i.e. after the MAC addresses in the Ethernet header.
And the VLAN tag insertion (if any) happens before the QinQ tag insertion (if any).

Note:
With this behavior, VLAN Stacking (i.e. double-tagged packets using EtherType 0x8100 for both inner and outer tag) can only be partially hardware offloaded.
On RX, HW VLAN stripping will strip the outer VLAN tag to vlan_tci, and the application must move vlan_tci to vlan_tci_outer and manually strip the inner VLAN tag to vlan_tci.
On TX, the application must manually insert the inner tag from vlan_tci, and move vlan_tci_outer to vlan_tci, and HW VLAN insertion will insert the outer VLAN tag from vlan_tci.


Support for VLAN Stacking would be nice, but it should be added as a new feature, not through a doc update.