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

[Trahe, Fiona]

Hi all,
 
Thanks to feedback from Harry, I've realised that I was only considering applications re-compiled
against the latest DPDK, but without any code rework to use the new feature.  
I hadn't considered pre-compiled applications running against shared libs.
This solution is not sufficient to handle those cases. 
There are many ways an API may change, this was just one small attempt to
minimise the impact of possible future changes.
So will nack this - we'll just deal with them through the usual
deprecation notices, wrappers, etc if and when they arise.

> > > -----Original Message-----
> > > From: Fiona Trahe <fiona.trahe at intel.com>
> > > Sent: Tuesday, August 27, 2019 10:56 PM
> > > To: dev at dpdk.org
> > > Cc: akhil.goyal at nxp.com; Ashish Gupta <ashishg at marvell.com>; Shally
> > > Verma <shallyv at marvell.com>; Fiona Trahe <fiona.trahe at 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 at 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.
> [Fiona] I looked through all API calls and these were the only one I could see. The op, private_xform and
> stream are all handed under the API. But would appreciate a review in case I've missed something.

Nack