1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright 2018 NXP 3 4Rawdevice 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: 161. create another lib/librte_MySpecialDev, driver/MySpecialDrv and use it 17through Bus/PMD model. 182. Or, create a vdev and implement necessary custom APIs which are directly 19exposed from driver layer. However this may still require changes in bus code 20in DPDK. 21 22The DPDK Rawdev library is an abstraction that provides the DPDK framework a 23way to manage such devices in a generic manner without expecting changes to 24library or EAL for each device type. This library provides a generic set of 25operations and APIs for framework and Applications to use, respectively, for 26interfacing with such type of devices. 27 28Design 29------ 30 31Key factors guiding design of the Rawdevice library: 32 331. 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 design 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 452. 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 49Figure below outlines the layout of the rawdevice library and device vis-a-vis 50other 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 86Device Identification 87~~~~~~~~~~~~~~~~~~~~~ 88 89Physical rawdev devices are discovered during the Bus scan executed at DPDK 90initialization, based on their identification and probing with corresponding 91driver. Thus, a generic device needs to have an identifier and a driver 92capable of identifying it through this identifier. 93 94Virtual devices can be created by two mechanisms, either using the EAL command 95line options or from within the application using an EAL API directly. 96 97From the command line using the --vdev EAL option 98 99.. code-block:: console 100 101 --vdev 'rawdev_dev1' 102 103Our using the rte_vdev_init API within the application code. 104 105.. code-block:: c 106 107 rte_vdev_init("rawdev_dev1", NULL) 108