| Message ID | 1447866184-6923-1-git-send-email-mike.holmes@linaro.org |
|---|---|
| State | New |
| Headers | show |
Looks like this patch needs to be applied on top of my patch to the user guide. Other than that: On Wed, Nov 18, 2015 at 11:03 AM, Mike Holmes <mike.holmes@linaro.org> wrote: > Signed-off-by: Mike Holmes <mike.holmes@linaro.org> > Reviewed-and-tested-by: Bill Fischofer <bill.fischofer@linaro.org> > --- > doc/users-guide/users-guide.adoc | 101 > +++++++++++++++++++++++++-------------- > 1 file changed, 66 insertions(+), 35 deletions(-) > > diff --git a/doc/users-guide/users-guide.adoc > b/doc/users-guide/users-guide.adoc > index be40d2f..e087696 100644 > --- a/doc/users-guide/users-guide.adoc > +++ b/doc/users-guide/users-guide.adoc > @@ -8,13 +8,16 @@ OpenDataPlane (ODP) Users-Guide > Abstract > -------- > This document is intended to guide a new ODP application developer. > -Further details about ODP may be found at the 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"] > > -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. > +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 == > @@ -422,23 +425,35 @@ goals. Again, the advantage here is that on many > platforms traffic management > functions are implemented in hardware, permitting transparent offload of > this work. > > -Glossary > --------- > +== Glossary == > + > [glossary] > odp_worker:: > - An opd_worker is a type of odp_thread. It will usually be isolated > from the scheduling of any host operating system and is intended for > fast-path processing with a low and predictable latency. Odp_workers will > not generally receive interrupts and will run to completion. > + An opd_worker is a type of odp_thread. It will usually be isolated > from the > + scheduling of any host operating system and is intended for fast-path > + processing with a low and predictable latency. Odp_workers will not > + generally receive interrupts and will run to completion. > odp_control:: > - An odp_control is a type of odp_thread. It will be isolated from the > host operating system house keeping tasks but will be scheduled by it and > may receive interrupts. > + An odp_control is a type of odp_thread. It will be isolated from the > host > + operating system house keeping tasks but will be scheduled by it and > may > + receive interrupts. > odp_thread:: > - An odp_thread is a flow of execution that in a Linux environment > could be a Linux process or thread. > + An odp_thread is a flow of execution that in a Linux environment > could be a > + Linux process or thread. > event:: > An event is a notification that can be placed in a queue. > > -The include structure > ---------------------- > -Applications only include the 'include/odp.h file which includes the > 'platform/<implementation name>/include/plat' files to provide a complete > definition of the API on that platform. > -The doxygen documentation defining the behavior of the ODP API is all > contained in the public API files, and the actual definitions for an > implementation will be found in the per platform directories. > -Per-platform data that might normally be a #define can be recovered via > the appropriate access function if the #define is not directly visible to > the application. > +== The include structure == > + > +Applications only include the 'include/odp.h' file which includes the > +'platform/<implementation name>/include/plat' files to provide a complete > +definition of the API on that platform. > +The doxygen documentation defining the behavior of the ODP API is all > contained > +in the public API files, and the actual definitions for an implementation > will > +be found in the per platform directories. > +Per-platform data that might normally be a #define can be recovered via > the > +appropriate access function if the #define is not directly visible to the > +application. > > .Users include structure > ---- > @@ -451,21 +466,29 @@ Per-platform data that might normally be a #define > can be recovered via the appr > │ └── odp.h This file should be the only file included by the > application. > ---- > > -Initialization > --------------- > -IMPORTANT: ODP depends on the application to perform a graceful shutdown, > calling the terminate functions should only be done when the application is > sure it has closed the ingress and subsequently drained all queues etc. > +== Initialization == > + > +IMPORTANT: ODP depends on the application to perform a graceful shutdown, > +calling the terminate functions should only be done when the application > is sure > +it has closed the ingress and subsequently drained all queues etc. > + > +=== Startup === > > -Startup > -~~~~~~~~ > The first API that must be called is 'odp_init_global()'. > -This takes two pointers, odp_init_t contains ODP initialization data that > is platform independent and portable. > -The second odp_platform_init_t is passed un parsed to the implementation > and can be used for platform specific data that is not yet, or may never be > suitable for the ODP API. > +This takes two pointers, +odp_init_t+ contains ODP initialization data > that is > +platform independent and portable. > +The second +odp_platform_init_t+ is passed un parsed to the > implementation and > +can be used for platform specific data that is not yet, or may never be > suitable > +for the ODP API. > > -The second API that must be called is 'odp_init_local()', this must be > called once per odp_thread, regardless of odp_thread type. Odp_threads may > be of type ODP_THREAD_WORKER or ODP_THREAD_CONTROL > +The second API that must be called is 'odp_init_local()', this must be > called > +once per odp_thread, regardless of odp_thread type. odp_threads may be > of type > ++ODP_THREAD_WORKER+ or +ODP_THREAD_CONTROL+ > > -Shutdown > -~~~~~~~~~ > -Shutdown is the logical reverse of the initialization procedure, with > 'odp_thread_term()' called for each worker before 'odp_term_global()' is > called. > +=== Shutdown === > + > +Shutdown is the logical reverse of the initialization procedure, with > +'odp_thread_term()' called for each worker before 'odp_term_global()' is > called. > > image::../images/resource_management.png[align="center"] > > @@ -474,27 +497,35 @@ Queues > There are three queue types, atomic, ordered and parallel. > A queue belongs to a single odp_worker and a odp_worker may have multiple > queues. > > -Events are sent to a queue, and the the sender chooses a queue based on > the service it needs. > -The sender does not need to know which odp_worker (on which core) or HW > accelerator will process the event, but all the events on a queue are > eventually scheduled and processed. > +Events are sent to a queue, and the the sender chooses a queue based on > the > +service it needs. > +The sender does not need to know which odp_worker (on which core) or HW > +accelerator will process the event, but all the events on a queue are > eventually > +scheduled and processed. > > -NOTE: Both ordered and parallel queue types improve throughput over an > atomic queue (due to parallel event processing), but the user has to take > care of the context data synchronization (if needed). > +NOTE: Both ordered and parallel queue types improve throughput over an > atomic > +queue (due to parallel event processing), but the user has to take care > of the > +context data synchronization (if needed). > > -Atomic Queue > -~~~~~~~~~~~~ > -Only one event at a time may be processed from a given queue. The > processing maintains order and context data synchronization but this will > impair scaling. > +=== Atomic Queue === > + > +Only one event at a time may be processed from a given queue. The > processing > +maintains order and context data synchronization but this will impair > scaling. > > .Overview Atomic Queue processing > image::../images/atomic_queue.png[align="center"] > > -Ordered Queue > -~~~~~~~~~~~~~ > -An ordered queue will ensure that the sequencing at the output is > identical to that of the input, but multiple events may be processed > simultaneously and the order is restored before the events move to the next > queue > +=== Ordered Queue === > + > +An ordered queue will ensure that the sequencing at the output is > identical to > +that of the input, but multiple events may be processed simultaneously > and the > +order is restored before the events move to the next queue > > .Overview Ordered Queue processing > image::../images/ordered_queue.png[align="center"] > > -Parallel Queue > -~~~~~~~~~~~~~~ > +=== Parallel Queue === > + > There are no restrictions on the number of events being processed. > > .Overview parallel Queue processing > -- > 2.5.0 > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > https://lists.linaro.org/mailman/listinfo/lng-odp >
Thanks, unless Maxim needs it I wont resend. On 18 November 2015 at 14:53, Bill Fischofer <bill.fischofer@linaro.org> wrote: > Looks like this patch needs to be applied on top of my patch to the user > guide. Other than that: > > On Wed, Nov 18, 2015 at 11:03 AM, Mike Holmes <mike.holmes@linaro.org> > wrote: > >> Signed-off-by: Mike Holmes <mike.holmes@linaro.org> >> > > Reviewed-and-tested-by: Bill Fischofer <bill.fischofer@linaro.org> > > >> --- >> doc/users-guide/users-guide.adoc | 101 >> +++++++++++++++++++++++++-------------- >> 1 file changed, 66 insertions(+), 35 deletions(-) >> >> diff --git a/doc/users-guide/users-guide.adoc >> b/doc/users-guide/users-guide.adoc >> index be40d2f..e087696 100644 >> --- a/doc/users-guide/users-guide.adoc >> +++ b/doc/users-guide/users-guide.adoc >> @@ -8,13 +8,16 @@ OpenDataPlane (ODP) Users-Guide >> Abstract >> -------- >> This document is intended to guide a new ODP application developer. >> -Further details about ODP may be found at the 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"] >> >> -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. >> +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 == >> @@ -422,23 +425,35 @@ goals. Again, the advantage here is that on many >> platforms traffic management >> functions are implemented in hardware, permitting transparent offload of >> this work. >> >> -Glossary >> --------- >> +== Glossary == >> + >> [glossary] >> odp_worker:: >> - An opd_worker is a type of odp_thread. It will usually be isolated >> from the scheduling of any host operating system and is intended for >> fast-path processing with a low and predictable latency. Odp_workers will >> not generally receive interrupts and will run to completion. >> + An opd_worker is a type of odp_thread. It will usually be isolated >> from the >> + scheduling of any host operating system and is intended for fast-path >> + processing with a low and predictable latency. Odp_workers will not >> + generally receive interrupts and will run to completion. >> odp_control:: >> - An odp_control is a type of odp_thread. It will be isolated from the >> host operating system house keeping tasks but will be scheduled by it and >> may receive interrupts. >> + An odp_control is a type of odp_thread. It will be isolated from the >> host >> + operating system house keeping tasks but will be scheduled by it and >> may >> + receive interrupts. >> odp_thread:: >> - An odp_thread is a flow of execution that in a Linux environment >> could be a Linux process or thread. >> + An odp_thread is a flow of execution that in a Linux environment >> could be a >> + Linux process or thread. >> event:: >> An event is a notification that can be placed in a queue. >> >> -The include structure >> ---------------------- >> -Applications only include the 'include/odp.h file which includes the >> 'platform/<implementation name>/include/plat' files to provide a complete >> definition of the API on that platform. >> -The doxygen documentation defining the behavior of the ODP API is all >> contained in the public API files, and the actual definitions for an >> implementation will be found in the per platform directories. >> -Per-platform data that might normally be a #define can be recovered via >> the appropriate access function if the #define is not directly visible to >> the application. >> +== The include structure == >> + >> +Applications only include the 'include/odp.h' file which includes the >> +'platform/<implementation name>/include/plat' files to provide a complete >> +definition of the API on that platform. >> +The doxygen documentation defining the behavior of the ODP API is all >> contained >> +in the public API files, and the actual definitions for an >> implementation will >> +be found in the per platform directories. >> +Per-platform data that might normally be a #define can be recovered via >> the >> +appropriate access function if the #define is not directly visible to the >> +application. >> >> .Users include structure >> ---- >> @@ -451,21 +466,29 @@ Per-platform data that might normally be a #define >> can be recovered via the appr >> │ └── odp.h This file should be the only file included by the >> application. >> ---- >> >> -Initialization >> --------------- >> -IMPORTANT: ODP depends on the application to perform a graceful >> shutdown, calling the terminate functions should only be done when the >> application is sure it has closed the ingress and subsequently drained all >> queues etc. >> +== Initialization == >> + >> +IMPORTANT: ODP depends on the application to perform a graceful shutdown, >> +calling the terminate functions should only be done when the application >> is sure >> +it has closed the ingress and subsequently drained all queues etc. >> + >> +=== Startup === >> >> -Startup >> -~~~~~~~~ >> The first API that must be called is 'odp_init_global()'. >> -This takes two pointers, odp_init_t contains ODP initialization data >> that is platform independent and portable. >> -The second odp_platform_init_t is passed un parsed to the >> implementation and can be used for platform specific data that is not yet, >> or may never be suitable for the ODP API. >> +This takes two pointers, +odp_init_t+ contains ODP initialization data >> that is >> +platform independent and portable. >> +The second +odp_platform_init_t+ is passed un parsed to the >> implementation and >> +can be used for platform specific data that is not yet, or may never be >> suitable >> +for the ODP API. >> >> -The second API that must be called is 'odp_init_local()', this must be >> called once per odp_thread, regardless of odp_thread type. Odp_threads may >> be of type ODP_THREAD_WORKER or ODP_THREAD_CONTROL >> +The second API that must be called is 'odp_init_local()', this must be >> called >> +once per odp_thread, regardless of odp_thread type. odp_threads may be >> of type >> ++ODP_THREAD_WORKER+ or +ODP_THREAD_CONTROL+ >> >> -Shutdown >> -~~~~~~~~~ >> -Shutdown is the logical reverse of the initialization procedure, with >> 'odp_thread_term()' called for each worker before 'odp_term_global()' is >> called. >> +=== Shutdown === >> + >> +Shutdown is the logical reverse of the initialization procedure, with >> +'odp_thread_term()' called for each worker before 'odp_term_global()' is >> called. >> >> image::../images/resource_management.png[align="center"] >> >> @@ -474,27 +497,35 @@ Queues >> There are three queue types, atomic, ordered and parallel. >> A queue belongs to a single odp_worker and a odp_worker may have >> multiple queues. >> >> -Events are sent to a queue, and the the sender chooses a queue based on >> the service it needs. >> -The sender does not need to know which odp_worker (on which core) or HW >> accelerator will process the event, but all the events on a queue are >> eventually scheduled and processed. >> +Events are sent to a queue, and the the sender chooses a queue based on >> the >> +service it needs. >> +The sender does not need to know which odp_worker (on which core) or HW >> +accelerator will process the event, but all the events on a queue are >> eventually >> +scheduled and processed. >> >> -NOTE: Both ordered and parallel queue types improve throughput over an >> atomic queue (due to parallel event processing), but the user has to take >> care of the context data synchronization (if needed). >> +NOTE: Both ordered and parallel queue types improve throughput over an >> atomic >> +queue (due to parallel event processing), but the user has to take care >> of the >> +context data synchronization (if needed). >> >> -Atomic Queue >> -~~~~~~~~~~~~ >> -Only one event at a time may be processed from a given queue. The >> processing maintains order and context data synchronization but this will >> impair scaling. >> +=== Atomic Queue === >> + >> +Only one event at a time may be processed from a given queue. The >> processing >> +maintains order and context data synchronization but this will impair >> scaling. >> >> .Overview Atomic Queue processing >> image::../images/atomic_queue.png[align="center"] >> >> -Ordered Queue >> -~~~~~~~~~~~~~ >> -An ordered queue will ensure that the sequencing at the output is >> identical to that of the input, but multiple events may be processed >> simultaneously and the order is restored before the events move to the next >> queue >> +=== Ordered Queue === >> + >> +An ordered queue will ensure that the sequencing at the output is >> identical to >> +that of the input, but multiple events may be processed simultaneously >> and the >> +order is restored before the events move to the next queue >> >> .Overview Ordered Queue processing >> image::../images/ordered_queue.png[align="center"] >> >> -Parallel Queue >> -~~~~~~~~~~~~~~ >> +=== Parallel Queue === >> + >> There are no restrictions on the number of events being processed. >> >> .Overview parallel Queue processing >> -- >> 2.5.0 >> >> _______________________________________________ >> 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 <http://www.linaro.org/> *│ *Open source software for ARM SoCs
Another reason to merge these since I have further updates I'd like to submit but don't want to get into a tower of babel set of patches. BTW, my base patch still needs a reviewed-by On Wed, Nov 18, 2015 at 1:56 PM, Mike Holmes <mike.holmes@linaro.org> wrote: > Thanks, unless Maxim needs it I wont resend. > > On 18 November 2015 at 14:53, Bill Fischofer <bill.fischofer@linaro.org> > wrote: > >> Looks like this patch needs to be applied on top of my patch to the user >> guide. Other than that: >> >> On Wed, Nov 18, 2015 at 11:03 AM, Mike Holmes <mike.holmes@linaro.org> >> wrote: >> >>> Signed-off-by: Mike Holmes <mike.holmes@linaro.org> >>> >> >> Reviewed-and-tested-by: Bill Fischofer <bill.fischofer@linaro.org> >> >> >>> --- >>> doc/users-guide/users-guide.adoc | 101 >>> +++++++++++++++++++++++++-------------- >>> 1 file changed, 66 insertions(+), 35 deletions(-) >>> >>> diff --git a/doc/users-guide/users-guide.adoc >>> b/doc/users-guide/users-guide.adoc >>> index be40d2f..e087696 100644 >>> --- a/doc/users-guide/users-guide.adoc >>> +++ b/doc/users-guide/users-guide.adoc >>> @@ -8,13 +8,16 @@ OpenDataPlane (ODP) Users-Guide >>> Abstract >>> -------- >>> This document is intended to guide a new ODP application developer. >>> -Further details about ODP may be found at the 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"] >>> >>> -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. >>> +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 == >>> @@ -422,23 +425,35 @@ goals. Again, the advantage here is that on many >>> platforms traffic management >>> functions are implemented in hardware, permitting transparent offload of >>> this work. >>> >>> -Glossary >>> --------- >>> +== Glossary == >>> + >>> [glossary] >>> odp_worker:: >>> - An opd_worker is a type of odp_thread. It will usually be isolated >>> from the scheduling of any host operating system and is intended for >>> fast-path processing with a low and predictable latency. Odp_workers will >>> not generally receive interrupts and will run to completion. >>> + An opd_worker is a type of odp_thread. It will usually be isolated >>> from the >>> + scheduling of any host operating system and is intended for >>> fast-path >>> + processing with a low and predictable latency. Odp_workers will not >>> + generally receive interrupts and will run to completion. >>> odp_control:: >>> - An odp_control is a type of odp_thread. It will be isolated from >>> the host operating system house keeping tasks but will be scheduled by it >>> and may receive interrupts. >>> + An odp_control is a type of odp_thread. It will be isolated from >>> the host >>> + operating system house keeping tasks but will be scheduled by it >>> and may >>> + receive interrupts. >>> odp_thread:: >>> - An odp_thread is a flow of execution that in a Linux environment >>> could be a Linux process or thread. >>> + An odp_thread is a flow of execution that in a Linux environment >>> could be a >>> + Linux process or thread. >>> event:: >>> An event is a notification that can be placed in a queue. >>> >>> -The include structure >>> ---------------------- >>> -Applications only include the 'include/odp.h file which includes the >>> 'platform/<implementation name>/include/plat' files to provide a complete >>> definition of the API on that platform. >>> -The doxygen documentation defining the behavior of the ODP API is all >>> contained in the public API files, and the actual definitions for an >>> implementation will be found in the per platform directories. >>> -Per-platform data that might normally be a #define can be recovered via >>> the appropriate access function if the #define is not directly visible to >>> the application. >>> +== The include structure == >>> + >>> +Applications only include the 'include/odp.h' file which includes the >>> +'platform/<implementation name>/include/plat' files to provide a >>> complete >>> +definition of the API on that platform. >>> +The doxygen documentation defining the behavior of the ODP API is all >>> contained >>> +in the public API files, and the actual definitions for an >>> implementation will >>> +be found in the per platform directories. >>> +Per-platform data that might normally be a #define can be recovered via >>> the >>> +appropriate access function if the #define is not directly visible to >>> the >>> +application. >>> >>> .Users include structure >>> ---- >>> @@ -451,21 +466,29 @@ Per-platform data that might normally be a #define >>> can be recovered via the appr >>> │ └── odp.h This file should be the only file included by the >>> application. >>> ---- >>> >>> -Initialization >>> --------------- >>> -IMPORTANT: ODP depends on the application to perform a graceful >>> shutdown, calling the terminate functions should only be done when the >>> application is sure it has closed the ingress and subsequently drained all >>> queues etc. >>> +== Initialization == >>> + >>> +IMPORTANT: ODP depends on the application to perform a graceful >>> shutdown, >>> +calling the terminate functions should only be done when the >>> application is sure >>> +it has closed the ingress and subsequently drained all queues etc. >>> + >>> +=== Startup === >>> >>> -Startup >>> -~~~~~~~~ >>> The first API that must be called is 'odp_init_global()'. >>> -This takes two pointers, odp_init_t contains ODP initialization data >>> that is platform independent and portable. >>> -The second odp_platform_init_t is passed un parsed to the >>> implementation and can be used for platform specific data that is not yet, >>> or may never be suitable for the ODP API. >>> +This takes two pointers, +odp_init_t+ contains ODP initialization data >>> that is >>> +platform independent and portable. >>> +The second +odp_platform_init_t+ is passed un parsed to the >>> implementation and >>> +can be used for platform specific data that is not yet, or may never be >>> suitable >>> +for the ODP API. >>> >>> -The second API that must be called is 'odp_init_local()', this must be >>> called once per odp_thread, regardless of odp_thread type. Odp_threads may >>> be of type ODP_THREAD_WORKER or ODP_THREAD_CONTROL >>> +The second API that must be called is 'odp_init_local()', this must be >>> called >>> +once per odp_thread, regardless of odp_thread type. odp_threads may be >>> of type >>> ++ODP_THREAD_WORKER+ or +ODP_THREAD_CONTROL+ >>> >>> -Shutdown >>> -~~~~~~~~~ >>> -Shutdown is the logical reverse of the initialization procedure, with >>> 'odp_thread_term()' called for each worker before 'odp_term_global()' is >>> called. >>> +=== Shutdown === >>> + >>> +Shutdown is the logical reverse of the initialization procedure, with >>> +'odp_thread_term()' called for each worker before 'odp_term_global()' >>> is called. >>> >>> image::../images/resource_management.png[align="center"] >>> >>> @@ -474,27 +497,35 @@ Queues >>> There are three queue types, atomic, ordered and parallel. >>> A queue belongs to a single odp_worker and a odp_worker may have >>> multiple queues. >>> >>> -Events are sent to a queue, and the the sender chooses a queue based on >>> the service it needs. >>> -The sender does not need to know which odp_worker (on which core) or HW >>> accelerator will process the event, but all the events on a queue are >>> eventually scheduled and processed. >>> +Events are sent to a queue, and the the sender chooses a queue based on >>> the >>> +service it needs. >>> +The sender does not need to know which odp_worker (on which core) or HW >>> +accelerator will process the event, but all the events on a queue are >>> eventually >>> +scheduled and processed. >>> >>> -NOTE: Both ordered and parallel queue types improve throughput over an >>> atomic queue (due to parallel event processing), but the user has to take >>> care of the context data synchronization (if needed). >>> +NOTE: Both ordered and parallel queue types improve throughput over an >>> atomic >>> +queue (due to parallel event processing), but the user has to take care >>> of the >>> +context data synchronization (if needed). >>> >>> -Atomic Queue >>> -~~~~~~~~~~~~ >>> -Only one event at a time may be processed from a given queue. The >>> processing maintains order and context data synchronization but this will >>> impair scaling. >>> +=== Atomic Queue === >>> + >>> +Only one event at a time may be processed from a given queue. The >>> processing >>> +maintains order and context data synchronization but this will impair >>> scaling. >>> >>> .Overview Atomic Queue processing >>> image::../images/atomic_queue.png[align="center"] >>> >>> -Ordered Queue >>> -~~~~~~~~~~~~~ >>> -An ordered queue will ensure that the sequencing at the output is >>> identical to that of the input, but multiple events may be processed >>> simultaneously and the order is restored before the events move to the next >>> queue >>> +=== Ordered Queue === >>> + >>> +An ordered queue will ensure that the sequencing at the output is >>> identical to >>> +that of the input, but multiple events may be processed simultaneously >>> and the >>> +order is restored before the events move to the next queue >>> >>> .Overview Ordered Queue processing >>> image::../images/ordered_queue.png[align="center"] >>> >>> -Parallel Queue >>> -~~~~~~~~~~~~~~ >>> +=== Parallel Queue === >>> + >>> There are no restrictions on the number of events being processed. >>> >>> .Overview parallel Queue processing >>> -- >>> 2.5.0 >>> >>> _______________________________________________ >>> 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 <http://www.linaro.org/> *│ *Open source software for ARM SoCs > > >
I will take a look soon so that we get the basics in. On 18 November 2015 at 14:59, Bill Fischofer <bill.fischofer@linaro.org> wrote: > Another reason to merge these since I have further updates I'd like to > submit but don't want to get into a tower of babel set of patches. > > BTW, my base patch still needs a reviewed-by > > On Wed, Nov 18, 2015 at 1:56 PM, Mike Holmes <mike.holmes@linaro.org> > wrote: > >> Thanks, unless Maxim needs it I wont resend. >> >> On 18 November 2015 at 14:53, Bill Fischofer <bill.fischofer@linaro.org> >> wrote: >> >>> Looks like this patch needs to be applied on top of my patch to the user >>> guide. Other than that: >>> >>> On Wed, Nov 18, 2015 at 11:03 AM, Mike Holmes <mike.holmes@linaro.org> >>> wrote: >>> >>>> Signed-off-by: Mike Holmes <mike.holmes@linaro.org> >>>> >>> >>> Reviewed-and-tested-by: Bill Fischofer <bill.fischofer@linaro.org> >>> >>> >>>> --- >>>> doc/users-guide/users-guide.adoc | 101 >>>> +++++++++++++++++++++++++-------------- >>>> 1 file changed, 66 insertions(+), 35 deletions(-) >>>> >>>> diff --git a/doc/users-guide/users-guide.adoc >>>> b/doc/users-guide/users-guide.adoc >>>> index be40d2f..e087696 100644 >>>> --- a/doc/users-guide/users-guide.adoc >>>> +++ b/doc/users-guide/users-guide.adoc >>>> @@ -8,13 +8,16 @@ OpenDataPlane (ODP) Users-Guide >>>> Abstract >>>> -------- >>>> This document is intended to guide a new ODP application developer. >>>> -Further details about ODP may be found at the 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"] >>>> >>>> -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. >>>> +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 == >>>> @@ -422,23 +425,35 @@ goals. Again, the advantage here is that on many >>>> platforms traffic management >>>> functions are implemented in hardware, permitting transparent offload >>>> of >>>> this work. >>>> >>>> -Glossary >>>> --------- >>>> +== Glossary == >>>> + >>>> [glossary] >>>> odp_worker:: >>>> - An opd_worker is a type of odp_thread. It will usually be isolated >>>> from the scheduling of any host operating system and is intended for >>>> fast-path processing with a low and predictable latency. Odp_workers will >>>> not generally receive interrupts and will run to completion. >>>> + An opd_worker is a type of odp_thread. It will usually be isolated >>>> from the >>>> + scheduling of any host operating system and is intended for >>>> fast-path >>>> + processing with a low and predictable latency. Odp_workers will not >>>> + generally receive interrupts and will run to completion. >>>> odp_control:: >>>> - An odp_control is a type of odp_thread. It will be isolated from >>>> the host operating system house keeping tasks but will be scheduled by it >>>> and may receive interrupts. >>>> + An odp_control is a type of odp_thread. It will be isolated from >>>> the host >>>> + operating system house keeping tasks but will be scheduled by it >>>> and may >>>> + receive interrupts. >>>> odp_thread:: >>>> - An odp_thread is a flow of execution that in a Linux environment >>>> could be a Linux process or thread. >>>> + An odp_thread is a flow of execution that in a Linux environment >>>> could be a >>>> + Linux process or thread. >>>> event:: >>>> An event is a notification that can be placed in a queue. >>>> >>>> -The include structure >>>> ---------------------- >>>> -Applications only include the 'include/odp.h file which includes the >>>> 'platform/<implementation name>/include/plat' files to provide a complete >>>> definition of the API on that platform. >>>> -The doxygen documentation defining the behavior of the ODP API is all >>>> contained in the public API files, and the actual definitions for an >>>> implementation will be found in the per platform directories. >>>> -Per-platform data that might normally be a #define can be recovered >>>> via the appropriate access function if the #define is not directly visible >>>> to the application. >>>> +== The include structure == >>>> + >>>> +Applications only include the 'include/odp.h' file which includes the >>>> +'platform/<implementation name>/include/plat' files to provide a >>>> complete >>>> +definition of the API on that platform. >>>> +The doxygen documentation defining the behavior of the ODP API is all >>>> contained >>>> +in the public API files, and the actual definitions for an >>>> implementation will >>>> +be found in the per platform directories. >>>> +Per-platform data that might normally be a #define can be recovered >>>> via the >>>> +appropriate access function if the #define is not directly visible to >>>> the >>>> +application. >>>> >>>> .Users include structure >>>> ---- >>>> @@ -451,21 +466,29 @@ Per-platform data that might normally be a >>>> #define can be recovered via the appr >>>> │ └── odp.h This file should be the only file included by the >>>> application. >>>> ---- >>>> >>>> -Initialization >>>> --------------- >>>> -IMPORTANT: ODP depends on the application to perform a graceful >>>> shutdown, calling the terminate functions should only be done when the >>>> application is sure it has closed the ingress and subsequently drained all >>>> queues etc. >>>> +== Initialization == >>>> + >>>> +IMPORTANT: ODP depends on the application to perform a graceful >>>> shutdown, >>>> +calling the terminate functions should only be done when the >>>> application is sure >>>> +it has closed the ingress and subsequently drained all queues etc. >>>> + >>>> +=== Startup === >>>> >>>> -Startup >>>> -~~~~~~~~ >>>> The first API that must be called is 'odp_init_global()'. >>>> -This takes two pointers, odp_init_t contains ODP initialization data >>>> that is platform independent and portable. >>>> -The second odp_platform_init_t is passed un parsed to the >>>> implementation and can be used for platform specific data that is not yet, >>>> or may never be suitable for the ODP API. >>>> +This takes two pointers, +odp_init_t+ contains ODP initialization data >>>> that is >>>> +platform independent and portable. >>>> +The second +odp_platform_init_t+ is passed un parsed to the >>>> implementation and >>>> +can be used for platform specific data that is not yet, or may never >>>> be suitable >>>> +for the ODP API. >>>> >>>> -The second API that must be called is 'odp_init_local()', this must be >>>> called once per odp_thread, regardless of odp_thread type. Odp_threads may >>>> be of type ODP_THREAD_WORKER or ODP_THREAD_CONTROL >>>> +The second API that must be called is 'odp_init_local()', this must be >>>> called >>>> +once per odp_thread, regardless of odp_thread type. odp_threads may >>>> be of type >>>> ++ODP_THREAD_WORKER+ or +ODP_THREAD_CONTROL+ >>>> >>>> -Shutdown >>>> -~~~~~~~~~ >>>> -Shutdown is the logical reverse of the initialization procedure, with >>>> 'odp_thread_term()' called for each worker before 'odp_term_global()' is >>>> called. >>>> +=== Shutdown === >>>> + >>>> +Shutdown is the logical reverse of the initialization procedure, with >>>> +'odp_thread_term()' called for each worker before 'odp_term_global()' >>>> is called. >>>> >>>> image::../images/resource_management.png[align="center"] >>>> >>>> @@ -474,27 +497,35 @@ Queues >>>> There are three queue types, atomic, ordered and parallel. >>>> A queue belongs to a single odp_worker and a odp_worker may have >>>> multiple queues. >>>> >>>> -Events are sent to a queue, and the the sender chooses a queue based >>>> on the service it needs. >>>> -The sender does not need to know which odp_worker (on which core) or >>>> HW accelerator will process the event, but all the events on a queue are >>>> eventually scheduled and processed. >>>> +Events are sent to a queue, and the the sender chooses a queue based >>>> on the >>>> +service it needs. >>>> +The sender does not need to know which odp_worker (on which core) or HW >>>> +accelerator will process the event, but all the events on a queue are >>>> eventually >>>> +scheduled and processed. >>>> >>>> -NOTE: Both ordered and parallel queue types improve throughput over an >>>> atomic queue (due to parallel event processing), but the user has to take >>>> care of the context data synchronization (if needed). >>>> +NOTE: Both ordered and parallel queue types improve throughput over an >>>> atomic >>>> +queue (due to parallel event processing), but the user has to take >>>> care of the >>>> +context data synchronization (if needed). >>>> >>>> -Atomic Queue >>>> -~~~~~~~~~~~~ >>>> -Only one event at a time may be processed from a given queue. The >>>> processing maintains order and context data synchronization but this will >>>> impair scaling. >>>> +=== Atomic Queue === >>>> + >>>> +Only one event at a time may be processed from a given queue. The >>>> processing >>>> +maintains order and context data synchronization but this will impair >>>> scaling. >>>> >>>> .Overview Atomic Queue processing >>>> image::../images/atomic_queue.png[align="center"] >>>> >>>> -Ordered Queue >>>> -~~~~~~~~~~~~~ >>>> -An ordered queue will ensure that the sequencing at the output is >>>> identical to that of the input, but multiple events may be processed >>>> simultaneously and the order is restored before the events move to the next >>>> queue >>>> +=== Ordered Queue === >>>> + >>>> +An ordered queue will ensure that the sequencing at the output is >>>> identical to >>>> +that of the input, but multiple events may be processed simultaneously >>>> and the >>>> +order is restored before the events move to the next queue >>>> >>>> .Overview Ordered Queue processing >>>> image::../images/ordered_queue.png[align="center"] >>>> >>>> -Parallel Queue >>>> -~~~~~~~~~~~~~~ >>>> +=== Parallel Queue === >>>> + >>>> There are no restrictions on the number of events being processed. >>>> >>>> .Overview parallel Queue processing >>>> -- >>>> 2.5.0 >>>> >>>> _______________________________________________ >>>> 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 <http://www.linaro.org/> *│ *Open source software for ARM SoCs >> >> >> > -- Mike Holmes Technical Manager - Linaro Networking Group Linaro.org <http://www.linaro.org/> *│ *Open source software for ARM SoCs
diff --git a/doc/users-guide/users-guide.adoc b/doc/users-guide/users-guide.adoc index be40d2f..e087696 100644 --- a/doc/users-guide/users-guide.adoc +++ b/doc/users-guide/users-guide.adoc @@ -8,13 +8,16 @@ OpenDataPlane (ODP) Users-Guide Abstract -------- This document is intended to guide a new ODP application developer. -Further details about ODP may be found at the 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"] -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. +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 == @@ -422,23 +425,35 @@ goals. Again, the advantage here is that on many platforms traffic management functions are implemented in hardware, permitting transparent offload of this work. -Glossary --------- +== Glossary == + [glossary] odp_worker:: - An opd_worker is a type of odp_thread. It will usually be isolated from the scheduling of any host operating system and is intended for fast-path processing with a low and predictable latency. Odp_workers will not generally receive interrupts and will run to completion. + An opd_worker is a type of odp_thread. It will usually be isolated from the + scheduling of any host operating system and is intended for fast-path + processing with a low and predictable latency. Odp_workers will not + generally receive interrupts and will run to completion. odp_control:: - An odp_control is a type of odp_thread. It will be isolated from the host operating system house keeping tasks but will be scheduled by it and may receive interrupts. + An odp_control is a type of odp_thread. It will be isolated from the host + operating system house keeping tasks but will be scheduled by it and may + receive interrupts. odp_thread:: - An odp_thread is a flow of execution that in a Linux environment could be a Linux process or thread. + An odp_thread is a flow of execution that in a Linux environment could be a + Linux process or thread. event:: An event is a notification that can be placed in a queue. -The include structure ---------------------- -Applications only include the 'include/odp.h file which includes the 'platform/<implementation name>/include/plat' files to provide a complete definition of the API on that platform. -The doxygen documentation defining the behavior of the ODP API is all contained in the public API files, and the actual definitions for an implementation will be found in the per platform directories. -Per-platform data that might normally be a #define can be recovered via the appropriate access function if the #define is not directly visible to the application. +== The include structure == + +Applications only include the 'include/odp.h' file which includes the +'platform/<implementation name>/include/plat' files to provide a complete +definition of the API on that platform. +The doxygen documentation defining the behavior of the ODP API is all contained +in the public API files, and the actual definitions for an implementation will +be found in the per platform directories. +Per-platform data that might normally be a #define can be recovered via the +appropriate access function if the #define is not directly visible to the +application. .Users include structure ---- @@ -451,21 +466,29 @@ Per-platform data that might normally be a #define can be recovered via the appr │ └── odp.h This file should be the only file included by the application. ---- -Initialization --------------- -IMPORTANT: ODP depends on the application to perform a graceful shutdown, calling the terminate functions should only be done when the application is sure it has closed the ingress and subsequently drained all queues etc. +== Initialization == + +IMPORTANT: ODP depends on the application to perform a graceful shutdown, +calling the terminate functions should only be done when the application is sure +it has closed the ingress and subsequently drained all queues etc. + +=== Startup === -Startup -~~~~~~~~ The first API that must be called is 'odp_init_global()'. -This takes two pointers, odp_init_t contains ODP initialization data that is platform independent and portable. -The second odp_platform_init_t is passed un parsed to the implementation and can be used for platform specific data that is not yet, or may never be suitable for the ODP API. +This takes two pointers, +odp_init_t+ contains ODP initialization data that is +platform independent and portable. +The second +odp_platform_init_t+ is passed un parsed to the implementation and +can be used for platform specific data that is not yet, or may never be suitable +for the ODP API. -The second API that must be called is 'odp_init_local()', this must be called once per odp_thread, regardless of odp_thread type. Odp_threads may be of type ODP_THREAD_WORKER or ODP_THREAD_CONTROL +The second API that must be called is 'odp_init_local()', this must be called +once per odp_thread, regardless of odp_thread type. odp_threads may be of type ++ODP_THREAD_WORKER+ or +ODP_THREAD_CONTROL+ -Shutdown -~~~~~~~~~ -Shutdown is the logical reverse of the initialization procedure, with 'odp_thread_term()' called for each worker before 'odp_term_global()' is called. +=== Shutdown === + +Shutdown is the logical reverse of the initialization procedure, with +'odp_thread_term()' called for each worker before 'odp_term_global()' is called. image::../images/resource_management.png[align="center"] @@ -474,27 +497,35 @@ Queues There are three queue types, atomic, ordered and parallel. A queue belongs to a single odp_worker and a odp_worker may have multiple queues. -Events are sent to a queue, and the the sender chooses a queue based on the service it needs. -The sender does not need to know which odp_worker (on which core) or HW accelerator will process the event, but all the events on a queue are eventually scheduled and processed. +Events are sent to a queue, and the the sender chooses a queue based on the +service it needs. +The sender does not need to know which odp_worker (on which core) or HW +accelerator will process the event, but all the events on a queue are eventually +scheduled and processed. -NOTE: Both ordered and parallel queue types improve throughput over an atomic queue (due to parallel event processing), but the user has to take care of the context data synchronization (if needed). +NOTE: Both ordered and parallel queue types improve throughput over an atomic +queue (due to parallel event processing), but the user has to take care of the +context data synchronization (if needed). -Atomic Queue -~~~~~~~~~~~~ -Only one event at a time may be processed from a given queue. The processing maintains order and context data synchronization but this will impair scaling. +=== Atomic Queue === + +Only one event at a time may be processed from a given queue. The processing +maintains order and context data synchronization but this will impair scaling. .Overview Atomic Queue processing image::../images/atomic_queue.png[align="center"] -Ordered Queue -~~~~~~~~~~~~~ -An ordered queue will ensure that the sequencing at the output is identical to that of the input, but multiple events may be processed simultaneously and the order is restored before the events move to the next queue +=== Ordered Queue === + +An ordered queue will ensure that the sequencing at the output is identical to +that of the input, but multiple events may be processed simultaneously and the +order is restored before the events move to the next queue .Overview Ordered Queue processing image::../images/ordered_queue.png[align="center"] -Parallel Queue -~~~~~~~~~~~~~~ +=== Parallel Queue === + There are no restrictions on the number of events being processed. .Overview parallel Queue processing
Signed-off-by: Mike Holmes <mike.holmes@linaro.org> --- doc/users-guide/users-guide.adoc | 101 +++++++++++++++++++++++++-------------- 1 file changed, 66 insertions(+), 35 deletions(-)