On 2 November 2015 at 04:51, Maxim Uvarov <[email protected]> wrote:
> On 10/22/2015 22:56, Mike Holmes wrote: > >> Signed-off-by: Mike Holmes <[email protected]> >> --- >> configure.ac | 1 + >> doc/Makefile.am | 2 +- >> doc/users-guide/Makefile.am | 10 +++++ >> doc/users-guide/guide.dox | 14 ------ >> doc/users-guide/users-guide.adoc | 92 >> ++++++++++++++++++++++++++++++++++++++++ >> 5 files changed, 104 insertions(+), 15 deletions(-) >> create mode 100644 doc/users-guide/Makefile.am >> delete mode 100644 doc/users-guide/guide.dox >> create mode 100644 doc/users-guide/users-guide.adoc >> >> diff --git a/configure.ac b/configure.ac >> index fde7d94..3a42e22 100644 >> --- a/configure.ac >> +++ b/configure.ac >> @@ -316,6 +316,7 @@ AM_CXXFLAGS="-std=c++11" >> AC_CONFIG_FILES([Makefile >> doc/Makefile >> doc/implementers-guide/Makefile >> + doc/users-guide/Makefile >> doc/images/Makefile >> example/Makefile >> example/classifier/Makefile >> diff --git a/doc/Makefile.am b/doc/Makefile.am >> index 3aa29a3..16d2160 100644 >> --- a/doc/Makefile.am >> +++ b/doc/Makefile.am >> @@ -6,5 +6,5 @@ clean-local: >> endif >> if user_guide >> -SUBDIRS += implementers-guide >> +SUBDIRS += implementers-guide users-guide >> endif >> diff --git a/doc/users-guide/Makefile.am b/doc/users-guide/Makefile.am >> new file mode 100644 >> index 0000000..312358d >> --- /dev/null >> +++ b/doc/users-guide/Makefile.am >> @@ -0,0 +1,10 @@ >> +TARGET = $(top_srcdir)/doc/output/users-guide.html >> + >> +all-local: $(TARGET) >> + >> +$(TARGET): users-guide.adoc >> + @mkdir -p $(top_srcdir)/doc/output >> + asciidoc --out-file=$@ $< >> + >> +clean-local: >> + rm -f $(TARGET) >> diff --git a/doc/users-guide/guide.dox b/doc/users-guide/guide.dox >> deleted file mode 100644 >> index f9289b8..0000000 >> --- a/doc/users-guide/guide.dox >> +++ /dev/null >> @@ -1,14 +0,0 @@ >> -/* Copyright (c) 2014, Linaro Limited >> - * All rights reserved >> - * >> - * SPDX-License-Identifier: BSD-3-Clause >> - */ >> - >> -/** >> - * >> - * @page users_guide Users Guide >> - * >> - * @section sec_gene Linux Generic >> - * @verbinclude linux-generic/README >> - * >> - */ >> diff --git a/doc/users-guide/users-guide.adoc >> b/doc/users-guide/users-guide.adoc >> new file mode 100644 >> index 0000000..1f71e35 >> --- /dev/null >> +++ b/doc/users-guide/users-guide.adoc >> @@ -0,0 +1,92 @@ >> +OpenDataPlane (ODP) Users-Guide >> +================================ >> +:toc: >> + >> + >> +:numbered!: >> +[abstract] >> +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. >> + >> +.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. >> + >> +Glossary >> +-------- >> +[glossary] >> +odp_worker:: >> + An opd_worker is a flow of execution a flow of execution that in a >> Linux environment could be a process or thread. >> > > "flow of execution" written twice. > > > +event:: >> + An event is a notification that can be placed in a queue. >> + >> +:numbered: >> +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 >> +---- >> +./ >> +├── include/ >> +│ ├── odp/ >> +│ │ └── api/ >> +│ │ └── The Public API and the documentation. >> +│ │ >> +│ └── 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. >> + >> +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. >> + >> +The second API that must be called is 'odp_init_local()', this must be >> called once per ODP worker, regardless of worker type. >> > or once per control odp_init_local(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. >> + >> +image::../images/resource_management.png[align="center"] >> + >> +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. >> + >> +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. >> + >> +.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 >> + >> +.Overview Ordered Queue processing >> +image::../images/ordered_queue.png[align="center"] >> + >> +Parallel Queue >> +~~~~~~~~~~~~~~ >> +There are no restrictions on the number of events being processed. >> + >> +.Overview parallel Queue processing >> +image::../images/parallel_queue.png[align="center"] >> > > _______________________________________________ > lng-odp mailing list > [email protected] > https://lists.linaro.org/mailman/listinfo/lng-odp > Thanks - I will generate a v2 -- 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
