Re: [dpdk-dev] [PATCH v3 10/10] doc: add mempool and octeontx mempool device

[Thomas Monjalon <thomas@monjalon.net>]

18/10/2017 16:36, Jerin Jacob:
> From: santosh <santosh.shukla@caviumnetworks.com>
> > 
> > On Wednesday 18 October 2017 07:15 PM, Thomas Monjalon wrote:
> > > 18/10/2017 14:17, santosh:
> > >> Hi Thomas,
> > >>
> > >>
> > >> On Monday 09 October 2017 02:49 PM, santosh wrote:
> > >>> On Monday 09 October 2017 02:18 PM, Thomas Monjalon wrote:
> > >>>> 09/10/2017 07:46, santosh:
> > >>>>> On Monday 09 October 2017 10:31 AM, santosh wrote:
> > >>>>>> Hi Thomas,
> > >>>>>>
> > >>>>>>
> > >>>>>> On Sunday 08 October 2017 10:13 PM, Thomas Monjalon wrote:
> > >>>>>>> 08/10/2017 14:40, Santosh Shukla:
> > >>>>>>>> This commit adds a section to the docs listing the mempool
> > >>>>>>>> device PMDs available.
> > >>>>>>> It is confusing to add a mempool guide, given that we already have
> > >>>>>>> a mempool section in the programmer's guide:
> > >>>>>>> 	http://dpdk.org/doc/guides/prog_guide/mempool_lib.html
> > >>>>>>>
> > >>>>>>> And we will probably need also some doc for bus drivers.
> > >>>>>>>
> > >>>>>>> I think it would be more interesting to create a platform guide
> > >>>>>>> where you can describe the bus and the mempool.
> > >>>>>>> OK for doc/guides/platform/octeontx.rst ?
> > >>>>>> No Strong opinion,
> > >>>>>>
> > >>>>>> But IMO, purpose of introducing mempool PMD was inspired from
> > >>>>>> eventdev, Which I find pretty organized.
> > >>>>>>
> > >>>>>> Yes, we have mempool_lib guide but that is more about common mempool
> > >>>>>> layer details like api, structure layout etc.. I wanted
> > >>>>>> to add guide which tells about mempool PMD's and their capability
> > >>>>>> if any, thats why included octeontx as strarter and was thinking
> > >>>>>> that other external-mempool PMDs like dpaa/dpaa2 , sw ring pmd may come
> > >>>>>> later.
> > >>>> Yes sure it is interesting.
> > >>>> The question is to know if mempool drivers make sense in their own guide
> > >>>> or if it's better to group them with all related platform specifics.
> > >>> I vote for keeping them just like Eventdev/cryptodev, 
> > >>> has vendor specific PMD's under one roof.. (has both s/w and hw).
> > >> To be clear and move on to v3 for this patch:
> > >> * Your proposition to mention about mempool block in dir struct like
> > >> doc/guides/platform/octeontx.rst. 
> > >> And right now we have more than one reference for octeontx.rst in dpdk
> > >> example:
> > >> ./doc/guides/nics/octeontx.rst --> NIC
> > >> ./doc/guides/eventdevs/octeontx.rst --> eventdev device
> > >>
> > >> Keeping above order in mind: My current proposal was to introduce doc like eventdev for mempool block.
> > >>
> > >> So now, I am in two mind, Whether I opt your path If so then that should I remove all octeontx.rst reference from dpdk?
> > > I think we must keep octeontx.rst in nics and eventdevs.
> > >
> > > My proposal was to have a platform guide to give more explanations
> > > about the common hardware and bus design.
> > 
> > That way, event device also a common hw block.. just like mempool block is
> > for octeontx platform. Also PCI bus is octeontx bus.. we don;t have platform
> > specific bus like dpaa has, so bus stuff not applicable to octeontx doc(imo).
> > 
> > > Some infos for tuning Intel platforms are in the quick start guide,
> > > and could be moved later in such a platform guide.
> > >
> > > With this suggestion, we can include mempool drivers in the
> > > platform guide as mempool is really specific to the platform.
> > >
> > > I thought you agreed on it when talking on IRC.
> > 
> > yes, we did discussed on IRC. But I'm still unsure about scope of that guide 
> > from octeontx perspective: That new platform entry has info about only one block
> > which is mempool and for other common block or specific blocks : 
> > user has to look around at different directories.. 
> > 
> > >> and bundle them under one roof OR go by my current proposal.
> > >>
> > >> Who'll take a call on that?
> > > If you strongly feel that mempool driver is better outside,
> > 
> > I don't have strong opinion on doc.. I'm just asking for more opinions here..
> 
> Combining both proposal. How about,
> 1) Create ./doc/guides/mempool/octeontx.rst to capture octeontx mempool
> specific information.(Which is inline with driver/ hierarchy).
> 2) Create a platform specific document(say doc/guides/platform/octeontx.rst)
> - We can use this file to capture information about the common content
> between the three separate documents(doc/guides/nics/octeontx.rst,
> ./doc/guides/eventdevs/octeontx.rst and ./doc/guides/mempool/octeontx.rst) and
> give reference to common file instead of duplicating the information in
> driver documentation.
> 
> Thomas, John,
> 
> Thoughts?

This is one of the two options I described in my last email.
Our emails have crossed in the air :)

The other option is to merge the mempool guide in the platform guide,
assuming that a hardware mempool cannot be used with another platform,
and assuming that the platform guide will give the big picture about
memory addressing and capabilities, overlapping with mempool section.

I am OK with both options.