From mboxrd@z Thu Jan 1 00:00:00 1970 From: Shreyansh Jain Subject: [PATCH v3 11/11] doc: add rawdev library page Date: Tue, 30 Jan 2018 20:27:10 +0530 Message-ID: <20180130145710.24757-12-shreyansh.jain@nxp.com> References: <20180123135910.10755-1-shreyansh.jain@nxp.com> <20180130145710.24757-1-shreyansh.jain@nxp.com> Mime-Version: 1.0 Content-Type: text/plain Cc: , , , , Shreyansh Jain To: 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) In-Reply-To: <20180130145710.24757-1-shreyansh.jain@nxp.com> List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" 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