From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from EUR01-DB5-obe.outbound.protection.outlook.com (mail-db5eur01on0067.outbound.protection.outlook.com [104.47.2.67]) by dpdk.org (Postfix) with ESMTP id 9BC021B747 for ; Wed, 31 Jan 2018 09:59:42 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=nxp.com; s=selector1; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version; bh=HeRx1A4Ot2kQ+4RZrN0HXz36QJ63NvCB4KKaWDLBe2g=; b=BiRqaDs9lAa3ss0QchttreIy5PIuNnQwUHG1Lyaho4xfTTzBpmlDY7zZQElsEB6m9Y/JWVA2eG8GUzMUPFFdQLS89jaKpZQkRO4Yc3FiNADv7rlqS+bhhW9znZVP/b/6PdgVdfAb0mGBDzB9h/u5JA5uJV+SaZgfSR8z16c2rJM= Authentication-Results: spf=none (sender IP is ) smtp.mailfrom=shreyansh.jain@nxp.com; Received: from Tophie.ap.freescale.net (192.88.169.1) by VI1PR0401MB2462.eurprd04.prod.outlook.com (2603:10a6:800:55::17) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384_P256) id 15.20.444.14; Wed, 31 Jan 2018 08:59:34 +0000 From: Shreyansh Jain To: thomas@monjalon.net Cc: dev@dpdk.org, hemant.agrawal@nxp.com, fiona.trahe@intel.com, rosen.xu@intel.com, Shreyansh Jain Date: Wed, 31 Jan 2018 14:43:18 +0530 Message-Id: <20180131091318.7894-11-shreyansh.jain@nxp.com> X-Mailer: git-send-email 2.14.1 In-Reply-To: <20180131091318.7894-1-shreyansh.jain@nxp.com> References: <20180130145710.24757-1-shreyansh.jain@nxp.com> <20180131091318.7894-1-shreyansh.jain@nxp.com> MIME-Version: 1.0 Content-Type: text/plain X-Originating-IP: [192.88.169.1] X-ClientProxiedBy: HK2PR02CA0168.apcprd02.prod.outlook.com (2603:1096:201:1f::28) To VI1PR0401MB2462.eurprd04.prod.outlook.com (2603:10a6:800:55::17) X-MS-PublicTrafficType: Email X-MS-Office365-Filtering-HT: Tenant X-MS-Office365-Filtering-Correlation-Id: 59d4a238-a90e-4714-0666-08d56888f61e X-Microsoft-Antispam: UriScan:; BCL:0; PCL:0; RULEID:(7020095)(4652020)(4534165)(4627221)(201703031133081)(201702281549075)(48565401081)(5600026)(4604075)(2017052603307)(7153060)(7193020); SRVR:VI1PR0401MB2462; X-Microsoft-Exchange-Diagnostics: 1; VI1PR0401MB2462; 3:Q70eK2GjBa1zVVuDy2unq/zCt1LrQoIuOx0nqIuRHW5EYNbW82UAuVqy1ZS7Hh2Pkqrl0sg5xNSlUy9j7kutG8OLYPjUcC1op07I37iMizH5VxU+GdTkNq7LkY5DUgR9RM8mAbnj15RfxHTMP+UVKR169PS9JdiIMB9hYUo5Jzw0YMSo7cm6dyIXPYRImKRWJ8095s4oBqciM2MQ3lqwXeU9tybluB8jYalG5+1hcgFaKN96JgEQfeMj9iT8shhF; 25:onkoqvphdVX7n/15OfKNnPfykoBYTSwcUJ2RH8IPdhbbRq/SkouxNZh8fFFkx03G4YMCTxa+/QDwt7jBZHC3M7+0+6iXOXZvKZiVktEC6GUAmII0MA2fErwwQfX0EbXFtoA2A/xaojWq6UIUvzgAVQELwK+hudKpmopteclD49tK8xqNpRkgdq+CoLSDT1iic70zeeXJpp6lha5TSiKfYGz6z4Ht3S/qv8Od2SyPDgorwYQ4dJv28Q/o5uVWmz6nHM165+v0lgekE4t9bzYOiGJgmbZ/eMW4mKvmwDusnsGQOXD+DlzlLzQG5Vm1u0MGDrYUxopfN7WD6TZEgv83tg==; 31:GyWUogS4igEuDHDkDglyooszOI05t8TN5HxqaGOhFmp5QydrHprKkIDQGxn2Z584e8W/iM+OP7Kb8ezlvDPklAnamfvFjICX26AWrIg8+X8fG8NtbyKzSLBDh+lgOokIOp5fwqBrCAwxYcgWocpmgrDDA/8vl1j6QFxEZW5ONtrYRQBT7ye5eC6b/cmex6ExBUfuTt3/aQjYanv3JNfD/Ta2ubGmN06A7Php1aPAH9k= X-MS-TrafficTypeDiagnostic: VI1PR0401MB2462: X-Microsoft-Exchange-Diagnostics: 1; VI1PR0401MB2462; 20:9zs1oLRZBsDpJZtdKAA3naPGusfzsklfjXazFFBXCBLGEwXMKAQVetKdYwooyFBQTZuyonPtZuMS5sJxhLDofDHyMmemeIsogkZv9eEz7zymSUEMARAFeNf/YHspG7ZiaK+BGujUFRZvyoLHI+EFohHwnllweMR9aVy1rRMXFMuQ0B+YSVESEgV/hlJH5SsuDAjI1NtnEm03V53pk9Zz1BHIy7n/rFOI78xNtl2Yj3y0lLAHvgpItXhL5HbGnP5U1y6BJRfBacsqcmbZLU5D22Qha4SX26+3VKeuUkQ7lXcGCOA+bGlscYG5HuYrTNuJ6GoyvNsKKrZD/Ghi7HV3RyguLwzea+liGqPlVpOj2SQE2sN/Rlp9egl+3LJhG2dBZvJpKXpu3aPG9WZw/ocDFK5pBHxzUVc+rJjXtFfRpvSZwUsFG3cMRVLtnaXPwLykxGtoZSHWu/lQouBS5uWkrDnj4rH/mczogjqtwA8tqYB+pG7X3E4QYtSnTYtcN3mA; 4:V/vNHoYPcZggIfnM4dxN7uTFDgm6DsyYNtapa24az7xff9L6NdHpLB8nqfHP+sqM7fDC2ip8c4uZqwKBEN95SeYJaC/gqIz23BTcpokfVuR7l/XFMGpGs9LRQNuahuujHbLezV60Q0jY70gWoZ0X2pJwTPRSbfV2tdWnBKmsCtLchY1MfmIRdapd095+eXLuxbTOvK282RuCzr/+YLcTv9YEPAXcTI0pCJTMpiKs2uf/VZa78Z4qs5pC/gF1a+y3oF6fe9vXlIaQKDPRYLSvpSwPblPsltnjNeepSu+tBzcAbyyLs1Taduq4SkFqcBUl/6/EYX31N1wpFG3SrUMCrYck6Ix63Oj8Xz43vd+yRROKZAE8PKLlpfMLd59Apvay X-Microsoft-Antispam-PRVS: X-Exchange-Antispam-Report-Test: UriScan:(278428928389397)(35073007944872)(185117386973197); X-Exchange-Antispam-Report-CFA-Test: BCL:0; PCL:0; RULEID:(6040501)(2401047)(5005006)(8121501046)(3002001)(3231101)(2400082)(944501161)(93006095)(93001095)(10201501046)(6055026)(6041288)(20161123562045)(20161123560045)(20161123564045)(201703131423095)(201702281528075)(20161123555045)(201703061421075)(201703061406153)(20161123558120)(6072148)(201708071742011); SRVR:VI1PR0401MB2462; BCL:0; PCL:0; RULEID:; SRVR:VI1PR0401MB2462; X-Forefront-PRVS: 056929CBB8 X-Forefront-Antispam-Report: SFV:NSPM; SFS:(10009020)(396003)(39380400002)(376002)(366004)(346002)(39860400002)(199004)(189003)(6486002)(6512007)(50226002)(8676002)(48376002)(4326008)(81156014)(316002)(8936002)(66066001)(6666003)(2950100002)(81166006)(6916009)(53936002)(16526019)(5660300001)(47776003)(186003)(26005)(106356001)(2361001)(97736004)(16586007)(305945005)(478600001)(51416003)(386003)(575784001)(36756003)(86362001)(105586002)(68736007)(2351001)(76176011)(1076002)(52116002)(2906002)(6506007)(25786009)(3846002)(6116002)(50466002)(59450400001)(7736002); DIR:OUT; SFP:1101; SCL:1; SRVR:VI1PR0401MB2462; H:Tophie.ap.freescale.net; FPR:; SPF:None; PTR:InfoNoRecords; A:1; MX:1; LANG:en; Received-SPF: None (protection.outlook.com: nxp.com does not designate permitted sender hosts) X-Microsoft-Exchange-Diagnostics: =?us-ascii?Q?1; VI1PR0401MB2462; 23:RXfGCmNqdbgmGlEN5dhb4fN+chBNq4rFhMnNip1?= =?us-ascii?Q?32FM++UvqoSQuHVa9xQCMTyi5SfjxlsHQkVE8tw/R886ttb02v9QkeiNkxgU?= =?us-ascii?Q?Wjs04eRhJdyPOIt3R5U0N+/tXAyVgnXklNdb+OVsWvgIHaozTwxlAmG8edXR?= =?us-ascii?Q?E8L3jONBq1DSCCyLa7jdUaB6aLdNAucqIqweU/evHyIeJA/64D6OnTfouw87?= =?us-ascii?Q?LLztU1wPlTO8Q0A9GycVdGSlIUUUxPT8BNgqQPybG30UtXbwex+tLklXgOIJ?= =?us-ascii?Q?AJeTTHXkJyRMyqpbSbboAkUdlZiZEwbhJM6zVCUfOp30+Z15k9PqjiBRyqoV?= =?us-ascii?Q?dzRSnOhtFQjgHyWm9NFhqLYznEVlQwzkygW3pnv3Y6refEjZ3ryY3pZraBhb?= =?us-ascii?Q?Yc06uP2uwYN0k39GaQ7wi+CNyeHPv2h/m8fx4olCr5Hq+RuSUx+954P/sDj/?= =?us-ascii?Q?eFhAASvb0wKi39MBp4sblbEjRiqQMMQSj581CGm1UzrOUeFw8iXI3Uiy4Nfh?= =?us-ascii?Q?imKYuzVWsjBWtqukmhvW3hS+p2+ZoDCzk2wsl3Kw6EOyND7pCfSNha6d5A0t?= =?us-ascii?Q?G7fcjSEde2cgPh3XO5If7fYgw6yX8+CKH9+mCLf6i7Y4hAdBkedvPWXgCOdB?= =?us-ascii?Q?TpG39/gJLeI9Z3V0yLjf7mRnlFTbcFa7CJpnc/cN4KhOjSwxu7F6UGE9agIy?= =?us-ascii?Q?KYDZbLdSxuT7ZEZMMpSMSR2sdHlD8gNOjGU/yjAeNKLCI7jpj/hG2cbYYre1?= =?us-ascii?Q?+QmO+PdppNF7c7nyLS72OhZHhJxcq3QEBHWh0RMKsC9EiRby5Wy/EREVe3d+?= =?us-ascii?Q?zdYbiny0dBcJW072VXG5C8XgMcb94S6+Q/3tZsKFhFEXY2FpZWu8khn0hH5u?= =?us-ascii?Q?xIwBsLLpPhcfSkDj/z31YolJTyeTZQyr3tXpEX6e/Lx7tPrQllx4NTF9EpYJ?= =?us-ascii?Q?CaoIpPPHGAKe+l85P+kfEtjvyL58N/0vdCrefwxqG6Y6MP9VC8Gu+Aq3+B1R?= =?us-ascii?Q?LSN46rf6GHUUT/yWl4p78SBr1N1ZC+bdq6jFUWEb2XQ+BscOX/+vb8u7Jfww?= =?us-ascii?Q?juuH82xcARkBJWankNdfTbEc6RwNDXKVBLR0AwMWbZCtJpCgoLkP6CAJ1ydf?= =?us-ascii?Q?rLFvDBevO6skNhyeQMDpTg19X+gDlGAo+b4qf1lRC2Dw+wwHxoLm/h1HzF5D?= =?us-ascii?Q?7AlXvDIZpo/RuIcqSz68p9b5KK5ZER4DEBwCu?= X-Microsoft-Exchange-Diagnostics: 1; VI1PR0401MB2462; 6:dfAI5jZESZb2hHIv3HNJli2XXPN7+uKelQwTi++dMgb8u/YDt5NOqU0OYIWmZzgrZOybe8G3BNP7ElhvKExImqBZFNTy6UPjGzEVEBvnXjFifOFEuKyjFncqsQeUf4+lPHmnQKCbSbL2T4djnIt1ht87/niPQyrseEfwiWjFZqqBRKwI9Cch0L855mBfBHdqRl5Akw/7KvGd00jd9gW00xLCD0bwMFERAQSV9KcTkbBLUtynq++v06IgaJIZDTpDo9hgakQZlg+38syTvv05dqzmC/rggnPpTYxOaH01QUId33WfDOcR/dYIvtdOdwizVD+41lsJz6BGHbCzMdUE9Mj1+jqbQ5K1kgcBFXcHg0U=; 5:bgvEt7R/m1/zrSaqmCeC024ZOem5Y4O0eP1yQQbiUAqRsxvGY9we9fYalM9KFkWJGhcXDRLTTE2nDnph821+geSe17tvpKxMgLOkFqHA3wESWiiQ/sQjcB044pFswRhTuKFepWFLfmoRPUAZ5VrIpQlg/E8hALRDfl5f8ag4kO8=; 24:3ZtyojeF71J9EmgeP1HhG8liOQd9gNIjE1vCHDvS1vgnbtGQrM8ixPs3lqkQUVZeHcg5MvP78UPdSAtYbjacjKOvBpRfcKKJ4o1gVN/vsDw=; 7:AltHk4mpEo49U5bCNnanWeiXyBshyxOABUvyMr1Amo0hc4vZyCzDqdlSLdxUVyCSRKlIjoWIFITsO7G6+czqKg20b2AORqbEVMRnY2KNNKmo6Ss8tzmZIU9uSyjZ4qDCSqSN+VwyF/e8Zgvd8Ih3vI75tnvGLQ9eXRJeaFExnp5R6GoMq3x799iC8LIEBMfe7i4+Wt7wPe/iZjKvBr/TqsRschW4MTHMpHlmpnjz6ulGwal1bGpVqkd7DFg2Bo5a SpamDiagnosticOutput: 1:99 SpamDiagnosticMetadata: NSPM X-OriginatorOrg: nxp.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 31 Jan 2018 08:59:34.9452 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: 59d4a238-a90e-4714-0666-08d56888f61e X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: 686ea1d3-bc2b-4c6f-a92c-d99c5c301635 X-MS-Exchange-Transport-CrossTenantHeadersStamped: VI1PR0401MB2462 Subject: [dpdk-dev] [PATCH v4 10/10] doc: add rawdev library page and support Doxygen 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: Wed, 31 Jan 2018 08:59:42 -0000 Signed-off-by: Shreyansh Jain --- MAINTAINERS | 1 + doc/api/doxy-api-index.md | 1 + doc/api/doxy-api.conf | 1 + doc/guides/prog_guide/index.rst | 1 + doc/guides/prog_guide/rawdev_lib.rst | 107 +++++++++++++++++++++++++++++++++ doc/guides/rel_notes/release_18_02.rst | 12 ++++ 6 files changed, 123 insertions(+) create mode 100644 doc/guides/prog_guide/rawdev_lib.rst diff --git a/MAINTAINERS b/MAINTAINERS index 42ddfbd8c..7ab7728f4 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -321,6 +321,7 @@ M: Hemant Agrawal F: lib/librte_rawdev/* F: drivers/rawdev/skeleton/* F: test/test/test_rawdev.c +F: doc/guides/prog_guide/rawdev_lib.rst Bus Drivers diff --git a/doc/api/doxy-api-index.md b/doc/api/doxy-api-index.md index 59281a109..4259b517a 100644 --- a/doc/api/doxy-api-index.md +++ b/doc/api/doxy-api-index.md @@ -43,6 +43,7 @@ The public API headers are grouped by topics: [rte_tm] (@ref rte_tm.h), [rte_mtr] (@ref rte_mtr.h), [bbdev] (@ref rte_bbdev.h), + [rawdev] (@ref rte_rawdev.h), [cryptodev] (@ref rte_cryptodev.h), [security] (@ref rte_security.h), [eventdev] (@ref rte_eventdev.h), diff --git a/doc/api/doxy-api.conf b/doc/api/doxy-api.conf index d4a72abc6..cda52fdfb 100644 --- a/doc/api/doxy-api.conf +++ b/doc/api/doxy-api.conf @@ -71,6 +71,7 @@ INPUT = doc/api/doxy-api-index.md \ lib/librte_pipeline \ lib/librte_port \ lib/librte_power \ + lib/librte_rawdev \ lib/librte_reorder \ lib/librte_ring \ lib/librte_sched \ diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst index af5f65a33..beead3105 100644 --- a/doc/guides/prog_guide/index.rst +++ b/doc/guides/prog_guide/index.rst @@ -75,6 +75,7 @@ Programmer's Guide vhost_lib metrics_lib port_hotplug_framework + rawdev_lib source_org dev_kit_build_system dev_kit_root_make_help diff --git a/doc/guides/prog_guide/rawdev_lib.rst b/doc/guides/prog_guide/rawdev_lib.rst new file mode 100644 index 000000000..54bffc585 --- /dev/null +++ b/doc/guides/prog_guide/rawdev_lib.rst @@ -0,0 +1,107 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright 2018 NXP + +Rawdevice Library +================= + +Introduction +------------ + +In terms of device flavor (type) support, DPDK currently has ethernet +(lib_ether), cryptodev (libcryptodev), eventdev (libeventdev) and vdev +(virtual device) support. + +For a new type of device, for example an accelerator, there are not many +options except: +1. create another lib/librte_MySpecialDev, driver/MySpecialDrv and use it +through Bus/PMD model. +2. Or, create a vdev and implement necessary custom APIs which are directly +exposed from driver layer. However this may still require changes in bus code +in DPDK. + +The DPDK Rawdev library is an abstraction that provides the DPDK framework a +way to manage such devices in a generic manner without expecting changes to +library or EAL for each device type. This library provides a generic set of +operations and APIs for framework and Applications to use, respectively, for +interfacing with such type of devices. + +Design +------ + +Key factors guiding design of the Rawdevice library: + +1. Following are some generic operations which can be treated as applicable + to a large subset of device types. None of the operations are mandatory to + be implemented by a driver. Application should also be design for proper + handling for unsupported APIs. + + * Device Start/Stop - In some cases, 'reset' might also be required which + has different semantics than a start-stop-start cycle. + * Configuration - Device, Queue or any other sub-system configuration + * I/O - Sending a series of buffers which can enclose any arbitrary data + * Statistics - Fetch arbitrary device statistics + * Firmware Management - Firmware load/unload/status + +2. Application API should be able to pass along arbitrary state information + to/fro device driver. This can be achieved by maintaining context + information through opaque data or pointers. + +Figure below outlines the layout of the rawdevice library and device vis-a-vis +other well known device types like eth and crypto: + +.. code-block:: console + + +-----------------------------------------------------------+ + | Application(s) | + +------------------------------.----------------------------+ + | + | + +------------------------------'----------------------------+ + | DPDK Framework (APIs) | + +--------------|----|-----------------|---------------------+ + / \ \ + (crypto ops) (eth ops) (rawdev ops) +----+ + / \ \ |DrvA| + +-----'---+ +----`----+ +---'-----+ +----+ + | crypto | | ethdev | | raw | + +--/------+ +---/-----+ +----/----+ +----+ + /\ __/\ / ..........|DrvB| + / \ / \ / ../ \ +----+ + +====+ +====+ +====+ +====+ +==/=+ ```Bus Probe + |DevA| |DevB| |DevC| |DevD| |DevF| + +====+ +====+ +====+ +====+ +====+ + | | | | | + ``|``````|````````|``````|`````````````````|````````Bus Scan + (PCI) | (PCI) (PCI) (PCI) + (BusA) + + * It is assumed above that DrvB is a PCI type driver which registers itself + with PCI Bus + * Thereafter, when the PCI scan is done, during probe DrvB would match the + rawdev DevF ID and take control of device + * Applications can then continue using the device through rawdev API + interfaces + + +Device Identification +~~~~~~~~~~~~~~~~~~~~~ + +Physical rawdev devices are discovered during the Bus scan executed at DPDK +initialization, based on their identification and probing with corresponding +driver. Thus, a generic device needs to have an identifier and a driver +capable of identifying it through this identifier. + +Virtual devices can be created by two mechanisms, either using the EAL command +line options or from within the application using an EAL API directly. + +From the command line using the --vdev EAL option + +.. code-block:: console + + --vdev 'rawdev_dev1' + +Our using the rte_vdev_init API within the application code. + +.. code-block:: c + + rte_vdev_init("rawdev_dev1", NULL) diff --git a/doc/guides/rel_notes/release_18_02.rst b/doc/guides/rel_notes/release_18_02.rst index 84e0ad068..ce5ccaf9d 100644 --- a/doc/guides/rel_notes/release_18_02.rst +++ b/doc/guides/rel_notes/release_18_02.rst @@ -192,6 +192,17 @@ New Features is unaffected by these changes, and can continue to be used for this and subsequent releases until such time as it's deprecation is announced. +* **Added Rawdev, a generic device support library.** + + Rawdev library provides support for integrating any generic device type with + DPDK framework. Generic devices are those which do not have a pre-defined + type within DPDK, for example, ethernet, crypto, event etc. + A set of northbound APIs have been defined which encompass a generic set of + operations by allowing applications to interact with device using opaque + structures/buffers. Also, southbound APIs provide APIs for integrating device + either as as part of a physical bus (PCI, FSLMC etc) or through ``vdev``. + + See the :doc:`../prog_guide/rawdev_lib` programmer's guide for more details. API Changes ----------- @@ -308,6 +319,7 @@ The libraries prepended with a plus sign were incremented in this version. librte_pmd_vhost.so.2 librte_port.so.3 librte_power.so.1 + librte_rawdev.so.1 librte_reorder.so.1 librte_ring.so.1 librte_sched.so.1 -- 2.14.1