From patchwork Tue May 17 14:40:31 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Mike Holmes X-Patchwork-Id: 67989 Delivered-To: patch@linaro.org Received: by 10.140.92.199 with SMTP id b65csp2116275qge; Tue, 17 May 2016 07:43:05 -0700 (PDT) X-Received: by 10.55.200.69 with SMTP id c66mr1999546qkj.14.1463496185677; Tue, 17 May 2016 07:43:05 -0700 (PDT) Return-Path: Received: from lists.linaro.org (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTP id n126si2425470qkf.201.2016.05.17.07.43.05; Tue, 17 May 2016 07:43:05 -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 D979C61784; Tue, 17 May 2016 14:43:04 +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, 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 23DC4616E4; Tue, 17 May 2016 14:41:30 +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 3DECC6172B; Tue, 17 May 2016 14:41:15 +0000 (UTC) Received: from mail-qk0-f180.google.com (mail-qk0-f180.google.com [209.85.220.180]) by lists.linaro.org (Postfix) with ESMTPS id D8C30616AF for ; Tue, 17 May 2016 14:41:01 +0000 (UTC) Received: by mail-qk0-f180.google.com with SMTP id n62so8508889qkc.2 for ; Tue, 17 May 2016 07:41:01 -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:mime-version :content-transfer-encoding; bh=t2cBK0YNPwZZvzuNymWpGwWOdx+BEqE8bF1O3OVtih4=; b=VFoCoTofeZtBrjnC022L8Gj2+8KyRqoaOf75PE0vrkp32/WuZpumJM+0de47NYTC+7 x8BZsvngPhoZhntFbkGG+BwObVNYzYBQoect1GNge2B+exwH754VifU7MgmqEQNGvP4+ CeFLunpVU1DFlfkJUBXv0GHm4RdiidLNkoX6MhiEUhkShSGc9gAFvE8U0mezbKCJOALZ R/uHgOqV6Dgy6mdlmWeh6X3PJZy9XoyDCLUlxodQMGBFcYmh4JwFSgr+yXlyf0gXy9Gr RztHPgVR35QarVdGnnISUqAqD9rDiX+yE5tA83xKGPZE/zteavvghX9QpR/bYVOEz1WO dr3w== X-Gm-Message-State: AOPr4FUwkp+k1NHRUxf8cbBif2DJvEX6gx00weUi2TItj52L259EKI3xaGnKGrgkpVrUACgFIYA= X-Received: by 10.55.140.69 with SMTP id o66mr2018821qkd.188.1463496060112; Tue, 17 May 2016 07:41:00 -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 w6sm1430131qhb.2.2016.05.17.07.40.59 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Tue, 17 May 2016 07:40:59 -0700 (PDT) From: Mike Holmes To: lng-odp@lists.linaro.org Date: Tue, 17 May 2016 10:40:31 -0400 Message-Id: <1463496031-30550-1-git-send-email-mike.holmes@linaro.org> X-Mailer: git-send-email 2.7.4 MIME-Version: 1.0 X-Topics: patch Subject: [lng-odp] [PATCH] doc: process: add FAQ document 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: , Errors-To: lng-odp-bounces@lists.linaro.org Sender: "lng-odp" Signed-off-by: Mike Holmes Please check this, I did make some updates as I went but I suspect we want to update this before pushign to the list. This will replace the burried hardcoded wordpress document and as such will be easier to maintain. --- doc/images/aboutODP1.svg | 110 ++++++++ doc/images/aboutODP2.svg | 117 ++++++++ doc/images/aboutODP3.svg | 641 ++++++++++++++++++++++++++++++++++++++++++ doc/images/aboutODP5.svg | 151 ++++++++++ doc/process-guide/.gitignore | 1 + doc/process-guide/Makefile.am | 20 +- doc/process-guide/faq.adoc | 273 ++++++++++++++++++ 7 files changed, 1310 insertions(+), 3 deletions(-) create mode 100644 doc/images/aboutODP1.svg create mode 100644 doc/images/aboutODP2.svg create mode 100644 doc/images/aboutODP3.svg create mode 100644 doc/images/aboutODP5.svg create mode 100644 doc/process-guide/faq.adoc diff --git a/doc/images/aboutODP1.svg b/doc/images/aboutODP1.svg new file mode 100644 index 0000000..7ad03bd --- /dev/null +++ b/doc/images/aboutODP1.svg @@ -0,0 +1,110 @@ + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Platform A + + + + Application + + + + Platform B + + + + Platform C + + + + ODP API + + + + + + + diff --git a/doc/images/aboutODP2.svg b/doc/images/aboutODP2.svg new file mode 100644 index 0000000..e66c6d2 --- /dev/null +++ b/doc/images/aboutODP2.svg @@ -0,0 +1,117 @@ + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Application A + + + + HW Platform(Soc or Server) + + + + Application B + + + + Application C + + + + ODP API + + + + + + + diff --git a/doc/images/aboutODP3.svg b/doc/images/aboutODP3.svg new file mode 100644 index 0000000..5bc91a2 --- /dev/null +++ b/doc/images/aboutODP3.svg @@ -0,0 +1,641 @@ + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ODP + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + GB/s + + + + 400+ + + + + 100 + + + + 10 + + + + SW+NIC + + + + SW+HWoffload + + + + HW + + + + Technology + + + + + + + diff --git a/doc/images/aboutODP5.svg b/doc/images/aboutODP5.svg new file mode 100644 index 0000000..86564c9 --- /dev/null +++ b/doc/images/aboutODP5.svg @@ -0,0 +1,151 @@ + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ODP API + + + + Simple Executive + + + + Community of ODP Applications + + + + ODP Applications + + + + OCTEON + + + + LWEUSDPAA + + + + QorIQ DPAA + + + + DPDK + + + + X86 + + + + SDK A + + + + Platform A + + + + + + + diff --git a/doc/process-guide/.gitignore b/doc/process-guide/.gitignore index 7632500..78bd409 100644 --- a/doc/process-guide/.gitignore +++ b/doc/process-guide/.gitignore @@ -1,2 +1,3 @@ bylaws-guide.html release-guide.html +faq.html diff --git a/doc/process-guide/Makefile.am b/doc/process-guide/Makefile.am index 196ed7f..7d5cd6a 100644 --- a/doc/process-guide/Makefile.am +++ b/doc/process-guide/Makefile.am @@ -1,14 +1,17 @@ include ../Makefile.inc EXTRA_DIST = $(top_srcdir)/doc/process-guide/bylaws-guide.adoc \ - $(top_srcdir)/doc/process-guide/release-guide.adoc + $(top_srcdir)/doc/process-guide/release-guide.adoc \ + $(top_srcdir)/doc/process-guide/faq.adoc all-local: bylaws-guide.html \ - release-guide.html + release-guide.html \ + faq.html clean-local: rm -f $(builddir)/bylaws-guide.html rm -f $(builddir)/release-guide.html + rm -f $(builddir)/faq.html release-guide.html: $(top_srcdir)/doc/process-guide/release-guide.adoc \ $(top_srcdir)/doc/images/simple_release_git.svg \ @@ -16,4 +19,15 @@ release-guide.html: $(top_srcdir)/doc/process-guide/release-guide.adoc \ bylaws-guide.html: $(top_srcdir)/doc/process-guide/bylaws-guide.adoc -doc_DATA = bylaws-guide.html release-guide.html +faq.html: $(top_srcdir)/doc/process-guide/faq.adoc \ + $(top_srcdir)/doc/images/aboutODP1.svg \ + $(top_srcdir)/doc/images/aboutODP2.svg \ + $(top_srcdir)/doc/images/aboutODP3.svg \ + $(top_srcdir)/doc/images/packet_flow.svg \ + $(top_srcdir)/doc/images/aboutODP5.svg \ + $(top_srcdir)/doc/images/overview.svg + + +#add deps on images + +doc_DATA = bylaws-guide.html release-guide.html faq.html diff --git a/doc/process-guide/faq.adoc b/doc/process-guide/faq.adoc new file mode 100644 index 0000000..8f0c263 --- /dev/null +++ b/doc/process-guide/faq.adoc @@ -0,0 +1,273 @@ +:doctitle: OpenDataPlane (ODP) Frequently Asked Questions (FAQ) +:description: This document is intended to guide a new ODP user in answering + +common questions +:imagesdir: ../images +:toc: +:numbered!: +[abstract] +Abstract +-------- +This document is intended to guide a new ODP user in answering +common questions. + +Further details about ODP may be found at the http://opendataplane.org[ODP] +home page. + +:numbered: + +== What is ODP? +OpenDataPlane (ODP) is an open source API defined for networking data plane +applications programming. The primary goal of ODP is to provide a common set of +APIs for application portability across a diverse range of networking platforms +(SoCs and servers) that offer various types of hardware acceleration. As an +abstract API specification, ODP permits applications to run on and exploit the +hardware offload capabilities of various platforms without requiring expertise +in the nuances of any target platform. + +At the same time, ODP is also a set of implementations of these APIs that are +optimized for each platform that supports ODP. Implementations of ODP currently +exist for a wide range of platforms spanning diverse instruction set +architectures including ARM, MIPS, Power, x86, as well as proprietary SoC +architectures, and include both general-purpose servers as well as specialized +networking SoCs. + +By decoupling the API definition from its implementation, ODP achieves two goals: + +* APIs can be defined to address data plane application needs rather than to +expose specific platform capabilities. This leads to easy application +portability across any platform that supports a conforming ODP implementation. +The result is that applications written to the ODP APIs can run on any platform +without developers needing expertise in the nuances of that platform + +.ODP Application view +image::aboutODP1.svg[align="center"] + +* At the same time, by keeping APIs abstract, ODP allows vendors full freedom to +implement these APIs in a manner optimized to the capabilities of each +platform. This means that platforms can compete for any socket: + +.ODP Implementation view +image::aboutODP2.svg[align="center"] + +This freedom is further enhanced by ODP’s use of 3-clause BSD licensing. ODP +APIs are fully open source and open contribution, however individual +implementors of these APIs may choose to make their code open or closed source +as business needs determine. As part of the main ODP distribution, several +reference implementations of the ODP APIs are made available and these +implementations are themselves open source and open contribution. These +reference implementations are designed to offer a good starting point for those +wishing to develop their own implementations of ODP tailored to their platform, +or to gain experiencing developing ODP applications without needing anything +other than a standard Linux platform. Also included as part of ODP is a +validation test suite that permits applications and vendors to confirm that a +given ODP implementation conforms to the ODP API specification, thus ensuring +consistency and portability across various implementations of ODP. + +== What is not ODP? +The data plane is the part of a network that carries user traffic. The data +plane, the control plane and the management plane are the three basic +components of a telecommunications architecture. The control plane and +management plane serve the data plane, which bears the traffic that the network +exists to carry. ODP is only concerned with the data plane. + +== Who is behind ODP? + +ODP is sponsored by the Linaro Networking Group (LNG) and its 13 member +companies. These companies include network system vendors, silicon vendors, +and software solution providers who are working to promote a truly cross +platform solution for data plane applications that is portable across a wide +range of network silicon yet can take full advantage of hardware acceleration +and offload capabilities offered by these platforms. + +== What are the goals of ODP? +* To support Software-defined networking (SDN) in which control is decoupled +from the physical infrastructure, allowing network administrators to support a +network fabric across multi-vendor equipment. +* To support Network function virtualization (NFV) which is an initiative to +visualize the network services that are now being carried out by proprietary +hardware. +* To enable a platform agnostic open source community to develop hardware +accelerated software that is very portable. + +== What is the ODP project history and status? + +The ODP project was launched in 2013. The first full-feature release of ODP +occurred in March of 2015 and a production-ready release called Monarch will be +finalizes in 2016 + +The history can be seen in the git stats for the the first implementation, the +linux-generic reference [2]. + +== Where does ODP fit in the solution space? + +.ODP in the solution space +image::aboutODP3.svg[align="center"] + +Although ODP applications are independent of available network speeds, at +present the benefits of ODP are best seen on networks operating at 10Gb/s and +above. This allows ODP applications to transition seamlessly from +software-based acceleration found on general purpose servers to hardware +acceleration found on specialized networking SoCs. At present this spans the +“sweet spot” of speeds from 10Gb/s to 100Gb/s. Beyond 100Gb/s ODP abstractions +have not matured enough to completely describe full offload processing, +although this is a long term goal. + +== What does a typical application packet flow look like? + +An application written as a clean room implementation will differ in structure +from one ported from a legacy application allowing it to benefit from more of +the ODP capabilities, a typical structure for a new application is shown below: + +.ODP packetflow +image::packet_flow.svg[align="center"] + +Using the scheduler and an event driven model, packets are distributed to +available workers maximizing the capacity of the cores. Where possible, the +function will be performed in hardware (red). Migrating to a device where more +of the functionality is in hardware will result in greater throughput without +rewriting the application. In addition, migration to a device with more cores +will automatically spread the load achieving greater throughput. + +In summary: + +* The classifier might be fixed-function or programmable (for flexibility as network protocols evolve) +* The scheduler is similar to a traffic manager +* Processing cores can be added and removed dynamically (elasticity) +* The scheduler knows which core is associated with which queue at every +moment, which enables hardware synchronization +* Packets and other types of work (e.g. timers) are scheduled together + +== What does the ODP software stack look like? + +.ODP in the solution space +image::overview.svg[align="center"] + +An application written to the ODP API will be linked to the ODP implementation +for the platform on which it is executing. This implementation will have been +optimized for that specific hardware; it will often call the native SDK via an +inline call, which also allows the application to simultaneously take +advantage of vendor extensions that have not yet been standardized. + +== What platforms does ODP support? + +To date, ODP is running on seven different network platforms that span five +different processing architectures (ARMv7, ARMv8, MIPS64, Power, and x86), +offering both application portability and accelerated performance tailored to +each platform. Other implementations are under development by both LNG member +companies and other companies participating in the project. + +== What OS is typically used with ODP? + +ODP applications usually run as Linux user space applications, but there are +also a number of “bare metal” environments in use. A typical deployment will be +using Linux as the control node on at least one CPU and then using the NO_HZ +and isolation features of Linux to essentially run the application fast-path +packet processing code as if it were using “bare metal” on the remaining cores. + +== Is ODP open? + +ODP is a true open source, open contribution project that is distributed under +a 3-clause BSD license, meaning that anyone is free to use, modify and +distribute it for commercial or other purposes without restriction. ODP has a +public mailing list (lng-odp@lists.linaro.org), and discussion on this list +shows the wide base of participation in the ODP project. There are also a +number of independent externally hosted ODP implementations [6]. + +== What is odp-linux? + +The ODP linux-generic implementation is a functional reference targeting +simplicity over performance if there is marked difference. The +higher-performance implementations of ODP come directly from the vendors. +Linaro also maintains implementations for some other important platforms that +do not yet have direct vendor support [3]. + +== Does ODP really help portability? + +.ODP and portability +image::aboutODP5.svg[align="center"] + +Yes. ODP abstracts hardware capabilities for data-plane processing so that +applications may be written more portably Application developers may make use +of important hardware capabilities such as crypto hardware acceleration without +needing deep knowledge of the hardware or the vendor-specific SDK associated +with it. This will make it much easier for them to write portable applications +that work well across multiple hardware implementations. + +== Can ODP inter-operate with a native SDK? + +Yes. + +== Does ODP allow software extensions? + +No. the ODP API does not allow for software extensions. However, ODP does not +preclude calling a vendor's SDK in parallel with ODP but the expectation is +that over time any features that become common to multiple platforms will be +supported in future versions of the portable ODP APIs. + +== Does ODP work with FPGAs? + +There is no explicit initialization support for altering the image in an FPGA +at boot time, but several major players have looked at ODP and we hope they +will help define the support they require. + +== Does ODP work with NICs? + +Yes. +So far, ODP has been vigorously taken up by vendors who supply much more +functionality in their hardware than a plain NIC can provide. One of those +vendors package this capability as a NIC + ODP library. The ODP project also +supports its own ODP-DPDK [1] implementation to help migrations from the lower +level DPDK API to the ODPs abstraction. + +But traditional NICs are supported odp-linux has PKTIO support for Netmap and +DPDK. + +== Does ODP support polling mode? + +ODP does not dictate a model, although the majority of current contributors see +greater value in an event-driven model which which it is felt will scale better +than a polling mode driver. + +== Does ODP add a lot of overhead vs. the native SDK? + +No, ODP is just an API designed by the contributors. The implementation is +developed by the hardware vendor to be optimal for their platform. + +Even running OVS on odp-dpdk vs dpdk shows at worst case 1.7% overhead in basic +tests. + +== What is the difference between ODP and DPDK? + +ODP is an API, DPDK is a specific implementation of an API. +ODP is an abstraction that is just at a high-enough level to allow platform +abstraction without imposing strict models and overheads + +== Does ODP force the use of specific structures? + +.ODP and specific structures +image::packet.svg[align="center"] + +ODP uses abstractions for the structures that are defined by the implementing +vendor so that they map closely to the hardware and are very efficient. The +application may then access this data though inline functions so that platform +specific data is never exposed, for example odp_packet_len() [5] to determine a +packet length. + +== Does ODP have legacy application support? + +ODP can be used to implement hardware acceleration for interfaces for sockets, +or polling mode drivers. + +== Does ODP provide everything needed for an application? + +No. ODP is defining the lowest level abstractions for hardware acceleration and +it is expected that layers of software using these primitives will be able to +add deeper application support. In addition ODP does not try to add Operating +System abstractions. + +== Where are ODP Data-plane Applications? + +They are traditionally the software in routers, switches, gateways, set top +boxes, Evolved Node B, etc. Increasingly they are data-center applications that +can make use of the acceleration features available in servers, such as Open +vSwitch, TRex, NGiNX.