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