From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga06.intel.com (mga06.intel.com [134.134.136.31]) by dpdk.org (Postfix) with ESMTP id BFA887CAB for ; Tue, 11 Jul 2017 16:19:44 +0200 (CEST) Received: from fmsmga005.fm.intel.com ([10.253.24.32]) by orsmga104.jf.intel.com with ESMTP; 11 Jul 2017 07:19:44 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.40,346,1496127600"; d="scan'208";a="125185223" Received: from silpixa00398672.ir.intel.com ([10.237.223.128]) by fmsmga005.fm.intel.com with ESMTP; 11 Jul 2017 07:19:42 -0700 From: Harry van Haaren To: dev@dpdk.org Cc: thomas@monjalon.net, jerin.jacob@caviumnetworks.com, keith.wiles@intel.com, bruce.richardson@intel.com, Harry van Haaren Date: Tue, 11 Jul 2017 15:19:32 +0100 Message-Id: <1499782773-12277-7-git-send-email-harry.van.haaren@intel.com> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1499782773-12277-1-git-send-email-harry.van.haaren@intel.com> References: <1499445667-32588-1-git-send-email-harry.van.haaren@intel.com> <1499782773-12277-1-git-send-email-harry.van.haaren@intel.com> Subject: [dpdk-dev] [PATCH v5 6/7] doc: add service cores to doc and release notes X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 11 Jul 2017 14:19:45 -0000 Add a section describing the fundamental concepts behind service cores. Where service cores originate from, and how to enable services. The release notes for 17.08 are updated, with an introductory paragraph on the service cores concept. Finally the Eventdev SW PMD documentation is amended to reflect that it can be run as a service. Signed-off-by: Harry van Haaren Acked-by: Jerin Jacob --- v4: - Add ack from ML I would like to enable the service-cores in the eventdev_pipeline sample app, to showcase the power of the service-core abstraction. There is some remaining work TODO, in order to genericise the sample app for both HW and SW PMDs, and during that rework the service-cores can be added too. The sample app will make a good showcase for docs, and make it much easier to understand. --- doc/guides/eventdevs/sw.rst | 4 +- doc/guides/prog_guide/index.rst | 1 + doc/guides/prog_guide/service_cores.rst | 81 +++++++++++++++++++++++++++++++++ doc/guides/rel_notes/release_17_08.rst | 8 ++++ 4 files changed, 93 insertions(+), 1 deletion(-) create mode 100644 doc/guides/prog_guide/service_cores.rst diff --git a/doc/guides/eventdevs/sw.rst b/doc/guides/eventdevs/sw.rst index fb63c84..a3e6624 100644 --- a/doc/guides/eventdevs/sw.rst +++ b/doc/guides/eventdevs/sw.rst @@ -32,7 +32,9 @@ Software Eventdev Poll Mode Driver The software eventdev is an implementation of the eventdev API, that provides a wide range of the eventdev features. The eventdev relies on a CPU core to -perform event scheduling. +perform event scheduling. This PMD can use the service core library to run the +scheduling function, allowing an application to utilize the power of service +cores to multiplex other work on the same core if required. Features diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst index 7578395..5548aba 100644 --- a/doc/guides/prog_guide/index.rst +++ b/doc/guides/prog_guide/index.rst @@ -38,6 +38,7 @@ Programmer's Guide intro overview env_abstraction_layer + service_cores ring_lib mempool_lib mbuf_lib diff --git a/doc/guides/prog_guide/service_cores.rst b/doc/guides/prog_guide/service_cores.rst new file mode 100644 index 0000000..3a029ba --- /dev/null +++ b/doc/guides/prog_guide/service_cores.rst @@ -0,0 +1,81 @@ +.. BSD LICENSE + Copyright(c) 2017 Intel Corporation. All rights reserved. + All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + + * Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + * Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in + the documentation and/or other materials provided with the + distribution. + * Neither the name of Intel Corporation nor the names of its + contributors may be used to endorse or promote products derived + from this software without specific prior written permission. + + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +Service Cores +============= + +DPDK has a concept known as service cores, which enables a dynamic way of +performing work on DPDK lcores. Service core support is built into the EAL, and +an API is provided to optionally allow applications to control how the service +cores are used at runtime. + +The service cores concept is built up out of services (components of DPDK that +require CPU cycles to operate) and service cores (DPDK lcores, tasked with +running services). The power of the service core concept is that the mapping +between service cores and services can be configured to abstract away the +difference between platforms and environments. + +For example, the Eventdev has hardware and software PMDs. Of these the software +PMD requires an lcore to perform the scheduling operations, while the hardware +PMD does not. With service cores, the application would not directly notice +that the scheduling is done in software. + +For detailed information about the service core API, please refer to the docs. + +Service Core Initialization +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are two methods to having service cores in a DPDK application, either by +using the service coremask, or by dynamically adding cores using the API. +The simpler of the two is to pass the `-s` coremask argument to EAL, which will +take any cores available in the main DPDK coremask, an if the bits are also set +in the service coremask the cores become service-cores instead of DPDK +application lcores. + +Enabling Services on Cores +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Each registered service can be individually mapped to a service core, or set of +service cores. Enabling a service on a particular core means that the lcore in +question will run the service. Disabling that core on the service stops the +lcore in question from running the service. + +Using this method, it is possible to assign specific workloads to each +service core, and map N workloads to M number of service cores. Each service +lcore loops over the services that are enabled for that core, and invokes the +function to run the service. + +Service Core Statistics +~~~~~~~~~~~~~~~~~~~~~~~ + +The service core library is capable of collecting runtime statistics like number +of calls to a specific service, and number of cycles used by the service. The +cycle count collection is dynamically configurable, allowing any application to +profile the services running on the system at any time. diff --git a/doc/guides/rel_notes/release_17_08.rst b/doc/guides/rel_notes/release_17_08.rst index 6273098..ab68f6f 100644 --- a/doc/guides/rel_notes/release_17_08.rst +++ b/doc/guides/rel_notes/release_17_08.rst @@ -59,6 +59,14 @@ New Features RAW pattern items with QUEUE actions. There are four type of filter support for this feature on igb. +* **Added Service Core functionality.** + + The service core functionality added to EAL allows DPDK to run services such + as SW PMDs on lcores without the application manually running them. The + service core infrastructure allows flexibility of running multiple services + on the same service lcore, and provides the application with powerful APIs to + configure the mapping from service lcores to services. + * **Added Generic Flow API support to enic.** Flow API support for outer Ethernet, VLAN, IPv4, IPv6, UDP, TCP, SCTP, VxLAN -- 2.7.4