From patchwork Thu Oct 22 19:56:15 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Mike Holmes X-Patchwork-Id: 55451 Return-Path: X-Original-To: linaro@patches.linaro.org Delivered-To: linaro@patches.linaro.org Received: from mail-lf0-f72.google.com (mail-lf0-f72.google.com [209.85.215.72]) by patches.linaro.org (Postfix) with ESMTPS id 512B222AA5 for ; Thu, 22 Oct 2015 19:57:33 +0000 (UTC) Received: by lfu67 with SMTP id 67sf12393946lfu.2 for ; Thu, 22 Oct 2015 12:57:32 -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:delivered-to:from:to:date :message-id:in-reply-to:references:mime-version:subject:precedence :list-id:list-unsubscribe:list-archive:list-post:list-help :list-subscribe:content-type:content-transfer-encoding:errors-to :sender:x-original-sender:x-original-authentication-results :mailing-list; bh=OOd+P7F0ck51tBlpXRiT9Dn4lgb2H2AHu5PvSJcsRzw=; b=eYIoUa5UFO23aqzmXM6j7iwfVjA4PBVnvjRIbLQdDYsdCH/zVmQrxzJ3wt50lGr9Sx kKPjEB3/sqRP0z19boNo8p3Gx9uibMfeWVbu7ntJr9+LTeMTQBexOPLn0NgUEMmeIZwm 0Nf+w+pU9cJ3mEFILx6Iyc3NZ6Yiv15JHZKUNEknV01OHTrLhArt4HW51FcIaGvifOFw AJHiXTiyvhmrvVlZejWiZ3WPgW+LGY6mZk2BLqu8vflAEl6iksYfE9YxMHL1fMyyOcsh MQb87QpOKW8xDaTcIjvMFGrs5utX3fiueMIvYaIqrBh8KN4DCYBQ7n4xEpyscoNmkkpU wesA== X-Gm-Message-State: ALoCoQlKFeuwL0TR1/4aBEhcNIV8hl/pWGRnD8YObMbUwXPdbztz2KARsMwVrpUVLqpdu9G1GJWO X-Received: by 10.112.209.73 with SMTP id mk9mr4096815lbc.14.1445543852243; Thu, 22 Oct 2015 12:57:32 -0700 (PDT) X-BeenThere: patchwork-forward@linaro.org Received: by 10.25.24.84 with SMTP id o81ls340988lfi.48.gmail; Thu, 22 Oct 2015 12:57:32 -0700 (PDT) X-Received: by 10.112.131.70 with SMTP id ok6mr9534268lbb.71.1445543852100; Thu, 22 Oct 2015 12:57:32 -0700 (PDT) Received: from mail-lf0-x22c.google.com (mail-lf0-x22c.google.com. [2a00:1450:4010:c07::22c]) by mx.google.com with ESMTPS id c5si10609185lbp.10.2015.10.22.12.57.32 for (version=TLSv1.2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 22 Oct 2015 12:57:32 -0700 (PDT) Received-SPF: pass (google.com: domain of patch+caf_=patchwork-forward=linaro.org@linaro.org designates 2a00:1450:4010:c07::22c as permitted sender) client-ip=2a00:1450:4010:c07::22c; Received: by lffz202 with SMTP id z202so60956677lff.3 for ; Thu, 22 Oct 2015 12:57:32 -0700 (PDT) X-Received: by 10.25.205.193 with SMTP id d184mr3887108lfg.72.1445543851959; Thu, 22 Oct 2015 12:57:31 -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.112.59.35 with SMTP id w3csp799746lbq; Thu, 22 Oct 2015 12:57:31 -0700 (PDT) X-Received: by 10.55.41.93 with SMTP id p90mr20440606qkh.14.1445543850993; Thu, 22 Oct 2015 12:57:30 -0700 (PDT) Received: from lists.linaro.org (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTP id j74si14305342qge.93.2015.10.22.12.57.30; Thu, 22 Oct 2015 12:57:30 -0700 (PDT) Received-SPF: pass (google.com: domain of lng-odp-bounces@lists.linaro.org designates 54.225.227.206 as permitted sender) client-ip=54.225.227.206; Received: by lists.linaro.org (Postfix, from userid 109) id 5B2B562C15; Thu, 22 Oct 2015 19:57:30 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on ip-10-142-244-252 X-Spam-Level: X-Spam-Status: No, score=-2.5 required=5.0 tests=BAYES_00,DKIM_SIGNED, RCVD_IN_DNSWL_LOW,RCVD_IN_MSPIKE_H2,T_DKIM_INVALID,URIBL_BLOCKED autolearn=disabled version=3.4.0 Received: from [127.0.0.1] (localhost [127.0.0.1]) by lists.linaro.org (Postfix) with ESMTP id 2DA6A62C16; Thu, 22 Oct 2015 19:56:37 +0000 (UTC) X-Original-To: lng-odp@lists.linaro.org Delivered-To: lng-odp@lists.linaro.org Received: by lists.linaro.org (Postfix, from userid 109) id E5DCE62C10; Thu, 22 Oct 2015 19:56:33 +0000 (UTC) Received: from mail-qg0-f48.google.com (mail-qg0-f48.google.com [209.85.192.48]) by lists.linaro.org (Postfix) with ESMTPS id BDD7B62C0E for ; Thu, 22 Oct 2015 19:56:30 +0000 (UTC) Received: by qgem9 with SMTP id m9so66735537qge.1 for ; Thu, 22 Oct 2015 12:56:30 -0700 (PDT) X-Received: by 10.140.237.208 with SMTP id i199mr6065282qhc.73.1445543790494; Thu, 22 Oct 2015 12:56:30 -0700 (PDT) Received: from localhost.localdomain (c-98-221-136-245.hsd1.nj.comcast.net. [98.221.136.245]) by smtp.gmail.com with ESMTPSA id s84sm6014716qki.14.2015.10.22.12.56.29 (version=TLSv1.2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Thu, 22 Oct 2015 12:56:30 -0700 (PDT) From: Mike Holmes To: lng-odp@lists.linaro.org Date: Thu, 22 Oct 2015 15:56:15 -0400 Message-Id: <1445543775-11220-3-git-send-email-mike.holmes@linaro.org> X-Mailer: git-send-email 2.5.0 In-Reply-To: <1445543775-11220-1-git-send-email-mike.holmes@linaro.org> References: <1445543775-11220-1-git-send-email-mike.holmes@linaro.org> MIME-Version: 1.0 X-Topics: patch Subject: [lng-odp] [PATCH 3/3] doc: users-guide convert to asciidoc X-BeenThere: lng-odp@lists.linaro.org X-Mailman-Version: 2.1.16 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: , List-Help: , List-Subscribe: , Errors-To: lng-odp-bounces@lists.linaro.org Sender: "lng-odp" X-Original-Sender: mike.holmes@linaro.org X-Original-Authentication-Results: mx.google.com; spf=pass (google.com: domain of patch+caf_=patchwork-forward=linaro.org@linaro.org designates 2a00:1450:4010:c07::22c as permitted sender) smtp.mailfrom=patch+caf_=patchwork-forward=linaro.org@linaro.org; dkim=neutral (body hash did not verify) header.i=@linaro_org.20150623.gappssmtp.com Mailing-list: list patchwork-forward@linaro.org; contact patchwork-forward+owners@linaro.org X-Google-Group-Id: 836684582541 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 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. +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 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"]