X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Ftools%2Fcryptoperf.rst;h=86c5a8aa164715260fbe1abe5fae582bc72de713;hb=c83456cdd7953e0659d13dcf0affc39bf76ef460;hp=6832312d6af5d7b615d41cb88c9be6f6a50e57ba;hpb=c6baca7adc94a204e4587761b3891916a4882fed;p=dpdk.git diff --git a/doc/guides/tools/cryptoperf.rst b/doc/guides/tools/cryptoperf.rst index 6832312d6a..86c5a8aa16 100644 --- a/doc/guides/tools/cryptoperf.rst +++ b/doc/guides/tools/cryptoperf.rst @@ -1,32 +1,5 @@ -.. BSD LICENSE - Copyright(c) 2016 Intel Corporation. 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 Intel Corporation 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. +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2016 Intel Corporation. dpdk-test-crypto-perf Application ================================= @@ -41,22 +14,25 @@ chain mode have to be specified in the command line as application parameters. These parameters are checked using device capabilities structure. -Compiling the Application -------------------------- - -**Step 1: PMD setting** - -The ``dpdk-test-crypto-perf`` tool depends on crypto device drivers PMD which -are disabled by default in the build configuration file ``common_base``. -The crypto device drivers PMD which should be tested can be enabled by setting:: - - CONFIG_RTE_LIBRTE_PMD_=y +Limitations +----------- +On hardware devices the cycle-count doesn't always represent the actual offload +cost. The cycle-count only represents the offload cost when the hardware +accelerator is not fully loaded, when loaded the cpu cycles freed up by the +offload are still consumed by the test tool and included in the cycle-count. +These cycles are consumed by retries and inefficient API calls enqueuing and +dequeuing smaller bursts than specified by the cmdline parameter. This results +in a larger cycle-count measurement and should not be interpreted as an offload +cost measurement. Using "pmd-cyclecount" mode will give a better idea of +actual costs of hardware acceleration. -Setting example for open ssl PMD:: +On hardware devices the throughput measurement is not necessarily the maximum +possible for the device, e.g. it may be necessary to use multiple cores to keep +the hardware accelerator fully loaded and so measure maximum throughput. - CONFIG_RTE_LIBRTE_PMD_OPENSSL=y -**Step 2: Linearization setting** +Linearization setting +--------------------- It is possible linearized input segmented packets just before crypto operation for devices which doesn't support scatter-gather, and allows to measure @@ -67,16 +43,6 @@ To set on the linearization options add below definition to the #define CPERF_LINEARIZATION_ENABLE -**Step 3: Build the application** - -Execute the ``dpdk-setup.sh`` script to build the DPDK library together with the -``dpdk-test-crypto-perf`` applcation. - -Initially, the user must select a DPDK target to choose the correct target type -and compiler options to use when building the libraries. -The user must have all libraries, modules, updates and compilers installed -in the system prior to this, -as described in the earlier chapters in this Getting Started Guide. Running the Application ----------------------- @@ -91,25 +57,26 @@ EAL Options ~~~~~~~~~~~ The following are the EAL command-line options that can be used in conjunction -with the ``dpdk-test-crypto-perf`` applcation. +with the ``dpdk-test-crypto-perf`` application. See the DPDK Getting Started Guides for more information on these options. -* ``-c `` +* ``-c `` or ``-l `` - Set the hexadecimal bitmask of the cores to run on. + Set the hexadecimal bitmask of the cores to run on. The corelist is a + list cores to use. -* ``-w `` +* ``-a `` - Add a PCI device in white list. + Add a PCI device in allow list. * ``--vdev `` Add a virtual device. -Appication Options -~~~~~~~~~~~~~~~~~~ +Application Options +~~~~~~~~~~~~~~~~~~~ -The following are the appication command-line options: +The following are the application command-line options: * ``--ptest type`` @@ -117,6 +84,8 @@ The following are the appication command-line options: throughput latency + verify + pmd-cyclecount * ``--silent`` @@ -134,13 +103,44 @@ The following are the appication command-line options: Set the number of packets per burst. + This can be set as: + * Single value (i.e. ``--burst-sz 16``) + * Range of values, using the following structure ``min:inc:max``, + where ``min`` is minimum size, ``inc`` is the increment size and ``max`` + is the maximum size (i.e. ``--burst-sz 16:2:32``) + * List of values, up to 32 values, separated in commas (i.e. ``--burst-sz 16,24,32``) + * ``--buffer-sz `` Set the size of single packet (plaintext or ciphertext in it). -* ``--segments-nb `` + This can be set as: + * Single value (i.e. ``--buffer-sz 16``) + * Range of values, using the following structure ``min:inc:max``, + where ``min`` is minimum size, ``inc`` is the increment size and ``max`` + is the maximum size (i.e. ``--buffer-sz 16:2:32``) + * List of values, up to 32 values, separated in commas (i.e. ``--buffer-sz 32,64,128``) + +* ``--imix `` + + Set the distribution of packet sizes. + + A list of weights must be passed, containing the same number of items than buffer-sz, + so each item in this list will be the weight of the packet size on the same position + in the buffer-sz parameter (a list have to be passed in that parameter). + + Example: - Set the number of segments per packet. + To test a distribution of 20% packets of 64 bytes, 40% packets of 100 bytes and 40% packets + of 256 bytes, the command line would be: ``--buffer-sz 64,100,256 --imix 20,40,40``. + Note that the weights do not have to be percentages, so using ``--imix 1,2,2`` would result + in the same distribution + +* ``--segment-sz `` + + Set the size of the segment to use, for Scatter Gather List testing. + By default, it is set to the size of the maximum buffer size, including the digest size, + so a single segment is created. * ``--devtype `` @@ -154,6 +154,11 @@ The following are the appication command-line options: crypto_snow3g crypto_kasumi crypto_zuc + crypto_dpaa_sec + crypto_dpaa2_sec + crypto_armv8 + crypto_scheduler + crypto_mvsam * ``--optype `` @@ -164,6 +169,10 @@ The following are the appication command-line options: cipher-then-auth auth-then-cipher aead + pdcp + docsis + + For GCM/CCM algorithms you should use aead flag. * ``--sessionless`` @@ -173,11 +182,6 @@ The following are the appication command-line options: Enable out-of-place crypto operations mode. -* ``--verify`` - - Enable verify that all crypto operations were successful. - The verification is done after the performance test. - * ``--test-file `` Set test vector file path. See the Test Vector File chapter. @@ -194,10 +198,8 @@ The following are the appication command-line options: 3des-ecb 3des-ctr aes-cbc - aes-ccm aes-ctr aes-ecb - aes-gcm aes-f8 aes-xts arc4 @@ -228,9 +230,7 @@ The following are the appication command-line options: 3des-cbc aes-cbc-mac - aes-ccm aes-cmac - aes-gcm aes-gmac aes-xcbc-mac md5 @@ -261,31 +261,86 @@ The following are the appication command-line options: Set the size of authentication key. -* ``--auth-digest-sz `` +* ``--auth-iv-sz `` + + Set the size of auth iv. + +* ``--aead-algo `` + + Set AEAD algorithm name, where ``name`` is one + of the following:: + + aes-ccm + aes-gcm + +* ``--aead-op `` + + Set AEAD operation mode, where ``mode`` is one of + the following:: + + encrypt + decrypt + +* ``--aead-key-sz `` + + Set the size of AEAD key. + +* ``--aead-iv-sz `` + + Set the size of AEAD iv. - Set the size of authentication digest. +* ``--aead-aad-sz `` -* ``--auth-aad-sz `` + Set the size of AEAD aad. - Set the size of authentication aad. +* ``--digest-sz `` + + Set the size of digest. + +* ``--desc-nb `` + + Set number of descriptors for each crypto device. + +* ``--pmd-cyclecount-delay-ms `` + + Add a delay (in milliseconds) between enqueue and dequeue in + pmd-cyclecount benchmarking mode (useful when benchmarking + hardware acceleration). * ``--csv-friendly`` Enable test result output CSV friendly rather than human friendly. +* ``--pdcp-sn-sz `` + + Set PDCP sequence number size(n) in bits. Valid values of n will + be 5/7/12/15/18. + +* ``--pdcp-domain `` + + Set PDCP domain to specify Control/user plane. + +* ``--docsis-hdr-sz `` + + Set DOCSIS header size(n) in bytes. + +* ``--pdcp-ses-hfn-en`` + + Enable fixed session based HFN instead of per packet HFN. + Test Vector File ~~~~~~~~~~~~~~~~ The test vector file is a text file contain information about test vectors. The file is made of the sections. The first section doesn't have header. It contain global information used in each test variant vectors - -typicaly information about plaintext, ciphertext, cipher key, aut key, +typically information about plaintext, ciphertext, cipher key, auth key, initial vector. All other sections begin header. -The sections contain particular information typicaly digest. +The sections contain particular information typically digest. **Format of the file:** -Each line beginig with sign '#' contain comment and it is ignored by parser:: +Each line beginning with sign '#' contain comment and it is ignored by parser:: # @@ -293,16 +348,16 @@ Header line is just name in square bracket:: [
] -Data line contain information tocken then sign '=' and +Data line contain information token then sign '=' and a string of bytes in C byte array format:: - = + = -**Tockens list:** +**Tokens list:** * ``plaintext`` - Original plaintext to be crypted. + Original plaintext to be encrypted. * ``ciphertext`` @@ -316,9 +371,13 @@ a string of bytes in C byte array format:: Key used in auth operation. -* ``iv`` +* ``cipher_iv`` - Initial vector. + Cipher Initial Vector. + +* ``auth_iv`` + + Auth Initial Vector. * ``aad`` @@ -333,34 +392,33 @@ Examples Call application for performance throughput test of single Aesni MB PMD for cipher encryption aes-cbc and auth generation sha1-hmac, -one milion operations, burst size 32, packet size 64:: +one million operations, burst size 32, packet size 64:: - dpdk-test-crypto-perf -c 0xc0 --vdev crypto_aesni_mb_pmd -w 0000:00:00.0 -- + dpdk-test-crypto-perf -l 6-7 --vdev crypto_aesni_mb -a 0000:00:00.0 -- --ptest throughput --devtype crypto_aesni_mb --optype cipher-then-auth --cipher-algo aes-cbc --cipher-op encrypt --cipher-key-sz 16 --auth-algo - sha1-hmac --auth-op generate --auth-key-sz 64 --auth-digest-sz 12 + sha1-hmac --auth-op generate --auth-key-sz 64 --digest-sz 12 --total-ops 10000000 --burst-sz 32 --buffer-sz 64 Call application for performance latency test of two Aesni MB PMD executed on two cores for cipher encryption aes-cbc, ten operations in silent mode:: - dpdk-test-crypto-perf -c 0xf0 --vdev crypto_aesni_mb_pmd1 - --vdev crypto_aesni_mb_pmd2 -w 0000:00:00.0 -- --devtype crypto_aesni_mb + dpdk-test-crypto-perf -l 4-7 --vdev crypto_aesni_mb1 + --vdev crypto_aesni_mb2 -a 0000:00:00.0 -- --devtype crypto_aesni_mb --cipher-algo aes-cbc --cipher-key-sz 16 --cipher-iv-sz 16 --cipher-op encrypt --optype cipher-only --silent --ptest latency --total-ops 10 -Call application for performance latency test of single open ssl PMD +Call application for verification test of single open ssl PMD for cipher encryption aes-gcm and auth generation aes-gcm,ten operations in silent mode, test vector provide in file "test_aes_gcm.data" with packet verification:: - dpdk-test-crypto-perf -c 0xf0 --vdev crypto_openssl -w 0000:00:00.0 -- - --devtype crypto_openssl --cipher-algo aes-gcm --cipher-key-sz 16 - --cipher-iv-sz 16 --cipher-op encrypt --auth-algo aes-gcm --auth-key-sz 16 - --auth-digest-sz 16 --auth-aad-sz 16 --auth-op generate --optype aead - --silent --ptest latency --total-ops 10 - --test-file test_aes_gcm.data --verify + dpdk-test-crypto-perf -l 4-7 --vdev crypto_openssl -a 0000:00:00.0 -- + --devtype crypto_openssl --aead-algo aes-gcm --aead-key-sz 16 + --aead-iv-sz 16 --aead-op encrypt --aead-aad-sz 16 --digest-sz 16 + --optype aead --silent --ptest verify --total-ops 10 + --test-file test_aes_gcm.data Test vector file for cipher algorithm aes cbc 256 with authorization sha:: @@ -383,7 +441,7 @@ Test vector file for cipher algorithm aes cbc 256 with authorization sha:: 0xf5, 0x0c, 0xe7, 0xa2, 0xa6, 0x23, 0xd5, 0x3d, 0x95, 0xd8, 0xcd, 0x86, 0x79, 0xf5, 0x01, 0x47, 0x4f, 0xf9, 0x1d, 0x9d, 0x36, 0xf7, 0x68, 0x1a, 0x64, 0x44, 0x58, 0x5d, 0xe5, 0x81, 0x15, 0x2a, 0x41, 0xe4, 0x0e, 0xaa, 0x1f, 0x04, 0x21, 0xff, 0x2c, 0xf3, 0x73, 0x2b, 0x48, 0x1e, 0xd2, 0xf7 - iv = + cipher_iv = 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F # Section sha 1 hmac buff 32 [sha1_hmac_buff_32] @@ -395,3 +453,146 @@ Test vector file for cipher algorithm aes cbc 256 with authorization sha:: digest = 0x1C, 0xB2, 0x3D, 0xD1, 0xF9, 0xC7, 0x6C, 0x49, 0x2E, 0xDA, 0x94, 0x8B, 0xF1, 0xCF, 0x96, 0x43, 0x67, 0x50, 0x39, 0x76, 0xB5, 0xA1, 0xCE, 0xA1, 0xD7, 0x77, 0x10, 0x07, 0x43, 0x37, 0x05, 0xB4 + + +Graph Crypto Perf Results +------------------------- + +The ``dpdk-graph-crypto-perf.py`` tool is a simple script to automate +running crypto performance tests, and graphing the results. +It can be found in the ``app/test-crypto-perf/`` directory. +The output graphs include various grouped barcharts for throughput +tests, and histogram and boxplot graphs for latency tests. +These are output to PDF files, with one PDF per test suite graph type. + + +Dependencies +~~~~~~~~~~~~ + +The following python modules must be installed to run the script: + +* img2pdf + +* plotly + +* pandas + +* glob + + +Test Configuration +~~~~~~~~~~~~~~~~~~ + +The test cases run by the script are defined by a JSON config file. +Some config files can be found in ``app/test-crypto-perf/configs/``, +or the user may create a new one following the same format as the config files provided. + +An example of this format is shown below for one test suite in the ``crypto-perf-aesni-mb.json`` file. +This shows the required default config for the test suite, and one test case. +The test case has additional app config that will be combined with +the default config when running the test case. + +.. code-block:: c + + "throughput": { + "default": { + "eal": { + "l": "1,2", + "vdev": "crypto_aesni_mb" + }, + "app": { + "csv-friendly": true, + "buffer-sz": "64,128,256,512,768,1024,1408,2048", + "burst-sz": "1,4,8,16,32", + "ptest": "throughput", + "devtype": "crypto_aesni_mb" + } + }, + "AES-CBC-128 SHA1-HMAC auth-then-cipher decrypt": { + "cipher-algo": "aes-cbc", + "cipher-key-sz": "16", + "auth-algo": "sha1-hmac", + "optype": "auth-then-cipher", + "cipher-op": "decrypt" + } + } + +.. note:: + The specific test cases only allow modification of app parameters, + and not EAL parameters. + The default case is required for each test suite in the config file, + to specify EAL parameters. + +Currently, crypto_qat, crypto_aesni_mb, and crypto_aesni_gcm devices for +both throughput and latency ptests are supported. + + +Usage +~~~~~ + +.. code-block:: console + + ./dpdk-graph-crypto-perf + +The ``config_file`` positional argument is required to run the script. +This points to a valid JSON config file containing test suites. + +.. code-block:: console + + ./dpdk-graph-crypto-perf configs/crypto-perf-aesni-mb.json + +The following are the application optional command-line options: + +* ``-h, --help`` + + Display usage information and quit + + +* ``-f , --file-path `` + + Provide path to ``dpdk-test-crypto-perf`` application. + The script uses the installed app by default. + + .. code-block:: console + + ./dpdk-graph-crypto-perf -f /app/dpdk-test-crypto-perf + + +* ``-t , --test-suites `` + + Specify test suites to run. All test suites are run by default. + + To run crypto-perf-qat latency test suite only: + + .. code-block:: console + + ./dpdk-graph-crypto-perf configs/crypto-perf-qat -t latency + + To run both crypto-perf-aesni-mb throughput and latency test suites + + .. code-block:: console + + ./dpdk-graph-crypto-perf configs/crypto-perf-aesni-mb -t throughput latency + + +* ``-o , --output-path `` + + Specify directory to use for output files. + The default is to use the script's directory. + + .. code-block:: console + + ./dpdk-graph-crypto-perf -o + + +* ``-v, --verbose`` + + Enable verbose output. This displays ``dpdk-test-crypto-perf`` app output in real-time. + + .. code-block:: console + + ./dpdk-graph-crypto-perf -v + + .. warning:: + Latency performance tests have a large amount of output. + It is not recommended to use the verbose option for latency tests.