[dpdk-dev] [PATCH] doc/cryptodev: clarify that full xform struct should be zeroed before use

[Trahe, Fiona]

Hi Akhil, etc,
Is a deprecation notice necessary for this patch?
If this patch is accepted I will send a follow-up patchset zeroing the xforms in crypto apps.
Fiona

> -----Original Message-----
> From: Trahe, Fiona
> Sent: Wednesday, May 15, 2019 5:37 PM
> To: dev at dpdk.org
> Cc: Trahe, Fiona <fiona.trahe at intel.com>; akhil.goyal at nxp.com; De Lara Guarch, Pablo
> <pablo.de.lara.guarch at intel.com>; Doherty, Declan <declan.doherty at intel.com>; Zhang, Roy Fan
> <roy.fan.zhang at intel.com>; jerinj at marvell.com; Nicolau, Radu <radu.nicolau at intel.com>
> Subject: [PATCH] doc/cryptodev: clarify that full xform struct should be zeroed before use
> 
> Signed-off-by: Fiona Trahe <fiona.trahe at intel.com>
> ---
>  doc/guides/prog_guide/cryptodev_lib.rst |   10 ++++++++--
>  1 files changed, 8 insertions(+), 2 deletions(-)
> 
> diff --git a/doc/guides/prog_guide/cryptodev_lib.rst b/doc/guides/prog_guide/cryptodev_lib.rst
> index 23fa5bc..cc53b25 100644
> --- a/doc/guides/prog_guide/cryptodev_lib.rst
> +++ b/doc/guides/prog_guide/cryptodev_lib.rst
> @@ -497,7 +497,10 @@ Symmetric Crypto transforms (``rte_crypto_sym_xform``) are the mechanism
> used
>  to specify the details of the Crypto operation. For chaining of symmetric
>  operations such as cipher encrypt and authentication generate, the next pointer
>  allows transform to be chained together. Crypto devices which support chaining
> -must publish the chaining of symmetric Crypto operations feature flag.
> +must publish the chaining of symmetric Crypto operations feature flag. Allocation of the
> +xform structure is in the the application domain. To allow future API extensions in a
> +backwardly compatible manner, e.g. addition of a new parameter, the application should
> +zero the full xform struct before populating it.
> 
>  Currently there are three transforms types cipher, authentication and AEAD.
>  Also it is important to note that the order in which the
> @@ -881,7 +884,10 @@ Transforms and Transform Chaining
>  Asymmetric Crypto transforms (``rte_crypto_asym_xform``) are the mechanism used
>  to specify the details of the asymmetric Crypto operation. Next pointer within
>  xform allows transform to be chained together. Also it is important to note that
> -the order in which the transforms are passed indicates the order of the chaining.
> +the order in which the transforms are passed indicates the order of the chaining. Allocation
> +of the xform structure is in the the application domain. To allow future API extensions in a
> +backwardly compatible manner, e.g. addition of a new parameter, the application should
> +zero the full xform struct before populating it.
> 
>  Not all asymmetric crypto xforms are supported for chaining. Currently supported
>  asymmetric crypto chaining is Diffie-Hellman private key generation followed by
> --
> 1.7.0.7