From 807418f263a48855fcc64455afda1b7d4be03e47 Mon Sep 17 00:00:00 2001 From: Pablo de Lara Date: Thu, 23 Mar 2017 11:38:55 +0000 Subject: [PATCH] doc: reformat crypto drivers overview Follow the approach in the network devices overview, for the feature matrix, so it improves readibility and maintainability. Signed-off-by: Pablo de Lara Acked-by: John McNamara --- .gitignore | 4 + doc/guides/conf.py | 58 ++-- doc/guides/cryptodevs/features/aesni_gcm.ini | 27 ++ doc/guides/cryptodevs/features/aesni_mb.ini | 41 +++ doc/guides/cryptodevs/features/armv8.ini | 28 ++ doc/guides/cryptodevs/features/default.ini | 70 +++++ doc/guides/cryptodevs/features/kasumi.ini | 24 ++ doc/guides/cryptodevs/features/null.ini | 25 ++ doc/guides/cryptodevs/features/openssl.ini | 47 +++ doc/guides/cryptodevs/features/qat.ini | 50 ++++ doc/guides/cryptodevs/features/snow3g.ini | 24 ++ doc/guides/cryptodevs/features/zuc.ini | 24 ++ doc/guides/cryptodevs/overview.rst | 285 +++++++++++++++---- 13 files changed, 631 insertions(+), 76 deletions(-) create mode 100644 doc/guides/cryptodevs/features/aesni_gcm.ini create mode 100644 doc/guides/cryptodevs/features/aesni_mb.ini create mode 100644 doc/guides/cryptodevs/features/armv8.ini create mode 100644 doc/guides/cryptodevs/features/default.ini create mode 100644 doc/guides/cryptodevs/features/kasumi.ini create mode 100644 doc/guides/cryptodevs/features/null.ini create mode 100644 doc/guides/cryptodevs/features/openssl.ini create mode 100644 doc/guides/cryptodevs/features/qat.ini create mode 100644 doc/guides/cryptodevs/features/snow3g.ini create mode 100644 doc/guides/cryptodevs/features/zuc.ini diff --git a/.gitignore b/.gitignore index a722abea21..c733967a85 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,5 @@ doc/guides/nics/overview_table.txt +doc/guides/cryptodevs/overview_feature_table.txt +doc/guides/cryptodevs/overview_cipher_table.txt +doc/guides/cryptodevs/overview_auth_table.txt +doc/guides/cryptodevs/overview_aead_table.txt diff --git a/doc/guides/conf.py b/doc/guides/conf.py index 4cac26d5f0..01ce16d2e9 100644 --- a/doc/guides/conf.py +++ b/doc/guides/conf.py @@ -178,25 +178,24 @@ def process_numref(app, doctree, from_docname): node.replace_self(newnode) -def generate_nic_overview_table(output_filename): +def generate_overview_table(output_filename, section, table_name, title): """ - Function to generate the NIC Overview Table from the ini files that define - the features for each NIC. + Function to generate the Overview Table from the ini files that define + the features for each driver. The default features for the table and their order is defined by the 'default.ini' file. """ - # Default worning string. - warning = 'Warning generate_nic_overview_table()' + # Default warning string. + warning = 'Warning generate_overview_table()' # Get the default features and order from the 'default.ini' file. ini_path = path_join(dirname(output_filename), 'features') config = configparser.ConfigParser() config.optionxform = str config.read(path_join(ini_path, 'default.ini')) - default_section = 'Features' - default_features = config.items(default_section) + default_features = config.items(section) # Create a dict of the valid features to validate the other ini files. valid_features = {} @@ -206,7 +205,7 @@ def generate_nic_overview_table(output_filename): valid_features[key] = ' ' max_feature_length = max(max_feature_length, len(key)) - # Get a list of NIC ini files, excluding 'default.ini'. + # Get a list of driver ini files, excluding 'default.ini'. ini_files = [basename(file) for file in listdir(ini_path) if file.endswith('.ini') and file != 'default.ini'] ini_files.sort() @@ -226,7 +225,7 @@ def generate_nic_overview_table(output_filename): header_names.append(name) - # Create a dict of the defined features for each NIC from the ini files. + # Create a dict of the defined features for each driver from the ini files. ini_data = {} for ini_filename in ini_files: config = configparser.ConfigParser() @@ -237,14 +236,14 @@ def generate_nic_overview_table(output_filename): ini_data[ini_filename] = valid_features.copy() # Check for a valid ini section. - if not config.has_section(default_section): + if not config.has_section(section): print("{}: File '{}' has no [{}] secton".format(warning, ini_filename, - default_section)) + section)) continue # Check for valid features names. - for name, value in config.items(default_section): + for name, value in config.items(section): if name not in valid_features: print("{}: Unknown feature '{}' in '{}'".format(warning, name, @@ -255,18 +254,18 @@ def generate_nic_overview_table(output_filename): # Get the first letter only. ini_data[ini_filename][name] = value[0] - # Print out the RST NIC Overview table from the ini file data. + # Print out the RST Driver Overview table from the ini file data. outfile = open(output_filename, 'w') num_cols = len(header_names) - print('.. table:: Features availability in networking drivers\n', + print('.. table:: ' + table_name + '\n', file=outfile) - print_table_header(outfile, num_cols, header_names) + print_table_header(outfile, num_cols, header_names, title) print_table_body(outfile, num_cols, ini_files, ini_data, default_features) -def print_table_header(outfile, num_cols, header_names): +def print_table_header(outfile, num_cols, header_names, title): """ Print the RST table header. The header names are vertical. """ print_table_divider(outfile, num_cols) @@ -274,7 +273,7 @@ def print_table_header(outfile, num_cols, header_names): for name in header_names: line += ' ' + name[0] - print_table_row(outfile, 'Feature', line) + print_table_row(outfile, title, line) for i in range(1, 10): line = '' @@ -319,7 +318,30 @@ def print_table_divider(outfile, num_cols): def setup(app): table_file = dirname(__file__) + '/nics/overview_table.txt' - generate_nic_overview_table(table_file) + generate_overview_table(table_file, + 'Features', + 'Features availability in networking drivers', + 'Feature') + table_file = dirname(__file__) + '/cryptodevs/overview_feature_table.txt' + generate_overview_table(table_file, + 'Features', + 'Features availability in crypto drivers', + 'Feature') + table_file = dirname(__file__) + '/cryptodevs/overview_cipher_table.txt' + generate_overview_table(table_file, + 'Cipher', + 'Cipher algorithms in crypto drivers', + 'Cipher algorithm') + table_file = dirname(__file__) + '/cryptodevs/overview_auth_table.txt' + generate_overview_table(table_file, + 'Auth', + 'Authentication algorithms in crypto drivers', + 'Authentication algorithm') + table_file = dirname(__file__) + '/cryptodevs/overview_aead_table.txt' + generate_overview_table(table_file, + 'AEAD', + 'AEAD algorithms in crypto drivers', + 'AEAD algorithm') if LooseVersion(sphinx_version) < LooseVersion('1.3.1'): print('Upgrade sphinx to version >= 1.3.1 for ' diff --git a/doc/guides/cryptodevs/features/aesni_gcm.ini b/doc/guides/cryptodevs/features/aesni_gcm.ini new file mode 100644 index 0000000000..5d9e119db2 --- /dev/null +++ b/doc/guides/cryptodevs/features/aesni_gcm.ini @@ -0,0 +1,27 @@ +; +; Supported features of the 'aesni_gcm' crypto driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Symmetric crypto = Y +Sym operation chaining = Y +CPU AESNI = Y + +; +; Supported crypto algorithms of the 'aesni_gcm' crypto driver. +; +[Cipher] + +; +; Supported authentication algorithms of the 'aesni_gcm' crypto driver. +; +[Auth] +AES GMAC = Y + +; +; Supported AEAD algorithms of the 'aesni_gcm' crypto driver. +; +[AEAD] +AES GCM (128) = Y +AES GCM (256) = Y diff --git a/doc/guides/cryptodevs/features/aesni_mb.ini b/doc/guides/cryptodevs/features/aesni_mb.ini new file mode 100644 index 0000000000..0bc202c932 --- /dev/null +++ b/doc/guides/cryptodevs/features/aesni_mb.ini @@ -0,0 +1,41 @@ +; +; Supported features of the 'aesni_mb' crypto driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Symmetric crypto = Y +Sym operation chaining = Y +CPU SSE = Y +CPU AVX = Y +CPU AVX2 = Y +CPU AVX512 = Y +CPU AESNI = Y + +; +; Supported crypto algorithms of the 'aesni_mb' 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 + +; +; Supported authentication algorithms of the 'aesni_mb' crypto driver. +; +[Auth] +MD5 HMAC = Y +SHA1 HMAC = Y +SHA224 HMAC = Y +SHA256 HMAC = Y +SHA384 HMAC = Y +SHA512 HMAC = Y +AES XCBC MAC = Y + +; +; Supported AEAD algorithms of the 'aesni_mb' crypto driver. +; +[AEAD] diff --git a/doc/guides/cryptodevs/features/armv8.ini b/doc/guides/cryptodevs/features/armv8.ini new file mode 100644 index 0000000000..1e10477140 --- /dev/null +++ b/doc/guides/cryptodevs/features/armv8.ini @@ -0,0 +1,28 @@ +; +; Supported features of the 'armv8' crypto driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Symmetric crypto = Y +Sym operation chaining = Y +CPU NEON = Y +CPU ARM CE = Y + +; +; Supported crypto algorithms of the 'armv8' crypto driver. +; +[Cipher] +AES CBC (128) = Y + +; +; Supported authentication algorithms of the 'armv8' crypto driver. +; +[Auth] +SHA1 HMAC = Y +SHA256 HMAC = Y + +; +; Supported AEAD algorithms of the 'armv8' crypto driver. +; +[AEAD] diff --git a/doc/guides/cryptodevs/features/default.ini b/doc/guides/cryptodevs/features/default.ini new file mode 100644 index 0000000000..0926887bc7 --- /dev/null +++ b/doc/guides/cryptodevs/features/default.ini @@ -0,0 +1,70 @@ +; +; Features of a default crypto driver. +; +; This file defines the features that are valid for inclusion in +; the other driver files and also the order that they appear in +; the features table in the documentation. +; +[Features] +Symmetric crypto = +Asymmetric crypto = +Sym operation chaining = +HW Accelerated = +CPU SSE = +CPU AVX = +CPU AVX2 = +CPU AVX512 = +CPU AESNI = +CPU NEON = +CPU ARM CE = + +; +; Supported crypto algorithms of a default crypto driver. +; +[Cipher] +NULL = +AES CBC (128) = +AES CBC (192) = +AES CBC (256) = +AES CTR (128) = +AES CTR (192) = +AES CTR (256) = +AES DOCSIS BPI = +3DES CBC = +3DES CTR = +DES CBC = +DES DOCSIS BPI = +SNOW3G UEA2 = +KASUMI F8 = +ZUC EEA3 = + +; +; Supported authentication algorithms of a default crypto driver. +; +[Auth] +NULL = +MD5 = +MD5 HMAC = +SHA1 = +SHA1 HMAC = +SHA224 = +SHA224 HMAC = +SHA256 = +SHA256 HMAC = +SHA384 = +SHA384 HMAC = +SHA512 = +SHA512 HMAC = +AES XCBC MAC = +AES GMAC = +SNOW3G UIA2 = +KASUMI F9 = +ZUC EIA3 = + +; +; Supported AEAD algorithms of a default crypto driver. +; +[AEAD] +AES GCM (128) = +AES GCM (192) = +AES GCM (256) = diff --git a/doc/guides/cryptodevs/features/kasumi.ini b/doc/guides/cryptodevs/features/kasumi.ini new file mode 100644 index 0000000000..0e138f5a64 --- /dev/null +++ b/doc/guides/cryptodevs/features/kasumi.ini @@ -0,0 +1,24 @@ +; +; Supported features of the 'kasumi' 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 the 'kasumi' crypto driver. +; +[Cipher] +KASUMI F8 = Y +; +; Supported authentication algorithms of the 'kasumi' crypto driver. +; +[Auth] +KASUMI F9 = Y + +; +; Supported AEAD algorithms of the 'kasumi' crypto driver. +; +[AEAD] diff --git a/doc/guides/cryptodevs/features/null.ini b/doc/guides/cryptodevs/features/null.ini new file mode 100644 index 0000000000..523c453cb1 --- /dev/null +++ b/doc/guides/cryptodevs/features/null.ini @@ -0,0 +1,25 @@ +; +; Supported features of the 'null' 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 the 'null' crypto driver. +; +[Cipher] +NULL = Y + +; +; Supported authentication algorithms of the 'null' crypto driver. +; +[Auth] +NULL = Y + +; +; Supported AEAD algorithms of the 'null' crypto driver. +; +[AEAD] diff --git a/doc/guides/cryptodevs/features/openssl.ini b/doc/guides/cryptodevs/features/openssl.ini new file mode 100644 index 0000000000..189b71bb86 --- /dev/null +++ b/doc/guides/cryptodevs/features/openssl.ini @@ -0,0 +1,47 @@ +; +; Supported features of the 'openssl' 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 the 'openssl' 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 the 'openssl' crypto driver. +; +[Auth] +MD5 = Y +MD5 HMAC = Y +SHA1 = Y +SHA1 HMAC = Y +SHA224 = Y +SHA224 HMAC = Y +SHA256 = Y +SHA256 HMAC = Y +SHA384 = Y +SHA384 HMAC = Y +SHA512 = Y +SHA512 HMAC = Y +AES GMAC = Y + +; +; Supported AEAD algorithms of the 'openssl' crypto driver. +; +[AEAD] +AES GCM (128) = Y +AES GCM (192) = Y +AES GCM (256) = Y diff --git a/doc/guides/cryptodevs/features/qat.ini b/doc/guides/cryptodevs/features/qat.ini new file mode 100644 index 0000000000..a3a46eb011 --- /dev/null +++ b/doc/guides/cryptodevs/features/qat.ini @@ -0,0 +1,50 @@ +; +; Supported features of the 'qat' crypto driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Symmetric crypto = Y +Sym operation chaining = Y +HW Accelerated = Y + +; +; Supported crypto algorithms of the 'qat' crypto driver. +; +[Cipher] +NULL = Y +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 +DES CBC = Y +SNOW3G UEA2 = Y +KASUMI F8 = Y + +; +; Supported authentication algorithms of the 'qat' crypto driver. +; +[Auth] +NULL = Y +MD5 HMAC = Y +SHA1 HMAC = Y +SHA224 HMAC = Y +SHA256 HMAC = Y +SHA384 HMAC = Y +SHA512 HMAC = Y +AES GMAC = Y +SNOW3G UIA2 = Y +KASUMI F9 = Y +AES XCBC MAC = Y + +; +; Supported AEAD algorithms of the 'qat' crypto driver. +; +[AEAD] +AES GCM (128) = Y +AES GCM (192) = Y +AES GCM (256) = Y diff --git a/doc/guides/cryptodevs/features/snow3g.ini b/doc/guides/cryptodevs/features/snow3g.ini new file mode 100644 index 0000000000..277136177c --- /dev/null +++ b/doc/guides/cryptodevs/features/snow3g.ini @@ -0,0 +1,24 @@ +; +; Supported features of the 'snow3g' 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 the 'snow3g' crypto driver. +; +[Cipher] +SNOW3G UEA2 = Y +; +; Supported authentication algorithms of the 'snow3g' crypto driver. +; +[Auth] +SNOW3G UIA2 = Y + +; +; Supported AEAD algorithms of the 'snow3g' crypto driver. +; +[AEAD] diff --git a/doc/guides/cryptodevs/features/zuc.ini b/doc/guides/cryptodevs/features/zuc.ini new file mode 100644 index 0000000000..5bb02afd4e --- /dev/null +++ b/doc/guides/cryptodevs/features/zuc.ini @@ -0,0 +1,24 @@ +; +; Supported features of the 'zuc' 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 the 'zuc' crypto driver. +; +[Cipher] +ZUC EEA3 = Y +; +; Supported authentication algorithms of the 'zuc' crypto driver. +; +[Auth] +ZUC EIA3 = Y + +; +; Supported AEAD algorithms of the 'zuc' crypto driver. +; +[AEAD] diff --git a/doc/guides/cryptodevs/overview.rst b/doc/guides/cryptodevs/overview.rst index 4bbfadbecd..656cf18c9b 100644 --- a/doc/guides/cryptodevs/overview.rst +++ b/doc/guides/cryptodevs/overview.rst @@ -1,5 +1,5 @@ .. BSD LICENSE - Copyright(c) 2016 Intel Corporation. All rights reserved. + Copyright(c) 2016-2017 Intel Corporation. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions @@ -11,7 +11,7 @@ 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 + * Neither the name of 6WIND S.A. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. @@ -28,75 +28,244 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. Crypto Device Supported Functionality Matrices ----------------------------------------------- +============================================== Supported Feature Flags +----------------------- -.. csv-table:: - :header: "Feature Flags", "qat", "null", "aesni_mb", "aesni_gcm", "snow3g", "kasumi", "zuc", "armv8" - :stub-columns: 1 +.. _table_crypto_pmd_features: - "RTE_CRYPTODEV_FF_SYMMETRIC_CRYPTO",x,x,x,x,x,x,x,x - "RTE_CRYPTODEV_FF_ASYMMETRIC_CRYPTO",,,,,,,, - "RTE_CRYPTODEV_FF_SYM_OPERATION_CHAINING",x,x,x,x,x,x,x,x - "RTE_CRYPTODEV_FF_CPU_SSE",,,x,,x,x,, - "RTE_CRYPTODEV_FF_CPU_AVX",,,x,,x,x,, - "RTE_CRYPTODEV_FF_CPU_AVX2",,,x,,,,, - "RTE_CRYPTODEV_FF_CPU_AVX512",,,x,,,,, - "RTE_CRYPTODEV_FF_CPU_AESNI",,,x,x,,,, - "RTE_CRYPTODEV_FF_HW_ACCELERATED",x,,,,,,, - "RTE_CRYPTODEV_FF_CPU_NEON",,,,,,,,x - "RTE_CRYPTODEV_FF_CPU_ARM_CE",,,,,,,,x +.. raw:: html + + + +.. include:: overview_feature_table.txt Supported Cipher Algorithms +--------------------------- -.. csv-table:: - :header: "Cipher Algorithms", "qat", "null", "aesni_mb", "aesni_gcm", "snow3g", "kasumi", "zuc", "armv8" - :stub-columns: 1 +.. _table_crypto_pmd_cipher_algos: - "NULL",,x,,,,,, - "AES_CBC_128",x,,x,,,,,x - "AES_CBC_192",x,,x,,,,, - "AES_CBC_256",x,,x,,,,, - "AES_CTR_128",x,,x,,,,, - "AES_CTR_192",x,,x,,,,, - "AES_CTR_256",x,,x,,,,, - "DES_CBC",x,,,,,,, - "SNOW3G_UEA2",x,,,,x,,, - "KASUMI_F8",,,,,,x,, - "ZUC_EEA3",,,,,,,x, +.. raw:: html + + + +.. include:: overview_cipher_table.txt Supported Authentication Algorithms +----------------------------------- -.. csv-table:: - :header: "Cipher Algorithms", "qat", "null", "aesni_mb", "aesni_gcm", "snow3g", "kasumi", "zuc", "armv8" - :stub-columns: 1 +.. _table_crypto_pmd_auth_algos: - "NONE",,x,,,,,, - "MD5",,,,,,,, - "MD5_HMAC",,,x,,,,, - "SHA1",,,,,,,, - "SHA1_HMAC",x,,x,,,,,x - "SHA224",,,,,,,, - "SHA224_HMAC",,,x,,,,, - "SHA256",,,,,,,, - "SHA256_HMAC",x,,x,,,,,x - "SHA384",,,,,,,, - "SHA384_HMAC",,,x,,,,, - "SHA512",,,,,,,, - "SHA512_HMAC",x,,x,,,,, - "AES_XCBC",x,,x,,,,, - "AES_GMAC",,,,x,,,, - "SNOW3G_UIA2",x,,,,x,,, - "KASUMI_F9",,,,,,x,, - "ZUC_EIA3",,,,,,,x, +.. raw:: html + + + +.. include:: overview_auth_table.txt Supported AEAD Algorithms +------------------------- -.. csv-table:: - :header: "AEAD Algorithms", "qat", "null", "aesni_mb", "aesni_gcm", "snow3g", "kasumi", "zuc", "armv8" - :stub-columns: 1 +.. _table_crypto_pmd_aead_algos: - "AES_GCM_128",x,,,x,,,, - "AES_GCM_192",x,,,,,,, - "AES_GCM_256",x,,,x,,,, +.. raw:: html + + + +.. include:: overview_aead_table.txt