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
