From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from NAM01-SN1-obe.outbound.protection.outlook.com (mail-sn1nam01on0082.outbound.protection.outlook.com [104.47.32.82]) by dpdk.org (Postfix) with ESMTP id CAE1E1B3E0 for ; Tue, 30 Jan 2018 16:24:49 +0100 (CET) Received: from BN6PR03CA0014.namprd03.prod.outlook.com (10.168.230.152) by BY2PR03MB476.namprd03.prod.outlook.com (10.141.141.153) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384_P256) id 15.20.444.14; Tue, 30 Jan 2018 15:24:48 +0000 Received: from BL2FFO11OLC015.protection.gbl (2a01:111:f400:7c09::148) by BN6PR03CA0014.outlook.office365.com (2603:10b6:404:23::24) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384) id 15.20.444.14 via Frontend Transport; Tue, 30 Jan 2018 15:24:47 +0000 Authentication-Results: spf=fail (sender IP is 192.88.168.50) smtp.mailfrom=nxp.com; dpdk.org; dkim=none (message not signed) header.d=none;dpdk.org; dmarc=fail action=none header.from=nxp.com; Received-SPF: Fail (protection.outlook.com: domain of nxp.com does not designate 192.88.168.50 as permitted sender) receiver=protection.outlook.com; client-ip=192.88.168.50; helo=tx30smr01.am.freescale.net; Received: from tx30smr01.am.freescale.net (192.88.168.50) by BL2FFO11OLC015.mail.protection.outlook.com (10.173.160.81) with Microsoft SMTP Server (version=TLS1_0, cipher=TLS_RSA_WITH_AES_256_CBC_SHA) id 15.20.444.13 via Frontend Transport; Tue, 30 Jan 2018 15:24:46 +0000 Received: from Tophie.ap.freescale.net ([10.232.14.39]) by tx30smr01.am.freescale.net (8.14.3/8.14.0) with ESMTP id w0UEh7so023996; Tue, 30 Jan 2018 07:43:45 -0700 From: Shreyansh Jain To: CC: , , , , Shreyansh Jain Date: Tue, 30 Jan 2018 20:27:10 +0530 Message-ID: <20180130145710.24757-12-shreyansh.jain@nxp.com> X-Mailer: git-send-email 2.14.1 In-Reply-To: <20180130145710.24757-1-shreyansh.jain@nxp.com> References: <20180123135910.10755-1-shreyansh.jain@nxp.com> <20180130145710.24757-1-shreyansh.jain@nxp.com> X-EOPAttributedMessage: 0 X-Matching-Connectors: 131617994878930248; (91ab9b29-cfa4-454e-5278-08d120cd25b8); () X-Forefront-Antispam-Report: CIP:192.88.168.50; IPV:NLI; CTRY:US; EFV:NLI; SFV:NSPM; SFS:(10009020)(376002)(39380400002)(39860400002)(346002)(396003)(2980300002)(1109001)(1110001)(339900001)(199004)(189003)(498600001)(97736004)(6862004)(106466001)(336011)(77096007)(54906003)(50466002)(36756003)(51416003)(76176011)(4326008)(26005)(50226002)(8676002)(356003)(81156014)(48376002)(8936002)(81166006)(305945005)(104016004)(5660300001)(53936002)(47776003)(105606002)(85426001)(2351001)(86362001)(1076002)(6666003)(16586007)(2950100002)(316002)(68736007)(2906002); DIR:OUT; SFP:1101; SCL:1; SRVR:BY2PR03MB476; H:tx30smr01.am.freescale.net; FPR:; SPF:Fail; PTR:InfoDomainNonexistent; A:1; MX:1; LANG:en; X-Microsoft-Exchange-Diagnostics: 1; BL2FFO11OLC015; 1:OuimVBs1zhZSnTJNdsZRxpDxjQRB3m2DEFgzksBMAZfbIJw0ngKO5C37K0lJiCspyfL2D1CpwavJ5Z3UiL1Qo4JkX/nTiVd5nAmGE+OzIvhPaxlIoZZDH8veDTwBFWJr MIME-Version: 1.0 Content-Type: text/plain X-MS-PublicTrafficType: Email X-MS-Office365-Filtering-Correlation-Id: 8f4f9759-3363-4848-6bf2-08d567f59943 X-Microsoft-Antispam: UriScan:; BCL:0; PCL:0; RULEID:(7020095)(5600026)(4604075)(2017052603307); SRVR:BY2PR03MB476; X-Microsoft-Exchange-Diagnostics: 1; BY2PR03MB476; 3:ijXGSZGC8Tbx1Fkh3iQJ3kK/3a3+UZx33k2Si5iJXeeIWnz6M86MPOpi7anU/Yu+chrLy0SWmdrFnrzvxASv7YBI37Q/OgIIAi56/jO80uyfEkiZWv0J77JGdmrIaIwvJWGN7qRUOhlxfvr6IUWhaaPzGkf6Tp1E1we+wRkpjDhbBZUSdFnyslYtlI5/3g705kZCxjdj1K2Ma76KmXc2qdxr5vo7DPN8ZM6wpHlqBQusibiCIWoPSrNDm8seEh9ZAQCx+rLICF88w4g69iaQgfhSHnRXSGGhtFPwM09XY0hrx8tMFkT5XAdmd3ixCSZ1wd0cmE2HKguOSrUMEbyMoVw6yNF3K4CC5rp28kUKAYQ=; 25:MQQs3LFzCIFvXDCN8/744pHN86W/wZeUbjAG3Z6JQJZ/68gxH4HCLKABh2WPrHi2Rz1/eqVjaXTXTMy1RUypcnkXh3mcL/2VXQpH1bQ0sdDJ9MWtfszMdA1ur1G08wSz6tkeHwdy6KpUrKM/TZoCCdsp9192o7jPUCBAYQnygO0kT0srQ2jn6TOgqtR7e4g9mli8ZjFYL1m36dYV9AxXMytOUpAMJ4a6I1G6gQFQtLFRUCpJGVp7IXYfFip+6oygfjXiEWMFPo87VUn+5CDKaGNEbmP7bu4vDvEKOy8ThQbg6RMyDoDdoZyh2nXNgXRjqsB/NqQLjgCMnmoyvRULJA== X-MS-TrafficTypeDiagnostic: BY2PR03MB476: X-Microsoft-Exchange-Diagnostics: 1; BY2PR03MB476; 31:VyIg8xaCe7JqZQPJvf/XBgWkT6UjmzJ16j+0f/JtUH7pOKRkqn7mHOYkvt0NwE8uf9XLvrtM9lLBfgU9dEFH4U2ShrNv+nTb2gFhUwKE+O824OgjVihnomINj589rTtVXLGFZM5lqB59dO7VooNNbGuBoILM9qmqKMQDgMMouSnDB+7agZCAfo7e2ZC2byh9LhI2G6dXYlbjofHPSqHTBGxCSnUfO9OekEz6nq8WoiM=; 4:XKXtQFkucPJeaQtuTuf2FQBaorPI5qrt6eF3ux93Gvgp+/vkJ+FTAAdqEVcB2dU0d5VjD2B4L36mWkPyZ7+R0KepguppJ6z4ill4dTLdUygsg7FAA3Hi1sOJCjpg3sSRL4l+mfOvdVXoHxUI8SKN9BYBgWtNxYVRhvDcuSgooqyEkGIIvez/fqfK8uFUcFdbjwHPmqEMLkg75k4HQHzqWpg76zNHKrraPXNYC6Xet7qwwWeNiWXYk7DBgjqHtVQqikagBTNdvd4UakFXqKnhwu+IDwuCHSS4e6cocgEzGpcmeisUhZJSKJBIm+58o9A3uYIta5wIGz9U26u9/MFyOFumjHDWVcWh6QidvYTXXGo= X-Microsoft-Antispam-PRVS: X-Exchange-Antispam-Report-Test: UriScan:(278428928389397)(185117386973197); X-Exchange-Antispam-Report-CFA-Test: BCL:0; PCL:0; RULEID:(6095135)(2401047)(8121501046)(5005006)(3002001)(93006095)(93001095)(3231101)(944501161)(10201501046)(6055026)(6096035)(20161123565025)(20161123561025)(201703131430075)(201703131448075)(201703131433075)(201703151042153)(20161123556025)(20161123559100)(20161123563025)(201708071742011); SRVR:BY2PR03MB476; BCL:0; PCL:0; RULEID:(400006); SRVR:BY2PR03MB476; X-Forefront-PRVS: 0568F32D91 X-Microsoft-Exchange-Diagnostics: =?us-ascii?Q?1; BY2PR03MB476; 23:pNibkwm8EQMhjKjvtt3aWd4PLVcLTC8xY5gRrmMjU/?= =?us-ascii?Q?jm86gv0KjqXlpl7kyj+Lb/iuuNpjkq30qwqrD0ce79KgwyaJHeK2NrGwjHfo?= =?us-ascii?Q?QjXWBvbXTqbUyCkBewjp9VFyLksqpM/8P5dhQOz+ksCdqyNOmBAc8WYKSYLv?= =?us-ascii?Q?/pfjtEK1Oebu5+eg9d7iEbnArhpIuLAUaXNIuWyioqA6jgd0D/aVbtJ0wElO?= =?us-ascii?Q?1XDgLR4JrkC6yWPuLvg7Bz+Q0gWmscbdEChp220B8vFDCF7ooTJii/ZOCN2w?= =?us-ascii?Q?AQKngDdglRY6Aif2HUt+OCz8sjo92pzglPuRqFoG9m6yETeEN77JaTRa8VI9?= =?us-ascii?Q?tfqLjdlXq72Qj83+iM+Ld1cn5+X1zQAftLehPNUNLGOh1eenxRPjTtkh9sgU?= =?us-ascii?Q?jcAz/fmCw8LV+Oo68Vgb765N3rsY90soPN3CIAccDqxoqCVkFnRsn2AUqHE6?= =?us-ascii?Q?2l1EXhxwMSLkY70aTaGQDx5Kt6CSa1bVvsY8N17G6JyXoNmAxxNI/ldVSpCr?= =?us-ascii?Q?WlQ5O+JcB4Vt6cv/XD8geb07Q3iKTKMRcA6S694gI3HAyNjIFc4w6B8NFteT?= =?us-ascii?Q?ZK7IcX8AVNOMhUJ4ZugTG6CaN4iTaXv6L6YqUt0m7yx/EINEx5i08GyMaxad?= =?us-ascii?Q?LHMF26wtXvFIhmHYB1bt8+/5x4on+PQyOWYWklrUlwolVmtS7S8VxoK1vSc/?= =?us-ascii?Q?DFfaikakdYNxdTunBf4quaX/uimii/6IkwFJ5YSi/iZ8Ow2rKwG5lTk342Kj?= =?us-ascii?Q?nIe5y48RS5J9VjckTnNQb4Zbl4YQE5HuDFnatxwctn6UVa9qPYXKh/ok7ePx?= =?us-ascii?Q?JHQyQXuQrDl5g8KRwqjx9NNqqcj9OwsoUkxVNdMj6pVBirkGVTxjGZywzQ+Y?= =?us-ascii?Q?ZgUOYc2QiZlHKu4wpVa3lksJjx3h6sMmgoj9WsnRbJ19X6EG5ehKfK6J59Xl?= =?us-ascii?Q?wTJuCQd2NdMOii788nTvCB6bTfy5vhjsnpCnqNSkueTcois/I9uUd0rv/CtD?= =?us-ascii?Q?w7S9pc0tYPuW/MgUZBl31MdD2awUX75tsw0GxOHcI4y4aNeTLd9ejuFGxHWU?= =?us-ascii?Q?Ryi3PGZsikGWz2EjVXUF/QbnqkipfQLjTzL+8S2IGH8M4g0A=3D=3D?= X-Microsoft-Exchange-Diagnostics: 1; BY2PR03MB476; 6:kkzpS7NplK6YFPG5wOLKg9KGuNjbPQkpXQUZZ1DxVx91/zB7t7JbvY7KoV8/PBUcEgu2mA9+W10LHg8R6BS8P9NKnVa13Dw9Lh3MHGvktVwZO6szcQ5XLyIaR9T2SRIbQ+S0K0A0X7qZ0wfpG3jgE8vRLuO0o/ZlZyzMkM+AXfZNL7a3iY/dXRrUV9d24h/TemzLYH8bbGxn+Iq9DN54MgwRoWw9V2Bko/uVNY2bksQkyM94PA9yeNTn4F1WVUTz15l28PEs6fx9ugPLDOSN1srMq3hxmLhhNbBZWmLYF3amLLdHcr7Gyc8+uiRM+RYqwycP7X4RblqvcKlN+5Qf+1Xn4/aFKNrxDH3YBExIyws=; 5:IgW6YsNkH0jFfz9LgJqhOHi/D4pXfQLtAxr4ONp4L4C5oZvlWCViFvkjdeV0wI/gHbqtWtyayjx65xiAhNPUHvpvGSRFwGGAex5nkb+2kocdVHMo3anGcfRI2zaqRxY/lTfNbujI7atCEVLRyOmjYVtR2Tp1nKF834DUbfk3nrw=; 24:N7/nGPIEJ03aGTRojq22ZA8L/5TLOaqtaO5LLpeBalYh0xHbzM8F6auDWhD0RF9NI8h0o6j3BWnEqhCWu4gawVS+PIREfhtMGglVoQ25bog=; 7:PizED6PZnbwswiE27rfQytLTJho/0saGP3WyclyyCEP8Dy0AZ+aLvtsMUqC2eHKfLZmoT7v5lW09e1Zr5xGHiRCrc3kVSt8Vsch9b+JqJFhv6UY9Ak3dxMWBoTSQGpflkvQxBHl/swTKaX8x+cG6tUf9Uiq/w99oCY9y7JX7mzLOtQ/jd9qSYuMFf5JQY2zov8nBjEascmiYv+v5ARpNT5PKYriQUr4l/qMQFUi7FmNOQVXfwkij54dUblfxsU32 SpamDiagnosticOutput: 1:99 SpamDiagnosticMetadata: NSPM X-MS-Exchange-CrossTenant-OriginalArrivalTime: 30 Jan 2018 15:24:46.7386 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: 8f4f9759-3363-4848-6bf2-08d567f59943 X-MS-Exchange-CrossTenant-Id: 5afe0b00-7697-4969-b663-5eab37d5f47e X-MS-Exchange-CrossTenant-OriginalAttributedTenantConnectingIp: TenantId=5afe0b00-7697-4969-b663-5eab37d5f47e; Ip=[192.88.168.50]; Helo=[tx30smr01.am.freescale.net] X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem X-MS-Exchange-Transport-CrossTenantHeadersStamped: BY2PR03MB476 Subject: [dpdk-dev] [PATCH v3 11/11] doc: add rawdev library page 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, 30 Jan 2018 15:24:50 -0000 Signed-off-by: Shreyansh Jain --- doc/guides/prog_guide/index.rst | 1 + doc/guides/prog_guide/rawdev_lib.rst | 83 ++++++++++++++++++++++++++++++++++++ 2 files changed, 84 insertions(+) create mode 100644 doc/guides/prog_guide/rawdev_lib.rst 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..d21d284ca --- /dev/null +++ b/doc/guides/prog_guide/rawdev_lib.rst @@ -0,0 +1,83 @@ +.. 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 -- 2.14.1