diff options
Diffstat (limited to 'doc')
114 files changed, 3946 insertions, 2112 deletions
diff --git a/doc/api/doxy-api-index.md b/doc/api/doxy-api-index.md index 2284a53b..6675f965 100644 --- a/doc/api/doxy-api-index.md +++ b/doc/api/doxy-api-index.md @@ -108,7 +108,6 @@ There are many libraries, so their headers may be grouped by topics: [reorder] (@ref rte_reorder.h), [tailq] (@ref rte_tailq.h), [bitmap] (@ref rte_bitmap.h), - [ivshmem] (@ref rte_ivshmem.h) - **packet framework**: * [port] (@ref rte_port.h): diff --git a/doc/api/doxy-api.conf b/doc/api/doxy-api.conf index af5d6dd4..9dc7ae5c 100644 --- a/doc/api/doxy-api.conf +++ b/doc/api/doxy-api.conf @@ -43,7 +43,6 @@ INPUT = doc/api/doxy-api-index.md \ lib/librte_ether \ lib/librte_hash \ lib/librte_ip_frag \ - lib/librte_ivshmem \ lib/librte_jobstats \ lib/librte_kni \ lib/librte_kvargs \ diff --git a/doc/api/examples.dox b/doc/api/examples.dox index 200af0b0..1626852c 100644 --- a/doc/api/examples.dox +++ b/doc/api/examples.dox @@ -40,8 +40,6 @@ @example ipv4_multicast/main.c @example kni/main.c @example l2fwd-crypto/main.c -@example l2fwd-ivshmem/guest/guest.c -@example l2fwd-ivshmem/host/host.c @example l2fwd-jobstats/main.c @example l2fwd-keepalive/main.c @example l2fwd/main.c diff --git a/doc/guides/conf.py b/doc/guides/conf.py index 2c5610f8..149bcdbc 100644 --- a/doc/guides/conf.py +++ b/doc/guides/conf.py @@ -28,12 +28,25 @@ # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +from __future__ import print_function import subprocess from docutils import nodes from distutils.version import LooseVersion from sphinx import __version__ as sphinx_version from sphinx.highlighting import PygmentsBridge from pygments.formatters.latex import LatexFormatter +from os import listdir +from os.path import basename +from os.path import dirname +from os.path import join as path_join + +try: + # Python 2. + import ConfigParser as configparser +except: + # Python 3. + import configparser + project = 'Data Plane Development Kit' @@ -92,6 +105,18 @@ class CustomLatexFormatter(LatexFormatter): # Replace the default latex formatter. PygmentsBridge.latex_formatter = CustomLatexFormatter +# Configuration for man pages +man_pages = [("testpmd_app_ug/run_app", "testpmd", + "tests for dpdk pmds", "", 1), + ("tools/pdump", "dpdk-pdump", + "enable packet capture on dpdk ports", "", 1), + ("tools/proc_info", "dpdk-procinfo", + "access dpdk port stats and memory info", "", 1), + ("tools/pmdinfo", "dpdk-pmdinfo", + "dump a PMDs hardware support info", "", 1), + ("tools/devbind", "dpdk-devbind", + "check device status and bind/unbind them from drivers", "", 8)] + ######## :numref: fallback ######## # The following hook functions add some simple handling for the :numref: # directive for Sphinx versions prior to 1.3.1. The functions replace the @@ -146,7 +171,149 @@ def process_numref(app, doctree, from_docname): internal=True) node.replace_self(newnode) + +def generate_nic_overview_table(output_filename): + """ + Function to generate the NIC Overview Table from the ini files that define + the features for each NIC. + + 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()' + + # 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) + + # Create a dict of the valid features to validate the other ini files. + valid_features = {} + max_feature_length = 0 + for feature in default_features: + key = feature[0] + valid_features[key] = ' ' + max_feature_length = max(max_feature_length, len(key)) + + # Get a list of NIC 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() + + # Build up a list of the table header names from the ini filenames. + header_names = [] + for ini_filename in ini_files: + name = ini_filename[:-4] + name = name.replace('_vf', 'vf') + + # Pad the table header names to match the existing format. + if '_vec' in name: + pmd, vec = name.split('_') + name = '{0:{fill}{align}7}vec'.format(pmd, fill='.', align='<') + else: + name = '{0:{fill}{align}10}'.format(name, fill=' ', align='<') + + header_names.append(name) + + # Create a dict of the defined features for each NIC from the ini files. + ini_data = {} + for ini_filename in ini_files: + config = configparser.ConfigParser() + config.optionxform = str + config.read(path_join(ini_path, ini_filename)) + + # Initialize the dict with the default.ini value. + ini_data[ini_filename] = valid_features.copy() + + # Check for a valid ini section. + if not config.has_section(default_section): + print("{}: File '{}' has no [{}] secton".format(warning, + ini_filename, + default_section)) + continue + + # Check for valid features names. + for name, value in config.items(default_section): + if name not in valid_features: + print("{}: Unknown feature '{}' in '{}'".format(warning, + name, + ini_filename)) + continue + + if value is not '': + # Get the first letter only. + ini_data[ini_filename][name] = value[0] + + # Print out the RST NIC 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', + file=outfile) + + print_table_header(outfile, num_cols, header_names) + print_table_body(outfile, num_cols, ini_files, ini_data, default_features) + + +def print_table_header(outfile, num_cols, header_names): + """ Print the RST table header. The header names are vertical. """ + print_table_divider(outfile, num_cols) + + line = '' + for name in header_names: + line += ' ' + name[0] + + print_table_row(outfile, 'Feature', line) + + for i in range(1, 10): + line = '' + for name in header_names: + line += ' ' + name[i] + + print_table_row(outfile, '', line) + + print_table_divider(outfile, num_cols) + + +def print_table_body(outfile, num_cols, ini_files, ini_data, default_features): + """ Print out the body of the table. Each row is a NIC feature. """ + + for feature, _ in default_features: + line = '' + + for ini_filename in ini_files: + line += ' ' + ini_data[ini_filename][feature] + + print_table_row(outfile, feature, line) + + print_table_divider(outfile, num_cols) + + +def print_table_row(outfile, feature, line): + """ Print a single row of the table with fixed formatting. """ + line = line.rstrip() + print(' {:<20}{}'.format(feature, line), file=outfile) + + +def print_table_divider(outfile, num_cols): + """ Print the table divider line. """ + line = ' ' + column_dividers = ['='] * num_cols + line += ' '.join(column_dividers) + + feature = '=' * 20 + + print_table_row(outfile, feature, line) + + def setup(app): + generate_nic_overview_table('doc/guides/nics/overview_table.txt') + if LooseVersion(sphinx_version) < LooseVersion('1.3.1'): print('Upgrade sphinx to version >= 1.3.1 for ' 'improved Figure/Table number handling.') diff --git a/doc/guides/contributing/documentation.rst b/doc/guides/contributing/documentation.rst index b2cc903f..2cfb1a29 100644 --- a/doc/guides/contributing/documentation.rst +++ b/doc/guides/contributing/documentation.rst @@ -458,8 +458,8 @@ Code and Literal block sections For long literal lines that exceed that limit try to wrap the text at sensible locations. For example a long command line could be documented like this and still work if copied directly from the docs:: - build/app/testpmd -c7 -n3 --vdev=eth_pcap0,iface=eth0 \ - --vdev=eth_pcap1,iface=eth1 \ + build/app/testpmd -c7 -n3 --vdev=net_pcap0,iface=eth0 \ + --vdev=net_pcap1,iface=eth1 \ -- -i --nb-cores=2 --nb-ports=2 \ --total-num-mbufs=2048 @@ -631,7 +631,7 @@ The following are some guidelines for use of Doxygen in the DPDK API documentati * @param devargs * A pointer to a strings array describing the new device * to be attached. The strings should be a pci address like - * `0000:01:00.0` or **virtual** device name like `eth_pcap0`. + * `0000:01:00.0` or **virtual** device name like `net_pcap0`. * @param port_id * A pointer to a port identifier actually attached. * @@ -643,7 +643,7 @@ The following are some guidelines for use of Doxygen in the DPDK API documentati * Doxygen supports Markdown style syntax such as bold, italics, fixed width text and lists. For example the second line in the ``devargs`` parameter in the previous example will be rendered as: - The strings should be a pci address like ``0000:01:00.0`` or **virtual** device name like ``eth_pcap0``. + The strings should be a pci address like ``0000:01:00.0`` or **virtual** device name like ``net_pcap0``. * Use ``-`` instead of ``*`` for lists within the Doxygen comment since the latter can get confused with the comment delimiter. diff --git a/doc/guides/contributing/patches.rst b/doc/guides/contributing/patches.rst index 16a21a52..729aea71 100644 --- a/doc/guides/contributing/patches.rst +++ b/doc/guides/contributing/patches.rst @@ -24,7 +24,7 @@ The DPDK development process has the following features: The mailing list for DPDK development is `dev@dpdk.org <http://dpdk.org/ml/archives/dev/>`_. Contributors will need to `register for the mailing list <http://dpdk.org/ml/listinfo/dev>`_ in order to submit patches. -It is also worth registering for the DPDK `Patchwork <http://dpdk.org/dev/patchwxispork/project/dpdk/list/>`_ +It is also worth registering for the DPDK `Patchwork <http://dpdk.org/dev/patchwork/project/dpdk/list/>`_ The development process requires some familiarity with the ``git`` version control system. Refer to the `Pro Git Book <http://www.git-scm.com/book/>`_ for further information. diff --git a/doc/guides/contributing/versioning.rst b/doc/guides/contributing/versioning.rst index 92b4d7ca..08e2e217 100644 --- a/doc/guides/contributing/versioning.rst +++ b/doc/guides/contributing/versioning.rst @@ -331,11 +331,12 @@ defined, we add this .. code-block:: c - struct rte_acl_create_v21(const struct rte_acl_param *param, int debug) + struct rte_acl_ctx * + rte_acl_create_v21(const struct rte_acl_param *param, int debug) { ... } - MAP_STATIC_SYMBOL(struct rte_acl_create(const struct rte_acl_param *param, int debug), rte_acl_create_v21); + MAP_STATIC_SYMBOL(struct rte_acl_ctx *rte_acl_create(const struct rte_acl_param *param, int debug), rte_acl_create_v21); That tells the compiler that, when building a static library, any calls to the symbol ``rte_acl_create`` should be linked to ``rte_acl_create_v21`` diff --git a/doc/guides/cryptodevs/aesni_gcm.rst b/doc/guides/cryptodevs/aesni_gcm.rst index 7ff1c6b3..04bf43c2 100644 --- a/doc/guides/cryptodevs/aesni_gcm.rst +++ b/doc/guides/cryptodevs/aesni_gcm.rst @@ -64,9 +64,9 @@ In order to enable this virtual crypto PMD, user must: To use the PMD in an application, user must: -* Call rte_eal_vdev_init("cryptodev_aesni_gcm_pmd") within the application. +* Call rte_eal_vdev_init("crypto_aesni_gcm") within the application. -* Use --vdev="cryptodev_aesni_gcm_pmd" in the EAL options, which will call rte_eal_vdev_init() internally. +* Use --vdev="crypto_aesni_gcm" in the EAL options, which will call rte_eal_vdev_init() internally. The following parameters (all optional) can be provided in the previous two calls: @@ -81,7 +81,7 @@ Example: .. code-block:: console - ./l2fwd-crypto -c 40 -n 4 --vdev="cryptodev_aesni_gcm_pmd,socket_id=1,max_nb_sessions=128" + ./l2fwd-crypto -c 40 -n 4 --vdev="crypto_aesni_gcm,socket_id=1,max_nb_sessions=128" Limitations ----------- diff --git a/doc/guides/cryptodevs/aesni_mb.rst b/doc/guides/cryptodevs/aesni_mb.rst index 60a89142..e812e957 100644 --- a/doc/guides/cryptodevs/aesni_mb.rst +++ b/doc/guides/cryptodevs/aesni_mb.rst @@ -45,18 +45,18 @@ AESNI MB PMD has support for: Cipher algorithms: -* RTE_CRYPTO_SYM_CIPHER_AES128_CBC -* RTE_CRYPTO_SYM_CIPHER_AES192_CBC -* RTE_CRYPTO_SYM_CIPHER_AES256_CBC -* RTE_CRYPTO_SYM_CIPHER_AES128_CTR -* RTE_CRYPTO_SYM_CIPHER_AES192_CTR -* RTE_CRYPTO_SYM_CIPHER_AES256_CTR +* RTE_CRYPTO_CIPHER_AES128_CBC +* RTE_CRYPTO_CIPHER_AES192_CBC +* RTE_CRYPTO_CIPHER_AES256_CBC +* RTE_CRYPTO_CIPHER_AES128_CTR +* RTE_CRYPTO_CIPHER_AES192_CTR +* RTE_CRYPTO_CIPHER_AES256_CTR Hash algorithms: -* RTE_CRYPTO_SYM_HASH_SHA1_HMAC -* RTE_CRYPTO_SYM_HASH_SHA256_HMAC -* RTE_CRYPTO_SYM_HASH_SHA512_HMAC +* RTE_CRYPTO_HASH_SHA1_HMAC +* RTE_CRYPTO_HASH_SHA256_HMAC +* RTE_CRYPTO_HASH_SHA512_HMAC Limitations ----------- @@ -96,9 +96,9 @@ In order to enable this virtual crypto PMD, user must: To use the PMD in an application, user must: -* Call rte_eal_vdev_init("cryptodev_aesni_mb_pmd") within the application. +* Call rte_eal_vdev_init("crypto_aesni_mb") within the application. -* Use --vdev="cryptodev_aesni_mb_pmd" in the EAL options, which will call rte_eal_vdev_init() internally. +* Use --vdev="crypto_aesni_mb" in the EAL options, which will call rte_eal_vdev_init() internally. The following parameters (all optional) can be provided in the previous two calls: @@ -113,4 +113,4 @@ Example: .. code-block:: console - ./l2fwd-crypto -c 40 -n 4 --vdev="cryptodev_aesni_mb_pmd,socket_id=1,max_nb_sessions=128" + ./l2fwd-crypto -c 40 -n 4 --vdev="crypto_aesni_mb,socket_id=1,max_nb_sessions=128" diff --git a/doc/guides/cryptodevs/index.rst b/doc/guides/cryptodevs/index.rst index 9616de1e..a6a9f23c 100644 --- a/doc/guides/cryptodevs/index.rst +++ b/doc/guides/cryptodevs/index.rst @@ -39,6 +39,8 @@ Crypto Device Drivers aesni_mb aesni_gcm kasumi + openssl null snow3g qat + zuc diff --git a/doc/guides/cryptodevs/kasumi.rst b/doc/guides/cryptodevs/kasumi.rst index 7346b217..90d8e7b3 100644 --- a/doc/guides/cryptodevs/kasumi.rst +++ b/doc/guides/cryptodevs/kasumi.rst @@ -41,11 +41,11 @@ KASUMI PMD has support for: Cipher algorithm: -* RTE_CRYPTO_SYM_CIPHER_KASUMI_F8 +* RTE_CRYPTO_CIPHER_KASUMI_F8 Authentication algorithm: -* RTE_CRYPTO_SYM_AUTH_KASUMI_F9 +* RTE_CRYPTO_AUTH_KASUMI_F9 Limitations ----------- @@ -68,7 +68,13 @@ and click on "Kasumi Bit Stream crypto library" link, to download the library. After downloading the library, the user needs to unpack and compile it on their system before building DPDK:: - make kasumi + make + +**Note**: To build the PMD as a shared library, the libsso_kasumi +library must be built as follows:: + + make KASUMI_CFLAGS=-DKASUMI_C + Initialization -------------- @@ -84,9 +90,9 @@ In order to enable this virtual crypto PMD, user must: To use the PMD in an application, user must: -* Call rte_eal_vdev_init("cryptodev_kasumi_pmd") within the application. +* Call rte_eal_vdev_init("crypto_kasumi") within the application. -* Use --vdev="cryptodev_kasumi_pmd" in the EAL options, which will call rte_eal_vdev_init() internally. +* Use --vdev="crypto_kasumi" in the EAL options, which will call rte_eal_vdev_init() internally. The following parameters (all optional) can be provided in the previous two calls: @@ -101,4 +107,4 @@ Example: .. code-block:: console - ./l2fwd-crypto -c 40 -n 4 --vdev="cryptodev_kasumi_pmd,socket_id=1,max_nb_sessions=128" + ./l2fwd-crypto -c 40 -n 4 --vdev="crypto_kasumi,socket_id=1,max_nb_sessions=128" diff --git a/doc/guides/cryptodevs/null.rst b/doc/guides/cryptodevs/null.rst index b68d4cd2..ec5bc70d 100644 --- a/doc/guides/cryptodevs/null.rst +++ b/doc/guides/cryptodevs/null.rst @@ -76,9 +76,9 @@ Initialization To use the PMD in an application, user must: -* Call rte_eal_vdev_init("cryptodev_null_pmd") within the application. +* Call rte_eal_vdev_init("crypto_null") within the application. -* Use --vdev="cryptodev_null_pmd" in the EAL options, which will call rte_eal_vdev_init() internally. +* Use --vdev="crypto_null" in the EAL options, which will call rte_eal_vdev_init() internally. The following parameters (all optional) can be provided in the previous two calls: @@ -93,4 +93,4 @@ Example: .. code-block:: console - ./l2fwd-crypto -c 40 -n 4 --vdev="cryptodev_null_pmd,socket_id=1,max_nb_sessions=128" + ./l2fwd-crypto -c 40 -n 4 --vdev="crypto_null,socket_id=1,max_nb_sessions=128" diff --git a/doc/guides/cryptodevs/openssl.rst b/doc/guides/cryptodevs/openssl.rst new file mode 100644 index 00000000..d2b5906d --- /dev/null +++ b/doc/guides/cryptodevs/openssl.rst @@ -0,0 +1,117 @@ +.. BSD LICENSE + Copyright(c) 2016 Intel Corporation. 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. + +OpenSSL Crypto Poll Mode Driver +=============================== + +This code provides the initial implementation of the openssl poll mode +driver. All cryptography operations are using Openssl library crypto API. +Each algorithm uses EVP interface from openssl API - which is recommended +by Openssl maintainers. + +For more details about openssl library please visit openssl webpage: +https://www.openssl.org/ + +Features +-------- + +OpenSSL PMD has support for: + +Supported cipher algorithms: +* ``RTE_CRYPTO_CIPHER_3DES_CBC`` +* ``RTE_CRYPTO_CIPHER_AES_CBC`` +* ``RTE_CRYPTO_CIPHER_AES_CTR`` +* ``RTE_CRYPTO_CIPHER_3DES_CTR`` +* ``RTE_CRYPTO_CIPHER_AES_GCM`` + +Supported authentication algorithms: +* ``RTE_CRYPTO_AUTH_AES_GMAC`` +* ``RTE_CRYPTO_AUTH_MD5`` +* ``RTE_CRYPTO_AUTH_SHA1`` +* ``RTE_CRYPTO_AUTH_SHA224`` +* ``RTE_CRYPTO_AUTH_SHA256`` +* ``RTE_CRYPTO_AUTH_SHA384`` +* ``RTE_CRYPTO_AUTH_SHA512`` +* ``RTE_CRYPTO_AUTH_MD5_HMAC`` +* ``RTE_CRYPTO_AUTH_SHA1_HMAC`` +* ``RTE_CRYPTO_AUTH_SHA224_HMAC`` +* ``RTE_CRYPTO_AUTH_SHA256_HMAC`` +* ``RTE_CRYPTO_AUTH_SHA384_HMAC`` +* ``RTE_CRYPTO_AUTH_SHA512_HMAC`` + + +Installation +------------ + +To compile openssl PMD, it has to be enabled in the config/common_base file +and appropriate openssl packages have to be installed in the build environment. + +The newest openssl library version is supported: +* 1.0.2h-fips 3 May 2016. +Older versions that were also verified: +* 1.0.1f 6 Jan 2014 +* 1.0.1 14 Mar 2012 + +For Ubuntu 14.04 LTS these packages have to be installed in the build system: +sudo apt-get install openssl +sudo apt-get install libc6-dev-i386 (for i686-native-linuxapp-gcc target) + +This code was also verified on Fedora 24. +This code was NOT yet verified on FreeBSD. + +Initialization +-------------- + +User can use app/test application to check how to use this pmd and to verify +crypto processing. + +Test name is cryptodev_openssl_autotest. +For performance test cryptodev_openssl_perftest can be used. + +To verify real traffic l2fwd-crypto example can be used with this command: + +.. code-block:: console + +sudo ./build/l2fwd-crypto -c 0x3 -n 4 --vdev "crypto_openssl" +--vdev "crypto_openssl"-- -p 0x3 --chain CIPHER_HASH +--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 +--iv 00:01:02:03:04:05:06:07:08:09:0a:0b:0c:0d:0e:ff +--auth_op GENERATE --auth_algo SHA1_HMAC +--auth_key 11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11 +:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11 +:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11 + +Limitations +----------- + +* Maximum number of sessions is 2048. +* Chained mbufs are not supported. +* Hash only is not supported for GCM and GMAC. +* Cipher only is not supported for GCM and GMAC. diff --git a/doc/guides/cryptodevs/qat.rst b/doc/guides/cryptodevs/qat.rst index cae19582..52a9ae35 100644 --- a/doc/guides/cryptodevs/qat.rst +++ b/doc/guides/cryptodevs/qat.rst @@ -27,11 +27,12 @@ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -Quick Assist Crypto Poll Mode Driver -==================================== +Intel(R) QuickAssist (QAT) Crypto Poll Mode Driver +================================================== The QAT PMD provides poll mode crypto driver support for **Intel QuickAssist -Technology DH895xxC** hardware accelerator. +Technology DH895xxC**, **Intel QuickAssist Technology C62x** and +**Intel QuickAssist Technology C3xxx** hardware accelerator. Features @@ -41,34 +42,43 @@ The QAT PMD has support for: Cipher algorithms: -* ``RTE_CRYPTO_SYM_CIPHER_AES128_CBC`` -* ``RTE_CRYPTO_SYM_CIPHER_AES192_CBC`` -* ``RTE_CRYPTO_SYM_CIPHER_AES256_CBC`` -* ``RTE_CRYPTO_SYM_CIPHER_AES128_CTR`` -* ``RTE_CRYPTO_SYM_CIPHER_AES192_CTR`` -* ``RTE_CRYPTO_SYM_CIPHER_AES256_CTR`` -* ``RTE_CRYPTO_SYM_CIPHER_SNOW3G_UEA2`` +* ``RTE_CRYPTO_CIPHER_3DES_CBC`` +* ``RTE_CRYPTO_CIPHER_3DES_CTR`` +* ``RTE_CRYPTO_CIPHER_AES128_CBC`` +* ``RTE_CRYPTO_CIPHER_AES192_CBC`` +* ``RTE_CRYPTO_CIPHER_AES256_CBC`` +* ``RTE_CRYPTO_CIPHER_AES128_CTR`` +* ``RTE_CRYPTO_CIPHER_AES192_CTR`` +* ``RTE_CRYPTO_CIPHER_AES256_CTR`` +* ``RTE_CRYPTO_CIPHER_SNOW3G_UEA2`` * ``RTE_CRYPTO_CIPHER_AES_GCM`` +* ``RTE_CRYPTO_CIPHER_NULL`` +* ``RTE_CRYPTO_CIPHER_KASUMI_F8`` Hash algorithms: * ``RTE_CRYPTO_AUTH_SHA1_HMAC`` +* ``RTE_CRYPTO_AUTH_SHA224_HMAC`` * ``RTE_CRYPTO_AUTH_SHA256_HMAC`` +* ``RTE_CRYPTO_AUTH_SHA384_HMAC`` * ``RTE_CRYPTO_AUTH_SHA512_HMAC`` * ``RTE_CRYPTO_AUTH_AES_XCBC_MAC`` * ``RTE_CRYPTO_AUTH_SNOW3G_UIA2`` +* ``RTE_CRYPTO_AUTH_MD5_HMAC`` +* ``RTE_CRYPTO_AUTH_NULL`` +* ``RTE_CRYPTO_AUTH_KASUMI_F9`` +* ``RTE_CRYPTO_AUTH_AES_GMAC`` Limitations ----------- * Chained mbufs are not supported. -* Hash only is not supported except Snow3G UIA2. -* Cipher only is not supported except Snow3G UEA2. +* Hash only is not supported except SNOW 3G UIA2 and KASUMI F9. +* Cipher only is not supported except SNOW 3G UEA2, KASUMI F8 and 3DES. * Only supports the session-oriented API implementation (session-less APIs are not supported). -* Not performance tuned. -* Snow3g(UEA2) supported only if cipher length, cipher offset fields are byte-aligned. -* Snow3g(UIA2) supported only if hash length, hash offset fields are byte-aligned. +* SNOW 3G (UEA2) and KASUMI (F8) supported only if cipher length, cipher offset fields are byte-aligned. +* SNOW 3G (UIA2) and KASUMI (F9) supported only if hash length, hash offset fields are byte-aligned. * No BSD support as BSD QAT kernel driver not available. @@ -78,14 +88,32 @@ Installation To use the DPDK QAT PMD an SRIOV-enabled QAT kernel driver is required. The VF devices exposed by this driver will be used by QAT PMD. +To enable QAT in DPDK, follow the instructions mentioned in +http://dpdk.org/doc/guides/linux_gsg/build_dpdk.html + +Quick instructions as follows: + +.. code-block:: console + + make config T=x86_64-native-linuxapp-gcc + sed -i 's,\(CONFIG_RTE_LIBRTE_PMD_QAT\)=n,\1=y,' build/.config + make + If you are running on kernel 4.4 or greater, see instructions for `Installation using kernel.org driver`_ below. If you are on a kernel earlier than 4.4, see `Installation using 01.org QAT driver`_. +For **Intel QuickAssist Technology C62x** and **Intel QuickAssist Technology C3xxx** +device, kernel 4.5 or greater is needed. +See instructions for `Installation using kernel.org driver`_ below. + Installation using 01.org QAT driver ------------------------------------ +NOTE: There is no driver available for **Intel QuickAssist Technology C62x** and +**Intel QuickAssist Technology C3xxx** devices on 01.org. + Download the latest QuickAssist Technology Driver from `01.org <https://01.org/packet-processing/intel%C2%AE-quickassist-technology-drivers-and-patches>`_ Consult the *Getting Started Guide* at the same URL for further information. @@ -162,6 +190,8 @@ If the build or install fails due to mismatching kernel sources you may need to Installation using kernel.org driver ------------------------------------ +For **Intel QuickAssist Technology DH895xxC**: + Assuming you are running on at least a 4.4 kernel, you can use the stock kernel.org QAT driver to start the QAT hardware. @@ -170,7 +200,9 @@ The steps below assume you are: * Running DPDK on a platform with one ``DH895xCC`` device. * On a kernel at least version 4.4. -In BIOS ensure that SRIOV is enabled and VT-d is disabled. +In BIOS ensure that SRIOV is enabled and either +a) disable VT-d or +b) enable VT-d and set ``"intel_iommu=on iommu=pt"`` in the grub file. Ensure the QAT driver is loaded on your system, by executing:: @@ -181,9 +213,9 @@ You should see the following output:: qat_dh895xcc 5626 0 intel_qat 82336 1 qat_dh895xcc -Next, you need to expose the VFs using the sysfs file system. +Next, you need to expose the Virtual Functions (VFs) using the sysfs file system. -First find the bdf of the DH895xCC device:: +First find the bdf of the physical function (PF) of the DH895xCC device:: lspci -d : 435 @@ -220,11 +252,99 @@ cd to your linux source root directory and start the qat kernel modules: **Note**:The following warning in /var/log/messages can be ignored: ``IOMMU should be enabled for SR-IOV to work correctly`` +For **Intel QuickAssist Technology C62x**: +Assuming you are running on at least a 4.5 kernel, you can use the stock kernel.org QAT +driver to start the QAT hardware. + +The steps below assume you are: + +* Running DPDK on a platform with one ``C62x`` device. +* On a kernel at least version 4.5. + +In BIOS ensure that SRIOV is enabled and either +a) disable VT-d or +b) enable VT-d and set ``"intel_iommu=on iommu=pt"`` in the grub file. + +Ensure the QAT driver is loaded on your system, by executing:: + + lsmod | grep qat + +You should see the following output:: + + qat_c62x 16384 0 + intel_qat 122880 1 qat_c62x + +Next, you need to expose the VFs using the sysfs file system. +First find the bdf of the C62x device:: + + lspci -d:37c8 + +You should see output similar to:: + + 1a:00.0 Co-processor: Intel Corporation Device 37c8 + 3d:00.0 Co-processor: Intel Corporation Device 37c8 + 3f:00.0 Co-processor: Intel Corporation Device 37c8 + +For each c62x device there are 3 PFs. +Using the sysfs, for each PF, enable the 16 VFs:: + + echo 16 > /sys/bus/pci/drivers/c6xx/0000\:1a\:00.0/sriov_numvfs + +If you get an error, it's likely you're using a QAT kernel driver earlier than kernel 4.5. + +To verify that the VFs are available for use - use ``lspci -d:37c9`` to confirm +the bdf of the 48 VF devices are available per ``C62x`` device. + +To complete the installation - follow instructions in `Binding the available VFs to the DPDK UIO driver`_. + +For **Intel QuickAssist Technology C3xxx**: +Assuming you are running on at least a 4.5 kernel, you can use the stock kernel.org QAT +driver to start the QAT hardware. + +The steps below assume you are: + +* Running DPDK on a platform with one ``C3xxx`` device. +* On a kernel at least version 4.5. + +In BIOS ensure that SRIOV is enabled and either +a) disable VT-d or +b) enable VT-d and set ``"intel_iommu=on iommu=pt"`` in the grub file. + +Ensure the QAT driver is loaded on your system, by executing:: + + lsmod | grep qat + +You should see the following output:: + + qat_c3xxx 16384 0 + intel_qat 122880 1 qat_c3xxx + +Next, you need to expose the Virtual Functions (VFs) using the sysfs file system. + +First find the bdf of the physical function (PF) of the C3xxx device + + lspci -d:19e2 + +You should see output similar to:: + + 01:00.0 Co-processor: Intel Corporation Device 19e2 + +For c3xxx device there is 1 PFs. +Using the sysfs, enable the 16 VFs:: + + echo 16 > /sys/bus/pci/drivers/c3xxx/0000\:01\:00.0/sriov_numvfs + +If you get an error, it's likely you're using a QAT kernel driver earlier than kernel 4.5. + +To verify that the VFs are available for use - use ``lspci -d:19e3`` to confirm +the bdf of the 16 VF devices are available per ``C3xxx`` device. +To complete the installation - follow instructions in `Binding the available VFs to the DPDK UIO driver`_. Binding the available VFs to the DPDK UIO driver ------------------------------------------------ +For **Intel(R) QuickAssist Technology DH895xcc** device: The unbind command below assumes ``bdfs`` of ``03:01.00-03:04.07``, if yours are different adjust the unbind command below:: cd $RTE_SDK @@ -241,3 +361,56 @@ The unbind command below assumes ``bdfs`` of ``03:01.00-03:04.07``, if yours are echo "8086 0443" > /sys/bus/pci/drivers/igb_uio/new_id You can use ``lspci -vvd:443`` to confirm that all devices are now in use by igb_uio kernel driver. + +For **Intel(R) QuickAssist Technology C62x** device: +The unbind command below assumes ``bdfs`` of ``1a:01.00-1a:02.07``, ``3d:01.00-3d:02.07`` and ``3f:01.00-3f:02.07``, +if yours are different adjust the unbind command below:: + + cd $RTE_SDK + modprobe uio + insmod ./build/kmod/igb_uio.ko + + for device in $(seq 1 2); do \ + for fn in $(seq 0 7); do \ + echo -n 0000:1a:0${device}.${fn} > \ + /sys/bus/pci/devices/0000\:1a\:0${device}.${fn}/driver/unbind; \ + + echo -n 0000:3d:0${device}.${fn} > \ + /sys/bus/pci/devices/0000\:3d\:0${device}.${fn}/driver/unbind; \ + + echo -n 0000:3f:0${device}.${fn} > \ + /sys/bus/pci/devices/0000\:3f\:0${device}.${fn}/driver/unbind; \ + done; \ + done + + echo "8086 37c9" > /sys/bus/pci/drivers/igb_uio/new_id + +You can use ``lspci -vvd:37c9`` to confirm that all devices are now in use by igb_uio kernel driver. + +For **Intel(R) QuickAssist Technology C3xxx** device: +The unbind command below assumes ``bdfs`` of ``01:01.00-01:02.07``, +if yours are different adjust the unbind command below:: + + cd $RTE_SDK + modprobe uio + insmod ./build/kmod/igb_uio.ko + + for device in $(seq 1 2); do \ + for fn in $(seq 0 7); do \ + echo -n 0000:01:0${device}.${fn} > \ + /sys/bus/pci/devices/0000\:01\:0${device}.${fn}/driver/unbind; \ + + done; \ + done + + echo "8086 19e3" > /sys/bus/pci/drivers/igb_uio/new_id + +You can use ``lspci -vvd:19e3`` to confirm that all devices are now in use by igb_uio kernel driver. + + +The other way to bind the VFs to the DPDK UIO driver is by using the ``dpdk-devbind.py`` script: + +.. code-block:: console + + cd $RTE_SDK + ./tools/dpdk-devbind.py -b igb_uio 0000:03:01.1 diff --git a/doc/guides/cryptodevs/snow3g.rst b/doc/guides/cryptodevs/snow3g.rst index 670a62a9..75a08aab 100644 --- a/doc/guides/cryptodevs/snow3g.rst +++ b/doc/guides/cryptodevs/snow3g.rst @@ -41,24 +41,24 @@ SNOW 3G PMD has support for: Cipher algorithm: -* RTE_CRYPTO_SYM_CIPHER_SNOW3G_UEA2 +* RTE_CRYPTO_CIPHER_SNOW3G_UEA2 Authentication algorithm: -* RTE_CRYPTO_SYM_AUTH_SNOW3G_UIA2 +* RTE_CRYPTO_AUTH_SNOW3G_UIA2 Limitations ----------- * Chained mbufs are not supported. -* Snow3g(UIA2) supported only if hash offset field is byte-aligned. -* In-place bit-level operations for Snow3g(UEA2) are not supported +* SNOW 3G (UIA2) supported only if hash offset field is byte-aligned. +* In-place bit-level operations for SNOW 3G (UEA2) are not supported (if length and/or offset of data to be ciphered is not byte-aligned). Installation ------------ -To build DPDK with the KASUMI_PMD the user is required to download +To build DPDK with the SNOW3G_PMD the user is required to download the export controlled ``libsso_snow3g`` library, by requesting it from `<https://networkbuilders.intel.com/network-technologies/dpdk>`_. Once approval has been granted, the user needs to log in @@ -83,9 +83,9 @@ In order to enable this virtual crypto PMD, user must: To use the PMD in an application, user must: -* Call rte_eal_vdev_init("cryptodev_snow3g_pmd") within the application. +* Call rte_eal_vdev_init("crypto_snow3g") within the application. -* Use --vdev="cryptodev_snow3g_pmd" in the EAL options, which will call rte_eal_vdev_init() internally. +* Use --vdev="crypto_snow3g" in the EAL options, which will call rte_eal_vdev_init() internally. The following parameters (all optional) can be provided in the previous two calls: @@ -100,4 +100,4 @@ Example: .. code-block:: console - ./l2fwd-crypto -c 40 -n 4 --vdev="cryptodev_snow3g_pmd,socket_id=1,max_nb_sessions=128" + ./l2fwd-crypto -c 40 -n 4 --vdev="crypto_snow3g,socket_id=1,max_nb_sessions=128" diff --git a/doc/guides/cryptodevs/zuc.rst b/doc/guides/cryptodevs/zuc.rst new file mode 100644 index 00000000..38d5068a --- /dev/null +++ b/doc/guides/cryptodevs/zuc.rst @@ -0,0 +1,111 @@ +.. BSD LICENSE + Copyright(c) 2016 Intel Corporation. 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. + +ZUC Crypto Poll Mode Driver +=========================== + +The ZUC PMD (**librte_pmd_zuc**) provides poll mode crypto driver +support for utilizing Intel Libsso library, which implements F8 and F9 functions +for ZUC EEA3 cipher and EIA3 hash algorithms. + +Features +-------- + +ZUC PMD has support for: + +Cipher algorithm: + +* RTE_CRYPTO_CIPHER_ZUC_EEA3 + +Authentication algorithm: + +* RTE_CRYPTO_AUTH_ZUC_EIA3 + +Limitations +----------- + +* Chained mbufs are not supported. +* ZUC (EIA3) supported only if hash offset field is byte-aligned. +* ZUC (EEA3) supported only if cipher length, cipher offset fields are byte-aligned. +* ZUC PMD cannot be built as a shared library, due to limitations in + in the underlying library. + + +Installation +------------ + +To build DPDK with the ZUC_PMD the user is required to download +the export controlled ``libsso_zuc`` library, by requesting it from +`<https://networkbuilders.intel.com/network-technologies/dpdk>`_. +Once approval has been granted, the user needs to log in +`<https://networkbuilders.intel.com/dpdklogin>`_ +and click on "ZUC Library" link, to download the library. +After downloading the library, the user needs to unpack and compile it +on their system before building DPDK:: + + make + +Initialization +-------------- + +In order to enable this virtual crypto PMD, user must: + +* Export the environmental variable LIBSSO_ZUC_PATH with the path where + the library was extracted (zuc folder). + +* Build the LIBSSO_ZUC library (explained in Installation section). + +* Build DPDK as follows: + +.. code-block:: console + + make config T=x86_64-native-linuxapp-gcc + sed -i 's,\(CONFIG_RTE_LIBRTE_PMD_ZUC\)=n,\1=y,' build/.config + make + +To use the PMD in an application, user must: + +* Call rte_eal_vdev_init("crypto_zuc") within the application. + +* Use --vdev="crypto_zuc" in the EAL options, which will call rte_eal_vdev_init() internally. + +The following parameters (all optional) can be provided in the previous two calls: + +* socket_id: Specify the socket where the memory for the device is going to be allocated + (by default, socket_id will be the socket where the core that is creating the PMD is running on). + +* max_nb_queue_pairs: Specify the maximum number of queue pairs in the device (8 by default). + +* max_nb_sessions: Specify the maximum number of sessions that can be created (2048 by default). + +Example: + +.. code-block:: console + + ./l2fwd-crypto -c 40 -n 4 --vdev="crypto_zuc,socket_id=1,max_nb_sessions=128" diff --git a/doc/guides/freebsd_gsg/build_dpdk.rst b/doc/guides/freebsd_gsg/build_dpdk.rst index 93c43661..24a9f879 100644 --- a/doc/guides/freebsd_gsg/build_dpdk.rst +++ b/doc/guides/freebsd_gsg/build_dpdk.rst @@ -88,7 +88,7 @@ The ports required and their locations are as follows: For compiling and using the DPDK with gcc, the compiler must be installed from the ports collection: -* gcc: version 4.8 is recommended ``/usr/ports/lang/gcc48``. +* gcc: version 4.9 is recommended ``/usr/ports/lang/gcc49``. Ensure that ``CPU_OPTS`` is selected (default is OFF). When running the make config-recursive command, a dialog may be presented to the @@ -111,10 +111,6 @@ First, uncompress the archive and move to the DPDK source directory: unzip DPDK-<version>.zip cd DPDK-<version> - ls - app/ config/ examples/ lib/ LICENSE.GPL LICENSE.LGPL Makefile - mk/ scripts/ tools/ - The DPDK is composed of several directories: * lib: Source code of DPDK libraries @@ -168,7 +164,7 @@ For example to compile for FreeBSD use: If the compiler binary to be used does not correspond to that given in the TOOLCHAIN part of the target, the compiler command may need to be explicitly specified. For example, if compiling for gcc, where the gcc binary is called - gcc4.8, the command would need to be ``gmake install T=<target> CC=gcc4.8``. + gcc4.9, the command would need to be ``gmake install T=<target> CC=gcc4.9``. Browsing the Installed DPDK Environment Target ---------------------------------------------- @@ -177,14 +173,7 @@ Once a target is created, it contains all the libraries and header files for the DPDK environment that are required to build customer applications. In addition, the test and testpmd applications are built under the build/app directory, which may be used for testing. A kmod directory is also present that -contains the kernel modules to install: - -.. code-block:: console - - ls x86_64-native-bsdapp-gcc - - app build include kmod lib Makefile - +contains the kernel modules to install. .. _loading_contigmem: diff --git a/doc/guides/freebsd_gsg/build_sample_apps.rst b/doc/guides/freebsd_gsg/build_sample_apps.rst index 2662303d..fffc4c01 100644 --- a/doc/guides/freebsd_gsg/build_sample_apps.rst +++ b/doc/guides/freebsd_gsg/build_sample_apps.rst @@ -54,7 +54,7 @@ the following variables must be exported: The following is an example of creating the ``helloworld`` application, which runs in the DPDK FreeBSD environment. While the example demonstrates compiling -using gcc version 4.8, compiling with clang will be similar, except that the ``CC=`` +using gcc version 4.9, compiling with clang will be similar, except that the ``CC=`` parameter can probably be omitted. The ``helloworld`` example may be found in the ``${RTE_SDK}/examples`` directory. @@ -72,7 +72,7 @@ in the build directory. setenv RTE_SDK $HOME/DPDK setenv RTE_TARGET x86_64-native-bsdapp-gcc - gmake CC=gcc48 + gmake CC=gcc49 CC main.o LD helloworld INSTALL-APP helloworld @@ -96,7 +96,7 @@ in the build directory. cd my_rte_app/ setenv RTE_TARGET x86_64-native-bsdapp-gcc - gmake CC=gcc48 + gmake CC=gcc49 CC main.o LD helloworld INSTALL-APP helloworld diff --git a/doc/guides/howto/flow_bifurcation.rst b/doc/guides/howto/flow_bifurcation.rst index a1c6262b..0d7226ae 100644 --- a/doc/guides/howto/flow_bifurcation.rst +++ b/doc/guides/howto/flow_bifurcation.rst @@ -119,8 +119,8 @@ The typical procedure to achieve this is as follows: .. code-block:: console modprobe vfio-pci - dpdk_nic_bind.py -b vfio-pci 01:10.0 - dpdk_nic_bind.py -b vfio-pci 01:10.1 + dpdk-devbind.py -b vfio-pci 01:10.0 + dpdk-devbind.py -b vfio-pci 01:10.1 #. Run a DPDK application on the VFs: @@ -279,8 +279,8 @@ The typical procedure to achieve this is as follows: .. code-block:: console modprobe vfio-pci - dpdk_nic_bind.py -b vfio-pci 01:10.0 - dpdk_nic_bind.py -b vfio-pci 01:10.1 + dpdk-devbind.py -b vfio-pci 01:10.0 + dpdk-devbind.py -b vfio-pci 01:10.1 #. run DPDK application on VFs: diff --git a/doc/guides/howto/index.rst b/doc/guides/howto/index.rst index aa6d3e2b..5575b274 100644 --- a/doc/guides/howto/index.rst +++ b/doc/guides/howto/index.rst @@ -28,8 +28,8 @@ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -How To User Guides -================== +HowTo Guides +============ .. toctree:: :maxdepth: 2 diff --git a/doc/guides/howto/lm_bond_virtio_sriov.rst b/doc/guides/howto/lm_bond_virtio_sriov.rst index 49666f13..fe9803e4 100644 --- a/doc/guides/howto/lm_bond_virtio_sriov.rst +++ b/doc/guides/howto/lm_bond_virtio_sriov.rst @@ -142,7 +142,7 @@ Bonding is port 2 (P2). .. code-block:: console testpmd> create bonded device 1 0 - Created new bonded device eth_bond_testpmd_0 on (port 2). + Created new bonded device net_bond_testpmd_0 on (port 2). testpmd> add bonding slave 0 2 testpmd> add bonding slave 1 2 testpmd> show bonding config 2 @@ -613,17 +613,17 @@ Set up DPDK in the Virtual Machine cat /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages ifconfig -a - /root/dpdk/tools/dpdk_nic_bind.py --status + /root/dpdk/tools/dpdk-devbind.py --status rmmod virtio-pci ixgbevf modprobe uio insmod /root/dpdk/x86_64-default-linuxapp-gcc/kmod/igb_uio.ko - /root/dpdk/tools/dpdk_nic_bind.py -b igb_uio 0000:00:03.0 - /root/dpdk/tools/dpdk_nic_bind.py -b igb_uio 0000:00:04.0 + /root/dpdk/tools/dpdk-devbind.py -b igb_uio 0000:00:03.0 + /root/dpdk/tools/dpdk-devbind.py -b igb_uio 0000:00:04.0 - /root/dpdk/tools/dpdk_nic_bind.py --status + /root/dpdk/tools/dpdk-devbind.py --status run_testpmd_bonding_in_vm.sh ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/guides/howto/lm_virtio_vhost_user.rst b/doc/guides/howto/lm_virtio_vhost_user.rst index fad1f2a8..49377818 100644 --- a/doc/guides/howto/lm_virtio_vhost_user.rst +++ b/doc/guides/howto/lm_virtio_vhost_user.rst @@ -91,14 +91,14 @@ For Fortville NIC. .. code-block:: console cd /root/dpdk/tools - ./dpdk_nic_bind.py -b igb_uio 0000:02:00.0 + ./dpdk-devbind.py -b igb_uio 0000:02:00.0 For Niantic NIC. .. code-block:: console cd /root/dpdk/tools - ./dpdk_nic_bind.py -b igb_uio 0000:09:00.0 + ./dpdk-devbind.py -b igb_uio 0000:09:00.0 On host_server_1: Terminal 3 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -172,14 +172,14 @@ For Fortville NIC. .. code-block:: console cd /root/dpdk/tools - ./dpdk_nic_bind.py -b igb_uio 0000:03:00.0 + ./dpdk-devbind.py -b igb_uio 0000:03:00.0 For Niantic NIC. .. code-block:: console cd /root/dpdk/tools - ./dpdk_nic_bind.py -b igb_uio 0000:06:00.0 + ./dpdk-devbind.py -b igb_uio 0000:06:00.0 On host_server_2: Terminal 3 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -444,17 +444,17 @@ setup_dpdk_virtio_in_vm.sh cat /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages ifconfig -a - /root/dpdk/tools/dpdk_nic_bind.py --status + /root/dpdk/tools/dpdk-devbind.py --status rmmod virtio-pci modprobe uio insmod /root/dpdk/x86_64-default-linuxapp-gcc/kmod/igb_uio.ko - /root/dpdk/tools/dpdk_nic_bind.py -b igb_uio 0000:00:03.0 - /root/dpdk/tools/dpdk_nic_bind.py -b igb_uio 0000:00:04.0 + /root/dpdk/tools/dpdk-devbind.py -b igb_uio 0000:00:03.0 + /root/dpdk/tools/dpdk-devbind.py -b igb_uio 0000:00:04.0 - /root/dpdk/tools/dpdk_nic_bind.py --status + /root/dpdk/tools/dpdk-devbind.py --status run_testpmd_in_vm.sh ~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/guides/index.rst b/doc/guides/index.rst index 04418599..82b00e97 100644 --- a/doc/guides/index.rst +++ b/doc/guides/index.rst @@ -36,13 +36,14 @@ DPDK documentation linux_gsg/index freebsd_gsg/index - xen/index + sample_app_ug/index prog_guide/index + howto/index + tools/index + testpmd_app_ug/index nics/index cryptodevs/index - sample_app_ug/index - testpmd_app_ug/index - faq/index - howto/index - rel_notes/index + xen/index contributing/index + rel_notes/index + faq/index diff --git a/doc/guides/linux_gsg/build_dpdk.rst b/doc/guides/linux_gsg/build_dpdk.rst index f8007b31..527c38dc 100644 --- a/doc/guides/linux_gsg/build_dpdk.rst +++ b/doc/guides/linux_gsg/build_dpdk.rst @@ -48,10 +48,6 @@ First, uncompress the archive and move to the uncompressed DPDK source directory unzip DPDK-<version>.zip cd DPDK-<version> - ls - app/ config/ examples/ lib/ LICENSE.GPL LICENSE.LGPL Makefile - mk/ scripts/ tools/ - The DPDK is composed of several directories: * lib: Source code of DPDK libraries @@ -75,7 +71,7 @@ where: * ``ARCH`` can be: ``i686``, ``x86_64``, ``ppc_64`` -* ``MACHINE`` can be: ``native``, ``ivshmem``, ``power8`` +* ``MACHINE`` can be: ``native``, ``power8`` * ``EXECENV`` can be: ``linuxapp``, ``bsdapp`` @@ -148,12 +144,6 @@ Once a target is created it contains all libraries, including poll-mode drivers, In addition, the test and testpmd applications are built under the build/app directory, which may be used for testing. A kmod directory is also present that contains kernel modules which may be loaded if needed. -.. code-block:: console - - ls x86_64-native-linuxapp-gcc - - app build include kmod lib Makefile - Loading Modules to Enable Userspace IO for DPDK ----------------------------------------------- diff --git a/doc/guides/linux_gsg/quick_start.rst b/doc/guides/linux_gsg/quick_start.rst index 8789b588..6e858c2a 100644 --- a/doc/guides/linux_gsg/quick_start.rst +++ b/doc/guides/linux_gsg/quick_start.rst @@ -126,19 +126,15 @@ Some options in the script prompt the user for further data before proceeding. [3] ppc_64-power8-linuxapp-gcc - [4] x86_64-ivshmem-linuxapp-gcc + [4] x86_64-native-bsdapp-clang - [5] x86_64-ivshmem-linuxapp-icc + [5] x86_64-native-bsdapp-gcc - [6] x86_64-native-bsdapp-clang + [6] x86_64-native-linuxapp-clang - [7] x86_64-native-bsdapp-gcc + [7] x86_64-native-linuxapp-gcc - [8] x86_64-native-linuxapp-clang - - [9] x86_64-native-linuxapp-gcc - - [10] x86_64-native-linuxapp-icc + [8] x86_64-native-linuxapp-icc ------------------------------------------------------------------------ diff --git a/doc/guides/linux_gsg/sys_reqs.rst b/doc/guides/linux_gsg/sys_reqs.rst index b3215448..3d743421 100644 --- a/doc/guides/linux_gsg/sys_reqs.rst +++ b/doc/guides/linux_gsg/sys_reqs.rst @@ -61,8 +61,8 @@ Compilation of the DPDK * coreutils: ``cmp``, ``sed``, ``grep``, ``arch``, etc. -* gcc: versions 4.5.x or later is recommended for ``i686/x86_64``. Versions 4.8.x or later is recommended - for ``ppc_64`` and ``x86_x32`` ABI. On some distributions, some specific compiler flags and linker flags are enabled by +* gcc: versions 4.9 or later is recommended for all platforms. + On some distributions, some specific compiler flags and linker flags are enabled by default and affect performance (``-fstack-protector``, for example). Please refer to the documentation of your distribution and to ``gcc -dumpspecs``. @@ -82,7 +82,7 @@ Compilation of the DPDK .. note:: x86_x32 ABI is currently supported with distribution packages only on Ubuntu - higher than 13.10 or recent Debian distribution. The only supported compiler is gcc 4.8+. + higher than 13.10 or recent Debian distribution. The only supported compiler is gcc 4.9+. .. note:: diff --git a/doc/guides/nics/bnx2x.rst b/doc/guides/nics/bnx2x.rst index 6453168e..6d1768a5 100644 --- a/doc/guides/nics/bnx2x.rst +++ b/doc/guides/nics/bnx2x.rst @@ -162,7 +162,7 @@ To compile BNX2X PMD for FreeBSD x86_64 gcc target, run the following "gmake" command:: cd <DPDK-source-directory> - gmake config T=x86_64-native-bsdapp-gcc install -Wl,-rpath=/usr/local/lib/gcc48 CC=gcc48 + gmake config T=x86_64-native-bsdapp-gcc install -Wl,-rpath=/usr/local/lib/gcc49 CC=gcc49 To compile BNX2X PMD for FreeBSD x86_64 gcc target, run the following "gmake" command: @@ -170,7 +170,7 @@ command: .. code-block:: console cd <DPDK-source-directory> - gmake config T=x86_64-native-bsdapp-gcc install -Wl,-rpath=/usr/local/lib/gcc48 CC=gcc48 + gmake config T=x86_64-native-bsdapp-gcc install -Wl,-rpath=/usr/local/lib/gcc49 CC=gcc49 Linux ----- diff --git a/doc/guides/nics/bnxt.rst b/doc/guides/nics/bnxt.rst index 2669e984..ad33cd5d 100644 --- a/doc/guides/nics/bnxt.rst +++ b/doc/guides/nics/bnxt.rst @@ -27,16 +27,33 @@ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -bnxt poll mode driver library -============================= +BNXT Poll Mode Driver +===================== -The bnxt poll mode library (**librte_pmd_bnxt**) implements support for -**Broadcom NetXtreme® C-Series**. These adapters support Standards- -compliant 10/25/50Gbps 30MPPS full-duplex throughput. +The bnxt poll mode library (**librte_pmd_bnxt**) implements support for: -Information about this family of adapters can be found in the -`NetXtreme® Brand section <https://www.broadcom.com/products/ethernet-communication-and-switching?technology%5B%5D=88>`_ -of the `Broadcom web site <http://www.broadcom.com/>`_. + * **Broadcom NetXtreme-C®/NetXtreme-E® BCM5730X and BCM5740X family of + Ethernet Network Controllers** + + These adapters support Standards compliant 10/25/50Gbps 30MPPS + full-duplex throughput. + + Information about the NetXtreme family of adapters can be found in the + `NetXtreme® Brand section + <https://www.broadcom.com/products/ethernet-communication-and-switching?technology%5B%5D=88>`_ + of the `Broadcom website <http://www.broadcom.com/>`_. + + * **Broadcom StrataGX® BCM5871X Series of Communucations Processors** + + These ARM based processors target a broad range of networking applications + including virtual CPE (vCPE) and NFV appliances, 10G service routers and + gateways, control plane processing for Ethernet switches and network + attached storage (NAS). + + Information about the StrataGX family of adapters can be found in the + `StrataGX® BCM5871X Series section + <http://www.broadcom.com/products/enterprise-and-network-processors/processors/bcm58712>`_ + of the `Broadcom website <http://www.broadcom.com/>`_. Limitations ----------- @@ -45,5 +62,3 @@ With the current driver, allocated mbufs must be large enough to hold the entire received frame. If the mbufs are not large enough, the packets will be dropped. This is most limiting when jumbo frames are used. - -SR-IOV is not supported. diff --git a/doc/guides/nics/enic.rst b/doc/guides/nics/enic.rst index 26692022..c535b589 100644 --- a/doc/guides/nics/enic.rst +++ b/doc/guides/nics/enic.rst @@ -119,7 +119,26 @@ Configuration information Only one interrupt per vNIC interface should be configured in the UCS manager regardless of the number receive/transmit queues. The ENIC PMD - uses this interrupt to get information about errors in the fast path. + uses this interrupt to get information about link status and errors + in the fast path. + +.. _enic-flow-director: + +Flow director support +--------------------- + +Advanced filtering support was added to 1300 series VIC firmware starting +with version 2.0.13 for C-series UCS servers and version 3.1.2 for UCSM +managed blade servers. In order to enable advanced filtering the 'Advanced +filter' radio button should be enabled via CIMC or UCSM followed by a reboot +of the server. + +With advanced filters, perfect matching of all fields of IPv4, IPv6 headers +as well as TCP, UDP and SCTP L4 headers is available through flow director. +Masking of these feilds for partial match is also supported. + +Without advanced filter support, the flow director is limited to IPv4 +perfect filtering of the 5-tuple with no masking of fields supported. Limitations ----------- @@ -144,6 +163,12 @@ Limitations vlan_offload |= ETH_VLAN_STRIP_OFFLOAD; rte_eth_dev_set_vlan_offload(port, vlan_offload); +- Limited flow director support on 1200 series and 1300 series Cisco VIC + adapters with old firmware. Please see :ref:`enic-flow-director`. + +- Flow director features are not supported on generation 1 Cisco VIC adapters + (M81KR and P81E) + How to build the suite? ----------------------- The build instructions for the DPDK suite should be followed. By default @@ -169,9 +194,6 @@ ENIC PMD supports all recent generations of Cisco VIC adapters including: - VIC 1385 - VIC 1387 -- Flow director features are not supported on generation 1 Cisco VIC adapters - (M81KR and P81E) - Supported Operating Systems --------------------------- Any Linux distribution fulfilling the conditions described in Dependencies @@ -186,8 +208,7 @@ Supported features - IP checksum offload - Receive side VLAN stripping - Multiple receive and transmit queues -- Flow Director ADD, UPDATE, DELETE, STATS operation support for IPV4 5-TUPLE - flows +- Flow Director ADD, UPDATE, DELETE, STATS operation support IPv4 and IPv6 - Promiscuous mode - Setting RX VLAN (supported via UCSM/CIMC only) - VLAN filtering (supported via UCSM/CIMC only) diff --git a/doc/guides/nics/features/afpacket.ini b/doc/guides/nics/features/afpacket.ini new file mode 100644 index 00000000..99f87ab6 --- /dev/null +++ b/doc/guides/nics/features/afpacket.ini @@ -0,0 +1,6 @@ +; +; Supported features of the 'afpacket' network poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] diff --git a/doc/guides/nics/features/bnx2x.ini b/doc/guides/nics/features/bnx2x.ini new file mode 100644 index 00000000..1ad8a3e8 --- /dev/null +++ b/doc/guides/nics/features/bnx2x.ini @@ -0,0 +1,16 @@ +; +; Supported features of the 'bnx2x' network poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Link status = Y +Link status event = Y +Promiscuous mode = Y +Unicast MAC filter = Y +Multicast MAC filter = Y +Basic stats = Y +Extended stats = Y +Linux UIO = Y +x86-64 = Y +Usage doc = Y diff --git a/doc/guides/nics/features/bnx2x_vf.ini b/doc/guides/nics/features/bnx2x_vf.ini new file mode 100644 index 00000000..da9168ea --- /dev/null +++ b/doc/guides/nics/features/bnx2x_vf.ini @@ -0,0 +1,17 @@ +; +; Supported features of the 'bnx2x_vf' network poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Link status = Y +Link status event = Y +Promiscuous mode = Y +Unicast MAC filter = Y +Multicast MAC filter = Y +SR-IOV = Y +Basic stats = Y +Extended stats = Y +Linux UIO = Y +x86-64 = Y +Usage doc = Y diff --git a/doc/guides/nics/features/bnxt.ini b/doc/guides/nics/features/bnxt.ini new file mode 100644 index 00000000..013a9cda --- /dev/null +++ b/doc/guides/nics/features/bnxt.ini @@ -0,0 +1,16 @@ +; +; Supported features of the 'bnxt' network poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Link status = Y +Queue start/stop = Y +Promiscuous mode = Y +Unicast MAC filter = Y +Multicast MAC filter = Y +RSS reta update = Y +Basic stats = Y +Extended stats = Y +Linux UIO = Y +x86-64 = Y diff --git a/doc/guides/nics/features/bonding.ini b/doc/guides/nics/features/bonding.ini new file mode 100644 index 00000000..c1653051 --- /dev/null +++ b/doc/guides/nics/features/bonding.ini @@ -0,0 +1,6 @@ +; +; Supported features of the 'bonding' network poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] diff --git a/doc/guides/nics/features/cxgbe.ini b/doc/guides/nics/features/cxgbe.ini new file mode 100644 index 00000000..2e72a107 --- /dev/null +++ b/doc/guides/nics/features/cxgbe.ini @@ -0,0 +1,31 @@ +; +; Supported features of the 'cxgbe' network poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Link status = Y +Queue start/stop = Y +MTU update = Y +Jumbo frame = Y +Scattered Rx = Y +TSO = Y +Promiscuous mode = Y +Allmulticast mode = Y +RSS hash = Y +Flow control = Y +CRC offload = Y +VLAN offload = Y +L3 checksum offload = Y +L4 checksum offload = Y +Packet type parsing = Y +Basic stats = Y +Stats per queue = Y +EEPROM dump = Y +Registers dump = Y +BSD nic_uio = Y +Linux UIO = Y +Linux VFIO = Y +x86-32 = Y +x86-64 = Y +Usage doc = Y diff --git a/doc/guides/nics/features/default.ini b/doc/guides/nics/features/default.ini new file mode 100644 index 00000000..f1bf9bf2 --- /dev/null +++ b/doc/guides/nics/features/default.ini @@ -0,0 +1,68 @@ +; +; Features of a default network 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] +Speed capabilities = +Link status = +Link status event = +Queue status event = +Rx interrupt = +Queue start/stop = +MTU update = +Jumbo frame = +Scattered Rx = +LRO = +TSO = +Promiscuous mode = +Allmulticast mode = +Unicast MAC filter = +Multicast MAC filter = +RSS hash = +RSS key update = +RSS reta update = +VMDq = +SR-IOV = +DCB = +VLAN filter = +Ethertype filter = +N-tuple filter = +SYN filter = +Tunnel filter = +Flexible filter = +Hash filter = +Flow director = +Flow control = +Rate limitation = +Traffic mirroring = +CRC offload = +VLAN offload = +QinQ offload = +L3 checksum offload = +L4 checksum offload = +Inner L3 checksum = +Inner L4 checksum = +Packet type parsing = +Timesync = +Basic stats = +Extended stats = +Stats per queue = +EEPROM dump = +Registers dump = +Multiprocess aware = +BSD nic_uio = +Linux UIO = +Linux VFIO = +Other kdrv = +ARMv7 = +ARMv8 = +Power8 = +TILE-Gx = +x86-32 = +x86-64 = +Usage doc = +Design doc = +Perf doc = diff --git a/doc/guides/nics/features/e1000.ini b/doc/guides/nics/features/e1000.ini new file mode 100644 index 00000000..7f6d55c4 --- /dev/null +++ b/doc/guides/nics/features/e1000.ini @@ -0,0 +1,28 @@ +; +; Supported features of the 'e1000' network poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Link status = Y +Link status event = Y +Rx interrupt = Y +MTU update = Y +Jumbo frame = Y +Scattered Rx = Y +Promiscuous mode = Y +Allmulticast mode = Y +Unicast MAC filter = Y +VLAN filter = Y +Flow control = Y +CRC offload = Y +VLAN offload = Y +QinQ offload = Y +L3 checksum offload = Y +L4 checksum offload = Y +Basic stats = Y +BSD nic_uio = Y +Linux UIO = Y +Linux VFIO = Y +x86-32 = Y +x86-64 = Y diff --git a/doc/guides/nics/features/ena.ini b/doc/guides/nics/features/ena.ini new file mode 100644 index 00000000..74969fd0 --- /dev/null +++ b/doc/guides/nics/features/ena.ini @@ -0,0 +1,26 @@ +; +; Supported features of the 'ena' network poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Queue start/stop = Y +MTU update = Y +Jumbo frame = Y +Scattered Rx = Y +TSO = Y +RSS hash = Y +RSS key update = Y +RSS reta update = Y +SR-IOV = Y +CRC offload = Y +VLAN offload = Y +L3 checksum offload = Y +L4 checksum offload = Y +Inner L3 checksum = Y +Inner L4 checksum = Y +Basic stats = Y +Extended stats = Y +Linux UIO = Y +x86-32 = Y +x86-64 = Y diff --git a/doc/guides/nics/features/enic.ini b/doc/guides/nics/features/enic.ini new file mode 100644 index 00000000..86576a75 --- /dev/null +++ b/doc/guides/nics/features/enic.ini @@ -0,0 +1,30 @@ +; +; Supported features of the 'enic' network poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Link status = Y +Link status event = Y +Queue start/stop = Y +MTU update = Y +Jumbo frame = Y +Scattered Rx = Y +Promiscuous mode = Y +Unicast MAC filter = Y +Multicast MAC filter = Y +RSS hash = Y +VLAN filter = Y +CRC offload = Y +VLAN offload = Y +Flow director = Y +L3 checksum offload = Y +L4 checksum offload = Y +Packet type parsing = Y +Basic stats = Y +BSD nic_uio = Y +Linux UIO = Y +Linux VFIO = Y +x86-32 = Y +x86-64 = Y +Usage doc = Y diff --git a/doc/guides/nics/features/fm10k.ini b/doc/guides/nics/features/fm10k.ini new file mode 100644 index 00000000..9e1035f3 --- /dev/null +++ b/doc/guides/nics/features/fm10k.ini @@ -0,0 +1,34 @@ +; +; Supported features of the 'fm10k' network poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Rx interrupt = Y +Queue start/stop = Y +Jumbo frame = Y +Scattered Rx = Y +TSO = Y +Promiscuous mode = Y +Allmulticast mode = Y +Unicast MAC filter = Y +Multicast MAC filter = Y +RSS hash = Y +RSS key update = Y +RSS reta update = Y +VMDq = Y +VLAN filter = Y +CRC offload = Y +VLAN offload = Y +L3 checksum offload = Y +L4 checksum offload = Y +Packet type parsing = Y +Basic stats = Y +Extended stats = Y +Stats per queue = Y +Multiprocess aware = Y +BSD nic_uio = Y +Linux UIO = Y +Linux VFIO = Y +x86-32 = Y +x86-64 = Y diff --git a/doc/guides/nics/features/fm10k_vec.ini b/doc/guides/nics/features/fm10k_vec.ini new file mode 100644 index 00000000..1384ab15 --- /dev/null +++ b/doc/guides/nics/features/fm10k_vec.ini @@ -0,0 +1,34 @@ +; +; Supported features of the 'fm10k_vec' network poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Rx interrupt = Y +Queue start/stop = Y +Jumbo frame = Y +Scattered Rx = Y +TSO = Y +Promiscuous mode = Y +Allmulticast mode = Y +Unicast MAC filter = Y +Multicast MAC filter = Y +RSS hash = Y +RSS key update = Y +RSS reta update = Y +VMDq = Y +VLAN filter = Y +CRC offload = Y +VLAN offload = Y +L3 checksum offload = Y +L4 checksum offload = Y +Packet type parsing = Y +Basic stats = Y +Extended stats = Y +Stats per queue = Y +Multiprocess aware = Y +BSD nic_uio = Y +Linux UIO = Y +Linux VFIO = Y +x86-32 = Y +x86-64 = Y diff --git a/doc/guides/nics/features/fm10k_vf.ini b/doc/guides/nics/features/fm10k_vf.ini new file mode 100644 index 00000000..15de536f --- /dev/null +++ b/doc/guides/nics/features/fm10k_vf.ini @@ -0,0 +1,28 @@ +; +; Supported features of the 'fm10k_vf' network poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Rx interrupt = Y +Queue start/stop = Y +Jumbo frame = Y +Scattered Rx = Y +TSO = Y +RSS hash = Y +RSS key update = Y +RSS reta update = Y +CRC offload = Y +VLAN offload = Y +L3 checksum offload = Y +L4 checksum offload = Y +Packet type parsing = Y +Basic stats = Y +Extended stats = Y +Stats per queue = Y +Multiprocess aware = Y +BSD nic_uio = Y +Linux UIO = Y +Linux VFIO = Y +x86-32 = Y +x86-64 = Y diff --git a/doc/guides/nics/features/fm10k_vf_vec.ini b/doc/guides/nics/features/fm10k_vf_vec.ini new file mode 100644 index 00000000..b32550cb --- /dev/null +++ b/doc/guides/nics/features/fm10k_vf_vec.ini @@ -0,0 +1,28 @@ +; +; Supported features of the 'fm10kvf_vec' network poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Rx interrupt = Y +Queue start/stop = Y +Jumbo frame = Y +Scattered Rx = Y +TSO = Y +RSS hash = Y +RSS key update = Y +RSS reta update = Y +CRC offload = Y +VLAN offload = Y +L3 checksum offload = Y +L4 checksum offload = Y +Packet type parsing = Y +Basic stats = Y +Extended stats = Y +Stats per queue = Y +Multiprocess aware = Y +BSD nic_uio = Y +Linux UIO = Y +Linux VFIO = Y +x86-32 = Y +x86-64 = Y diff --git a/doc/guides/nics/features/i40e.ini b/doc/guides/nics/features/i40e.ini new file mode 100644 index 00000000..0d143bca --- /dev/null +++ b/doc/guides/nics/features/i40e.ini @@ -0,0 +1,48 @@ +; +; Supported features of the 'i40e' network poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Link status = Y +Link status event = Y +Rx interrupt = Y +Queue start/stop = Y +Jumbo frame = Y +Scattered Rx = Y +TSO = Y +Promiscuous mode = Y +Allmulticast mode = Y +Unicast MAC filter = Y +Multicast MAC filter = Y +RSS hash = Y +RSS key update = Y +RSS reta update = Y +VMDq = Y +SR-IOV = Y +DCB = Y +VLAN filter = Y +Ethertype filter = Y +Tunnel filter = Y +Hash filter = Y +Flow director = Y +Flow control = Y +Traffic mirroring = Y +CRC offload = Y +VLAN offload = Y +QinQ offload = Y +L3 checksum offload = Y +L4 checksum offload = Y +Inner L3 checksum = Y +Inner L4 checksum = Y +Packet type parsing = Y +Timesync = Y +Basic stats = Y +Extended stats = Y +Multiprocess aware = Y +BSD nic_uio = Y +Linux UIO = Y +Linux VFIO = Y +x86-32 = Y +x86-64 = Y +ARMv8 = Y diff --git a/doc/guides/nics/features/i40e_vec.ini b/doc/guides/nics/features/i40e_vec.ini new file mode 100644 index 00000000..edd6b717 --- /dev/null +++ b/doc/guides/nics/features/i40e_vec.ini @@ -0,0 +1,40 @@ +; +; Supported features of the 'i40e_vec' network poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Link status = Y +Link status event = Y +Rx interrupt = Y +Queue start/stop = Y +Jumbo frame = Y +Scattered Rx = Y +TSO = Y +Promiscuous mode = Y +Allmulticast mode = Y +Unicast MAC filter = Y +Multicast MAC filter = Y +RSS hash = Y +RSS key update = Y +RSS reta update = Y +VMDq = Y +SR-IOV = Y +DCB = Y +VLAN filter = Y +Ethertype filter = Y +Tunnel filter = Y +Hash filter = Y +Flow director = Y +Flow control = Y +Traffic mirroring = Y +Timesync = Y +Basic stats = Y +Extended stats = Y +Multiprocess aware = Y +BSD nic_uio = Y +Linux UIO = Y +Linux VFIO = Y +x86-32 = Y +x86-64 = Y +ARMv8 = Y diff --git a/doc/guides/nics/features/i40e_vf.ini b/doc/guides/nics/features/i40e_vf.ini new file mode 100644 index 00000000..2f82c6b9 --- /dev/null +++ b/doc/guides/nics/features/i40e_vf.ini @@ -0,0 +1,36 @@ +; +; Supported features of the 'i40e_vf' network poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Rx interrupt = Y +Queue start/stop = Y +Jumbo frame = Y +Scattered Rx = Y +TSO = Y +Promiscuous mode = Y +Allmulticast mode = Y +Unicast MAC filter = Y +Multicast MAC filter = Y +RSS hash = Y +RSS key update = Y +RSS reta update = Y +VLAN filter = Y +Hash filter = Y +CRC offload = Y +VLAN offload = Y +QinQ offload = Y +L3 checksum offload = Y +L4 checksum offload = Y +Inner L3 checksum = Y +Inner L4 checksum = Y +Packet type parsing = Y +Basic stats = Y +Extended stats = Y +Multiprocess aware = Y +BSD nic_uio = Y +Linux UIO = Y +Linux VFIO = Y +x86-32 = Y +x86-64 = Y diff --git a/doc/guides/nics/features/i40e_vf_vec.ini b/doc/guides/nics/features/i40e_vf_vec.ini new file mode 100644 index 00000000..d6674f76 --- /dev/null +++ b/doc/guides/nics/features/i40e_vf_vec.ini @@ -0,0 +1,29 @@ +; +; Supported features of the 'i40evf_vec' network poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Rx interrupt = Y +Queue start/stop = Y +Jumbo frame = Y +Scattered Rx = Y +TSO = Y +Promiscuous mode = Y +Allmulticast mode = Y +Unicast MAC filter = Y +Multicast MAC filter = Y +RSS hash = Y +RSS key update = Y +RSS reta update = Y +VLAN filter = Y +Hash filter = Y +Basic stats = Y +Extended stats = Y +Multiprocess aware = Y +BSD nic_uio = Y +Linux UIO = Y +Linux VFIO = Y +x86-32 = Y +x86-64 = Y +ARMv8 = Y diff --git a/doc/guides/nics/features/igb.ini b/doc/guides/nics/features/igb.ini new file mode 100644 index 00000000..9fafe72d --- /dev/null +++ b/doc/guides/nics/features/igb.ini @@ -0,0 +1,44 @@ +; +; Supported features of the 'igb' network poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Link status = Y +Link status event = Y +Rx interrupt = Y +MTU update = Y +Jumbo frame = Y +Scattered Rx = Y +TSO = Y +Promiscuous mode = Y +Allmulticast mode = Y +Unicast MAC filter = Y +RSS hash = Y +RSS key update = Y +RSS reta update = Y +VMDq = Y +SR-IOV = Y +DCB = Y +VLAN filter = Y +Ethertype filter = Y +N-tuple filter = Y +SYN filter = Y +Flexible filter = Y +Flow control = Y +CRC offload = Y +VLAN offload = Y +QinQ offload = Y +L3 checksum offload = Y +L4 checksum offload = Y +Packet type parsing = Y +Timesync = Y +Basic stats = Y +Extended stats = Y +EEPROM dump = Y +Registers dump = Y +BSD nic_uio = Y +Linux UIO = Y +Linux VFIO = Y +x86-32 = Y +x86-64 = Y diff --git a/doc/guides/nics/features/igb_vf.ini b/doc/guides/nics/features/igb_vf.ini new file mode 100644 index 00000000..b6178202 --- /dev/null +++ b/doc/guides/nics/features/igb_vf.ini @@ -0,0 +1,27 @@ +; +; Supported features of the 'igb_vf' network poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Rx interrupt = Y +Scattered Rx = Y +TSO = Y +Promiscuous mode = Y +Allmulticast mode = Y +Unicast MAC filter = Y +VLAN filter = Y +CRC offload = Y +VLAN offload = Y +QinQ offload = Y +L3 checksum offload = Y +L4 checksum offload = Y +Packet type parsing = Y +Basic stats = Y +Extended stats = Y +Registers dump = Y +BSD nic_uio = Y +Linux UIO = Y +Linux VFIO = Y +x86-32 = Y +x86-64 = Y diff --git a/doc/guides/nics/features/ixgbe.ini b/doc/guides/nics/features/ixgbe.ini new file mode 100644 index 00000000..4a5667f0 --- /dev/null +++ b/doc/guides/nics/features/ixgbe.ini @@ -0,0 +1,54 @@ +; +; Supported features of the 'ixgbe' network poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Link status = Y +Link status event = Y +Rx interrupt = Y +Queue start/stop = Y +MTU update = Y +Jumbo frame = Y +Scattered Rx = Y +LRO = Y +TSO = Y +Promiscuous mode = Y +Allmulticast mode = Y +Unicast MAC filter = Y +RSS hash = Y +RSS key update = Y +RSS reta update = Y +VMDq = Y +SR-IOV = Y +DCB = Y +VLAN filter = Y +Ethertype filter = Y +N-tuple filter = Y +SYN filter = Y +Tunnel filter = Y +Flow director = Y +Flow control = Y +Rate limitation = Y +Traffic mirroring = Y +CRC offload = Y +VLAN offload = Y +QinQ offload = Y +L3 checksum offload = Y +L4 checksum offload = Y +Inner L3 checksum = Y +Inner L4 checksum = Y +Packet type parsing = Y +Timesync = Y +Basic stats = Y +Extended stats = Y +Stats per queue = Y +EEPROM dump = Y +Registers dump = Y +Multiprocess aware = Y +BSD nic_uio = Y +Linux UIO = Y +Linux VFIO = Y +ARMv8 = Y +x86-32 = Y +x86-64 = Y diff --git a/doc/guides/nics/features/ixgbe_vec.ini b/doc/guides/nics/features/ixgbe_vec.ini new file mode 100644 index 00000000..e1773dd6 --- /dev/null +++ b/doc/guides/nics/features/ixgbe_vec.ini @@ -0,0 +1,46 @@ +; +; Supported features of the 'ixgbe_vec' network poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Link status = Y +Link status event = Y +Rx interrupt = Y +Queue start/stop = Y +MTU update = Y +Jumbo frame = Y +Scattered Rx = Y +LRO = Y +TSO = Y +Promiscuous mode = Y +Allmulticast mode = Y +Unicast MAC filter = Y +RSS hash = Y +RSS key update = Y +RSS reta update = Y +VMDq = Y +SR-IOV = Y +DCB = Y +VLAN filter = Y +Ethertype filter = Y +N-tuple filter = Y +SYN filter = Y +Tunnel filter = Y +Flow director = Y +Flow control = Y +Rate limitation = Y +Traffic mirroring = Y +Timesync = Y +Basic stats = Y +Extended stats = Y +Stats per queue = Y +EEPROM dump = Y +Registers dump = Y +Multiprocess aware = Y +BSD nic_uio = Y +Linux UIO = Y +Linux VFIO = Y +ARMv8 = Y +x86-32 = Y +x86-64 = Y diff --git a/doc/guides/nics/features/ixgbe_vf.ini b/doc/guides/nics/features/ixgbe_vf.ini new file mode 100644 index 00000000..bf28215d --- /dev/null +++ b/doc/guides/nics/features/ixgbe_vf.ini @@ -0,0 +1,37 @@ +; +; Supported features of the 'ixgbe_vf' network poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Link status = Y +Rx interrupt = Y +MTU update = Y +Jumbo frame = Y +Scattered Rx = Y +LRO = Y +TSO = Y +Allmulticast mode = Y +Unicast MAC filter = Y +RSS hash = Y +RSS key update = Y +RSS reta update = Y +VLAN filter = Y +CRC offload = Y +VLAN offload = Y +QinQ offload = Y +L3 checksum offload = Y +L4 checksum offload = Y +Inner L3 checksum = Y +Inner L4 checksum = Y +Packet type parsing = Y +Basic stats = Y +Extended stats = Y +Registers dump = Y +Multiprocess aware = Y +BSD nic_uio = Y +Linux UIO = Y +Linux VFIO = Y +ARMv8 = Y +x86-32 = Y +x86-64 = Y diff --git a/doc/guides/nics/features/ixgbe_vf_vec.ini b/doc/guides/nics/features/ixgbe_vf_vec.ini new file mode 100644 index 00000000..8b8c90ba --- /dev/null +++ b/doc/guides/nics/features/ixgbe_vf_vec.ini @@ -0,0 +1,29 @@ +; +; Supported features of the 'ixgbevf_vec' network poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Link status = Y +Rx interrupt = Y +MTU update = Y +Jumbo frame = Y +Scattered Rx = Y +LRO = Y +TSO = Y +Allmulticast mode = Y +Unicast MAC filter = Y +RSS hash = Y +RSS key update = Y +RSS reta update = Y +VLAN filter = Y +Basic stats = Y +Extended stats = Y +Registers dump = Y +Multiprocess aware = Y +BSD nic_uio = Y +Linux UIO = Y +Linux VFIO = Y +ARMv8 = Y +x86-32 = Y +x86-64 = Y diff --git a/doc/guides/nics/features/mlx4.ini b/doc/guides/nics/features/mlx4.ini new file mode 100644 index 00000000..c9828f71 --- /dev/null +++ b/doc/guides/nics/features/mlx4.ini @@ -0,0 +1,32 @@ +; +; Supported features of the 'mlx4' network poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Link status = Y +Link status event = Y +Queue start/stop = Y +MTU update = Y +Jumbo frame = Y +Scattered Rx = Y +Promiscuous mode = Y +Allmulticast mode = Y +Unicast MAC filter = Y +Multicast MAC filter = Y +RSS hash = Y +SR-IOV = Y +VLAN filter = Y +L3 checksum offload = Y +L4 checksum offload = Y +Inner L3 checksum = Y +Inner L4 checksum = Y +Packet type parsing = Y +Basic stats = Y +Stats per queue = Y +Multiprocess aware = Y +Other kdrv = Y +Power8 = Y +x86-32 = Y +x86-64 = Y +Usage doc = Y diff --git a/doc/guides/nics/features/mlx5.ini b/doc/guides/nics/features/mlx5.ini new file mode 100644 index 00000000..f811e3fb --- /dev/null +++ b/doc/guides/nics/features/mlx5.ini @@ -0,0 +1,36 @@ +; +; Supported features of the 'mlx5' network poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Speed capabilities = Y +Link status = Y +Link status event = Y +Queue start/stop = Y +MTU update = Y +Jumbo frame = Y +Scattered Rx = Y +Promiscuous mode = Y +Allmulticast mode = Y +Unicast MAC filter = Y +Multicast MAC filter = Y +RSS hash = Y +RSS key update = Y +RSS reta update = Y +SR-IOV = Y +VLAN filter = Y +Flow director = Y +CRC offload = Y +VLAN offload = Y +L3 checksum offload = Y +L4 checksum offload = Y +Packet type parsing = Y +Basic stats = Y +Stats per queue = Y +Multiprocess aware = Y +Other kdrv = Y +Power8 = Y +x86-32 = Y +x86-64 = Y +Usage doc = Y diff --git a/doc/guides/nics/features/mpipe.ini b/doc/guides/nics/features/mpipe.ini new file mode 100644 index 00000000..ca609331 --- /dev/null +++ b/doc/guides/nics/features/mpipe.ini @@ -0,0 +1,6 @@ +; +; Supported features of the 'mpipe' network poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] diff --git a/doc/guides/nics/features/nfp.ini b/doc/guides/nics/features/nfp.ini new file mode 100644 index 00000000..d9671512 --- /dev/null +++ b/doc/guides/nics/features/nfp.ini @@ -0,0 +1,6 @@ +; +; Supported features of the 'nfp' network poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] diff --git a/doc/guides/nics/features/null.ini b/doc/guides/nics/features/null.ini new file mode 100644 index 00000000..3957f7ca --- /dev/null +++ b/doc/guides/nics/features/null.ini @@ -0,0 +1,6 @@ +; +; Supported features of the 'null' network poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] diff --git a/doc/guides/nics/features/pcap.ini b/doc/guides/nics/features/pcap.ini new file mode 100644 index 00000000..8245cbfb --- /dev/null +++ b/doc/guides/nics/features/pcap.ini @@ -0,0 +1,16 @@ +; +; Supported features of the 'pcap' network poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Jumbo frame = Y +Basic stats = Y +Multiprocess aware = Y +ARMv7 = Y +ARMv8 = Y +Power8 = Y +TILE-Gx = Y +x86-32 = Y +x86-64 = Y +Usage doc = Y diff --git a/doc/guides/nics/features/qede.ini b/doc/guides/nics/features/qede.ini new file mode 100644 index 00000000..7d75030a --- /dev/null +++ b/doc/guides/nics/features/qede.ini @@ -0,0 +1,33 @@ +; +; Supported features of the 'qede' network poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Speed capabilities = Y +Link status = Y +Link status event = Y +MTU update = Y +Jumbo frame = Y +Scattered Rx = Y +Promiscuous mode = Y +Allmulticast mode = Y +Unicast MAC filter = Y +Multicast MAC filter = Y +RSS hash = Y +RSS key update = Y +RSS reta update = Y +VLAN filter = Y +Flow control = Y +CRC offload = Y +VLAN offload = Y +L3 checksum offload = Y +L4 checksum offload = Y +Packet type parsing = Y +Basic stats = Y +Extended stats = Y +Stats per queue = Y +Multiprocess aware = Y +Linux UIO = Y +x86-64 = Y +Usage doc = Y diff --git a/doc/guides/nics/features/qede_vf.ini b/doc/guides/nics/features/qede_vf.ini new file mode 100644 index 00000000..acb1b991 --- /dev/null +++ b/doc/guides/nics/features/qede_vf.ini @@ -0,0 +1,34 @@ +; +; Supported features of the 'qede_vf' network poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Speed capabilities = Y +Link status = Y +Link status event = Y +MTU update = Y +Jumbo frame = Y +Scattered Rx = Y +Promiscuous mode = Y +Allmulticast mode = Y +Unicast MAC filter = Y +Multicast MAC filter = Y +RSS hash = Y +RSS key update = Y +RSS reta update = Y +SR-IOV = Y +VLAN filter = Y +Flow control = Y +CRC offload = Y +VLAN offload = Y +L3 checksum offload = Y +L4 checksum offload = Y +Packet type parsing = Y +Basic stats = Y +Extended stats = Y +Stats per queue = Y +Multiprocess aware = Y +Linux UIO = Y +x86-64 = Y +Usage doc = Y diff --git a/doc/guides/nics/features/ring.ini b/doc/guides/nics/features/ring.ini new file mode 100644 index 00000000..ac207ba3 --- /dev/null +++ b/doc/guides/nics/features/ring.ini @@ -0,0 +1,6 @@ +; +; Supported features of the 'ring' network poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] diff --git a/doc/guides/nics/features/szedata2.ini b/doc/guides/nics/features/szedata2.ini new file mode 100644 index 00000000..624314d3 --- /dev/null +++ b/doc/guides/nics/features/szedata2.ini @@ -0,0 +1,17 @@ +; +; Supported features of the 'szedata2' network poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Link status = Y +Queue start/stop = Y +Scattered Rx = Y +Promiscuous mode = Y +Allmulticast mode = Y +Basic stats = Y +Extended stats = Y +Stats per queue = Y +Other kdrv = Y +x86-64 = Y +Usage doc = Y diff --git a/doc/guides/nics/features/thunderx.ini b/doc/guides/nics/features/thunderx.ini new file mode 100644 index 00000000..b9720be6 --- /dev/null +++ b/doc/guides/nics/features/thunderx.ini @@ -0,0 +1,30 @@ +; +; Supported features of the 'thunderx' network poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Link status = Y +Link status event = Y +Queue start/stop = Y +MTU update = Y +Jumbo frame = Y +Scattered Rx = Y +Promiscuous mode = Y +Allmulticast mode = Y +RSS hash = Y +RSS key update = Y +RSS reta update = Y +SR-IOV = Y +CRC offload = Y +VLAN offload = P +L3 checksum offload = Y +L4 checksum offload = Y +Packet type parsing = Y +Basic stats = Y +Stats per queue = Y +Registers dump = Y +Multiprocess aware = Y +Linux VFIO = Y +ARMv8 = Y +Usage doc = Y diff --git a/doc/guides/nics/features/vhost.ini b/doc/guides/nics/features/vhost.ini new file mode 100644 index 00000000..23166fba --- /dev/null +++ b/doc/guides/nics/features/vhost.ini @@ -0,0 +1,13 @@ +; +; Supported features of the 'vhost' network poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Link status = Y +Link status event = Y +Queue status event = Y +Basic stats = Y +Extended stats = Y +x86-32 = Y +x86-64 = Y diff --git a/doc/guides/nics/features/virtio.ini b/doc/guides/nics/features/virtio.ini new file mode 100644 index 00000000..41830c14 --- /dev/null +++ b/doc/guides/nics/features/virtio.ini @@ -0,0 +1,24 @@ +; +; Supported features of the 'virtio' network poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Link status = Y +Queue start/stop = Y +Scattered Rx = Y +Promiscuous mode = Y +Allmulticast mode = Y +Unicast MAC filter = Y +Multicast MAC filter = Y +VLAN filter = Y +Basic stats = Y +Stats per queue = Y +BSD nic_uio = Y +Linux UIO = Y +Linux VFIO = Y +ARMv7 = Y +ARMv8 = Y +x86-32 = Y +x86-64 = Y +Usage doc = Y diff --git a/doc/guides/nics/features/virtio_vec.ini b/doc/guides/nics/features/virtio_vec.ini new file mode 100644 index 00000000..6dc7cf02 --- /dev/null +++ b/doc/guides/nics/features/virtio_vec.ini @@ -0,0 +1,22 @@ +; +; Supported features of the 'virtio_vec' network poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Link status = Y +Queue start/stop = Y +Promiscuous mode = Y +Allmulticast mode = Y +Unicast MAC filter = Y +Multicast MAC filter = Y +VLAN filter = Y +Basic stats = Y +Stats per queue = Y +BSD nic_uio = Y +Linux UIO = Y +Linux VFIO = Y +ARMv7 = Y +ARMv8 = Y +x86-32 = Y +x86-64 = Y diff --git a/doc/guides/nics/features/vmxnet3.ini b/doc/guides/nics/features/vmxnet3.ini new file mode 100644 index 00000000..ef95932a --- /dev/null +++ b/doc/guides/nics/features/vmxnet3.ini @@ -0,0 +1,28 @@ +; +; Supported features of the 'vmxnet3' network poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Link status = Y +Link status event = Y +Queue start/stop = Y +MTU update = Y +Jumbo frame = Y +LRO = Y +TSO = Y +Promiscuous mode = Y +Allmulticast mode = Y +Unicast MAC filter = Y +RSS hash = Y +VLAN filter = Y +VLAN offload = Y +L4 checksum offload = Y +Packet type parsing = Y +Basic stats = Y +Stats per queue = Y +Linux UIO = Y +Linux VFIO = Y +x86-32 = Y +x86-64 = Y +Usage doc = Y diff --git a/doc/guides/nics/features/xenvirt.ini b/doc/guides/nics/features/xenvirt.ini new file mode 100644 index 00000000..8ab5f465 --- /dev/null +++ b/doc/guides/nics/features/xenvirt.ini @@ -0,0 +1,6 @@ +; +; Supported features of the 'xenvirt' network poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] diff --git a/doc/guides/nics/intel_vf.rst b/doc/guides/nics/intel_vf.rst index 95a79b59..9fe42093 100644 --- a/doc/guides/nics/intel_vf.rst +++ b/doc/guides/nics/intel_vf.rst @@ -486,7 +486,7 @@ The setup procedure is as follows: .. note:: - — The pci-assign,host=08:10.0 alue indicates that you want to attach a PCI device + — The pci-assign,host=08:10.0 value indicates that you want to attach a PCI device to a Virtual Machine and the respective (Bus:Device.Function) numbers should be passed for the Virtual Function to be attached. diff --git a/doc/guides/nics/ixgbe.rst b/doc/guides/nics/ixgbe.rst index 3dc6b004..3b6851b6 100644 --- a/doc/guides/nics/ixgbe.rst +++ b/doc/guides/nics/ixgbe.rst @@ -1,5 +1,5 @@ .. BSD LICENSE - Copyright(c) 2010-2014 Intel Corporation. All rights reserved. + Copyright(c) 2010-2016 Intel Corporation. All rights reserved. All rights reserved. Redistribution and use in source and binary forms, with or without @@ -147,6 +147,11 @@ The following MACROs are used for these three features: * ETH_TXQ_FLAGS_NOXSUMTCP +Application Programming Interface +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In DPDK release v16.11 an API for ixgbe specific functions has been added to the ixgbe PMD. +The declarations for the API functions are in the header ``rte_pmd_ixgbe.h``. Sample Application Notes ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -224,3 +229,35 @@ be calculated as follows: max_read_interval = ~4 mins 48 sec. In order to ensure valid results, it is recommended to poll every 4 minutes. + + +Supported Chipsets and NICs +--------------------------- + +- Intel 82599EB 10 Gigabit Ethernet Controller +- Intel 82598EB 10 Gigabit Ethernet Controller +- Intel 82599ES 10 Gigabit Ethernet Controller +- Intel 82599EN 10 Gigabit Ethernet Controller +- Intel Ethernet Controller X540-AT2 +- Intel Ethernet Controller X550-BT2 +- Intel Ethernet Controller X550-AT2 +- Intel Ethernet Controller X550-AT +- Intel Ethernet Converged Network Adapter X520-SR1 +- Intel Ethernet Converged Network Adapter X520-SR2 +- Intel Ethernet Converged Network Adapter X520-LR1 +- Intel Ethernet Converged Network Adapter X520-DA1 +- Intel Ethernet Converged Network Adapter X520-DA2 +- Intel Ethernet Converged Network Adapter X520-DA4 +- Intel Ethernet Converged Network Adapter X520-QDA1 +- Intel Ethernet Converged Network Adapter X520-T2 +- Intel 10 Gigabit AF DA Dual Port Server Adapter +- Intel 10 Gigabit AT Server Adapter +- Intel 10 Gigabit AT2 Server Adapter +- Intel 10 Gigabit CX4 Dual Port Server Adapter +- Intel 10 Gigabit XF LR Server Adapter +- Intel 10 Gigabit XF SR Dual Port Server Adapter +- Intel 10 Gigabit XF SR Server Adapter +- Intel Ethernet Converged Network Adapter X540-T1 +- Intel Ethernet Converged Network Adapter X540-T2 +- Intel Ethernet Converged Network Adapter X550-T1 +- Intel Ethernet Converged Network Adapter X550-T2 diff --git a/doc/guides/nics/mlx5.rst b/doc/guides/nics/mlx5.rst index 89231738..98d13419 100644 --- a/doc/guides/nics/mlx5.rst +++ b/doc/guides/nics/mlx5.rst @@ -88,6 +88,7 @@ Features RTE_ETH_FDIR_REJECT). - Secondary process TX is supported. - KVM and VMware ESX SR-IOV modes are supported. +- RSS hash result is supported. Limitations ----------- @@ -240,12 +241,12 @@ DPDK and must be installed separately: Currently supported by DPDK: -- Mellanox OFED **3.3-1.0.0.0** and **3.3-2.0.0.0**. +- Mellanox OFED **3.4-1.0.0.0**. -- Minimum firmware version: +- firmware version: - - ConnectX-4: **12.16.1006** - - ConnectX-4 Lx: **14.16.1006** + - ConnectX-4: **12.17.1010** + - ConnectX-4 Lx: **14.17.1010** Getting Mellanox OFED ~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/guides/nics/overview.rst b/doc/guides/nics/overview.rst index 6abbae69..2c7f5eb9 100644 --- a/doc/guides/nics/overview.rst +++ b/doc/guides/nics/overview.rst @@ -72,81 +72,7 @@ Most of these differences are summarized below. } </style> -.. table:: Features availability in networking drivers - - ==================== = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = - Feature a b b b b c e e e i i i i i i i i i i f f f f m m m n n p q q r s t v v v v x - f n n n o x 1 n n 4 4 4 4 g g x x x x m m m m l l p f u c e e i z h h i i m e - p x x x n g 0 a i 0 0 0 0 b b g g g g 1 1 1 1 x x i p l a d d n e u o r r x n - a 2 2 t d b 0 c e e e e v b b b b 0 0 0 0 4 5 p l p e e g d n s t t n v - c x x i e 0 . v v f e e e e k k k k e v a d t i i e i - k v n . f f . v v . v v f t e o o t r - e f g . . . f f . f f a r . 3 t - t v v v v v v 2 x v - e e e e e e e - c c c c c c c - ==================== = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = - Speed capabilities - Link status Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y - Link status event Y Y Y Y Y Y Y Y Y Y Y Y Y Y - Queue status event Y - Rx interrupt Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y - Queue start/stop Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y - MTU update Y Y Y P Y Y Y Y Y Y Y Y Y Y - Jumbo frame Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y - Scattered Rx Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y - LRO Y Y Y Y - TSO Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y - Promiscuous mode Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y - Allmulticast mode Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y - Unicast MAC filter Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y - Multicast MAC filter Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y - RSS hash Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y - RSS key update Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y - RSS reta update Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y - VMDq Y Y Y Y Y Y Y - SR-IOV Y Y Y Y Y Y Y Y Y Y Y - DCB Y Y Y Y Y - VLAN filter Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y - Ethertype filter Y Y Y Y Y - N-tuple filter Y Y Y - SYN filter Y Y Y - Tunnel filter Y Y Y Y - Flexible filter Y - Hash filter Y Y Y Y - Flow director Y Y Y Y Y - Flow control Y Y Y Y Y Y Y Y Y - Rate limitation Y Y - Traffic mirroring Y Y Y Y - CRC offload Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y - VLAN offload Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y P - QinQ offload Y Y Y Y Y Y Y - L3 checksum offload Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y - L4 checksum offload Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y - Inner L3 checksum Y Y Y Y Y Y - Inner L4 checksum Y Y Y Y Y Y - Packet type parsing Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y - Timesync Y Y Y Y Y - Basic stats Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y - Extended stats Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y - Stats per queue Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y - EEPROM dump Y Y Y Y - Registers dump Y Y Y Y Y Y Y Y - Multiprocess aware Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y - BSD nic_uio Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y - Linux UIO Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y - Linux VFIO Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y - Other kdrv Y Y Y - ARMv7 Y Y Y - ARMv8 Y Y Y Y Y Y Y Y - Power8 Y Y Y - TILE-Gx Y - x86-32 Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y - x86-64 Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y - Usage doc Y Y Y Y Y Y Y Y Y Y Y Y - Design doc - Perf doc - ==================== = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = +.. include:: overview_table.txt .. Note:: diff --git a/doc/guides/nics/pcap_ring.rst b/doc/guides/nics/pcap_ring.rst index aa48d339..79c95255 100644 --- a/doc/guides/nics/pcap_ring.rst +++ b/doc/guides/nics/pcap_ring.rst @@ -62,14 +62,16 @@ Libpcap-based PMD ~~~~~~~~~~~~~~~~~ Pcap-based devices can be created using the virtual device --vdev option. -The device name must start with the eth_pcap prefix followed by numbers or letters. +The device name must start with the net_pcap prefix followed by numbers or letters. The name is unique for each device. Each device can have multiple stream options and multiple devices can be used. Multiple device definitions can be arranged using multiple --vdev. Device name and stream options must be separated by commas as shown below: .. code-block:: console - $RTE_TARGET/app/testpmd -c f -n 4 --vdev 'eth_pcap0,stream_opt0=..,stream_opt1=..' --vdev='eth_pcap1,stream_opt0=..' + $RTE_TARGET/app/testpmd -c f -n 4 \ + --vdev 'net_pcap0,stream_opt0=..,stream_opt1=..' \ + --vdev='net_pcap1,stream_opt0=..' Device Streams ^^^^^^^^^^^^^^ @@ -120,25 +122,32 @@ Read packets from one pcap file and write them to another: .. code-block:: console - $RTE_TARGET/app/testpmd -c '0xf' -n 4 --vdev 'eth_pcap0,rx_pcap=/path/to/ file_rx.pcap,tx_pcap=/path/to/file_tx.pcap' -- --port-topology=chained + $RTE_TARGET/app/testpmd -c '0xf' -n 4 \ + --vdev 'net_pcap0,rx_pcap=file_rx.pcap,tx_pcap=file_tx.pcap' \ + -- --port-topology=chained Read packets from a network interface and write them to a pcap file: .. code-block:: console - $RTE_TARGET/app/testpmd -c '0xf' -n 4 --vdev 'eth_pcap0,rx_iface=eth0,tx_pcap=/path/to/file_tx.pcap' -- --port-topology=chained + $RTE_TARGET/app/testpmd -c '0xf' -n 4 \ + --vdev 'net_pcap0,rx_iface=eth0,tx_pcap=file_tx.pcap' \ + -- --port-topology=chained Read packets from a pcap file and write them to a network interface: .. code-block:: console - $RTE_TARGET/app/testpmd -c '0xf' -n 4 --vdev 'eth_pcap0,rx_pcap=/path/to/ file_rx.pcap,tx_iface=eth1' -- --port-topology=chained + $RTE_TARGET/app/testpmd -c '0xf' -n 4 \ + --vdev 'net_pcap0,rx_pcap=file_rx.pcap,tx_iface=eth1' \ + -- --port-topology=chained Forward packets through two network interfaces: .. code-block:: console - $RTE_TARGET/app/testpmd -c '0xf' -n 4 --vdev 'eth_pcap0,iface=eth0' --vdev='eth_pcap1;iface=eth1' + $RTE_TARGET/app/testpmd -c '0xf' -n 4 \ + --vdev 'net_pcap0,iface=eth0' --vdev='net_pcap1;iface=eth1' Using libpcap-based PMD with the testpmd Application ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -162,19 +171,21 @@ Otherwise, the first 512 packets from the input pcap file will be discarded by t .. code-block:: console - $RTE_TARGET/app/testpmd -c '0xf' -n 4 --vdev 'eth_pcap0,rx_pcap=/path/to/ file_rx.pcap,tx_pcap=/path/to/file_tx.pcap' -- --port-topology=chained --no-flush-rx + $RTE_TARGET/app/testpmd -c '0xf' -n 4 \ + --vdev 'net_pcap0,rx_pcap=file_rx.pcap,tx_pcap=file_tx.pcap' \ + -- --port-topology=chained --no-flush-rx Rings-based PMD ~~~~~~~~~~~~~~~ To run a DPDK application on a machine without any Ethernet devices, a pair of ring-based rte_ethdevs can be used as below. -The device names passed to the --vdev option must start with eth_ring and take no additional parameters. +The device names passed to the --vdev option must start with net_ring and take no additional parameters. Multiple devices may be specified, separated by commas. .. code-block:: console - ./testpmd -c E -n 4 --vdev=eth_ring0 --vdev=eth_ring1 -- -i + ./testpmd -c E -n 4 --vdev=net_ring0 --vdev=net_ring1 -- -i EAL: Detected lcore 1 as core 1 on socket 0 ... @@ -243,8 +254,8 @@ for reception on the same port (error handling omitted for clarity): /* create two ethdev's */ - port0 = rte_eth_from_rings("eth_ring0", ring, NUM_RINGS, ring, NUM_RINGS, SOCKET0); - port1 = rte_eth_from_rings("eth_ring1", ring, NUM_RINGS, ring, NUM_RINGS, SOCKET0); + port0 = rte_eth_from_rings("net_ring0", ring, NUM_RINGS, ring, NUM_RINGS, SOCKET0); + port1 = rte_eth_from_rings("net_ring1", ring, NUM_RINGS, ring, NUM_RINGS, SOCKET0); To create two pseudo-Ethernet ports where the traffic is switched between them, @@ -253,8 +264,8 @@ the final two lines could be changed as below: .. code-block:: c - port0 = rte_eth_from_rings("eth_ring0", &ring[0], 1, &ring[1], 1, SOCKET0); - port1 = rte_eth_from_rings("eth_ring1", &ring[1], 1, &ring[0], 1, SOCKET0); + port0 = rte_eth_from_rings("net_ring0", &ring[0], 1, &ring[1], 1, SOCKET0); + port1 = rte_eth_from_rings("net_ring1", &ring[1], 1, &ring[0], 1, SOCKET0); This type of configuration could be useful in a pipeline model, for example, where one may want to have inter-core communication using pseudo Ethernet devices rather than raw rings, diff --git a/doc/guides/nics/qede.rst b/doc/guides/nics/qede.rst index 53d749c9..d22ecdd9 100644 --- a/doc/guides/nics/qede.rst +++ b/doc/guides/nics/qede.rst @@ -32,7 +32,7 @@ QEDE Poll Mode Driver ====================== The QEDE poll mode driver library (**librte_pmd_qede**) implements support -for **QLogic FastLinQ QL4xxxx 25G/40G CNA** family of adapters as well +for **QLogic FastLinQ QL4xxxx 25G/40G/100G CNA** family of adapters as well as their virtual functions (VF) in SR-IOV context. It is supported on several standard Linux distros like RHEL7.x, SLES12.x and Ubuntu. It is compile-tested under FreeBSD OS. @@ -47,45 +47,43 @@ Supported Features - Promiscuous mode - Allmulti mode - Port hardware statistics -- Jumbo frames (using single buffer) +- Jumbo frames - VLAN offload - Filtering and stripping - Stateless checksum offloads (IPv4/TCP/UDP) -- Multiple Rx/Tx queues (queue-pairs) -- RSS (with user configurable table/key) +- Multiple Rx/Tx queues +- RSS (with RETA/hash table/key) - TSS - Multiple MAC address - Default pause flow control -- SR-IOV VF for 25G/40G modes +- SR-IOV VF +- MTU change +- Multiprocess aware +- Scatter-Gather Non-supported Features ---------------------- -- Scatter-Gather Rx/Tx frames -- Unequal number of Rx/Tx queues -- MTU change (dynamic) - SR-IOV PF - Tunneling offloads -- Reload of the PMD after a non-graceful termination +- LRO/TSO +- NPAR Supported QLogic Adapters ------------------------- -- QLogic FastLinQ QL4xxxx 25G/40G/100G CNAs. +- QLogic FastLinQ QL4xxxx 10G/25G/40G/100G CNAs. Prerequisites ------------- -- Requires firmware version **8.7.x.** and management firmware - version **8.7.x or higher**. Firmware may be available +- Requires firmware version **8.10.x.** and management firmware + version **8.10.x or higher**. Firmware may be available inbox in certain newer Linux distros under the standard directory - ``E.g. /lib/firmware/qed/qed_init_values_zipped-8.7.7.0.bin`` + ``E.g. /lib/firmware/qed/qed_init_values-8.10.9.0.bin`` - If the required firmware files are not available then visit `QLogic Driver Download Center <http://driverdownloads.qlogic.com>`_. -- This driver relies on external zlib library (-lz) for uncompressing - the firmware file. - Performance note ~~~~~~~~~~~~~~~~ @@ -120,7 +118,7 @@ enabling debugging options may affect system performance. - ``CONFIG_RTE_LIBRTE_QEDE_FW`` (default **""**) Gives absolute path of firmware file. - ``Eg: "/lib/firmware/qed/qed_init_values_zipped-8.7.7.0.bin"`` + ``Eg: "/lib/firmware/qed/qed_init_values_zipped-8.10.9.0.bin"`` Empty string indicates driver will pick up the firmware file from the default location. @@ -150,7 +148,7 @@ command:: cd <DPDK-source-directory> gmake config T=x86_64-native-bsdapp-gcc install -Wl,-rpath=\ - /usr/local/lib/gcc48 CC=gcc48 + /usr/local/lib/gcc49 CC=gcc49 Sample Application Notes @@ -243,7 +241,7 @@ SR-IOV: Prerequisites and Sample Application Notes This section provides instructions to configure SR-IOV with Linux OS. -**Note**: librte_pmd_qede will be used to bind to SR-IOV VF device and Linux native kernel driver (QEDE) will function as SR-IOV PF driver. +**Note**: librte_pmd_qede will be used to bind to SR-IOV VF device and Linux native kernel driver (QEDE) will function as SR-IOV PF driver. Requires PF driver to be 8.10.x.x or higher. #. Verify SR-IOV and ARI capability is enabled on the adapter using ``lspci``: diff --git a/doc/guides/nics/thunderx.rst b/doc/guides/nics/thunderx.rst index 248b1af7..187c9a4a 100644 --- a/doc/guides/nics/thunderx.rst +++ b/doc/guides/nics/thunderx.rst @@ -56,10 +56,13 @@ Features of the ThunderX PMD are: - VLAN stripping - SR-IOV VF - NUMA support +- Multi queue set support (up to 96 queues (12 queue sets)) per port Supported ThunderX SoCs ----------------------- - CN88xx +- CN81xx +- CN83xx Prerequisites ------------- @@ -206,13 +209,13 @@ This section provides instructions to configure SR-IOV with Linux OS. .. code-block:: console 0002:01:00.0 Ethernet controller: Cavium Networks Device a01e (rev 01) - ... - Capabilities: [100 v1] Alternative Routing-ID Interpretation (ARI) - ... - Capabilities: [180 v1] Single Root I/O Virtualization (SR-IOV) - ... - Kernel driver in use: thunder-nic - ... + ... + Capabilities: [100 v1] Alternative Routing-ID Interpretation (ARI) + ... + Capabilities: [180 v1] Single Root I/O Virtualization (SR-IOV) + ... + Kernel driver in use: thunder-nic + ... .. note:: @@ -229,18 +232,18 @@ This section provides instructions to configure SR-IOV with Linux OS. .. code-block:: console 0002:01:00.1 Ethernet controller: Cavium Networks Device 0011 (rev 01) - ... - Capabilities: [100 v1] Alternative Routing-ID Interpretation (ARI) - ... - Kernel driver in use: thunder-nicvf - ... + ... + Capabilities: [100 v1] Alternative Routing-ID Interpretation (ARI) + ... + Kernel driver in use: thunder-nicvf + ... 0002:01:00.2 Ethernet controller: Cavium Networks Device 0011 (rev 01) - ... - Capabilities: [100 v1] Alternative Routing-ID Interpretation (ARI) - ... - Kernel driver in use: thunder-nicvf - ... + ... + Capabilities: [100 v1] Alternative Routing-ID Interpretation (ARI) + ... + Kernel driver in use: thunder-nicvf + ... .. note:: @@ -321,6 +324,112 @@ This section provides instructions to configure SR-IOV with Linux OS. #. Refer to section :ref:`Running testpmd <thunderx_testpmd_example>` for instruction how to launch ``testpmd`` application. +Multiple Queue Set per DPDK port configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are two types of VFs: + +- Primary VF +- Secondary VF + +Each port consists of a primary VF and n secondary VF(s). Each VF provides 8 Tx/Rx queues to a port. +When a given port is configured to use more than 8 queues, it requires one (or more) secondary VF. +Each secondary VF adds 8 additional queues to the queue set. + +During PMD driver initialization, the primary VF's are enumerated by checking the +specific flag (see sqs message in DPDK boot log - sqs indicates secondary queue set). +They are at the beginning of VF list (the remain ones are secondary VF's). + +The primary VFs are used as master queue sets. Secondary VFs provide +additional queue sets for primary ones. If a port is configured for more then +8 queues than it will request for additional queues from secondary VFs. + +Secondary VFs cannot be shared between primary VFs. + +Primary VFs are present on the beginning of the 'Network devices using kernel +driver' list, secondary VFs are on the remaining on the remaining part of the list. + + .. note:: + + The VNIC driver in the multiqueue setup works differently than other drivers like `ixgbe`. + We need to bind separately each specific queue set device with the ``tools/dpdk-devbind.py`` utility. + + .. note:: + + Depending on the hardware used, the kernel driver sets a threshold ``vf_id``. VFs that try to attached with an id below or equal to + this boundary are considered primary VFs. VFs that try to attach with an id above this boundary are considered secondary VFs. + + +Example device binding +~~~~~~~~~~~~~~~~~~~~~~ + +If a system has three interfaces, a total of 18 VF devices will be created +on a non-NUMA machine. + + .. note:: + + NUMA systems have 12 VFs per port and non-NUMA 6 VFs per port. + + .. code-block:: console + + # tools/dpdk-devbind.py --status + + Network devices using DPDK-compatible driver + ============================================ + <none> + + Network devices using kernel driver + =================================== + 0000:01:10.0 'Device a026' if= drv=thunder-BGX unused=vfio-pci,uio_pci_generic + 0000:01:10.1 'Device a026' if= drv=thunder-BGX unused=vfio-pci,uio_pci_generic + 0002:01:00.0 'Device a01e' if= drv=thunder-nic unused=vfio-pci,uio_pci_generic + 0002:01:00.1 'Device 0011' if=eth0 drv=thunder-nicvf unused=vfio-pci,uio_pci_generic + 0002:01:00.2 'Device 0011' if=eth1 drv=thunder-nicvf unused=vfio-pci,uio_pci_generic + 0002:01:00.3 'Device 0011' if=eth2 drv=thunder-nicvf unused=vfio-pci,uio_pci_generic + 0002:01:00.4 'Device 0011' if= drv=thunder-nicvf unused=vfio-pci,uio_pci_generic + 0002:01:00.5 'Device 0011' if= drv=thunder-nicvf unused=vfio-pci,uio_pci_generic + 0002:01:00.6 'Device 0011' if= drv=thunder-nicvf unused=vfio-pci,uio_pci_generic + 0002:01:00.7 'Device 0011' if= drv=thunder-nicvf unused=vfio-pci,uio_pci_generic + 0002:01:01.0 'Device 0011' if= drv=thunder-nicvf unused=vfio-pci,uio_pci_generic + 0002:01:01.1 'Device 0011' if= drv=thunder-nicvf unused=vfio-pci,uio_pci_generic + 0002:01:01.2 'Device 0011' if= drv=thunder-nicvf unused=vfio-pci,uio_pci_generic + 0002:01:01.3 'Device 0011' if= drv=thunder-nicvf unused=vfio-pci,uio_pci_generic + 0002:01:01.4 'Device 0011' if= drv=thunder-nicvf unused=vfio-pci,uio_pci_generic + 0002:01:01.5 'Device 0011' if= drv=thunder-nicvf unused=vfio-pci,uio_pci_generic + 0002:01:01.6 'Device 0011' if= drv=thunder-nicvf unused=vfio-pci,uio_pci_generic + 0002:01:01.7 'Device 0011' if= drv=thunder-nicvf unused=vfio-pci,uio_pci_generic + 0002:01:02.0 'Device 0011' if= drv=thunder-nicvf unused=vfio-pci,uio_pci_generic + 0002:01:02.1 'Device 0011' if= drv=thunder-nicvf unused=vfio-pci,uio_pci_generic + 0002:01:02.2 'Device 0011' if= drv=thunder-nicvf unused=vfio-pci,uio_pci_generic + + Other network devices + ===================== + 0002:00:03.0 'Device a01f' unused=vfio-pci,uio_pci_generic + + +We want to bind two physical interfaces with 24 queues each device, we attach two primary VFs +and four secondary queues. In our example we choose two 10G interfaces eth1 (0002:01:00.2) and eth2 (0002:01:00.3). +We will choose four secondary queue sets from the ending of the list (0002:01:01.7-0002:01:02.2). + + +#. Bind two primary VFs to the ``vfio-pci`` driver: + + .. code-block:: console + + tools/dpdk-devbind.py -b vfio-pci 0002:01:00.2 + tools/dpdk-devbind.py -b vfio-pci 0002:01:00.3 + +#. Bind four primary VFs to the ``vfio-pci`` driver: + + .. code-block:: console + + tools/dpdk-devbind.py -b vfio-pci 0002:01:01.7 + tools/dpdk-devbind.py -b vfio-pci 0002:01:02.0 + tools/dpdk-devbind.py -b vfio-pci 0002:01:02.1 + tools/dpdk-devbind.py -b vfio-pci 0002:01:02.2 + +The nicvf thunderx driver will make use of attached secondary VFs automatically during the interface configuration stage. + Limitations ----------- @@ -345,10 +454,3 @@ Maximum packet segments The ThunderX SoC family NICs support up to 12 segments per packet when working in scatter/gather mode. So, setting MTU will result with ``EINVAL`` when the frame size does not fit in the maximum number of segments. - -Limited VFs -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The ThunderX SoC family NICs has 128VFs and each VF has 8/8 queues -for RX/TX respectively. Current driver implementation has one to one mapping -between physical port and VF hence only limited VFs can be used. diff --git a/doc/guides/nics/vhost.rst b/doc/guides/nics/vhost.rst index 1e3f1ade..6b30b54e 100644 --- a/doc/guides/nics/vhost.rst +++ b/doc/guides/nics/vhost.rst @@ -92,7 +92,7 @@ This section demonstrates vhost PMD with testpmd DPDK sample application. .. code-block:: console - ./testpmd -c f -n 4 --vdev 'eth_vhost0,iface=/tmp/sock0,queues=1' -- -i + ./testpmd -c f -n 4 --vdev 'net_vhost0,iface=/tmp/sock0,queues=1' -- -i Other basic DPDK preparations like hugepage enabling here. Please refer to the *DPDK Getting Started Guide* for detailed instructions. diff --git a/doc/guides/nics/vmxnet3.rst b/doc/guides/nics/vmxnet3.rst index e919088d..bf845942 100644 --- a/doc/guides/nics/vmxnet3.rst +++ b/doc/guides/nics/vmxnet3.rst @@ -32,17 +32,11 @@ Poll Mode Driver for Paravirtual VMXNET3 NIC ============================================ The VMXNET3 adapter is the next generation of a paravirtualized NIC, introduced by VMware* ESXi. -It is designed for performance and is not related to VMXNET or VMXENET2. -It offers all the features available in VMXNET2, and adds several new features such as, +It is designed for performance, offers all the features available in VMXNET2, and adds several new features such as, multi-queue support (also known as Receive Side Scaling, RSS), IPv6 offloads, and MSI/MSI-X interrupt delivery. -Because operating system vendors do not provide built-in drivers for this card, -VMware Tools must be installed to have a driver for the VMXNET3 network adapter available. One can use the same device in a DPDK application with VMXNET3 PMD introduced in DPDK API. -Currently, the driver provides basic support for using the device in a DPDK application running on a guest OS. -Optimization is needed on the backend, that is, the VMware* ESXi vmkernel switch, to achieve optimal performance end-to-end. - In this chapter, two setups with the use of the VMXNET3 PMD are demonstrated: #. Vmxnet3 with a native NIC connected to a vSwitch @@ -59,8 +53,6 @@ For performance details, refer to the following link from VMware: `http://www.vmware.com/pdf/vsp_4_vmxnet3_perf.pdf <http://www.vmware.com/pdf/vsp_4_vmxnet3_perf.pdf>`_ As a PMD, the VMXNET3 driver provides the packet reception and transmission callbacks, vmxnet3_recv_pkts and vmxnet3_xmit_pkts. -It does not support scattered packet reception as part of vmxnet3_recv_pkts and vmxnet3_xmit_pkts. -Also, it does not support scattered packet reception as part of the device operations supported. The VMXNET3 PMD handles all the packet buffer memory allocation and resides in guest address space and it is solely responsible to free that memory when not needed. @@ -79,7 +71,7 @@ This keeps performance up on the RX side, even though the device provides a noti In the transmit routine, the DPDK application fills packet buffer pointers in the descriptors of the command ring and notifies the hypervisor. -In response the hypervisor takes packets and passes them to the vSwitch. It writes into the completion descriptors ring. +In response the hypervisor takes packets and passes them to the vSwitch, It writes into the completion descriptors ring. The rings are read by the PMD in the next transmit routine call and the buffers and descriptors are freed from memory. Features and Limitations of VMXNET3 PMD diff --git a/doc/guides/prog_guide/dev_kit_build_system.rst b/doc/guides/prog_guide/dev_kit_build_system.rst index fa2411f7..19de1563 100644 --- a/doc/guides/prog_guide/dev_kit_build_system.rst +++ b/doc/guides/prog_guide/dev_kit_build_system.rst @@ -53,62 +53,7 @@ Build Directory Concept ~~~~~~~~~~~~~~~~~~~~~~~ After installation, a build directory structure is created. -Each build directory contains include files, libraries, and applications: - -.. code-block:: console - - ~/DPDK$ ls - app MAINTAINERS - config Makefile - COPYRIGHT mk - doc scripts - examples lib - tools x86_64-native-linuxapp-gcc - x86_64-native-linuxapp-icc i686-native-linuxapp-gcc - i686-native-linuxapp-icc - - ... - ~/DEV/DPDK$ ls i686-native-linuxapp-gcc - - app build buildtools include kmod lib Makefile - - - ~/DEV/DPDK$ ls i686-native-linuxapp-gcc/app/ - cmdline_test dump_cfg test testpmd - cmdline_test.map dump_cfg.map test.map - testpmd.map - - - ~/DEV/DPDK$ ls i686-native-linuxapp-gcc/lib/ - - libethdev.a librte_hash.a librte_mbuf.a librte_pmd_ixgbe.a - - librte_cmdline.a librte_lpm.a librte_mempool.a librte_ring.a - - librte_eal.a librte_pmd_e1000.a librte_timer.a - - - ~/DEV/DPDK$ ls i686-native-linuxapp-gcc/include/ - arch rte_cpuflags.h rte_memcpy.h - cmdline_cirbuf.h rte_cycles.h rte_memory.h - cmdline.h rte_debug.h rte_mempool.h - cmdline_parse_etheraddr.h rte_eal.h rte_memzone.h - cmdline_parse.h rte_errno.h rte_pci_dev_ids.h - cmdline_parse_ipaddr.h rte_ethdev.h rte_pci.h - cmdline_parse_num.h rte_ether.h rte_per_lcore.h - cmdline_parse_portlist.h rte_fbk_hash.h rte_prefetch.h - cmdline_parse_string.h rte_hash_crc.h rte_random.h - cmdline_rdline.h rte_hash.h rte_ring.h - cmdline_socket.h rte_interrupts.h rte_rwlock.h - cmdline_vt100.h rte_ip.h rte_sctp.h - exec-env rte_jhash.h rte_spinlock.h - rte_alarm.h rte_launch.h rte_string_fns.h - rte_atomic.h rte_lcore.h rte_tailq.h - rte_branch_prediction.h rte_log.h rte_tcp.h - rte_byteorder.h rte_lpm.h rte_timer.h - rte_common.h rte_malloc.h rte_udp.h - rte_config.h rte_mbuf.h - +Each build directory contains include files, libraries, and applications. A build directory is specific to a configuration that includes architecture + execution environment + toolchain. It is possible to have several build directories sharing the same sources with different configurations. @@ -319,7 +264,7 @@ instance the macro: .. code-block:: c - PMD_REGISTER_DRIVER(drv, name) + RTE_PMD_REGISTER_PCI(name, drv) Creates the following symbol: diff --git a/doc/guides/prog_guide/img/ivshmem.png b/doc/guides/prog_guide/img/ivshmem.png Binary files differdeleted file mode 100644 index 2b34a2cf..00000000 --- a/doc/guides/prog_guide/img/ivshmem.png +++ /dev/null diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst index 07a4d354..e5a50a88 100644 --- a/doc/guides/prog_guide/index.rst +++ b/doc/guides/prog_guide/index.rst @@ -43,7 +43,6 @@ Programmer's Guide mbuf_lib poll_mode_drv cryptodev_lib - ivshmem_lib link_bonding_poll_mode_drv_lib timer_lib hash_lib diff --git a/doc/guides/prog_guide/ivshmem_lib.rst b/doc/guides/prog_guide/ivshmem_lib.rst deleted file mode 100644 index b8a32e4c..00000000 --- a/doc/guides/prog_guide/ivshmem_lib.rst +++ /dev/null @@ -1,160 +0,0 @@ -.. BSD LICENSE - Copyright(c) 2010-2014 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. - -IVSHMEM Library -=============== - -The DPDK IVSHMEM library facilitates fast zero-copy data sharing among virtual machines -(host-to-guest or guest-to-guest) by means of QEMU's IVSHMEM mechanism. - -The library works by providing a command line for QEMU to map several hugepages into a single IVSHMEM device. -For the guest to know what is inside any given IVSHMEM device -(and to distinguish between DPDK and non-DPDK IVSHMEM devices), -a metadata file is also mapped into the IVSHMEM segment. -No work needs to be done by the guest application to map IVSHMEM devices into memory; -they are automatically recognized by the DPDK Environment Abstraction Layer (EAL). - -A typical DPDK IVSHMEM use case looks like the following. - - -.. figure:: img/ivshmem.* - - Typical Ivshmem use case - - -The same could work with several virtual machines, providing host-to-VM or VM-to-VM communication. -The maximum number of metadata files is 32 (by default) and each metadata file can contain different (or even the same) hugepages. -The only constraint is that each VM has to have access to the memory it is sharing with other entities (be it host or another VM). -For example, if the user wants to share the same memzone across two VMs, each VM must have that memzone in its metadata file. - -IVHSHMEM Library API Overview ------------------------------ - -The following is a simple guide to using the IVSHMEM Library API: - -* Call rte_ivshmem_metadata_create() to create a new metadata file. - The metadata name is used to distinguish between multiple metadata files. - -* Populate each metadata file with DPDK data structures. - This can be done using the following API calls: - - * rte_ivhshmem_metadata_add_memzone() to add rte_memzone to metadata file - - * rte_ivshmem_metadata_add_ring() to add rte_ring to metadata file - - * rte_ivshmem_metadata_add_mempool() to add rte_mempool to metadata file - -* Finally, call rte_ivshmem_metadata_cmdline_generate() to generate the command line for QEMU. - Multiple metadata files (and thus multiple command lines) can be supplied to a single VM. - -.. note:: - - Only data structures fully residing in DPDK hugepage memory work correctly. - Supported data structures created by malloc(), mmap() - or otherwise using non-DPDK memory cause undefined behavior and even a segmentation fault. - Specifically, because the memzone field in an rte_ring refers to a memzone structure residing in local memory, - accessing the memzone field in a shared rte_ring will cause an immediate segmentation fault. - -IVSHMEM Environment Configuration ---------------------------------- - -The steps needed to successfully run IVSHMEM applications are the following: - -* Compile a special version of QEMU from sources. - - The source code can be found on the QEMU website (currently, version 1.4.x is supported, but version 1.5.x is known to work also), - however, the source code will need to be patched to support using regular files as the IVSHMEM memory backend. - The patch is not included in the DPDK package, - but is available on the `Intel®DPDK-vswitch project webpage <https://01.org/packet-processing/intel%C2%AE-ovdk>`_ - (either separately or in a DPDK vSwitch package). - -* Enable IVSHMEM library in the DPDK build configuration. - - In the default configuration, IVSHMEM library is not compiled. To compile the IVSHMEM library, - one has to either use one of the provided IVSHMEM targets - (for example, x86_64-ivshmem-linuxapp-gcc), - or set CONFIG_RTE_LIBRTE_IVSHMEM to "y" in the build configuration. - -* Set up hugepage memory on the virtual machine. - - The guest applications run as regular DPDK (primary) processes and thus need their own hugepage memory set up inside the VM. - The process is identical to the one described in the *DPDK Getting Started Guide*. - -Best Practices for Writing IVSHMEM Applications ------------------------------------------------ - -When considering the use of IVSHMEM for sharing memory, security implications need to be carefully evaluated. -IVSHMEM is not suitable for untrusted guests, as IVSHMEM is essentially a window into the host process memory. -This also has implications for the multiple VM scenarios. -While the IVSHMEM library tries to share as little memory as possible, -it is quite probable that data designated for one VM might also be present in an IVSMHMEM device designated for another VM. -Consequently, any shared memory corruption will affect both host and all VMs sharing that particular memory. - -IVSHMEM applications essentially behave like multi-process applications, -so it is important to implement access serialization to data and thread safety. -DPDK ring structures are already thread-safe, however, -any custom data structures that the user might need would have to be thread-safe also. - -Similar to regular DPDK multi-process applications, -it is not recommended to use function pointers as functions might have different memory addresses in different processes. - -It is best to avoid freeing the rte_mbuf structure on a different machine from where it was allocated, -that is, if the mbuf was allocated on the host, the host should free it. -Consequently, any packet transmission and reception should also happen on the same machine (whether virtual or physical). -Failing to do so may lead to data corruption in the mempool cache. - -Despite the IVSHMEM mechanism being zero-copy and having good performance, -it is still desirable to do processing in batches and follow other procedures described in -:ref:`Performance Optimization <Performance_Optimization>`. - -Best Practices for Running IVSHMEM Applications ------------------------------------------------ - -For performance reasons, -it is best to pin host processes and QEMU processes to different cores so that they do not interfere with each other. -If NUMA support is enabled, it is also desirable to keep host process' hugepage memory and QEMU process on the same NUMA node. - -For the best performance across all NUMA nodes, each QEMU core should be pinned to host CPU core on the appropriate NUMA node. -QEMU's virtual NUMA nodes should also be set up to correspond to physical NUMA nodes. -More on how to set up DPDK and QEMU NUMA support can be found in *DPDK Getting Started Guide* and -`QEMU documentation <http://qemu.weilnetz.de/qemu-doc.html>`_ respectively. -A script called cpu_layout.py is provided with the DPDK package (in the tools directory) -that can be used to identify which CPU cores correspond to which NUMA node. - -The QEMU IVSHMEM command line creation should be considered the last step before starting the virtual machine. -Currently, there is no hot plug support for QEMU IVSHMEM devices, -so one cannot add additional memory to an IVSHMEM device once it has been created. -Therefore, the correct sequence to run an IVSHMEM application is to run host application first, -obtain the command lines for each IVSHMEM device and then run all QEMU instances with guest applications afterwards. - -It is important to note that once QEMU is started, it holds on to the hugepages it uses for IVSHMEM devices. -As a result, if the user wishes to shut down or restart the IVSHMEM host application, -it is not enough to simply shut the application down. -The virtual machine must also be shut down (if not, it will hold onto outdated host data). diff --git a/doc/guides/prog_guide/kernel_nic_interface.rst b/doc/guides/prog_guide/kernel_nic_interface.rst index fac1960b..eb16e2e3 100644 --- a/doc/guides/prog_guide/kernel_nic_interface.rst +++ b/doc/guides/prog_guide/kernel_nic_interface.rst @@ -102,6 +102,9 @@ Refer to rte_kni_common.h in the DPDK source code for more details. The physical addresses will be re-mapped into the kernel address space and stored in separate KNI contexts. +The affinity of kernel RX thread (both single and multi-threaded modes) is controlled by force_bind and +core_id config parameters. + The KNI interfaces can be deleted by a DPDK application dynamically after being created. Furthermore, all those KNI interfaces not deleted will be deleted on the release operation of the miscellaneous device (when the DPDK application is closed). diff --git a/doc/guides/prog_guide/link_bonding_poll_mode_drv_lib.rst b/doc/guides/prog_guide/link_bonding_poll_mode_drv_lib.rst index 01ddcb91..65813c9e 100644 --- a/doc/guides/prog_guide/link_bonding_poll_mode_drv_lib.rst +++ b/doc/guides/prog_guide/link_bonding_poll_mode_drv_lib.rst @@ -356,7 +356,7 @@ Using Link Bonding Devices from the EAL Command Line Link bonding devices can be created at application startup time using the ``--vdev`` EAL command line option. The device name must start with the -eth_bond prefix followed by numbers or letters. The name must be unique for +net_bond prefix followed by numbers or letters. The name must be unique for each device. Each device can have multiple options arranged in a comma separated list. Multiple devices definitions can be arranged by calling the ``--vdev`` option multiple times. @@ -365,7 +365,7 @@ Device names and bonding options must be separated by commas as shown below: .. code-block:: console - $RTE_TARGET/app/testpmd -c f -n 4 --vdev 'eth_bond0,bond_opt0=..,bond opt1=..'--vdev 'eth_bond1,bond _opt0=..,bond_opt1=..' + $RTE_TARGET/app/testpmd -c f -n 4 --vdev 'net_bond0,bond_opt0=..,bond opt1=..'--vdev 'net_bond1,bond _opt0=..,bond_opt1=..' Link Bonding EAL Options ^^^^^^^^^^^^^^^^^^^^^^^^ @@ -373,7 +373,7 @@ Link Bonding EAL Options There are multiple ways of definitions that can be assessed and combined as long as the following two rules are respected: -* A unique device name, in the format of eth_bondX is provided, +* A unique device name, in the format of net_bondX is provided, where X can be any combination of numbers and/or letters, and the name is no greater than 32 characters long. @@ -465,22 +465,22 @@ Create a bonded device in round robin mode with two slaves specified by their PC .. code-block:: console - $RTE_TARGET/app/testpmd -c '0xf' -n 4 --vdev 'eth_bond0,mode=0, slave=0000:00a:00.01,slave=0000:004:00.00' -- --port-topology=chained + $RTE_TARGET/app/testpmd -c '0xf' -n 4 --vdev 'net_bond0,mode=0, slave=0000:00a:00.01,slave=0000:004:00.00' -- --port-topology=chained Create a bonded device in round robin mode with two slaves specified by their PCI address and an overriding MAC address: .. code-block:: console - $RTE_TARGET/app/testpmd -c '0xf' -n 4 --vdev 'eth_bond0,mode=0, slave=0000:00a:00.01,slave=0000:004:00.00,mac=00:1e:67:1d:fd:1d' -- --port-topology=chained + $RTE_TARGET/app/testpmd -c '0xf' -n 4 --vdev 'net_bond0,mode=0, slave=0000:00a:00.01,slave=0000:004:00.00,mac=00:1e:67:1d:fd:1d' -- --port-topology=chained Create a bonded device in active backup mode with two slaves specified, and a primary slave specified by their PCI addresses: .. code-block:: console - $RTE_TARGET/app/testpmd -c '0xf' -n 4 --vdev 'eth_bond0,mode=1, slave=0000:00a:00.01,slave=0000:004:00.00,primary=0000:00a:00.01' -- --port-topology=chained + $RTE_TARGET/app/testpmd -c '0xf' -n 4 --vdev 'net_bond0,mode=1, slave=0000:00a:00.01,slave=0000:004:00.00,primary=0000:00a:00.01' -- --port-topology=chained Create a bonded device in balance mode with two slaves specified by their PCI addresses, and a transmission policy of layer 3 + 4 forwarding: .. code-block:: console - $RTE_TARGET/app/testpmd -c '0xf' -n 4 --vdev 'eth_bond0,mode=2, slave=0000:00a:00.01,slave=0000:004:00.00,xmit_policy=l34' -- --port-topology=chained + $RTE_TARGET/app/testpmd -c '0xf' -n 4 --vdev 'net_bond0,mode=2, slave=0000:00a:00.01,slave=0000:004:00.00,xmit_policy=l34' -- --port-topology=chained diff --git a/doc/guides/prog_guide/multi_proc_support.rst b/doc/guides/prog_guide/multi_proc_support.rst index badd102e..2a996ae8 100644 --- a/doc/guides/prog_guide/multi_proc_support.rst +++ b/doc/guides/prog_guide/multi_proc_support.rst @@ -35,7 +35,7 @@ Multi-process Support In the DPDK, multi-process support is designed to allow a group of DPDK processes to work together in a simple transparent manner to perform packet processing, -or other workloads, on Intel® architecture hardware. +or other workloads. To support this functionality, a number of additions have been made to the core DPDK Environment Abstraction Layer (EAL). diff --git a/doc/guides/prog_guide/overview.rst b/doc/guides/prog_guide/overview.rst index 68cc75cc..9986e3cb 100644 --- a/doc/guides/prog_guide/overview.rst +++ b/doc/guides/prog_guide/overview.rst @@ -157,7 +157,7 @@ The mbuf library provides the facility to create and destroy buffers that may be used by the DPDK application to store message buffers. The message buffers are created at startup time and stored in a mempool, using the DPDK mempool library. -This library provide an API to allocate/free mbufs, manipulate control message buffers (ctrlmbuf) which are generic message buffers, +This library provides an API to allocate/free mbufs, manipulate control message buffers (ctrlmbuf) which are generic message buffers, and packet buffers (pktmbuf) which are used to carry network packets. Network Packet Buffer Management is described in :ref:`Mbuf Library <Mbuf_Library>`. diff --git a/doc/guides/prog_guide/port_hotplug_framework.rst b/doc/guides/prog_guide/port_hotplug_framework.rst index fe6d72a6..6e4436e5 100644 --- a/doc/guides/prog_guide/port_hotplug_framework.rst +++ b/doc/guides/prog_guide/port_hotplug_framework.rst @@ -80,7 +80,7 @@ Port Hotplug API overview returns the attached port number. Before calling the API, the device should be recognized by an userspace driver I/O framework. The API receives a pci address like "0000:01:00.0" or a virtual device name - like "eth_pcap0,iface=eth0". In the case of virtual device name, the + like "net_pcap0,iface=eth0". In the case of virtual device name, the format is the same as the general "--vdev" option of DPDK. * Detaching a port diff --git a/doc/guides/prog_guide/profile_app.rst b/doc/guides/prog_guide/profile_app.rst index 32261875..54b546ac 100644 --- a/doc/guides/prog_guide/profile_app.rst +++ b/doc/guides/prog_guide/profile_app.rst @@ -31,8 +31,15 @@ Profile Your Application ======================== +The following sections describe methods of profiling DPDK applications on +different architectures. + + +Profiling on x86 +---------------- + Intel processors provide performance counters to monitor events. -Some tools provided by Intel can be used to profile and benchmark an application. +Some tools provided by Intel, such as VTune, can be used to profile and benchmark an application. See the *VTune Performance Analyzer Essentials* publication from Intel Press for more information. For a DPDK application, this can be done in a Linux* application environment only. @@ -50,3 +57,58 @@ The main situations that should be monitored through event counters are: Refer to the `Intel Performance Analysis Guide <http://software.intel.com/sites/products/collateral/hpc/vtune/performance_analysis_guide.pdf>`_ for details about application profiling. + + +Profiling on ARM64 +------------------ + +Using Linux perf +~~~~~~~~~~~~~~~~ + +The ARM64 architecture provide performance counters to monitor events. The +Linux ``perf`` tool can be used to profile and benchmark an application. In +addition to the standard events, ``perf`` can be used to profile arm64 +specific PMU (Performance Monitor Unit) events through raw events (``-e`` +``-rXX``). + +For more derails refer to the +`ARM64 specific PMU events enumeration <http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.100095_0002_04_en/way1382543438508.html>`_. + + +High-resolution cycle counter +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The default ``cntvct_el0`` based ``rte_rdtsc()`` provides a portable means to +get a wall clock counter in user space. Typically it runs at <= 100MHz. + +The alternative method to enable ``rte_rdtsc()`` for a high resolution wall +clock counter is through the armv8 PMU subsystem. The PMU cycle counter runs +at CPU frequency. However, access to the PMU cycle counter from user space is +not enabled by default in the arm64 linux kernel. It is possible to enable +cycle counter for user space access by configuring the PMU from the privileged +mode (kernel space). + +By default the ``rte_rdtsc()`` implementation uses a portable ``cntvct_el0`` +scheme. Application can choose the PMU based implementation with +``CONFIG_RTE_ARM_EAL_RDTSC_USE_PMU``. + +The example below shows the steps to configure the PMU based cycle counter on +an armv8 machine. + +.. code-block:: console + + git clone https://github.com/jerinjacobk/armv8_pmu_cycle_counter_el0 + cd armv8_pmu_cycle_counter_el0 + make + sudo insmod pmu_el0_cycle_counter.ko + cd $DPDK_DIR + make config T=arm64-armv8a-linuxapp-gcc + echo "CONFIG_RTE_ARM_EAL_RDTSC_USE_PMU=y" >> build/.config + make + +.. warning:: + + The PMU based scheme is useful for high accuracy performance profiling with + ``rte_rdtsc()``. However, this method can not be used in conjunction with + Linux userspace profiling tools like ``perf`` as this scheme alters the PMU + registers state. diff --git a/doc/guides/prog_guide/source_org.rst b/doc/guides/prog_guide/source_org.rst index 0c06d47b..d9c140f7 100644 --- a/doc/guides/prog_guide/source_org.rst +++ b/doc/guides/prog_guide/source_org.rst @@ -70,7 +70,6 @@ The lib directory contains:: +-- librte_ether # Generic interface to poll mode driver +-- librte_hash # Hash library +-- librte_ip_frag # IP fragmentation library - +-- librte_ivshmem # QEMU IVSHMEM library +-- librte_kni # Kernel NIC interface +-- librte_kvargs # Argument parsing library +-- librte_lpm # Longest prefix match library diff --git a/doc/guides/prog_guide/vhost_lib.rst b/doc/guides/prog_guide/vhost_lib.rst index 6b0c6b26..4f997d47 100644 --- a/doc/guides/prog_guide/vhost_lib.rst +++ b/doc/guides/prog_guide/vhost_lib.rst @@ -46,26 +46,8 @@ vhost library should be able to: * Know all the necessary information about the vring: Information such as where the available ring is stored. Vhost defines some - messages to tell the backend all the information it needs to know how to - manipulate the vring. - -Currently, there are two ways to pass these messages and as a result there are -two Vhost implementations in DPDK: *vhost-cuse* (where the character devices -are in user space) and *vhost-user*. - -Vhost-cuse creates a user space character device and hook to a function ioctl, -so that all ioctl commands that are sent from the frontend (QEMU) will be -captured and handled. - -Vhost-user creates a Unix domain socket file through which messages are -passed. - -.. Note:: - - Since DPDK v2.2, the majority of the development effort has gone into - enhancing vhost-user, such as multiple queue, live migration, and - reconnect. Thus, it is strongly advised to use vhost-user instead of - vhost-cuse. + messages (passed through a Unix domain socket file) to tell the backend all + the information it needs to know how to manipulate the vring. Vhost API Overview @@ -75,11 +57,10 @@ The following is an overview of the Vhost API functions: * ``rte_vhost_driver_register(path, flags)`` - This function registers a vhost driver into the system. For vhost-cuse, a - ``/dev/path`` character device file will be created. For vhost-user server - mode, a Unix domain socket file ``path`` will be created. + This function registers a vhost driver into the system. ``path`` specifies + the Unix domain socket file path. - Currently two flags are supported (these are valid for vhost-user only): + Currently supported flags are: - ``RTE_VHOST_USER_CLIENT`` @@ -97,6 +78,38 @@ The following is an overview of the Vhost API functions: This reconnect option is enabled by default. However, it can be turned off by setting this flag. + - ``RTE_VHOST_USER_DEQUEUE_ZERO_COPY`` + + Dequeue zero copy will be enabled when this flag is set. It is disabled by + default. + + There are some truths (including limitations) you might want to know while + setting this flag: + + * zero copy is not good for small packets (typically for packet size below + 512). + + * zero copy is really good for VM2VM case. For iperf between two VMs, the + boost could be above 70% (when TSO is enableld). + + * for VM2NIC case, the ``nb_tx_desc`` has to be small enough: <= 64 if virtio + indirect feature is not enabled and <= 128 if it is enabled. + + The is because when dequeue zero copy is enabled, guest Tx used vring will + be updated only when corresponding mbuf is freed. Thus, the nb_tx_desc + has to be small enough so that the PMD driver will run out of available + Tx descriptors and free mbufs timely. Otherwise, guest Tx vring would be + starved. + + * Guest memory should be backended with huge pages to achieve better + performance. Using 1G page size is the best. + + When dequeue zero copy is enabled, the guest phys address and host phys + address mapping has to be established. Using non-huge pages means far + more page segments. To make it simple, DPDK vhost does a linear search + of those segments, thus the fewer the segments, the quicker we will get + the mapping. NOTE: we may speed it by using tree searching in future. + * ``rte_vhost_driver_session_start()`` This function starts the vhost session loop to handle vhost messages. It @@ -139,35 +152,8 @@ The following is an overview of the Vhost API functions: default. -Vhost Implementations ---------------------- - -Vhost-cuse implementation -~~~~~~~~~~~~~~~~~~~~~~~~~ - -When vSwitch registers the vhost driver, it will register a cuse device driver -into the system and creates a character device file. This cuse driver will -receive vhost open/release/IOCTL messages from the QEMU simulator. - -When the open call is received, the vhost driver will create a vhost device -for the virtio device in the guest. - -When the ``VHOST_SET_MEM_TABLE`` ioctl is received, vhost searches the memory -region to find the starting user space virtual address that maps the memory of -the guest virtual machine. Through this virtual address and the QEMU pid, -vhost can find the file QEMU uses to map the guest memory. Vhost maps this -file into its address space, in this way vhost can fully access the guest -physical memory, which means vhost could access the shared virtio ring and the -guest physical address specified in the entry of the ring. - -The guest virtual machine tells the vhost whether the virtio device is ready -for processing or is de-activated through the ``VHOST_NET_SET_BACKEND`` -message. The registered callback from vSwitch will be called. - -When the release call is made, vhost will destroy the device. - -Vhost-user implementation -~~~~~~~~~~~~~~~~~~~~~~~~~ +Vhost-user Implementations +-------------------------- Vhost-user uses Unix domain sockets for passing messages. This means the DPDK vhost-user implementation has two options: @@ -214,8 +200,6 @@ For ``VHOST_SET_MEM_TABLE`` message, QEMU will send information for each memory region and its file descriptor in the ancillary data of the message. The file descriptor is used to map that region. -There is no ``VHOST_NET_SET_BACKEND`` message as in vhost-cuse to signal -whether the virtio device is ready or stopped. Instead, ``VHOST_SET_VRING_KICK`` is used as the signal to put the vhost device into the data plane, and ``VHOST_GET_VRING_BASE`` is used as the signal to remove the vhost device from the data plane. diff --git a/doc/guides/rel_notes/deprecation.rst b/doc/guides/rel_notes/deprecation.rst index d2dc4a9a..2d17bc6e 100644 --- a/doc/guides/rel_notes/deprecation.rst +++ b/doc/guides/rel_notes/deprecation.rst @@ -8,64 +8,66 @@ API and ABI deprecation notices are to be posted here. Deprecation Notices ------------------- -* The log history is deprecated. - It is voided in 16.07 and will be removed in release 16.11. - -* The ethdev library file will be renamed from libethdev.* to librte_ethdev.* - in release 16.11 in order to have a more consistent namespace. - -* In 16.11 ABI changes are planned: the ``rte_eth_dev`` structure will be - extended with new function pointer ``tx_pkt_prep`` allowing verification +* igb_uio: iomem mapping and sysfs files created for iomem and ioport in + igb_uio will be removed, because we are able to detect these from what Linux + has exposed, like the way we have done with uio-pci-generic. This change + targets release 17.02. + +* ABI/API changes are planned for 17.02: ``rte_device``, ``rte_driver`` will be + impacted because of introduction of a new ``rte_bus`` hierarchy. This would + also impact the way devices are identified by EAL. A bus-device-driver model + will be introduced providing a hierarchical view of devices. + +* ``eth_driver`` is planned to be removed in 17.02. This currently serves as + a placeholder for PMDs to register themselves. Changes for ``rte_bus`` will + provide a way to handle device initialization currently being done in + ``eth_driver``. + +* In 17.02 ABI changes are planned: the ``rte_eth_dev`` structure will be + extended with new function pointer ``tx_pkt_prepare`` allowing verification and processing of packet burst to meet HW specific requirements before transmit. Also new fields will be added to the ``rte_eth_desc_lim`` structure: ``nb_seg_max`` and ``nb_mtu_seg_max`` providing information about number of segments limit to be transmitted by device for TSO/non-TSO packets. -* The ethdev hotplug API is going to be moved to EAL with a notification - mechanism added to crypto and ethdev libraries so that hotplug is now - available to both of them. This API will be stripped of the device arguments - so that it only cares about hotplugging. +* In 17.02 ABI change is planned: the ``rte_eth_dev_info`` structure + will be extended with a new member ``fw_version`` in order to store + the NIC firmware version. + +* ethdev: an API change is planned for 17.02 for the function + ``_rte_eth_dev_callback_process``. In 17.02 the function will return an ``int`` + instead of ``void`` and a fourth parameter ``void *ret_param`` will be added. + +* ethdev: for 17.02 it is planned to deprecate the following five functions + and move them in ixgbe: + + ``rte_eth_dev_set_vf_rxmode`` + + ``rte_eth_dev_set_vf_rx`` -* Structures embodying pci and vdev devices are going to be reworked to - integrate new common rte_device / rte_driver objects (see - http://dpdk.org/ml/archives/dev/2016-January/031390.html). - ethdev and crypto libraries will then only handle those objects so that they - do not need to care about the kind of devices that are being used, making it - easier to add new buses later. + ``rte_eth_dev_set_vf_tx`` -* ABI changes are planned for 16.11 in the ``rte_mbuf`` structure: some fields + ``rte_eth_dev_set_vf_vlan_filter`` + + ``rte_eth_set_vf_rate_limit`` + +* ABI changes are planned for 17.02 in the ``rte_mbuf`` structure: some fields may be reordered to facilitate the writing of ``data_off``, ``refcnt``, and ``nb_segs`` in one operation, because some platforms have an overhead if the store address is not naturally aligned. Other mbuf fields, such as the - ``port`` field, may be moved or removed as part of this mbuf work. + ``port`` field, may be moved or removed as part of this mbuf work. A + ``timestamp`` will also be added. * The mbuf flags PKT_RX_VLAN_PKT and PKT_RX_QINQ_PKT are deprecated and are respectively replaced by PKT_RX_VLAN_STRIPPED and PKT_RX_QINQ_STRIPPED, that are better described. The old flags and - their behavior will be kept in 16.07 and will be removed in 16.11. - -* The APIs rte_mempool_count and rte_mempool_free_count are being deprecated - on the basis that they are confusing to use - free_count actually returns - the number of allocated entries, not the number of free entries as expected. - They are being replaced by rte_mempool_avail_count and - rte_mempool_in_use_count respectively. - -* The mempool functions for single/multi producer/consumer are deprecated and - will be removed in 16.11. - It is replaced by rte_mempool_generic_get/put functions. - -* The ``rte_ivshmem`` feature (including library and EAL code) will be removed - in 16.11 because it has some design issues which are not planned to be fixed. - -* The vhost-cuse will be removed in 16.11. Since v2.1, a large majority of - development effort has gone to vhost-user, such as multiple-queue, live - migration, reconnect etc. Therefore, vhost-user should be used instead. + their behavior will be kept until 16.11 and will be removed in 17.02. -* Driver names are quite inconsistent among each others and they will be - renamed to something more consistent (net and crypto prefixes) in 16.11. - Some of these driver names are used publicly, to create virtual devices, - so a deprecation notice is necessary. +* mempool: The functions ``rte_mempool_count`` and ``rte_mempool_free_count`` + will be removed in 17.02. + They are replaced by ``rte_mempool_avail_count`` and + ``rte_mempool_in_use_count`` respectively. -* API will change for ``rte_port_source_params`` and ``rte_port_sink_params`` - structures. The member ``file_name`` data type will be changed from - ``char *`` to ``const char *``. This change targets release 16.11. +* mempool: The functions for single/multi producer/consumer are deprecated + and will be removed in 17.02. + It is replaced by ``rte_mempool_generic_get/put`` functions. diff --git a/doc/guides/rel_notes/index.rst b/doc/guides/rel_notes/index.rst index 52c63b40..7e51b2c7 100644 --- a/doc/guides/rel_notes/index.rst +++ b/doc/guides/rel_notes/index.rst @@ -36,6 +36,7 @@ Release Notes :numbered: rel_description + release_16_11 release_16_07 release_16_04 release_2_2 diff --git a/doc/guides/rel_notes/release_16_07.rst b/doc/guides/rel_notes/release_16_07.rst index 4d6e0d50..a8a3fc11 100644 --- a/doc/guides/rel_notes/release_16_07.rst +++ b/doc/guides/rel_notes/release_16_07.rst @@ -548,144 +548,3 @@ Tested OSes - Ubuntu 16.04 LTS - Wind River Linux 8 -Fixes in Stable Release ------------------------ - -16.07.1 -~~~~~~~ - -The following fixes were applied in DPDK 16.07.01 Stable Release: - -* app/test: fix verification of digest for GCM -* app/testpmd: fix crash when mempool allocation fails -* app/testpmd: fix help of MTU set commmand -* app/testpmd: fix timeout in Rx queue flushing -* contigmem: zero all pages during mmap -* crypto/null: fix key size increment value -* crypto/qat: fix FreeBSD build -* crypto: fix build with icc -* examples/ip_pipeline: fix Python interpreter -* examples/ip_pipeline: fix lcore mapping for ppc64 -* hash: fix false zero signature key hit lookup -* hash: fix ring size -* mbuf: fix error handling on pool creation -* mem: fix build with -O1 -* mem: fix crash on hugepage mapping error -* mempool: fix corruption due to invalid handler -* net/e1000: fix returned number of available Rx descriptors -* net/enic: fix bad L4 checksum flag on ICMP packets -* net/enic: fix freeing memory for descriptor ring -* net/fm10k: fix MAC address removal from switch -* net/i40e/base: fix UDP packet header -* net/i40e: fix dropping packets with ethertype 0x88A8 -* net/i40e: fix mbuf leak during Rx queue release -* net/i40e: fix null pointer dereferences when using VMDq+RSS -* net/i40e: fix parsing QinQ packets type -* net/ixgbe/base: fix check for NACK -* net/ixgbe/base: fix pointer check -* net/ixgbe/base: fix possible corruption of shadow RAM -* net/ixgbe/base: fix skipping PHY config -* net/ixgbe: fix VF reset to apply to correct VF -* net/ixgbe: fix mbuf leak during Rx queue release -* net/mlx: fix debug build with gcc 6.1 -* net/nfp: fix copying MAC address -* net/pcap: fix memory leak in jumbo frames -* net/virtio: fix xstats name -* net/virtio_user: fix error management during init -* net/virtio_user: fix first queue pair without multiqueue -* net/virtio_user: fix wrong sequence of messages -* pci: fix memory leak when detaching device -* pmdinfogen: fix clang build -* sched: fix releasing enqueued packets -* table: fix symbol exports -* timer: fix lag delay -* tools: fix json output of pmdinfo -* tools: fix virtio interface name when binding - - -16.07.2 -~~~~~~~ - -* app/procinfo: free xstats memory upon failure -* app/test: fix hash multiwriter sequence -* app/testpmd: fix DCB configuration -* app/testpmd: fix DCB configuration -* app/testpmd: fix PF/VF check of flow director -* app/testpmd: fix RSS hash key size -* app/testpmd: fix flow director endianness -* app/testpmd: fix flow director mask -* doc: add limitations for i40e PMD -* eal/arm: fix file descriptor leak when getting CPU features -* eal/ppc: fix file descriptor leak when getting CPU features -* ethdev: fix vendor id in debug message -* ethdev: prevent duplicate event callback -* examples/ip_pipeline: fix plugin loading -* examples/ipsec-secgw: check SP only when setup -* examples/l2fwd-crypto: fix verify with decrypt in chain -* examples/qos_sched: fix dequeue from ring -* examples/tep_term: fix L4 length -* examples/tep_term: fix packet length with multi-segments -* hash: fix bucket size usage -* hash: fix unlimited cuckoo path -* kni: fix build with kernel 4.8 -* kni: fix build with kernel 4.9 -* lpm: fix freeing memory -* lpm: fix freeing unused sub-table on rule delete -* mempool: fix leak if populate fails -* mempool: fix search of maximum contiguous pages -* net/bnx2x: fix build with icc -* net/bnx2x: fix maximum PF queues -* net/bnx2x: fix socket id for slowpath memory -* net/bnxt: ensure entry length is unsigned -* net/bnxt: fix bit shift size -* net/bnxt: fix crash when closing -* net/bonding: validate speed after link up -* net/ena: improve safety of string handling -* net/enic: document how to configure vNIC parameters -* net/enic: fix Rx queue index when not using Rx scatter -* net/enic: fix crash on MTU update or Rx queue reconfigure -* net/enic: fix crash with removed flow director filters -* net/enic: fix flow director -* net/enic: fix max packet length check -* net/enic: fix multi-queue Rx performance -* net/enic: revert truncated packets counter fix -* net/fm10k: fix Rx checksum flags -* net/fm10k: fix VF Tx queue initialization -* net/fm10k: fix out of order Rx read -* net/i40e: do not use VSI before NULL check -* net/i40e: fix DCB configuration -* net/i40e: fix Rx hang when disable LLDP -* net/i40e: fix VF bonded device link down -* net/i40e: fix floating VEB -* net/i40e: fix hash filter on X722 -* net/i40e: fix link status change interrupt -* net/i40e: fix out of order Rx read -* net/i40e: fixed build error with icc -* net/ixgbe: fix VF registers -* net/ixgbe: fix flow director mask -* net/ixgbe: fix out of order Rx read -* net/mlx5: fix Rx VLAN offload capability report -* net/mlx5: fix Rx checksum macros -* net/mlx5: fix Rx function selection -* net/mlx5: fix flow director drop mode -* net/mlx5: fix handling of small mbuf sizes -* net/mlx5: fix hash key size retrieval -* net/mlx5: fix inconsistent return value in flow director -* net/mlx5: fix initialization in secondary process -* net/mlx5: fix inline logic -* net/mlx5: fix link speed capability information -* net/mlx5: fix link status report -* net/mlx5: fix possible NULL dereference in Rx path -* net/mlx5: fix removing VLAN filter -* net/mlx5: fix support for newer link speeds -* net/mlx5: re-factorize functions -* net/mlx5: refactor allocation of flow director queues -* net/mlx5: support Mellanox OFED 3.4 -* net/qede/base: fix 32-bit build -* net/ring: fix ring device creation via devargs -* net/thunderx: fix Tx checksum handling -* net/virtio: revert fix restart -* net/vmxnet3: fix mbuf release on reset/stop -* pci: fix probing error if no driver found -* pdump: fix created directory permissions -* vhost: fix Windows VM hang diff --git a/doc/guides/rel_notes/release_16_11.rst b/doc/guides/rel_notes/release_16_11.rst new file mode 100644 index 00000000..8c9ec65c --- /dev/null +++ b/doc/guides/rel_notes/release_16_11.rst @@ -0,0 +1,600 @@ +DPDK Release 16.11 +================== + +.. **Read this first.** + + The text below explains how to update the release notes. + + Use proper spelling, capitalization and punctuation in all sections. + + Variable and config names should be quoted as fixed width text: ``LIKE_THIS``. + + Build the docs and view the output file to ensure the changes are correct:: + + make doc-guides-html + + firefox build/doc/html/guides/rel_notes/release_16_11.html + + +New Features +------------ + +.. This section should contain new features added in this release. Sample format: + + * **Add a title in the past tense with a full stop.** + + Add a short 1-2 sentence description in the past tense. The description + should be enough to allow someone scanning the release notes to understand + the new feature. + + If the feature adds a lot of sub-features you can use a bullet list like this. + + * Added feature foo to do something. + * Enhanced feature bar to do something else. + + Refer to the previous release notes for examples. + + This section is a comment. Make sure to start the actual text at the margin. + + +* **Added software parser for packet type.** + + * Added a new function ``rte_pktmbuf_read()`` to read the packet data from an + mbuf chain, linearizing if required. + * Added a new function ``rte_net_get_ptype()`` to parse an Ethernet packet + in an mbuf chain and retrieve its packet type from software. + * Added new functions ``rte_get_ptype_*()`` to dump a packet type as a string. + +* **Improved offloads support in mbuf.** + + * Added a new function ``rte_raw_cksum_mbuf()`` to process the checksum of + data embedded in an mbuf chain. + * Added new Rx checksum flags in mbufs to describe more states: unknown, + good, bad, or not present (useful for virtual drivers). This modification + was done for IP and L4. + * Added a new Rx LRO mbuf flag, used when packets are coalesced. This + flag indicates that the segment size of original packets is known. + +* **Added vhost-user dequeue zero copy support.** + + The copy in the dequeue path is avoided in order to improve the performance. + In the VM2VM case, the boost is quite impressive. The bigger the packet size, + the bigger performance boost you may get. However, for the VM2NIC case, there + are some limitations, so the boost is not as impressive as the VM2VM case. + It may even drop quite a bit for small packets. + + For that reason, this feature is disabled by default. It can be enabled when + the ``RTE_VHOST_USER_DEQUEUE_ZERO_COPY`` flag is set. Check the VHost section + of the Programming Guide for more information. + +* **Added vhost-user indirect descriptors support.** + + If the indirect descriptor feature is enabled, each packet sent by the guest + will take exactly one slot in the enqueue virtqueue. Without this feature, as in + the current version, even 64 bytes packets take two slots with Virtio PMD on guest + side. + + The main impact is better performance for 0% packet loss use-cases, as it + behaves as if the virtqueue size was enlarged, so more packets can be buffered + in the case of system perturbations. On the downside, small performance degradations + were measured when running micro-benchmarks. + +* **Added vhost PMD xstats.** + + Added extended statistics to vhost PMD from a per port perspective. + +* **Supported offloads with virtio.** + + Added support for the following offloads in virtio: + + * Rx/Tx checksums. + * LRO. + * TSO. + +* **Added virtio NEON support for ARM.** + + Added NEON support for ARM based virtio. + +* **Updated the ixgbe base driver.** + + Updated the ixgbe base driver, including the following changes: + + * Added X550em_a 10G PHY support. + * Added support for flow control auto negotiation for X550em_a 1G PHY. + * Added X550em_a FW ALEF support. + * Increased mailbox version to ``ixgbe_mbox_api_13``. + * Added two MAC operations for Hyper-V support. + +* **Added APIs for VF management to the ixgbe PMD.** + + Eight new APIs have been added to the ixgbe PMD for VF management from the PF. + The declarations for the API's can be found in ``rte_pmd_ixgbe.h``. + +* **Updated the enic driver.** + + * Added update to use interrupt for link status checking instead of polling. + * Added more flow director modes on UCS Blade with firmware version >= 2.0(13e). + * Added full support for MTU update. + * Added support for the ``rte_eth_rx_queue_count`` function. + +* **Updated the mlx5 driver.** + + * Added support for RSS hash results. + * Added several performance improvements. + * Added several bug fixes. + +* **Updated the QAT PMD.** + + The QAT PMD was updated with additional support for: + + * MD5_HMAC algorithm. + * SHA224-HMAC algorithm. + * SHA384-HMAC algorithm. + * GMAC algorithm. + * KASUMI (F8 and F9) algorithm. + * 3DES algorithm. + * NULL algorithm. + * C3XXX device. + * C62XX device. + +* **Added openssl PMD.** + + A new crypto PMD has been added, which provides several ciphering and hashing algorithms. + All cryptography operations use the Openssl library crypto API. + +* **Updated the IPsec example.** + + Updated the IPsec example with the following support: + + * Configuration file support. + * AES CBC IV generation with cipher forward function. + * AES GCM/CTR mode. + +* **Added support for new gcc -march option.** + + The GCC 4.9 ``-march`` option supports the Intel processor code names. + The config option ``RTE_MACHINE`` can be used to pass code names to the compiler via the ``-march`` flag. + + +Resolved Issues +--------------- + +.. This section should contain bug fixes added to the relevant sections. Sample format: + + * **code/section Fixed issue in the past tense with a full stop.** + + Add a short 1-2 sentence description of the resolved issue in the past tense. + The title should contain the code/lib section like a commit message. + Add the entries in alphabetic order in the relevant sections below. + + This section is a comment. Make sure to start the actual text at the margin. + + +Drivers +~~~~~~~ + +* **enic: Fixed several flow director issues.** + +* **enic: Fixed inadvertent setting of L4 checksum ptype on ICMP packets.** + +* **enic: Fixed high driver overhead when servicing Rx queues beyond the first.** + + + +Known Issues +------------ + +.. This section should contain new known issues in this release. Sample format: + + * **Add title in present tense with full stop.** + + Add a short 1-2 sentence description of the known issue in the present + tense. Add information on any known workarounds. + + This section is a comment. Make sure to start the actual text at the margin. + +* **L3fwd-power app does not work properly when Rx vector is enabled.** + + The L3fwd-power app doesn't work properly with some drivers in vector mode + since the queue monitoring works differently between scalar and vector modes + leading to incorrect frequency scaling. In addition, L3fwd-power application + requires the mbuf to have correct packet type set but in some drivers the + vector mode must be disabled for this. + + Therefore, in order to use L3fwd-power, vector mode should be disabled + via the config file. + +* **Digest address must be supplied for crypto auth operation on QAT PMD.** + + The cryptodev API specifies that if the rte_crypto_sym_op.digest.data field, + and by inference the digest.phys_addr field which points to the same location, + is not set for an auth operation the driver is to understand that the digest + result is located immediately following the region over which the digest is + computed. The QAT PMD doesn't correctly handle this case and reads and writes + to an incorrect location. + + Callers can workaround this by always supplying the digest virtual and + physical address fields in the rte_crypto_sym_op for an auth operation. + + +API Changes +----------- + +.. This section should contain API changes. Sample format: + + * Add a short 1-2 sentence description of the API change. Use fixed width + quotes for ``rte_function_names`` or ``rte_struct_names``. Use the past tense. + + This section is a comment. Make sure to start the actual text at the margin. + +* The driver naming convention has been changed to make them more + consistent. It especially impacts ``--vdev`` arguments. For example + ``eth_pcap`` becomes ``net_pcap`` and ``cryptodev_aesni_mb_pmd`` becomes + ``crypto_aesni_mb``. + + For backward compatibility an alias feature has been enabled to support the + original names. + +* The log history has been removed. + +* The ``rte_ivshmem`` feature (including library and EAL code) has been removed + in 16.11 because it had some design issues which were not planned to be fixed. + +* The ``file_name`` data type of ``struct rte_port_source_params`` and + ``struct rte_port_sink_params`` is changed from ``char *`` to ``const char *``. + +* **Improved device/driver hierarchy and generalized hotplugging.** + + The device and driver relationship has been restructured by introducing generic + classes. This paves the way for having PCI, VDEV and other device types as + instantiated objects rather than classes in themselves. Hotplugging has also + been generalized into EAL so that Ethernet or crypto devices can use the + common infrastructure. + + * Removed ``pmd_type`` as a way of segregation of devices. + * Moved ``numa_node`` and ``devargs`` into ``rte_driver`` from + ``rte_pci_driver``. These can now be used by any instantiated object of + ``rte_driver``. + * Added ``rte_device`` class and all PCI and VDEV devices inherit from it + * Renamed devinit/devuninit handlers to probe/remove to make it more + semantically correct with respect to the device <=> driver relationship. + * Moved hotplugging support to EAL. Hereafter, PCI and vdev can use the + APIs ``rte_eal_dev_attach`` and ``rte_eal_dev_detach``. + * Renamed helpers and support macros to make them more synonymous + with their device types + (e.g. ``PMD_REGISTER_DRIVER`` => ``RTE_PMD_REGISTER_PCI``). + * Device naming functions have been generalized from ethdev and cryptodev + to EAL. ``rte_eal_pci_device_name`` has been introduced for obtaining + unique device name from PCI Domain-BDF description. + * Virtual device registration APIs have been added: ``rte_eal_vdrv_register`` + and ``rte_eal_vdrv_unregister``. + + +ABI Changes +----------- + +.. This section should contain ABI changes. Sample format: + + * Add a short 1-2 sentence description of the ABI change that was announced in + the previous releases and made in this release. Use fixed width quotes for + ``rte_function_names`` or ``rte_struct_names``. Use the past tense. + + This section is a comment. Make sure to start the actual text at the margin. + + + +Shared Library Versions +----------------------- + +.. Update any library version updated in this release and prepend with a ``+`` + sign, like this: + + libethdev.so.4 + librte_acl.so.2 + + librte_cfgfile.so.2 + librte_cmdline.so.2 + + + +The libraries prepended with a plus sign were incremented in this version. + +.. code-block:: diff + + librte_acl.so.2 + librte_cfgfile.so.2 + librte_cmdline.so.2 + + librte_cryptodev.so.2 + librte_distributor.so.1 + + librte_eal.so.3 + + librte_ethdev.so.5 + librte_hash.so.2 + librte_ip_frag.so.1 + librte_jobstats.so.1 + librte_kni.so.2 + librte_kvargs.so.1 + librte_lpm.so.2 + librte_mbuf.so.2 + librte_mempool.so.2 + librte_meter.so.1 + librte_net.so.1 + librte_pdump.so.1 + librte_pipeline.so.3 + librte_pmd_bond.so.1 + librte_pmd_ring.so.2 + librte_port.so.3 + librte_power.so.1 + librte_reorder.so.1 + librte_ring.so.1 + librte_sched.so.1 + librte_table.so.2 + librte_timer.so.1 + librte_vhost.so.3 + + +Tested Platforms +---------------- + +.. This section should contain a list of platforms that were tested with this release. + + The format is: + + #. Platform name. + + * Platform details. + * Platform details. + + This section is a comment. Make sure to start the actual text at the margin. + +#. SuperMicro 1U + + - BIOS: 1.0c + - Processor: Intel(R) Atom(TM) CPU C2758 @ 2.40GHz + +#. SuperMicro 1U + + - BIOS: 1.0a + - Processor: Intel(R) Xeon(R) CPU D-1540 @ 2.00GHz + - Onboard NIC: Intel(R) X552/X557-AT (2x10G) + + - Firmware-version: 0x800001cf + - Device ID (PF/VF): 8086:15ad /8086:15a8 + + - kernel driver version: 4.2.5 (ixgbe) + +#. SuperMicro 2U + + - BIOS: 1.0a + - Processor: Intel(R) Xeon(R) CPU E5-4667 v3 @ 2.00GHz + +#. Intel(R) Server board S2600GZ + + - BIOS: SE5C600.86B.02.02.0002.122320131210 + - Processor: Intel(R) Xeon(R) CPU E5-2680 v2 @ 2.80GHz + +#. Intel(R) Server board W2600CR + + - BIOS: SE5C600.86B.02.01.0002.082220131453 + - Processor: Intel(R) Xeon(R) CPU E5-2680 v2 @ 2.80GHz + +#. Intel(R) Server board S2600CWT + + - BIOS: SE5C610.86B.01.01.0009.060120151350 + - Processor: Intel(R) Xeon(R) CPU E5-2699 v3 @ 2.30GHz + +#. Intel(R) Server board S2600WTT + + - BIOS: SE5C610.86B.01.01.0005.101720141054 + - Processor: Intel(R) Xeon(R) CPU E5-2699 v3 @ 2.30GHz + +#. Intel(R) Server board S2600WTT + + - BIOS: SE5C610.86B.11.01.0044.090120151156 + - Processor: Intel(R) Xeon(R) CPU E5-2695 v4 @ 2.10GHz + +#. Intel(R) Server board S2600WTT + + - Processor: Intel(R) Xeon(R) CPU E5-2697 v2 @ 2.70GHz + +#. Intel(R) Server + + - Intel(R) Xeon(R) CPU E5-2697 v3 @ 2.60GHz + +#. IBM(R) Power8(R) + + - Machine type-model: 8247-22L + - Firmware FW810.21 (SV810_108) + - Processor: POWER8E (raw), AltiVec supported + + +Tested NICs +----------- + +.. This section should contain a list of NICs that were tested with this release. + + The format is: + + #. NIC name. + + * NIC details. + * NIC details. + + This section is a comment. Make sure to start the actual text at the margin. + +#. Intel(R) Ethernet Controller X540-AT2 + + - Firmware version: 0x80000389 + - Device id (pf): 8086:1528 + - Driver version: 3.23.2 (ixgbe) + +#. Intel(R) 82599ES 10 Gigabit Ethernet Controller + + - Firmware version: 0x61bf0001 + - Device id (pf/vf): 8086:10fb / 8086:10ed + - Driver version: 4.0.1-k (ixgbe) + +#. Intel(R) Corporation Ethernet Connection X552/X557-AT 10GBASE-T + + - Firmware version: 0x800001cf + - Device id (pf/vf): 8086:15ad / 8086:15a8 + - Driver version: 4.2.5 (ixgbe) + +#. Intel(R) Ethernet Converged Network Adapter X710-DA4 (4x10G) + + - Firmware version: 5.05 + - Device id (pf/vf): 8086:1572 / 8086:154c + - Driver version: 1.5.23 (i40e) + +#. Intel(R) Ethernet Converged Network Adapter X710-DA2 (2x10G) + + - Firmware version: 5.05 + - Device id (pf/vf): 8086:1572 / 8086:154c + - Driver version: 1.5.23 (i40e) + +#. Intel(R) Ethernet Converged Network Adapter XL710-QDA1 (1x40G) + + - Firmware version: 5.05 + - Device id (pf/vf): 8086:1584 / 8086:154c + - Driver version: 1.5.23 (i40e) + +#. Intel(R) Ethernet Converged Network Adapter XL710-QDA2 (2X40G) + + - Firmware version: 5.05 + - Device id (pf/vf): 8086:1583 / 8086:154c + - Driver version: 1.5.23 (i40e) + +#. Intel(R) Corporation I350 Gigabit Network Connection + + - Firmware version: 1.48, 0x800006e7 + - Device id (pf/vf): 8086:1521 / 8086:1520 + - Driver version: 5.2.13-k (igb) + +#. Intel(R) Ethernet Multi-host Controller FM10000 + + - Firmware version: N/A + - Device id (pf/vf): 8086:15d0 + - Driver version: 0.17.0.9 (fm10k) + +#. Mellanox(R) ConnectX(R)-4 10G MCX4111A-XCAT (1x10G) + + * Host interface: PCI Express 3.0 x8 + * Device ID: 15b3:1013 + * MLNX_OFED: 3.4-1.0.0.0 + * Firmware version: 12.17.1010 + +#. Mellanox(R) ConnectX(R)-4 10G MCX4121A-XCAT (2x10G) + + * Host interface: PCI Express 3.0 x8 + * Device ID: 15b3:1013 + * MLNX_OFED: 3.4-1.0.0.0 + * Firmware version: 12.17.1010 + +#. Mellanox(R) ConnectX(R)-4 25G MCX4111A-ACAT (1x25G) + + * Host interface: PCI Express 3.0 x8 + * Device ID: 15b3:1013 + * MLNX_OFED: 3.4-1.0.0.0 + * Firmware version: 12.17.1010 + +#. Mellanox(R) ConnectX(R)-4 25G MCX4121A-ACAT (2x25G) + + * Host interface: PCI Express 3.0 x8 + * Device ID: 15b3:1013 + * MLNX_OFED: 3.4-1.0.0.0 + * Firmware version: 12.17.1010 + +#. Mellanox(R) ConnectX(R)-4 40G MCX4131A-BCAT/MCX413A-BCAT (1x40G) + + * Host interface: PCI Express 3.0 x8 + * Device ID: 15b3:1013 + * MLNX_OFED: 3.4-1.0.0.0 + * Firmware version: 12.17.1010 + +#. Mellanox(R) ConnectX(R)-4 40G MCX415A-BCAT (1x40G) + + * Host interface: PCI Express 3.0 x16 + * Device ID: 15b3:1013 + * MLNX_OFED: 3.4-1.0.0.0 + * Firmware version: 12.17.1010 + +#. Mellanox(R) ConnectX(R)-4 50G MCX4131A-GCAT/MCX413A-GCAT (1x50G) + + * Host interface: PCI Express 3.0 x8 + * Device ID: 15b3:1013 + * MLNX_OFED: 3.4-1.0.0.0 + * Firmware version: 12.17.1010 + +#. Mellanox(R) ConnectX(R)-4 50G MCX414A-BCAT (2x50G) + + * Host interface: PCI Express 3.0 x8 + * Device ID: 15b3:1013 + * MLNX_OFED: 3.4-1.0.0.0 + * Firmware version: 12.17.1010 + +#. Mellanox(R) ConnectX(R)-4 50G MCX415A-GCAT/MCX416A-BCAT/MCX416A-GCAT (2x50G) + + * Host interface: PCI Express 3.0 x16 + * Device ID: 15b3:1013 + * MLNX_OFED: 3.4-1.0.0.0 + * Firmware version: 12.17.1010 + +#. Mellanox(R) ConnectX(R)-4 50G MCX415A-CCAT (1x100G) + + * Host interface: PCI Express 3.0 x16 + * Device ID: 15b3:1013 + * MLNX_OFED: 3.4-1.0.0.0 + * Firmware version: 12.17.1010 + +#. Mellanox(R) ConnectX(R)-4 100G MCX416A-CCAT (2x100G) + + * Host interface: PCI Express 3.0 x16 + * Device ID: 15b3:1013 + * MLNX_OFED: 3.4-1.0.0.0 + * Firmware version: 12.17.1010 + +#. Mellanox(R) ConnectX(R)-4 Lx 10G MCX4121A-XCAT (2x10G) + + * Host interface: PCI Express 3.0 x8 + * Device ID: 15b3:1015 + * MLNX_OFED: 3.4-1.0.0.0 + * Firmware version: 14.17.1010 + +#. Mellanox(R) ConnectX(R)-4 Lx 25G MCX4121A-ACAT (2x25G) + + * Host interface: PCI Express 3.0 x8 + * Device ID: 15b3:1015 + * MLNX_OFED: 3.4-1.0.0.0 + * Firmware version: 14.17.1010 + + +Tested OSes +----------- + +.. This section should contain a list of OSes that were tested with this release. + The format is as follows, in alphabetical order: + + * CentOS 7.0 + * Fedora 23 + * Fedora 24 + * FreeBSD 10.3 + * Red Hat Enterprise Linux 7.2 + * SUSE Enterprise Linux 12 + * Ubuntu 15.10 + * Ubuntu 16.04 LTS + * Wind River Linux 8 + + This section is a comment. Make sure to start the actual text at the margin. + +* CentOS 7.2 +* Fedora 23 +* Fedora 24 +* FreeBSD 10.3 +* FreeBSD 11 +* Red Hat Enterprise Linux Server release 6.7 (Santiago) +* Red Hat Enterprise Linux Server release 7.0 (Maipo) +* Red Hat Enterprise Linux Server release 7.2 (Maipo) +* SUSE Enterprise Linux 12 +* Wind River Linux 6.0.0.26 +* Wind River Linux 8 +* Ubuntu 14.04 +* Ubuntu 15.04 +* Ubuntu 16.04 diff --git a/doc/guides/sample_app_ug/img/l2_fwd_vm2vm.svg b/doc/guides/sample_app_ug/img/l2_fwd_vm2vm.svg new file mode 100644 index 00000000..b84dcb27 --- /dev/null +++ b/doc/guides/sample_app_ug/img/l2_fwd_vm2vm.svg @@ -0,0 +1,311 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> + +<svg + xmlns:osb="http://www.openswatchbook.org/uri/2009/osb" + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="554.46204" + height="443.63278" + viewBox="0 0 554.46204 443.63279" + id="svg3917" + version="1.1" + inkscape:version="0.91 r13725" + sodipodi:docname="l2_fwd_vm2vm.svg"> + <defs + id="defs3919"> + <marker + inkscape:isstock="true" + style="overflow:visible" + id="marker8020" + refX="0" + refY="0" + orient="auto" + inkscape:stockid="Arrow1Lend"> + <path + transform="matrix(-0.8,0,0,-0.8,-10,0)" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1pt;stroke-opacity:1" + d="M 0,0 5,-5 -12.5,0 5,5 0,0 Z" + id="path8022" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:isstock="true" + style="overflow:visible" + id="marker7177" + refX="0" + refY="0" + orient="auto" + inkscape:stockid="Arrow1Lend"> + <path + transform="matrix(-0.8,0,0,-0.8,-10,0)" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1pt;stroke-opacity:1" + d="M 0,0 5,-5 -12.5,0 5,5 0,0 Z" + id="path7179" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:isstock="true" + style="overflow:visible" + id="marker6025" + refX="0" + refY="0" + orient="auto" + inkscape:stockid="Arrow1Lend"> + <path + transform="matrix(-0.8,0,0,-0.8,-10,0)" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1pt;stroke-opacity:1" + d="M 0,0 5,-5 -12.5,0 5,5 0,0 Z" + id="path6027" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow1Lend" + orient="auto" + refY="0" + refX="0" + id="Arrow1Lend" + style="overflow:visible" + inkscape:isstock="true" + inkscape:collect="always"> + <path + id="path5351" + d="M 0,0 5,-5 -12.5,0 5,5 0,0 Z" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1pt;stroke-opacity:1" + transform="matrix(-0.8,0,0,-0.8,-10,0)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow1Lstart" + orient="auto" + refY="0" + refX="0" + id="Arrow1Lstart" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path5348" + d="M 0,0 5,-5 -12.5,0 5,5 0,0 Z" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1pt;stroke-opacity:1" + transform="matrix(0.8,0,0,0.8,10,0)" + inkscape:connector-curvature="0" /> + </marker> + <inkscape:path-effect + effect="powerstroke" + id="path-effect4780" + is_visible="true" + offset_points="0,0.5" + sort_points="true" + interpolator_type="Linear" + interpolator_beta="0.2" + start_linecap_type="zerowidth" + linejoin_type="round" + miter_limit="4" + end_linecap_type="zerowidth" + cusp_linecap_type="round" /> + <linearGradient + id="linearGradient4729" + osb:paint="solid"> + <stop + style="stop-color:#000000;stop-opacity:1;" + offset="0" + id="stop4731" /> + </linearGradient> + <marker + inkscape:stockid="Arrow1Lend" + orient="auto" + refY="0" + refX="0" + id="Arrow1Lend-5" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path5351-3" + d="M 0,0 5,-5 -12.5,0 5,5 0,0 Z" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1pt;stroke-opacity:1" + transform="matrix(-0.8,0,0,-0.8,-10,0)" /> + </marker> + <marker + inkscape:stockid="Arrow1Lend" + orient="auto" + refY="0" + refX="0" + id="Arrow1Lend-6" + style="overflow:visible" + inkscape:isstock="true" + inkscape:collect="always"> + <path + inkscape:connector-curvature="0" + id="path5351-2" + d="M 0,0 5,-5 -12.5,0 5,5 0,0 Z" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1pt;stroke-opacity:1" + transform="matrix(-0.8,0,0,-0.8,-10,0)" /> + </marker> + <marker + inkscape:stockid="Arrow1Lend" + orient="auto" + refY="0" + refX="0" + id="Arrow1Lend-6-1" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path5351-2-2" + d="M 0,0 5,-5 -12.5,0 5,5 0,0 Z" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1pt;stroke-opacity:1" + transform="matrix(-0.8,0,0,-0.8,-10,0)" /> + </marker> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="1" + inkscape:cx="323.29803" + inkscape:cy="27.634604" + inkscape:document-units="px" + inkscape:current-layer="layer1" + showgrid="false" + inkscape:snap-nodes="false" + inkscape:snap-bbox="true" + inkscape:window-width="1276" + inkscape:window-height="1400" + inkscape:window-x="1280" + inkscape:window-y="38" + inkscape:window-maximized="0" + units="px" + fit-margin-top="5" + fit-margin-left="5" + fit-margin-right="5" + fit-margin-bottom="5" /> + <metadata + id="metadata3922"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title></dc:title> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(-0.56091356,-0.34416246)"> + <rect + style="fill:none;fill-opacity:1;stroke:#000000;stroke-width:2.10537624;stroke-opacity:1" + id="rect4727" + width="542.35669" + height="431.5274" + x="6.6136017" + y="6.3968506" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:30.53249741px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="237.30467" + y="33.252548" + id="text4735" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4737" + x="237.30467" + y="33.252548">Host</tspan></text> + <rect + style="fill:none;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect4739" + width="207.08128" + height="202.03053" + x="38.385803" + y="45.240112" /> + <rect + style="fill:none;fill-opacity:1;stroke:#000000;stroke-opacity:1" + id="rect4739-3" + width="207.08128" + height="202.03053" + x="301.53052" + y="44.22995" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:19.96650314px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="101.13004" + y="63.706543" + id="text4756" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4758" + x="101.13004" + y="63.706543">Guest1</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:19.96650314px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="369.73492" + y="63.619873" + id="text4756-6" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4758-7" + x="369.73492" + y="63.619873">Guest2</tspan></text> + <rect + style="fill:none;fill-opacity:1;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" + id="rect5336" + width="477.80215" + height="85.862968" + x="39.39595" + y="316.97116" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:23.81648636px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="237.96404" + y="398.79352" + id="text5338" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan5340" + x="237.96404" + y="398.79352">L2FWD</tspan></text> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.9760201px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow1Lend)" + d="m 120.20815,247.27063 0,68.32236" + id="path5342" + inkscape:connector-curvature="0" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.9760201px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow1Lend-5)" + d="m 382.84782,246.56645 0,68.32236" + id="path5342-5" + inkscape:connector-curvature="0" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.9760201px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow1Lend-6)" + d="m 162.63455,316.66519 0,-68.32236" + id="path5342-9" + inkscape:connector-curvature="0" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.9760201px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow1Lend-6-1)" + d="m 423.25391,315.65504 0,-68.32236" + id="path5342-9-7" + inkscape:connector-curvature="0" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.60951841;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:4.82855511, 1.60951837;stroke-dashoffset:0;stroke-opacity:1" + d="m 119.48645,319.66266 0,47.47156 303.479,0 0,-51.26929" + id="path10412" + inkscape:connector-curvature="0" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.1137104;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:3.3411313, 1.11371043;stroke-dashoffset:0;stroke-opacity:1" + d="m 162.67537,318.28501 0,31.19206 221.14177,0 0,-33.68743" + id="path10412-0" + inkscape:connector-curvature="0" /> + </g> +</svg> diff --git a/doc/guides/sample_app_ug/img/qemu_virtio_net.png b/doc/guides/sample_app_ug/img/qemu_virtio_net.png Binary files differdeleted file mode 100644 index a852c166..00000000 --- a/doc/guides/sample_app_ug/img/qemu_virtio_net.png +++ /dev/null diff --git a/doc/guides/sample_app_ug/img/tx_dpdk_testpmd.png b/doc/guides/sample_app_ug/img/tx_dpdk_testpmd.png Binary files differdeleted file mode 100644 index 656e17b8..00000000 --- a/doc/guides/sample_app_ug/img/tx_dpdk_testpmd.png +++ /dev/null diff --git a/doc/guides/sample_app_ug/img/vhost_net_arch.png b/doc/guides/sample_app_ug/img/vhost_net_arch.png Binary files differdeleted file mode 100644 index 3008feef..00000000 --- a/doc/guides/sample_app_ug/img/vhost_net_arch.png +++ /dev/null diff --git a/doc/guides/sample_app_ug/img/vhost_net_sample_app.png b/doc/guides/sample_app_ug/img/vhost_net_sample_app.png Binary files differdeleted file mode 100644 index c7a181b2..00000000 --- a/doc/guides/sample_app_ug/img/vhost_net_sample_app.png +++ /dev/null diff --git a/doc/guides/sample_app_ug/img/virtio_linux_vhost.png b/doc/guides/sample_app_ug/img/virtio_linux_vhost.png Binary files differdeleted file mode 100644 index 06142699..00000000 --- a/doc/guides/sample_app_ug/img/virtio_linux_vhost.png +++ /dev/null diff --git a/doc/guides/sample_app_ug/index.rst b/doc/guides/sample_app_ug/index.rst index 96bb3179..775e2f70 100644 --- a/doc/guides/sample_app_ug/index.rst +++ b/doc/guides/sample_app_ug/index.rst @@ -28,8 +28,8 @@ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -Sample Applications User Guide -============================== +Sample Applications User Guides +=============================== .. toctree:: :maxdepth: 2 @@ -72,11 +72,9 @@ Sample Applications User Guide dist_app vm_power_management tep_termination - proc_info ptpclient performance_thread ipsec_secgw - pdump **Figures** @@ -120,16 +118,6 @@ Sample Applications User Guide :numref:`figure_vmdq_dcb_example` :ref:`figure_vmdq_dcb_example` -:numref:`figure_qemu_virtio_net` :ref:`figure_qemu_virtio_net` - -:numref:`figure_virtio_linux_vhost` :ref:`figure_virtio_linux_vhost` - -:numref:`figure_vhost_net_arch` :ref:`figure_vhost_net_arch` - -:numref:`figure_vhost_net_sample_app` :ref:`figure_vhost_net_sample_app` - -:numref:`figure_tx_dpdk_testpmd` :ref:`figure_tx_dpdk_testpmd` - :numref:`figure_test_pipeline_app` :ref:`figure_test_pipeline_app` :numref:`figure_dist_perf` :ref:`figure_dist_perf` diff --git a/doc/guides/sample_app_ug/ipsec_secgw.rst b/doc/guides/sample_app_ug/ipsec_secgw.rst index fcb33c26..885c77e3 100644 --- a/doc/guides/sample_app_ug/ipsec_secgw.rst +++ b/doc/guides/sample_app_ug/ipsec_secgw.rst @@ -79,7 +79,7 @@ Constraints * No IPv6 options headers. * No AH mode. -* Currently only EAS-CBC, HMAC-SHA1 and NULL. +* Supported algorithms: AES-CBC, AES-CTR, AES-GCM, HMAC-SHA1 and NULL. * Each SA must be handle by a unique lcore (*1 RX queue per port*). * No chained mbufs. @@ -122,7 +122,7 @@ The application has a number of command line options:: -p PORTMASK -P -u PORTMASK --config (port,queue,lcore)[,(port,queue,lcore] --single-sa SAIDX - --ep0|--ep1 + -f CONFIG_FILE_PATH Where: @@ -142,14 +142,11 @@ Where: on both Inbound and Outbound. This option is meant for debugging/performance purposes. -* ``--ep0``: configure the app as Endpoint 0. +* ``-f CONFIG_FILE_PATH``: the full path of text-based file containing all + configuration items for running the application (See Configuration file + syntax section below). ``-f CONFIG_FILE_PATH`` **must** be specified. + **ONLY** the UNIX format configuration file is accepted. -* ``--ep1``: configure the app as Endpoint 1. - -Either one of ``--ep0`` or ``--ep1`` **must** be specified. -The main purpose of these options is to easily configure two systems -back-to-back that would forward traffic through an IPsec tunnel (see -:ref:`figure_ipsec_endpoints`). The mapping of lcores to port/queues is similar to other l3fwd applications. @@ -157,7 +154,8 @@ For example, given the following command line:: ./build/ipsec-secgw -l 20,21 -n 4 --socket-mem 0,2048 \ --vdev "cryptodev_null_pmd" -- -p 0xf -P -u 0x3 \ - --config="(0,0,20),(1,0,20),(2,0,21),(3,0,21)" --ep0 \ + --config="(0,0,20),(1,0,20),(2,0,21),(3,0,21)" \ + -f /path/to/config_file \ where each options means: @@ -194,8 +192,12 @@ where each options means: | | | | | +----------+-----------+-----------+---------------------------------------+ -* The ``--ep0`` options configures the app with a given set of SP, SA and Routing - entries as explained below in more detail. +* The ``-f /path/to/config_file`` option enables the application read and + parse the configuration file specified, and configures the application + with a given set of SP, SA and Routing entries accordingly. The syntax of + the configuration file will be explained below in more detail. Please + **note** the parser only accepts UNIX format text file. Other formats + such as DOS/MAC format will cause a parse error. Refer to the *DPDK Getting Started Guide* for general information on running applications and the Environment Abstraction Layer (EAL) options. @@ -219,496 +221,362 @@ For example, something like the following command line: --vdev "cryptodev_aesni_mb_pmd" --vdev "cryptodev_null_pmd" \ -- \ -p 0xf -P -u 0x3 --config="(0,0,20),(1,0,20),(2,0,21),(3,0,21)" \ - --ep0 + -f sample.cfg Configurations -------------- -The following sections provide some details on the default values used to -initialize the SP, SA and Routing tables. -Currently all configuration information is hard coded into the application. +The following sections provide the syntax of configurations to initialize +your SP, SA and Routing tables. +Configurations shall be specified in the configuration file to be passed to +the application. The file is then parsed by the application. The successful +parsing will result in the appropriate rules being applied to the tables +accordingly. -The following image illustrate a few of the concepts regarding IPSec, such -as protected/unprotected and inbound/outbound traffic, from the point of -view of two back-to-back endpoints: -.. _figure_ipsec_endpoints: +Configuration File Syntax +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. figure:: img/ipsec_endpoints.* +As mention in the overview, the Security Policies are ACL rules. +The application parsers the rules specified in the configuration file and +passes them to the ACL table, and replicates them per socket in use. - IPSec Inbound/Outbound traffic +Following are the configuration file syntax. -Note that the above image only displays unidirectional traffic per port -for illustration purposes. -The application supports bidirectional traffic on all ports, +General rule syntax +^^^^^^^^^^^^^^^^^^^ +The parse treats one line in the configuration file as one configuration +item (unless the line concatenation symbol exists). Every configuration +item shall follow the syntax of either SP, SA, or Routing rules specified +below. -Security Policy Initialization -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The configuration parser supports the following special symbols: -As mention in the overview, the Security Policies are ACL rules. -The application defines two ACLs, one each of Inbound and Outbound, and -it replicates them per socket in use. - -Following are the default rules which show only the relevant information, -assuming ANY value is valid for the fields not mentioned (src ip, proto, -src/dst ports). - -.. _table_ipsec_endpoint_outbound_sp: - -.. table:: Endpoint 0 Outbound Security Policies - - +-----------------------------------+------------+ - | **Dst** | **SA idx** | - | | | - +-----------------------------------+------------+ - | 192.168.105.0/24 | 5 | - | | | - +-----------------------------------+------------+ - | 192.168.106.0/24 | 6 | - | | | - +-----------------------------------+------------+ - | 192.168.175.0/24 | 10 | - | | | - +-----------------------------------+------------+ - | 192.168.176.0/24 | 11 | - | | | - +-----------------------------------+------------+ - | 192.168.200.0/24 | 15 | - | | | - +-----------------------------------+------------+ - | 192.168.201.0/24 | 16 | - | | | - +-----------------------------------+------------+ - | 192.168.55.0/24 | 25 | - | | | - +-----------------------------------+------------+ - | 192.168.56.0/24 | 26 | - | | | - +-----------------------------------+------------+ - | 192.168.240.0/24 | BYPASS | - | | | - +-----------------------------------+------------+ - | 192.168.241.0/24 | BYPASS | - | | | - +-----------------------------------+------------+ - | 0:0:0:0:5555:5555:0:0/96 | 5 | - | | | - +-----------------------------------+------------+ - | 0:0:0:0:6666:6666:0:0/96 | 6 | - | | | - +-----------------------------------+------------+ - | 0:0:1111:1111:0:0:0:0/96 | 10 | - | | | - +-----------------------------------+------------+ - | 0:0:1111:1111:1111:1111:0:0/96 | 11 | - | | | - +-----------------------------------+------------+ - | 0:0:0:0:aaaa:aaaa:0:0/96 | 25 | - | | | - +-----------------------------------+------------+ - | 0:0:0:0:bbbb:bbbb:0:0/96 | 26 | - | | | - +-----------------------------------+------------+ - -.. _table_ipsec_endpoint_inbound_sp: - -.. table:: Endpoint 0 Inbound Security Policies - - +-----------------------------------+------------+ - | **Dst** | **SA idx** | - | | | - +-----------------------------------+------------+ - | 192.168.115.0/24 | 105 | - | | | - +-----------------------------------+------------+ - | 192.168.116.0/24 | 106 | - | | | - +-----------------------------------+------------+ - | 192.168.185.0/24 | 110 | - | | | - +-----------------------------------+------------+ - | 192.168.186.0/24 | 111 | - | | | - +-----------------------------------+------------+ - | 192.168.210.0/24 | 115 | - | | | - +-----------------------------------+------------+ - | 192.168.211.0/24 | 116 | - | | | - +-----------------------------------+------------+ - | 192.168.65.0/24 | 125 | - | | | - +-----------------------------------+------------+ - | 192.168.66.0/24 | 126 | - | | | - +-----------------------------------+------------+ - | 192.168.245.0/24 | BYPASS | - | | | - +-----------------------------------+------------+ - | 192.168.246.0/24 | BYPASS | - | | | - +-----------------------------------+------------+ - | ffff:0:0:0:5555:5555:0:0/96 | 105 | - | | | - +-----------------------------------+------------+ - | ffff:0:0:0:6666:6666:0:0/96 | 106 | - | | | - +-----------------------------------+------------+ - | ffff:0:1111:1111:0:0:0:0/96 | 110 | - | | | - +-----------------------------------+------------+ - | ffff:0:1111:1111:1111:1111:0:0/96 | 111 | - | | | - +-----------------------------------+------------+ - | ffff:0:0:0:aaaa:aaaa:0:0/96 | 125 | - | | | - +-----------------------------------+------------+ - | ffff:0:0:0:bbbb:bbbb:0:0/96 | 126 | - | | | - +-----------------------------------+------------+ - -For Endpoint 1, we use the same policies in reverse, meaning the Inbound SP -entries are set as Outbound and vice versa. - - -Security Association Initialization -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The SAs are kept in a array table. - -For Inbound, the SPI is used as index modulo the table size. -This means that on a table for 100 SA, SPI 5 and 105 would use the same index -and that is not currently supported. - -Notice that it is not an issue for Outbound traffic as we store the index and -not the SPI in the Security Policy. - -All SAs configured with AES-CBC and HMAC-SHA1 share the same values for cipher -block size and key, and authentication digest size and key. - -The following are the default values: - -.. _table_ipsec_endpoint_outbound_sa: - -.. table:: Endpoint 0 Outbound Security Associations - - +---------+----------+------------+-----------+----------------+----------------+ - | **SPI** | **Mode** | **Cipher** | **Auth** | **Tunnel src** | **Tunnel dst** | - | | | | | | | - +---------+----------+------------+-----------+----------------+----------------+ - | 5 | Tunnel | AES-CBC | HMAC-SHA1 | 172.16.1.5 | 172.16.2.5 | - | | | | | | | - +---------+----------+------------+-----------+----------------+----------------+ - | 6 | Tunnel | AES-CBC | HMAC-SHA1 | 172.16.1.6 | 172.16.2.6 | - | | | | | | | - +---------+----------+------------+-----------+----------------+----------------+ - | 10 | Trans | AES-CBC | HMAC-SHA1 | N/A | N/A | - | | | | | | | - +---------+----------+------------+-----------+----------------+----------------+ - | 11 | Trans | AES-CBC | HMAC-SHA1 | N/A | N/A | - | | | | | | | - +---------+----------+------------+-----------+----------------+----------------+ - | 15 | Tunnel | NULL | NULL | 172.16.1.5 | 172.16.2.5 | - | | | | | | | - +---------+----------+------------+-----------+----------------+----------------+ - | 16 | Tunnel | NULL | NULL | 172.16.1.6 | 172.16.2.6 | - | | | | | | | - +---------+----------+------------+-----------+----------------+----------------+ - | 25 | Tunnel | AES-CBC | HMAC-SHA1 | 1111:1111: | 2222:2222: | - | | | | | 1111:1111: | 2222:2222: | - | | | | | 1111:1111: | 2222:2222: | - | | | | | 1111:5555 | 2222:5555 | - | | | | | | | - +---------+----------+------------+-----------+----------------+----------------+ - | 26 | Tunnel | AES-CBC | HMAC-SHA1 | 1111:1111: | 2222:2222: | - | | | | | 1111:1111: | 2222:2222: | - | | | | | 1111:1111: | 2222:2222: | - | | | | | 1111:6666 | 2222:6666 | - | | | | | | | - +---------+----------+------------+-----------+----------------+----------------+ - -.. _table_ipsec_endpoint_inbound_sa: - -.. table:: Endpoint 0 Inbound Security Associations - - +---------+----------+------------+-----------+----------------+----------------+ - | **SPI** | **Mode** | **Cipher** | **Auth** | **Tunnel src** | **Tunnel dst** | - | | | | | | | - +---------+----------+------------+-----------+----------------+----------------+ - | 105 | Tunnel | AES-CBC | HMAC-SHA1 | 172.16.2.5 | 172.16.1.5 | - | | | | | | | - +---------+----------+------------+-----------+----------------+----------------+ - | 106 | Tunnel | AES-CBC | HMAC-SHA1 | 172.16.2.6 | 172.16.1.6 | - | | | | | | | - +---------+----------+------------+-----------+----------------+----------------+ - | 110 | Trans | AES-CBC | HMAC-SHA1 | N/A | N/A | - | | | | | | | - +---------+----------+------------+-----------+----------------+----------------+ - | 111 | Trans | AES-CBC | HMAC-SHA1 | N/A | N/A | - | | | | | | | - +---------+----------+------------+-----------+----------------+----------------+ - | 115 | Tunnel | NULL | NULL | 172.16.2.5 | 172.16.1.5 | - | | | | | | | - +---------+----------+------------+-----------+----------------+----------------+ - | 116 | Tunnel | NULL | NULL | 172.16.2.6 | 172.16.1.6 | - | | | | | | | - +---------+----------+------------+-----------+----------------+----------------+ - | 125 | Tunnel | AES-CBC | HMAC-SHA1 | 2222:2222: | 1111:1111: | - | | | | | 2222:2222: | 1111:1111: | - | | | | | 2222:2222: | 1111:1111: | - | | | | | 2222:5555 | 1111:5555 | - | | | | | | | - +---------+----------+------------+-----------+----------------+----------------+ - | 126 | Tunnel | AES-CBC | HMAC-SHA1 | 2222:2222: | 1111:1111: | - | | | | | 2222:2222: | 1111:1111: | - | | | | | 2222:2222: | 1111:1111: | - | | | | | 2222:6666 | 1111:6666 | - | | | | | | | - +---------+----------+------------+-----------+----------------+----------------+ - -For Endpoint 1, we use the same policies in reverse, meaning the Inbound SP -entries are set as Outbound and vice versa. - - -Routing Initialization -~~~~~~~~~~~~~~~~~~~~~~ - -The Routing is implemented using an LPM table. - -Following default values: - -.. _table_ipsec_endpoint_outbound_routing: - -.. table:: Endpoint 0 Routing Table - - +------------------+----------+ - | **Dst addr** | **Port** | - | | | - +------------------+----------+ - | 172.16.2.5/32 | 0 | - | | | - +------------------+----------+ - | 172.16.2.6/32 | 1 | - | | | - +------------------+----------+ - | 192.168.175.0/24 | 0 | - | | | - +------------------+----------+ - | 192.168.176.0/24 | 1 | - | | | - +------------------+----------+ - | 192.168.240.0/24 | 0 | - | | | - +------------------+----------+ - | 192.168.241.0/24 | 1 | - | | | - +------------------+----------+ - | 192.168.115.0/24 | 2 | - | | | - +------------------+----------+ - | 192.168.116.0/24 | 3 | - | | | - +------------------+----------+ - | 192.168.65.0/24 | 2 | - | | | - +------------------+----------+ - | 192.168.66.0/24 | 3 | - | | | - +------------------+----------+ - | 192.168.185.0/24 | 2 | - | | | - +------------------+----------+ - | 192.168.186.0/24 | 3 | - | | | - +------------------+----------+ - | 192.168.210.0/24 | 2 | - | | | - +------------------+----------+ - | 192.168.211.0/24 | 3 | - | | | - +------------------+----------+ - | 192.168.245.0/24 | 2 | - | | | - +------------------+----------+ - | 192.168.246.0/24 | 3 | - | | | - +------------------+----------+ - | 2222:2222: | 0 | - | 2222:2222: | | - | 2222:2222: | | - | 2222:5555/116 | | - | | | - +------------------+----------+ - | 2222:2222: | 1 | - | 2222:2222: | | - | 2222:2222: | | - | 2222:6666/116 | | - | | | - +------------------+----------+ - | 0000:0000: | 0 | - | 1111:1111: | | - | 0000:0000: | | - | 0000:0000/116 | | - | | | - +------------------+----------+ - | 0000:0000: | 1 | - | 1111:1111: | | - | 1111:1111: | | - | 0000:0000/116 | | - | | | - +------------------+----------+ - | ffff:0000: | 2 | - | 0000:0000: | | - | aaaa:aaaa: | | - | 0000:0/116 | | - | | | - +------------------+----------+ - | ffff:0000: | 3 | - | 0000:0000: | | - | bbbb:bbbb: | | - | 0000:0/116 | | - | | | - +------------------+----------+ - | ffff:0000: | 2 | - | 0000:0000: | | - | 5555:5555: | | - | 0000:0/116 | | - | | | - +------------------+----------+ - | ffff:0000: | 3 | - | 0000:0000: | | - | 6666:6666: | | - | 0000:0/116 | | - | | | - +------------------+----------+ - | ffff:0000: | 2 | - | 1111:1111: | | - | 0000:0000: | | - | 0000:0000/116 | | - | | | - +------------------+----------+ - | ffff:0000: | 3 | - | 1111:1111: | | - | 1111:1111: | | - | 0000:0000/116 | | - | | | - +------------------+----------+ - -.. _table_ipsec_endpoint_inbound_routing: - -.. table:: Endpoint 1 Routing Table - - +------------------+----------+ - | **Dst addr** | **Port** | - | | | - +------------------+----------+ - | 172.16.1.5/32 | 0 | - | | | - +------------------+----------+ - | 172.16.1.6/32 | 1 | - | | | - +------------------+----------+ - | 192.168.185.0/24 | 0 | - | | | - +------------------+----------+ - | 192.168.186.0/24 | 1 | - | | | - +------------------+----------+ - | 192.168.245.0/24 | 0 | - | | | - +------------------+----------+ - | 192.168.246.0/24 | 1 | - | | | - +------------------+----------+ - | 192.168.105.0/24 | 2 | - | | | - +------------------+----------+ - | 192.168.106.0/24 | 3 | - | | | - +------------------+----------+ - | 192.168.55.0/24 | 2 | - | | | - +------------------+----------+ - | 192.168.56.0/24 | 3 | - | | | - +------------------+----------+ - | 192.168.175.0/24 | 2 | - | | | - +------------------+----------+ - | 192.168.176.0/24 | 3 | - | | | - +------------------+----------+ - | 192.168.200.0/24 | 2 | - | | | - +------------------+----------+ - | 192.168.201.0/24 | 3 | - | | | - +------------------+----------+ - | 192.168.240.0/24 | 2 | - | | | - +------------------+----------+ - | 192.168.241.0/24 | 3 | - | | | - +------------------+----------+ - | 1111:1111: | 0 | - | 1111:1111: | | - | 1111:1111: | | - | 1111:5555/116 | | - | | | - +------------------+----------+ - | 1111:1111: | 1 | - | 1111:1111: | | - | 1111:1111: | | - | 1111:6666/116 | | - | | | - +------------------+----------+ - | ffff:0000: | 0 | - | 1111:1111: | | - | 0000:0000: | | - | 0000:0000/116 | | - | | | - +------------------+----------+ - | ffff:0000: | 1 | - | 1111:1111: | | - | 1111:1111: | | - | 0000:0000/116 | | - | | | - +------------------+----------+ - | 0000:0000: | 2 | - | 0000:0000: | | - | aaaa:aaaa: | | - | 0000:0/116 | | - | | | - +------------------+----------+ - | 0000:0000: | 3 | - | 0000:0000: | | - | bbbb:bbbb: | | - | 0000:0/116 | | - | | | - +------------------+----------+ - | 0000:0000: | 2 | - | 0000:0000: | | - | 5555:5555: | | - | 0000:0/116 | | - | | | - +------------------+----------+ - | 0000:0000: | 3 | - | 0000:0000: | | - | 6666:6666: | | - | 0000:0/116 | | - | | | - +------------------+----------+ - | 0000:0000: | 2 | - | 1111:1111: | | - | 0000:0000: | | - | 0000:0000/116 | | - | | | - +------------------+----------+ - | 0000:0000: | 3 | - | 1111:1111: | | - | 1111:1111: | | - | 0000:0000/116 | | - | | | - +------------------+----------+ + * Comment symbol **#**. Any character from this symbol to the end of + line is treated as comment and will not be parsed. + + * Line concatenation symbol **\\**. This symbol shall be placed in the end + of the line to be concatenated to the line below. Multiple lines' + concatenation is supported. + + +SP rule syntax +^^^^^^^^^^^^^^ + +The SP rule syntax is shown as follows: + +.. code-block:: console + + sp <ip_ver> <dir> esp <action> <priority> <src_ip> <dst_ip> + <proto> <sport> <dport> + + +where each options means: + +``<ip_ver>`` + + * IP protocol version + + * Optional: No + + * Available options: + + * *ipv4*: IP protocol version 4 + * *ipv6*: IP protocol version 6 + +``<dir>`` + + * The traffic direction + + * Optional: No + + * Available options: + + * *in*: inbound traffic + * *out*: outbound traffic + +``<action>`` + + * IPsec action + + * Optional: No + + * Available options: + + * *protect <SA_idx>*: the specified traffic is protected by SA rule + with id SA_idx + * *bypass*: the specified traffic traffic is bypassed + * *discard*: the specified traffic is discarded + +``<priority>`` + + * Rule priority + + * Optional: Yes, default priority 0 will be used + + * Syntax: *pri <id>* + +``<src_ip>`` + + * The source IP address and mask + + * Optional: Yes, default address 0.0.0.0 and mask of 0 will be used + + * Syntax: + + * *src X.X.X.X/Y* for IPv4 + * *src XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX/Y* for IPv6 + +``<dst_ip>`` + + * The destination IP address and mask + + * Optional: Yes, default address 0.0.0.0 and mask of 0 will be used + + * Syntax: + + * *dst X.X.X.X/Y* for IPv4 + * *dst XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX/Y* for IPv6 + +``<proto>`` + + * The protocol start and end range + + * Optional: yes, default range of 0 to 0 will be used + + * Syntax: *proto X:Y* + +``<sport>`` + + * The source port start and end range + + * Optional: yes, default range of 0 to 0 will be used + + * Syntax: *sport X:Y* + +``<dport>`` + + * The destination port start and end range + + * Optional: yes, default range of 0 to 0 will be used + + * Syntax: *dport X:Y* + +Example SP rules: + +.. code-block:: console + + sp ipv4 out esp protect 105 pri 1 dst 192.168.115.0/24 sport 0:65535 \ + dport 0:65535 + + sp ipv6 in esp bypass pri 1 dst 0000:0000:0000:0000:5555:5555:\ + 0000:0000/96 sport 0:65535 dport 0:65535 + + +SA rule syntax +^^^^^^^^^^^^^^ + +The successfully parsed SA rules will be stored in an array table. + +The SA rule syntax is shown as follows: + +.. code-block:: console + + sa <dir> <spi> <cipher_algo> <cipher_key> <auth_algo> <auth_key> + <mode> <src_ip> <dst_ip> + +where each options means: + +``<dir>`` + + * The traffic direction + + * Optional: No + + * Available options: + + * *in*: inbound traffic + * *out*: outbound traffic + +``<spi>`` + + * The SPI number + + * Optional: No + + * Syntax: unsigned integer number + +``<cipher_algo>`` + + * Cipher algorithm + + * Optional: No + + * Available options: + + * *null*: NULL algorithm + * *aes-128-cbc*: AES-CBC 128-bit algorithm + * *aes-128-ctr*: AES-CTR 128-bit algorithm + * *aes-128-gcm*: AES-GCM 128-bit algorithm + + * Syntax: *cipher_algo <your algorithm>* + +``<cipher_key>`` + + * Cipher key, NOT available when 'null' algorithm is used + + * Optional: No, must followed by <cipher_algo> option + + * Syntax: Hexadecimal bytes (0x0-0xFF) concatenate by colon symbol ':'. + The number of bytes should be as same as the specified cipher algorithm + key size. + + For example: *cipher_key A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4: + A1:B2:C3:D4* + +``<auth_algo>`` + + * Authentication algorithm + + * Optional: No + + * Available options: + + * *null*: NULL algorithm + * *sha1-hmac*: HMAC SHA1 algorithm + * *aes-128-gcm*: AES-GCM 128-bit algorithm + +``<auth_key>`` + + * Authentication key, NOT available when 'null' or 'aes-128-gcm' algorithm + is used. + + * Optional: No, must followed by <auth_algo> option + + * Syntax: Hexadecimal bytes (0x0-0xFF) concatenate by colon symbol ':'. + The number of bytes should be as same as the specified authentication + algorithm key size. + + For example: *auth_key A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4: + A1:B2:C3:D4* + +``<mode>`` + + * The operation mode + + * Optional: No + + * Available options: + + * *ipv4-tunnel*: Tunnel mode for IPv4 packets + * *ipv6-tunnel*: Tunnel mode for IPv6 packets + * *transport*: transport mode + + * Syntax: mode XXX + +``<src_ip>`` + + * The source IP address. This option is not available when + transport mode is used + + * Optional: Yes, default address 0.0.0.0 will be used + + * Syntax: + + * *src X.X.X.X* for IPv4 + * *src XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX* for IPv6 + +``<dst_ip>`` + + * The destination IP address. This option is not available when + transport mode is used + + * Optional: Yes, default address 0.0.0.0 will be used + + * Syntax: + + * *dst X.X.X.X* for IPv4 + * *dst XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX* for IPv6 + +Example SA rules: + +.. code-block:: console + + sa out 5 cipher_algo null auth_algo null mode ipv4-tunnel \ + src 172.16.1.5 dst 172.16.2.5 + + sa out 25 cipher_algo aes-128-cbc \ + cipher_key c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3 \ + auth_algo sha1-hmac \ + auth_key c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3 \ + mode ipv6-tunnel \ + src 1111:1111:1111:1111:1111:1111:1111:5555 \ + dst 2222:2222:2222:2222:2222:2222:2222:5555 + + sa in 105 cipher_algo aes-128-gcm \ + cipher_key de:ad:be:ef:de:ad:be:ef:de:ad:be:ef:de:ad:be:ef:de:ad:be:ef \ + auth_algo aes-128-gcm \ + mode ipv4-tunnel src 172.16.2.5 dst 172.16.1.5 + +Routing rule syntax +^^^^^^^^^^^^^^^^^^^ + +The Routing rule syntax is shown as follows: + +.. code-block:: console + + rt <ip_ver> <src_ip> <dst_ip> <port> + + +where each options means: + +``<ip_ver>`` + + * IP protocol version + + * Optional: No + + * Available options: + + * *ipv4*: IP protocol version 4 + * *ipv6*: IP protocol version 6 + +``<src_ip>`` + + * The source IP address and mask + + * Optional: Yes, default address 0.0.0.0 and mask of 0 will be used + + * Syntax: + + * *src X.X.X.X/Y* for IPv4 + * *src XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX/Y* for IPv6 + +``<dst_ip>`` + + * The destination IP address and mask + + * Optional: Yes, default address 0.0.0.0 and mask of 0 will be used + + * Syntax: + + * *dst X.X.X.X/Y* for IPv4 + * *dst XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX/Y* for IPv6 + +``<port>`` + + * The traffic output port id + + * Optional: yes, default output port 0 will be used + + * Syntax: *port X* + +Example SP rules: + +.. code-block:: console + + rt ipv4 dst 172.16.1.5/32 port 0 + + rt ipv6 dst 1111:1111:1111:1111:1111:1111:1111:5555/116 port 0 diff --git a/doc/guides/sample_app_ug/l2_forward_real_virtual.rst b/doc/guides/sample_app_ug/l2_forward_real_virtual.rst index a1c10c04..cf15d1c3 100644 --- a/doc/guides/sample_app_ug/l2_forward_real_virtual.rst +++ b/doc/guides/sample_app_ug/l2_forward_real_virtual.rst @@ -50,17 +50,14 @@ performs L2 forwarding for each packet that is received on an RX_PORT. The destination port is the adjacent port from the enabled portmask, that is, if the first four ports are enabled (portmask 0xf), ports 1 and 2 forward into each other, and ports 3 and 4 forward into each other. -Also, the MAC addresses are affected as follows: +Also, if MAC addresses updating is enabled, the MAC addresses are affected as follows: * The source MAC address is replaced by the TX_PORT MAC address * The destination MAC address is replaced by 02:00:00:00:00:TX_PORT_ID -This application can be used to benchmark performance using a traffic-generator, as shown in the :numref:`figure_l2_fwd_benchmark_setup`. - -The application can also be used in a virtualized environment as shown in :numref:`figure_l2_fwd_virtenv_benchmark_setup`. - -The L2 Forwarding application can also be used as a starting point for developing a new application based on the DPDK. +This application can be used to benchmark performance using a traffic-generator, as shown in the :numref:`figure_l2_fwd_benchmark_setup`, +or in a virtualized environment as shown in :numref:`figure_l2_fwd_virtenv_benchmark_setup`. .. _figure_l2_fwd_benchmark_setup: @@ -68,13 +65,23 @@ The L2 Forwarding application can also be used as a starting point for developin Performance Benchmark Setup (Basic Environment) - .. _figure_l2_fwd_virtenv_benchmark_setup: .. figure:: img/l2_fwd_virtenv_benchmark_setup.* Performance Benchmark Setup (Virtualized Environment) +This application may be used for basic VM to VM communication as shown in :numref:`figure_l2_fwd_vm2vm`, +when MAC addresses updating is disabled. + +.. _figure_l2_fwd_vm2vm: + +.. figure:: img/l2_fwd_vm2vm.* + + Virtual Machine to Virtual Machine communication. + +The L2 Forwarding application can also be used as a starting point for developing a new application based on the DPDK. + .. _l2_fwd_vf_setup: Virtual Function Setup Instructions @@ -128,7 +135,7 @@ The application requires a number of command line options: .. code-block:: console - ./build/l2fwd [EAL options] -- -p PORTMASK [-q NQ] + ./build/l2fwd [EAL options] -- -p PORTMASK [-q NQ] --[no-]mac-updating where, @@ -136,7 +143,10 @@ where, * q NQ: A number of queues (=ports) per lcore (default is 1) -To run the application in linuxapp environment with 4 lcores, 16 ports and 8 RX queues per lcore, issue the command: +* --[no-]mac-updating: Enable or disable MAC addresses updating (enabled by default). + +To run the application in linuxapp environment with 4 lcores, 16 ports and 8 RX queues per lcore and MAC address +updating enabled, issue the command: .. code-block:: console @@ -415,7 +425,8 @@ Packets are read in a burst of size MAX_PKT_BURST. The rte_eth_rx_burst() function writes the mbuf pointers in a local table and returns the number of available mbufs in the table. Then, each mbuf in the table is processed by the l2fwd_simple_forward() function. -The processing is very simple: process the TX port from the RX port, then replace the source and destination MAC addresses. +The processing is very simple: process the TX port from the RX port, then replace the source and destination MAC addresses if MAC +addresses updating is enabled. .. note:: diff --git a/doc/guides/sample_app_ug/l3_forward.rst b/doc/guides/sample_app_ug/l3_forward.rst index e2e62236..ab916b97 100644 --- a/doc/guides/sample_app_ug/l3_forward.rst +++ b/doc/guides/sample_app_ug/l3_forward.rst @@ -42,7 +42,7 @@ The initialization and run-time paths are very similar to those of the :doc:`l2_ The main difference from the L2 Forwarding sample application is that the forwarding decision is made based on information read from the input packet. -The lookup method is either hash-based or LPM-based and is selected at compile time. When the selected lookup method is hash-based, +The lookup method is either hash-based or LPM-based and is selected at run time. When the selected lookup method is hash-based, a hash object is used to emulate the flow classification stage. The hash object is used in correlation with a flow table to map each input packet to its flow at runtime. diff --git a/doc/guides/sample_app_ug/tep_termination.rst b/doc/guides/sample_app_ug/tep_termination.rst index c3d1e97c..88e08cf9 100644 --- a/doc/guides/sample_app_ug/tep_termination.rst +++ b/doc/guides/sample_app_ug/tep_termination.rst @@ -99,7 +99,8 @@ The sample will support the followings: * TSO offload support for tunneling packet. -The following figure shows the framework of the TEP termination sample application based on vhost-cuse. +The following figure shows the framework of the TEP termination sample +application based on DPDK vhost lib. .. _figure_tep_termination_arch: @@ -118,11 +119,6 @@ The example in this section have been validated with the following distributions * Fedora* 20 -Prerequisites -------------- - -Refer to :ref:`vhost_app_prerequisites`. - Compiling the Sample Code ------------------------- #. Compile vhost lib: @@ -133,14 +129,6 @@ Compiling the Sample Code CONFIG_RTE_LIBRTE_VHOST=y - vhost user is turned on by default in the configure file config/common_linuxapp. - To enable vhost cuse, disable vhost user. - - .. code-block:: console - - CONFIG_RTE_LIBRTE_VHOST_USER=n - - After vhost is enabled and the implementation is selected, build the vhost library. #. Go to the examples directory: @@ -167,40 +155,9 @@ Compiling the Sample Code cd ${RTE_SDK}/examples/tep_termination make -#. Go to the eventfd_link directory(vhost cuse required): - - .. code-block:: console - - cd ${RTE_SDK}/lib/librte_vhost/eventfd_link - -#. Build the eventfd_link kernel module(vhost cuse required): - - .. code-block:: console - - make - Running the Sample Code ----------------------- -#. Install the cuse kernel module(vhost cuse required): - - .. code-block:: console - - modprobe cuse - -#. Go to the eventfd_link directory(vhost cuse required): - - .. code-block:: console - - export RTE_SDK=/path/to/rte_sdk - cd ${RTE_SDK}/lib/librte_vhost/eventfd_link - -#. Install the eventfd_link module(vhost cuse required): - - .. code-block:: console - - insmod ./eventfd_link.ko - #. Go to the examples directory: .. code-block:: console @@ -225,8 +182,7 @@ Parameters **The same parameters with the vhost sample.** -Refer to :ref:`vhost_app_parameters` for the meanings of 'Basename', -'Stats', 'RX Retry', 'RX Retry Number' and 'RX Retry Delay Time'. +Refer to :ref:`vhost_app_parameters` for detailed explanation. **Number of Devices.** @@ -303,12 +259,12 @@ The default value is 1. Running the Virtual Machine (QEMU) ---------------------------------- -Refer to :ref:`vhost_app_running`. +Refer to :ref:`vhost_app_run_vm`. Running DPDK in the Virtual Machine ----------------------------------- -Refer to :ref:`vhost_app_running_dpdk`. +Refer to :ref:`vhost_app_run_dpdk_inside_guest`. Passing Traffic to the Virtual Machine Device --------------------------------------------- diff --git a/doc/guides/sample_app_ug/vhost.rst b/doc/guides/sample_app_ug/vhost.rst index 2b7defc8..1f6d0d96 100644 --- a/doc/guides/sample_app_ug/vhost.rst +++ b/doc/guides/sample_app_ug/vhost.rst @@ -1,6 +1,6 @@ .. BSD LICENSE - Copyright(c) 2010-2015 Intel Corporation. All rights reserved. + Copyright(c) 2010-2016 Intel Corporation. All rights reserved. All rights reserved. Redistribution and use in source and binary forms, with or without @@ -33,820 +33,194 @@ Vhost Sample Application ======================== -The vhost sample application demonstrates integration of the Data Plane Development Kit (DPDK) -with the Linux* KVM hypervisor by implementing the vhost-net offload API. -The sample application performs simple packet switching between virtual machines based on Media Access Control -(MAC) address or Virtual Local Area Network (VLAN) tag. -The splitting of Ethernet traffic from an external switch is performed in hardware by the Virtual Machine Device Queues -(VMDQ) and Data Center Bridging (DCB) features of the Intel® 82599 10 Gigabit Ethernet Controller. +The vhost sample application demonstrates integration of the Data Plane +Development Kit (DPDK) with the Linux* KVM hypervisor by implementing the +vhost-net offload API. The sample application performs simple packet +switching between virtual machines based on Media Access Control (MAC) +address or Virtual Local Area Network (VLAN) tag. The splitting of Ethernet +traffic from an external switch is performed in hardware by the Virtual +Machine Device Queues (VMDQ) and Data Center Bridging (DCB) features of +the Intel® 82599 10 Gigabit Ethernet Controller. -Background ----------- - -Virtio networking (virtio-net) was developed as the Linux* KVM para-virtualized method for communicating network packets -between host and guest. -It was found that virtio-net performance was poor due to context switching and packet copying between host, guest, and QEMU. -The following figure shows the system architecture for a virtio-based networking (virtio-net). - -.. _figure_qemu_virtio_net: - -.. figure:: img/qemu_virtio_net.* - - System Architecture for Virtio-based Networking (virtio-net). - - -The Linux* Kernel vhost-net module was developed as an offload mechanism for virtio-net. -The vhost-net module enables KVM (QEMU) to offload the servicing of virtio-net devices to the vhost-net kernel module, -reducing the context switching and packet copies in the virtual dataplane. - -This is achieved by QEMU sharing the following information with the vhost-net module through the vhost-net API: - -* The layout of the guest memory space, to enable the vhost-net module to translate addresses. - -* The locations of virtual queues in QEMU virtual address space, - to enable the vhost module to read/write directly to and from the virtqueues. - -* An event file descriptor (eventfd) configured in KVM to send interrupts to the virtio- net device driver in the guest. - This enables the vhost-net module to notify (call) the guest. - -* An eventfd configured in KVM to be triggered on writes to the virtio-net device's - Peripheral Component Interconnect (PCI) config space. - This enables the vhost-net module to receive notifications (kicks) from the guest. - -The following figure shows the system architecture for virtio-net networking with vhost-net offload. - -.. _figure_virtio_linux_vhost: - -.. figure:: img/virtio_linux_vhost.* - - Virtio with Linux - - -Sample Code Overview --------------------- - -The DPDK vhost-net sample code demonstrates KVM (QEMU) offloading the servicing of a Virtual Machine's (VM's) -virtio-net devices to a DPDK-based application in place of the kernel's vhost-net module. - -The DPDK vhost-net sample code is based on vhost library. Vhost library is developed for user space Ethernet switch to -easily integrate with vhost functionality. - -The vhost library implements the following features: - -* Management of virtio-net device creation/destruction events. - -* Mapping of the VM's physical memory into the DPDK vhost-net's address space. - -* Triggering/receiving notifications to/from VMs via eventfds. - -* A virtio-net back-end implementation providing a subset of virtio-net features. - -There are two vhost implementations in vhost library, vhost cuse and vhost user. In vhost cuse, a character device driver is implemented to -receive and process vhost requests through ioctl messages. In vhost user, a socket server is created to received vhost requests through -socket messages. Most of the messages share the same handler routine. - -.. note:: - **Any vhost cuse specific requirement in the following sections will be emphasized**. - -Two implementations are turned on and off statically through configure file. Only one implementation could be turned on. They don't co-exist in current implementation. - -The vhost sample code application is a simple packet switching application with the following feature: - -* Packet switching between virtio-net devices and the network interface card, - including using VMDQs to reduce the switching that needs to be performed in software. - -The following figure shows the architecture of the Vhost sample application based on vhost-cuse. - -.. _figure_vhost_net_arch: - -.. figure:: img/vhost_net_arch.* - - Vhost-net Architectural Overview - - -The following figure shows the flow of packets through the vhost-net sample application. - -.. _figure_vhost_net_sample_app: - -.. figure:: img/vhost_net_sample_app.* - - Packet Flow Through the vhost-net Sample Application - - -Supported Distributions ------------------------ - -The example in this section have been validated with the following distributions: - -* Fedora* 18 - -* Fedora* 19 - -* Fedora* 20 - -.. _vhost_app_prerequisites: - -Prerequisites +Testing steps ------------- -This section lists prerequisite packages that must be installed. - -Installing Packages on the Host(vhost cuse required) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The vhost cuse code uses the following packages; fuse, fuse-devel, and kernel-modules-extra. -The vhost user code don't rely on those modules as eventfds are already installed into vhost process through -Unix domain socket. - -#. Install Fuse Development Libraries and headers: - - .. code-block:: console - - yum -y install fuse fuse-devel - -#. Install the Cuse Kernel Module: - - .. code-block:: console - - yum -y install kernel-modules-extra - -QEMU simulator -~~~~~~~~~~~~~~ - -For vhost user, qemu 2.2 is required. - -Setting up the Execution Environment -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The vhost sample code requires that QEMU allocates a VM's memory on the hugetlbfs file system. -As the vhost sample code requires hugepages, -the best practice is to partition the system into separate hugepage mount points for the VMs and the vhost sample code. - -.. note:: - - This is best-practice only and is not mandatory. - For systems that only support 2 MB page sizes, - both QEMU and vhost sample code can use the same hugetlbfs mount point without issue. - -**QEMU** - -VMs with gigabytes of memory can benefit from having QEMU allocate their memory from 1 GB huge pages. -1 GB huge pages must be allocated at boot time by passing kernel parameters through the grub boot loader. - -#. Calculate the maximum memory usage of all VMs to be run on the system. - Then, round this value up to the nearest Gigabyte the execution environment will require. - -#. Edit the /etc/default/grub file, and add the following to the GRUB_CMDLINE_LINUX entry: - - .. code-block:: console - - GRUB_CMDLINE_LINUX="... hugepagesz=1G hugepages=<Number of hugepages required> default_hugepagesz=1G" - -#. Update the grub boot loader: - - .. code-block:: console - - grub2-mkconfig -o /boot/grub2/grub.cfg - -#. Reboot the system. - -#. The hugetlbfs mount point (/dev/hugepages) should now default to allocating gigabyte pages. - -.. note:: - - Making the above modification will change the system default hugepage size to 1 GB for all applications. - -**Vhost Sample Code** - -In this section, we create a second hugetlbs mount point to allocate hugepages for the DPDK vhost sample code. - -#. Allocate sufficient 2 MB pages for the DPDK vhost sample code: - - .. code-block:: console - - echo 256 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages - -#. Mount hugetlbs at a separate mount point for 2 MB pages: - - .. code-block:: console - - mount -t hugetlbfs nodev /mnt/huge -o pagesize=2M - -The above steps can be automated by doing the following: - -#. Edit /etc/fstab to add an entry to automatically mount the second hugetlbfs mount point: - - :: - - hugetlbfs <tab> /mnt/huge <tab> hugetlbfs defaults,pagesize=1G 0 0 - -#. Edit the /etc/default/grub file, and add the following to the GRUB_CMDLINE_LINUX entry: - - :: - - GRUB_CMDLINE_LINUX="... hugepagesz=2M hugepages=256 ... default_hugepagesz=1G" - -#. Update the grub bootloader: - - .. code-block:: console - - grub2-mkconfig -o /boot/grub2/grub.cfg - -#. Reboot the system. - -.. note:: - - Ensure that the default hugepage size after this setup is 1 GB. - -Setting up the Guest Execution Environment -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -It is recommended for testing purposes that the DPDK testpmd sample application is used in the guest to forward packets, -the reasons for this are discussed in `Running the Virtual Machine (QEMU)`_. - -The testpmd application forwards packets between pairs of Ethernet devices, -it requires an even number of Ethernet devices (virtio or otherwise) to execute. -It is therefore recommended to create multiples of two virtio-net devices for each Virtual Machine either through libvirt or -at the command line as follows. - -.. note:: - - Observe that in the example, "-device" and "-netdev" are repeated for two virtio-net devices. - -For vhost cuse: - -.. code-block:: console - - qemu-system-x86_64 ... \ - -netdev tap,id=hostnet1,vhost=on,vhostfd=<open fd> \ - -device virtio-net-pci, netdev=hostnet1,id=net1 \ - -netdev tap,id=hostnet2,vhost=on,vhostfd=<open fd> \ - -device virtio-net-pci, netdev=hostnet2,id=net1 - -For vhost user: - -.. code-block:: console - - qemu-system-x86_64 ... \ - -chardev socket,id=char1,path=<sock_path> \ - -netdev type=vhost-user,id=hostnet1,chardev=char1 \ - -device virtio-net-pci,netdev=hostnet1,id=net1 \ - -chardev socket,id=char2,path=<sock_path> \ - -netdev type=vhost-user,id=hostnet2,chardev=char2 \ - -device virtio-net-pci,netdev=hostnet2,id=net2 - -sock_path is the path for the socket file created by vhost. - -Compiling the Sample Code -------------------------- -#. Compile vhost lib: - - To enable vhost, turn on vhost library in the configure file config/common_linuxapp. - - .. code-block:: console - - CONFIG_RTE_LIBRTE_VHOST=n - - vhost user is turned on by default in the configure file config/common_linuxapp. - To enable vhost cuse, disable vhost user. - - .. code-block:: console - - CONFIG_RTE_LIBRTE_VHOST_USER=y - - After vhost is enabled and the implementation is selected, build the vhost library. - -#. Go to the examples directory: - - .. code-block:: console - - export RTE_SDK=/path/to/rte_sdk - cd ${RTE_SDK}/examples/vhost - -#. Set the target (a default target is used if not specified). For example: - - .. code-block:: console - - export RTE_TARGET=x86_64-native-linuxapp-gcc - - See the DPDK Getting Started Guide for possible RTE_TARGET values. - -#. Build the application: - - .. code-block:: console - - cd ${RTE_SDK} - make config ${RTE_TARGET} - make install ${RTE_TARGET} - cd ${RTE_SDK}/examples/vhost - make - -#. Go to the eventfd_link directory(vhost cuse required): - - .. code-block:: console - - cd ${RTE_SDK}/lib/librte_vhost/eventfd_link - -#. Build the eventfd_link kernel module(vhost cuse required): - - .. code-block:: console - - make - -Running the Sample Code ------------------------ - -#. Install the cuse kernel module(vhost cuse required): - - .. code-block:: console - - modprobe cuse - -#. Go to the eventfd_link directory(vhost cuse required): - - .. code-block:: console +This section shows the steps how to test a typical PVP case with this +vhost-switch sample, whereas packets are received from the physical NIC +port first and enqueued to the VM's Rx queue. Through the guest testpmd's +default forwarding mode (io forward), those packets will be put into +the Tx queue. The vhost-switch example, in turn, gets the packets and +puts back to the same physical NIC port. - export RTE_SDK=/path/to/rte_sdk - cd ${RTE_SDK}/lib/librte_vhost/eventfd_link +Build +~~~~~ -#. Install the eventfd_link module(vhost cuse required): +Follow the *Getting Started Guide for Linux* on generic info about +environment setup and building DPDK from source. - .. code-block:: console - - insmod ./eventfd_link.ko - -#. Go to the examples directory: - - .. code-block:: console - - export RTE_SDK=/path/to/rte_sdk - cd ${RTE_SDK}/examples/vhost/build/app - -#. Run the vhost-switch sample code: - - vhost cuse: - - .. code-block:: console - - ./vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge \ - -- -p 0x1 --dev-basename usvhost - - vhost user: a socket file named usvhost will be created under current directory. Use its path as the socket path in guest's qemu commandline. - - .. code-block:: console - - ./vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge \ - -- -p 0x1 --dev-basename usvhost - -.. note:: - - Please note the huge-dir parameter instructs the DPDK to allocate its memory from the 2 MB page hugetlbfs. - -.. note:: - - The number used with the --socket-mem parameter may need to be more than 1024. - The number required depends on the number of mbufs allocated by vhost-switch. - -.. _vhost_app_parameters: - -Parameters -~~~~~~~~~~ - -**Basename.** -vhost cuse uses a Linux* character device to communicate with QEMU. -The basename is used to generate the character devices name. - - /dev/<basename> - -For compatibility with the QEMU wrapper script, a base name of "usvhost" should be used: - -.. code-block:: console - - ./vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge \ - -- -p 0x1 --dev-basename usvhost - -**vm2vm.** -The vm2vm parameter disable/set mode of packet switching between guests in the host. -Value of "0" means disabling vm2vm implies that on virtual machine packet transmission will always go to the Ethernet port; -Value of "1" means software mode packet forwarding between guests, it needs packets copy in vHOST, -so valid only in one-copy implementation, and invalid for zero copy implementation; -value of "2" means hardware mode packet forwarding between guests, it allows packets go to the Ethernet port, -hardware L2 switch will determine which guest the packet should forward to or need send to external, -which bases on the packet destination MAC address and VLAN tag. - -.. code-block:: console - - ./vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge \ - -- --vm2vm [0,1,2] - -**Mergeable Buffers.** -The mergeable buffers parameter controls how virtio-net descriptors are used for virtio-net headers. -In a disabled state, one virtio-net header is used per packet buffer; -in an enabled state one virtio-net header is used for multiple packets. -The default value is 0 or disabled since recent kernels virtio-net drivers show performance degradation with this feature is enabled. - -.. code-block:: console - - ./vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge \ - -- --mergeable [0,1] - -**Stats.** -The stats parameter controls the printing of virtio-net device statistics. -The parameter specifies an interval second to print statistics, with an interval of 0 seconds disabling statistics. - -.. code-block:: console - - ./vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge \ - -- --stats [0,n] - -**RX Retry.** -The rx-retry option enables/disables enqueue retries when the guests RX queue is full. -This feature resolves a packet loss that is observed at high data-rates, -by allowing it to delay and retry in the receive path. -This option is enabled by default. - -.. code-block:: console - - ./vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge \ - -- --rx-retry [0,1] - -**RX Retry Number.** -The rx-retry-num option specifies the number of retries on an RX burst, -it takes effect only when rx retry is enabled. -The default value is 4. +In this example, you need build DPDK both on the host and inside guest. +Also, you need build this example. .. code-block:: console - ./vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge \ - -- --rx-retry 1 --rx-retry-num 5 + export RTE_SDK=/path/to/dpdk_source + export RTE_TARGET=x86_64-native-linuxapp-gcc -**RX Retry Delay Time.** -The rx-retry-delay option specifies the timeout (in micro seconds) between retries on an RX burst, -it takes effect only when rx retry is enabled. -The default value is 15. + cd ${RTE_SDK}/examples/vhost + make -.. code-block:: console - - ./vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge \ - -- --rx-retry 1 --rx-retry-delay 20 - -**Zero copy.** -Zero copy mode is removed, due to it has not been working for a while. And -due to the large and complex code, it's better to redesign it than fixing -it to make it work again. Hence, zero copy may be added back later. -**VLAN strip.** -The VLAN strip option enable/disable the VLAN strip on host, if disabled, the guest will receive the packets with VLAN tag. -It is enabled by default. +Start the vswitch example +~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: console - ./vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge \ - -- --vlan-strip [0, 1] - -.. _vhost_app_running: - -Running the Virtual Machine (QEMU) ----------------------------------- - -QEMU must be executed with specific parameters to: - -* Ensure the guest is configured to use virtio-net network adapters. - - .. code-block:: console - - qemu-system-x86_64 ... -device virtio-net-pci,netdev=hostnet1, \ - id=net1 ... - -* Ensure the guest's virtio-net network adapter is configured with offloads disabled. - - .. code-block:: console - - qemu-system-x86_64 ... -device virtio-net-pci,netdev=hostnet1, \ - id=net1, csum=off,gso=off,guest_tso4=off,guest_tso6=off,guest_ecn=off - -* Redirect QEMU to communicate with the DPDK vhost-net sample code in place of the vhost-net kernel module(vhost cuse). - - .. code-block:: console - - qemu-system-x86_64 ... -netdev tap,id=hostnet1,vhost=on, \ - vhostfd=<open fd> ... - -* Enable the vhost-net sample code to map the VM's memory into its own process address space. - - .. code-block:: console - - qemu-system-x86_64 ... -mem-prealloc -mem-path /dev/hugepages ... - -.. note:: - - The QEMU wrapper (qemu-wrap.py) is a Python script designed to automate the QEMU configuration described above. - It also facilitates integration with libvirt, although the script may also be used standalone without libvirt. - -Redirecting QEMU to vhost-net Sample Code(vhost cuse) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To redirect QEMU to the vhost-net sample code implementation of the vhost-net API, -an open file descriptor must be passed to QEMU running as a child process. - -.. code-block:: python - - #!/usr/bin/python - fd = os.open("/dev/usvhost-1", os.O_RDWR) - subprocess.call - ("qemu-system-x86_64 ... -netdev tap,id=vhostnet0,vhost=on,vhostfd=" - + fd +"...", shell=True) - -.. note:: + ./vhost-switch -c f -n 4 --socket-mem 1024 \ + -- --socket-file /tmp/sock0 --client \ + ... - This process is automated in the `QEMU Wrapper Script`_. +Check the `Parameters`_ section for the explanations on what do those +parameters mean. -Mapping the Virtual Machine's Memory -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. _vhost_app_run_vm: -For the DPDK vhost-net sample code to be run correctly, QEMU must allocate the VM's memory on hugetlbfs. -This is done by specifying mem-prealloc and mem-path when executing QEMU. -The vhost-net sample code accesses the virtio-net device's virtual rings and packet buffers -by finding and mapping the VM's physical memory on hugetlbfs. -In this case, the path passed to the guest should be that of the 1 GB page hugetlbfs: +Start the VM +~~~~~~~~~~~~ .. code-block:: console - qemu-system-x86_64 ... -mem-prealloc -mem-path /dev/hugepages ... + qemu-system-x86_64 -machine accel=kvm -cpu host \ + -m $mem -object memory-backend-file,id=mem,size=$mem,mem-path=/dev/hugepages,share=on \ + -mem-prealloc -numa node,memdev=mem \ + \ + -chardev socket,id=char1,path=/tmp/sock0,server \ + -netdev type=vhost-user,id=hostnet1,chardev=char1 \ + -device virtio-net-pci,netdev=hostnet1,id=net1,mac=52:54:00:00:00:14 \ + ... .. note:: + For basic vhost-user support, QEMU 2.2 (or above) is required. For + some specific features, a higher version might be need. Such as + QEMU 2.7 (or above) for the reconnect feature. - This process is automated in the `QEMU Wrapper Script`_. - The following two sections only applies to vhost cuse. - For vhost-user, please make corresponding changes to qemu-wrapper script and guest XML file. +.. _vhost_app_run_dpdk_inside_guest: -QEMU Wrapper Script -~~~~~~~~~~~~~~~~~~~ +Run testpmd inside guest +~~~~~~~~~~~~~~~~~~~~~~~~ -The QEMU wrapper script automatically detects and calls QEMU with the necessary parameters required -to integrate with the vhost sample code. -It performs the following actions: - -* Automatically detects the location of the hugetlbfs and inserts this into the command line parameters. - -* Automatically open file descriptors for each virtio-net device and inserts this into the command line parameters. - -* Disables offloads on each virtio-net device. - -* Calls Qemu passing both the command line parameters passed to the script itself and those it has auto-detected. - -The QEMU wrapper script will automatically configure calls to QEMU: +Make sure you have DPDK built inside the guest. Also make sure the +corresponding virtio-net PCI device is bond to a uio driver, which +could be done by: .. code-block:: console - qemu-wrap.py -machine pc-i440fx-1.4,accel=kvm,usb=off \ - -cpu SandyBridge -smp 4,sockets=4,cores=1,threads=1 \ - -netdev tap,id=hostnet1,vhost=on \ - -device virtio-net-pci,netdev=hostnet1,id=net1 \ - -hda <disk img> -m 4096 + modprobe uio_pci_generic + $RTE_SDK/tools/dpdk-devbind.py -b=uio_pci_generic 0000:00:04.0 -which will become the following call to QEMU: +Then start testpmd for packet forwarding testing. .. code-block:: console - qemu-system-x86_64 -machine pc-i440fx-1.4,accel=kvm,usb=off \ - -cpu SandyBridge -smp 4,sockets=4,cores=1,threads=1 \ - -netdev tap,id=hostnet1,vhost=on,vhostfd=<open fd> \ - -device virtio-net-pci,netdev=hostnet1,id=net1, \ - csum=off,gso=off,guest_tso4=off,guest_tso6=off,guest_ecn=off \ - -hda <disk img> -m 4096 -mem-path /dev/hugepages -mem-prealloc - -Libvirt Integration -~~~~~~~~~~~~~~~~~~~ - -The QEMU wrapper script (qemu-wrap.py) "wraps" libvirt calls to QEMU, -such that QEMU is called with the correct parameters described above. -To call the QEMU wrapper automatically from libvirt, the following configuration changes must be made: - -* Place the QEMU wrapper script in libvirt's binary search PATH ($PATH). - A good location is in the directory that contains the QEMU binary. - -* Ensure that the script has the same owner/group and file permissions as the QEMU binary. + ./x86_64-native-gcc/app/testpmd -c 0x3 -- -i + > start tx_first -* Update the VM xml file using virsh edit <vm name>: +Inject packets +-------------- - * Set the VM to use the launch script +While a virtio-net is connected to vhost-switch, a VLAN tag starts with +1000 is assigned to it. So make sure configure your packet generator +with the right MAC and VLAN tag, you should be able to see following +log from the vhost-switch console. It means you get it work:: - * Set the emulator path contained in the #<emulator><emulator/> tags For example, - replace <emulator>/usr/bin/qemu-kvm<emulator/> with <emulator>/usr/bin/qemu-wrap.py<emulator/> + VHOST_DATA: (0) mac 52:54:00:00:00:14 and vlan 1000 registered - * Set the VM's virtio-net device's to use vhost-net offload: - .. code-block:: xml - - <interface type="network"> - <model type="virtio"/> - <driver name="vhost"/> - <interface/> - - * Enable libvirt to access the DPDK Vhost sample code's character device file by adding it - to controllers cgroup for libvirtd using the following steps: - - .. code-block:: xml - - cgroup_controllers = [ ... "devices", ... ] clear_emulator_capabilities = 0 - user = "root" group = "root" - cgroup_device_acl = [ - "/dev/null", "/dev/full", "/dev/zero", - "/dev/random", "/dev/urandom", - "/dev/ptmx", "/dev/kvm", "/dev/kqemu", - "/dev/rtc", "/dev/hpet", "/dev/net/tun", - "/dev/<devbase-name>-<index>", - ] - -* Disable SELinux or set to permissive mode. +.. _vhost_app_parameters: +Parameters +---------- -* Mount cgroup device controller: +**--socket-file path** +Specifies the vhost-user socket file path. - .. code-block:: console +**--client** +DPDK vhost-user will act as the client mode when such option is given. +In the client mode, QEMU will create the socket file. Otherwise, DPDK +will create it. Put simply, it's the server to create the socket file. - mkdir /dev/cgroup - mount -t cgroup none /dev/cgroup -o devices -* Restart the libvirtd system process +**--vm2vm mode** +The vm2vm parameter sets the mode of packet switching between guests in +the host. - For example, on Fedora* "systemctl restart libvirtd.service" +- 0 disables vm2vm, impling that VM's packets will always go to the NIC port. +- 1 means a normal mac lookup packet routing. +- 2 means hardware mode packet forwarding between guests, it allows packets + go to the NIC port, hardware L2 switch will determine which guest the + packet should forward to or need send to external, which bases on the + packet destination MAC address and VLAN tag. -* Edit the configuration parameters section of the script: +**--mergeable 0|1** +Set 0/1 to disable/enable the mergeable Rx feature. It's disabled by default. - * Configure the "emul_path" variable to point to the QEMU emulator. +**--stats interval** +The stats parameter controls the printing of virtio-net device statistics. +The parameter specifies an interval (in unit of seconds) to print statistics, +with an interval of 0 seconds disabling statistics. - .. code-block:: xml +**--rx-retry 0|1** +The rx-retry option enables/disables enqueue retries when the guests Rx queue +is full. This feature resolves a packet loss that is observed at high data +rates, by allowing it to delay and retry in the receive path. This option is +enabled by default. - emul_path = "/usr/local/bin/qemu-system-x86_64" +**--rx-retry-num num** +The rx-retry-num option specifies the number of retries on an Rx burst, it +takes effect only when rx retry is enabled. The default value is 4. - * Configure the "us_vhost_path" variable to point to the DPDK vhost-net sample code's character devices name. - DPDK vhost-net sample code's character device will be in the format "/dev/<basename>". +**--rx-retry-delay msec** +The rx-retry-delay option specifies the timeout (in micro seconds) between +retries on an RX burst, it takes effect only when rx retry is enabled. The +default value is 15. - .. code-block:: xml +**--dequeue-zero-copy** +Dequeue zero copy will be enabled when this option is given. - us_vhost_path = "/dev/usvhost" +**--vlan-strip 0|1** +VLAN strip option is removed, because different NICs have different behaviors +when disabling VLAN strip. Such feature, which heavily depends on hardware, +should be removed from this example to reduce confusion. Now, VLAN strip is +enabled and cannot be disabled. Common Issues -~~~~~~~~~~~~~ - -* QEMU failing to allocate memory on hugetlbfs, with an error like the following:: - - file_ram_alloc: can't mmap RAM pages: Cannot allocate memory - - When running QEMU the above error indicates that it has failed to allocate memory for the Virtual Machine on - the hugetlbfs. This is typically due to insufficient hugepages being free to support the allocation request. - The number of free hugepages can be checked as follows: - - .. code-block:: console - - cat /sys/kernel/mm/hugepages/hugepages-<pagesize>/nr_hugepages - - The command above indicates how many hugepages are free to support QEMU's allocation request. - -* User space VHOST when the guest has 2MB sized huge pages: - - The guest may have 2MB or 1GB sized huge pages. The user space VHOST should work properly in both cases. - -* User space VHOST will not work with QEMU without the ``-mem-prealloc`` option: - - The current implementation works properly only when the guest memory is pre-allocated, so it is required to - use a QEMU version (e.g. 1.6) which supports ``-mem-prealloc``. The ``-mem-prealloc`` option must be - specified explicitly in the QEMU command line. - -* User space VHOST will not work with a QEMU version without shared memory mapping: - - As shared memory mapping is mandatory for user space VHOST to work properly with the guest, user space VHOST - needs access to the shared memory from the guest to receive and transmit packets. It is important to make sure - the QEMU version supports shared memory mapping. - -* In an Ubuntu environment, QEMU fails to start a new guest normally with user space VHOST due to not being able - to allocate huge pages for the new guest: - - The solution for this issue is to add ``-boot c`` into the QEMU command line to make sure the huge pages are - allocated properly and then the guest should start normally. - - Use ``cat /proc/meminfo`` to check if there is any changes in the value of ``HugePages_Total`` and ``HugePages_Free`` - after the guest startup. - -* Log message: ``eventfd_link: module verification failed: signature and/or required key missing - tainting kernel``: - - This log message may be ignored. The message occurs due to the kernel module ``eventfd_link``, which is not a standard - Linux module but which is necessary for the user space VHOST current implementation (CUSE-based) to communicate with - the guest. - -.. _vhost_app_running_dpdk: - -Running DPDK in the Virtual Machine ------------------------------------ - -For the DPDK vhost-net sample code to switch packets into the VM, -the sample code must first learn the MAC address of the VM's virtio-net device. -The sample code detects the address from packets being transmitted from the VM, similar to a learning switch. - -This behavior requires no special action or configuration with the Linux* virtio-net driver in the VM -as the Linux* Kernel will automatically transmit packets during device initialization. -However, DPDK-based applications must be modified to automatically transmit packets during initialization -to facilitate the DPDK vhost- net sample code's MAC learning. - -The DPDK testpmd application can be configured to automatically transmit packets during initialization -and to act as an L2 forwarding switch. - -Testpmd MAC Forwarding -~~~~~~~~~~~~~~~~~~~~~~ - -At high packet rates, a minor packet loss may be observed. -To resolve this issue, a "wait and retry" mode is implemented in the testpmd and vhost sample code. -In the "wait and retry" mode if the virtqueue is found to be full, then testpmd waits for a period of time before retrying to enqueue packets. - -The "wait and retry" algorithm is implemented in DPDK testpmd as a forwarding method call "mac_retry". -The following sequence diagram describes the algorithm in detail. - -.. _figure_tx_dpdk_testpmd: - -.. figure:: img/tx_dpdk_testpmd.* - - Packet Flow on TX in DPDK-testpmd - - -Running Testpmd -~~~~~~~~~~~~~~~ - -The testpmd application is automatically built when DPDK is installed. -Run the testpmd application as follows: - -.. code-block:: console - - cd ${RTE_SDK}/x86_64-native-linuxapp-gcc/app - ./testpmd -c 0x3 -n 4 --socket-mem 512 \ - -- --burst=64 --i --disable-hw-vlan-filter - -The destination MAC address for packets transmitted on each port can be set at the command line: - -.. code-block:: console - - ./testpmd -c 0x3 -n 4 --socket-mem 512 \ - -- --burst=64 --i --disable-hw-vlan-filter \ - --eth-peer=0,aa:bb:cc:dd:ee:ff --eth-peer=1,ff:ee:dd:cc:bb:aa - -* Packets received on port 1 will be forwarded on port 0 to MAC address - - aa:bb:cc:dd:ee:ff - -* Packets received on port 0 will be forwarded on port 1 to MAC address - - ff:ee:dd:cc:bb:aa - -The testpmd application can then be configured to act as an L2 forwarding application: - -.. code-block:: console - - testpmd> set fwd mac_retry - -The testpmd can then be configured to start processing packets, -transmitting packets first so the DPDK vhost sample code on the host can learn the MAC address: - -.. code-block:: console - - testpmd> start tx_first +------------- -.. note:: +* QEMU fails to allocate memory on hugetlbfs, with an error like the + following:: - Please note "set fwd mac_retry" is used in place of "set fwd mac_fwd" to ensure the retry feature is activated. + file_ram_alloc: can't mmap RAM pages: Cannot allocate memory -Passing Traffic to the Virtual Machine Device ---------------------------------------------- + When running QEMU the above error indicates that it has failed to allocate + memory for the Virtual Machine on the hugetlbfs. This is typically due to + insufficient hugepages being free to support the allocation request. The + number of free hugepages can be checked as follows: -For a virtio-net device to receive traffic, -the traffic's Layer 2 header must include both the virtio-net device's MAC address and VLAN tag. -The DPDK sample code behaves in a similar manner to a learning switch in that -it learns the MAC address of the virtio-net devices from the first transmitted packet. -On learning the MAC address, -the DPDK vhost sample code prints a message with the MAC address and VLAN tag virtio-net device. -For example: + .. code-block:: console -.. code-block:: console + cat /sys/kernel/mm/hugepages/hugepages-<pagesize>/nr_hugepages - DATA: (0) MAC_ADDRESS cc:bb:bb:bb:bb:bb and VLAN_TAG 1000 registered + The command above indicates how many hugepages are free to support QEMU's + allocation request. -The above message indicates that device 0 has been registered with MAC address cc:bb:bb:bb:bb:bb and VLAN tag 1000. -Any packets received on the NIC with these values is placed on the devices receive queue. -When a virtio-net device transmits packets, the VLAN tag is added to the packet by the DPDK vhost sample code. +* vhost-user will not work with QEMU without the ``-mem-prealloc`` option -Running virtio_user with vhost-switch -------------------------------------- + The current implementation works properly only when the guest memory is + pre-allocated. -We can also use virtio_user with vhost-switch now. -Virtio_user is a virtual device that can be run in a application (container) parallelly with vhost in the same OS, -aka, there is no need to start a VM. We just run it with a different --file-prefix to avoid startup failure. +* vhost-user will not work with a QEMU version without shared memory mapping: -.. code-block:: console + Make sure ``share=on`` QEMU option is given. - cd ${RTE_SDK}/x86_64-native-linuxapp-gcc/app - ./testpmd -c 0x3 -n 4 --socket-mem 1024 --no-pci --file-prefix=virtio_user-testpmd \ - --vdev=virtio_user0,mac=00:01:02:03:04:05,path=$path_vhost \ - -- -i --txqflags=0xf01 --disable-hw-vlan +* Failed to build DPDK in VM -There is no difference on the vhost side. -Pleae note that there are some limitations (see release note for more information) in the usage of virtio_user. + Make sure "-cpu host" QEMU option is given. diff --git a/doc/guides/testpmd_app_ug/run_app.rst b/doc/guides/testpmd_app_ug/run_app.rst index 7712bd24..d7c51209 100644 --- a/doc/guides/testpmd_app_ug/run_app.rst +++ b/doc/guides/testpmd_app_ug/run_app.rst @@ -130,7 +130,7 @@ See the DPDK Getting Started Guides for more information on these options. For example:: - --vdev 'eth_pcap0,rx_pcap=input.pcap,tx_pcap=output.pcap' + --vdev 'net_pcap0,rx_pcap=input.pcap,tx_pcap=output.pcap' * ``--base-virtaddr`` @@ -285,6 +285,10 @@ The commandline options are: Enable hardware CRC stripping. +* ``--enable-lro`` + + Enable large receive offload. + * ``--enable-rx-cksum`` Enable hardware RX checksum offload. @@ -450,7 +454,8 @@ The commandline options are: * ``--txpkts=X[,Y]`` - Set TX segment sizes. + Set TX segment sizes or total packet length. Valid for ``tx-only`` + and ``flowgen`` forwarding modes. * ``--disable-link-check`` diff --git a/doc/guides/testpmd_app_ug/testpmd_funcs.rst b/doc/guides/testpmd_app_ug/testpmd_funcs.rst index ed04532a..f1c269a3 100644 --- a/doc/guides/testpmd_app_ug/testpmd_funcs.rst +++ b/doc/guides/testpmd_app_ug/testpmd_funcs.rst @@ -1,5 +1,5 @@ .. BSD LICENSE - Copyright(c) 2010-2015 Intel Corporation. All rights reserved. + Copyright(c) 2010-2016 Intel Corporation. All rights reserved. All rights reserved. Redistribution and use in source and binary forms, with or without @@ -35,7 +35,8 @@ Testpmd Runtime Functions Where the testpmd application is started in interactive mode, (``-i|--interactive``), it displays a prompt that can be used to start and stop forwarding, -configure the application, display statistics, set the Flow Director and other tasks:: +configure the application, display statistics (including the extended NIC +statistics aka xstats) , set the Flow Director and other tasks:: testpmd> @@ -50,10 +51,10 @@ If you type a partial command and hit ``<TAB>`` you get a list of the available testpmd> show port <TAB> - info [Mul-choice STRING]: show|clear port info|stats|fdir|stat_qmap|dcb_tc X - info [Mul-choice STRING]: show|clear port info|stats|fdir|stat_qmap|dcb_tc all - stats [Mul-choice STRING]: show|clear port info|stats|fdir|stat_qmap|dcb_tc X - stats [Mul-choice STRING]: show|clear port info|stats|fdir|stat_qmap|dcb_tc all + info [Mul-choice STRING]: show|clear port info|stats|xstats|fdir|stat_qmap|dcb_tc X + info [Mul-choice STRING]: show|clear port info|stats|xstats|fdir|stat_qmap|dcb_tc all + stats [Mul-choice STRING]: show|clear port info|stats|xstats|fdir|stat_qmap|dcb_tc X + stats [Mul-choice STRING]: show|clear port info|stats|xstats|fdir|stat_qmap|dcb_tc all ... @@ -130,7 +131,7 @@ show port Display information for a given port or all ports:: - testpmd> show port (info|stats|fdir|stat_qmap|dcb_tc) (port_id|all) + testpmd> show port (info|stats|xstats|fdir|stat_qmap|dcb_tc) (port_id|all) The available information categories are: @@ -138,6 +139,8 @@ The available information categories are: * ``stats``: RX/TX statistics. +* ``xstats``: RX/TX extended NIC statistics. + * ``fdir``: Flow Director information and statistics. * ``stat_qmap``: Queue statistics mapping. @@ -205,7 +208,7 @@ clear port Clear the port statistics for a given port or for all ports:: - testpmd> clear port (info|stats|fdir|stat_qmap) (port_id|all) + testpmd> clear port (info|stats|xstats|fdir|stat_qmap) (port_id|all) For example:: @@ -267,6 +270,9 @@ The available information categories are: This is the default mode. * ``mac``: Changes the source and the destination Ethernet addresses of packets before forwarding them. + Default application behaviour is to set source Ethernet address to that of the transmitting interface, and destination + address to a dummy value (set during init). The user may specify a target destination Ethernet address via the 'eth-peer' or + 'eth-peer-configfile' command-line options. It is not currently possible to specify a specific source Ethernet address. * ``macswap``: MAC swap forwarding mode. Swaps the source and the destination Ethernet addresses of packets before forwarding them. @@ -405,7 +411,7 @@ When retry is enabled, the transmit delay time and number of retries can also be set txpkts ~~~~~~~~~~ -Set the length of each segment of the TX-ONLY packets:: +Set the length of each segment of the TX-ONLY packets or length of packet for FLOWGEN mode:: testpmd> set txpkts (x[,y]*) @@ -473,6 +479,34 @@ For example, to change the port forwarding: RX P=1/Q=0 (socket 0) -> TX P=3/Q=0 (socket 0) peer=02:00:00:00:00:03 RX P=3/Q=0 (socket 0) -> TX P=1/Q=0 (socket 0) peer=02:00:00:00:00:02 +set tx loopback +~~~~~~~~~~~~~~~ + +Enable/disable tx loopback:: + + testpmd> set tx loopback (port_id) (on|off) + +set drop enable +~~~~~~~~~~~~~~~ + +set drop enable bit for all queues:: + + testpmd> set all queues drop (port_id) (on|off) + +set split drop enable (for VF) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +set split drop enable bit for VF from PF:: + + testpmd> set vf split drop (port_id) (vf_id) (on|off) + +set mac antispoof (for VF) +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Set mac antispoof for a VF from the PF:: + + testpmd> set vf mac antispoof (port_id) (vf_id) (on|off) + vlan set strip ~~~~~~~~~~~~~~ @@ -487,6 +521,27 @@ Set the VLAN strip for a queue on a port:: testpmd> vlan set stripq (on|off) (port_id,queue_id) +vlan set stripq (for VF) +~~~~~~~~~~~~~~~~~~~~~~~~ + +Set VLAN strip for all queues in a pool for a VF from the PF:: + + testpmd> set vf vlan stripq (port_id) (vf_id) (on|off) + +vlan set insert (for VF) +~~~~~~~~~~~~~~~~~~~~~~~~ + +Set VLAN insert for a VF from the PF:: + + testpmd> set vf vlan insert (port_id) (vf_id) (vlan_id) + +vlan set antispoof (for VF) +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Set VLAN antispoof for a VF from the PF:: + + testpmd> set vf vlan antispoof (port_id) (vf_id) (on|off) + vlan set filter ~~~~~~~~~~~~~~~ @@ -727,13 +782,20 @@ Remove a MAC address from a port:: testpmd> mac_addr remove (port_id) (XX:XX:XX:XX:XX:XX) -mac_addr add(for VF) -~~~~~~~~~~~~~~~~~~~~ +mac_addr add (for VF) +~~~~~~~~~~~~~~~~~~~~~ Add an alternative MAC address for a VF to a port:: testpmd> mac_add add port (port_id) vf (vf_id) (XX:XX:XX:XX:XX:XX) +mac_addr set (for VF) +~~~~~~~~~~~~~~~~~~~~~ + +Set the MAC address for a VF from the PF:: + + testpmd> set vf mac addr (port_id) (vf_id) (XX:XX:XX:XX:XX:XX) + set port-uta ~~~~~~~~~~~~ @@ -1041,14 +1103,14 @@ For example, to attach a port created by pcap PMD. .. code-block:: console - testpmd> port attach eth_pcap0 + testpmd> port attach net_pcap0 Attaching a new port... - PMD: Initializing pmd_pcap for eth_pcap0 + PMD: Initializing pmd_pcap for net_pcap0 PMD: Creating pcap-backed ethdev on numa socket 0 Port 0 is attached. Now total ports is 1 Done -In this case, identifier is ``eth_pcap0``. +In this case, identifier is ``net_pcap0``. This identifier format is the same as ``--vdev`` format of DPDK applications. For example, to re-attach a bonded port which has been previously detached, @@ -1056,10 +1118,10 @@ the mode and slave parameters must be given. .. code-block:: console - testpmd> port attach eth_bond_0,mode=0,slave=1 + testpmd> port attach net_bond_0,mode=0,slave=1 Attaching a new port... - EAL: Initializing pmd_bond for eth_bond_0 - EAL: Create bonded device eth_bond_0 on port 0 in mode 0 on socket 0. + EAL: Initializing pmd_bond for net_bond_0 + EAL: Create bonded device net_bond_0 on port 0 in mode 0 on socket 0. Port 0 is attached. Now total ports is 1 Done @@ -1107,7 +1169,7 @@ For example, to detach a virtual device port 0. testpmd> port detach 0 Detaching a port... PMD: Closing pcap ethdev on numa socket 0 - Port 'eth_pcap0' is detached. Now total ports is 0 + Port 'net_pcap0' is detached. Now total ports is 0 Done To remove a pci device completely from the system, first detach the port from testpmd. @@ -1167,7 +1229,7 @@ port config - speed Set the speed and duplex mode for all ports or a specific port:: - testpmd> port config (port_id|all) speed (10|100|1000|10000|40000|100000|auto) \ + testpmd> port config (port_id|all) speed (10|100|1000|10000|25000|40000|50000|100000|auto) \ duplex (half|full|auto) port config - queues/descriptors diff --git a/doc/guides/tools/devbind.rst b/doc/guides/tools/devbind.rst new file mode 100644 index 00000000..cabd99dd --- /dev/null +++ b/doc/guides/tools/devbind.rst @@ -0,0 +1,143 @@ +.. BSD LICENSE + Copyright(c) 2016 Canonical Limited. 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. + + +dpdk-devbind Application +======================== + +The ``dpdk-devbind`` tool is a Data Plane Development Kit (DPDK) utility +that helps binding and unbinding devices from specific drivers. +As well as checking their status in that regard. + + +Running the Application +----------------------- + +The tool has a number of command line options: + +.. code-block:: console + + dpdk-devbind [options] DEVICE1 DEVICE2 .... + +OPTIONS +------- + +* ``--help, --usage`` + + Display usage information and quit + +* ``-s, --status`` + + Print the current status of all known network interfaces. + For each device, it displays the PCI domain, bus, slot and function, + along with a text description of the device. Depending upon whether the + device is being used by a kernel driver, the ``igb_uio`` driver, or no + driver, other relevant information will be displayed: + - the Linux interface name e.g. ``if=eth0`` + - the driver being used e.g. ``drv=igb_uio`` + - any suitable drivers not currently using that device e.g. ``unused=igb_uio`` + NOTE: if this flag is passed along with a bind/unbind option, the + status display will always occur after the other operations have taken + place. + +* ``-b driver, --bind=driver`` + + Select the driver to use or "none" to unbind the device + +* ``-u, --unbind`` + + Unbind a device (Equivalent to ``-b none``) + +* ``--force`` + + By default, devices which are used by Linux - as indicated by having + routes in the routing table - cannot be modified. Using the ``--force`` + flag overrides this behavior, allowing active links to be forcibly + unbound. + WARNING: This can lead to loss of network connection and should be used + with caution. + + +.. warning:: + + Due to the way VFIO works, there are certain limitations to which devices can be used with VFIO. + Mainly it comes down to how IOMMU groups work. + Any Virtual Function device can be used with VFIO on its own, but physical devices will require either all ports bound to VFIO, + or some of them bound to VFIO while others not being bound to anything at all. + + If your device is behind a PCI-to-PCI bridge, the bridge will then be part of the IOMMU group in which your device is in. + Therefore, the bridge driver should also be unbound from the bridge PCI device for VFIO to work with devices behind the bridge. + +.. warning:: + + While any user can run the ``dpdk-devbind.py`` script to view the status of the network ports, + binding or unbinding network ports requires root privileges. + + +Examples +-------- + +To display current device status:: + + dpdk-devbind --status + +To bind eth1 from the current driver and move to use igb_uio:: + + dpdk-devbind --bind=igb_uio eth1 + +To unbind 0000:01:00.0 from using any driver:: + + dpdk-devbind -u 0000:01:00.0 + +To bind 0000:02:00.0 and 0000:02:00.1 to the ixgbe kernel driver:: + + dpdk-devbind -b ixgbe 02:00.0 02:00.1 + +To check status of all network ports, assign one to the igb_uio driver and check status again:: + + # Check the status of the available devices. + dpdk-devbind --status + Network devices using DPDK-compatible driver + ============================================ + <none> + + Network devices using kernel driver + =================================== + 0000:0a:00.0 '82599ES 10-Gigabit' if=eth2 drv=ixgbe unused= + + + # Bind the device to igb_uio. + sudo dpdk-devbind -b igb_uio 0000:0a:00.0 + + + # Recheck the status of the devices. + dpdk-devbind --status + Network devices using DPDK-compatible driver + ============================================ + 0000:0a:00.0 '82599ES 10-Gigabit' drv=igb_uio unused= diff --git a/doc/guides/tools/index.rst b/doc/guides/tools/index.rst new file mode 100644 index 00000000..513221ca --- /dev/null +++ b/doc/guides/tools/index.rst @@ -0,0 +1,42 @@ +.. BSD LICENSE + Copyright(c) 2016 Canonical Limited. 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. + +DPDK Tools User Guides +====================== + +.. toctree:: + :maxdepth: 2 + :numbered: + + proc_info + pdump + pmdinfo + devbind + diff --git a/doc/guides/sample_app_ug/pdump.rst b/doc/guides/tools/pdump.rst index ac0e7c96..57097e43 100644 --- a/doc/guides/sample_app_ug/pdump.rst +++ b/doc/guides/tools/pdump.rst @@ -1,4 +1,3 @@ - .. BSD LICENSE Copyright(c) 2016 Intel Corporation. All rights reserved. All rights reserved. @@ -37,6 +36,8 @@ The ``dpdk-pdump`` tool is a Data Plane Development Kit (DPDK) tool that runs as a DPDK secondary process and is capable of enabling packet capture on dpdk ports. .. Note:: + * The ``dpdk-pdump`` tool can only be used in conjunction with a primary + application which has the packet capture framework initialized already. * The ``dpdk-pdump`` tool depends on libpcap based PMD which is disabled by default in the build configuration files, @@ -119,8 +120,8 @@ Can be either a pcap file name or any Linux iface. * To receive ingress and egress packets separately ``rx-dev`` and ``tx-dev`` should both be passed with the different file names or the Linux iface names. - * To receive ingress and egress packets separately ``rx-dev`` and ``tx-dev`` - should both be passed with the same file names or the the Linux iface names. + * To receive ingress and egress packets together, ``rx-dev`` and ``tx-dev`` + should both be passed with the same file name or the same Linux iface name. ``ring-size``: Size of the ring. This value is used internally for ring creation. The ring will be used to enqueue the packets from diff --git a/doc/guides/tools/pmdinfo.rst b/doc/guides/tools/pmdinfo.rst new file mode 100644 index 00000000..efbf527f --- /dev/null +++ b/doc/guides/tools/pmdinfo.rst @@ -0,0 +1,55 @@ +.. BSD LICENSE + Copyright(c) 2016 Canonical Limited. 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. + + +dpdk-pmdinfo Application +======================== + +The ``dpdk-pmdinfo`` tool is a Data Plane Development Kit (DPDK) utility that +can dump a PMDs hardware support info. + + +Running the Application +----------------------- + +The tool has a number of command line options: + +.. code-block:: console + + dpdk-pmdinfo [-hrtp] [-d <pci id file] <elf-file> + + -h, --help Show a short help message and exit + -r, --raw Dump as raw json strings + -d FILE, --pcidb=FILE Specify a pci database to get vendor names from + -t, --table Output information on hw support as a hex table + -p, --plugindir Scan dpdk for autoload plugins + +.. Note:: + + * Parameters inside the square brackets represents optional parameters. diff --git a/doc/guides/sample_app_ug/proc_info.rst b/doc/guides/tools/proc_info.rst index 73f21958..baaf977f 100644 --- a/doc/guides/sample_app_ug/proc_info.rst +++ b/doc/guides/tools/proc_info.rst @@ -1,4 +1,3 @@ - .. BSD LICENSE Copyright(c) 2015 Intel Corporation. All rights reserved. All rights reserved. diff --git a/doc/guides/xen/pkt_switch.rst b/doc/guides/xen/pkt_switch.rst index 00a8f0c1..a45841b9 100644 --- a/doc/guides/xen/pkt_switch.rst +++ b/doc/guides/xen/pkt_switch.rst @@ -409,7 +409,7 @@ Building and Running the Front End .. code-block:: console - ./x86_64-native-linuxapp-gcc/app/testpmd -c f -n 4 --vdev="eth_xenvirt0,mac=00:00:00:00:00:11" + ./x86_64-native-linuxapp-gcc/app/testpmd -c f -n 4 --vdev="net_xenvirt0,mac=00:00:00:00:00:11" testpmd>set fwd mac testpmd>start @@ -417,7 +417,7 @@ Building and Running the Front End .. code-block:: console - --vdev="eth_xenvirt0,mac=00:00:00:00:00:11" --vdev="eth_xenvirt1;mac=00:00:00:00:00:22" + --vdev="net_xenvirt0,mac=00:00:00:00:00:11" --vdev="net_xenvirt1;mac=00:00:00:00:00:22" Usage Examples: Injecting a Packet Stream Using a Packet Generator @@ -430,7 +430,7 @@ Run TestPMD in a guest VM: .. code-block:: console - ./x86_64-native-linuxapp-gcc/app/testpmd -c f -n 4 --vdev="eth_xenvirt0,mac=00:00:00:00:00:11" -- -i --eth-peer=0,00:00:00:00:00:22 + ./x86_64-native-linuxapp-gcc/app/testpmd -c f -n 4 --vdev="net_xenvirt0,mac=00:00:00:00:00:11" -- -i --eth-peer=0,00:00:00:00:00:22 testpmd> set fwd mac testpmd> start @@ -453,13 +453,13 @@ Run TestPMD in guest VM1: .. code-block:: console - ./x86_64-native-linuxapp-gcc/app/testpmd -c f -n 4 --vdev="eth_xenvirt0,mac=00:00:00:00:00:11" -- -i --eth-peer=0,00:00:00:00:00:22 -- -i + ./x86_64-native-linuxapp-gcc/app/testpmd -c f -n 4 --vdev="net_xenvirt0,mac=00:00:00:00:00:11" -- -i --eth-peer=0,00:00:00:00:00:22 -- -i Run TestPMD in guest VM2: .. code-block:: console - ./x86_64-native-linuxapp-gcc/app/testpmd -c f -n 4 --vdev="eth_xenvirt0,mac=00:00:00:00:00:22" -- -i --eth-peer=0,00:00:00:00:00:33 + ./x86_64-native-linuxapp-gcc/app/testpmd -c f -n 4 --vdev="net_xenvirt0,mac=00:00:00:00:00:22" -- -i --eth-peer=0,00:00:00:00:00:33 Configure a packet stream in the packet generator, and set the destination MAC address to 00:00:00:00:00:11 and VLAN to 1000. The packets received in Virtio in guest VM1 will be forwarded to Virtio in guest VM2 and |
