[dpdk-dev] [PATCH v2] doc: add reserve fields to eventdev public structures

[Bruce Richardson]

On Wed, Aug 05, 2020 at 10:18:41AM +0100, Kinsella, Ray wrote:
> 
> 
> On 04/08/2020 18:18, Jerin Jacob wrote:
> > On Tue, Aug 4, 2020 at 9:54 PM Bruce Richardson
> > <bruce.richardson at intel.com> wrote:
> >>
> >> On Tue, Aug 04, 2020 at 09:33:14PM +0530, Jerin Jacob wrote:
> >>> On Tue, Aug 4, 2020 at 7:55 PM Bruce Richardson
> >>> <bruce.richardson at intel.com> wrote:
> >>>>
> >>>> On Tue, Aug 04, 2020 at 05:07:12PM +0530, Jerin Jacob wrote:
> >>>>> On Tue, Aug 4, 2020 at 4:12 PM Bruce Richardson
> >>>>> <bruce.richardson at intel.com> wrote:
> >>>>>>
> >>>>>> On Mon, Aug 03, 2020 at 12:59:03PM +0530, pbhagavatula at marvell.com wrote:
> >>>>>>> From: Pavan Nikhilesh <pbhagavatula at marvell.com>
> >>>>>>>
> >>>>>>> Add 64 byte padding at the end of event device public structure to allow
> >>>>>>> future extensions.
> >>>>>>>
> >>>>>>> Signed-off-by: Pavan Nikhilesh <pbhagavatula at marvell.com>
> >>>>>>> Acked-by: Jerin Jacob <jerinj at marvell.com>
> >>>>>>> ---
> >>>>>>>  v2 Changes:
> >>>>>>>  - Modify commit title.
> >>>>>>>  - Add patch reference to doc.
> >>>>>>>
> >>>>>>>  doc/guides/rel_notes/deprecation.rst | 11 +++++++++++
> >>>>>>>  1 file changed, 11 insertions(+)
> >>>>>>>
> >>>>>>> diff --git a/doc/guides/rel_notes/deprecation.rst b/doc/guides/rel_notes/deprecation.rst
> >>>>>>> index ea4cfa7a4..ec5db68e9 100644
> >>>>>>> --- a/doc/guides/rel_notes/deprecation.rst
> >>>>>>> +++ b/doc/guides/rel_notes/deprecation.rst
> >>>>>>> @@ -151,3 +151,14 @@ Deprecation Notices
> >>>>>>>    Python 2 support will be completely removed in 20.11.
> >>>>>>>    In 20.08, explicit deprecation warnings will be displayed when running
> >>>>>>>    scripts with Python 2.
> >>>>>>> +
> >>>>>>> +* eventdev: A 64 byte padding is added at the end of the following structures
> >>>>>>> +  in event device library to support future extensions:
> >>>>>>> +  ``rte_event_crypto_adapter_conf``, ``rte_event_eth_rx_adapter_conf``,
> >>>>>>> +  ``rte_event_eth_rx_adapter_queue_conf``, ``rte_event_eth_tx_adapter_conf``,
> >>>>>>> +  ``rte_event_timer_adapter_conf``, ``rte_event_timer_adapter_info``,
> >>>>>>> +  ``rte_event_dev_info``, ``rte_event_dev_config``, ``rte_event_queue_conf``,
> >>>>>>> +  ``rte_event_port_conf``, ``rte_event_timer_adapter``,
> >>>>>>> +  ``rte_event_timer_adapter_data``.
> >>>>>>> +  Reference:
> >>>>>>> +  http://patches.dpdk.org/project/dpdk/list/?series=10728&archive=both&state=*
> >>>>>>> --
> >>>>>>
> >>>>>> I don't like this idea of adding lots of padding to the ends of these
> >>>>>> structures. For some structures, such as the public arrays for devices it
> >>>>>> may be necessary, but for all the conf structures passed as parameters to
> >>>>>> functions I think we can do better. Since these structures are passed by
> >>>>>> the user to various functions, function versioning can be used to ensure
> >>>>>> that the correct function in eventdev is always called. From there to the
> >>>>>> individual PMDs, we can implement ABI compatibility by either:
> >>>>>> 1. including the length of the struct as a parameter to the driver. (This is
> >>>>>>   a bit similar to my proposal for rawdev [1])
> >>>>>> 2. including the ABI version as a parameter to the driver.
> >>>>>
> >>>>> But, Will the above solution work if the application is dependent on
> >>>>> struct size?
> >>>>> i.e change of s1 size will change offset of s3 i.e
> >>>>> app_sepecific_struct_s3. Right?
> >>>>> i.e DPDK version should not change the offset of s3. Right?
> >>>>>
> >>>>> example,
> >>>>> struct app_struct {
> >>>>>           struct dpdk_public_struct_s1 s1;
> >>>>>           struct dpdk_public_struct_s2 s2;
> >>>>>           struct app_sepecific_struct_s3 s3;
> >>>>> }
> >>>>>
> >>>> Not sure what exactly you mean here. The actual offsets and sizes of the
> >>>> structs will obviously change as you change the struct, but the end
> >>>> compiled app has no idea of structs, all it knows of is offsets, which is
> >>>> why you provide ABI compatible versions of the functions which use "legacy"
> >>>> copies of the structs to ensure correct offsets. It's pretty much standard
> >>>> practice for ABI versioning.
> >>>
> >>> Currently, We have only function versioning(not structure versioning).
> >>> Are you suggesting having structure versioning?
> >>> Will it complicate the code in terms of readability and supporting multiple
> >>> structure versions aginst its support functions.
> >>>
> >>
> >> We don't, and can't version structures, only functions are versioned.
> >> Even if we do what you suggest and add a block of 64-bytes expansion room
> >> at the end of the structures, how is the function you are calling expected
> >> to know what the structure actually contains? For example, if you add a
> >> field to the end, and reduce the padding by 8 bytes, your structure is
> >> still the same size, and how does the called function know whether X or X+8
> >> bytes are valid in it. Basically, you still need to version all
> >> functions using the structure, just as if you didn't bother extending the
> >> struct.
> > 
> > Yes. We need function versioning for sure if we change the behavior of
> > the function.
> > Is function version + reserved field enough to decode the correct value from
> > the reserved filed from the structure.
> > 
> > My concern is, Let say, we are making the change in structure a->b and
> > function c->d
> > assisted with it.
> > 
> > In the reserved filed case:
> > - struct a remains same(we will adding the fields in reserved filed)
> > - the function will have c and d version and both using struct a
> > 
> > In another scheme:
> > - The application needs to change where versioned function(c or d) need to
> > give associate structure manually. Right? If it is manually, it will
> > be huge change
> > in application. Right?
> > 
> > How an application can express the correct structure mapping?
> > Will it it be like
> > rte_substrem_v21(struct rte_subsystem_conf_v21 *config)?
> > vs
> > rte_substrem_v21(struct rte_subsystem_conf *config)?> where rte_subsystem_conf  has reserved filed.
> 
> So the ABI policy approach for doing this is 
> 
> rte_substrem_v21(struct rte_subsystem_conf_v21 *config)
> 
> instead of 
> 
> rte_substrem_v21(struct rte_subsystem_conf *config) (with extension padding). 
> 
> There are benefits and drawbacks with each approach, these include ... 
> 
> The padding approach assumes you are always happy to tack whatever field you want 
> onto the end of the structure, when in many cases it's more natural home is usually
> in the middle or beginning. Then there is also dead/unused and uninitialized memory, 
> to be conscious of. 
> 
> However what you say is completely correct, if I have a v21 version of the function, 
> only it should be looking at the new field/additional bytes in the structure. 
> 
> The alternative is to version the structure along with the function. 
> And this is what is described in the ABI policy.
> 
> The obvious drawback with this approach is that if you have a structure that is used across
> a large number of functions ... it can be a real headache as they all need to be versioned. 
> 
> The benefit with this approach is that it is completely explicit, 
> which function and structure versions are associated. 
> 

IMHO, the only time we should look to use padding is for structures like
the ethdev structure that are internal-only but used across so many
functions and inline functions that it simply becomes impossible to version
them. For any structures that are simply passed as parameters, which I
believe applies to all structs referred to by this deprecation notice,
function versioning should be sufficient to deal with any issues.

Regards,
/Bruce