doc/guides/prog_guide/rawdev.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright 2018 NXP
   3
   4 Rawdevice Library
   5 =================
   6
   7 Introduction
   8 ------------
   9
  10 In terms of device flavor (type) support, DPDK currently has ethernet
  11 (lib_ether), cryptodev (libcryptodev), eventdev (libeventdev) and vdev
  12 (virtual device) support.
  13
  14 For a new type of device, for example an accelerator, there are not many
  15 options except:
  16 1. create another lib/MySpecialDev, driver/MySpecialDrv and use it
  17 through Bus/PMD model.
  18 2. Or, create a vdev and implement necessary custom APIs which are directly
  19 exposed from driver layer. However this may still require changes in bus code
  20 in DPDK.
  21
  22 The DPDK Rawdev library is an abstraction that provides the DPDK framework a
  23 way to manage such devices in a generic manner without expecting changes to
  24 library or EAL for each device type. This library provides a generic set of
  25 operations and APIs for framework and Applications to use, respectively, for
  26 interfacing with such type of devices.
  27
  28 Design
  29 ------
  30
  31 Key factors guiding design of the Rawdevice library:
  32
  33 1. Following are some generic operations which can be treated as applicable
  34    to a large subset of device types. None of the operations are mandatory to
  35    be implemented by a driver. Application should also be designed for proper
  36    handling for unsupported APIs.
  37
  38   * Device Start/Stop - In some cases, 'reset' might also be required which
  39     has different semantics than a start-stop-start cycle.
  40   * Configuration - Device, Queue or any other sub-system configuration
  41   * I/O - Sending a series of buffers which can enclose any arbitrary data
  42   * Statistics - Fetch arbitrary device statistics
  43   * Firmware Management - Firmware load/unload/status
  44
  45 2. Application API should be able to pass along arbitrary state information
  46    to/from device driver. This can be achieved by maintaining context
  47    information through opaque data or pointers.
  48
  49 Figure below outlines the layout of the rawdevice library and device vis-a-vis
  50 other well known device types like eth and crypto:
  51
  52 .. code-block:: console
  53
  54      +-----------------------------------------------------------+
  55      |                        Application(s)                     |
  56      +------------------------------.----------------------------+
  57                                     |
  58                                     |
  59      +------------------------------'----------------------------+
  60      |                     DPDK Framework (APIs)                 |
  61      +--------------|----|-----------------|---------------------+
  62                    /      \                 \
  63             (crypto ops)  (eth ops)      (rawdev ops)        +----+
  64             /               \                 \              |DrvA|
  65      +-----'---+        +----`----+        +---'-----+       +----+
  66      | crypto  |        | ethdev  |        | raw     |
  67      +--/------+        +---/-----+        +----/----+       +----+
  68        /\                __/\                  /   ..........|DrvB|
  69       /  \              /    \                / ../    \     +----+
  70   +====+ +====+    +====+ +====+            +==/=+      ```Bus Probe
  71   |DevA| |DevB|    |DevC| |DevD|            |DevF|
  72   +====+ +====+    +====+ +====+            +====+
  73     |      |        |      |                 |
  74   ``|``````|````````|``````|`````````````````|````````Bus Scan
  75    (PCI)   |       (PCI)  (PCI)            (PCI)
  76          (BusA)
  77
  78  * It is assumed above that DrvB is a PCI type driver which registers itself
  79    with PCI Bus
  80  * Thereafter, when the PCI scan is done, during probe DrvB would match the
  81    rawdev DevF ID and take control of device
  82  * Applications can then continue using the device through rawdev API
  83    interfaces
  84
  85
  86 Device Identification
  87 ~~~~~~~~~~~~~~~~~~~~~
  88
  89 Physical rawdev devices are discovered during the Bus scan executed at DPDK
  90 initialization, based on their identification and probing with corresponding
  91 driver. Thus, a generic device needs to have an identifier and a driver
  92 capable of identifying it through this identifier.
  93
  94 Virtual devices can be created by two mechanisms, either using the EAL command
  95 line options or from within the application using an EAL API directly.
  96
  97 From the command line using the --vdev EAL option
  98
  99 .. code-block:: console
 100
 101    --vdev 'rawdev_dev1'
 102
 103 Or using the rte_vdev_init API within the application code.
 104
 105 .. code-block:: c
 106
 107     rte_vdev_init("rawdev_dev1", NULL)