From patchwork Thu May 12 21:23:47 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bill Fischofer X-Patchwork-Id: 67701 Delivered-To: patch@linaro.org Received: by 10.140.92.199 with SMTP id b65csp964455qge; Thu, 12 May 2016 14:24:39 -0700 (PDT) X-Received: by 10.140.100.173 with SMTP id s42mr11629287qge.19.1463088278745; Thu, 12 May 2016 14:24:38 -0700 (PDT) Return-Path: Received: from lists.linaro.org (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTP id c191si9846640qke.4.2016.05.12.14.24.38; Thu, 12 May 2016 14:24:38 -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; Authentication-Results: mx.google.com; spf=pass (google.com: domain of lng-odp-bounces@lists.linaro.org designates 54.225.227.206 as permitted sender) smtp.mailfrom=lng-odp-bounces@lists.linaro.org; dmarc=pass (p=NONE dis=NONE) header.from=linaro.org Received: by lists.linaro.org (Postfix, from userid 109) id 6DF256164A; Thu, 12 May 2016 21:24:38 +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.6 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_LOW, RCVD_IN_MSPIKE_H3, RCVD_IN_MSPIKE_WL, 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 4E2C36164E; Thu, 12 May 2016 21:24:06 +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 1DD256164A; Thu, 12 May 2016 21:23:59 +0000 (UTC) Received: from mail-oi0-f41.google.com (mail-oi0-f41.google.com [209.85.218.41]) by lists.linaro.org (Postfix) with ESMTPS id CF3C261648 for ; Thu, 12 May 2016 21:23:56 +0000 (UTC) Received: by mail-oi0-f41.google.com with SMTP id x19so141019841oix.2 for ; Thu, 12 May 2016 14:23:56 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references; bh=62U/6OTjlKW1EpqceJvm913TPvZv5e1e7qZxyvkNips=; b=eE70WCs6I50i7MtIUDlvD9VeiU4g8ROfB7fUP1wlRUEaLfus56UMrCvIeerD5w0x02 2368XJy/kJlOt0Lgn6hGp2gsMsfMNtPy/KtblE/o7FZKdj8TUs9np3pAHcH3OJ94gjNh 4iCN7F9ba9I7uUSTiNIfxejKaRjSIKBVxQMy5Fiu+Tq7ic/GQXhWmkjQAvN85zSA1fR7 Z276wrIlb92GM+9eurJgqED+yiO1St/ZsBXY6OsPLyR+Evj7GLGwe0qQOwoR+LfIombj uh2MQ96o0QJZ6SWnwie+iyvlA8mS8ZQQDpwkPLZ91uWvwhHWPn5zmjoOLekaiPAQTWfR v1Gg== X-Gm-Message-State: AOPr4FX61G8TQgVVNB7NaXgkqJ6OPqO4Ln7b6xkNKl5+ndMIJSOA8x0OPNWpljn2YNvKpeeQZIg= X-Received: by 10.202.51.133 with SMTP id z127mr6786374oiz.194.1463088236276; Thu, 12 May 2016 14:23:56 -0700 (PDT) Received: from localhost.localdomain (cpe-66-68-129-43.austin.res.rr.com. [66.68.129.43]) by smtp.gmail.com with ESMTPSA id 78sm4372245otd.12.2016.05.12.14.23.55 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Thu, 12 May 2016 14:23:55 -0700 (PDT) From: Bill Fischofer To: lng-odp@lists.linaro.org Date: Thu, 12 May 2016 16:23:47 -0500 Message-Id: <1463088227-2677-3-git-send-email-bill.fischofer@linaro.org> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1463088227-2677-1-git-send-email-bill.fischofer@linaro.org> References: <1463088227-2677-1-git-send-email-bill.fischofer@linaro.org> X-Topics: patch Subject: [lng-odp] [PATCHv4 3/3] doc: users-guide: add packet flow overview X-BeenThere: lng-odp@lists.linaro.org X-Mailman-Version: 2.1.16 Precedence: list List-Id: "The OpenDataPlane \(ODP\) List" 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" From: Mike Holmes Signed-off-by: Mike Holmes Signed-off-by: Bill Fischofer --- doc/users-guide/Makefile.am | 1 + doc/users-guide/users-guide.adoc | 89 +++++++++++++++++++++++++++++----------- 2 files changed, 66 insertions(+), 24 deletions(-) mode change 100644 => 100755 doc/users-guide/users-guide.adoc diff --git a/doc/users-guide/Makefile.am b/doc/users-guide/Makefile.am index 439ce69..77594fc 100644 --- a/doc/users-guide/Makefile.am +++ b/doc/users-guide/Makefile.am @@ -14,6 +14,7 @@ IMAGES = $(top_srcdir)/doc/images/overview.svg \ $(top_srcdir)/doc/images/odp_scheduling.svg \ $(top_srcdir)/doc/images/odp_traffic_manager.svg \ $(top_srcdir)/doc/images/ordered_queue.svg \ + $(top_srcdir)/doc/images/packet_flow.svg \ $(top_srcdir)/doc/images/packet-adddata.svg \ $(top_srcdir)/doc/images/packet-align.svg \ $(top_srcdir)/doc/images/packet-copyops.svg \ diff --git a/doc/users-guide/users-guide.adoc b/doc/users-guide/users-guide.adoc old mode 100644 new mode 100755 index 0221634..3b8c442 --- a/doc/users-guide/users-guide.adoc +++ b/doc/users-guide/users-guide.adoc @@ -181,7 +181,8 @@ as it scales from 4, to 40, to 400 cores. == Organization of this Document This document is organized into several sections. The first presents a high -level overview of the ODP API component areas and their associated abstract +level overview of ODP applications, the ODP API component areas, +and their associated abstract data types. This section introduces ODP APIs at a conceptual level. The second provides a tutorial on the programming model(s) supported by ODP, paying particular attention to the event model as this @@ -194,6 +195,59 @@ full reference specification for each API. The latter is intended to be used by ODP application programmers, as well as implementers, to understand the precise syntax and semantics of each API. +== ODP Applications and Packet Flow +Data plane applications are fundamentally concerned with receiving, examining, +manipulating, and transmitting packets. The distinguishing feature of the +data plane is that these applications are mostly concerned with the lowest +layers of the ISO stack (Layers 2 and 3) and they have very high to extreme +performance requirements. ODP is designed to provide a portable framework for +such applications. + +At the highest level, an *ODP Application* is a program that uses one or more +ODP APIs. Because ODP is a framework rather than a programming environment, +applications are free to also use other APIs that may or may not provide the +same portability characteristics as ODP APIs. + +ODP applications vary in terms of what they do and how they operate, but in +general all share the following characteristics: + +. They are organized into one or more _threads_ that execute in parallel. +. These threads communicate and coordinate their activities using various +_synchronization_ mechanisms. +. They receive packets from one or more _packet I/O interfaces_. +. They examine, transform, or otherwise process packets. +. They transmit packets to one or more _packet I/O interfaces_. + +At the highest level, an ODP application looks as follows: + +.ODP Application Packet Flow Overview +image::packet_flow.svg[align="center"] + +Packets arrive and are received (RX) from a network interface represented by +a _PktIO_ abstraction. From here they go either directly to _Queues_ that are +polled by ODP _Threads_, or can pass through the _Classifier_ and sorted into +Queues that represent individual flows. These queues can then be dispatched +to application threads via the _Scheduler_. + +Threads, in term can invoke various ODP APIs to manipulate packet contents +prior to disposing of them. For output processing, packets make by directly +queued to a PktIO output queue or else they may be handed to the _Traffic +Manager_ for programmatic _Quality of Service (QoS)_ processing before winding +up being transmitted (TX). Note that output interfaces may operate in +_loopback_ mode, in which case packets sent to them are re-routed back to the +input lines for "second pass" processing. For example, an incoming IPSec packet +cannot be properly classified (beyond being IPSec traffic) until it is +decrypted. Once decrypted and its actual contents made visible, it can then +be classified into its real flow. + +What is important to note is that the only part of the above diagram that need +be written are the boxes in yellow that contain the application +logic. Everything else shown here is provided by the ODP framework and +available for use by any ODP application. This represents the "machinery" of a +data plane application and is structured to allow applications written to the +ODP APIs to be both portable and optimized for each platform that offers an +ODP implementation without additional programming effort. + == ODP API Concepts ODP programs are built around several conceptual structures that every application programmer needs to be familiar with to use ODP effectively. The @@ -298,11 +352,11 @@ with each packet for its own use. Packets are represented by handles of abstract type `odp_packet_t`. -=== PktIO -PktIO is how ODP represents I/O interfaces. A pktio object is a logical -port capable of receiving and/or transmitting packets. This may be directly -supported by the underlying platform as an integrated feature, -or may represent a device attached via a PCIE or other bus. +=== Packet I/O (PktIO) +PktIO is how ODP represents I/O interfaces. A pktio object is a logical port +capable of receiving (RX) and/or transmitting (TX) packets. This may be +directly supported by the underlying platform as an integrated feature, or may +represent a device attached via a PCIE or other bus. PktIOs are represented by handles of abstract type `odp_pktio_t`. @@ -444,23 +498,7 @@ goals. Again, the advantage here is that on many platforms traffic management functions are implemented in hardware, permitting transparent offload of this work. -== ODP Application Programming -At the highest level, an *ODP Application* is a program that uses one or more -ODP APIs. Because ODP is a framework rather than a programming environment, -applications are free to also use other APIs that may or may not provide the -same portability characteristics as ODP APIs. - -ODP applications vary in terms of what they do and how they operate, but in -general all share the following characteristics: - -. They are organized into one or more _threads_ that execute in parallel. -. These threads communicate and coordinate their activities using various -_synchronization_ mechanisms. -. They receive packets from one or more _packet I/O interfaces_. -. They examine, transform, or otherwise process packets. -. They transmit packets to one or more _packet I/O interfaces_. - -ODP provides APIs to assist in each of these areas. +== ODP Application Programming Structure === The include structure Applications only include the 'include/odp_api.h' file, which includes the @@ -509,9 +547,12 @@ which is either `ODP_THREAD_WORKER` or `ODP_THREAD_CONTROL`. === Shutdown Shutdown is the logical reverse of the initialization procedure, with -'odp_term_local()' called for each thread before 'odp_term_global()' is +`odp_term_local()` called for each thread before `odp_term_global()` is called to terminate ODP. +=== Application Initialization/Termination Structure +ODP Applications follow the general structure flow shown below: + .ODP Application Structure Flow Diagram image::resource_management.svg[align="center"]