[PATCH] doc/mlx5: document firmware requirement for flex item

[PATCH] doc/mlx5: document firmware requirement for flex item

[Khadem Ullah]

Some BlueField firmware versions (e.g. 24.30.1004) do not support flex item
definitions using FIELD_MODE_FIXED with size set to 0, such as in 'next_header'.
Attempting to use this configuration may result in the following error:

  'unsupported header length field mode (FIXED)'

This is resolved starting from firmware version 24.38.1002.

The patch adds a note to the mlx5 guide explaining the firmware requirement
for such flex item configurations.

Fixes: 16508bfd0816 ('net/mlx5: doc: add flex item specifications in mlx5 guide')
Cc: stable@dpdk.org
Signed-off-by: Khadem Ullah <14pwcse1224@uetpeshawar.edu.pk>
---
 doc/guides/nics/mlx5.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/doc/guides/nics/mlx5.rst b/doc/guides/nics/mlx5.rst
index c3a350d24e..1b0e3efc41 100644
--- a/doc/guides/nics/mlx5.rst
+++ b/doc/guides/nics/mlx5.rst
@@ -476,6 +476,10 @@ Limitations
   - In flex item configuration, ``next_header.field_base`` value
     must be byte aligned (multiple of 8).
   - Modify field with flex item, the offset must be byte aligned (multiple of 8).
+    .. note::
+     Some firmware versions (e.g. 24.30.1004) do not support
+     ``next_header`` with ``field_mode = FIELD_MODE_FIXED`` and zero size.
+     A newer firmware (e.g. >= 24.38.1002) is required to support this configuration.
 
 - Match on random value:
 
-- 
2.43.0

Re: [PATCH] doc/mlx5: document firmware requirement for flex item

[Dariusz Sosnowski]

+ mlx5 maintainers

On Tue, Jul 08, 2025 at 07:49:21AM -0400, Khadem Ullah wrote:
> Some BlueField firmware versions (e.g. 24.30.1004) do not support flex item
> definitions using FIELD_MODE_FIXED with size set to 0, such as in 'next_header'.
> Attempting to use this configuration may result in the following error:
> 
>   'unsupported header length field mode (FIXED)'
> 
> This is resolved starting from firmware version 24.38.1002.

Could you please share the DPDK version you used and
a code sample with flex item configuration?

I checked internally and I see no change which would trigger
a change in behavior regarding 'unsupported header length field mode (FIXED)' error message.

> 
> The patch adds a note to the mlx5 guide explaining the firmware requirement
> for such flex item configurations.
> 
> Fixes: 16508bfd0816 ('net/mlx5: doc: add flex item specifications in mlx5 guide')
> Cc: stable@dpdk.org
> Signed-off-by: Khadem Ullah <14pwcse1224@uetpeshawar.edu.pk>
> ---
>  doc/guides/nics/mlx5.rst | 4 ++++
>  1 file changed, 4 insertions(+)
> 
> diff --git a/doc/guides/nics/mlx5.rst b/doc/guides/nics/mlx5.rst
> index c3a350d24e..1b0e3efc41 100644
> --- a/doc/guides/nics/mlx5.rst
> +++ b/doc/guides/nics/mlx5.rst
> @@ -476,6 +476,10 @@ Limitations
>    - In flex item configuration, ``next_header.field_base`` value
>      must be byte aligned (multiple of 8).
>    - Modify field with flex item, the offset must be byte aligned (multiple of 8).
> +    .. note::
> +     Some firmware versions (e.g. 24.30.1004) do not support
> +     ``next_header`` with ``field_mode = FIELD_MODE_FIXED`` and zero size.
> +     A newer firmware (e.g. >= 24.38.1002) is required to support this configuration.
>  
>  - Match on random value:
>  
> -- 
> 2.43.0
> 

Best regards,
Dariusz Sosnowski

Re: [PATCH] doc/mlx5: document firmware requirement for flex item

[Khadem Ullah]

Hi Dariusz,

Thanks for the follow-up.

I was using DPDK v23.11 with the following flex item configuration:

{
  "next_header": { "field_mode": "FIELD_MODE_FIXED", "field_size": 0, "field_base": 0 },
  "next_protocol": { "field_mode": "FIELD_MODE_FIXED", "field_size": 8, "field_base": 72 },
  "sample_data": [
    { "field_mode": "FIELD_MODE_FIXED", "field_size": 32, "field_base": 0 },
    { "field_mode": "FIELD_MODE_FIXED", "field_size": 32, "field_base": 32 },
    { "field_mode": "FIELD_MODE_FIXED", "field_size": 32, "field_base": 64 },
    { "field_mode": "FIELD_MODE_FIXED", "field_size": 32, "field_base": 96 }
  ],
  "input_link": [
    { "item": "eth type is 0x08802" }
  ],
  "output_link": [
    { "item": "udp", "next": 17 },
    { "item": "tcp", "next": 6 }
  ]
}

With firmware version 24.30.1004 (MT_0000000704), the following error was produced:

  port-0: flex item #3 creation failed: unsupported header length field mode (FIXED)

After upgrading to firmware version 24.38.1002, the same configuration succeeded.

Example flow after upgrade:

  testpmd> flow flex_item pattern 2 spec 45000000000000000000000001020304 mask FF0000000000000000000000FFFFFFFF
  created pattern #2

  testpmd> flow create 0 ingress pattern eth / ipv4 / udp / flex item is 3 pattern is 2 / end actions mark id 1 / queue index 0 / end
  Flow rule #0 created

It appears this issue was resolved at the firmware level.

Best regards,  
Khadem Ullah

Re: [PATCH] doc/mlx5: document firmware requirement for flex item

[Dariusz Sosnowski]

On Wed, Jul 16, 2025 at 03:49:40AM -0400, Khadem Ullah wrote:
> Hi Dariusz,
> 
> Thanks for the follow-up.
> 
> I was using DPDK v23.11 with the following flex item configuration:
> 
> {
>   "next_header": { "field_mode": "FIELD_MODE_FIXED", "field_size": 0, "field_base": 0 },
>   "next_protocol": { "field_mode": "FIELD_MODE_FIXED", "field_size": 8, "field_base": 72 },
>   "sample_data": [
>     { "field_mode": "FIELD_MODE_FIXED", "field_size": 32, "field_base": 0 },
>     { "field_mode": "FIELD_MODE_FIXED", "field_size": 32, "field_base": 32 },
>     { "field_mode": "FIELD_MODE_FIXED", "field_size": 32, "field_base": 64 },
>     { "field_mode": "FIELD_MODE_FIXED", "field_size": 32, "field_base": 96 }
>   ],
>   "input_link": [
>     { "item": "eth type is 0x08802" }
>   ],
>   "output_link": [
>     { "item": "udp", "next": 17 },
>     { "item": "tcp", "next": 6 }
>   ]
> }
> 
> With firmware version 24.30.1004 (MT_0000000704), the following error was produced:
> 
>   port-0: flex item #3 creation failed: unsupported header length field mode (FIXED)

Thank you for providing the flex item configuration.

Could you share what exactly are you trying to achieve with this
flex item configuration?

We investigated locally and yes, FW version 24.30.1004 does not fully support flex item yet.
The error log misreports the actual root cause of the error,
because of a bug in PMD. We'll provide a separate fix for that.

The proposed documentation change would also be inaccurate, because different
flex item capabilities were added in different FW versions.
We will update the documentation with more details regarding that
in the same fix.
The earliest version where this specific flex item configuration works
should be 24.37.1300. However I would advise to use
at least FW version 24.39.xxxx versions (this is the oldest relevant LTS FW).

> 
> After upgrading to firmware version 24.38.1002, the same configuration succeeded.
> 
> Example flow after upgrade:
> 
>   testpmd> flow flex_item pattern 2 spec 45000000000000000000000001020304 mask FF0000000000000000000000FFFFFFFF
>   created pattern #2
> 
>   testpmd> flow create 0 ingress pattern eth / ipv4 / udp / flex item is 3 pattern is 2 / end actions mark id 1 / queue index 0 / end
>   Flow rule #0 created
> 
> It appears this issue was resolved at the firmware level.
> 
> Best regards,  
> Khadem Ullah
>