From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga11.intel.com (mga11.intel.com [192.55.52.93]) by dpdk.org (Postfix) with ESMTP id F126D10BAB for ; Thu, 30 Mar 2017 10:27:19 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=simple/simple; d=intel.com; i=@intel.com; q=dns/txt; s=intel; t=1490862440; x=1522398440; h=from:to:cc:subject:date:message-id:references: in-reply-to:content-transfer-encoding:mime-version; bh=anq5dWEAQqNnbvkNvUJ/OUxIggM+DJDZN3GX/CP5rVE=; b=n2iko9PV6do650fX9amSHA6TmAXnOTQtkACMovoGfAOkHqz94Z0/4xt3 8KQuaaPbHKyL4SJ1iGSl+F8bXWYLcw==; Received: from orsmga001.jf.intel.com ([10.7.209.18]) by fmsmga102.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 30 Mar 2017 01:27:18 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.36,245,1486454400"; d="scan'208";a="1113572249" Received: from irsmsx107.ger.corp.intel.com ([163.33.3.99]) by orsmga001.jf.intel.com with ESMTP; 30 Mar 2017 01:27:17 -0700 Received: from irsmsx109.ger.corp.intel.com ([169.254.13.12]) by IRSMSX107.ger.corp.intel.com ([169.254.10.107]) with mapi id 14.03.0319.002; Thu, 30 Mar 2017 09:27:16 +0100 From: "Burakov, Anatoly" To: "Van Haaren, Harry" , "dev@dpdk.org" CC: "jerin.jacob@caviumnetworks.com" , "Van Haaren, Harry" Thread-Topic: [dpdk-dev] [PATCH v6 20/21] doc: add event device and software eventdev Thread-Index: AQHSqO7B9pTxvxyiUEWQ5SHJZkbh7aGtC3LQ Date: Thu, 30 Mar 2017 08:27:15 +0000 Message-ID: References: <1490374395-149320-1-git-send-email-harry.van.haaren@intel.com> <1490829963-106807-1-git-send-email-harry.van.haaren@intel.com> <1490829963-106807-21-git-send-email-harry.van.haaren@intel.com> In-Reply-To: <1490829963-106807-21-git-send-email-harry.van.haaren@intel.com> Accept-Language: en-US Content-Language: en-US X-MS-Has-Attach: X-MS-TNEF-Correlator: x-ctpclassification: CTP_PUBLIC x-titus-metadata-40: eyJDYXRlZ29yeUxhYmVscyI6IiIsIk1ldGFkYXRhIjp7Im5zIjoiaHR0cDpcL1wvd3d3LnRpdHVzLmNvbVwvbnNcL0ludGVsMyIsImlkIjoiNWY3ZmNhYTYtZmMzZi00YWE0LWE5MDItMzEwNWY5MjczMjhkIiwicHJvcHMiOlt7Im4iOiJDVFBDbGFzc2lmaWNhdGlvbiIsInZhbHMiOlt7InZhbHVlIjoiQ1RQX1BVQkxJQyJ9XX1dfSwiU3ViamVjdExhYmVscyI6W10sIlRNQ1ZlcnNpb24iOiIxNi41LjkuMyIsIlRydXN0ZWRMYWJlbEhhc2giOiJrME02U3g4SnlFbXFYdEo3ZnV0RTZPOHI3VDFYTXNORFJsbGVwQm1wYUNJPSJ9 x-originating-ip: [163.33.239.181] Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Subject: Re: [dpdk-dev] [PATCH v6 20/21] doc: add event device and software eventdev 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: Thu, 30 Mar 2017 08:27:20 -0000 Hi Harry, Small cosmetic suggestions :) > From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Harry van Haaren > Sent: Thursday, March 30, 2017 12:26 AM > To: dev@dpdk.org > Cc: jerin.jacob@caviumnetworks.com; Van Haaren, Harry > > Subject: [dpdk-dev] [PATCH v6 20/21] doc: add event device and software > eventdev >=20 > This commit adds a section to the docs listing the event device PMDs > available. >=20 > It then adds the software eventdev PMD to the listed event devices. >=20 > Signed-off-by: Harry van Haaren > Acked-by: Jerin Jacob >=20 > --- >=20 > v6: > - Fix QOS to QoS typo (Jerin) > - Add to section on dequeue timeout to limitations (Jerin) > --- > doc/guides/eventdevs/index.rst | 40 +++++++++++ > doc/guides/eventdevs/sw.rst | 157 > +++++++++++++++++++++++++++++++++++++++++ > doc/guides/index.rst | 1 + > 3 files changed, 198 insertions(+) > create mode 100644 doc/guides/eventdevs/index.rst create mode 100644 > doc/guides/eventdevs/sw.rst >=20 > diff --git a/doc/guides/eventdevs/index.rst > b/doc/guides/eventdevs/index.rst new file mode 100644 index > 0000000..9b1fcc7 > --- /dev/null > +++ b/doc/guides/eventdevs/index.rst > @@ -0,0 +1,40 @@ > +.. BSD LICENSE > + Copyright(c) 2017 Intel Corporation. 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. > + > +Event Device Drivers > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > + > +The following are a list of Event device PMDs, which can be used from > +an application trough the EventDev API. > + > +.. toctree:: > + :maxdepth: 2 > + :numbered: > + > + sw > diff --git a/doc/guides/eventdevs/sw.rst b/doc/guides/eventdevs/sw.rst > new file mode 100644 index 0000000..a531cf0 > --- /dev/null > +++ b/doc/guides/eventdevs/sw.rst > @@ -0,0 +1,157 @@ > +.. BSD LICENSE > + Copyright(c) 2017 Intel Corporation. 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. > + > +Software Eventdev Poll Mode Driver > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > + > +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. The naming is a bit inconsistent. At various times you are referring to eve= ntdev as Eventdev, EventDev (in index.rst), and eventdev. Maybe worth it to standardize on one= :) > + > + > +Features > +-------- > + > +The software eventdev implements many features in the eventdev API; > + > +Queues > + * Atomic > + * Ordered > + * Parallel > + * Single-Link > + > +Ports > + * Load balanced (for Atomic, Ordered, Parallel queues) > + * Single Link (for single-link queues) > + > +Event Priorities > + * Each event has a priority, which can be used to provide basic QoS > + > + > +Configuration and Options > +------------------------- > + > +The software eventdev is a vdev device, and as such can be created from > +the application code, or from the EAL command line: > + > +* Call ``rte_eal_vdev_init("event_sw0")`` from the application > + > +* Use ``--vdev=3D"event_sw0"`` in the EAL options, which will call > + rte_eal_vdev_init() internally > + > +Example: > + > +.. code-block:: console > + > + ./your_eventdev_application --vdev=3D"event_sw0" > + > + > +Scheduling Quanta > +~~~~~~~~~~~~~~~~~ > + > +The scheduling quanta sets the number of events that the device > +attempts to schedule before returning to the application from the > +``rte_event_schedule()`` function. Note that is a *hint* only, and that > +fewer or more events may be scheduled in a given iteration. > + > +The scheduling quanta can be set using a string argument to the vdev > +create call: > + > +.. code-block:: console > + > + --vdev=3D"event_sw0,sched_quanta=3D64" > + > + > +Credit Quanta > +~~~~~~~~~~~~~ > + > +The credit quanta is the number of credits that a port will fetch at a > +time from the instance's credit pool. Higher numbers will cause less > +overhead in the atomic credit fetch code, however it also reduces the > +overall number of credits in the system faster. A balanced number (eg > +32) ensures that only small numbers of credits are pre-allocated at a > +time, while also mitigating performance impact of the atomics. > + > +Experimentation with higher values may provide minor performance > +improvements, at the cost of the whole system having less credits. On > +the other hand, reducing the quanta may cause measurable performance > +impact but provide the system with a higher number of credits at all tim= es. > + > +A value of 32 seems a good balance however your specific application > +may benefit from a higher or reduced quanta size, experimentation is > +required to verify possible gains. > + > +.. code-block:: console > + > + --vdev=3D"event_sw0,credit_quanta=3D64" > + > + > +Limitations > +----------- > + > +The software eventdev implementation has a few limitations. The root > +cause of these limitations is that the performance impact of supporting > +the feature would be significant. I think the phrase "root cause" is usually used in context of figuring out = a bug, rather than describing reasoning behind a certain decision. I would replace "root cause" with "reason" or similar. > + > + > +"All Types" Queues > +~~~~~~~~~~~~~~~~~~ > + > +The software eventdev does not support creating queues that handle all > +types of traffic. An eventdev with this capability allows enqueueing > +Atomic, Ordered and Parallel traffic to the same queue, but scheduling e= ach > of them appropriately. > + > +The root cause of not allowing Atomic, Ordered and Parallel event types > +in the same queue is that it causes excessive branching in the code to > +enqueue packets to the queue, causing a significant performance impact. Same as above. > + > +The ``RTE_EVENT_DEV_CAP_QUEUE_ALL_TYPES`` flag is not set in the > +``event_dev_cap`` field of the ``rte_event_dev_info`` struct for the > +software eventdev. > + > +Distributed Scheduler > +~~~~~~~~~~~~~~~~~~~~~ > + > +The software eventdev is a centralized scheduler, requiring the > +``rte_event_schedule()`` function to be called by a CPU core to perform > +the required event distribution. This is not really a limitation but > +rather a design decision. > + > +The ``RTE_EVENT_DEV_CAP_DISTRIBUTED_SCHED`` flag is not set in the > +``event_dev_cap`` field of the ``rte_event_dev_info`` struct for the > +software eventdev. > + > +Dequeue Timeout > +~~~~~~~~~~~~~~~ > + > +The eventdev API supports a timeout when dequeuing packets using the > +``rte_event_dequeue_burst`` function. > +This allows a core to wait for an event to arrive, or until ``timeout`` > +number of ticks have passed. Timeout ticks is not supported by the > +software eventdev for performance reasons. > diff --git a/doc/guides/index.rst b/doc/guides/index.rst index > 82b00e9..63716b0 100644 > --- a/doc/guides/index.rst > +++ b/doc/guides/index.rst > @@ -43,6 +43,7 @@ DPDK documentation > testpmd_app_ug/index > nics/index > cryptodevs/index > + eventdevs/index > xen/index > contributing/index > rel_notes/index > -- > 2.7.4 Thanks, Anatoly