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 <pablo.de.lara.guarch@intel.com>
Acked-by: John McNamara <john.mcnamara@intel.com>
This commit is contained in:
Pablo de Lara 2017-03-23 11:38:55 +00:00
parent 5d0bd2b31b
commit 807418f263
13 changed files with 631 additions and 76 deletions

4
.gitignore vendored
View File

@ -1 +1,5 @@
doc/guides/nics/overview_table.txt 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

View File

@ -178,25 +178,24 @@ def process_numref(app, doctree, from_docname):
node.replace_self(newnode) 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 Function to generate the Overview Table from the ini files that define
the features for each NIC. the features for each driver.
The default features for the table and their order is defined by the The default features for the table and their order is defined by the
'default.ini' file. 'default.ini' file.
""" """
# Default worning string. # Default warning string.
warning = 'Warning generate_nic_overview_table()' warning = 'Warning generate_overview_table()'
# Get the default features and order from the 'default.ini' file. # Get the default features and order from the 'default.ini' file.
ini_path = path_join(dirname(output_filename), 'features') ini_path = path_join(dirname(output_filename), 'features')
config = configparser.ConfigParser() config = configparser.ConfigParser()
config.optionxform = str config.optionxform = str
config.read(path_join(ini_path, 'default.ini')) config.read(path_join(ini_path, 'default.ini'))
default_section = 'Features' default_features = config.items(section)
default_features = config.items(default_section)
# Create a dict of the valid features to validate the other ini files. # Create a dict of the valid features to validate the other ini files.
valid_features = {} valid_features = {}
@ -206,7 +205,7 @@ def generate_nic_overview_table(output_filename):
valid_features[key] = ' ' valid_features[key] = ' '
max_feature_length = max(max_feature_length, len(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) ini_files = [basename(file) for file in listdir(ini_path)
if file.endswith('.ini') and file != 'default.ini'] if file.endswith('.ini') and file != 'default.ini']
ini_files.sort() ini_files.sort()
@ -226,7 +225,7 @@ def generate_nic_overview_table(output_filename):
header_names.append(name) 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 = {} ini_data = {}
for ini_filename in ini_files: for ini_filename in ini_files:
config = configparser.ConfigParser() config = configparser.ConfigParser()
@ -237,14 +236,14 @@ def generate_nic_overview_table(output_filename):
ini_data[ini_filename] = valid_features.copy() ini_data[ini_filename] = valid_features.copy()
# Check for a valid ini section. # 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, print("{}: File '{}' has no [{}] secton".format(warning,
ini_filename, ini_filename,
default_section)) section))
continue continue
# Check for valid features names. # 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: if name not in valid_features:
print("{}: Unknown feature '{}' in '{}'".format(warning, print("{}: Unknown feature '{}' in '{}'".format(warning,
name, name,
@ -255,18 +254,18 @@ def generate_nic_overview_table(output_filename):
# Get the first letter only. # Get the first letter only.
ini_data[ini_filename][name] = value[0] 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') outfile = open(output_filename, 'w')
num_cols = len(header_names) num_cols = len(header_names)
print('.. table:: Features availability in networking drivers\n', print('.. table:: ' + table_name + '\n',
file=outfile) 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) 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 the RST table header. The header names are vertical. """
print_table_divider(outfile, num_cols) print_table_divider(outfile, num_cols)
@ -274,7 +273,7 @@ def print_table_header(outfile, num_cols, header_names):
for name in header_names: for name in header_names:
line += ' ' + name[0] line += ' ' + name[0]
print_table_row(outfile, 'Feature', line) print_table_row(outfile, title, line)
for i in range(1, 10): for i in range(1, 10):
line = '' line = ''
@ -319,7 +318,30 @@ def print_table_divider(outfile, num_cols):
def setup(app): def setup(app):
table_file = dirname(__file__) + '/nics/overview_table.txt' 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'): if LooseVersion(sphinx_version) < LooseVersion('1.3.1'):
print('Upgrade sphinx to version >= 1.3.1 for ' print('Upgrade sphinx to version >= 1.3.1 for '

View File

@ -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

View File

@ -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]

View File

@ -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]

View File

@ -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) =

View File

@ -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]

View File

@ -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]

View File

@ -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

View File

@ -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

View File

@ -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]

View File

@ -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]

View File

@ -1,5 +1,5 @@
.. BSD LICENSE .. 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 Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions modification, are permitted provided that the following conditions
@ -11,7 +11,7 @@
notice, this list of conditions and the following disclaimer in notice, this list of conditions and the following disclaimer in
the documentation and/or other materials provided with the the documentation and/or other materials provided with the
distribution. 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 contributors may be used to endorse or promote products derived
from this software without specific prior written permission. from this software without specific prior written permission.
@ -28,75 +28,244 @@
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Crypto Device Supported Functionality Matrices Crypto Device Supported Functionality Matrices
---------------------------------------------- ==============================================
Supported Feature Flags Supported Feature Flags
-----------------------
.. csv-table:: .. _table_crypto_pmd_features:
:header: "Feature Flags", "qat", "null", "aesni_mb", "aesni_gcm", "snow3g", "kasumi", "zuc", "armv8"
:stub-columns: 1
"RTE_CRYPTODEV_FF_SYMMETRIC_CRYPTO",x,x,x,x,x,x,x,x .. raw:: html
"RTE_CRYPTODEV_FF_ASYMMETRIC_CRYPTO",,,,,,,,
"RTE_CRYPTODEV_FF_SYM_OPERATION_CHAINING",x,x,x,x,x,x,x,x <style>
"RTE_CRYPTODEV_FF_CPU_SSE",,,x,,x,x,, .wy-nav-content {
"RTE_CRYPTODEV_FF_CPU_AVX",,,x,,x,x,, opacity: .99;
"RTE_CRYPTODEV_FF_CPU_AVX2",,,x,,,,, }
"RTE_CRYPTODEV_FF_CPU_AVX512",,,x,,,,, table#id1 {
"RTE_CRYPTODEV_FF_CPU_AESNI",,,x,x,,,, cursor: default;
"RTE_CRYPTODEV_FF_HW_ACCELERATED",x,,,,,,, overflow: hidden;
"RTE_CRYPTODEV_FF_CPU_NEON",,,,,,,,x }
"RTE_CRYPTODEV_FF_CPU_ARM_CE",,,,,,,,x table#id1 th, table#id1 td {
text-align: center;
}
table#id1 th {
font-size: 80%;
white-space: pre-wrap;
vertical-align: top;
padding: 2px;
}
table#id1 th:first-child {
vertical-align: bottom;
}
table#id1 td {
font-size: 70%;
padding: 1px;
}
table#id1 td:first-child {
padding-left: 1em;
text-align: left;
}
table#id1 tr:nth-child(2n-1) td {
background-color: rgba(210, 210, 210, 0.2);
}
table#id1 th:not(:first-child):hover,
table#id1 td:not(:first-child):hover {
position: relative;
}
table#id1 th:not(:first-child):hover::after,
table#id1 td:not(:first-child):hover::after {
content: '';
height: 6000px;
top: -3000px;
width: 100%;
left: 0;
position: absolute;
z-index: -1;
background-color: #ffb;
}
table#id1 tr:hover td {
background-color: #ffb;
}
</style>
.. include:: overview_feature_table.txt
Supported Cipher Algorithms Supported Cipher Algorithms
---------------------------
.. csv-table:: .. _table_crypto_pmd_cipher_algos:
:header: "Cipher Algorithms", "qat", "null", "aesni_mb", "aesni_gcm", "snow3g", "kasumi", "zuc", "armv8"
:stub-columns: 1
"NULL",,x,,,,,, .. raw:: html
"AES_CBC_128",x,,x,,,,,x
"AES_CBC_192",x,,x,,,,, <style>
"AES_CBC_256",x,,x,,,,, .wy-nav-content {
"AES_CTR_128",x,,x,,,,, opacity: .99;
"AES_CTR_192",x,,x,,,,, }
"AES_CTR_256",x,,x,,,,, table#id2 {
"DES_CBC",x,,,,,,, cursor: default;
"SNOW3G_UEA2",x,,,,x,,, overflow: hidden;
"KASUMI_F8",,,,,,x,, }
"ZUC_EEA3",,,,,,,x, table#id2 th, table#id2 td {
text-align: center;
}
table#id2 th {
font-size: 80%;
white-space: pre-wrap;
vertical-align: top;
padding: 2px;
}
table#id2 th:first-child {
vertical-align: bottom;
}
table#id2 td {
font-size: 70%;
padding: 1px;
}
table#id2 td:first-child {
padding-left: 1em;
text-align: left;
}
table#id2 tr:nth-child(2n-1) td {
background-color: rgba(210, 210, 210, 0.2);
}
table#id2 th:not(:first-child):hover,
table#id2 td:not(:first-child):hover {
position: relative;
}
table#id2 th:not(:first-child):hover::after,
table#id2 td:not(:first-child):hover::after {
content: '';
height: 6000px;
top: -3000px;
width: 100%;
left: 0;
position: absolute;
z-index: -1;
background-color: #ffb;
}
table#id2 tr:hover td {
background-color: #ffb;
}
</style>
.. include:: overview_cipher_table.txt
Supported Authentication Algorithms Supported Authentication Algorithms
-----------------------------------
.. csv-table:: .. _table_crypto_pmd_auth_algos:
:header: "Cipher Algorithms", "qat", "null", "aesni_mb", "aesni_gcm", "snow3g", "kasumi", "zuc", "armv8"
:stub-columns: 1
"NONE",,x,,,,,, .. raw:: html
"MD5",,,,,,,,
"MD5_HMAC",,,x,,,,, <style>
"SHA1",,,,,,,, .wy-nav-content {
"SHA1_HMAC",x,,x,,,,,x opacity: .99;
"SHA224",,,,,,,, }
"SHA224_HMAC",,,x,,,,, table#id3 {
"SHA256",,,,,,,, cursor: default;
"SHA256_HMAC",x,,x,,,,,x overflow: hidden;
"SHA384",,,,,,,, }
"SHA384_HMAC",,,x,,,,, table#id3 th, table#id3 td {
"SHA512",,,,,,,, text-align: center;
"SHA512_HMAC",x,,x,,,,, }
"AES_XCBC",x,,x,,,,, table#id3 th {
"AES_GMAC",,,,x,,,, font-size: 80%;
"SNOW3G_UIA2",x,,,,x,,, white-space: pre-wrap;
"KASUMI_F9",,,,,,x,, vertical-align: top;
"ZUC_EIA3",,,,,,,x, padding: 2px;
}
table#id3 th:first-child {
vertical-align: bottom;
}
table#id3 td {
font-size: 70%;
padding: 1px;
}
table#id3 td:first-child {
padding-left: 1em;
text-align: left;
}
table#id3 tr:nth-child(2n-1) td {
background-color: rgba(210, 210, 210, 0.2);
}
table#id3 th:not(:first-child):hover,
table#id3 td:not(:first-child):hover {
position: relative;
}
table#id3 th:not(:first-child):hover::after,
table#id3 td:not(:first-child):hover::after {
content: '';
height: 6000px;
top: -3000px;
width: 100%;
left: 0;
position: absolute;
z-index: -1;
background-color: #ffb;
}
table#id3 tr:hover td {
background-color: #ffb;
}
</style>
.. include:: overview_auth_table.txt
Supported AEAD Algorithms Supported AEAD Algorithms
-------------------------
.. csv-table:: .. _table_crypto_pmd_aead_algos:
:header: "AEAD Algorithms", "qat", "null", "aesni_mb", "aesni_gcm", "snow3g", "kasumi", "zuc", "armv8"
:stub-columns: 1
"AES_GCM_128",x,,,x,,,, .. raw:: html
"AES_GCM_192",x,,,,,,,
"AES_GCM_256",x,,,x,,,, <style>
.wy-nav-content {
opacity: .99;
}
table#id4 {
cursor: default;
overflow: hidden;
}
table#id4 th, table#id4 td {
text-align: center;
}
table#id4 th {
font-size: 80%;
white-space: pre-wrap;
vertical-align: top;
padding: 2px;
}
table#id4 th:first-child {
vertical-align: bottom;
}
table#id4 td {
font-size: 70%;
padding: 1px;
}
table#id4 td:first-child {
padding-left: 1em;
text-align: left;
}
table#id4 tr:nth-child(2n-1) td {
background-color: rgba(210, 210, 210, 0.2);
}
table#id4 th:not(:first-child):hover,
table#id4 td:not(:first-child):hover {
position: relative;
}
table#id4 th:not(:first-child):hover::after,
table#id4 td:not(:first-child):hover::after {
content: '';
height: 6000px;
top: -3000px;
width: 100%;
left: 0;
position: absolute;
z-index: -1;
background-color: #ffb;
}
table#id4 tr:hover td {
background-color: #ffb;
}
</style>
.. include:: overview_aead_table.txt