I will take a look soon so that we get the basics in. On 18 November 2015 at 14:59, Bill Fischofer <bill.fischo...@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.hol...@linaro.org> > wrote: > >> Thanks, unless Maxim needs it I wont resend. >> >> On 18 November 2015 at 14:53, Bill Fischofer <bill.fischo...@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.hol...@linaro.org> >>> wrote: >>> >>>> Signed-off-by: Mike Holmes <mike.hol...@linaro.org> >>>> >>> >>> Reviewed-and-tested-by: Bill Fischofer <bill.fischo...@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
_______________________________________________ lng-odp mailing list lng-odp@lists.linaro.org https://lists.linaro.org/mailman/listinfo/lng-odp
