Skip to contentSkip to conversation

doc: deprecate using MAX values as array size

PATCH Applied Ferruh Yigit 5 participants 7 messages Jan 30, 2020 – Feb 25, 2020

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 doc: deprecate using MAX values as array size

Adding the deprecation notice as reminder for next ABI breakage release (20.11).
This one time breakage is required to be able to extend enum/define without breaking ABI.

---
 doc/guides/rel_notes/deprecation.rst | 14 ++++++++++++++
 1 file changed, 14 insertions(+)
doc/guides/rel_notes/deprecation.rst +14 -0
index dfcca87ab..99d81564a 100644
@@ -38,6 +38,20 @@ Deprecation Notices
   remove it from the externally visible ABI and allow it to be updated in the
   future.
 
+* lib: will fix extending some enum/define breaking the ABI. There are multiple
+  samples in DPDK that enum/define terminated with a ``.*MAX.*`` value which is
+  used by iterators, and arrays holding these values are sized with this
+  ``.*MAX.*`` value. So extending this enum/define increases the ``.*MAX.*``
+  value which increases the size of the array and depending on how/where the
+  array is used this may break the ABI.
+  ``RTE_ETH_FLOW_MAX`` is one sample of the mentioned case, adding a new flow
+  type will break the ABI because of ``flex_mask[RTE_ETH_FLOW_MAX]`` array
+  usage in following public struct hierarchy:
+  ``rte_eth_fdir_flex_conf -> rte_fdir_conf -> rte_eth_conf (in the middle)``.
+  Need to identify this kind of usages and fix in 20.11, otherwise this blocks
+  us extending existing enum/define.
+  One solution can be using a fixed size array instead of ``.*MAX.*`` value.
+
 * dpaa2: removal of ``rte_dpaa2_memsegs`` structure which has been replaced
   by a pa-va search library. This structure was earlier being used for holding
   memory segments used by dpaa2 driver for faster pa->va translation. This
Signature · 1 line
2.24.1
#1 lore raw
Quoted 26 lines · Ferruh Yigit

Adding the deprecation notice as reminder for next ABI breakage release (20.11).
This one time breakage is required to be able to extend enum/define without breaking ABI.

---
 doc/guides/rel_notes/deprecation.rst | 14 ++++++++++++++
 1 file changed, 14 insertions(+)
doc/guides/rel_notes/deprecation.rst +7 -0
index dfcca87ab..99d81564a 100644
@@ -38,6 +38,20 @@ Deprecation Notices
   remove it from the externally visible ABI and allow it to be updated in the
   future.
 
+* lib: will fix extending some enum/define breaking the ABI. There are multiple
+  samples in DPDK that enum/define terminated with a ``.*MAX.*`` value which is
+  used by iterators, and arrays holding these values are sized with this
+  ``.*MAX.*`` value. So extending this enum/define increases the ``.*MAX.*``
+  value which increases the size of the array and depending on how/where the
+  array is used this may break the ABI.
+  ``RTE_ETH_FLOW_MAX`` is one sample of the mentioned case, adding a new flow

doc/guides/rel_notes/deprecation.rst Deprecation Notices · line 57

Quoted 10 lines
doc/guides/rel_notes/deprecation.rst +7 -0
+  type will break the ABI because of ``flex_mask[RTE_ETH_FLOW_MAX]`` array
+  usage in following public struct hierarchy:
+  ``rte_eth_fdir_flex_conf -> rte_fdir_conf -> rte_eth_conf (in the middle)``.
+  Need to identify this kind of usages and fix in 20.11, otherwise this blocks
+  us extending existing enum/define.
+  One solution can be using a fixed size array instead of ``.*MAX.*`` value.
+
 * dpaa2: removal of ``rte_dpaa2_memsegs`` structure which has been replaced
   by a pa-va search library. This structure was earlier being used for holding
   memory segments used by dpaa2 driver for faster pa->va translation. This

Reminder of this deprecation notice.

Acked-by
#2 lore raw
Quoted 34 lines · Ferruh Yigit

Review

Quoted 11 lines

Adding the deprecation notice as reminder for next ABI breakage release (20.11).
This one time breakage is required to be able to extend enum/define without breaking ABI.

---
 doc/guides/rel_notes/deprecation.rst | 14 ++++++++++++++
 1 file changed, 14 insertions(+)
(quoted diff) +0 -0

b/doc/guides/rel_notes/deprecation.rst

doc/guides/rel_notes/deprecation.rst Deprecation Notices · line 41

Quoted 8 lines

index dfcca87ab..99d81564a 100644

doc/guides/rel_notes/deprecation.rst +1 -0
@@ -38,6 +38,20 @@ Deprecation Notices
   remove it from the externally visible ABI and allow it to be updated in the
   future.
 
+* lib: will fix extending some enum/define breaking the ABI. There are

multiple

doc/guides/rel_notes/deprecation.rst Deprecation Notices · line 42

Quoted 1 line
doc/guides/rel_notes/deprecation.rst +1 -0
+  samples in DPDK that enum/define terminated with a ``.*MAX.*`` value

which is

doc/guides/rel_notes/deprecation.rst Deprecation Notices

Quoted 5 lines
doc/guides/rel_notes/deprecation.rst +5 -0
+  used by iterators, and arrays holding these values are sized with this
+  ``.*MAX.*`` value. So extending this enum/define increases the ``.*MAX.*``
+  value which increases the size of the array and depending on how/where the
+  array is used this may break the ABI.
+  ``RTE_ETH_FLOW_MAX`` is one sample of the mentioned case, adding a

new flow

doc/guides/rel_notes/deprecation.rst Deprecation Notices · line 48

Quoted 1 line
doc/guides/rel_notes/deprecation.rst +1 -0
+  type will break the ABI because of ``flex_mask[RTE_ETH_FLOW_MAX]``

array

Quoted 12 lines

doc/guides/rel_notes/deprecation.rst Deprecation Notices

Quoted 7 lines
doc/guides/rel_notes/deprecation.rst +6 -0
+  usage in following public struct hierarchy:
+  ``rte_eth_fdir_flex_conf -> rte_fdir_conf -> rte_eth_conf (in the middle)``.
+  Need to identify this kind of usages and fix in 20.11, otherwise this blocks
+  us extending existing enum/define.
+  One solution can be using a fixed size array instead of ``.*MAX.*`` value.
+
 * dpaa2: removal of ``rte_dpaa2_memsegs`` structure which has been

replaced

Quoted 3 lines
doc/guides/rel_notes/deprecation.rst +0 -0
   by a pa-va search library. This structure was earlier being used for holding
   memory segments used by dpaa2 driver for faster pa->va translation. This

We admit that the issue is there and we can discuss the possible solutions for this issue.

For the deprecation notice.

#3 lore raw
Quoted 25 lines
Quoted 11 lines
Quoted 8 lines

Adding the deprecation notice as reminder for next ABI breakage release (20.11).
This one time breakage is required to be able to extend enum/define without breaking ABI.

---
+* lib: will fix extending some enum/define breaking the ABI. There are

multiple

Quoted 1 line

+ samples in DPDK that enum/define terminated with a ``.*MAX.*`` value

which is

Quoted 14 lines

doc/guides/rel_notes/deprecation.rst Deprecation Notices

Quoted 5 lines
doc/guides/rel_notes/deprecation.rst +5 -0
+  used by iterators, and arrays holding these values are sized with this
+  ``.*MAX.*`` value. So extending this enum/define increases the ``.*MAX.*``
+  value which increases the size of the array and depending on how/where the
+  array is used this may break the ABI.
+  ``RTE_ETH_FLOW_MAX`` is one sample of the mentioned case, adding a

new flow

Quoted 1 line

+ type will break the ABI because of ``flex_mask[RTE_ETH_FLOW_MAX]``

array

Quoted 5 lines
doc/guides/rel_notes/deprecation.rst +5 -0
+  usage in following public struct hierarchy:
+  ``rte_eth_fdir_flex_conf -> rte_fdir_conf -> rte_eth_conf (in the middle)``.
+  Need to identify this kind of usages and fix in 20.11, otherwise this blocks
+  us extending existing enum/define.
+  One solution can be using a fixed size array instead of ``.*MAX.*`` value.
Quoted 4 lines

We admit that the issue is there and we can discuss the possible solutions for this issue.

For the deprecation notice.

I think we'll need a new coding style guideline to avoid shuch issue in future. Anyway, about fixing the issue in 20.11,

#4 lore raw
In reply to Ferruh Yigit
Quoted 30 lines · Ferruh Yigit
Quoted 29 lines · Ferruh Yigit

Adding the deprecation notice as reminder for next ABI breakage release (20.11).
This one time breakage is required to be able to extend enum/define without breaking ABI.

---
 doc/guides/rel_notes/deprecation.rst | 14 ++++++++++++++
 1 file changed, 14 insertions(+)
doc/guides/rel_notes/deprecation.rst +11 -0
index dfcca87ab..99d81564a 100644
@@ -38,6 +38,20 @@ Deprecation Notices
   remove it from the externally visible ABI and allow it to be updated in the
   future.
 
+* lib: will fix extending some enum/define breaking the ABI. There are multiple
+  samples in DPDK that enum/define terminated with a ``.*MAX.*`` value which is
+  used by iterators, and arrays holding these values are sized with this
+  ``.*MAX.*`` value. So extending this enum/define increases the ``.*MAX.*``
+  value which increases the size of the array and depending on how/where the
+  array is used this may break the ABI.
+  ``RTE_ETH_FLOW_MAX`` is one sample of the mentioned case, adding a new flow
+  type will break the ABI because of ``flex_mask[RTE_ETH_FLOW_MAX]`` array
+  usage in following public struct hierarchy:
+  ``rte_eth_fdir_flex_conf -> rte_fdir_conf -> rte_eth_conf (in the middle)``.
+  Need to identify this kind of usages and fix in 20.11, otherwise this blocks
Quoted 8 lines

doc/guides/rel_notes/deprecation.rst Deprecation Notices · line 57

Quoted 7 lines
doc/guides/rel_notes/deprecation.rst +3 -0
+  us extending existing enum/define.
+  One solution can be using a fixed size array instead of ``.*MAX.*`` value.
+
 * dpaa2: removal of ``rte_dpaa2_memsegs`` structure which has been replaced
   by a pa-va search library. This structure was earlier being used for holding
   memory segments used by dpaa2 driver for faster pa->va translation. This

Reminder of this deprecation notice.

Acked-by on v1 1/1
#5 lore raw
In reply to Ferruh Yigit
Quoted 36 lines · Ferruh Yigit

Adding the deprecation notice as reminder for next ABI breakage release (20.11).
This one time breakage is required to be able to extend enum/define without breaking ABI.

---
 doc/guides/rel_notes/deprecation.rst | 14 ++++++++++++++
 1 file changed, 14 insertions(+)
doc/guides/rel_notes/deprecation.rst +14 -1
index dfcca87ab..99d81564a 100644
@@ -38,6 +38,20 @@ Deprecation Notices
   remove it from the externally visible ABI and allow it to be updated in the
   future.
 
+* lib: will fix extending some enum/define breaking the ABI. There are multiple
+  samples in DPDK that enum/define terminated with a ``.*MAX.*`` value which is
+  used by iterators, and arrays holding these values are sized with this
+  ``.*MAX.*`` value. So extending this enum/define increases the ``.*MAX.*``
+  value which increases the size of the array and depending on how/where the
+  array is used this may break the ABI.
+  ``RTE_ETH_FLOW_MAX`` is one sample of the mentioned case, adding a new flow
+  type will break the ABI because of ``flex_mask[RTE_ETH_FLOW_MAX]`` array
+  usage in following public struct hierarchy:
+  ``rte_eth_fdir_flex_conf -> rte_fdir_conf -> rte_eth_conf (in the middle)``.
+  Need to identify this kind of usages and fix in 20.11, otherwise this blocks
+  us extending existing enum/define.
+  One solution can be using a fixed size array instead of ``.*MAX.*`` value.
+
 * dpaa2: removal of ``rte_dpaa2_memsegs`` structure which has been replaced
   by a pa-va search library. This structure was earlier being used for holding
   memory segments used by dpaa2 driver for faster pa->va translation. This
--
Quoted 2 lines

2.24.1

--
David Marchand

Acked-by Akhil Goyal Acked-by Andrew Rybchenko Acked-by Thomas Monjalon Acked-by on v1 1/1 Applied
#6 lore raw
In reply to Ferruh Yigit
Quoted 6 lines · Ferruh Yigit

Adding the deprecation notice as reminder for next ABI breakage release (20.11).
This one time breakage is required to be able to extend enum/define without breaking ABI.

Applied, thanks.

Signature · 1 line
David Marchand