From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-lf0-f51.google.com (mail-lf0-f51.google.com [209.85.215.51]) by dpdk.org (Postfix) with ESMTP id BEC0B1B2A0 for ; Tue, 10 Oct 2017 14:17:36 +0200 (CEST) Received: by mail-lf0-f51.google.com with SMTP id c82so26946356lfc.6 for ; Tue, 10 Oct 2017 05:17:36 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=semihalf-com.20150623.gappssmtp.com; s=20150623; h=from:to:cc:subject:date:message-id:in-reply-to:references; bh=Q8ZhjrjshgJG3vwT5DSnfLk1keG56Gjdp3Dz7Vp7cQk=; b=IoTFc3qkb1IZhZI6HEZu+h5VMvlvw+0pky4rW0VPZfxY1+m109LpTAIfjqSjUGKR5A 5rjSZUx9Q7d44V/RZA8JK4KLMEQL+pO+jJJeOorUltm+HxLnCtHakoS9lcQBHM3u+e7b aKVvP48J2wMBeBh3vNNKP/jG7LjUY3fwHeD9ROF/FxgFBN+yr7AdH/Dg4boeQScHb7to WPC9RAe5DTVOtINc25fkxnbRfb0jbMbicQokggDPmFYhWZ+WyedA72SqFiJrXpWkvzQZ /JBiQsiwqXeCdxPYQAdI+7LDiS6UuyMCmeeFnpFQ2a70HDa75AT9gTO5gbl0SWO3gYpD nAbA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references; bh=Q8ZhjrjshgJG3vwT5DSnfLk1keG56Gjdp3Dz7Vp7cQk=; b=rWgQo5fZzNizVXwfGfiNYrTTXrqBMlwt+Zwg5/DJ9vLIh1B8AUPHxgXr8r4gCFm5PS Y/2eEVdH8DX24vdDKbdvLE10mnjzrUA8VNTyCOu4MBivmmjPo1b2eRdMrOc+veL0zmzQ Uc5sJ6cCl3eGtFdVhu9q62csDU8aLND8rSAQg++ahIBITz+qNihru8+ed7w2bKLJSfw8 zxEwdSX8yjOi4oFtjzee51UCPDeYsFX7cndoV9TOhzCuHdFHtQuTro4qKuIgWpzh3gXW 4x4sUq6EP2lXP5YkToqvH2JfYXBIEfkNJhyC/joDFmh6DbXQRSEd5iYnxI2TxXuJ9+mJ WeRA== X-Gm-Message-State: AMCzsaWpTikleKgmCDryVDoyIw9iLPZljGz2eHfQ8AtV4JdfrdMe2F/9 7NcruOVWBXlhPzHuAuMKs+OAh1CYn3E= X-Google-Smtp-Source: AOwi7QC8TA4sQJltekrhpxg3cj1Twkcwi51Lq/M1LhNm70oy61NMqwPmBuVH0YiraQF2iitdLA7Sjg== X-Received: by 10.25.195.88 with SMTP id t85mr619769lff.214.1507637855982; Tue, 10 Oct 2017 05:17:35 -0700 (PDT) Received: from tdu.semihalf.local (31-172-191-173.noc.fibertech.net.pl. [31.172.191.173]) by smtp.gmail.com with ESMTPSA id e13sm1677728ljb.93.2017.10.10.05.17.34 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Tue, 10 Oct 2017 05:17:35 -0700 (PDT) From: Tomasz Duszynski To: dev@dpdk.org Cc: mw@semihalf.com, dima@marvell.com, nsamsono@marvell.com, Jianbo.liu@arm.org, Tomasz Duszynski , Jacek Siuda Date: Tue, 10 Oct 2017 14:17:20 +0200 Message-Id: <1507637842-4417-3-git-send-email-tdu@semihalf.com> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1507637842-4417-1-git-send-email-tdu@semihalf.com> References: <1507408106-11292-1-git-send-email-tdu@semihalf.com> <1507637842-4417-1-git-send-email-tdu@semihalf.com> Subject: [dpdk-dev] [PATCH v4 2/4] doc: add mrvl crypto pmd documentation X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 10 Oct 2017 12:17:37 -0000 Add documentation for the MRVL CRYPTO PMD driver. Signed-off-by: Jacek Siuda Signed-off-by: Tomasz Duszynski --- v4: * Updated documentation. v3: * Updated documentation. doc/guides/cryptodevs/features/mrvl.ini | 42 +++++++ doc/guides/cryptodevs/index.rst | 1 + doc/guides/cryptodevs/mrvl.rst | 205 ++++++++++++++++++++++++++++++++ 3 files changed, 248 insertions(+) create mode 100644 doc/guides/cryptodevs/features/mrvl.ini create mode 100644 doc/guides/cryptodevs/mrvl.rst diff --git a/doc/guides/cryptodevs/features/mrvl.ini b/doc/guides/cryptodevs/features/mrvl.ini new file mode 100644 index 0000000..6d2fe6a --- /dev/null +++ b/doc/guides/cryptodevs/features/mrvl.ini @@ -0,0 +1,42 @@ +; Supported features of the 'mrvl' crypto driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Symmetric crypto = Y +Sym operation chaining = Y + +; +; Supported crypto algorithms of a default crypto driver. +; +[Cipher] +AES CBC (128) = Y +AES CBC (192) = Y +AES CBC (256) = Y +AES CTR (128) = Y +AES CTR (192) = Y +AES CTR (256) = Y +3DES CBC = Y +3DES CTR = Y + +; +; Supported authentication algorithms of a default crypto driver. +; +[Auth] +MD5 = Y +MD5 HMAC = Y +SHA1 = Y +SHA1 HMAC = Y +SHA256 = Y +SHA256 HMAC = Y +SHA384 = Y +SHA384 HMAC = Y +SHA512 = Y +SHA512 HMAC = Y +AES GMAC = Y + +; +; Supported AEAD algorithms of a default crypto driver. +; +[AEAD] +AES GCM (128) = Y diff --git a/doc/guides/cryptodevs/index.rst b/doc/guides/cryptodevs/index.rst index 3a39a2d..6d4e15b 100644 --- a/doc/guides/cryptodevs/index.rst +++ b/doc/guides/cryptodevs/index.rst @@ -43,6 +43,7 @@ Crypto Device Drivers dpaa_sec kasumi openssl + mrvl null scheduler snow3g diff --git a/doc/guides/cryptodevs/mrvl.rst b/doc/guides/cryptodevs/mrvl.rst new file mode 100644 index 0000000..8c941f9 --- /dev/null +++ b/doc/guides/cryptodevs/mrvl.rst @@ -0,0 +1,205 @@ +.. BSD LICENSE + Copyright(c) 2017 Semihalf. All rights reserved. + All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + + * Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + * Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in + the documentation and/or other materials provided with the + distribution. + * Neither the name of Semihalf nor the names of its + contributors may be used to endorse or promote products derived + from this software without specific prior written permission. + + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +MRVL Crypto Poll Mode Driver +============================ + +The MRVL CRYPTO PMD (**librte_crypto_mrvl_pmd**) provides poll mode crypto driver +support by utilizing MUSDK library, which provides cryptographic operations +acceleration by using Security Acceleration Engine (EIP197) directly from +user-space with minimum overhead and high performance. + +Features +-------- + +MRVL CRYPTO PMD has support for: + +* Symmetric crypto +* Sym operation chaining +* AES CBC (128) +* AES CBC (192) +* AES CBC (256) +* AES CTR (128) +* AES CTR (192) +* AES CTR (256) +* 3DES CBC +* 3DES CTR +* MD5 +* MD5 HMAC +* SHA1 +* SHA1 HMAC +* SHA256 +* SHA256 HMAC +* SHA384 +* SHA384 HMAC +* SHA512 +* SHA512 HMAC +* AES GCM (128) + +Limitations +----------- + +* Hardware only supports scenarios where ICV (digest buffer) is placed just + after the authenticated data. Other placement will result in error. + +* Before running crypto test suite it is advised to increase limit of + opened files: + + .. code-block:: console + + ulimit -n 20000 + +Installation +------------ + +MRVL CRYPTO PMD driver compilation is disabled by default due to external dependencies. +Currently there are two driver specific compilation options in +``config/common_base`` available: + +- ``CONFIG_RTE_LIBRTE_MRVL_CRYPTO`` (default ``n``) + + Toggle compilation of the librte_pmd_mrvl driver. + +- ``CONFIG_RTE_LIBRTE_MRVL_CRYPTO_DEBUG`` (default ``n``) + + Toggle display of debugging messages. + +During compilation external MUSDK library, which provides direct access +to Marvell's EIP197 cryptographic engine, is necessary. Library sources are +available `here `__. + +Alternatively, prebuilt library can be downloaded from +`Marvell Extranet `_. Once approval has been +granted, library can be found by typing ``musdk`` in the search box. + +For MUSDK library build instructions please refer to ``doc/musdk_get_started.txt`` +in library sources directory. + +MUSDK requires out of tree kernel modules to work. Kernel tree needed to build +them is available +`here `__. + +Initialization +-------------- + +After successfully building MRVL CRYPTO PMD, the following modules need to be +loaded: + +.. code-block:: console + + insmod musdk_uio.ko + insmod mvpp2x_sysfs.ko + insmod mv_pp_uio.ko + insmod mv_sam_uio.ko + insmod crypto_safexcel.ko + +- `musdk_uio.ko`, `mv_pp2_uio.ko` and `mv_sam_uio.ko` are distributed together with MUSDK library. +- `crypto_safexcel.ko` is an in-kernel module. +- `mvpp2x_sysfs.ko` can be build from sources available `here `__. + +The following parameters (all optional) are exported by the driver: + +* max_nb_queue_pairs: maximum number of queue pairs in the device (8 by default). +* max_nb_sessions: maximum number of sessions that can be created (2048 by default). +* socket_id: socket on which to allocate the device resources on. + +l2fwd-crypto example application can be used to verify MRVL CRYPTO PMD +operation: + +.. code-block:: console + + ./l2fwd-crypto --vdev=net_mrvl,iface=eth0 --vdev=crypto_mrvl -- \ + --cipher_op ENCRYPT --cipher_algo aes-cbc \ + --cipher_key 00:01:02:03:04:05:06:07:08:09:0a:0b:0c:0d:0e:0f \ + --auth_op GENERATE --auth_algo sha1-hmac \ + --auth_key 10:11:12:13:14:15:16:17:18:19:1a:1b:1c:1d:1e:1f + +Example output: + +.. code-block:: console + + [...] + AAD: at [0x7f253ceb80], len= + P ID 0 configuration ---- + Port mode : KR + MAC status : disabled + Link status : link up + Port speed : 10G + Port duplex : full + Port: Egress enable tx_port_num=16 qmap=0x1 + PORT: Port0 - link + P ID 0 configuration ---- + Port mode : KR + MAC status : disabled + Link status : link down + Port speed : 10G + Port duplex : full + Port: Egress enable tx_port_num=16 qmap=0x1 + Port 0, MAC address: 00:50:43:02:21:20 + + + Checking link statusdone + Port 0 Link Up - speed 0 Mbps - full-duplex + Lcore 0: RX port 0 + Allocated session pool on socket 0 + eip197: 0:0 registers: paddr: 0xf2880000, vaddr: 0x0x7f56a80000 + DMA buffer (131136 bytes) for CDR #0 allocated: paddr = 0xb0585e00, vaddr = 0x7f09384e00 + DMA buffer (131136 bytes) for RDR #0 allocated: paddr = 0xb05a5f00, vaddr = 0x7f093a4f00 + DMA buffers allocated for 2049 operations. Tokens - 256 bytes + Lcore 0: cryptodev 0 + L2FWD: lcore 1 has nothing to do + L2FWD: lcore 2 has nothing to do + L2FWD: lcore 3 has nothing to do + L2FWD: entering main loop on lcore 0 + L2FWD: -- lcoreid=0 portid=0 + L2FWD: -- lcoreid=0 cryptoid=0 + Options:- + nportmask: ffffffff + ports per lcore: 1 + refresh period : 10000 + single lcore mode: disabled + stats_printing: enabled + sessionless crypto: disabled + + Crypto chain: Input --> Encrypt --> Auth generate --> Output + + ---- Cipher information --- + Algorithm: aes-cbc + Cipher key: at [0x7f56db4e80], len=16 + 00000000: 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F | ................ + IV: at [0x7f56db4b80], len=16 + 00000000: 20 F0 63 0E 45 EB 2D 84 72 D4 13 6E 36 B5 AF FE | .c.E.-.r..n6... + + ---- Authentication information --- + Algorithm: sha1-hmac + Auth key: at [0x7f56db4d80], len=16 + 00000000: 10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F | ................ + IV: at [0x7f56db4a80], len=0 + AAD: at [0x7f253ceb80], len= -- 2.7.4