[RFC] lib/cryptodev: update API documentation for aux_flags

[RFC] lib/cryptodev: update API documentation for aux_flags

[Radu Nicolau]

Update the API documentation description of rte_crypto_op field
aux_flags as to allow PMDs to define driver-specific flags.

Signed-off-by: Radu Nicolau <radu.nicolau@intel.com>
---
 lib/cryptodev/rte_crypto.h | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/lib/cryptodev/rte_crypto.h b/lib/cryptodev/rte_crypto.h
index dcf4a36fb2..38c8acbf4c 100644
--- a/lib/cryptodev/rte_crypto.h
+++ b/lib/cryptodev/rte_crypto.h
@@ -116,6 +116,10 @@ struct rte_crypto_op {
 			 * the status is RTE_CRYPTO_OP_STATUS_SUCCESS.
 			 * In case of errors, the value of this field is undefined.
 			 *
+			 * In addition to RTE_CRYPTO_OP_AUX_FLAGS_* the PMDs can define
+			 * their own optional auxiliary flags as needed, set by the
+			 * application and to be used for driver-specific purposes.
+			 *
 			 * With TLS record offload (RTE_SECURITY_PROTOCOL_TLS_RECORD),
 			 * application may provide the extra padding required for the plaintext
 			 * provided. This field can be used for passing the same in units of 8B.
-- 
2.50.1

RE: [EXTERNAL] [RFC] lib/cryptodev: update API documentation for aux_flags

[Akhil Goyal]

Hi Radu,

> Update the API documentation description of rte_crypto_op field
> aux_flags as to allow PMDs to define driver-specific flags.

Can you give examples of the flags that you want to add for driver specific work?
I believe adding driver specific things here may not be good.
May be we can discuss the specific flags and define them as common for all PMDs.


> 
> Signed-off-by: Radu Nicolau <radu.nicolau@intel.com>
> ---
>  lib/cryptodev/rte_crypto.h | 4 ++++
>  1 file changed, 4 insertions(+)
> 
> diff --git a/lib/cryptodev/rte_crypto.h b/lib/cryptodev/rte_crypto.h
> index dcf4a36fb2..38c8acbf4c 100644
> --- a/lib/cryptodev/rte_crypto.h
> +++ b/lib/cryptodev/rte_crypto.h
> @@ -116,6 +116,10 @@ struct rte_crypto_op {
>  			 * the status is RTE_CRYPTO_OP_STATUS_SUCCESS.
>  			 * In case of errors, the value of this field is undefined.
>  			 *
> +			 * In addition to RTE_CRYPTO_OP_AUX_FLAGS_* the
> PMDs can define
> +			 * their own optional auxiliary flags as needed, set by
> the
> +			 * application and to be used for driver-specific
> purposes.
> +			 *
>  			 * With TLS record offload
> (RTE_SECURITY_PROTOCOL_TLS_RECORD),
>  			 * application may provide the extra padding required for
> the plaintext
>  			 * provided. This field can be used for passing the same
> in units of 8B.
> --
> 2.50.1

Re: [EXTERNAL] [RFC] lib/cryptodev: update API documentation for aux_flags

[Radu Nicolau]

Hi Akhil,

Thanks for looking at this.

On 12-Sep-25 2:05 PM, Akhil Goyal wrote:
> Hi Radu,
>
>> Update the API documentation description of rte_crypto_op field
>> aux_flags as to allow PMDs to define driver-specific flags.
> Can you give examples of the flags that you want to add for driver specific work?
> I believe adding driver specific things here may not be good.
> May be we can discuss the specific flags and define them as common for all PMDs.

The flags we have in mind are very PMD specific i.e. controlling 
specific hardware behavior so they will not be suitable to be added to 
the common flags.

Seeing that aux_flags are not that strongly defined and seeing that they 
are already potentially used for PMD specific values my reasoning was to 
formalize this possibility of usage

aux_flags are used here to potentially carry a value that is not covered 
in the common API aux_flags definitions:

https://git.dpdk.org/dpdk/tree/drivers/crypto/cnxk/cn20k_cryptodev_ops.c#n857


Regards,

Radu

RE: [EXTERNAL] [RFC] lib/cryptodev: update API documentation for aux_flags

[Akhil Goyal]

> On 12-Sep-25 2:05 PM, Akhil Goyal wrote:
> > Hi Radu,
> >
> >> Update the API documentation description of rte_crypto_op field
> >> aux_flags as to allow PMDs to define driver-specific flags.
> > Can you give examples of the flags that you want to add for driver specific
> work?
> > I believe adding driver specific things here may not be good.
> > May be we can discuss the specific flags and define them as common for all
> PMDs.
> 
> The flags we have in mind are very PMD specific i.e. controlling
> specific hardware behavior so they will not be suitable to be added to
> the common flags.
> 
> Seeing that aux_flags are not that strongly defined and seeing that they
> are already potentially used for PMD specific values my reasoning was to
> formalize this possibility of usage
> 
> aux_flags are used here to potentially carry a value that is not covered
> in the common API aux_flags definitions:
> 
> https://git.dpdk.org/dpdk/tree/drivers/crypto/cnxk/cn20k_cryptodev_ops.c#n857
> 
The aux flags that are currently defined are for soft expiry(out param) and TLS padding(in param).
These are not PMD specific and are defined as generic flags passed by application
 Or getting more info about the crypto operation such as soft expiry which is not an error
but will be useful for application to trigger rekeying in advance.

In your case, these flags need to be exposed if application is required to set.
And we cannot define pmd specific flags in rte_crypto.h.
Please specify use case if it can be useful for other PMDs also and we can add another flag.

For PMD specific flags, is it not possible for you to use mbuf dynamic fields if it is an IPsec case?
Or we can also explore to introduce dynfields in crypto_op.

In above link, cop->aux_flags = res->uc_compcode;
is set to give debug information to application, as warning codes are not exposed in crypto_op status.
Application is not required to take any action based on the values other than the ones defined in rte_crypto.h.

-Akhil

Re: [EXTERNAL] [RFC] lib/cryptodev: update API documentation for aux_flags

[Radu Nicolau]

On 12-Sep-25 3:56 PM, Akhil Goyal wrote:
>> On 12-Sep-25 2:05 PM, Akhil Goyal wrote:
>>> Hi Radu,
>>>
>>>> Update the API documentation description of rte_crypto_op field
>>>> aux_flags as to allow PMDs to define driver-specific flags.
>>> Can you give examples of the flags that you want to add for driver specific
>> work?
>>> I believe adding driver specific things here may not be good.
>>> May be we can discuss the specific flags and define them as common for all
>> PMDs.
>>
>> The flags we have in mind are very PMD specific i.e. controlling
>> specific hardware behavior so they will not be suitable to be added to
>> the common flags.
>>
>> Seeing that aux_flags are not that strongly defined and seeing that they
>> are already potentially used for PMD specific values my reasoning was to
>> formalize this possibility of usage
>>
>> aux_flags are used here to potentially carry a value that is not covered
>> in the common API aux_flags definitions:
>>
>> https://git.dpdk.org/dpdk/tree/drivers/crypto/cnxk/cn20k_cryptodev_ops.c#n857
>>
> The aux flags that are currently defined are for soft expiry(out param) and TLS padding(in param).
> These are not PMD specific and are defined as generic flags passed by application
>   Or getting more info about the crypto operation such as soft expiry which is not an error
> but will be useful for application to trigger rekeying in advance.
>
> In your case, these flags need to be exposed if application is required to set.
The application is not required to set these flags, the RFC change 
specifically states "optional auxiliary flags".
> And we cannot define pmd specific flags in rte_crypto.h.
> Please specify use case if it can be useful for other PMDs also and we can add another flag.
>
> For PMD specific flags, is it not possible for you to use mbuf dynamic fields if it is an IPsec case?
> Or we can also explore to introduce dynfields in crypto_op.
Yes, we can use dynfields and we can explore adding them to the crypto 
op, but since we already have these flags we can make use of them.
>
> In above link, cop->aux_flags = res->uc_compcode;
> is set to give debug information to application, as warning codes are not exposed in crypto_op status.
> Application is not required to take any action based on the values other than the ones defined in rte_crypto.h.
My proposal is very similar to this use case, just in the other 
direction. The PMD is not required to take any action on the value of 
aux_flags, and the application is not required to set anything.
>
> -Akhil

RE: [EXTERNAL] [RFC] lib/cryptodev: update API documentation for aux_flags

[Akhil Goyal]

> 
> On 12-Sep-25 3:56 PM, Akhil Goyal wrote:
> >> On 12-Sep-25 2:05 PM, Akhil Goyal wrote:
> >>> Hi Radu,
> >>>
> >>>> Update the API documentation description of rte_crypto_op field
> >>>> aux_flags as to allow PMDs to define driver-specific flags.
> >>> Can you give examples of the flags that you want to add for driver specific
> >> work?
> >>> I believe adding driver specific things here may not be good.
> >>> May be we can discuss the specific flags and define them as common for all
> >> PMDs.
> >>
> >> The flags we have in mind are very PMD specific i.e. controlling
> >> specific hardware behavior so they will not be suitable to be added to
> >> the common flags.
> >>
> >> Seeing that aux_flags are not that strongly defined and seeing that they
> >> are already potentially used for PMD specific values my reasoning was to
> >> formalize this possibility of usage
> >>
> >> aux_flags are used here to potentially carry a value that is not covered
> >> in the common API aux_flags definitions:
> >>
> >> https://git.dpdk.org/dpdk/tree/drivers/crypto/cnxk/cn20k_cryptodev_ops.c#n857
> >>
> > The aux flags that are currently defined are for soft expiry(out param) and TLS
> padding(in param).
> > These are not PMD specific and are defined as generic flags passed by
> application
> >   Or getting more info about the crypto operation such as soft expiry which is not
> an error
> > but will be useful for application to trigger rekeying in advance.
> >
> > In your case, these flags need to be exposed if application is required to set.
> The application is not required to set these flags, the RFC change
> specifically states "optional auxiliary flags".

Even if it is optional, application need to set them in your case. Right?
So some macros need to be there which application can set.

> > And we cannot define pmd specific flags in rte_crypto.h.
> > Please specify use case if it can be useful for other PMDs also and we can add
> another flag.
> >
> > For PMD specific flags, is it not possible for you to use mbuf dynamic fields if it is
> an IPsec case?
> > Or we can also explore to introduce dynfields in crypto_op.
> Yes, we can use dynfields and we can explore adding them to the crypto
> op, but since we already have these flags we can make use of them.

Aux flags are basically used for common things which PMDs and applications can use.
Dynfields in mbuf are vendor specific fields. It can be a good option in your case and
would be useful for other PMDs also.

> >
> > In above link, cop->aux_flags = res->uc_compcode;
> > is set to give debug information to application, as warning codes are not
> exposed in crypto_op status.
> > Application is not required to take any action based on the values other than
> the ones defined in rte_crypto.h.
> My proposal is very similar to this use case, just in the other
> direction. The PMD is not required to take any action on the value of
> aux_flags, and the application is not required to set anything.

The main issue is direction.
If application is required to set some value for your specific case, it need to be defined in cryptodev.
But if application is getting extra information, it can ignore it and use only the one which is defined and useful.