[RFC] cryptodev: replace LIST_END enumerators with APIs
Checks
Commit Message
Replace *_LIST_END enumerators from asymmetric crypto
lib to avoid ABI breakage for every new addition in
enums with inline APIs.
Signed-off-by: Akhil Goyal <gakhil@marvell.com>
---
This patch was discussed in ML long time back.
https://patches.dpdk.org/project/dpdk/patch/20211008204516.3497060-1-gakhil@marvell.com/
Now added inline APIs for getting the list end which need to be updated
for each new entry to the enum. This shall help in avoiding ABI break
for adding new algo.
app/test/test_cryptodev_asym.c | 2 +-
lib/cryptodev/rte_crypto_asym.h | 18 ++++++++++++++----
2 files changed, 15 insertions(+), 5 deletions(-)
Comments
> +++ b/app/test/test_cryptodev_asym.c
> @@ -581,7 +581,7 @@ static inline void print_asym_capa(
> rte_cryptodev_asym_get_xform_string(capa->xform_type));
> printf("operation supported -");
>
> - for (i = 0; i < RTE_CRYPTO_ASYM_OP_LIST_END; i++) {
> + for (i = 0; i < rte_crypto_asym_op_list_end(); i++) {
> +++ b/lib/cryptodev/rte_crypto_asym.h
> +static inline int
> +rte_crypto_asym_xform_type_list_end(void)
> +{
> + return RTE_CRYPTO_ASYM_XFORM_SM2 + 1;
> +}
> +
> /**
> * Asymmetric crypto operation type variants
> + * Note: Update rte_crypto_asym_op_list_end for every new type added.
> */
> enum rte_crypto_asym_op_type {
> RTE_CRYPTO_ASYM_OP_ENCRYPT,
> @@ -135,9 +141,14 @@ enum rte_crypto_asym_op_type {
> /**< Signature Generation operation */
> RTE_CRYPTO_ASYM_OP_VERIFY,
> /**< Signature Verification operation */
> - RTE_CRYPTO_ASYM_OP_LIST_END
> };
>
> +static inline int
> +rte_crypto_asym_op_list_end(void)
> +{
> + return RTE_CRYPTO_ASYM_OP_VERIFY + 1;
> +}
I like the concept of replacing an "last enum value" with a "last enum function" for API/ABI compatibility purposes.
Here's an idea...
We can introduce a generic design pattern where we keep the _LIST_END enum value at the end, somehow marking it private (and not part of the API/ABI), and move the _list_end() function inside the C file, so it uses the _LIST_END enum value that the library was built with. E.g. like this:
In the header file:
enum rte_crypto_asym_op_type {
RTE_CRYPTO_ASYM_OP_VERIFY,
/**< Signature Verification operation */
#if RTE_BUILDING_INTERNAL
__RTE_CRYPTO_ASYM_OP_LIST_END /* internal */
#endif
}
int rte_crypto_asym_op_list_end(void);
And in the associated library code file, when including rte_crypto_asym.h:
#define RTE_BUILDING_INTERNAL
#include <cryptodev/rte_crypto_asym.h>
int
rte_crypto_asym_op_list_end(void)
{
return __RTE_CRYPTO_ASYM_OP_LIST_END;
}
> -----Original Message-----
> From: Morten Brørup <mb@smartsharesystems.com>
> Sent: Thursday, September 5, 2024 5:09 PM
> To: Akhil Goyal <gakhil@marvell.com>; dev@dpdk.org
> Cc: thomas@monjalon.net; Marchand, David <david.marchand@redhat.com>;
> hemant.agrawal@nxp.com; anoobj@marvell.com; De Lara Guarch, Pablo
> <pablo.de.lara.guarch@intel.com>; Trahe, Fiona <fiona.trahe@intel.com>;
> Doherty, Declan <declan.doherty@intel.com>; matan@nvidia.com;
> g.singh@nxp.com; fanzhang.oss@gmail.com; jianjay.zhou@huawei.com;
> asomalap@amd.com; ruifeng.wang@arm.com;
> konstantin.v.ananyev@yandex.ru; Nicolau, Radu <radu.nicolau@intel.com>;
> ajit.khaparde@broadcom.com; rnagadheeraj@marvell.com; mdr@ashroe.eu
> Subject: RE: [PATCH] [RFC] cryptodev: replace LIST_END enumerators with APIs
>
> > +++ b/app/test/test_cryptodev_asym.c
> > @@ -581,7 +581,7 @@ static inline void print_asym_capa(
> > rte_cryptodev_asym_get_xform_string(capa-
> >xform_type));
> > printf("operation supported -");
> >
> > - for (i = 0; i < RTE_CRYPTO_ASYM_OP_LIST_END; i++) {
> > + for (i = 0; i < rte_crypto_asym_op_list_end(); i++) {
>
> > +++ b/lib/cryptodev/rte_crypto_asym.h
> > +static inline int
> > +rte_crypto_asym_xform_type_list_end(void)
> > +{
> > + return RTE_CRYPTO_ASYM_XFORM_SM2 + 1; }
> > +
> > /**
> > * Asymmetric crypto operation type variants
> > + * Note: Update rte_crypto_asym_op_list_end for every new type added.
> > */
> > enum rte_crypto_asym_op_type {
> > RTE_CRYPTO_ASYM_OP_ENCRYPT,
> > @@ -135,9 +141,14 @@ enum rte_crypto_asym_op_type {
> > /**< Signature Generation operation */
> > RTE_CRYPTO_ASYM_OP_VERIFY,
> > /**< Signature Verification operation */
> > - RTE_CRYPTO_ASYM_OP_LIST_END
> > };
> >
> > +static inline int
> > +rte_crypto_asym_op_list_end(void)
> > +{
> > + return RTE_CRYPTO_ASYM_OP_VERIFY + 1; }
>
> I like the concept of replacing an "last enum value" with a "last enum function"
> for API/ABI compatibility purposes.
>
> Here's an idea...
>
> We can introduce a generic design pattern where we keep the _LIST_END enum
> value at the end, somehow marking it private (and not part of the API/ABI), and
> move the _list_end() function inside the C file, so it uses the _LIST_END enum
> value that the library was built with. E.g. like this:
>
Why asym crypto API does need these ENDs at all? Will any PMD or the user ever or use it? Sym crypto does not have this at all, as well as rte_crypto_asym_ke_type in asym crypto.
>
> In the header file:
>
> enum rte_crypto_asym_op_type {
> RTE_CRYPTO_ASYM_OP_VERIFY,
> /**< Signature Verification operation */ #if RTE_BUILDING_INTERNAL
> __RTE_CRYPTO_ASYM_OP_LIST_END /* internal */ #endif }
>
> int rte_crypto_asym_op_list_end(void);
>
>
> And in the associated library code file, when including rte_crypto_asym.h:
>
> #define RTE_BUILDING_INTERNAL
> #include <cryptodev/rte_crypto_asym.h>
>
> int
> rte_crypto_asym_op_list_end(void)
> {
> return __RTE_CRYPTO_ASYM_OP_LIST_END;
> }
On 2024/9/5 23:09, Morten Brørup wrote:
>> +++ b/app/test/test_cryptodev_asym.c
>> @@ -581,7 +581,7 @@ static inline void print_asym_capa(
>> rte_cryptodev_asym_get_xform_string(capa->xform_type));
>> printf("operation supported -");
>>
>> - for (i = 0; i < RTE_CRYPTO_ASYM_OP_LIST_END; i++) {
>> + for (i = 0; i < rte_crypto_asym_op_list_end(); i++) {
>
>> +++ b/lib/cryptodev/rte_crypto_asym.h
>> +static inline int
>> +rte_crypto_asym_xform_type_list_end(void)
>> +{
>> + return RTE_CRYPTO_ASYM_XFORM_SM2 + 1;
>> +}
>> +
>> /**
>> * Asymmetric crypto operation type variants
>> + * Note: Update rte_crypto_asym_op_list_end for every new type added.
>> */
>> enum rte_crypto_asym_op_type {
>> RTE_CRYPTO_ASYM_OP_ENCRYPT,
>> @@ -135,9 +141,14 @@ enum rte_crypto_asym_op_type {
>> /**< Signature Generation operation */
>> RTE_CRYPTO_ASYM_OP_VERIFY,
>> /**< Signature Verification operation */
>> - RTE_CRYPTO_ASYM_OP_LIST_END
>> };
>>
>> +static inline int
>> +rte_crypto_asym_op_list_end(void)
>> +{
>> + return RTE_CRYPTO_ASYM_OP_VERIFY + 1;
>> +}
>
> I like the concept of replacing an "last enum value" with a "last enum function" for API/ABI compatibility purposes.
+1
There are many such define in DPDK, e.g. RTE_ETH_EVENT_MAX
>
> Here's an idea...
>
> We can introduce a generic design pattern where we keep the _LIST_END enum value at the end, somehow marking it private (and not part of the API/ABI), and move the _list_end() function inside the C file, so it uses the _LIST_END enum value that the library was built with. E.g. like this:
>
>
> In the header file:
>
> enum rte_crypto_asym_op_type {
> RTE_CRYPTO_ASYM_OP_VERIFY,
> /**< Signature Verification operation */
> #if RTE_BUILDING_INTERNAL
> __RTE_CRYPTO_ASYM_OP_LIST_END /* internal */
> #endif
> }
>
> int rte_crypto_asym_op_list_end(void);
>
>
> And in the associated library code file, when including rte_crypto_asym.h:
>
> #define RTE_BUILDING_INTERNAL
> #include <cryptodev/rte_crypto_asym.h>
>
> int
> rte_crypto_asym_op_list_end(void)
> {
> return __RTE_CRYPTO_ASYM_OP_LIST_END;
> }
It's more generic, and also keep LIST_END in the define, we just add new enum before it.
But based on my understanding of ABI compatibility, from the point view of application,
this API should return old-value even with the new library, but it will return new-value
with new library. It could also break ABI.
So this API should force inline, just as this patch did. But it seem can't work if move
this API to header file and add static inline.
>
> .
>
> >
> > Here's an idea...
> >
> > We can introduce a generic design pattern where we keep the _LIST_END enum
> value at the end, somehow marking it private (and not part of the API/ABI), and
> move the _list_end() function inside the C file, so it uses the _LIST_END enum
> value that the library was built with. E.g. like this:
> >
> >
> > In the header file:
> >
> > enum rte_crypto_asym_op_type {
> > RTE_CRYPTO_ASYM_OP_VERIFY,
> > /**< Signature Verification operation */
> > #if RTE_BUILDING_INTERNAL
> > __RTE_CRYPTO_ASYM_OP_LIST_END /* internal */
> > #endif
> > }
> >
> > int rte_crypto_asym_op_list_end(void);
> >
> >
> > And in the associated library code file, when including rte_crypto_asym.h:
> >
> > #define RTE_BUILDING_INTERNAL
> > #include <cryptodev/rte_crypto_asym.h>
> >
> > int
> > rte_crypto_asym_op_list_end(void)
> > {
> > return __RTE_CRYPTO_ASYM_OP_LIST_END;
> > }
>
> It's more generic, and also keep LIST_END in the define, we just add new enum
> before it.
> But based on my understanding of ABI compatibility, from the point view of
> application,
> this API should return old-value even with the new library, but it will return new-
> value
> with new library. It could also break ABI.
>
> So this API should force inline, just as this patch did. But it seem can't work if
> move
> this API to header file and add static inline.
>
Yes, moving to c file does not seem to solve the purpose.
So should we move with the way the patch is submitted or we have some other suggestion?
Regards,
Akhil
> From: fengchengwen [mailto:fengchengwen@huawei.com]
> Sent: Friday, 6 September 2024 08.33
>
> On 2024/9/5 23:09, Morten Brørup wrote:
> >> +++ b/app/test/test_cryptodev_asym.c
> >> @@ -581,7 +581,7 @@ static inline void print_asym_capa(
> >> rte_cryptodev_asym_get_xform_string(capa->xform_type));
> >> printf("operation supported -");
> >>
> >> - for (i = 0; i < RTE_CRYPTO_ASYM_OP_LIST_END; i++) {
> >> + for (i = 0; i < rte_crypto_asym_op_list_end(); i++) {
> >
> >> +++ b/lib/cryptodev/rte_crypto_asym.h
> >> +static inline int
> >> +rte_crypto_asym_xform_type_list_end(void)
> >> +{
> >> + return RTE_CRYPTO_ASYM_XFORM_SM2 + 1;
> >> +}
> >> +
> >> /**
> >> * Asymmetric crypto operation type variants
> >> + * Note: Update rte_crypto_asym_op_list_end for every new type added.
> >> */
> >> enum rte_crypto_asym_op_type {
> >> RTE_CRYPTO_ASYM_OP_ENCRYPT,
> >> @@ -135,9 +141,14 @@ enum rte_crypto_asym_op_type {
> >> /**< Signature Generation operation */
> >> RTE_CRYPTO_ASYM_OP_VERIFY,
> >> /**< Signature Verification operation */
> >> - RTE_CRYPTO_ASYM_OP_LIST_END
> >> };
> >>
> >> +static inline int
> >> +rte_crypto_asym_op_list_end(void)
> >> +{
> >> + return RTE_CRYPTO_ASYM_OP_VERIFY + 1;
> >> +}
> >
> > I like the concept of replacing an "last enum value" with a "last enum
> function" for API/ABI compatibility purposes.
>
> +1
> There are many such define in DPDK, e.g. RTE_ETH_EVENT_MAX
>
> >
> > Here's an idea...
> >
> > We can introduce a generic design pattern where we keep the _LIST_END enum
> value at the end, somehow marking it private (and not part of the API/ABI),
> and move the _list_end() function inside the C file, so it uses the _LIST_END
> enum value that the library was built with. E.g. like this:
> >
> >
> > In the header file:
> >
> > enum rte_crypto_asym_op_type {
> > RTE_CRYPTO_ASYM_OP_VERIFY,
> > /**< Signature Verification operation */
> > #if RTE_BUILDING_INTERNAL
> > __RTE_CRYPTO_ASYM_OP_LIST_END /* internal */
> > #endif
> > }
> >
> > int rte_crypto_asym_op_list_end(void);
> >
> >
> > And in the associated library code file, when including rte_crypto_asym.h:
> >
> > #define RTE_BUILDING_INTERNAL
> > #include <cryptodev/rte_crypto_asym.h>
> >
> > int
> > rte_crypto_asym_op_list_end(void)
> > {
> > return __RTE_CRYPTO_ASYM_OP_LIST_END;
> > }
>
> It's more generic, and also keep LIST_END in the define, we just add new enum
> before it.
> But based on my understanding of ABI compatibility, from the point view of
> application,
> this API should return old-value even with the new library, but it will return
> new-value
> with new library. It could also break ABI.
>
> So this API should force inline, just as this patch did. But it seem can't
> work if move
> this API to header file and add static inline.
Maybe a combination, returning the lowest end of the two versions of the list, would work...
----------------------------------
Common header file (rte_common.h):
----------------------------------
/* Add at end of enum list in the header file. */
#define RTE_ENUM_LIST_END(name) \
_ # name # _ENUM_LIST_END /**< @internal */
/* Add somewhere in header file, preferably after the enum list. */
#define rte_declare_enum_list_end(name) \
/** @internal */ \
int _# name # _enum_list_end(void); \
\
static int name # _enum_list_end(void) \
{ \
static int cached = 0; \
\
if (likely(cached != 0)) \
return cached; \
\
return cached = RTE_MIN( \
RTE_ENUM_LIST_END(name), \
_ # name # _enum_list_end()); \
} \
\
int _# name # _enum_list_end(void)
/* Add in the library/driver implementation. */
#define rte_define_enum_list_end(name) \
int _# name # _enum_list_end(void) \
{ \
return RTE_ENUM_LIST_END(name); \
} \
\
int _# name # _enum_list_end(void)
--------------------
Library header file:
--------------------
enum rte_crypto_asym_op_type {
RTE_CRYPTO_ASYM_OP_VERIFY,
/**< Signature Verification operation */
RTE_ENUM_LIST_END(rte_crypto_asym_op)
}
rte_declare_enum_list_end(rte_crypto_asym_op);
---------------
Library C file:
---------------
rte_define_enum_list_end(rte_crypto_asym_op);
Hi Morten,
Apologies for delayed response.
> Maybe a combination, returning the lowest end of the two versions of the list,
> would work...
>
> ----------------------------------
> Common header file (rte_common.h):
> ----------------------------------
>
> /* Add at end of enum list in the header file. */
> #define RTE_ENUM_LIST_END(name) \
> _ # name # _ENUM_LIST_END /**< @internal */
>
> /* Add somewhere in header file, preferably after the enum list. */
> #define rte_declare_enum_list_end(name) \
> /** @internal */ \
> int _# name # _enum_list_end(void); \
> \
> static int name # _enum_list_end(void) \
> { \
> static int cached = 0; \
> \
> if (likely(cached != 0)) \
> return cached; \
> \
> return cached = RTE_MIN( \
> RTE_ENUM_LIST_END(name), \
> _ # name # _enum_list_end()); \
> } \
> \
> int _# name # _enum_list_end(void)
>
> /* Add in the library/driver implementation. */
> #define rte_define_enum_list_end(name) \
> int _# name # _enum_list_end(void) \
> { \
> return RTE_ENUM_LIST_END(name); \
> } \
> \
> int _# name # _enum_list_end(void)
>
> --------------------
> Library header file:
> --------------------
>
> enum rte_crypto_asym_op_type {
> RTE_CRYPTO_ASYM_OP_VERIFY,
> /**< Signature Verification operation */
> RTE_ENUM_LIST_END(rte_crypto_asym_op)
Will the ABI check be ok for adding anything in between
RTE_CRYPTO_ASYM_OP_VERIFY and RTE_ENUM_LIST_END(rte_crypto_asym_op)?
Don’t we need to add exception for that if we somehow make it internal by adding a comment only?
Library is actually not restricting the application to not use RTE_ENUM_LIST_END(rte_crypto_asym_op) directly.
Also we may need to expose the .c file internal function as experimental in version.map
> }
>
> rte_declare_enum_list_end(rte_crypto_asym_op);
>
> ---------------
> Library C file:
> ---------------
>
> rte_define_enum_list_end(rte_crypto_asym_op);
If we want to make it a generic thing in rte_common.h
Will the below change be ok?
----------------------------------
Common header file (rte_common.h):
----------------------------------
#define rte_define_enum_list_end(name, last_value) \
static inline int name ## _enum_list_end(void) \
{ \
return last_value + 1; \
}
----------------
Lib header file
----------------
//After the enum definition define the list end as below
rte_define_enum_list_end(rte_crypto_asym_op, RTE_CRYPTO_ASYM_OP_VERIFY);
And wherever list end is needed use rte_crypto_asym_op_enum_list_end()?
With this change, abi check will not complain for any new addition at the end of enum.
And we do not need to expose any internal API in version.map.
Hi Morten,
>
> Apologies for delayed response.
> > Maybe a combination, returning the lowest end of the two versions of the list,
> > would work...
> >
> > ----------------------------------
> > Common header file (rte_common.h):
> > ----------------------------------
> >
> > /* Add at end of enum list in the header file. */
> > #define RTE_ENUM_LIST_END(name) \
> > _ # name # _ENUM_LIST_END /**< @internal */
> >
> > /* Add somewhere in header file, preferably after the enum list. */
> > #define rte_declare_enum_list_end(name) \
> > /** @internal */ \
> > int _# name # _enum_list_end(void); \
> > \
> > static int name # _enum_list_end(void) \
> > { \
> > static int cached = 0; \
> > \
> > if (likely(cached != 0)) \
> > return cached; \
> > \
> > return cached = RTE_MIN( \
> > RTE_ENUM_LIST_END(name), \
> > _ # name # _enum_list_end()); \
> > } \
> > \
> > int _# name # _enum_list_end(void)
> >
> > /* Add in the library/driver implementation. */
> > #define rte_define_enum_list_end(name) \
> > int _# name # _enum_list_end(void) \
> > { \
> > return RTE_ENUM_LIST_END(name); \
> > } \
> > \
> > int _# name # _enum_list_end(void)
> >
> > --------------------
> > Library header file:
> > --------------------
> >
> > enum rte_crypto_asym_op_type {
> > RTE_CRYPTO_ASYM_OP_VERIFY,
> > /**< Signature Verification operation */
> > RTE_ENUM_LIST_END(rte_crypto_asym_op)
>
> Will the ABI check be ok for adding anything in between
> RTE_CRYPTO_ASYM_OP_VERIFY and
> RTE_ENUM_LIST_END(rte_crypto_asym_op)?
> Don’t we need to add exception for that if we somehow make it internal by
> adding a comment only?
> Library is actually not restricting the application to not use
> RTE_ENUM_LIST_END(rte_crypto_asym_op) directly.
>
> Also we may need to expose the .c file internal function as experimental in
> version.map
>
> > }
> >
> > rte_declare_enum_list_end(rte_crypto_asym_op);
> >
> > ---------------
> > Library C file:
> > ---------------
> >
> > rte_define_enum_list_end(rte_crypto_asym_op);
>
> If we want to make it a generic thing in rte_common.h
> Will the below change be ok?
> ----------------------------------
> Common header file (rte_common.h):
> ----------------------------------
> #define rte_define_enum_list_end(name, last_value) \
> static inline int name ## _enum_list_end(void) \
> { \
> return last_value + 1; \
> }
>
> ----------------
> Lib header file
> ----------------
> //After the enum definition define the list end as below
> rte_define_enum_list_end(rte_crypto_asym_op,
> RTE_CRYPTO_ASYM_OP_VERIFY);
>
>
> And wherever list end is needed use rte_crypto_asym_op_enum_list_end()?
>
> With this change, abi check will not complain for any new addition at the end of
> enum.
> And we do not need to expose any internal API in version.map.
>
Can we move forward with above suggestion?
On 9/5/2024 11:14 AM, Akhil Goyal wrote:
> Replace *_LIST_END enumerators from asymmetric crypto
> lib to avoid ABI breakage for every new addition in
> enums with inline APIs.
>
> Signed-off-by: Akhil Goyal <gakhil@marvell.com>
> ---
> This patch was discussed in ML long time back.
> https://patches.dpdk.org/project/dpdk/patch/20211008204516.3497060-1-gakhil@marvell.com/
> Now added inline APIs for getting the list end which need to be updated
> for each new entry to the enum. This shall help in avoiding ABI break
> for adding new algo.
>
Hi Akhil,
*I think* this hides the problem instead of fixing it, and this may be
partially because of the tooling (libabigail) limitation.
This patch prevents the libabigail warning, true, but it doesn't improve
anything from the application's perspective.
Before or after this patch, application knows a fixed value as END value.
Not all changes in the END (MAX) enum values cause ABI break, but tool
warns on all, that is why I think this may be tooling limitation [1].
(Just to stress, I am NOT talking about regular enum values change, I am
talking about only END (MAX) value changes caused by appending new enum
items.)
As far as I can see (please Dodji, David correct me if I am wrong) ABI
break only happens if application and library exchange enum values in
the API (directly or within a struct).
Exchanging enum values via API cause ABI issues because:
1. enum size is not fixed, it uses min storage size that can hold all
values, adding new enums may cause its size change and of course this
breaks ABI.
2. Library can send enum values that application doesn't know, this may
cause application behave undefined.
3. Application sending MAX value (or more) to API expects error, but
that may be a valid value in the new library and applications gets
unexpected result.
Let's assume above 1. happens, with this patch warning is prevented, but
ABI break still can occur.
One option can be not exchanging enums in APIs at all, this way changes
in the END (MAX) enum values are harmless. But I can see cryptodev does
this a lot.
When enum is exchanged in APIs, and if we want to be strict about the
ABI, safest option can be not appending to enums at all, and keeping END
(MAX) items can be a way to enable warnings for this.
More relaxed option is protect against only 1. since that is the real
ABI issue, 2 & 3 are more defensive programming, so as long as enum size
is not changed we may ignore the END (MAX) value change warnings.
[1] It would be better if tool gives END (MAX) enum value warnings only
if it is exchanged in an API, but not sure if this can be possible to
detect.
> app/test/test_cryptodev_asym.c | 2 +-
> lib/cryptodev/rte_crypto_asym.h | 18 ++++++++++++++----
> 2 files changed, 15 insertions(+), 5 deletions(-)
>
> diff --git a/app/test/test_cryptodev_asym.c b/app/test/test_cryptodev_asym.c
> index f0b5d38543..f1ece475b8 100644
> --- a/app/test/test_cryptodev_asym.c
> +++ b/app/test/test_cryptodev_asym.c
> @@ -581,7 +581,7 @@ static inline void print_asym_capa(
> rte_cryptodev_asym_get_xform_string(capa->xform_type));
> printf("operation supported -");
>
> - for (i = 0; i < RTE_CRYPTO_ASYM_OP_LIST_END; i++) {
> + for (i = 0; i < rte_crypto_asym_op_list_end(); i++) {
> /* check supported operations */
> if (rte_cryptodev_asym_xform_capability_check_optype(capa, i)) {
> if (capa->xform_type == RTE_CRYPTO_ASYM_XFORM_DH)
> diff --git a/lib/cryptodev/rte_crypto_asym.h b/lib/cryptodev/rte_crypto_asym.h
> index 39d3da3952..290b300f84 100644
> --- a/lib/cryptodev/rte_crypto_asym.h
> +++ b/lib/cryptodev/rte_crypto_asym.h
> @@ -72,6 +72,7 @@ enum rte_crypto_curve_id {
> * Asymmetric crypto transformation types.
> * Each xform type maps to one asymmetric algorithm
> * performing specific operation
> + * Note: Update rte_crypto_asym_xform_type_list_end() for every new type added.
> */
> enum rte_crypto_asym_xform_type {
> RTE_CRYPTO_ASYM_XFORM_UNSPECIFIED = 0,
> @@ -119,12 +120,17 @@ enum rte_crypto_asym_xform_type {
> * Performs Encrypt, Decrypt, Sign and Verify.
> * Refer to rte_crypto_asym_op_type.
> */
> - RTE_CRYPTO_ASYM_XFORM_TYPE_LIST_END
> - /**< End of list */
> };
>
> +static inline int
> +rte_crypto_asym_xform_type_list_end(void)
> +{
> + return RTE_CRYPTO_ASYM_XFORM_SM2 + 1;
> +}
> +
> /**
> * Asymmetric crypto operation type variants
> + * Note: Update rte_crypto_asym_op_list_end for every new type added.
> */
> enum rte_crypto_asym_op_type {
> RTE_CRYPTO_ASYM_OP_ENCRYPT,
> @@ -135,9 +141,14 @@ enum rte_crypto_asym_op_type {
> /**< Signature Generation operation */
> RTE_CRYPTO_ASYM_OP_VERIFY,
> /**< Signature Verification operation */
> - RTE_CRYPTO_ASYM_OP_LIST_END
> };
>
> +static inline int
> +rte_crypto_asym_op_list_end(void)
> +{
> + return RTE_CRYPTO_ASYM_OP_VERIFY + 1;
> +}
> +
> /**
> * Asymmetric crypto key exchange operation type
> */
> @@ -168,7 +179,6 @@ enum rte_crypto_rsa_padding_type {
> /**< RSA PKCS#1 OAEP padding scheme */
> RTE_CRYPTO_RSA_PADDING_PSS,
> /**< RSA PKCS#1 PSS padding scheme */
> - RTE_CRYPTO_RSA_PADDING_TYPE_LIST_END
> };
>
> /**
On 9/6/2024 8:45 AM, Akhil Goyal wrote:
>>>
>>> Here's an idea...
>>>
>>> We can introduce a generic design pattern where we keep the _LIST_END enum
>> value at the end, somehow marking it private (and not part of the API/ABI), and
>> move the _list_end() function inside the C file, so it uses the _LIST_END enum
>> value that the library was built with. E.g. like this:
>>>
>>>
>>> In the header file:
>>>
>>> enum rte_crypto_asym_op_type {
>>> RTE_CRYPTO_ASYM_OP_VERIFY,
>>> /**< Signature Verification operation */
>>> #if RTE_BUILDING_INTERNAL
>>> __RTE_CRYPTO_ASYM_OP_LIST_END /* internal */
>>> #endif
>>> }
>>>
>>> int rte_crypto_asym_op_list_end(void);
>>>
>>>
>>> And in the associated library code file, when including rte_crypto_asym.h:
>>>
>>> #define RTE_BUILDING_INTERNAL
>>> #include <cryptodev/rte_crypto_asym.h>
>>>
>>> int
>>> rte_crypto_asym_op_list_end(void)
>>> {
>>> return __RTE_CRYPTO_ASYM_OP_LIST_END;
>>> }
>>
>> It's more generic, and also keep LIST_END in the define, we just add new enum
>> before it.
>> But based on my understanding of ABI compatibility, from the point view of
>> application,
>> this API should return old-value even with the new library, but it will return new-
>> value
>> with new library. It could also break ABI.
>>
>> So this API should force inline, just as this patch did. But it seem can't work if
>> move
>> this API to header file and add static inline.
>>
> Yes, moving to c file does not seem to solve the purpose.
> So should we move with the way the patch is submitted or we have some other suggestion?
>
+1, when it is not inline function, this approach won't work.
On 9/23/2024 9:41 PM, Akhil Goyal wrote:
> Hi Morten,
>
> Apologies for delayed response.
>> Maybe a combination, returning the lowest end of the two versions of the list,
>> would work...
>>
>> ----------------------------------
>> Common header file (rte_common.h):
>> ----------------------------------
>>
>> /* Add at end of enum list in the header file. */
>> #define RTE_ENUM_LIST_END(name) \
>> _ # name # _ENUM_LIST_END /**< @internal */
>>
>> /* Add somewhere in header file, preferably after the enum list. */
>> #define rte_declare_enum_list_end(name) \
>> /** @internal */ \
>> int _# name # _enum_list_end(void); \
>> \
>> static int name # _enum_list_end(void) \
>> { \
>> static int cached = 0; \
>> \
>> if (likely(cached != 0)) \
>> return cached; \
>> \
>> return cached = RTE_MIN( \
>> RTE_ENUM_LIST_END(name), \
>> _ # name # _enum_list_end()); \
>> } \
>> \
>> int _# name # _enum_list_end(void)
>>
>> /* Add in the library/driver implementation. */
>> #define rte_define_enum_list_end(name) \
>> int _# name # _enum_list_end(void) \
>> { \
>> return RTE_ENUM_LIST_END(name); \
>> } \
>> \
>> int _# name # _enum_list_end(void)
>>
>> --------------------
>> Library header file:
>> --------------------
>>
>> enum rte_crypto_asym_op_type {
>> RTE_CRYPTO_ASYM_OP_VERIFY,
>> /**< Signature Verification operation */
>> RTE_ENUM_LIST_END(rte_crypto_asym_op)
>
> Will the ABI check be ok for adding anything in between
> RTE_CRYPTO_ASYM_OP_VERIFY and RTE_ENUM_LIST_END(rte_crypto_asym_op)?
> Don’t we need to add exception for that if we somehow make it internal by adding a comment only?
> Library is actually not restricting the application to not use RTE_ENUM_LIST_END(rte_crypto_asym_op) directly.
>
> Also we may need to expose the .c file internal function as experimental in version.map
>
>> }
>>
>> rte_declare_enum_list_end(rte_crypto_asym_op);
>>
>> ---------------
>> Library C file:
>> ---------------
>>
>> rte_define_enum_list_end(rte_crypto_asym_op);
>
> If we want to make it a generic thing in rte_common.h
> Will the below change be ok?
> ----------------------------------
> Common header file (rte_common.h):
> ----------------------------------
> #define rte_define_enum_list_end(name, last_value) \
> static inline int name ## _enum_list_end(void) \
> { \
> return last_value + 1; \
> }
>
> ----------------
> Lib header file
> ----------------
> //After the enum definition define the list end as below
> rte_define_enum_list_end(rte_crypto_asym_op, RTE_CRYPTO_ASYM_OP_VERIFY);
>
I assume Morten suggests his macros to escape from maintenance cost of
updating inline function each time a new enum is added.
But with above suggestion, that cost is still there, so I don't think
this one has a benefit against the original suggestion.
On Fri, Oct 4, 2024 at 5:55 AM Ferruh Yigit <ferruh.yigit@amd.com> wrote:
>
> On 9/5/2024 11:14 AM, Akhil Goyal wrote:
> > Replace *_LIST_END enumerators from asymmetric crypto
> > lib to avoid ABI breakage for every new addition in
> > enums with inline APIs.
> >
> > Signed-off-by: Akhil Goyal <gakhil@marvell.com>
> > ---
> > This patch was discussed in ML long time back.
> > https://patches.dpdk.org/project/dpdk/patch/20211008204516.3497060-1-gakhil@marvell.com/
> > Now added inline APIs for getting the list end which need to be updated
> > for each new entry to the enum. This shall help in avoiding ABI break
> > for adding new algo.
> >
>
> Hi Akhil,
>
> *I think* this hides the problem instead of fixing it, and this may be
> partially because of the tooling (libabigail) limitation.
>
> This patch prevents the libabigail warning, true, but it doesn't improve
> anything from the application's perspective.
> Before or after this patch, application knows a fixed value as END value.
>
> Not all changes in the END (MAX) enum values cause ABI break, but tool
> warns on all, that is why I think this may be tooling limitation [1].
> (Just to stress, I am NOT talking about regular enum values change, I am
> talking about only END (MAX) value changes caused by appending new enum
> items.)
>
> As far as I can see (please Dodji, David correct me if I am wrong) ABI
> break only happens if application and library exchange enum values in
> the API (directly or within a struct).
- There is also the following issue:
A library publicly exports an array sized against a END (MAX) enum in the API.
https://developers.redhat.com/blog/2019/05/06/how-c-array-sizes-become-part-of-the-binary-interface-of-a-library
I had made comments for an issue in the cryptodev library in the past:
https://inbox.dpdk.org/dev/CAJFAV8xs5CVdE2xwRtaxk5vE_PiQMV5LY5tKStk3R1gOuRTsUw@mail.gmail.com/
- Sorry to deviate from the _END enum discussion that tries to define
a solution for all cases, but all I see in the cryptodev patch is a
need for an enumerator... for an internal unit test.
From the RFC patch, I would simply change the
rte_crypto_asym_xform_type_list_end helper into a non inline symbol
and mark it __rte_internal, or move this helper to a non public header
used by the unit test.
Or add a (internal) rte_crypto_asym_xform_type_next_op() used through
a a RTE_CRYPTO_FOREACH_ASYM_OP() macro.
Hello,
Ferruh Yigit <ferruh.yigit@amd.com> writes:
> On 9/5/2024 11:14 AM, Akhil Goyal wrote:
>> Replace *_LIST_END enumerators from asymmetric crypto
>> lib to avoid ABI breakage for every new addition in
>> enums with inline APIs.
>>
>> Signed-off-by: Akhil Goyal <gakhil@marvell.com>
>> ---
>> This patch was discussed in ML long time back.
>> https://patches.dpdk.org/project/dpdk/patch/20211008204516.3497060-1-gakhil@marvell.com/
>> Now added inline APIs for getting the list end which need to be updated
>> for each new entry to the enum. This shall help in avoiding ABI break
>> for adding new algo.
>>
>
> Hi Akhil,
>
> *I think* this hides the problem instead of fixing it, and this may be
> partially because of the tooling (libabigail) limitation.
So, I am not sure to understand how this would be a libabigail
limitation in general. Let me explain.
The abidiff tool that compares two binaries and emits reports about
their ABI changes can be given a suppression specification file which
instructs the tool about what type of change to avoid emitting reports
about.
It turns out there is a construct specifically designed to handle the
case where an enumerator is added right before the last enumerator of a
enum. Such a change causes the value of the last enumerator to
increase.
For instance, consider this enum:
enum foo_enum
{
FOO_FIRST,
FOO_SECOND,
FOO_END
};
If I add a new enumerator right before the last enumerator, I would get
this:
enum foo_enum
{
FOO_FIRST,
FOO_SECOND,
FOO_THIRD,
FOO_END
};
This change cause the value of the the FOOD_END enumerator to increase.
And that increase might be problematic. At the moment, for it being
problematic or not has to be the result of a careful review.
So, by default, abidiff will complain by saying that the value of
FOO_END was changed.
But you, as a community of practice, can decide that this kind of change
to the value of the last enumerator is not a problematic change, after
careful review of your code and practice. You thus can specify that
the tool using a suppression specification which has the following
syntax:
[suppress_type]
type_kind = enum
changed_enumerators = FOO_END, ANOTHER_ENUM_END, AND_ANOTHER_ENUM_END
or, alternatively, you can specify the enumerators you want to suppress
the changes for as a list of regular expressions:
[suppress_type]
type_kind = enum
changed_enumerators_regexp = .*_END$, .*_LAST$, .*_LIST_END$
Wouldn't that be enough to address your use case here (honest question)?
> This patch prevents the libabigail warning, true, but it doesn't improve
> anything from the application's perspective.
> Before or after this patch, application knows a fixed value as END value.
>
> Not all changes in the END (MAX) enum values cause ABI break, but tool
> warns on all, that is why I think this may be tooling limitation [1].
> (Just to stress, I am NOT talking about regular enum values change, I am
> talking about only END (MAX) value changes caused by appending new enum
> items.)
>
> As far as I can see (please Dodji, David correct me if I am wrong) ABI
> break only happens if application and library exchange enum values in
> the API (directly or within a struct).
Sorry, I am not sure to understand what you mean by "exchange enum values".
I would say is that if a change to an enumerator value causes a change
to the layout of a type which is part of the ABI, then that enumerator
value change might change the ABI. That ABI change might be problematic
(i.e an ABI break) or not.
>
> Exchanging enum values via API cause ABI issues because:
> 1. enum size is not fixed, it uses min storage size that can hold all
> values, adding new enums may cause its size change and of course this
> breaks ABI.
> 2. Library can send enum values that application doesn't know, this may
> cause application behave undefined.
> 3. Application sending MAX value (or more) to API expects error, but
> that may be a valid value in the new library and applications gets
> unexpected result.
>
>
> Let's assume above 1. happens, with this patch warning is prevented, but
> ABI break still can occur.
>
> One option can be not exchanging enums in APIs at all, this way changes
> in the END (MAX) enum values are harmless. But I can see cryptodev does
> this a lot.
>
> When enum is exchanged in APIs, and if we want to be strict about the
> ABI, safest option can be not appending to enums at all, and keeping END
> (MAX) items can be a way to enable warnings for this.
>
>
> More relaxed option is protect against only 1. since that is the real
> ABI issue, 2 & 3 are more defensive programming, so as long as enum size
> is not changed we may ignore the END (MAX) value change warnings.
>
>
>
> [1] It would be better if tool gives END (MAX) enum value warnings only
> if it is exchanged in an API, but not sure if this can be possible to
> detect.
I believe that if you want to know if an enumerator value is *USED* by a
type (which I believe is at the root of what you are alluding to), then
you would need a static analysis tool that works at the source level.
Or, you need a human review of the code once the binary analysis tool
told you that that value of the enumerator changed.
Why ? please let me give you an example:
enum foo_enum
{
FOO_FIRST,
FOO_SECOND,
FOO_END
};
int array[FOO_END];
Once this is compiled into binary, what libabigail is going to see by
analyzing the binary is that 'array' is an array of 2 integers. The
information about the size of the array being initially an enumerator
value is lost. To detect that, you need source level analysis.
But then, by reviewing the code, this is a construct that you can spot
and allow or forbid, depending on your goals as a project.
[...]
Cheers,
> > If we want to make it a generic thing in rte_common.h
> > Will the below change be ok?
> > ----------------------------------
> > Common header file (rte_common.h):
> > ----------------------------------
> > #define rte_define_enum_list_end(name, last_value) \
> > static inline int name ## _enum_list_end(void) \
> > { \
> > return last_value + 1; \
> > }
> >
> > ----------------
> > Lib header file
> > ----------------
> > //After the enum definition define the list end as below
> > rte_define_enum_list_end(rte_crypto_asym_op,
> RTE_CRYPTO_ASYM_OP_VERIFY);
> >
>
> I assume Morten suggests his macros to escape from maintenance cost of
> updating inline function each time a new enum is added.
Except for the maintenance cost, is there any other issue with this?
Will the ABI break for any new additions?
I believe this is a simple change to define and maintain LIST_END wherever required.
We can add a comment in the enum for asking people to update it for new additions.
The macros suggested by Morten seem a bit complex and
would add #if in the enum to compile it as internal.
Also we would need to expose "_ ## name ## _enum_list_end" function also in version.map
While the "name ## _enum_list_end" would be used by the application.
I would suggest to remove the list_end from crypto library instead of adding #if in enum.
Like it was suggested long back. Application can live without it.
https://patches.dpdk.org/project/dpdk/patch/20211008204516.3497060-1-gakhil@marvell.com/
The list_end were removed for all symmetric crypto enums when we worked on ABI stability.
But asymmetric was left as it was experimental at that time and we missed them as it was not complaining.
But now since it is marked as stable. We need to deal with it as soon as possible.
>
> But with above suggestion, that cost is still there, so I don't think
> this one has a benefit against the original suggestion.
Yes the idea is same for both.
It is just that this approach is generalized to be used anywhere.
> On Fri, Oct 4, 2024 at 5:55 AM Ferruh Yigit <ferruh.yigit@amd.com> wrote:
> >
> > On 9/5/2024 11:14 AM, Akhil Goyal wrote:
> > > Replace *_LIST_END enumerators from asymmetric crypto
> > > lib to avoid ABI breakage for every new addition in
> > > enums with inline APIs.
> > >
> > > Signed-off-by: Akhil Goyal <gakhil@marvell.com>
> > > ---
> > > This patch was discussed in ML long time back.
> > > https://patches.dpdk.org/project/dpdk/patch/20211008204516.3497060-1-gakhil@marvell.com/
> > > Now added inline APIs for getting the list end which need to be updated
> > > for each new entry to the enum. This shall help in avoiding ABI break
> > > for adding new algo.
> > >
> >
> > Hi Akhil,
> >
> > *I think* this hides the problem instead of fixing it, and this may be
> > partially because of the tooling (libabigail) limitation.
> >
> > This patch prevents the libabigail warning, true, but it doesn't improve
> > anything from the application's perspective.
> > Before or after this patch, application knows a fixed value as END value.
> >
> > Not all changes in the END (MAX) enum values cause ABI break, but tool
> > warns on all, that is why I think this may be tooling limitation [1].
> > (Just to stress, I am NOT talking about regular enum values change, I am
> > talking about only END (MAX) value changes caused by appending new enum
> > items.)
> >
> > As far as I can see (please Dodji, David correct me if I am wrong) ABI
> > break only happens if application and library exchange enum values in
> > the API (directly or within a struct).
>
> - There is also the following issue:
> A library publicly exports an array sized against a END (MAX) enum in the API.
> https://developers.redhat.com/blog/2019/05/06/how-c-array-sizes-become-part-of-the-binary-interface-of-a-library
>
> I had made comments for an issue in the cryptodev library in the past:
> https://inbox.dpdk.org/dev/CAJFAV8xs5CVdE2xwRtaxk5vE_PiQMV5LY5tKStk3R1gOuRTsUw@mail.gmail.com/
>
Yes this issue is being discussed multiple times.
One discussion is mentioned in patch description also.
There haven’t been a consensus yet.
>
> - Sorry to deviate from the _END enum discussion that tries to define
> a solution for all cases, but all I see in the cryptodev patch is a
> need for an enumerator... for an internal unit test.
> From the RFC patch, I would simply change the
> rte_crypto_asym_xform_type_list_end helper into a non inline symbol
> and mark it __rte_internal, or move this helper to a non public header
> used by the unit test.
That means we are not allowing applications to use it. Right?
So then why not we remove these LIST_END completely.
Test app can manage without it as well.
This was the original RFC to remove all list end.
https://patches.dpdk.org/project/dpdk/patch/20211008204516.3497060-1-gakhil@marvell.com/
As per our last discussion we need to find the LIST_END using a function and not via MACRO or enum.
This RFC tries to do that with an inline function which will give the list end based on the last enum value
Which is defined in that header file.
The only thing is we have an overhead of updating that inline function with a different value on every new addition which are normally not very frequent.
>
> Or add a (internal) rte_crypto_asym_xform_type_next_op() used through
> a a RTE_CRYPTO_FOREACH_ASYM_OP() macro.
>
>
> --
> David Marchand
> Hello,
>
> Ferruh Yigit <ferruh.yigit@amd.com> writes:
>
> > On 9/5/2024 11:14 AM, Akhil Goyal wrote:
> >> Replace *_LIST_END enumerators from asymmetric crypto
> >> lib to avoid ABI breakage for every new addition in
> >> enums with inline APIs.
> >>
> >> Signed-off-by: Akhil Goyal <gakhil@marvell.com>
> >> ---
> >> This patch was discussed in ML long time back.
> >> https://patches.dpdk.org/project/dpdk/patch/20211008204516.3497060-1-gakhil@marvell.com/
> >> Now added inline APIs for getting the list end which need to be updated
> >> for each new entry to the enum. This shall help in avoiding ABI break
> >> for adding new algo.
> >>
> >
> > Hi Akhil,
> >
> > *I think* this hides the problem instead of fixing it, and this may be
> > partially because of the tooling (libabigail) limitation.
>
> So, I am not sure to understand how this would be a libabigail
> limitation in general. Let me explain.
>
> The abidiff tool that compares two binaries and emits reports about
> their ABI changes can be given a suppression specification file which
> instructs the tool about what type of change to avoid emitting reports
> about.
>
> It turns out there is a construct specifically designed to handle the
> case where an enumerator is added right before the last enumerator of a
> enum. Such a change causes the value of the last enumerator to
> increase.
>
> For instance, consider this enum:
>
> enum foo_enum
> {
> FOO_FIRST,
> FOO_SECOND,
> FOO_END
> };
>
> If I add a new enumerator right before the last enumerator, I would get
> this:
>
> enum foo_enum
> {
> FOO_FIRST,
> FOO_SECOND,
> FOO_THIRD,
> FOO_END
> };
>
> This change cause the value of the the FOOD_END enumerator to increase.
> And that increase might be problematic. At the moment, for it being
> problematic or not has to be the result of a careful review.
>
> So, by default, abidiff will complain by saying that the value of
> FOO_END was changed.
>
> But you, as a community of practice, can decide that this kind of change
> to the value of the last enumerator is not a problematic change, after
> careful review of your code and practice. You thus can specify that
> the tool using a suppression specification which has the following
> syntax:
>
> [suppress_type]
> type_kind = enum
> changed_enumerators = FOO_END, ANOTHER_ENUM_END,
> AND_ANOTHER_ENUM_END
>
> or, alternatively, you can specify the enumerators you want to suppress
> the changes for as a list of regular expressions:
>
> [suppress_type]
> type_kind = enum
> changed_enumerators_regexp = .*_END$, .*_LAST$, .*_LIST_END$
>
> Wouldn't that be enough to address your use case here (honest question)?
>
> > This patch prevents the libabigail warning, true, but it doesn't improve
> > anything from the application's perspective.
> > Before or after this patch, application knows a fixed value as END value.
> >
> > Not all changes in the END (MAX) enum values cause ABI break, but tool
> > warns on all, that is why I think this may be tooling limitation [1].
> > (Just to stress, I am NOT talking about regular enum values change, I am
> > talking about only END (MAX) value changes caused by appending new enum
> > items.)
> >
> > As far as I can see (please Dodji, David correct me if I am wrong) ABI
> > break only happens if application and library exchange enum values in
> > the API (directly or within a struct).
>
> Sorry, I am not sure to understand what you mean by "exchange enum values".
>
> I would say is that if a change to an enumerator value causes a change
> to the layout of a type which is part of the ABI, then that enumerator
> value change might change the ABI. That ABI change might be problematic
> (i.e an ABI break) or not.
>
> >
> > Exchanging enum values via API cause ABI issues because:
> > 1. enum size is not fixed, it uses min storage size that can hold all
> > values, adding new enums may cause its size change and of course this
> > breaks ABI.
> > 2. Library can send enum values that application doesn't know, this may
> > cause application behave undefined.
> > 3. Application sending MAX value (or more) to API expects error, but
> > that may be a valid value in the new library and applications gets
> > unexpected result.
> >
> >
> > Let's assume above 1. happens, with this patch warning is prevented, but
> > ABI break still can occur.
> >
> > One option can be not exchanging enums in APIs at all, this way changes
> > in the END (MAX) enum values are harmless. But I can see cryptodev does
> > this a lot.
> >
> > When enum is exchanged in APIs, and if we want to be strict about the
> > ABI, safest option can be not appending to enums at all, and keeping END
> > (MAX) items can be a way to enable warnings for this.
> >
> >
> > More relaxed option is protect against only 1. since that is the real
> > ABI issue, 2 & 3 are more defensive programming, so as long as enum size
> > is not changed we may ignore the END (MAX) value change warnings.
> >
> >
> >
> > [1] It would be better if tool gives END (MAX) enum value warnings only
> > if it is exchanged in an API, but not sure if this can be possible to
> > detect.
>
> I believe that if you want to know if an enumerator value is *USED* by a
> type (which I believe is at the root of what you are alluding to), then
> you would need a static analysis tool that works at the source level.
> Or, you need a human review of the code once the binary analysis tool
> told you that that value of the enumerator changed.
>
> Why ? please let me give you an example:
>
> enum foo_enum
> {
> FOO_FIRST,
> FOO_SECOND,
> FOO_END
> };
>
> int array[FOO_END];
>
> Once this is compiled into binary, what libabigail is going to see by
> analyzing the binary is that 'array' is an array of 2 integers. The
> information about the size of the array being initially an enumerator
> value is lost. To detect that, you need source level analysis.
>
> But then, by reviewing the code, this is a construct that you can spot
> and allow or forbid, depending on your goals as a project.
>
In the above example if in newer library a FOO_THIRD is added.
FOO_END value will change and will cause ABI break for change in existing value.
But if we replace it with inline function to get the list_end and use it in array like below.
So if FOO_THIRD is added, we will also update foo_enum_list_end() function to return (FOO_THIRD+1)
enum foo_enum
{
FOO_FIRST,
FOO_SECOND,
};
static inline int foo_enum_list_end()
{
return FOO_SECOND + 1;
}
int array[foo_enum_list_end()];
Will this cause an ABI break if we add this array in application or in library?
> From: Akhil Goyal [mailto:gakhil@marvell.com]
> Sent: Thursday, 3 October 2024 09.01
>
> Hi Morten,
> >
> > Apologies for delayed response.
> > > Maybe a combination, returning the lowest end of the two versions
> of the list,
> > > would work...
> > >
> > > ----------------------------------
> > > Common header file (rte_common.h):
> > > ----------------------------------
> > >
> > > /* Add at end of enum list in the header file. */
> > > #define RTE_ENUM_LIST_END(name) \
> > > _ # name # _ENUM_LIST_END /**< @internal */
> > >
> > > /* Add somewhere in header file, preferably after the enum list. */
> > > #define rte_declare_enum_list_end(name) \
> > > /** @internal */ \
> > > int _# name # _enum_list_end(void); \
> > > \
> > > static int name # _enum_list_end(void) \
> > > { \
> > > static int cached = 0; \
> > > \
> > > if (likely(cached != 0)) \
> > > return cached; \
> > > \
> > > return cached = RTE_MIN( \
> > > RTE_ENUM_LIST_END(name), \
> > > _ # name # _enum_list_end()); \
> > > } \
> > > \
> > > int _# name # _enum_list_end(void)
> > >
> > > /* Add in the library/driver implementation. */
> > > #define rte_define_enum_list_end(name) \
> > > int _# name # _enum_list_end(void) \
> > > { \
> > > return RTE_ENUM_LIST_END(name); \
> > > } \
> > > \
> > > int _# name # _enum_list_end(void)
> > >
> > > --------------------
> > > Library header file:
> > > --------------------
> > >
> > > enum rte_crypto_asym_op_type {
> > > RTE_CRYPTO_ASYM_OP_VERIFY,
> > > /**< Signature Verification operation */
> > > RTE_ENUM_LIST_END(rte_crypto_asym_op)
> >
> > Will the ABI check be ok for adding anything in between
> > RTE_CRYPTO_ASYM_OP_VERIFY and
> > RTE_ENUM_LIST_END(rte_crypto_asym_op)?
> > Don’t we need to add exception for that if we somehow make it
> internal by
> > adding a comment only?
> > Library is actually not restricting the application to not use
> > RTE_ENUM_LIST_END(rte_crypto_asym_op) directly.
> >
> > Also we may need to expose the .c file internal function as
> experimental in
> > version.map
> >
> > > }
> > >
> > > rte_declare_enum_list_end(rte_crypto_asym_op);
> > >
> > > ---------------
> > > Library C file:
> > > ---------------
> > >
> > > rte_define_enum_list_end(rte_crypto_asym_op);
> >
> > If we want to make it a generic thing in rte_common.h
> > Will the below change be ok?
> > ----------------------------------
> > Common header file (rte_common.h):
> > ----------------------------------
> > #define rte_define_enum_list_end(name, last_value) \
> > static inline int name ## _enum_list_end(void) \
> > { \
> > return last_value + 1; \
> > }
> >
> > ----------------
> > Lib header file
> > ----------------
> > //After the enum definition define the list end as below
> > rte_define_enum_list_end(rte_crypto_asym_op,
> > RTE_CRYPTO_ASYM_OP_VERIFY);
> >
> >
> > And wherever list end is needed use
> rte_crypto_asym_op_enum_list_end()?
> >
> > With this change, abi check will not complain for any new addition at
> the end of
> > enum.
> > And we do not need to expose any internal API in version.map.
> >
> Can we move forward with above suggestion?
Sorry about the late reply, Akhil.
It seems Ferruh and David have picked up this discussion with good arguments.
I have no preferences for a generic solution, especially if this is an isolated case. A generic solution can be added at any time later.
> > From: Akhil Goyal [mailto:gakhil@marvell.com]
> > Sent: Thursday, 3 October 2024 09.01
> >
> > Hi Morten,
> > >
> > > Apologies for delayed response.
> > > > Maybe a combination, returning the lowest end of the two versions
> > of the list,
> > > > would work...
> > > >
> > > > ----------------------------------
> > > > Common header file (rte_common.h):
> > > > ----------------------------------
> > > >
> > > > /* Add at end of enum list in the header file. */
> > > > #define RTE_ENUM_LIST_END(name) \
> > > > _ # name # _ENUM_LIST_END /**< @internal */
> > > >
> > > > /* Add somewhere in header file, preferably after the enum list. */
> > > > #define rte_declare_enum_list_end(name) \
> > > > /** @internal */ \
> > > > int _# name # _enum_list_end(void); \
> > > > \
> > > > static int name # _enum_list_end(void) \
> > > > { \
> > > > static int cached = 0; \
> > > > \
> > > > if (likely(cached != 0)) \
> > > > return cached; \
> > > > \
> > > > return cached = RTE_MIN( \
> > > > RTE_ENUM_LIST_END(name), \
> > > > _ # name # _enum_list_end()); \
> > > > } \
> > > > \
> > > > int _# name # _enum_list_end(void)
> > > >
> > > > /* Add in the library/driver implementation. */
> > > > #define rte_define_enum_list_end(name) \
> > > > int _# name # _enum_list_end(void) \
> > > > { \
> > > > return RTE_ENUM_LIST_END(name); \
> > > > } \
> > > > \
> > > > int _# name # _enum_list_end(void)
> > > >
> > > > --------------------
> > > > Library header file:
> > > > --------------------
> > > >
> > > > enum rte_crypto_asym_op_type {
> > > > RTE_CRYPTO_ASYM_OP_VERIFY,
> > > > /**< Signature Verification operation */
> > > > RTE_ENUM_LIST_END(rte_crypto_asym_op)
> > >
> > > Will the ABI check be ok for adding anything in between
> > > RTE_CRYPTO_ASYM_OP_VERIFY and
> > > RTE_ENUM_LIST_END(rte_crypto_asym_op)?
> > > Don’t we need to add exception for that if we somehow make it
> > internal by
> > > adding a comment only?
> > > Library is actually not restricting the application to not use
> > > RTE_ENUM_LIST_END(rte_crypto_asym_op) directly.
> > >
> > > Also we may need to expose the .c file internal function as
> > experimental in
> > > version.map
> > >
> > > > }
> > > >
> > > > rte_declare_enum_list_end(rte_crypto_asym_op);
> > > >
> > > > ---------------
> > > > Library C file:
> > > > ---------------
> > > >
> > > > rte_define_enum_list_end(rte_crypto_asym_op);
> > >
> > > If we want to make it a generic thing in rte_common.h
> > > Will the below change be ok?
> > > ----------------------------------
> > > Common header file (rte_common.h):
> > > ----------------------------------
> > > #define rte_define_enum_list_end(name, last_value) \
> > > static inline int name ## _enum_list_end(void) \
> > > { \
> > > return last_value + 1; \
> > > }
> > >
> > > ----------------
> > > Lib header file
> > > ----------------
> > > //After the enum definition define the list end as below
> > > rte_define_enum_list_end(rte_crypto_asym_op,
> > > RTE_CRYPTO_ASYM_OP_VERIFY);
> > >
> > >
> > > And wherever list end is needed use
> > rte_crypto_asym_op_enum_list_end()?
> > >
> > > With this change, abi check will not complain for any new addition at
> > the end of
> > > enum.
> > > And we do not need to expose any internal API in version.map.
> > >
> > Can we move forward with above suggestion?
>
> Sorry about the late reply, Akhil.
>
> It seems Ferruh and David have picked up this discussion with good arguments.
>
> I have no preferences for a generic solution, especially if this is an isolated case. A
> generic solution can be added at any time later.
Ok, since we are not talking about a generic solution.
We can remove RTE_CRYPTO_ASYM_XFORM_TYPE_LIST_END
And RTE_CRYPTO_RSA_PADDING_TYPE_LIST_END.
These enums are not used anywhere and are not required at all.
And for RTE_CRYPTO_ASYM_OP_LIST_END, we can keep it as is.
The rte_crypto_asym_op_type is not expected to grow in future and
We need the list end for loops as well as arrays.
Hence sending a patch to remove RTE_CRYPTO_ASYM_XFORM_TYPE_LIST_END
And RTE_CRYPTO_RSA_PADDING_TYPE_LIST_END.
This is inline with symmetric crypto xform type list.
On 10/4/2024 10:38 AM, Dodji Seketeli wrote:
> Hello,
>
> Ferruh Yigit <ferruh.yigit@amd.com> writes:
>
>> On 9/5/2024 11:14 AM, Akhil Goyal wrote:
>>> Replace *_LIST_END enumerators from asymmetric crypto
>>> lib to avoid ABI breakage for every new addition in
>>> enums with inline APIs.
>>>
>>> Signed-off-by: Akhil Goyal <gakhil@marvell.com>
>>> ---
>>> This patch was discussed in ML long time back.
>>> https://patches.dpdk.org/project/dpdk/patch/20211008204516.3497060-1-gakhil@marvell.com/
>>> Now added inline APIs for getting the list end which need to be updated
>>> for each new entry to the enum. This shall help in avoiding ABI break
>>> for adding new algo.
>>>
>>
>> Hi Akhil,
>>
>> *I think* this hides the problem instead of fixing it, and this may be
>> partially because of the tooling (libabigail) limitation.
>
> So, I am not sure to understand how this would be a libabigail
> limitation in general. Let me explain.
>
Hi Dodji,
Thank you for the clarification, a few notes below.
> The abidiff tool that compares two binaries and emits reports about
> their ABI changes can be given a suppression specification file which
> instructs the tool about what type of change to avoid emitting reports
> about.
>
> It turns out there is a construct specifically designed to handle the
> case where an enumerator is added right before the last enumerator of a
> enum. Such a change causes the value of the last enumerator to
> increase.
>
> For instance, consider this enum:
>
> enum foo_enum
> {
> FOO_FIRST,
> FOO_SECOND,
> FOO_END
> };
>
> If I add a new enumerator right before the last enumerator, I would get
> this:
>
> enum foo_enum
> {
> FOO_FIRST,
> FOO_SECOND,
> FOO_THIRD,
> FOO_END
> };
>
> This change cause the value of the the FOOD_END enumerator to increase.
> And that increase might be problematic. At the moment, for it being
> problematic or not has to be the result of a careful review.
>
As you said, FOOD_END value change can be sometimes problematic, but
sometimes it is not.
This what I referred as limitation that tool is not reporting only
problematic case, but require human review.
(btw, this is a very useful tool, I don't want to sound like negative
about it, only want to address this recurring subject in dpdk.)
> So, by default, abidiff will complain by saying that the value of
> FOO_END was changed.
>
> But you, as a community of practice, can decide that this kind of change
> to the value of the last enumerator is not a problematic change, after
> careful review of your code and practice. You thus can specify that
> the tool using a suppression specification which has the following
> syntax:
>
> [suppress_type]
> type_kind = enum
> changed_enumerators = FOO_END, ANOTHER_ENUM_END, AND_ANOTHER_ENUM_END
>
> or, alternatively, you can specify the enumerators you want to suppress
> the changes for as a list of regular expressions:
>
> [suppress_type]
> type_kind = enum
> changed_enumerators_regexp = .*_END$, .*_LAST$, .*_LIST_END$
>
> Wouldn't that be enough to address your use case here (honest question)?
>
We are already using suppress feature in dpdk.
But difficulty is to decide if END (MAX) enum value change warning is an
actual ABI break or not.
When tool gives warning, tendency is to just make warning go away,
mostly by removing END (MAX) enum without really analyzing if it is a
real ABI break.
>> This patch prevents the libabigail warning, true, but it doesn't improve
>> anything from the application's perspective.
>> Before or after this patch, application knows a fixed value as END value.
>>
>> Not all changes in the END (MAX) enum values cause ABI break, but tool
>> warns on all, that is why I think this may be tooling limitation [1].
>> (Just to stress, I am NOT talking about regular enum values change, I am
>> talking about only END (MAX) value changes caused by appending new enum
>> items.)
>>
>> As far as I can see (please Dodji, David correct me if I am wrong) ABI
>> break only happens if application and library exchange enum values in
>> the API (directly or within a struct).
>
> Sorry, I am not sure to understand what you mean by "exchange enum values".
>
> I would say is that if a change to an enumerator value causes a change
> to the layout of a type which is part of the ABI, then that enumerator
> value change might change the ABI. That ABI change might be problematic
> (i.e an ABI break) or not.
>
I mean if enum is used in the API, either as parameter or return value
of it, and either directly or as part of other struct.
Think about a case an enum is used in both application and library
independently, but enum is not used in any API at all, for this usage I
don't see a case increasing END (MAX) enum value causing an ABI break.
I was thinking if this is something tool can detect.
>>
>> Exchanging enum values via API cause ABI issues because:
>> 1. enum size is not fixed, it uses min storage size that can hold all
>> values, adding new enums may cause its size change and of course this
>> breaks ABI.
>> 2. Library can send enum values that application doesn't know, this may
>> cause application behave undefined.
>> 3. Application sending MAX value (or more) to API expects error, but
>> that may be a valid value in the new library and applications gets
>> unexpected result.
>>
>>
>> Let's assume above 1. happens, with this patch warning is prevented, but
>> ABI break still can occur.
>>
>> One option can be not exchanging enums in APIs at all, this way changes
>> in the END (MAX) enum values are harmless. But I can see cryptodev does
>> this a lot.
>>
>> When enum is exchanged in APIs, and if we want to be strict about the
>> ABI, safest option can be not appending to enums at all, and keeping END
>> (MAX) items can be a way to enable warnings for this.
>>
>>
>> More relaxed option is protect against only 1. since that is the real
>> ABI issue, 2 & 3 are more defensive programming, so as long as enum size
>> is not changed we may ignore the END (MAX) value change warnings.
>>
>>
>>
>> [1] It would be better if tool gives END (MAX) enum value warnings only
>> if it is exchanged in an API, but not sure if this can be possible to
>> detect.
>
> I believe that if you want to know if an enumerator value is *USED* by a
> type (which I believe is at the root of what you are alluding to), then
> you would need a static analysis tool that works at the source level.
> Or, you need a human review of the code once the binary analysis tool
> told you that that value of the enumerator changed.
>
> Why ? please let me give you an example:
>
> enum foo_enum
> {
> FOO_FIRST,
> FOO_SECOND,
> FOO_END
> };
>
> int array[FOO_END];
>
> Once this is compiled into binary, what libabigail is going to see by
> analyzing the binary is that 'array' is an array of 2 integers. The
> information about the size of the array being initially an enumerator
> value is lost. To detect that, you need source level analysis.
>
I see the problem.
Is this the main reason that changing FOO_END value reported as warning?
If we forbid this kind of usage of the FOO_END, can we ignore this
warning safely?
> But then, by reviewing the code, this is a construct that you can spot
> and allow or forbid, depending on your goals as a project.
>
> [...]
>
> Cheers,
>
On 10/4/2024 8:04 AM, David Marchand wrote:
> On Fri, Oct 4, 2024 at 5:55 AM Ferruh Yigit <ferruh.yigit@amd.com> wrote:
>>
>> On 9/5/2024 11:14 AM, Akhil Goyal wrote:
>>> Replace *_LIST_END enumerators from asymmetric crypto
>>> lib to avoid ABI breakage for every new addition in
>>> enums with inline APIs.
>>>
>>> Signed-off-by: Akhil Goyal <gakhil@marvell.com>
>>> ---
>>> This patch was discussed in ML long time back.
>>> https://patches.dpdk.org/project/dpdk/patch/20211008204516.3497060-1-gakhil@marvell.com/
>>> Now added inline APIs for getting the list end which need to be updated
>>> for each new entry to the enum. This shall help in avoiding ABI break
>>> for adding new algo.
>>>
>>
>> Hi Akhil,
>>
>> *I think* this hides the problem instead of fixing it, and this may be
>> partially because of the tooling (libabigail) limitation.
>>
>> This patch prevents the libabigail warning, true, but it doesn't improve
>> anything from the application's perspective.
>> Before or after this patch, application knows a fixed value as END value.
>>
>> Not all changes in the END (MAX) enum values cause ABI break, but tool
>> warns on all, that is why I think this may be tooling limitation [1].
>> (Just to stress, I am NOT talking about regular enum values change, I am
>> talking about only END (MAX) value changes caused by appending new enum
>> items.)
>>
>> As far as I can see (please Dodji, David correct me if I am wrong) ABI
>> break only happens if application and library exchange enum values in
>> the API (directly or within a struct).
>
> - There is also the following issue:
> A library publicly exports an array sized against a END (MAX) enum in the API.
> https://developers.redhat.com/blog/2019/05/06/how-c-array-sizes-become-part-of-the-binary-interface-of-a-library
>
I see. And Dodji explained this requires source code to detect.
I don't remember seeing a public array whose size is defined by an enum,
are you aware of any instance of this usage?
> I had made comments for an issue in the cryptodev library in the past:
> https://inbox.dpdk.org/dev/CAJFAV8xs5CVdE2xwRtaxk5vE_PiQMV5LY5tKStk3R1gOuRTsUw@mail.gmail.com/
>
>
> - Sorry to deviate from the _END enum discussion that tries to define
> a solution for all cases, but all I see in the cryptodev patch is a
> need for an enumerator... for an internal unit test.
> From the RFC patch, I would simply change the
> rte_crypto_asym_xform_type_list_end helper into a non inline symbol
> and mark it __rte_internal, or move this helper to a non public header
> used by the unit test.
>
> Or add a (internal) rte_crypto_asym_xform_type_next_op() used through
> a a RTE_CRYPTO_FOREACH_ASYM_OP() macro.
>
>
> >>> Now added inline APIs for getting the list end which need to be updated
> >>> for each new entry to the enum. This shall help in avoiding ABI break
> >>> for adding new algo.
> >>>
> >>
> >> Hi Akhil,
> >>
> >> *I think* this hides the problem instead of fixing it, and this may be
> >> partially because of the tooling (libabigail) limitation.
> >>
> >> This patch prevents the libabigail warning, true, but it doesn't improve
> >> anything from the application's perspective.
> >> Before or after this patch, application knows a fixed value as END value.
> >>
> >> Not all changes in the END (MAX) enum values cause ABI break, but tool
> >> warns on all, that is why I think this may be tooling limitation [1].
> >> (Just to stress, I am NOT talking about regular enum values change, I am
> >> talking about only END (MAX) value changes caused by appending new enum
> >> items.)
> >>
> >> As far as I can see (please Dodji, David correct me if I am wrong) ABI
> >> break only happens if application and library exchange enum values in
> >> the API (directly or within a struct).
> >
> > - There is also the following issue:
> > A library publicly exports an array sized against a END (MAX) enum in the API.
> > https://developers.redhat.com/blog/2019/05/06/how-c-array-sizes-become-part-of-the-binary-interface-of-a-library
> >
>
> I see. And Dodji explained this requires source code to detect.
>
> I don't remember seeing a public array whose size is defined by an enum,
> are you aware of any instance of this usage?
https://patches.dpdk.org/project/dpdk/patch/20241009071151.1106-1-gmuthukrishn@marvell.com/
This was merged yesterday.
Hello,
Ferruh Yigit <ferruh.yigit@amd.com> writes:
[...]
>> This change cause the value of the the FOOD_END enumerator to increase.
>> And that increase might be problematic. At the moment, for it being
>> problematic or not has to be the result of a careful review.
>>
>
> As you said, FOOD_END value change can be sometimes problematic, but
> sometimes it is not.
> This what I referred as limitation that tool is not reporting only
> problematic case, but require human review.
Oh, I see. Thank you for clarifying.
> (btw, this is a very useful tool, I don't want to sound like negative
> about it, only want to address this recurring subject in dpdk.)
No problem, I never assume you mean anything negative :-)
[...]
>> So, by default, abidiff will complain by saying that the value of
>> FOO_END was changed.
>>
>> But you, as a community of practice, can decide that this kind of change
>> to the value of the last enumerator is not a problematic change, after
>> careful review of your code and practice. You thus can specify that
>> the tool using a suppression specification which has the following
>> syntax:
>>
>> [suppress_type]
>> type_kind = enum
>> changed_enumerators = FOO_END, ANOTHER_ENUM_END, AND_ANOTHER_ENUM_END
>>
>> or, alternatively, you can specify the enumerators you want to suppress
>> the changes for as a list of regular expressions:
>>
>> [suppress_type]
>> type_kind = enum
>> changed_enumerators_regexp = .*_END$, .*_LAST$, .*_LIST_END$
>>
>> Wouldn't that be enough to address your use case here (honest question)?
>>
>
> We are already using suppress feature in dpdk.
>
> But difficulty is to decide if END (MAX) enum value change warning is an
> actual ABI break or not.
>
> When tool gives warning, tendency is to just make warning go away,
> mostly by removing END (MAX) enum without really analyzing if it is a
> real ABI break.
I see.
[...]
>>> [1] It would be better if tool gives END (MAX) enum value warnings only
>>> if it is exchanged in an API, but not sure if this can be possible to
>>> detect.
>>
>> I believe that if you want to know if an enumerator value is *USED* by a
>> type (which I believe is at the root of what you are alluding to), then
>> you would need a static analysis tool that works at the source level.
>> Or, you need a human review of the code once the binary analysis tool
>> told you that that value of the enumerator changed.
>>
>> Why ? please let me give you an example:
>>
>> enum foo_enum
>> {
>> FOO_FIRST,
>> FOO_SECOND,
>> FOO_END
>> };
>>
>> int array[FOO_END];
>>
>> Once this is compiled into binary, what libabigail is going to see by
>> analyzing the binary is that 'array' is an array of 2 integers. The
>> information about the size of the array being initially an enumerator
>> value is lost. To detect that, you need source level analysis.
>>
>
> I see the problem.
>
> Is this the main reason that changing FOO_END value reported as warning?
Yes, it is because of this class of issues.
Actually if ANY enumerator value is changed, that is actually an ABI
change. And that ABI change is either compatible or not.
> If we forbid this kind of usage of the FOO_END, can we ignore this
> warning safely?
I would think so.
But then, you'd have to also forbid the use of all enumerators,
basically. I am not sure that would be practical.
Rather I would tend to lean toward reviewing the use of enumerators, on
a case by case basis, using tools like 'grep' and whatnot.
What I would advise to forbid is the use of complicated macros or
constructs that makes the review of the use of enumerators
non-practical. You should be able to grep "FOO_END" and see where it's
used in the source code. Reviewing that shouldn't take more than a few
minutes whenever a tool warns about the change of its value.
>
>> But then, by reviewing the code, this is a construct that you can spot
>> and allow or forbid, depending on your goals as a project.
>>
>> [...]
>>
>> Cheers,
>>
>
Hello,
Akhil Goyal <gakhil@marvell.com> writes:
[...]
>> I believe that if you want to know if an enumerator value is *USED* by a
>> type (which I believe is at the root of what you are alluding to), then
>> you would need a static analysis tool that works at the source level.
>> Or, you need a human review of the code once the binary analysis tool
>> told you that that value of the enumerator changed.
>>
>> Why ? please let me give you an example:
>>
>> enum foo_enum
>> {
>> FOO_FIRST,
>> FOO_SECOND,
>> FOO_END
>> };
>>
>> int array[FOO_END];
>>
>> Once this is compiled into binary, what libabigail is going to see by
>> analyzing the binary is that 'array' is an array of 2 integers. The
>> information about the size of the array being initially an enumerator
>> value is lost. To detect that, you need source level analysis.
>>
>> But then, by reviewing the code, this is a construct that you can spot
>> and allow or forbid, depending on your goals as a project.
>>
> In the above example if in newer library a FOO_THIRD is added.
> FOO_END value will change and will cause ABI break for change in existing value.
> But if we replace it with inline function to get the list_end and use it in array like below.
> So if FOO_THIRD is added, we will also update foo_enum_list_end() function to return (FOO_THIRD+1)
>
> enum foo_enum
> {
> FOO_FIRST,
> FOO_SECOND,
> };
> static inline int foo_enum_list_end()
> {
> return FOO_SECOND + 1;
> }
> int array[foo_enum_list_end()];
>
> Will this cause an ABI break if we add this array in application or in library?
I think this (inline function) construct is essentially the same as just
adding a FOO_END enumerator after FOO_SECOND. Using either
foo_enum_list_end() or FOO_END result in having the value '2' in the
application using the library to get FOO_END or foo_enum_list_end().
Newer versions of the library being linked to the application won't
change that value '2', regardless of the newer values of FOO_END or
foo_enum_list_end().
So, adding a FOO_THIRD right after FOO_END, induces and ABI change.
This change being "breaking" (incompatible) or not, really depends on
what the application expects, I would say. Sorry if that looks "vague",
but this whole concept is quite blurry.
For instance, if you add FOO_THIRD after FOO_SECOND in the newer version
of the library and the application still gets the value '2' rather than
getting the value '3', and that value is actually multiplied by "two
trillions" in the application to get the value of the dividend to be
payed to investors, then, then that's a very big error induced by that
change. That might be considered by the application as a "breaking" ABI
change and you might get a call or two from the CEO of an S&P500 company
that uses the library.
Other applications might consider that "off-by-one" error not being
problematic at all and thus might consider it not "breaking".
Note that REMOVING an enumerator however is always considered an
incompatible (breaking) ABI change.
Adding an enumerator however has this annoying "grey topic" (not black or
white) property that I am not sure how to address at this point.
Cheers,
Akhil Goyal <gakhil@marvell.com> writes:
>> >>> Now added inline APIs for getting the list end which need to be updated
>> >>> for each new entry to the enum. This shall help in avoiding ABI break
>> >>> for adding new algo.
>> >>>
>> >>
>> >> Hi Akhil,
>> >>
>> >> *I think* this hides the problem instead of fixing it, and this may be
>> >> partially because of the tooling (libabigail) limitation.
>> >>
>> >> This patch prevents the libabigail warning, true, but it doesn't improve
>> >> anything from the application's perspective.
>> >> Before or after this patch, application knows a fixed value as END value.
>> >>
>> >> Not all changes in the END (MAX) enum values cause ABI break, but tool
>> >> warns on all, that is why I think this may be tooling limitation [1].
>> >> (Just to stress, I am NOT talking about regular enum values change, I am
>> >> talking about only END (MAX) value changes caused by appending new enum
>> >> items.)
>> >>
>> >> As far as I can see (please Dodji, David correct me if I am wrong) ABI
>> >> break only happens if application and library exchange enum values in
>> >> the API (directly or within a struct).
>> >
>> > - There is also the following issue:
>> > A library publicly exports an array sized against a END (MAX) enum in the API.
>> > https://developers.redhat.com/blog/2019/05/06/how-c-array-sizes-become-part-of-the-binary-interface-of-a-library
>> >
>>
>> I see. And Dodji explained this requires source code to detect.
>>
>> I don't remember seeing a public array whose size is defined by an enum,
>> are you aware of any instance of this usage?
>
> https://patches.dpdk.org/project/dpdk/patch/20241009071151.1106-1-gmuthukrishn@marvell.com/
> This was merged yesterday.
I guess the problematic piece of the code is this:
diff --git a/lib/cryptodev/rte_cryptodev.h
b/lib/cryptodev/rte_cryptodev.h
index bec947f6d5..aa6ef3a94d 100644
--- a/lib/cryptodev/rte_cryptodev.h
+++ b/lib/cryptodev/rte_cryptodev.h
@@ -185,6 +185,9 @@ struct rte_cryptodev_asymmetric_xform_capability {
* Value 0 means unavailable, and application should pass the
required
* random value. Otherwise, PMD would internally compute
the random number.
*/
+
+ uint32_t op_capa[RTE_CRYPTO_ASYM_OP_LIST_END];
+ /**< Operation specific capabilities. */
};
Is it possible for the struct rte_cryptodev_asymmetric_xform_capability
to be made an opaque struct which definition would be present only in a
.c file of the library?
Its data members would then be retrieved by getter functions that take a
pointer to that struct in parameter.
That way, the uint32_t op_capa[RTE_CRYPTO_ASYM_OP_LIST_END] data member
would be "private" to the .c file and thus would not be part of the
ABI. Any change to the RTE_CRYPTO_ASYM_OP enum would then become
harmless to that struct.
I hope this helps.
@@ -581,7 +581,7 @@ static inline void print_asym_capa(
rte_cryptodev_asym_get_xform_string(capa->xform_type));
printf("operation supported -");
- for (i = 0; i < RTE_CRYPTO_ASYM_OP_LIST_END; i++) {
+ for (i = 0; i < rte_crypto_asym_op_list_end(); i++) {
/* check supported operations */
if (rte_cryptodev_asym_xform_capability_check_optype(capa, i)) {
if (capa->xform_type == RTE_CRYPTO_ASYM_XFORM_DH)
@@ -72,6 +72,7 @@ enum rte_crypto_curve_id {
* Asymmetric crypto transformation types.
* Each xform type maps to one asymmetric algorithm
* performing specific operation
+ * Note: Update rte_crypto_asym_xform_type_list_end() for every new type added.
*/
enum rte_crypto_asym_xform_type {
RTE_CRYPTO_ASYM_XFORM_UNSPECIFIED = 0,
@@ -119,12 +120,17 @@ enum rte_crypto_asym_xform_type {
* Performs Encrypt, Decrypt, Sign and Verify.
* Refer to rte_crypto_asym_op_type.
*/
- RTE_CRYPTO_ASYM_XFORM_TYPE_LIST_END
- /**< End of list */
};
+static inline int
+rte_crypto_asym_xform_type_list_end(void)
+{
+ return RTE_CRYPTO_ASYM_XFORM_SM2 + 1;
+}
+
/**
* Asymmetric crypto operation type variants
+ * Note: Update rte_crypto_asym_op_list_end for every new type added.
*/
enum rte_crypto_asym_op_type {
RTE_CRYPTO_ASYM_OP_ENCRYPT,
@@ -135,9 +141,14 @@ enum rte_crypto_asym_op_type {
/**< Signature Generation operation */
RTE_CRYPTO_ASYM_OP_VERIFY,
/**< Signature Verification operation */
- RTE_CRYPTO_ASYM_OP_LIST_END
};
+static inline int
+rte_crypto_asym_op_list_end(void)
+{
+ return RTE_CRYPTO_ASYM_OP_VERIFY + 1;
+}
+
/**
* Asymmetric crypto key exchange operation type
*/
@@ -168,7 +179,6 @@ enum rte_crypto_rsa_padding_type {
/**< RSA PKCS#1 OAEP padding scheme */
RTE_CRYPTO_RSA_PADDING_PSS,
/**< RSA PKCS#1 PSS padding scheme */
- RTE_CRYPTO_RSA_PADDING_TYPE_LIST_END
};
/**