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

  This commit adds a section to the docs listing the mempool
device PMDs available.

It then adds the octeontx fpavf mempool PMD to the listed mempool
devices.

Cc: John McNamara <john.mcnamara@intel.com>

Signed-off-by: Santosh Shukla <santosh.shukla@caviumnetworks.com>
Signed-off-by: Jerin Jacob <jerin.jacob@caviumnetworks.com>
Reviewed-by: John McNamara <john.mcnamara@intel.com>
---
v2 --> v3:
- Incorporated doc review comment (Suggested by John)

 MAINTAINERS                     |   7 +++
 doc/guides/index.rst            |   1 +
 doc/guides/mempool/index.rst    |  40 +++++++++++++
 doc/guides/mempool/octeontx.rst | 130 ++++++++++++++++++++++++++++++++++++++++
 4 files changed, 178 insertions(+)
 create mode 100644 doc/guides/mempool/index.rst
 create mode 100644 doc/guides/mempool/octeontx.rst
  

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 ?

I choose to integrate this series without this last patch.
I mark this patch as rejected.
Please submit a new one separately.

> It then adds the octeontx fpavf mempool PMD to the listed mempool
> devices.
> 
> Cc: John McNamara <john.mcnamara@intel.com>
> 
> Signed-off-by: Santosh Shukla <santosh.shukla@caviumnetworks.com>
> Signed-off-by: Jerin Jacob <jerin.jacob@caviumnetworks.com>
> Reviewed-by: John McNamara <john.mcnamara@intel.com>
> ---
[...]
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -340,6 +340,13 @@ F: drivers/net/liquidio/
>  F: doc/guides/nics/liquidio.rst
>  F: doc/guides/nics/features/liquidio.ini
>  
> +Cavium Octeontx Mempool
> +M: Santosh Shukla <santosh.shukla@caviumnetworks.com>
> +M: Jerin Jacob <jerin.jacob@caviumnetworks.com>
> +F: drivers/mempool/octeontx

A slash is missing at the end of the directory.

Until now, the mempool and bus drivers are listed with net drivers.
We could move them in a platform section later.
For now, let's put it as "Cavium OcteonTX" in net drivers.

I fixed and merged it with the first patch.

> +F: doc/guides/mempool/index.rst

The index must not be part of Octeontx section.

> +F: doc/guides/mempool/octeontx.rst
  

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.

If above said does not make sense then will follow Thomas proposition
and propose a patch.

Thoughts?

> I choose to integrate this series without this last patch.
> I mark this patch as rejected.
> Please submit a new one separately.
>
>> It then adds the octeontx fpavf mempool PMD to the listed mempool
>> devices.
>>
>> Cc: John McNamara <john.mcnamara@intel.com>
>>
>> Signed-off-by: Santosh Shukla <santosh.shukla@caviumnetworks.com>
>> Signed-off-by: Jerin Jacob <jerin.jacob@caviumnetworks.com>
>> Reviewed-by: John McNamara <john.mcnamara@intel.com>
>> ---
> [...]
>> --- a/MAINTAINERS
>> +++ b/MAINTAINERS
>> @@ -340,6 +340,13 @@ F: drivers/net/liquidio/
>>  F: doc/guides/nics/liquidio.rst
>>  F: doc/guides/nics/features/liquidio.ini
>>  
>> +Cavium Octeontx Mempool
>> +M: Santosh Shukla <santosh.shukla@caviumnetworks.com>
>> +M: Jerin Jacob <jerin.jacob@caviumnetworks.com>
>> +F: drivers/mempool/octeontx
> A slash is missing at the end of the directory.
>
> Until now, the mempool and bus drivers are listed with net drivers.
> We could move them in a platform section later.
> For now, let's put it as "Cavium OcteonTX" in net drivers.
>
> I fixed and merged it with the first patch.

Thanks.

IMO, for MAINTAINERS file:
Just like we have entry for "Eventdev Driver" and underneath
to that- all vendor specific PMD sits, I was thinking to
introduce "Mempool Drivers" such that we place all
external mempool PMDs + s/w PMD (example: Ring) sits underneath.

thoughts?

>> +F: doc/guides/mempool/index.rst
> The index must not be part of Octeontx section.
>
>> +F: doc/guides/mempool/octeontx.rst
  

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.
>
> If above said does not make sense then will follow Thomas proposition
> and propose a patch.
>
> Thoughts?
>
Additional input:

mempool PMD logically can work across nics.. could be a reason
to not to mention under platform/octeontx or platform/dpaa ..etc..

IMO, Its worth adding a new section for mempool PMD.

Thoughts?

Regards,

>> I choose to integrate this series without this last patch.
>> I mark this patch as rejected.
>> Please submit a new one separately.
>>
>>> It then adds the octeontx fpavf mempool PMD to the listed mempool
>>> devices.
>>>
>>> Cc: John McNamara <john.mcnamara@intel.com>
>>>
>>> Signed-off-by: Santosh Shukla <santosh.shukla@caviumnetworks.com>
>>> Signed-off-by: Jerin Jacob <jerin.jacob@caviumnetworks.com>
>>> Reviewed-by: John McNamara <john.mcnamara@intel.com>
>>> ---
>> [...]
>>> --- a/MAINTAINERS
>>> +++ b/MAINTAINERS
>>> @@ -340,6 +340,13 @@ F: drivers/net/liquidio/
>>>  F: doc/guides/nics/liquidio.rst
>>>  F: doc/guides/nics/features/liquidio.ini
>>>  
>>> +Cavium Octeontx Mempool
>>> +M: Santosh Shukla <santosh.shukla@caviumnetworks.com>
>>> +M: Jerin Jacob <jerin.jacob@caviumnetworks.com>
>>> +F: drivers/mempool/octeontx
>> A slash is missing at the end of the directory.
>>
>> Until now, the mempool and bus drivers are listed with net drivers.
>> We could move them in a platform section later.
>> For now, let's put it as "Cavium OcteonTX" in net drivers.
>>
>> I fixed and merged it with the first patch.
> Thanks.
>
> IMO, for MAINTAINERS file:
> Just like we have entry for "Eventdev Driver" and underneath
> to that- all vendor specific PMD sits, I was thinking to
> introduce "Mempool Drivers" such that we place all
> external mempool PMDs + s/w PMD (example: Ring) sits underneath.
>
> thoughts?
>
>>> +F: doc/guides/mempool/index.rst
>> The index must not be part of Octeontx section.
>>
>>> +F: doc/guides/mempool/octeontx.rst
  

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.

> > If above said does not make sense then will follow Thomas proposition
> > and propose a patch.
> >
> > Thoughts?
> >
> Additional input:
> 
> mempool PMD logically can work across nics.. could be a reason
> to not to mention under platform/octeontx or platform/dpaa ..etc..

I don't understand. OcteonTx mempool works only on OcteonTX?
Are you saying that OcteonTX can be managed as a device?

> IMO, Its worth adding a new section for mempool PMD.
> 
> Thoughts?
> 
> Regards,
> 
> >> I choose to integrate this series without this last patch.
> >> I mark this patch as rejected.
> >> Please submit a new one separately.
> >>
> >>> It then adds the octeontx fpavf mempool PMD to the listed mempool
> >>> devices.
> >>>
> >>> Cc: John McNamara <john.mcnamara@intel.com>
> >>>
> >>> Signed-off-by: Santosh Shukla <santosh.shukla@caviumnetworks.com>
> >>> Signed-off-by: Jerin Jacob <jerin.jacob@caviumnetworks.com>
> >>> Reviewed-by: John McNamara <john.mcnamara@intel.com>
> >>> ---
> >> [...]
> >>> --- a/MAINTAINERS
> >>> +++ b/MAINTAINERS
> >>> @@ -340,6 +340,13 @@ F: drivers/net/liquidio/
> >>>  F: doc/guides/nics/liquidio.rst
> >>>  F: doc/guides/nics/features/liquidio.ini
> >>>  
> >>> +Cavium Octeontx Mempool
> >>> +M: Santosh Shukla <santosh.shukla@caviumnetworks.com>
> >>> +M: Jerin Jacob <jerin.jacob@caviumnetworks.com>
> >>> +F: drivers/mempool/octeontx
> >> A slash is missing at the end of the directory.
> >>
> >> Until now, the mempool and bus drivers are listed with net drivers.
> >> We could move them in a platform section later.
> >> For now, let's put it as "Cavium OcteonTX" in net drivers.
> >>
> >> I fixed and merged it with the first patch.
> > Thanks.
> >
> > IMO, for MAINTAINERS file:
> > Just like we have entry for "Eventdev Driver" and underneath
> > to that- all vendor specific PMD sits, I was thinking to
> > introduce "Mempool Drivers" such that we place all
> > external mempool PMDs + s/w PMD (example: Ring) sits underneath.
> >
> > thoughts?

No need to move SW mempool drivers in a different section.
They are maintained by Olivier with the mempool core code.

I have the feeling that all platform specific stuff
(bus, mempool, makefile and config file) are maintained by
the same persons.
I think it is easier to know who contact for issues with a platform.
  

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).

>>> If above said does not make sense then will follow Thomas proposition
>>> and propose a patch.
>>>
>>> Thoughts?
>>>
>> Additional input:
>>
>> mempool PMD logically can work across nics.. could be a reason
>> to not to mention under platform/octeontx or platform/dpaa ..etc..
> I don't understand. OcteonTx mempool works only on OcteonTX?

Can work on other external PCI-e nics though current pmd don;t support.

> Are you saying that OcteonTX can be managed as a device?
>
Yes.
For example:
We have standalone test application for mempool for test purpose,
so to test standlone mempool device, right?
if user gives ]octeontx_fpavf' pool handle
then test works just like for s/w ring.

BTW: HW mempool offload behaves just like ring for example,
Only difference buffer mgmt is ofloaded. Having said that
In theory, offload mempool driver Or s/w pool driver should be agnostic.
(my 2 cents).

Thanks.

>> IMO, Its worth adding a new section for mempool PMD.
>>
>> Thoughts?
>>
>> Regards,
>>
>>>> I choose to integrate this series without this last patch.
>>>> I mark this patch as rejected.
>>>> Please submit a new one separately.
>>>>
>>>>> It then adds the octeontx fpavf mempool PMD to the listed mempool
>>>>> devices.
>>>>>
>>>>> Cc: John McNamara <john.mcnamara@intel.com>
>>>>>
>>>>> Signed-off-by: Santosh Shukla <santosh.shukla@caviumnetworks.com>
>>>>> Signed-off-by: Jerin Jacob <jerin.jacob@caviumnetworks.com>
>>>>> Reviewed-by: John McNamara <john.mcnamara@intel.com>
>>>>> ---
>>>> [...]
>>>>> --- a/MAINTAINERS
>>>>> +++ b/MAINTAINERS
>>>>> @@ -340,6 +340,13 @@ F: drivers/net/liquidio/
>>>>>  F: doc/guides/nics/liquidio.rst
>>>>>  F: doc/guides/nics/features/liquidio.ini
>>>>>  
>>>>> +Cavium Octeontx Mempool
>>>>> +M: Santosh Shukla <santosh.shukla@caviumnetworks.com>
>>>>> +M: Jerin Jacob <jerin.jacob@caviumnetworks.com>
>>>>> +F: drivers/mempool/octeontx
>>>> A slash is missing at the end of the directory.
>>>>
>>>> Until now, the mempool and bus drivers are listed with net drivers.
>>>> We could move them in a platform section later.
>>>> For now, let's put it as "Cavium OcteonTX" in net drivers.
>>>>
>>>> I fixed and merged it with the first patch.
>>> Thanks.
>>>
>>> IMO, for MAINTAINERS file:
>>> Just like we have entry for "Eventdev Driver" and underneath
>>> to that- all vendor specific PMD sits, I was thinking to
>>> introduce "Mempool Drivers" such that we place all
>>> external mempool PMDs + s/w PMD (example: Ring) sits underneath.
>>>
>>> thoughts?
> No need to move SW mempool drivers in a different section.
> They are maintained by Olivier with the mempool core code.
>
> I have the feeling that all platform specific stuff
> (bus, mempool, makefile and config file) are maintained by
> the same persons.
> I think it is easier to know who contact for issues with a platform.
  

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?
and bundle them under one roof OR go by my current proposal.

Who'll take a call on that?

Thanks.
  

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

> 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,
you can make it outside in a mempool guide.
John do you have an opinion?
  

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..
as I'm not fully convinced with your proposition.

> you can make it outside in a mempool guide.
> John do you have an opinion?
>
  

18/10/2017 16:02, santosh:
> 
> 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).

Right.

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

Right.
You can point to other sections in the platform guide.
From platform/octeontx.rst, you can point to eventdev/octeontx.rst,
nics/octeontx.rst and mempool/octeontx.rst (if you add it).

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

Me too, I'm asking for more opinions.

> as I'm not fully convinced with your proposition.

I am convinced we must create a platform guide.
But I am not convinced about where put the mempool section:
either directly in the platform guide,
or in a new mempool guide which is referenced from the platform guide.

> > you can make it outside in a mempool guide.
> > John do you have an opinion?

If we do not have more opinions, do as you feel.
Anyway it will be possible to change it later if needed.
  

-----Original Message-----
> Date: Wed, 18 Oct 2017 19:32:44 +0530
> From: santosh <santosh.shukla@caviumnetworks.com>
> To: Thomas Monjalon <thomas@monjalon.net>, John McNamara
>  <john.mcnamara@intel.com>
> Cc: dev@dpdk.org, olivier.matz@6wind.com, jerin.jacob@caviumnetworks.com,
>  hemant.agrawal@nxp.com, ferruh.yigit@intel.com
> Subject: Re: [dpdk-dev] [PATCH v3 10/10] doc: add mempool and octeontx
>  mempool device
> User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:45.0) Gecko/20100101
>  Thunderbird/45.5.1
> 
> 
> 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?


> as I'm not fully convinced with your proposition.
> 
> > you can make it outside in a mempool guide.
> > John do you have an opinion?
> >
>
  

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.
  

Patch 1: Introduce platform/ entry in guide. That has information about
platform drivers. ( As per discussion[1])
Patch 2: Introduce mempool/ entry in guide. (Refer discussion[1])
Patch 3: Misc Fix for nic/octeontx.rst

Thanks.

[1] http://dpdk.org/dev/patchwork/patch/29893/


Santosh Shukla (3):
  doc: add platform device
  doc: add mempool and octeontx mempool device
  doc: use correct mempool ops handle name

 doc/guides/eventdevs/octeontx.rst |  28 +---------
 doc/guides/index.rst              |   2 +
 doc/guides/mempool/index.rst      |  40 +++++++++++++++
 doc/guides/mempool/octeontx.rst   | 104 ++++++++++++++++++++++++++++++++++++++
 doc/guides/nics/octeontx.rst      |  31 +-----------
 doc/guides/platform/index.rst     |  40 +++++++++++++++
 doc/guides/platform/octeontx.rst  |  78 ++++++++++++++++++++++++++++
 7 files changed, 267 insertions(+), 56 deletions(-)
 create mode 100644 doc/guides/mempool/index.rst
 create mode 100644 doc/guides/mempool/octeontx.rst
 create mode 100644 doc/guides/platform/index.rst
 create mode 100644 doc/guides/platform/octeontx.rst
  

> -----Original Message-----
> From: Santosh Shukla [mailto:santosh.shukla@caviumnetworks.com]
> Sent: Friday, October 20, 2017 4:21 PM
> To: dev@dpdk.org
> Cc: thomas@monjalon.net; jerin.jacob@caviumnetworks.com; Mcnamara, John
> <john.mcnamara@intel.com>; Santosh Shukla
> <santosh.shukla@caviumnetworks.com>
> Subject: [PATCH v4 0/3] Octeontx doc misc
> 
> Patch 1: Introduce platform/ entry in guide. That has information about
> platform drivers. ( As per discussion[1]) Patch 2: Introduce mempool/
> entry in guide. (Refer discussion[1]) Patch 3: Misc Fix for
> nic/octeontx.rst
> 

Hi,

I may be missing context from other patches/emails but what is a Platform Device Driver?

John
  

20/10/2017 18:07, Mcnamara, John:
> From: Santosh Shukla [mailto:santosh.shukla@caviumnetworks.com]
> > Patch 1: Introduce platform/ entry in guide. That has information about
> > platform drivers. ( As per discussion[1]) Patch 2: Introduce mempool/
> > entry in guide. (Refer discussion[1]) Patch 3: Misc Fix for
> > nic/octeontx.rst
> > 
> 
> Hi,
> 
> I may be missing context from other patches/emails but what is a Platform Device Driver?

The idea is to add a guide for platforms (x86, Power8, DPAA, DPAA2, ThunderX, OcteonTX, Armada).
We could move the x86 tuning from the QSG to this platform guide.
For the SoCs, it is also a good way to reference docs for the drivers related to the platform.

Santosh, I know you like referencing previous discussions. It's good.
It should not prevent you from doing a summary where needed :)

Thanks for bringing this idea to live.
  

> -----Original Message-----
> From: Thomas Monjalon [mailto:thomas@monjalon.net]
> Sent: Friday, October 20, 2017 10:11 PM
> To: Mcnamara, John <john.mcnamara@intel.com>; Santosh Shukla
> <santosh.shukla@caviumnetworks.com>
> Cc: dev@dpdk.org; jerin.jacob@caviumnetworks.com
> Subject: Re: [PATCH v4 0/3] Octeontx doc misc
> 
> 20/10/2017 18:07, Mcnamara, John:
> > From: Santosh Shukla [mailto:santosh.shukla@caviumnetworks.com]
> > > Patch 1: Introduce platform/ entry in guide. That has information
> > > about platform drivers. ( As per discussion[1]) Patch 2: Introduce
> > > mempool/ entry in guide. (Refer discussion[1]) Patch 3: Misc Fix for
> > > nic/octeontx.rst
> > >
> >
> > Hi,
> >
> > I may be missing context from other patches/emails but what is a
> Platform Device Driver?
> 
> The idea is to add a guide for platforms (x86, Power8, DPAA, DPAA2,
> ThunderX, OcteonTX, Armada).
> We could move the x86 tuning from the QSG to this platform guide.
> For the SoCs, it is also a good way to reference docs for the drivers
> related to the platform.


Ok. Seems like a good idea. But should it be called something like 
"Platform Specific Guides"?

John
  

v5:

Introduce platform specific guide in doc, That can have
any misc/common information about platform like quick start guide,
, tunning tips, how-to-setup platform. 
Also can have information about platforms common hw block etc..

Series has Octeontx specific Misc doc changes.

v5 --> 4:
* Replaced `Ref:` with `Sec :doc:` as per John review comment.
* Renamed Feature to Features (john).
* Replaced Section from `Platform Device Driver` to
  `Platform Specific guide` (john).

Thanks.

Discussion history;
[1] http://dpdk.org/dev/patchwork/patch/29893/



Santosh Shukla (3):
  doc: add platform guide
  doc: add mempool and octeontx mempool device
  doc: use correct mempool ops handle name

 doc/guides/eventdevs/octeontx.rst |  28 +---------
 doc/guides/index.rst              |   2 +
 doc/guides/mempool/index.rst      |  40 +++++++++++++++
 doc/guides/mempool/octeontx.rst   | 104 ++++++++++++++++++++++++++++++++++++++
 doc/guides/nics/octeontx.rst      |  31 +-----------
 doc/guides/platform/index.rst     |  39 ++++++++++++++
 doc/guides/platform/octeontx.rst  |  81 +++++++++++++++++++++++++++++
 7 files changed, 269 insertions(+), 56 deletions(-)
 create mode 100644 doc/guides/mempool/index.rst
 create mode 100644 doc/guides/mempool/octeontx.rst
 create mode 100644 doc/guides/platform/index.rst
 create mode 100644 doc/guides/platform/octeontx.rst
  

> Santosh Shukla (3):
>   doc: add platform guide
>   doc: add mempool and octeontx mempool device
>   doc: use correct mempool ops handle name

Applied, thanks