[dpdk-dev] [PATCH v6 19/19] doc: update release notes for multi process hotplug

[Zhang, Qi Z]

Hi Anatoly:
	Your comments looks good to me.
Thanks!
Qi 

> -----Original Message-----
> From: Burakov, Anatoly
> Sent: Thursday, June 28, 2018 5:39 PM
> To: Zhang, Qi Z <qi.z.zhang at intel.com>; thomas at monjalon.net
> Cc: Ananyev, Konstantin <konstantin.ananyev at intel.com>; dev at dpdk.org;
> Richardson, Bruce <bruce.richardson at intel.com>; Yigit, Ferruh
> <ferruh.yigit at intel.com>; Shelton, Benjamin H
> <benjamin.h.shelton at intel.com>; Vangati, Narender
> <narender.vangati at intel.com>; Mcnamara, John <john.mcnamara at intel.com>
> Subject: Re: [PATCH v6 19/19] doc: update release notes for multi process
> hotplug
> 
> On 28-Jun-18 2:52 AM, Qi Zhang wrote:
> > Update release notes for the new multi process hotplug feature.
> >
> > Signed-off-by: Qi Zhang <qi.z.zhang at intel.com>
> > ---
> 
> +CC John Mc as our resident native English speaker :)
> 
> >   doc/guides/rel_notes/release_18_08.rst | 21 +++++++++++++++++++++
> >   1 file changed, 21 insertions(+)
> >
> > diff --git a/doc/guides/rel_notes/release_18_08.rst
> > b/doc/guides/rel_notes/release_18_08.rst
> > index bc0124295..fc4736814 100644
> > --- a/doc/guides/rel_notes/release_18_08.rst
> > +++ b/doc/guides/rel_notes/release_18_08.rst
> > @@ -46,6 +46,20 @@ New Features
> >     Flow API support has been added to CXGBE Poll Mode Driver to offload
> >     flows to Chelsio T5/T6 NICs.
> >
> > +* **Support ethernet device hotplug for primary-secondary model.**
> > +
> > +  In primary-secondary process model, ethernet devices are regarded
> > + as shared  by default, attach or detach a device on any process will
> > + broadcast to  other processes through mp channel then device
> > + information will be  synchronzied on all processes. While secondary
> > + process can still attach  or detach a private device (vdev only) with specific
> API.
> 
> Suggested rewording:
> 
> **Support ethdev multiprocess hotplug.**
> 
> Hotplug and hot-unplug for ethdev devices will now be supported in
> multiprocessing scenario. Any ethdev devices created in the primary process
> will be regarded as shared and will be available for all DPDK processes, while
> secondary processes will have a choice between adding a private (non-shared)
> or a shared device. Synchronization between processes will be done using
> DPDK IPC.
> 
> ------
> 
> I hope this is accurate enough, but please correct me if my interpretation of
> the changes is wrong!
> 
> > +
> > +* **Support ethernet device lock.**
> > +
> > +  An ethernet device can be directly or conditionally locked. A
> > + directly  locked device can't be detached, while when try to detach
> > + a conditionally  locked device a pre-registered callback will be
> > + invoked to perform condition  check and decide if it can be detached or
> not.
> 
> Suggested rewording:
> 
> **Support ethernet device locking.**
> 
> Application can now lock an ethernet device to prevent unexpected device
> removal. Devices can either be locked unconditionally, or an application can
> register for a callback before unplug for the purposes of performing cleanup
> before releasing the device (or have a chance to deny unplug).
> 
> >
> >   API Changes
> >   -----------
> > @@ -60,6 +74,13 @@ API Changes
> >      Also, make sure to start the actual text at the margin.
> >      =========================================================
> >
> > +* ethdev: scope of rte_eth_dev_attach and rte_eth_dev_detach is
> extended.
> > +
> > +  In primary-secondary process model, ``rte_eth_dev_attach`` will
> > + guarantee that  device be attached on all processes, if any process
> > + failed to attach, it will  rollback to orignal status.
> 
> IMO no need to mention rollback - these are internal implementation details.
> The main thing is, the device is either attached everywhere, or attached
> nowhere.
> 
>   ``rte_eth_dev_detach`` also guarantee device be
> > +  detached on all processes, if device is locked by any process, it
> > + will roll  back to original status.
> 
> Again, no need to mention internal implementation details - it would be
> sufficient to mention that rte_eth_dev_detach will only succeed if the device is
> not locked by any of the participating processes.
> 
> >
> >   ABI Changes
> >   -----------
> >
> 
> 
> --
> Thanks,
> Anatoly