[v6,19/19] doc: update release notes for multi process hotplug

  Update release notes for the new multi process hotplug feature.

Signed-off-by: Qi Zhang <qi.z.zhang@intel.com>
---
 doc/guides/rel_notes/release_18_08.rst | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)
  

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@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
>   -----------
>
  

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@intel.com>; thomas@monjalon.net
> Cc: Ananyev, Konstantin <konstantin.ananyev@intel.com>; dev@dpdk.org;
> Richardson, Bruce <bruce.richardson@intel.com>; Yigit, Ferruh
> <ferruh.yigit@intel.com>; Shelton, Benjamin H
> <benjamin.h.shelton@intel.com>; Vangati, Narender
> <narender.vangati@intel.com>; Mcnamara, John <john.mcnamara@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@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