Re: [dpdk-dev] [PATCH] doc/compressdev: clarify that structs should be zeroed before use

[Shally Verma <shallyv@marvell.com>]

> -----Original Message-----
> From: Fiona Trahe <fiona.trahe@intel.com>
> Sent: Tuesday, August 27, 2019 10:56 PM
> To: dev@dpdk.org
> Cc: akhil.goyal@nxp.com; Ashish Gupta <ashishg@marvell.com>; Shally
> Verma <shallyv@marvell.com>; Fiona Trahe <fiona.trahe@intel.com>
> Subject: [PATCH] doc/compressdev: clarify that structs should be zeroed
> before use
> 
> Some structs used on the API are zeroed on creation by API calls, (e.g.
> rte_comp_op), but a few are allocated in the application domain.
> Clarify that the application should zero those to enable future extensions
> without API breakage.
> 
> Signed-off-by: Fiona Trahe <fiona.trahe@intel.com>
> ---
>  doc/guides/prog_guide/compressdev.rst |   10 ++++++++++
>  1 files changed, 10 insertions(+), 0 deletions(-)
> 
> diff --git a/doc/guides/prog_guide/compressdev.rst
> b/doc/guides/prog_guide/compressdev.rst
> index a089db1..2a85eba 100644
> --- a/doc/guides/prog_guide/compressdev.rst
> +++ b/doc/guides/prog_guide/compressdev.rst
> @@ -76,6 +76,11 @@ The ``rte_compressdev_configure`` API is used to
> configure a compression device.
>  The ``rte_compressdev_config`` structure is used to pass the configuration
> parameters.
> 
> +The allocation of the ``rte_compressdev_config`` struct passed on the
> +API is in the application domain, so to allow future API extensions in
> +a backwardly compatible manner the application should zero this struct,
> +e.g. using sizeof(), before populating it. This allows the addition of new
> parameters to the struct with default value of zero indicating original
> behaviour.
> +
>  See *DPDK API Reference* for details.
> 
>  Configuration of Queue Pairs
> @@ -264,6 +269,11 @@ Compression transforms (``rte_comp_xform``) are
> the mechanism  to specify the details of the compression operation such as
> algorithm,  window size and checksum.
> 
> +The allocation of the ``rte_comp_xform`` struct passed on the API is in
> +the application domain, so to allow future API extensions in a
> +backwardly compatible manner the application should zero this struct,
> +e.g. using sizeof(), before populating it. This allows the addition of new
> parameters to the struct with default value of zero indicating original
> behaviour.
> +
[Shally] Though summary and description looks fine. Only thing to confirm is that this description is applicable only on xform and config structure? And 0s to all field is allowed values.
I have not gone back to refer to latest config and xform structure so take it just a pointer to check on these cases.

Thanks
Shally
>  Compression API Hash support
>  ----------------------------
> 
> --
> 1.7.0.7