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>
Tested-by: Mike Holmes <mike.holmes@linaro.org>

4 files changed, 61 insertions, 184 deletions

diff --git a/doc/api/api.dox b/doc/api/api.dox
new file mode 100644
index 000000000..752227057
--- /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/doc/doxygen.cfg b/doc/doxygen.cfg
new file mode 100644
index 000000000..b3a033d10
--- /dev/null
+++ b/doc/doxygen.cfg
@@ -0,0 +1,32 @@
+PROJECT_NAME = "API Reference Manual"
+PROJECT_LOGO = $(SRCDIR)/doc/images/ODP-Logo-HQ.png
+QUIET = YES
+OUTPUT_DIRECTORY = $(DOCDIR)
+FULL_PATH_NAMES = NO
+JAVADOC_AUTOBRIEF = YES
+OPTIMIZE_OUTPUT_FOR_C = YES
+TYPEDEF_HIDES_STRUCT = YES
+EXTRACT_STATIC = YES
+SORT_MEMBER_DOCS = NO
+WARN_NO_PARAMDOC = YES
+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
+REFERENCED_BY_RELATION = YES
+REFERENCES_RELATION = YES
+ALPHABETICAL_INDEX = NO
+QHP_NAMESPACE =
+GENERATE_TREEVIEW = YES
+PAPER_TYPE = a4wide
+CLASS_DIAGRAMS = NO
+HAVE_DOT = YES
+CALL_GRAPH = YES
+DOT_MULTI_TARGETS = NO
+EXAMPLE_PATH = $(SRCDIR)/example $(SRCDIR)/platform
+EXAMPLE_PATTERNS = *.c
+EXAMPLE_RECURSIVE = YES
+IMAGE_PATH = $(SRCDIR)/doc/images
+HTML_EXTRA_STYLESHEET = $(SRCDIR)/doc/odpdoxygen.css
+PREDEFINED = __GNUC__
+INTERNAL_DOCS = YES
diff --git a/doc/odp.dox b/doc/odp.dox
index 328c7bb71..73d1f371b 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 000000000..314d2952f
--- /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
+ *
+ */