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.tr...@intel.com> > > > Sent: Tuesday, August 27, 2019 10:56 PM > > > To: dev@dpdk.org > > > Cc: akhil.go...@nxp.com; Ashish Gupta <ashi...@marvell.com>; Shally > > > Verma <shal...@marvell.com>; Fiona Trahe <fiona.tr...@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.tr...@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
