From patchwork Fri Jul 25 07:46:56 2014 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Anders Roxell X-Patchwork-Id: 34265 Return-Path: X-Original-To: linaro@patches.linaro.org Delivered-To: linaro@patches.linaro.org Received: from mail-oi0-f69.google.com (mail-oi0-f69.google.com [209.85.218.69]) by ip-10-151-82-157.ec2.internal (Postfix) with ESMTPS id A5E14235AB for ; Fri, 25 Jul 2014 07:47:22 +0000 (UTC) Received: by mail-oi0-f69.google.com with SMTP id h136sf15472159oig.0 for ; Fri, 25 Jul 2014 00:47:22 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:delivered-to:from:to:date:message-id:subject :precedence:list-id:list-unsubscribe:list-archive:list-post :list-help:list-subscribe:mime-version:errors-to:sender :x-original-sender:x-original-authentication-results:mailing-list :content-type:content-transfer-encoding; bh=wLVDI/gHp62iZKxd7bW2Ct1EKzyRKZZxx9RJ1eeRXzk=; b=IzrOyOwJ566g0K8KnvCmgb4s23XfEjWWKomt/tL9kmoHElNLw68EpBzi8fYQCm+ZUl EMQVvQTXZ0+pqfcfg+Cp/qGoMa1mpQDWWWg/umvA7zhX+PVOyg+oL4sCs/VNpjw8gJot V6MiXW9JjSa3+nzuQiOBJoDkXBgJgIL/KMgCgfq3AmywMtvtmg9mWEn+YQisug0DD5f1 Pz8elKWHMzS1Zoo2EtlB0iO3RpYTj49xEaB33+X4kciwh4+P+OMY8cU0kWC1B61d11mP bJuZga4MkIT+7lbvfY37CK7xYG+tMFwtIZdx13LpB6zDHQtec5Sk6RqxA2KBsqGZbNpT FgzQ== X-Gm-Message-State: ALoCoQnqI3QJBaDicKiFfYuAfksoP7T3d4NFV0vOqnsFrvVxrtTzNnO9g+hGXtntfBbHn/11BDrA X-Received: by 10.182.51.228 with SMTP id n4mr7347769obo.28.1406274442152; Fri, 25 Jul 2014 00:47:22 -0700 (PDT) X-BeenThere: patchwork-forward@linaro.org Received: by 10.140.100.214 with SMTP id s80ls1070213qge.99.gmail; Fri, 25 Jul 2014 00:47:22 -0700 (PDT) X-Received: by 10.52.129.200 with SMTP id ny8mr15653588vdb.27.1406274441994; Fri, 25 Jul 2014 00:47:21 -0700 (PDT) Received: from mail-vc0-f170.google.com (mail-vc0-f170.google.com [209.85.220.170]) by mx.google.com with ESMTPS id lh5si6957707vdb.33.2014.07.25.00.47.21 for (version=TLSv1 cipher=ECDHE-RSA-RC4-SHA bits=128/128); Fri, 25 Jul 2014 00:47:21 -0700 (PDT) Received-SPF: pass (google.com: domain of patch+caf_=patchwork-forward=linaro.org@linaro.org designates 209.85.220.170 as permitted sender) client-ip=209.85.220.170; Received: by mail-vc0-f170.google.com with SMTP id lf12so6696972vcb.29 for ; Fri, 25 Jul 2014 00:47:21 -0700 (PDT) X-Received: by 10.220.95.132 with SMTP id d4mr18706435vcn.33.1406274441897; Fri, 25 Jul 2014 00:47:21 -0700 (PDT) X-Forwarded-To: patchwork-forward@linaro.org X-Forwarded-For: patch@linaro.org patchwork-forward@linaro.org Delivered-To: patch@linaro.org Received: by 10.221.37.5 with SMTP id tc5csp18060vcb; Fri, 25 Jul 2014 00:47:21 -0700 (PDT) X-Received: by 10.224.16.212 with SMTP id p20mr6494318qaa.1.1406274441477; Fri, 25 Jul 2014 00:47:21 -0700 (PDT) Received: from ip-10-141-164-156.ec2.internal (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTPS id 66si14921927qgg.117.2014.07.25.00.47.20 for (version=TLSv1 cipher=RC4-SHA bits=128/128); Fri, 25 Jul 2014 00:47:21 -0700 (PDT) Received-SPF: none (google.com: lng-odp-bounces@lists.linaro.org does not designate permitted sender hosts) client-ip=54.225.227.206; Received: from localhost ([127.0.0.1] helo=ip-10-141-164-156.ec2.internal) by ip-10-141-164-156.ec2.internal with esmtp (Exim 4.76) (envelope-from ) id 1XAaDo-00040K-Hi; Fri, 25 Jul 2014 07:47:20 +0000 Received: from mail-la0-f50.google.com ([209.85.215.50]) by ip-10-141-164-156.ec2.internal with esmtp (Exim 4.76) (envelope-from ) id 1XAaDi-00040C-EN for lng-odp@lists.linaro.org; Fri, 25 Jul 2014 07:47:14 +0000 Received: by mail-la0-f50.google.com with SMTP id gf5so2808560lab.9 for ; Fri, 25 Jul 2014 00:47:08 -0700 (PDT) X-Received: by 10.152.36.225 with SMTP id t1mr1290450laj.65.1406274428415; Fri, 25 Jul 2014 00:47:08 -0700 (PDT) Received: from localhost (c-4f66bc92-74736162.cust.telenor.se. [79.102.188.146]) by mx.google.com with ESMTPSA id o1sm6068147lag.36.2014.07.25.00.47.06 for (version=TLSv1.2 cipher=RC4-SHA bits=128/128); Fri, 25 Jul 2014 00:47:07 -0700 (PDT) From: Anders Roxell To: lng-odp@lists.linaro.org Date: Fri, 25 Jul 2014 09:46:56 +0200 Message-Id: <1406274416-8087-1-git-send-email-anders.roxell@linaro.org> X-Mailer: git-send-email 1.9.1 X-Topics: patch Subject: [lng-odp] [PATCH] doxygen reorganisation X-BeenThere: lng-odp@lists.linaro.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: , List-Help: , List-Subscribe: , MIME-Version: 1.0 Errors-To: lng-odp-bounces@lists.linaro.org Sender: lng-odp-bounces@lists.linaro.org X-Removed-Original-Auth: Dkim didn't pass. X-Original-Sender: anders.roxell@linaro.org X-Original-Authentication-Results: mx.google.com; spf=pass (google.com: domain of patch+caf_=patchwork-forward=linaro.org@linaro.org designates 209.85.220.170 as permitted sender) smtp.mail=patch+caf_=patchwork-forward=linaro.org@linaro.org Mailing-list: list patchwork-forward@linaro.org; contact patchwork-forward+owners@linaro.org X-Google-Group-Id: 836684582541 1. To make the structure better 2. To have a Users Guide 3. Remove out of date content Signed-off-by: Anders Roxell Tested-by: Mike Holmes --- 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 - * ...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 + * + */