doxygen reorganisation

1. To make the structure better
2. To have a Users Guide
3. Remove out of date content

Signed-off-by: Anders Roxell <anders.roxell@linaro.org>
---

Hi,

I didn't want to include this patch into the previeous patchset
"Restructuring and cleanup README ", this should be added ontop of that.

Cheers,
Anders


 configure.ac                   |   2 +-
 doc/api/api.dox                |  11 +++
 doxygen.cfg => doc/doxygen.cfg |   4 +-
 doc/odp.dox                    | 184 -----------------------------------------
 doc/users-guide/guide.dox      |  18 ++++
 5 files changed, 32 insertions(+), 187 deletions(-)
 create mode 100644 doc/api/api.dox
 rename doxygen.cfg => doc/doxygen.cfg (83%)
 create mode 100644 doc/users-guide/guide.dox

On 25 July 2014 03:46, Anders Roxell <anders.roxell@linaro.org> wrote:

> 1. To make the structure better
> 2. To have a Users Guide
> 3. Remove out of date content
>
> Signed-off-by: Anders Roxell <anders.roxell@linaro.org>
>
Tested-by: Mike Holmes <mike.holmes@linaro.org>

> ---
>
> Hi,
>
> I didn't want to include this patch into the previeous patchset
> "Restructuring and cleanup README ", this should be added ontop of that.
>
> Cheers,
> Anders
>
>
>  configure.ac                   |   2 +-
>  doc/api/api.dox                |  11 +++
>  doxygen.cfg => doc/doxygen.cfg |   4 +-
>  doc/odp.dox                    | 184
> -----------------------------------------
>  doc/users-guide/guide.dox      |  18 ++++
>  5 files changed, 32 insertions(+), 187 deletions(-)
>  create mode 100644 doc/api/api.dox
>  rename doxygen.cfg => doc/doxygen.cfg (83%)
>  create mode 100644 doc/users-guide/guide.dox
>
> diff --git a/configure.ac b/configure.ac
> index 97089e9..f3f8579 100644
> --- a/configure.ac
> +++ b/configure.ac
> @@ -10,7 +10,7 @@ AM_SILENT_RULES([yes])
>
>  DX_HTML_FEATURE(ON)
>  DX_PDF_FEATURE(ON)
> -DX_INIT_DOXYGEN($PACKAGE_NAME, doxygen.cfg)
> +DX_INIT_DOXYGEN($PACKAGE_NAME, doc/doxygen.cfg)
>
>  # Checks for programs.
>  AC_PROG_CC
> diff --git a/doc/api/api.dox b/doc/api/api.dox
> new file mode 100644
> index 0000000..7522270
> --- /dev/null
> +++ b/doc/api/api.dox
> @@ -0,0 +1,11 @@
> +/* Copyright (c) 2014, Linaro Limited
> + * All rights reserved
> + *
> + * SPDX-License-Identifier:     BSD-3-Clause
> + */
> +
> +/**
> + *
> + * @page api Application Programming Interface (API) Guide
> + *
> + */
> diff --git a/doxygen.cfg b/doc/doxygen.cfg
> similarity index 83%
> rename from doxygen.cfg
> rename to doc/doxygen.cfg
> index 86fe92a..b3a033d 100644
> --- a/doxygen.cfg
> +++ b/doc/doxygen.cfg
> @@ -9,7 +9,7 @@ TYPEDEF_HIDES_STRUCT = YES
>  EXTRACT_STATIC = YES
>  SORT_MEMBER_DOCS = NO
>  WARN_NO_PARAMDOC = YES
> -INPUT = $(SRCDIR)/doc $(SRCDIR)/include $(SRCDIR)/example
> +INPUT = $(SRCDIR)/doc $(SRCDIR)/doc/users-guide $(SRCDIR)/doc/api
> $(SRCDIR)/include $(SRCDIR)/example
>  FILE_PATTERNS = odp*.h odp*.c *.dox
>  RECURSIVE = YES
>  SOURCE_BROWSER = YES
> @@ -23,7 +23,7 @@ CLASS_DIAGRAMS = NO
>  HAVE_DOT = YES
>  CALL_GRAPH = YES
>  DOT_MULTI_TARGETS = NO
> -EXAMPLE_PATH = $(SRCDIR)/example
> +EXAMPLE_PATH = $(SRCDIR)/example $(SRCDIR)/platform
>  EXAMPLE_PATTERNS = *.c
>  EXAMPLE_RECURSIVE = YES
>  IMAGE_PATH = $(SRCDIR)/doc/images
> diff --git a/doc/odp.dox b/doc/odp.dox
> index 328c7bb..73d1f37 100644
> --- a/doc/odp.dox
> +++ b/doc/odp.dox
> @@ -68,188 +68,4 @@
>   * - The git repo is https://git.linaro.org/lng/odp.git
>   * - Bug tracking https://launchpad.net/linaro-odp
>   *
> - *
> - * @section sec_2 User guide
> - *
> - * @subsection sub2_1 The ODP API
> - *
> - * This file (odp.h) is the main ODP API file. User should include only
> this
> - * file to keep portability since structure and naming of sub header files
> - * may be change between implementations.
> - *
> - * @subsection sub2_2 Threading
> - *
> - * ODP does not specify a threading model.  Applications can use
> - * processes or pthreads, or Roll-Your-Own (RYO) threading/fibre
> - * mechanisms for multi-threading as needed. Creation and control of
> - * threads is the responsibility of the ODP application. For optimal
> - * performance on many-core SoCs, it is recommended that threads be
> - * run on dedicated cores. ODP provides high-level APIs for core
> - * enumeration and assignment while the corresponding ODP
> - * implementation layer provides the appropriate mechanisms to realize
> - * these functions.
> - *
> - * Threads used for ODP processing should be pinned into separate cores.
> - * Commonly these threads process packets in a run-to-completion loop.
> - * Application should avoid blocking threads used for ODP processing,
> - * since it may cause blocking on other threads/cores.
> - *
> - * @subsection sub2_3 ODP initialisation
> - *
> - * Before calling any other ODP API functions, ODP library must be
> - * initialised by calling odp_init_global() once and odp_init_local()
> - * on each of the cores sharing the same ODP environment (instance).
> - *
> - * @subsection sub2_4 API Categories
> - *
> - * APIs provided by ODP cover the following areas:
> - *
> - * @subsubsection  memory_management Memory Management
> - *
> - *   This includes macros and other APIs to control memory alignments
> - *   of data structures as well as allocation/deallocation services
> - *   for ODP-managed objects.  Note that ODP does not wrapper malloc()
> - *   or similar platform specific APIs for the sake of wrappering.
> - *
> - * @subsubsection buffer_management Buffer Management
> - *
> - *   This includes APIs for defining and managing buffer pools used
> - *   for packets and other bulk purposes.  Note that the allocation
> - *   and release of buffers from buffer pools is not something done
> - *   explicitly by ODP applications, but rather by APIs that use these
> - *   buffers.  This is because in most SoCs, actual buffer allocation
> - *   and release is accelerated and performed by hardware.  Software's
> - *   role in buffer management is normally reserved to allocating
> - *   large chunks of memory which are then given to hardware for
> - *   automatic management as pools of buffers.  In this way the ODP
> - *   application operates independent of how buffers are managed by
> - *   the underlying ODP implementation.
> - *
> - * @subsubsection packet_management Packet Management
> - *
> - *   This includes APIs and accessor functions for packet descriptors
> - *   as well as packet receipt and transmission.
> - *
> - * @subsubsection syncronisation Synchronization
> - *
> - *   This includes APIs and related functions for synchronization
> - *   involving other ODP APIs, such as barriers and related atomics.
> - *   Again, as ODP does not specify a threading model applications
> - *   make use whatever synchronization primitives are native to the
> - *   model they use.
> - *
> - * @subsubsection core_enumeration Core Enumeration and managment
> - *
> - *   This includes APIs to allow applications to enumerate and
> - *   reference cores and per-core data structures.
> - *
> - * @subsection sub2_5 Miscellaneous Facilities
> - *
> - * ODP includes miscellaneous facilities for compiler hints and
> - * optimizations common in GCC.  [Not sure if we want to consider
> - * these an "API" per se].
> - *
> - * @subsection sub2_6 Application Programming Model
> - *
> - * ODP supports applications that execute using a "run to completion"
> - * programming model.  This means that once dispatched, application
> - * threads are not interrupted by the kernel or other scheduling
> - * entity.
> - *
> - * Application threads receive work requests as \a events that are
> - * delivered on application and/or implementation defined
> - * \a queues.  ODP application code would thus normally be
> - * structured as follows:
> - *
> - * @code
> - * #include <odp.h>
> - * ...other needed #includes
> - *
> - * int main (int argc, char *argv[])
> - * {
> - *         ...application-specific initialization
> - *         odp_init_global();
> - *
> - *         ...launch threads
> - *         ...wait for threads to terminate
> - * }
> - *
> - * void worker_thread (parameters)
> - * {
> - *         odp_init_local();
> - *
> - *         while (1) {
> - *             do_work(get_work());  // Replace with ODP calls when
> defined
> - *         }
> - *
> - * }
> - * @endcode
> - *
> - * Events are receved on input queues and are processed until they are
> - * placed on an output queue of some sort.  The thread then gets the
> - * next event to be processed from an input queue and repeats the
> - * process.
> - *
> - * @subsection sub3_1 Asynchronous Operations
> - *
> - * Note that work to be performed by a thread may require access to an
> - * asynchronous function that takes a significant amount of time to
> - * complete.  In such cases the event is forwarded to another worker
> - * thread or hardware accelerator, depending on the implementation, by
> - * placing it on anothert queue, which is an output queue of the
> - * thread making the request. This event in turn is received and
> - * processed by the thread/accelerator that handles it via its input
> - * queue.  When this aysynchronous event is complete, the event is
> - * placed on the handler's output queue, which feeds back to the
> - * original requestor's input queue.  When the requesting thread next
> - * receives this event it resumes processing of the event following
> - * the asynchronous event and works on it either until it is ready for
> - * final disposition, or until another asynchronous operation is
> - * required to process the event.
> - *
> - * @subsection sub3_2 Queue Linkages
> - *
> - * The mapping of input and output queues that connect worker threads
> - * to accelerators and related offload functions is a cooperation
> - * between the implementation and the ODP application.  The
> - * implementation defines the service funtions that are available to
> - * worker threads (e.g., cypto offload services) and as part of that
> - * definition defines the queue structure that connects requests to
> - * those services as well as the outputs from those services that
> - * connect back to the requesting workers.  The ODP application, in
> - * turn, defines the number of worker threads and how they cooperate
> - * among themselves.  Note that the application may use ODP core
> - * enumeration APIs to decide how many such worker threads should be
> - * deployed.
> - *
> - * @subsection sub3_3 Packet I/O
> - *
> - * In ODP packet I/O is implicit by reading from and writing to queues
> - * associated with interfaces.  An ODP application receives packets by
> - * dequeuing an event from an input queue associated with an I/O
> - * interface.  This either triggers a packet read or (more likely)
> - * simply provides the next (queued) packet from the associated
> - * interface.  The actual mechanism used to effect the receipt of the
> - * packet is left to the ODP implementation and may involve any
> - * combination of sofware and/or hardware operations.
> - *
> - * Similarly, packet transmission is performed by writing a packet to
> - * an output queue associated with an I/O interface.  Again, this
> - * schedules the packet for output using some combination of software
> - * and/or hardware as determined by the implementation.  ODP applications
> - * themselves, therefore, are freed from the details of how packet I/O
> - * is performed or buffered to minimize latencies.  The latter is the
> - * concern of the ODP implementation to achieve optimal results for
> - * the platform supporting the implementation.
> - *
> - * @subsection How to Use this Reference
> - *
> - * This reference provides an overview of each data structure and API
> - * function, along with a graphical representation of the various
> - * structural dependencies among them.  When using the HTML version of
> - * this reference, all links are dynamic and provide access to the
> - * underlying implementation source files as well, thus providing both
> - * a ready reference to API parameters and syntax, as well as
> - * convenient access to the actual implementation behind them to
> - * further programmer understandng.
>   */
> diff --git a/doc/users-guide/guide.dox b/doc/users-guide/guide.dox
> new file mode 100644
> index 0000000..314d295
> --- /dev/null
> +++ b/doc/users-guide/guide.dox
> @@ -0,0 +1,18 @@
> +/* 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
> + * @section sec_dpdk Linux DPDK
> + * @verbinclude linux-dpdk/README
> + * @section sec_keys Linux Keystone2
> + * @verbinclude linux-keystone2/README
> + *
> + */
> --
> 1.9.1
>
>
> _______________________________________________
> lng-odp mailing list
> lng-odp@lists.linaro.org
> http://lists.linaro.org/mailman/listinfo/lng-odp
>

Merged, thanks!
Maxim.

On 07/25/2014 11:46 AM, Anders Roxell wrote:
> 1. To make the structure better
> 2. To have a Users Guide
> 3. Remove out of date content
>
> Signed-off-by: Anders Roxell <anders.roxell@linaro.org>
> ---
>
> Hi,
>
> I didn't want to include this patch into the previeous patchset
> "Restructuring and cleanup README ", this should be added ontop of that.
>
> Cheers,
> Anders
>
>
>   configure.ac                   |   2 +-
>   doc/api/api.dox                |  11 +++
>   doxygen.cfg => doc/doxygen.cfg |   4 +-
>   doc/odp.dox                    | 184 -----------------------------------------
>   doc/users-guide/guide.dox      |  18 ++++
>   5 files changed, 32 insertions(+), 187 deletions(-)
>   create mode 100644 doc/api/api.dox
>   rename doxygen.cfg => doc/doxygen.cfg (83%)
>   create mode 100644 doc/users-guide/guide.dox
>
> diff --git a/configure.ac b/configure.ac
> index 97089e9..f3f8579 100644
> --- a/configure.ac
> +++ b/configure.ac
> @@ -10,7 +10,7 @@ AM_SILENT_RULES([yes])
>   
>   DX_HTML_FEATURE(ON)
>   DX_PDF_FEATURE(ON)
> -DX_INIT_DOXYGEN($PACKAGE_NAME, doxygen.cfg)
> +DX_INIT_DOXYGEN($PACKAGE_NAME, doc/doxygen.cfg)
>   
>   # Checks for programs.
>   AC_PROG_CC
> diff --git a/doc/api/api.dox b/doc/api/api.dox
> new file mode 100644
> index 0000000..7522270
> --- /dev/null
> +++ b/doc/api/api.dox
> @@ -0,0 +1,11 @@
> +/* Copyright (c) 2014, Linaro Limited
> + * All rights reserved
> + *
> + * SPDX-License-Identifier:     BSD-3-Clause
> + */
> +
> +/**
> + *
> + * @page api Application Programming Interface (API) Guide
> + *
> + */
> diff --git a/doxygen.cfg b/doc/doxygen.cfg
> similarity index 83%
> rename from doxygen.cfg
> rename to doc/doxygen.cfg
> index 86fe92a..b3a033d 100644
> --- a/doxygen.cfg
> +++ b/doc/doxygen.cfg
> @@ -9,7 +9,7 @@ TYPEDEF_HIDES_STRUCT = YES
>   EXTRACT_STATIC = YES
>   SORT_MEMBER_DOCS = NO
>   WARN_NO_PARAMDOC = YES
> -INPUT = $(SRCDIR)/doc $(SRCDIR)/include $(SRCDIR)/example
> +INPUT = $(SRCDIR)/doc $(SRCDIR)/doc/users-guide $(SRCDIR)/doc/api $(SRCDIR)/include $(SRCDIR)/example
>   FILE_PATTERNS = odp*.h odp*.c *.dox
>   RECURSIVE = YES
>   SOURCE_BROWSER = YES
> @@ -23,7 +23,7 @@ CLASS_DIAGRAMS = NO
>   HAVE_DOT = YES
>   CALL_GRAPH = YES
>   DOT_MULTI_TARGETS = NO
> -EXAMPLE_PATH = $(SRCDIR)/example
> +EXAMPLE_PATH = $(SRCDIR)/example $(SRCDIR)/platform
>   EXAMPLE_PATTERNS = *.c
>   EXAMPLE_RECURSIVE = YES
>   IMAGE_PATH = $(SRCDIR)/doc/images
> diff --git a/doc/odp.dox b/doc/odp.dox
> index 328c7bb..73d1f37 100644
> --- a/doc/odp.dox
> +++ b/doc/odp.dox
> @@ -68,188 +68,4 @@
>    * - The git repo is https://git.linaro.org/lng/odp.git
>    * - Bug tracking https://launchpad.net/linaro-odp
>    *
> - *
> - * @section sec_2 User guide
> - *
> - * @subsection sub2_1 The ODP API
> - *
> - * This file (odp.h) is the main ODP API file. User should include only this
> - * file to keep portability since structure and naming of sub header files
> - * may be change between implementations.
> - *
> - * @subsection sub2_2 Threading
> - *
> - * ODP does not specify a threading model.  Applications can use
> - * processes or pthreads, or Roll-Your-Own (RYO) threading/fibre
> - * mechanisms for multi-threading as needed. Creation and control of
> - * threads is the responsibility of the ODP application. For optimal
> - * performance on many-core SoCs, it is recommended that threads be
> - * run on dedicated cores. ODP provides high-level APIs for core
> - * enumeration and assignment while the corresponding ODP
> - * implementation layer provides the appropriate mechanisms to realize
> - * these functions.
> - *
> - * Threads used for ODP processing should be pinned into separate cores.
> - * Commonly these threads process packets in a run-to-completion loop.
> - * Application should avoid blocking threads used for ODP processing,
> - * since it may cause blocking on other threads/cores.
> - *
> - * @subsection sub2_3 ODP initialisation
> - *
> - * Before calling any other ODP API functions, ODP library must be
> - * initialised by calling odp_init_global() once and odp_init_local()
> - * on each of the cores sharing the same ODP environment (instance).
> - *
> - * @subsection sub2_4 API Categories
> - *
> - * APIs provided by ODP cover the following areas:
> - *
> - * @subsubsection  memory_management Memory Management
> - *
> - *   This includes macros and other APIs to control memory alignments
> - *   of data structures as well as allocation/deallocation services
> - *   for ODP-managed objects.  Note that ODP does not wrapper malloc()
> - *   or similar platform specific APIs for the sake of wrappering.
> - *
> - * @subsubsection buffer_management Buffer Management
> - *
> - *   This includes APIs for defining and managing buffer pools used
> - *   for packets and other bulk purposes.  Note that the allocation
> - *   and release of buffers from buffer pools is not something done
> - *   explicitly by ODP applications, but rather by APIs that use these
> - *   buffers.  This is because in most SoCs, actual buffer allocation
> - *   and release is accelerated and performed by hardware.  Software's
> - *   role in buffer management is normally reserved to allocating
> - *   large chunks of memory which are then given to hardware for
> - *   automatic management as pools of buffers.  In this way the ODP
> - *   application operates independent of how buffers are managed by
> - *   the underlying ODP implementation.
> - *
> - * @subsubsection packet_management Packet Management
> - *
> - *   This includes APIs and accessor functions for packet descriptors
> - *   as well as packet receipt and transmission.
> - *
> - * @subsubsection syncronisation Synchronization
> - *
> - *   This includes APIs and related functions for synchronization
> - *   involving other ODP APIs, such as barriers and related atomics.
> - *   Again, as ODP does not specify a threading model applications
> - *   make use whatever synchronization primitives are native to the
> - *   model they use.
> - *
> - * @subsubsection core_enumeration Core Enumeration and managment
> - *
> - *   This includes APIs to allow applications to enumerate and
> - *   reference cores and per-core data structures.
> - *
> - * @subsection sub2_5 Miscellaneous Facilities
> - *
> - * ODP includes miscellaneous facilities for compiler hints and
> - * optimizations common in GCC.  [Not sure if we want to consider
> - * these an "API" per se].
> - *
> - * @subsection sub2_6 Application Programming Model
> - *
> - * ODP supports applications that execute using a "run to completion"
> - * programming model.  This means that once dispatched, application
> - * threads are not interrupted by the kernel or other scheduling
> - * entity.
> - *
> - * Application threads receive work requests as \a events that are
> - * delivered on application and/or implementation defined
> - * \a queues.  ODP application code would thus normally be
> - * structured as follows:
> - *
> - * @code
> - * #include <odp.h>
> - * ...other needed #includes
> - *
> - * int main (int argc, char *argv[])
> - * {
> - *         ...application-specific initialization
> - *         odp_init_global();
> - *
> - *         ...launch threads
> - *         ...wait for threads to terminate
> - * }
> - *
> - * void worker_thread (parameters)
> - * {
> - *         odp_init_local();
> - *
> - *         while (1) {
> - *             do_work(get_work());  // Replace with ODP calls when defined
> - *         }
> - *
> - * }
> - * @endcode
> - *
> - * Events are receved on input queues and are processed until they are
> - * placed on an output queue of some sort.  The thread then gets the
> - * next event to be processed from an input queue and repeats the
> - * process.
> - *
> - * @subsection sub3_1 Asynchronous Operations
> - *
> - * Note that work to be performed by a thread may require access to an
> - * asynchronous function that takes a significant amount of time to
> - * complete.  In such cases the event is forwarded to another worker
> - * thread or hardware accelerator, depending on the implementation, by
> - * placing it on anothert queue, which is an output queue of the
> - * thread making the request. This event in turn is received and
> - * processed by the thread/accelerator that handles it via its input
> - * queue.  When this aysynchronous event is complete, the event is
> - * placed on the handler's output queue, which feeds back to the
> - * original requestor's input queue.  When the requesting thread next
> - * receives this event it resumes processing of the event following
> - * the asynchronous event and works on it either until it is ready for
> - * final disposition, or until another asynchronous operation is
> - * required to process the event.
> - *
> - * @subsection sub3_2 Queue Linkages
> - *
> - * The mapping of input and output queues that connect worker threads
> - * to accelerators and related offload functions is a cooperation
> - * between the implementation and the ODP application.  The
> - * implementation defines the service funtions that are available to
> - * worker threads (e.g., cypto offload services) and as part of that
> - * definition defines the queue structure that connects requests to
> - * those services as well as the outputs from those services that
> - * connect back to the requesting workers.  The ODP application, in
> - * turn, defines the number of worker threads and how they cooperate
> - * among themselves.  Note that the application may use ODP core
> - * enumeration APIs to decide how many such worker threads should be
> - * deployed.
> - *
> - * @subsection sub3_3 Packet I/O
> - *
> - * In ODP packet I/O is implicit by reading from and writing to queues
> - * associated with interfaces.  An ODP application receives packets by
> - * dequeuing an event from an input queue associated with an I/O
> - * interface.  This either triggers a packet read or (more likely)
> - * simply provides the next (queued) packet from the associated
> - * interface.  The actual mechanism used to effect the receipt of the
> - * packet is left to the ODP implementation and may involve any
> - * combination of sofware and/or hardware operations.
> - *
> - * Similarly, packet transmission is performed by writing a packet to
> - * an output queue associated with an I/O interface.  Again, this
> - * schedules the packet for output using some combination of software
> - * and/or hardware as determined by the implementation.  ODP applications
> - * themselves, therefore, are freed from the details of how packet I/O
> - * is performed or buffered to minimize latencies.  The latter is the
> - * concern of the ODP implementation to achieve optimal results for
> - * the platform supporting the implementation.
> - *
> - * @subsection How to Use this Reference
> - *
> - * This reference provides an overview of each data structure and API
> - * function, along with a graphical representation of the various
> - * structural dependencies among them.  When using the HTML version of
> - * this reference, all links are dynamic and provide access to the
> - * underlying implementation source files as well, thus providing both
> - * a ready reference to API parameters and syntax, as well as
> - * convenient access to the actual implementation behind them to
> - * further programmer understandng.
>    */
> diff --git a/doc/users-guide/guide.dox b/doc/users-guide/guide.dox
> new file mode 100644
> index 0000000..314d295
> --- /dev/null
> +++ b/doc/users-guide/guide.dox
> @@ -0,0 +1,18 @@
> +/* 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
> + * @section sec_dpdk Linux DPDK
> + * @verbinclude linux-dpdk/README
> + * @section sec_keys Linux Keystone2
> + * @verbinclude linux-keystone2/README
> + *
> + */