doc: add rawdev library guide and doxygen page
Signed-off-by: Shreyansh Jain <shreyansh.jain@nxp.com>
This commit is contained in:
Shreyansh Jain
Thomas Monjalon
parent
544092a0f9
commit
a9bb0c44c7
@ -321,6 +321,7 @@ M: Hemant Agrawal <hemant.agrawal@nxp.com>
|
||||
F: lib/librte_rawdev/
|
||||
F: drivers/raw/skeleton_rawdev/
|
||||
F: test/test/test_rawdev.c
|
||||
F: doc/guides/prog_guide/rawdev.rst
|
||||
|
||||
|
||||
Bus Drivers
|
||||
|
||||
@ -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),
|
||||
|
||||
@ -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 \
|
||||
|
||||
@ -49,6 +49,7 @@ Programmer's Guide
|
||||
bbdev
|
||||
cryptodev_lib
|
||||
rte_security
|
||||
rawdev
|
||||
link_bonding_poll_mode_drv_lib
|
||||
timer_lib
|
||||
hash_lib
|
||||
|
||||
107
doc/guides/prog_guide/rawdev.rst
Normal file
107
doc/guides/prog_guide/rawdev.rst
Normal file
@ -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)
|
||||
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user