83d8e32397e25b0687a58388b1ebbf252e8d21bf
[dpdk.git] / 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 Tests
79 -----
80
81 The unit test cases can be tested as below:
82
83 .. code-block:: console
84
85     reserve enough huge pages
86     cd to <build_dir>
87     meson test cryptodev_virtio_autotest
88
89 The performance can be tested as below:
90
91 .. code-block:: console
92
93     reserve enough huge pages
94     cd to <build_dir>
95
96     ./app/dpdk-test-crypto-perf -l 0,1 -- --devtype crypto_virtio \
97         --ptest throughput --optype cipher-then-auth --cipher-algo aes-cbc \
98         --cipher-op encrypt --cipher-key-sz 16 --auth-algo sha1-hmac \
99         --auth-op generate --auth-key-sz 64 --digest-sz 12 \
100         --total-ops 100000000 --burst-sz 64 --buffer-sz 2048