Re: [lng-odp] [PATCH 3/3] doc: users-guide convert to asciidoc
On 2 November 2015 at 04:51, Maxim Uvarov wrote: > On 10/22/2015 22:56, Mike Holmes wrote: > >> Signed-off-by: Mike Holmes >> --- >> 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 000..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..000 >> --- 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 000..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//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
Re: [lng-odp] [PATCH 3/3] doc: users-guide convert to asciidoc
On 10/22/2015 22:56, Mike Holmes wrote: Signed-off-by: Mike Holmes --- 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 000..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..000 --- 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 000..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//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_
[lng-odp] [PATCH 3/3] doc: users-guide convert to asciidoc
Signed-off-by: Mike Holmes --- 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 000..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..000 --- 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 000..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. +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//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. + +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 p
