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 <[email protected]> wrote: > Thanks, unless Maxim needs it I wont resend. > > On 18 November 2015 at 14:53, Bill Fischofer <[email protected]> > 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 <[email protected]> >> wrote: >> >>> Signed-off-by: Mike Holmes <[email protected]> >>> >> >> Reviewed-and-tested-by: Bill Fischofer <[email protected]> >> >> >>> --- >>> 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 >>> [email protected] >>> 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 > > >
_______________________________________________ lng-odp mailing list [email protected] https://lists.linaro.org/mailman/listinfo/lng-odp
