[PATCH] doc: announce header split deprecation

[Andrew Rybchenko]

On 7/14/22 16:25, Thomas Monjalon wrote:
> 14/07/2022 14:54, Ding, Xuan:
>> Hi,
>>
>> From: Thomas Monjalon <thomas at monjalon.net>
>>> 14/07/2022 07:50, Ding, Xuan:
>>>> From: Thomas Monjalon <thomas at monjalon.net>
>>>>> 23/05/2022 16:20, xuan.ding at intel.com:
>>>>>> From: Xuan Ding <xuan.ding at intel.com>
>>>>>>
>>>>>> RTE_ETH_RX_OFFLOAD_HEADER_SPLIT offload was introduced some
>>> time
>>>>> ago
>>>>>> to substitute bit-field header_split in struct rte_eth_rxmode. It
>>>>>> allows to enable header split offload with the header size
>>>>>> controlled using split_hdr_size in the same structure.
>>>>>>
>>>>>> Right now, no single PMD actually supports
>>>>>> RTE_ETH_RX_OFFLOAD_HEADER_SPLIT with above definition. Many
>>>>>> examples and test apps initialize the field to 0 explicitly. The
>>>>>> most of drivers simply ignore split_hdr_size since the offload is
>>>>>> not advertised, but
>>>>> some double-check that its value is 0.
>>>>>>
>>>>>> So the RTE_ETH_RX_OFFLOAD_HEADER_SPLIT and split_header_size
>>> field
>>>>>> will be removed in DPDK 22.11.
>>>>>>
>>>>>> Signed-off-by: Xuan Ding <xuan.ding at intel.com>
>>>>>> ---
>>>>>>   doc/guides/rel_notes/deprecation.rst | 4 ++++
>>>>>>   1 file changed, 4 insertions(+)
>>>>>>
>>>>>> diff --git a/doc/guides/rel_notes/deprecation.rst
>>>>>> b/doc/guides/rel_notes/deprecation.rst
>>>>>> index 4e5b23c53d..b8114f29ed 100644
>>>>>> --- a/doc/guides/rel_notes/deprecation.rst
>>>>>> +++ b/doc/guides/rel_notes/deprecation.rst
>>>>>> @@ -125,3 +125,7 @@ Deprecation Notices
>>>>>>     applications should be updated to use the ``dmadev`` library instead,
>>>>>>     with the underlying HW-functionality being provided by the ``ioat`` or
>>>>>>     ``idxd`` dma drivers
>>>>>> +
>>>>>> +* ethdev: After bit-field header split was removed, the
>>>>>> +``RTE_ETH_RX_OFFLOAD_HEADER_SPLIT``
>>>>>> +offload and the ``split_hdr_size`` field in structure
>>>>>> +``rte_eth_rxmode`` to enable header split offload are not
>>>>>> +supported in any
>>>>> PMDs. They will be removed in DPDK 22.11.
>>>>>
>>>>> It would have been good to talk about rte_eth_rxseg_split which is
>>>>> similar and configured per-queue.
>>>>
>>>> Thanks for your suggestion.
>>>>
>>>> But I'm a little confused, are you referring that I need to involve protocol
>>> based buffer split?
>>>> About the deprecation of header split, I haven't realized its connection to
>>> rte_eth_rxseg_split.
>>>
>>> What???
>>> In old versions of your patch "ethdev: introduce protocol type based header
>>> split"
>>> you wrote:
>>> "
>>> A new proto field is introduced in the
>>> rte_eth_rxseg_split structure reserved field to specify header protocol type.
>>> With Rx offload flag RTE_ETH_RX_OFFLOAD_HEADER_SPLIT enabled and
>>> protocol type configured, PMD will split the ingress packets into two separate
>>> regions.
>>> "
>>
>> It has a long history...
>> It was corrected in v4 that RTE_ETH_RX_OFFLOAD_HEADER_SPLIT is used to enable header
>> split offload with the header size controlled using "split_hdr_size".
>> But no single PMD actually supports RTE_ETH_RX_OFFLOAD_HEADER_SPLIT for this purpose.
>> So we finally decide to deprecate this flag.
>>
>> http://patchwork.dpdk.org/project/dpdk/patch/20220402104109.472078-2-wenxuanx.wu@intel.com/
>>
>> In following series, I use RTE_ETH_RX_OFFLOAD_BUFFER_SPLIT instead. It is for multi-segments packet
>> split. And it still needs a "proto_hdr" field in rte_eth_rxmode to configure split location.
> 
> I know this history because I was the one asking you to deprecate this.
> But it seems you didn't get the big picture.
> 
>>>> Currently there are 2 acks, add more PMD maintainers to help review
>>>> this deprecation notice for header split, thanks a lot!
>>>
>>> I cannot say my feeling strong enough.
>>
>> So IMO the deprecation for header split is not relevant with buffer split. But we can still clean the code.
>> Hope it make things clearer.
> 
> They are almost the same features.
> So when deprecating one, it is important to mention what remains.
> If needed RTE_ETH_RX_OFFLOAD_BUFFER_SPLIT can still be used
> and it is configured per-queue,
> while RTE_ETH_RX_OFFLOAD_HEADER_SPLIT was configurable per-port.
> 
> Andrew, Ferruh, do you agree to improve this deprecation notice
> by adding above information?

+1 tt is definitely a very good idea.