From a9bb0c44c775784f3d6cafd4d774301db633cb47 Mon Sep 17 00:00:00 2001 From: Shreyansh Jain Date: Wed, 31 Jan 2018 14:43:18 +0530 Subject: [PATCH] doc: add rawdev library guide and doxygen page 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.rst | 107 +++++++++++++++++++++++++ doc/guides/rel_notes/release_18_02.rst | 13 +++ 6 files changed, 124 insertions(+) create mode 100644 doc/guides/prog_guide/rawdev.rst diff --git a/MAINTAINERS b/MAINTAINERS index 9beb30237a..d22837793f 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -321,6 +321,7 @@ M: Hemant Agrawal F: lib/librte_rawdev/ F: drivers/raw/skeleton_rawdev/ F: test/test/test_rawdev.c +F: doc/guides/prog_guide/rawdev.rst Bus Drivers diff --git a/doc/api/doxy-api-index.md b/doc/api/doxy-api-index.md index 59281a1098..d77f205bbd 100644 --- a/doc/api/doxy-api-index.md +++ b/doc/api/doxy-api-index.md @@ -47,6 +47,7 @@ The public API headers are grouped by topics: [security] (@ref rte_security.h), [eventdev] (@ref rte_eventdev.h), [event_eth_rx_adapter] (@ref rte_event_eth_rx_adapter.h), + [rawdev] (@ref rte_rawdev.h), [metrics] (@ref rte_metrics.h), [bitrate] (@ref rte_bitrate.h), [latency] (@ref rte_latencystats.h), diff --git a/doc/api/doxy-api.conf b/doc/api/doxy-api.conf index d4a72abc6f..cda52fdfbe 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 af5f65a338..aa41898400 100644 --- a/doc/guides/prog_guide/index.rst +++ b/doc/guides/prog_guide/index.rst @@ -49,6 +49,7 @@ Programmer's Guide bbdev cryptodev_lib rte_security + rawdev link_bonding_poll_mode_drv_lib timer_lib hash_lib diff --git a/doc/guides/prog_guide/rawdev.rst b/doc/guides/prog_guide/rawdev.rst new file mode 100644 index 0000000000..54bffc5851 --- /dev/null +++ b/doc/guides/prog_guide/rawdev.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 84e0ad0681..689080bed4 100644 --- a/doc/guides/rel_notes/release_18_02.rst +++ b/doc/guides/rel_notes/release_18_02.rst @@ -166,6 +166,18 @@ New Features renamed the application from SW PMD specific ``eventdev_pipeline_sw_pmd`` to PMD agnostic ``eventdev_pipeline``. +* **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` programmer's guide for more details. + * **Added new multi-process communication channel** Added a generic channel in EAL for multi-process (primary/secondary) communication. @@ -308,6 +320,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.20.1