doc/guides/cryptodevs/virtio.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2018 HUAWEI TECHNOLOGIES CO., LTD.
   3
   4 Virtio Crypto Poll Mode Driver
   5 ==============================
   6
   7 The virtio crypto PMD provides poll mode driver support for the virtio crypto
   8 device.
   9
  10 Features
  11 --------
  12
  13 The virtio crypto PMD has support for:
  14
  15 Cipher algorithms:
  16
  17 * ``RTE_CRYPTO_CIPHER_AES_CBC``
  18
  19 Hash algorithms:
  20
  21 * ``RTE_CRYPTO_AUTH_SHA1_HMAC``
  22
  23 Limitations
  24 -----------
  25
  26 *  Only supports the session-oriented API implementation (session-less APIs are
  27    not supported).
  28 *  Only supports modern mode since virtio crypto conforms to virtio-1.0.
  29 *  Only has two types of queues: data queue and control queue. These two queues
  30    only support indirect buffers to communication with the virtio backend.
  31 *  Only supports AES_CBC cipher only algorithm and AES_CBC with HMAC_SHA1
  32    chaining algorithm since the vhost crypto backend only these algorithms
  33    are supported.
  34 *  Does not support Link State interrupt.
  35 *  Does not support runtime configuration.
  36
  37 Virtio crypto PMD Rx/Tx Callbacks
  38 ---------------------------------
  39
  40 Rx callbacks:
  41
  42 * ``virtio_crypto_pkt_rx_burst``
  43
  44 Tx callbacks:
  45
  46 * ``virtio_crypto_pkt_tx_burst``
  47
  48 Installation
  49 ------------
  50
  51 Quick instructions are as follows:
  52
  53 Firstly run DPDK vhost crypto sample as a server side and build QEMU with
  54 vhost crypto enabled.
  55 QEMU can then be started using the following parameters:
  56
  57 .. code-block:: console
  58
  59     qemu-system-x86_64 \
  60     [...] \
  61         -chardev socket,id=charcrypto0,path=/path/to/your/socket \
  62         -object cryptodev-vhost-user,id=cryptodev0,chardev=charcrypto0 \
  63         -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0
  64     [...]
  65
  66 Secondly bind the uio_generic driver for the virtio-crypto device.
  67 For example, 0000:00:04.0 is the domain, bus, device and function
  68 number of the virtio-crypto device:
  69
  70 .. code-block:: console
  71
  72     modprobe uio_pci_generic
  73     echo -n 0000:00:04.0 > /sys/bus/pci/drivers/virtio-pci/unbind
  74     echo "1af4 1054" > /sys/bus/pci/drivers/uio_pci_generic/new_id
  75
  76 Finally the front-end virtio crypto PMD driver can be installed:
  77
  78 .. code-block:: console
  79
  80     cd to the top-level DPDK directory
  81     sed -i 's,\(CONFIG_RTE_LIBRTE_PMD_VIRTIO_CRYPTO\)=n,\1=y,' config/common_base
  82     make config T=x86_64-native-linuxapp-gcc
  83     make install T=x86_64-native-linuxapp-gcc
  84
  85 Tests
  86 -----
  87
  88 The unit test cases can be tested as below:
  89
  90 .. code-block:: console
  91
  92     reserve enough huge pages
  93     cd to the top-level DPDK directory
  94     export RTE_TARGET=x86_64-native-linuxapp-gcc
  95     export RTE_SDK=`pwd`
  96     cd to test/test
  97     type the command "make" to compile
  98     run the tests with "./test"
  99     type the command "cryptodev_virtio_autotest" to test
 100
 101 The performance can be tested as below:
 102
 103 .. code-block:: console
 104
 105     reserve enough huge pages
 106     cd to the top-level DPDK directory
 107     export RTE_TARGET=x86_64-native-linuxapp-gcc
 108     export RTE_SDK=`pwd`
 109     cd to app/test-crypto-perf
 110     type the command "make" to compile
 111     run the tests with the following command:
 112
 113     ./dpdk-test-crypto-perf -l 0,1 -- --devtype crypto_virtio \
 114         --ptest throughput --optype cipher-then-auth --cipher-algo aes-cbc \
 115         --cipher-op encrypt --cipher-key-sz 16 --auth-algo sha1-hmac \
 116         --auth-op generate --auth-key-sz 64 --digest-sz 12 \
 117         --total-ops 100000000 --burst-sz 64 --buffer-sz 2048