[dpdk-dev] [PATCH] doc/event: improve eventdev library documentation

[Honnappa Nagarahalli]

-----Original Message-----
> Date: Tue, 5 Jun 2018 20:32:39 +0000
> From: Honnappa Nagarahalli <Honnappa.Nagarahalli at arm.com>
> To: "Van Haaren, Harry" <harry.van.haaren at intel.com>, Jerin Jacob 
> <jerin.jacob at caviumnetworks.com>
> CC: "dev at dpdk.org" <dev at dpdk.org>
> Subject: RE: [PATCH] doc/event: improve eventdev library documentation
> 
> 
> 
> -----Original Message-----
> From: Van Haaren, Harry <harry.van.haaren at intel.com>
> Sent: Tuesday, June 5, 2018 11:31 AM
> To: Jerin Jacob <jerin.jacob at caviumnetworks.com>; Honnappa Nagarahalli 
> <Honnappa.Nagarahalli at arm.com>
> Cc: dev at dpdk.org
> Subject: RE: [PATCH] doc/event: improve eventdev library documentation
> 
> > From: Jerin Jacob [mailto:jerin.jacob at caviumnetworks.com]
> > Sent: Monday, June 4, 2018 5:42 AM
> > To: Honnappa Nagarahalli <honnappa.nagarahalli at arm.com>
> > Cc: dev at dpdk.org; Van Haaren, Harry <harry.van.haaren at intel.com>
> > Subject: Re: [PATCH] doc/event: improve eventdev library 
> > documentation
> >
> > -----Original Message-----
> > > Date: Thu, 31 May 2018 15:23:42 -0500
> > > From: Honnappa Nagarahalli <honnappa.nagarahalli at arm.com>
> > > To: jerin.jacob at caviumnetworks.com
> > > CC: dev at dpdk.org, Honnappa Nagarahalli 
> > > <honnappa.nagarahalli at arm.com>
> > > Subject: [PATCH] doc/event: improve eventdev library documentation
> > > X-Mailer: git-send-email 2.7.4
> > >
> > > Add small amount of additional code, use consistent variable names 
> > > across code blocks, change the image to represent queues and CPU 
> > > cores intuitively. These help improve the eventdev library 
> > > documentation.
> > >
> > > Signed-off-by: Honnappa Nagarahalli <honnappa.nagarahalli at arm.com>
> > > Reviewed-by: Gavin Hu <gavin.hu at arm.com>
> > > ---
> >
> > Changes looks good to me.
> >
> > Adding Harry for this review as he is the original author of this file.
> 
> Thanks Jerin,
> 
> >> uint16_t nb_rx = rte_event_dequeue_burst(dev_id, worker_port_id1, 
> >> events, BATCH_SIZE, timeout);
> 
> why is the worker port variable named "worker_port_id1"? Previously it was just worker_port_id.
> 
> I think just worker_port_id makes more sense, perhaps update the 2 occurances of id1 ?
> 
> Will change in V2
> 
> With that you have my
> Acked-by: Harry van Haaren <harry.van.haaren at intel.com>
> 
> 
> 
> > >  doc/guides/prog_guide/eventdev.rst           |   55 +-
> > >  doc/guides/prog_guide/img/eventdev_usage.svg | 1518
> > > +++++++++------------
> > -----
> > >  2 files changed, 570 insertions(+), 1003 deletions(-)
> > >
> > > diff --git a/doc/guides/prog_guide/eventdev.rst
> > b/doc/guides/prog_guide/eventdev.rst
> > > index ce19997..0203d9e 100644
> > > --- a/doc/guides/prog_guide/eventdev.rst
> > > +++ b/doc/guides/prog_guide/eventdev.rst
> > > @@ -1,5 +1,6 @@
> > >  ..  SPDX-License-Identifier: BSD-3-Clause
> > >      Copyright(c) 2017 Intel Corporation.
> > > +    Copyright(c) 2018 Arm Limited.
> > >
> > >  Event Device Library
> > >  ====================
> > > @@ -129,7 +130,7 @@ API Walk-through
> > >
> > >  This section will introduce the reader to the eventdev API, 
> > > showing how
> > to
> > >  create and configure an eventdev and use it for a two-stage 
> > > atomic
> > pipeline
> > > -with a single core for TX. The diagram below shows the final 
> > > state of the
> > > +with one core each for RX and TX. The diagram below shows the 
> > > +final state
> > of the
> >
> > I think, we can mention the usage of RX and TX core are API 
> > illustration purpose only, In the real case, it is abstracted using 
> > Eventdev - Ethdev adapters to hide the difference between various 
> > eventdev capabilities to Rx or Tx the packets.
> > or something on similar lines.
> >
> 
> I think we should leave it as is currently, the code under the section 'Ingress of New Events' is tied into RX core. I think the API walk-through section as a whole has to change to introduce the usage of adaptors.

We already have Rx adapter documentation at http://dpdk.org/doc/guides/prog_guide/event_ethernet_rx_adapter.html
My concern is reader gets confused about Rx core and think That way to send the packets in eventdev from ethdev. I think, it will help reader if give pointers about adapter here and mention the Rx and Tx core usage as API illustration purpose only to clarify the existing architecture.

Ok, understood for RX. I do not see anything for TX core, I will leave it out from this clarification. Also TX core should be left out of this since we have to show the single link queue case.

Apologies, I see the TX adapter RFC. I will change the text.

> 
> > >
> > >
> > >  Egress of Events
> > > diff --git a/doc/guides/prog_guide/img/eventdev_usage.svg
> > b/doc/guides/prog_guide/img/eventdev_usage.svg
> > > index 7765649..b0792dc 100644
> > > --- a/doc/guides/prog_guide/img/eventdev_usage.svg
> > > +++ b/doc/guides/prog_guide/img/eventdev_usage.svg
> > > @@ -1,994 +1,546 @@
> > >  <?xml version="1.0" encoding="UTF-8" standalone="no"?>
> >
> > License is missing
> >
> > see doc/guides/prog_guide/img/architecture-overview.svg file as reference.
> >
> > With above changes:
> 
> Will add in V2
> 
> >
> > Acked-by: Jerin Jacob <jerin.jacob at caviumnetworks.com>
> 
> IMPORTANT NOTICE: The contents of this email and any attachments are confidential and may also be privileged. If you are not the intended recipient, please notify the sender immediately and do not disclose the contents to any other person, use it for any purpose, or store or copy the information in any medium. Thank you.