doc/guides/cryptodevs/null.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2016 Intel Corporation.
   3
   4 Null Crypto Poll Mode Driver
   5 ============================
   6
   7 The Null Crypto PMD (**librte_pmd_null_crypto**) provides a crypto poll mode
   8 driver which provides a minimal implementation for a software crypto device. As
   9 a null device it does not modify the data in the mbuf on which the crypto
  10 operation is to operate and it only has support for a single cipher and
  11 authentication algorithm.
  12
  13 When a burst of mbufs is submitted to a Null Crypto PMD for processing then
  14 each mbuf in the burst will be enqueued in an internal buffer for collection on
  15 a dequeue call as long as the mbuf has a valid rte_mbuf_offload operation with
  16 a valid rte_cryptodev_session or rte_crypto_xform chain of operations.
  17
  18 Features
  19 --------
  20
  21 Modes:
  22
  23 * RTE_CRYPTO_XFORM_CIPHER ONLY
  24 * RTE_CRYPTO_XFORM_AUTH ONLY
  25 * RTE_CRYPTO_XFORM_CIPHER THEN RTE_CRYPTO_XFORM_AUTH
  26 * RTE_CRYPTO_XFORM_AUTH THEN RTE_CRYPTO_XFORM_CIPHER
  27
  28 Cipher algorithms:
  29
  30 * RTE_CRYPTO_CIPHER_NULL
  31
  32 Authentication algorithms:
  33
  34 * RTE_CRYPTO_AUTH_NULL
  35
  36 Limitations
  37 -----------
  38
  39 * Only in-place is currently supported (destination address is the same as
  40   source address).
  41
  42 Installation
  43 ------------
  44
  45 The Null Crypto PMD is enabled and built by default in both the Linux and
  46 FreeBSD builds.
  47
  48 Initialization
  49 --------------
  50
  51 To use the PMD in an application, user must:
  52
  53 * Call rte_vdev_init("crypto_null") within the application.
  54
  55 * Use --vdev="crypto_null" in the EAL options, which will call rte_vdev_init() internally.
  56
  57 The following parameters (all optional) can be provided in the previous two calls:
  58
  59 * socket_id: Specify the socket where the memory for the device is going to be allocated
  60   (by default, socket_id will be the socket where the core that is creating the PMD is running on).
  61
  62 * max_nb_queue_pairs: Specify the maximum number of queue pairs in the device (8 by default).
  63
  64 * max_nb_sessions: Specify the maximum number of sessions that can be created (2048 by default).
  65
  66 Example:
  67
  68 .. code-block:: console
  69
  70     ./l2fwd-crypto -l 1 -n 4 --vdev="crypto_null,socket_id=0,max_nb_sessions=128" \
  71     -- -p 1 --cdev SW --chain CIPHER_ONLY --cipher_algo "null"