Re: [lng-odp] [PATCHv2 2/2] doc: userguide: add baseline overview to document

[Maxim Uvarov]

Merged,
Maxim.

On 11/29/2015 19:13, Bill Fischofer wrote:
ping.  These doc updates need to be merged so we can continue to add 
to them.


On Mon, Nov 23, 2015 at 10:37 AM, Mike Holmes > wrote:


Reviewed-by: Mike Holmes mailto:mike.hol...@linaro.org>

Caveat that issues such as the glossary etc are solved before Monarch


On 18 November 2015 at 10:54, Bill Fischofer
mailto:bill.fischo...@linaro.org>> wrote:

On that subject, I was just discussing with Mike this morning
how Asciidoc support include structures, so it's probably
reasonable to put things like a glossary into its own file
that can be maintained separately and included in the main
doc.

On Wed, Nov 18, 2015 at 9:53 AM, Bill Fischofer
mailto:bill.fischo...@linaro.org>>
wrote:

Thanks.  The glossary is part of the base document and not
covered by this patch.  The intent is to start improving
the document on an incremental basis to keep the size of
individual patches manageable.  Much more will follow as
we restructure and fill in this document.

On Wed, Nov 18, 2015 at 9:38 AM, Stuart Haslam
mailto:stuart.has...@linaro.org>> wrote:

On Wed, Nov 18, 2015 at 03:30:31PM +, Stuart
Haslam wrote:
> On Tue, Nov 17, 2015 at 11:15:14AM -0600, Bill
Fischofer wrote:
> > Add a basic ODP overview to the User's Guide,
providing
> > an overview of ODP concepts, components, etc. Included
> > are a number of diagrams covering component structure
> > as well as packet RX, event scheduling, and packet TX
> > processing.
> >
> > Signed-off-by: Bill Fischofer
mailto:bill.fischo...@linaro.org>>
>
> Looks good to me. Mostly just typo comments below.
>

Sorry just realised I reviewed v2 and you've sent v4
with the typos
fixed. The comment about the glossary is still valid
though.

--
Stuart.




___
lng-odp mailing list
lng-odp@lists.linaro.org 
https://lists.linaro.org/mailman/listinfo/lng-odp




-- 
Mike Holmes

Technical Manager - Linaro Networking Group
Linaro.org ***│ *Open source software for
ARM SoCs




___
lng-odp mailing list
lng-odp@lists.linaro.org
https://lists.linaro.org/mailman/listinfo/lng-odp


___
lng-odp mailing list
lng-odp@lists.linaro.org
https://lists.linaro.org/mailman/listinfo/lng-odp

Re: [lng-odp] [PATCHv2 2/2] doc: userguide: add baseline overview to document

[Bill Fischofer]

ping.  These doc updates need to be merged so we can continue to add to
them.

On Mon, Nov 23, 2015 at 10:37 AM, Mike Holmes 
wrote:

> Reviewed-by: Mike Holmes 
> Caveat that issues such as the glossary etc are solved before Monarch
>
>
> On 18 November 2015 at 10:54, Bill Fischofer 
> wrote:
>
>> On that subject, I was just discussing with Mike this morning how
>> Asciidoc support include structures, so it's probably reasonable to put
>> things like a glossary into its own file that can be maintained separately
>> and included in the main
>> doc.
>>
>> On Wed, Nov 18, 2015 at 9:53 AM, Bill Fischofer <
>> bill.fischo...@linaro.org> wrote:
>>
>>> Thanks.  The glossary is part of the base document and not covered by
>>> this patch.  The intent is to start improving the document on an
>>> incremental basis to keep the size of individual patches manageable.  Much
>>> more will follow as we restructure and fill in this document.
>>>
>>> On Wed, Nov 18, 2015 at 9:38 AM, Stuart Haslam >> > wrote:
>>>
 On Wed, Nov 18, 2015 at 03:30:31PM +, Stuart Haslam wrote:
 > On Tue, Nov 17, 2015 at 11:15:14AM -0600, Bill Fischofer wrote:
 > > Add a basic ODP overview to the User's Guide, providing
 > > an overview of ODP concepts, components, etc. Included
 > > are a number of diagrams covering component structure
 > > as well as packet RX, event scheduling, and packet TX
 > > processing.
 > >
 > > Signed-off-by: Bill Fischofer 
 >
 > Looks good to me. Mostly just typo comments below.
 >

 Sorry just realised I reviewed v2 and you've sent v4 with the typos
 fixed. The comment about the glossary is still valid though.

 --
 Stuart.

>>>
>>>
>>
>> ___
>> lng-odp mailing list
>> lng-odp@lists.linaro.org
>> https://lists.linaro.org/mailman/listinfo/lng-odp
>>
>>
>
>
> --
> Mike Holmes
> Technical Manager - Linaro Networking Group
> Linaro.org  *│ *Open source software for ARM SoCs
>
>
>
___
lng-odp mailing list
lng-odp@lists.linaro.org
https://lists.linaro.org/mailman/listinfo/lng-odp

Re: [lng-odp] [PATCHv2 2/2] doc: userguide: add baseline overview to document

[Mike Holmes]

Reviewed-by: Mike Holmes 
wrote:

> On that subject, I was just discussing with Mike this morning how Asciidoc
> support include structures, so it's probably reasonable to put things like
> a glossary into its own file that can be maintained separately and included
> in the main
> doc.
>
> On Wed, Nov 18, 2015 at 9:53 AM, Bill Fischofer  > wrote:
>
>> Thanks.  The glossary is part of the base document and not covered by
>> this patch.  The intent is to start improving the document on an
>> incremental basis to keep the size of individual patches manageable.  Much
>> more will follow as we restructure and fill in this document.
>>
>> On Wed, Nov 18, 2015 at 9:38 AM, Stuart Haslam 
>> wrote:
>>
>>> On Wed, Nov 18, 2015 at 03:30:31PM +, Stuart Haslam wrote:
>>> > On Tue, Nov 17, 2015 at 11:15:14AM -0600, Bill Fischofer wrote:
>>> > > Add a basic ODP overview to the User's Guide, providing
>>> > > an overview of ODP concepts, components, etc. Included
>>> > > are a number of diagrams covering component structure
>>> > > as well as packet RX, event scheduling, and packet TX
>>> > > processing.
>>> > >
>>> > > Signed-off-by: Bill Fischofer 
>>> >
>>> > Looks good to me. Mostly just typo comments below.
>>> >
>>>
>>> Sorry just realised I reviewed v2 and you've sent v4 with the typos
>>> fixed. The comment about the glossary is still valid though.
>>>
>>> --
>>> Stuart.
>>>
>>
>>
>
> ___
> lng-odp mailing list
> lng-odp@lists.linaro.org
> https://lists.linaro.org/mailman/listinfo/lng-odp
>
>


-- 
Mike Holmes
Technical Manager - Linaro Networking Group
Linaro.org  *│ *Open source software for ARM SoCs
___
lng-odp mailing list
lng-odp@lists.linaro.org
https://lists.linaro.org/mailman/listinfo/lng-odp

Re: [lng-odp] [PATCHv2 2/2] doc: userguide: add baseline overview to document

[Bill Fischofer]

On that subject, I was just discussing with Mike this morning how Asciidoc
support include structures, so it's probably reasonable to put things like
a glossary into its own file that can be maintained separately and included
in the main
doc.

On Wed, Nov 18, 2015 at 9:53 AM, Bill Fischofer 
wrote:

> Thanks.  The glossary is part of the base document and not covered by this
> patch.  The intent is to start improving the document on an incremental
> basis to keep the size of individual patches manageable.  Much more will
> follow as we restructure and fill in this document.
>
> On Wed, Nov 18, 2015 at 9:38 AM, Stuart Haslam 
> wrote:
>
>> On Wed, Nov 18, 2015 at 03:30:31PM +, Stuart Haslam wrote:
>> > On Tue, Nov 17, 2015 at 11:15:14AM -0600, Bill Fischofer wrote:
>> > > Add a basic ODP overview to the User's Guide, providing
>> > > an overview of ODP concepts, components, etc. Included
>> > > are a number of diagrams covering component structure
>> > > as well as packet RX, event scheduling, and packet TX
>> > > processing.
>> > >
>> > > Signed-off-by: Bill Fischofer 
>> >
>> > Looks good to me. Mostly just typo comments below.
>> >
>>
>> Sorry just realised I reviewed v2 and you've sent v4 with the typos
>> fixed. The comment about the glossary is still valid though.
>>
>> --
>> Stuart.
>>
>
>
___
lng-odp mailing list
lng-odp@lists.linaro.org
https://lists.linaro.org/mailman/listinfo/lng-odp

Re: [lng-odp] [PATCHv2 2/2] doc: userguide: add baseline overview to document

[Bill Fischofer]

Thanks.  The glossary is part of the base document and not covered by this
patch.  The intent is to start improving the document on an incremental
basis to keep the size of individual patches manageable.  Much more will
follow as we restructure and fill in this document.

On Wed, Nov 18, 2015 at 9:38 AM, Stuart Haslam 
wrote:

> On Wed, Nov 18, 2015 at 03:30:31PM +, Stuart Haslam wrote:
> > On Tue, Nov 17, 2015 at 11:15:14AM -0600, Bill Fischofer wrote:
> > > Add a basic ODP overview to the User's Guide, providing
> > > an overview of ODP concepts, components, etc. Included
> > > are a number of diagrams covering component structure
> > > as well as packet RX, event scheduling, and packet TX
> > > processing.
> > >
> > > Signed-off-by: Bill Fischofer 
> >
> > Looks good to me. Mostly just typo comments below.
> >
>
> Sorry just realised I reviewed v2 and you've sent v4 with the typos
> fixed. The comment about the glossary is still valid though.
>
> --
> Stuart.
>
___
lng-odp mailing list
lng-odp@lists.linaro.org
https://lists.linaro.org/mailman/listinfo/lng-odp

Re: [lng-odp] [PATCHv2 2/2] doc: userguide: add baseline overview to document

[Stuart Haslam]

On Wed, Nov 18, 2015 at 03:30:31PM +, Stuart Haslam wrote:
> On Tue, Nov 17, 2015 at 11:15:14AM -0600, Bill Fischofer wrote:
> > Add a basic ODP overview to the User's Guide, providing
> > an overview of ODP concepts, components, etc. Included
> > are a number of diagrams covering component structure
> > as well as packet RX, event scheduling, and packet TX
> > processing.
> > 
> > Signed-off-by: Bill Fischofer 
> 
> Looks good to me. Mostly just typo comments below.
> 

Sorry just realised I reviewed v2 and you've sent v4 with the typos
fixed. The comment about the glossary is still valid though.

--
Stuart.
___
lng-odp mailing list
lng-odp@lists.linaro.org
https://lists.linaro.org/mailman/listinfo/lng-odp

Re: [lng-odp] [PATCHv2 2/2] doc: userguide: add baseline overview to document

[Stuart Haslam]

On Tue, Nov 17, 2015 at 11:15:14AM -0600, Bill Fischofer wrote:
> Add a basic ODP overview to the User's Guide, providing
> an overview of ODP concepts, components, etc. Included
> are a number of diagrams covering component structure
> as well as packet RX, event scheduling, and packet TX
> processing.
> 
> Signed-off-by: Bill Fischofer 

Looks good to me. Mostly just typo comments below.

> ---
>  doc/users-guide/users-guide.adoc | 400 
> ++-
>  1 file changed, 398 insertions(+), 2 deletions(-)
> 
> diff --git a/doc/users-guide/users-guide.adoc 
> b/doc/users-guide/users-guide.adoc
> index 7f70046..cf77fa0 100644
> --- a/doc/users-guide/users-guide.adoc
> +++ b/doc/users-guide/users-guide.adoc
> @@ -8,7 +8,7 @@ OpenDataPlane (ODP)  Users-Guide
>  Abstract
>  
>  This document is intended to guide a new ODP application developer.
> -Further details about ODP may be found at then http://opendataplane.org[ODP] 
> home page.
> +Further details about ODP may be found at the http://opendataplane.org[ODP] 
> home page.
>  
>  .Overview of a system running ODP applications
>  image::../images/overview.png[align="center"]
> @@ -16,6 +16,403 @@ image::../images/overview.png[align="center"]
>  ODP is an API specification that allows many implementations to provide 
> platform independence, automatic hardware acceleration and CPU scaling to 
> high performance networking  applications.
>  This document describes how to write an application that can successfully 
> take advantage of the API.
>  
> +:numbered:
> +== Introduction ==
> +.OpenDataPlane Components
> +image::../images/odp_components.png[align="center"]
> +
> +.The ODP API Specification
> +ODP consists of three separate but related component parts. First, ODP is an
> +abstract API specification that describes a functional model for
> +data plane applications. This specification covers many common data plane
> +application programming needs, such as the ability to receive, manipulate, 
> and
> +transmit packet data, without specifying how these functions are performed. 
> This
> +is quite intentional. It is precisely because ODP APIs do not have a 
> preferred
> +embodiment that they permit innovation in how these functions can
> +be realized on various platforms that offer implementations of ODP. To 
> achieve
> +this goal, ODP APIs are described using abstract data types whose definition
> +is left up to the ODP implementer.  For example, in ODP packets are 
> referenced
> +by abstract handles of type +odp_packet_t+, and packet-related APIs take
> +arguments of this type. What an +odp_packet_t+ actually is is not part of the
> +ODP API specification--that is the responsibility of each ODP implementation.
> +
> +.Summary: ODP API attributes:
> +* Open Source, open contribution, BSD-3 licensed.
> +* Vendor and platform neutral.
> +* Application-centric.  Covers functional needs of data plane applications.
> +* Ensures portability by specifying the functional behavior of ODP.
> +* Defined jointly and openly by application writers and platform 
> implementers.
> +* Archiected to be implementable on a wide range of platforms efficiently

Architected

> +* Sponsored, governed, and maintained by the Linaro Networking Group (LNG)
> +
> +.ODP Implementations
> +Second, ODP consists of multiple implementations of this API specification,
> +each tailored to a specific target platform. ODP implementations determine
> +how each ODP abstract type is represented on that platform and how each ODP
> +API is realized. On some platforms, ODP APIs will
> +be realized using specialized instructions that accelerate the functional
> +behavior specified by the API. On others, hardware co-processing engines may
> +completely offload the API so that again it can be performed with little or 
> no
> +involvement by a CPU. In all cases, the application sees the same
> +functional behavior independent of how a given platform has chosen to realize
> +it. By allowing each platform the freedom to determine how best to realize 
> each
> +API's specified functional behavior in an optimal manner, ODP permits
> +applications written to its APIs to take full advantage of the unique
> +capabilities of each platform without the application programmer needing to
> +have specialist knowledge of that platform or to be concerned with how best
> +to tune the application to a particular platform. This latter consideration 
> is
> +particularly important in Network Function Virtualization (NFV) environments
> +where the application will run on a target platform chosen by someone else.
> +
> +.Summary: ODP Implementation Characteristics
> +* One size does not fit all--supporting multiple implementations allows ODP
> +to adapt to widely differing internals among platforms.
> +* Anyone can create an ODP implementation tailored to their platform
> +* Distribution and mainteinance of each implementation is as owner wishes

maintenance 

> +  - Open source or close

Re: [lng-odp] [PATCHv2 2/2] doc: userguide: add baseline overview to document

[Bill Fischofer]

Thanks for the spelling corrections.  v4 submitted (v3 still had a typo)
that corrects these and others and adds the list you suggested.  Other
comments inline:

On Tue, Nov 17, 2015 at 12:52 PM, Mike Holmes 
wrote:

> General comments to hash as we get docs moving.
>
>- I think this would be a lot easier to review in smaller pieces, a
>section at a time, for future patches I think we should do that. Images
>should go in first and  it occurs to me we never add an image that is not
>used in a doc - maybe images and their use in the doc are a single patch ?
>If there are not too many objections I can live with these two patches as
>they are though.
>
> In general I agree, which is why I stopped here.  I don't think we want to
be too strict here, however.  This isn't code and isn't subject to
bisection.  Images should be in a separate patch because they are large and
non-reviewable in unrendered form since they are binary.  Putting them in
with the text portions just adds clutter for reviewers.


>-
>- We should pick one heading tag style, I have no preference but you
>and I differ currently in this doc so we should convert them all to the
>same style
>
> Agreed.  I prefer the == style since it's very clear that = is 1st level
header == is 2nd etc.  Using -, +, ~, etc. it's not obvious which is what
level. I can submit a patch to standardize on this style.


>
>-
>- We should pick a line style, again we differ. I put one sentence per
>line as we try to do with doxygen so that git diffs are per logical
>sentence rather than being slightly more random diffs of clumps of chars.
>The down side it in raw form the doc looks a little longer - but I think
>the diff ability makes it worth it.
>
> Strongly disagree.  The goal here is to make things readable for the human
writer and reviewer.  Keeping to natural line breaks and our checkpatch 80
char length guidelines do that.  Changes are to improve readability, not to
minimize the number of characters changed in some diff, which is a
completely arbitrary criteria that bears little relevance to how
documentation is intended to be used.  The whole point of using asciidoc is
to make the document source humanly readable.  That trumps all else.

>
>-
>- Also this patch has introduced highlighting for ODP types and enums
>using "+" which I like, but is it not used consistently with the initial
>doc, If we are going to use this I think we should update the existing doc
>to use them also.
>
> Again, additional patches can revise the existing portions of the doc to
standardize.


>
>-
>
> On 17 November 2015 at 12:15, Bill Fischofer 
> wrote:
>
>> Add a basic ODP overview to the User's Guide, providing
>> an overview of ODP concepts, components, etc. Included
>> are a number of diagrams covering component structure
>> as well as packet RX, event scheduling, and packet TX
>> processing.
>>
>> Signed-off-by: Bill Fischofer 
>> ---
>>  doc/users-guide/users-guide.adoc | 400
>> ++-
>>  1 file changed, 398 insertions(+), 2 deletions(-)
>>
>> diff --git a/doc/users-guide/users-guide.adoc
>> b/doc/users-guide/users-guide.adoc
>> index 7f70046..cf77fa0 100644
>> --- a/doc/users-guide/users-guide.adoc
>> +++ b/doc/users-guide/users-guide.adoc
>> @@ -8,7 +8,7 @@ OpenDataPlane (ODP)  Users-Guide
>>  Abstract
>>  
>>  This document is intended to guide a new ODP application developer.
>> -Further details about ODP may be found at then http://opendataplane.org[ODP]
>> home page.
>> +Further details about ODP may be found at the http://opendataplane.org[ODP]
>> home page.
>>
>>  .Overview of a system running ODP applications
>>  image::../images/overview.png[align="center"]
>> @@ -16,6 +16,403 @@ image::../images/overview.png[align="center"]
>>  ODP is an API specification that allows many implementations to provide
>> platform independence, automatic hardware acceleration and CPU scaling to
>> high performance networking  applications.
>>  This document describes how to write an application that can
>> successfully take advantage of the API.
>>
>> +:numbered:
>> +== Introduction ==
>> +.OpenDataPlane Components
>> +image::../images/odp_components.png[align="center"]
>> +
>> +.The ODP API Specification
>> +ODP consists of three separate but related component parts. First, ODP
>> is an
>> +abstract API specification that describes a functional model for
>> +data plane applications. This specification covers many common data plane
>> +application programming needs, such as the ability to receive,
>> manipulate, and
>> +transmit packet data, without specifying how these functions are
>> performed. This
>> +is quite intentional. It is precisely because ODP APIs do not have a
>> preferred
>> +embodiment that they permit innovation in how these functions can
>> +be realized on various platforms that offer implementations of ODP. To
>> achieve
>> +this goal, ODP APIs 

Re: [lng-odp] [PATCHv2 2/2] doc: userguide: add baseline overview to document

[Mike Holmes]

General comments to hash as we get docs moving.

   - I think this would be a lot easier to review in smaller pieces, a
   section at a time, for future patches I think we should do that. Images
   should go in first and  it occurs to me we never add an image that is not
   used in a doc - maybe images and their use in the doc are a single patch ?
   If there are not too many objections I can live with these two patches as
   they are though.
   - We should pick one heading tag style, I have no preference but you and
   I differ currently in this doc so we should convert them all to the same
   style
   - We should pick a line style, again we differ. I put one sentence per
   line as we try to do with doxygen so that git diffs are per logical
   sentence rather than being slightly more random diffs of clumps of chars.
   The down side it in raw form the doc looks a little longer - but I think
   the diff ability makes it worth it.
   - Also this patch has introduced highlighting for ODP types and enums
   using "+" which I like, but is it not used consistently with the initial
   doc, If we are going to use this I think we should update the existing doc
   to use them also.


On 17 November 2015 at 12:15, Bill Fischofer 
wrote:

> Add a basic ODP overview to the User's Guide, providing
> an overview of ODP concepts, components, etc. Included
> are a number of diagrams covering component structure
> as well as packet RX, event scheduling, and packet TX
> processing.
>
> Signed-off-by: Bill Fischofer 
> ---
>  doc/users-guide/users-guide.adoc | 400
> ++-
>  1 file changed, 398 insertions(+), 2 deletions(-)
>
> diff --git a/doc/users-guide/users-guide.adoc
> b/doc/users-guide/users-guide.adoc
> index 7f70046..cf77fa0 100644
> --- a/doc/users-guide/users-guide.adoc
> +++ b/doc/users-guide/users-guide.adoc
> @@ -8,7 +8,7 @@ OpenDataPlane (ODP)  Users-Guide
>  Abstract
>  
>  This document is intended to guide a new ODP application developer.
> -Further details about ODP may be found at then http://opendataplane.org[ODP]
> home page.
> +Further details about ODP may be found at the http://opendataplane.org[ODP]
> home page.
>
>  .Overview of a system running ODP applications
>  image::../images/overview.png[align="center"]
> @@ -16,6 +16,403 @@ image::../images/overview.png[align="center"]
>  ODP is an API specification that allows many implementations to provide
> platform independence, automatic hardware acceleration and CPU scaling to
> high performance networking  applications.
>  This document describes how to write an application that can successfully
> take advantage of the API.
>
> +:numbered:
> +== Introduction ==
> +.OpenDataPlane Components
> +image::../images/odp_components.png[align="center"]
> +
> +.The ODP API Specification
> +ODP consists of three separate but related component parts. First, ODP is
> an
> +abstract API specification that describes a functional model for
> +data plane applications. This specification covers many common data plane
> +application programming needs, such as the ability to receive,
> manipulate, and
> +transmit packet data, without specifying how these functions are
> performed. This
> +is quite intentional. It is precisely because ODP APIs do not have a
> preferred
> +embodiment that they permit innovation in how these functions can
> +be realized on various platforms that offer implementations of ODP. To
> achieve
> +this goal, ODP APIs are described using abstract data types whose
> definition
> +is left up to the ODP implementer.  For example, in ODP packets are
> referenced
> +by abstract handles of type +odp_packet_t+, and packet-related APIs take
> +arguments of this type. What an +odp_packet_t+ actually is is not part of
> the
> +ODP API specification--that is the responsibility of each ODP
> implementation.
> +
> +.Summary: ODP API attributes:
> +* Open Source, open contribution, BSD-3 licensed.
> +* Vendor and platform neutral.
> +* Application-centric.  Covers functional needs of data plane
> applications.
> +* Ensures portability by specifying the functional behavior of ODP.
> +* Defined jointly and openly by application writers and platform
> implementers.
> +* Archiected

to be implementable on a wide range of platforms efficiently
> +* Sponsored, governed, and maintained by the Linaro Networking Group (LNG)
> +
> +.ODP Implementations
> +Second, ODP consists of multiple implementations of this API
> specification,
> +each tailored to a specific target platform. ODP implementations determine
> +how each ODP abstract type is represented on that platform and how each
> ODP
> +API is realized. On some platforms, ODP APIs will
> +be realized using specialized instructions that accelerate the functional
> +behavior specified by the API. On others, hardware co-processing engines
> may
> +completely offload the API so that again it can be performed with little
> or no
> +involvement by a CPU. In all cases, the applica

Re: [lng-odp] [PATCHv2 2/2] doc: userguide: add baseline overview to document

[Mike Holmes]

On 17 November 2015 at 13:15, Bill Fischofer 
wrote:

> That's what make does :)
>

Indeed - but reviews on docs are very hard to get, hopefully some one reads
it and objects who would normally ignore it!


>
> On Tue, Nov 17, 2015 at 11:57 AM, Mike Holmes 
> wrote:
>
>>
>>
>> On 17 November 2015 at 12:54, Bill Fischofer 
>> wrote:
>>
>>> Is that a review comment?  Is there a problem with the rendering?
>>>
>>
>> Not a review comment just to make it easier for folks to read initially.
>>
>>
>>> On Tue, Nov 17, 2015 at 11:51 AM, Mike Holmes 
>>> wrote:
>>>
 This is the rendered doc

 http://people.linaro.org/~mike.holmes/output/users-guide.html

 On 17 November 2015 at 12:15, Bill Fischofer >>> > wrote:

> Add a basic ODP overview to the User's Guide, providing
> an overview of ODP concepts, components, etc. Included
> are a number of diagrams covering component structure
> as well as packet RX, event scheduling, and packet TX
> processing.
>
> Signed-off-by: Bill Fischofer 
> ---
>  doc/users-guide/users-guide.adoc | 400
> ++-
>  1 file changed, 398 insertions(+), 2 deletions(-)
>
> diff --git a/doc/users-guide/users-guide.adoc
> b/doc/users-guide/users-guide.adoc
> index 7f70046..cf77fa0 100644
> --- a/doc/users-guide/users-guide.adoc
> +++ b/doc/users-guide/users-guide.adoc
> @@ -8,7 +8,7 @@ OpenDataPlane (ODP)  Users-Guide
>  Abstract
>  
>  This document is intended to guide a new ODP application developer.
> -Further details about ODP may be found at then
> http://opendataplane.org[ODP] home page.
> +Further details about ODP may be found at the
> http://opendataplane.org[ODP] home page.
>
>  .Overview of a system running ODP applications
>  image::../images/overview.png[align="center"]
> @@ -16,6 +16,403 @@ image::../images/overview.png[align="center"]
>  ODP is an API specification that allows many implementations to
> provide platform independence, automatic hardware acceleration and CPU
> scaling to high performance networking  applications.
>  This document describes how to write an application that can
> successfully take advantage of the API.
>
> +:numbered:
> +== Introduction ==
> +.OpenDataPlane Components
> +image::../images/odp_components.png[align="center"]
> +
> +.The ODP API Specification
> +ODP consists of three separate but related component parts. First,
> ODP is an
> +abstract API specification that describes a functional model for
> +data plane applications. This specification covers many common data
> plane
> +application programming needs, such as the ability to receive,
> manipulate, and
> +transmit packet data, without specifying how these functions are
> performed. This
> +is quite intentional. It is precisely because ODP APIs do not have a
> preferred
> +embodiment that they permit innovation in how these functions can
> +be realized on various platforms that offer implementations of ODP.
> To achieve
> +this goal, ODP APIs are described using abstract data types whose
> definition
> +is left up to the ODP implementer.  For example, in ODP packets are
> referenced
> +by abstract handles of type +odp_packet_t+, and packet-related APIs
> take
> +arguments of this type. What an +odp_packet_t+ actually is is not
> part of the
> +ODP API specification--that is the responsibility of each ODP
> implementation.
> +
> +.Summary: ODP API attributes:
> +* Open Source, open contribution, BSD-3 licensed.
> +* Vendor and platform neutral.
> +* Application-centric.  Covers functional needs of data plane
> applications.
> +* Ensures portability by specifying the functional behavior of ODP.
> +* Defined jointly and openly by application writers and platform
> implementers.
> +* Archiected to be implementable on a wide range of platforms
> efficiently
> +* Sponsored, governed, and maintained by the Linaro Networking Group
> (LNG)
> +
> +.ODP Implementations
> +Second, ODP consists of multiple implementations of this API
> specification,
> +each tailored to a specific target platform. ODP implementations
> determine
> +how each ODP abstract type is represented on that platform and how
> each ODP
> +API is realized. On some platforms, ODP APIs will
> +be realized using specialized instructions that accelerate the
> functional
> +behavior specified by the API. On others, hardware co-processing
> engines may
> +completely offload the API so that again it can be performed with
> little or no
> +involvement by a CPU. In all cases, the application sees the same
> +functional behavior independent of how a given platform has chosen to
> realize
> +it. By a

Re: [lng-odp] [PATCHv2 2/2] doc: userguide: add baseline overview to document

[Bill Fischofer]

That's what make does :)

On Tue, Nov 17, 2015 at 11:57 AM, Mike Holmes 
wrote:

>
>
> On 17 November 2015 at 12:54, Bill Fischofer 
> wrote:
>
>> Is that a review comment?  Is there a problem with the rendering?
>>
>
> Not a review comment just to make it easier for folks to read initially.
>
>
>> On Tue, Nov 17, 2015 at 11:51 AM, Mike Holmes 
>> wrote:
>>
>>> This is the rendered doc
>>>
>>> http://people.linaro.org/~mike.holmes/output/users-guide.html
>>>
>>> On 17 November 2015 at 12:15, Bill Fischofer 
>>> wrote:
>>>
 Add a basic ODP overview to the User's Guide, providing
 an overview of ODP concepts, components, etc. Included
 are a number of diagrams covering component structure
 as well as packet RX, event scheduling, and packet TX
 processing.

 Signed-off-by: Bill Fischofer 
 ---
  doc/users-guide/users-guide.adoc | 400
 ++-
  1 file changed, 398 insertions(+), 2 deletions(-)

 diff --git a/doc/users-guide/users-guide.adoc
 b/doc/users-guide/users-guide.adoc
 index 7f70046..cf77fa0 100644
 --- a/doc/users-guide/users-guide.adoc
 +++ b/doc/users-guide/users-guide.adoc
 @@ -8,7 +8,7 @@ OpenDataPlane (ODP)  Users-Guide
  Abstract
  
  This document is intended to guide a new ODP application developer.
 -Further details about ODP may be found at then
 http://opendataplane.org[ODP] home page.
 +Further details about ODP may be found at the 
 http://opendataplane.org[ODP]
 home page.

  .Overview of a system running ODP applications
  image::../images/overview.png[align="center"]
 @@ -16,6 +16,403 @@ image::../images/overview.png[align="center"]
  ODP is an API specification that allows many implementations to
 provide platform independence, automatic hardware acceleration and CPU
 scaling to high performance networking  applications.
  This document describes how to write an application that can
 successfully take advantage of the API.

 +:numbered:
 +== Introduction ==
 +.OpenDataPlane Components
 +image::../images/odp_components.png[align="center"]
 +
 +.The ODP API Specification
 +ODP consists of three separate but related component parts. First, ODP
 is an
 +abstract API specification that describes a functional model for
 +data plane applications. This specification covers many common data
 plane
 +application programming needs, such as the ability to receive,
 manipulate, and
 +transmit packet data, without specifying how these functions are
 performed. This
 +is quite intentional. It is precisely because ODP APIs do not have a
 preferred
 +embodiment that they permit innovation in how these functions can
 +be realized on various platforms that offer implementations of ODP. To
 achieve
 +this goal, ODP APIs are described using abstract data types whose
 definition
 +is left up to the ODP implementer.  For example, in ODP packets are
 referenced
 +by abstract handles of type +odp_packet_t+, and packet-related APIs
 take
 +arguments of this type. What an +odp_packet_t+ actually is is not part
 of the
 +ODP API specification--that is the responsibility of each ODP
 implementation.
 +
 +.Summary: ODP API attributes:
 +* Open Source, open contribution, BSD-3 licensed.
 +* Vendor and platform neutral.
 +* Application-centric.  Covers functional needs of data plane
 applications.
 +* Ensures portability by specifying the functional behavior of ODP.
 +* Defined jointly and openly by application writers and platform
 implementers.
 +* Archiected to be implementable on a wide range of platforms
 efficiently
 +* Sponsored, governed, and maintained by the Linaro Networking Group
 (LNG)
 +
 +.ODP Implementations
 +Second, ODP consists of multiple implementations of this API
 specification,
 +each tailored to a specific target platform. ODP implementations
 determine
 +how each ODP abstract type is represented on that platform and how
 each ODP
 +API is realized. On some platforms, ODP APIs will
 +be realized using specialized instructions that accelerate the
 functional
 +behavior specified by the API. On others, hardware co-processing
 engines may
 +completely offload the API so that again it can be performed with
 little or no
 +involvement by a CPU. In all cases, the application sees the same
 +functional behavior independent of how a given platform has chosen to
 realize
 +it. By allowing each platform the freedom to determine how best to
 realize each
 +API's specified functional behavior in an optimal manner, ODP permits
 +applications written to its APIs to take full advantage of the unique
 +capabilities of each platform without the application programmer

Re: [lng-odp] [PATCHv2 2/2] doc: userguide: add baseline overview to document

[Mike Holmes]

On 17 November 2015 at 12:54, Bill Fischofer 
wrote:

> Is that a review comment?  Is there a problem with the rendering?
>

Not a review comment just to make it easier for folks to read initially.


> On Tue, Nov 17, 2015 at 11:51 AM, Mike Holmes 
> wrote:
>
>> This is the rendered doc
>>
>> http://people.linaro.org/~mike.holmes/output/users-guide.html
>>
>> On 17 November 2015 at 12:15, Bill Fischofer 
>> wrote:
>>
>>> Add a basic ODP overview to the User's Guide, providing
>>> an overview of ODP concepts, components, etc. Included
>>> are a number of diagrams covering component structure
>>> as well as packet RX, event scheduling, and packet TX
>>> processing.
>>>
>>> Signed-off-by: Bill Fischofer 
>>> ---
>>>  doc/users-guide/users-guide.adoc | 400
>>> ++-
>>>  1 file changed, 398 insertions(+), 2 deletions(-)
>>>
>>> diff --git a/doc/users-guide/users-guide.adoc
>>> b/doc/users-guide/users-guide.adoc
>>> index 7f70046..cf77fa0 100644
>>> --- a/doc/users-guide/users-guide.adoc
>>> +++ b/doc/users-guide/users-guide.adoc
>>> @@ -8,7 +8,7 @@ OpenDataPlane (ODP)  Users-Guide
>>>  Abstract
>>>  
>>>  This document is intended to guide a new ODP application developer.
>>> -Further details about ODP may be found at then 
>>> http://opendataplane.org[ODP]
>>> home page.
>>> +Further details about ODP may be found at the http://opendataplane.org[ODP]
>>> home page.
>>>
>>>  .Overview of a system running ODP applications
>>>  image::../images/overview.png[align="center"]
>>> @@ -16,6 +16,403 @@ image::../images/overview.png[align="center"]
>>>  ODP is an API specification that allows many implementations to provide
>>> platform independence, automatic hardware acceleration and CPU scaling to
>>> high performance networking  applications.
>>>  This document describes how to write an application that can
>>> successfully take advantage of the API.
>>>
>>> +:numbered:
>>> +== Introduction ==
>>> +.OpenDataPlane Components
>>> +image::../images/odp_components.png[align="center"]
>>> +
>>> +.The ODP API Specification
>>> +ODP consists of three separate but related component parts. First, ODP
>>> is an
>>> +abstract API specification that describes a functional model for
>>> +data plane applications. This specification covers many common data
>>> plane
>>> +application programming needs, such as the ability to receive,
>>> manipulate, and
>>> +transmit packet data, without specifying how these functions are
>>> performed. This
>>> +is quite intentional. It is precisely because ODP APIs do not have a
>>> preferred
>>> +embodiment that they permit innovation in how these functions can
>>> +be realized on various platforms that offer implementations of ODP. To
>>> achieve
>>> +this goal, ODP APIs are described using abstract data types whose
>>> definition
>>> +is left up to the ODP implementer.  For example, in ODP packets are
>>> referenced
>>> +by abstract handles of type +odp_packet_t+, and packet-related APIs take
>>> +arguments of this type. What an +odp_packet_t+ actually is is not part
>>> of the
>>> +ODP API specification--that is the responsibility of each ODP
>>> implementation.
>>> +
>>> +.Summary: ODP API attributes:
>>> +* Open Source, open contribution, BSD-3 licensed.
>>> +* Vendor and platform neutral.
>>> +* Application-centric.  Covers functional needs of data plane
>>> applications.
>>> +* Ensures portability by specifying the functional behavior of ODP.
>>> +* Defined jointly and openly by application writers and platform
>>> implementers.
>>> +* Archiected to be implementable on a wide range of platforms
>>> efficiently
>>> +* Sponsored, governed, and maintained by the Linaro Networking Group
>>> (LNG)
>>> +
>>> +.ODP Implementations
>>> +Second, ODP consists of multiple implementations of this API
>>> specification,
>>> +each tailored to a specific target platform. ODP implementations
>>> determine
>>> +how each ODP abstract type is represented on that platform and how each
>>> ODP
>>> +API is realized. On some platforms, ODP APIs will
>>> +be realized using specialized instructions that accelerate the
>>> functional
>>> +behavior specified by the API. On others, hardware co-processing
>>> engines may
>>> +completely offload the API so that again it can be performed with
>>> little or no
>>> +involvement by a CPU. In all cases, the application sees the same
>>> +functional behavior independent of how a given platform has chosen to
>>> realize
>>> +it. By allowing each platform the freedom to determine how best to
>>> realize each
>>> +API's specified functional behavior in an optimal manner, ODP permits
>>> +applications written to its APIs to take full advantage of the unique
>>> +capabilities of each platform without the application programmer
>>> needing to
>>> +have specialist knowledge of that platform or to be concerned with how
>>> best
>>> +to tune the application to a particular platform. This latter
>>> consideration is
>>> +particularly importa

Re: [lng-odp] [PATCHv2 2/2] doc: userguide: add baseline overview to document

[Bill Fischofer]

Is that a review comment?  Is there a problem with the rendering?

On Tue, Nov 17, 2015 at 11:51 AM, Mike Holmes 
wrote:

> This is the rendered doc
>
> http://people.linaro.org/~mike.holmes/output/users-guide.html
>
> On 17 November 2015 at 12:15, Bill Fischofer 
> wrote:
>
>> Add a basic ODP overview to the User's Guide, providing
>> an overview of ODP concepts, components, etc. Included
>> are a number of diagrams covering component structure
>> as well as packet RX, event scheduling, and packet TX
>> processing.
>>
>> Signed-off-by: Bill Fischofer 
>> ---
>>  doc/users-guide/users-guide.adoc | 400
>> ++-
>>  1 file changed, 398 insertions(+), 2 deletions(-)
>>
>> diff --git a/doc/users-guide/users-guide.adoc
>> b/doc/users-guide/users-guide.adoc
>> index 7f70046..cf77fa0 100644
>> --- a/doc/users-guide/users-guide.adoc
>> +++ b/doc/users-guide/users-guide.adoc
>> @@ -8,7 +8,7 @@ OpenDataPlane (ODP)  Users-Guide
>>  Abstract
>>  
>>  This document is intended to guide a new ODP application developer.
>> -Further details about ODP may be found at then http://opendataplane.org[ODP]
>> home page.
>> +Further details about ODP may be found at the http://opendataplane.org[ODP]
>> home page.
>>
>>  .Overview of a system running ODP applications
>>  image::../images/overview.png[align="center"]
>> @@ -16,6 +16,403 @@ image::../images/overview.png[align="center"]
>>  ODP is an API specification that allows many implementations to provide
>> platform independence, automatic hardware acceleration and CPU scaling to
>> high performance networking  applications.
>>  This document describes how to write an application that can
>> successfully take advantage of the API.
>>
>> +:numbered:
>> +== Introduction ==
>> +.OpenDataPlane Components
>> +image::../images/odp_components.png[align="center"]
>> +
>> +.The ODP API Specification
>> +ODP consists of three separate but related component parts. First, ODP
>> is an
>> +abstract API specification that describes a functional model for
>> +data plane applications. This specification covers many common data plane
>> +application programming needs, such as the ability to receive,
>> manipulate, and
>> +transmit packet data, without specifying how these functions are
>> performed. This
>> +is quite intentional. It is precisely because ODP APIs do not have a
>> preferred
>> +embodiment that they permit innovation in how these functions can
>> +be realized on various platforms that offer implementations of ODP. To
>> achieve
>> +this goal, ODP APIs are described using abstract data types whose
>> definition
>> +is left up to the ODP implementer.  For example, in ODP packets are
>> referenced
>> +by abstract handles of type +odp_packet_t+, and packet-related APIs take
>> +arguments of this type. What an +odp_packet_t+ actually is is not part
>> of the
>> +ODP API specification--that is the responsibility of each ODP
>> implementation.
>> +
>> +.Summary: ODP API attributes:
>> +* Open Source, open contribution, BSD-3 licensed.
>> +* Vendor and platform neutral.
>> +* Application-centric.  Covers functional needs of data plane
>> applications.
>> +* Ensures portability by specifying the functional behavior of ODP.
>> +* Defined jointly and openly by application writers and platform
>> implementers.
>> +* Archiected to be implementable on a wide range of platforms efficiently
>> +* Sponsored, governed, and maintained by the Linaro Networking Group
>> (LNG)
>> +
>> +.ODP Implementations
>> +Second, ODP consists of multiple implementations of this API
>> specification,
>> +each tailored to a specific target platform. ODP implementations
>> determine
>> +how each ODP abstract type is represented on that platform and how each
>> ODP
>> +API is realized. On some platforms, ODP APIs will
>> +be realized using specialized instructions that accelerate the functional
>> +behavior specified by the API. On others, hardware co-processing engines
>> may
>> +completely offload the API so that again it can be performed with little
>> or no
>> +involvement by a CPU. In all cases, the application sees the same
>> +functional behavior independent of how a given platform has chosen to
>> realize
>> +it. By allowing each platform the freedom to determine how best to
>> realize each
>> +API's specified functional behavior in an optimal manner, ODP permits
>> +applications written to its APIs to take full advantage of the unique
>> +capabilities of each platform without the application programmer needing
>> to
>> +have specialist knowledge of that platform or to be concerned with how
>> best
>> +to tune the application to a particular platform. This latter
>> consideration is
>> +particularly important in Network Function Virtualization (NFV)
>> environments
>> +where the application will run on a target platform chosen by someone
>> else.
>> +
>> +.Summary: ODP Implementation Characteristics
>> +* One size does not fit all--supporting multiple implementations

Re: [lng-odp] [PATCHv2 2/2] doc: userguide: add baseline overview to document

[Mike Holmes]

This is the rendered doc

http://people.linaro.org/~mike.holmes/output/users-guide.html

On 17 November 2015 at 12:15, Bill Fischofer 
wrote:

> Add a basic ODP overview to the User's Guide, providing
> an overview of ODP concepts, components, etc. Included
> are a number of diagrams covering component structure
> as well as packet RX, event scheduling, and packet TX
> processing.
>
> Signed-off-by: Bill Fischofer 
> ---
>  doc/users-guide/users-guide.adoc | 400
> ++-
>  1 file changed, 398 insertions(+), 2 deletions(-)
>
> diff --git a/doc/users-guide/users-guide.adoc
> b/doc/users-guide/users-guide.adoc
> index 7f70046..cf77fa0 100644
> --- a/doc/users-guide/users-guide.adoc
> +++ b/doc/users-guide/users-guide.adoc
> @@ -8,7 +8,7 @@ OpenDataPlane (ODP)  Users-Guide
>  Abstract
>  
>  This document is intended to guide a new ODP application developer.
> -Further details about ODP may be found at then http://opendataplane.org[ODP]
> home page.
> +Further details about ODP may be found at the http://opendataplane.org[ODP]
> home page.
>
>  .Overview of a system running ODP applications
>  image::../images/overview.png[align="center"]
> @@ -16,6 +16,403 @@ image::../images/overview.png[align="center"]
>  ODP is an API specification that allows many implementations to provide
> platform independence, automatic hardware acceleration and CPU scaling to
> high performance networking  applications.
>  This document describes how to write an application that can successfully
> take advantage of the API.
>
> +:numbered:
> +== Introduction ==
> +.OpenDataPlane Components
> +image::../images/odp_components.png[align="center"]
> +
> +.The ODP API Specification
> +ODP consists of three separate but related component parts. First, ODP is
> an
> +abstract API specification that describes a functional model for
> +data plane applications. This specification covers many common data plane
> +application programming needs, such as the ability to receive,
> manipulate, and
> +transmit packet data, without specifying how these functions are
> performed. This
> +is quite intentional. It is precisely because ODP APIs do not have a
> preferred
> +embodiment that they permit innovation in how these functions can
> +be realized on various platforms that offer implementations of ODP. To
> achieve
> +this goal, ODP APIs are described using abstract data types whose
> definition
> +is left up to the ODP implementer.  For example, in ODP packets are
> referenced
> +by abstract handles of type +odp_packet_t+, and packet-related APIs take
> +arguments of this type. What an +odp_packet_t+ actually is is not part of
> the
> +ODP API specification--that is the responsibility of each ODP
> implementation.
> +
> +.Summary: ODP API attributes:
> +* Open Source, open contribution, BSD-3 licensed.
> +* Vendor and platform neutral.
> +* Application-centric.  Covers functional needs of data plane
> applications.
> +* Ensures portability by specifying the functional behavior of ODP.
> +* Defined jointly and openly by application writers and platform
> implementers.
> +* Archiected to be implementable on a wide range of platforms efficiently
> +* Sponsored, governed, and maintained by the Linaro Networking Group (LNG)
> +
> +.ODP Implementations
> +Second, ODP consists of multiple implementations of this API
> specification,
> +each tailored to a specific target platform. ODP implementations determine
> +how each ODP abstract type is represented on that platform and how each
> ODP
> +API is realized. On some platforms, ODP APIs will
> +be realized using specialized instructions that accelerate the functional
> +behavior specified by the API. On others, hardware co-processing engines
> may
> +completely offload the API so that again it can be performed with little
> or no
> +involvement by a CPU. In all cases, the application sees the same
> +functional behavior independent of how a given platform has chosen to
> realize
> +it. By allowing each platform the freedom to determine how best to
> realize each
> +API's specified functional behavior in an optimal manner, ODP permits
> +applications written to its APIs to take full advantage of the unique
> +capabilities of each platform without the application programmer needing
> to
> +have specialist knowledge of that platform or to be concerned with how
> best
> +to tune the application to a particular platform. This latter
> consideration is
> +particularly important in Network Function Virtualization (NFV)
> environments
> +where the application will run on a target platform chosen by someone
> else.
> +
> +.Summary: ODP Implementation Characteristics
> +* One size does not fit all--supporting multiple implementations allows
> ODP
> +to adapt to widely differing internals among platforms.
> +* Anyone can create an ODP implementation tailored to their platform
> +* Distribution and mainteinance of each implementation is as owner wishes
> +  - Open source or cl