From ca33590b6af032bff57d9cc70455660466a654b2 Mon Sep 17 00:00:00 2001 From: Luca Boccassi Date: Mon, 19 Feb 2018 11:16:57 +0000 Subject: New upstream version 18.02 Change-Id: I89ed24cb2a49b78fe5be6970b99dd46c1499fcc3 Signed-off-by: Luca Boccassi --- doc/guides/prog_guide/bbdev.rst | 585 +++++++++++++++++++++ doc/guides/prog_guide/build_app.rst | 31 +- doc/guides/prog_guide/cryptodev_lib.rst | 40 +- doc/guides/prog_guide/dev_kit_build_system.rst | 31 +- doc/guides/prog_guide/dev_kit_root_make_help.rst | 31 +- doc/guides/prog_guide/efd_lib.rst | 31 +- doc/guides/prog_guide/env_abstraction_layer.rst | 39 +- .../prog_guide/event_ethernet_rx_adapter.rst | 30 +- doc/guides/prog_guide/eventdev.rst | 30 +- doc/guides/prog_guide/ext_app_lib_make_help.rst | 31 +- doc/guides/prog_guide/extend_dpdk.rst | 31 +- doc/guides/prog_guide/flow_classify_lib.rst | 114 ++-- .../prog_guide/generic_receive_offload_lib.rst | 300 ++++++----- .../generic_segmentation_offload_lib.rst | 31 +- doc/guides/prog_guide/glossary.rst | 31 +- doc/guides/prog_guide/hash_lib.rst | 31 +- .../prog_guide/img/architecture-overview.svg | 35 +- doc/guides/prog_guide/img/bond-mode-0.svg | 36 +- doc/guides/prog_guide/img/bond-mode-1.svg | 36 +- doc/guides/prog_guide/img/bond-mode-2.svg | 36 +- doc/guides/prog_guide/img/bond-mode-3.svg | 36 +- doc/guides/prog_guide/img/bond-mode-4.svg | 36 +- doc/guides/prog_guide/img/bond-mode-5.svg | 36 +- doc/guides/prog_guide/img/bond-overview.svg | 36 +- doc/guides/prog_guide/img/gro-key-algorithm.svg | 223 ++++++++ doc/guides/prog_guide/img/linuxapp_launch.svg | 35 +- doc/guides/prog_guide/img/malloc_heap.svg | 35 +- doc/guides/prog_guide/img/mbuf1.svg | 37 +- doc/guides/prog_guide/img/mbuf2.svg | 37 +- doc/guides/prog_guide/img/memory-management.svg | 35 +- doc/guides/prog_guide/img/memory-management2.svg | 35 +- doc/guides/prog_guide/img/mempool.svg | 35 +- doc/guides/prog_guide/img/multi_process_memory.svg | 35 +- doc/guides/prog_guide/img/ring-dequeue1.svg | 35 +- doc/guides/prog_guide/img/ring-dequeue2.svg | 35 +- doc/guides/prog_guide/img/ring-dequeue3.svg | 35 +- doc/guides/prog_guide/img/ring-enqueue1.svg | 35 +- doc/guides/prog_guide/img/ring-enqueue2.svg | 35 +- doc/guides/prog_guide/img/ring-enqueue3.svg | 35 +- doc/guides/prog_guide/img/ring-modulo1.svg | 36 +- doc/guides/prog_guide/img/ring-modulo2.svg | 35 +- doc/guides/prog_guide/img/ring-mp-enqueue1.svg | 35 +- doc/guides/prog_guide/img/ring-mp-enqueue2.svg | 35 +- doc/guides/prog_guide/img/ring-mp-enqueue3.svg | 35 +- doc/guides/prog_guide/img/ring-mp-enqueue4.svg | 35 +- doc/guides/prog_guide/img/ring-mp-enqueue5.svg | 35 +- doc/guides/prog_guide/img/ring1.svg | 35 +- doc/guides/prog_guide/index.rst | 33 +- doc/guides/prog_guide/intro.rst | 31 +- .../prog_guide/ip_fragment_reassembly_lib.rst | 31 +- doc/guides/prog_guide/kernel_nic_interface.rst | 31 +- .../prog_guide/link_bonding_poll_mode_drv_lib.rst | 45 +- doc/guides/prog_guide/lpm6_lib.rst | 31 +- doc/guides/prog_guide/lpm_lib.rst | 31 +- doc/guides/prog_guide/mbuf_lib.rst | 31 +- doc/guides/prog_guide/member_lib.rst | 32 +- doc/guides/prog_guide/mempool_lib.rst | 31 +- doc/guides/prog_guide/metrics_lib.rst | 31 +- doc/guides/prog_guide/multi_proc_support.rst | 35 +- doc/guides/prog_guide/overview.rst | 31 +- .../prog_guide/packet_classif_access_ctrl.rst | 31 +- doc/guides/prog_guide/packet_distrib_lib.rst | 31 +- doc/guides/prog_guide/packet_framework.rst | 31 +- doc/guides/prog_guide/pdump_lib.rst | 31 +- doc/guides/prog_guide/perf_opt_guidelines.rst | 31 +- doc/guides/prog_guide/poll_mode_drv.rst | 49 +- doc/guides/prog_guide/power_man.rst | 39 +- doc/guides/prog_guide/profile_app.rst | 31 +- doc/guides/prog_guide/qos_framework.rst | 35 +- doc/guides/prog_guide/rawdev.rst | 107 ++++ doc/guides/prog_guide/reorder_lib.rst | 31 +- doc/guides/prog_guide/ring_lib.rst | 31 +- doc/guides/prog_guide/rte_flow.rst | 14 +- doc/guides/prog_guide/rte_security.rst | 53 +- doc/guides/prog_guide/service_cores.rst | 33 +- doc/guides/prog_guide/source_org.rst | 31 +- .../prog_guide/thread_safety_dpdk_functions.rst | 31 +- doc/guides/prog_guide/timer_lib.rst | 31 +- doc/guides/prog_guide/traffic_management.rst | 32 +- .../prog_guide/traffic_metering_and_policing.rst | 32 +- doc/guides/prog_guide/vhost_lib.rst | 31 +- doc/guides/prog_guide/writing_efficient_code.rst | 31 +- 82 files changed, 1375 insertions(+), 2548 deletions(-) create mode 100644 doc/guides/prog_guide/bbdev.rst create mode 100644 doc/guides/prog_guide/img/gro-key-algorithm.svg create mode 100644 doc/guides/prog_guide/rawdev.rst (limited to 'doc/guides/prog_guide') diff --git a/doc/guides/prog_guide/bbdev.rst b/doc/guides/prog_guide/bbdev.rst new file mode 100644 index 00000000..d40c7f4c --- /dev/null +++ b/doc/guides/prog_guide/bbdev.rst @@ -0,0 +1,585 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2017 Intel Corporation + +Wireless Baseband Device Library +================================ + +The Wireless Baseband library provides a common programming framework that +abstracts HW accelerators based on FPGA and/or Fixed Function Accelerators that +assist with 3gpp Physical Layer processing. Furthermore, it decouples the +application from the compute-intensive wireless functions by abstracting their +optimized libraries to appear as virtual bbdev devices. + +The functional scope of the BBDEV library are those functions in relation to +the 3gpp Layer 1 signal processing (channel coding, modulation, ...). + +The framework currently only supports Turbo Code FEC function. + + +Design Principles +----------------- + +The Wireless Baseband library follows the same ideology of DPDK's Ethernet +Device and Crypto Device frameworks. Wireless Baseband provides a generic +acceleration abstraction framework which supports both physical (hardware) and +virtual (software) wireless acceleration functions. + +Device Management +----------------- + +Device Creation +~~~~~~~~~~~~~~~ + +Physical bbdev devices are discovered during the PCI probe/enumeration of the +EAL function which is executed at DPDK initialization, based on +their PCI device identifier, each unique PCI BDF (bus/bridge, device, +function). + +Virtual devices can be created by two mechanisms, either using the EAL command +line options or from within the application using an EAL API directly. + +From the command line using the --vdev EAL option + +.. code-block:: console + + --vdev 'turbo_sw,max_nb_queues=8,socket_id=0' + +Our using the rte_vdev_init API within the application code. + +.. code-block:: c + + rte_vdev_init("turbo_sw", "max_nb_queues=2,socket_id=0") + +All virtual bbdev devices support the following initialization parameters: + +- ``max_nb_queues`` - maximum number of queues supported by the device. + +- ``socket_id`` - socket on which to allocate the device resources on. + + +Device Identification +~~~~~~~~~~~~~~~~~~~~~ + +Each device, whether virtual or physical is uniquely designated by two +identifiers: + +- A unique device index used to designate the bbdev device in all functions + exported by the bbdev API. + +- A device name used to designate the bbdev device in console messages, for + administration or debugging purposes. For ease of use, the port name includes + the port index. + + +Device Configuration +~~~~~~~~~~~~~~~~~~~~ + +From the application point of view, each instance of a bbdev device consists of +one or more queues identified by queue IDs. While different devices may have +different capabilities (e.g. support different operation types), all queues on +a device support identical configuration possibilities. A queue is configured +for only one type of operation and is configured at initializations time. +When an operation is enqueued to a specific queue ID, the result is dequeued +from the same queue ID. + +Configuration of a device has two different levels: configuration that applies +to the whole device, and configuration that applies to a single queue. + +Device configuration is applied with +``rte_bbdev_setup_queues(dev_id,num_queues,socket_id)`` +and queue configuration is applied with +``rte_bbdev_queue_configure(dev_id,queue_id,conf)``. Note that, although all +queues on a device support same capabilities, they can be configured differently +and will then behave differently. +Devices supporting interrupts can enable them by using +``rte_bbdev_intr_enable(dev_id)``. + +The configuration of each bbdev device includes the following operations: + +- Allocation of resources, including hardware resources if a physical device. +- Resetting the device into a well-known default state. +- Initialization of statistics counters. + +The ``rte_bbdev_setup_queues`` API is used to setup queues for a bbdev device. + +.. code-block:: c + + int rte_bbdev_setup_queues(uint16_t dev_id, uint16_t num_queues, + int socket_id); + +- ``num_queues`` argument identifies the total number of queues to setup for + this device. + +- ``socket_id`` specifies which socket will be used to allocate the memory. + + +The ``rte_bbdev_intr_enable`` API is used to enable interrupts for a bbdev +device, if supported by the driver. Should be called before starting the device. + +.. code-block:: c + + int rte_bbdev_intr_enable(uint16_t dev_id); + + +Queues Configuration +~~~~~~~~~~~~~~~~~~~~ + +Each bbdev devices queue is individually configured through the +``rte_bbdev_queue_configure()`` API. +Each queue resources may be allocated on a specified socket. + +.. code-block:: c + + struct rte_bbdev_queue_conf { + int socket; + uint32_t queue_size; + uint8_t priority; + bool deferred_start; + enum rte_bbdev_op_type op_type; + }; + +Device & Queues Management +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +After initialization, devices are in a stopped state, so must be started by the +application. If an application is finished using a device it can close the +device. Once closed, it cannot be restarted. + +.. code-block:: c + + int rte_bbdev_start(uint16_t dev_id) + int rte_bbdev_stop(uint16_t dev_id) + int rte_bbdev_close(uint16_t dev_id) + int rte_bbdev_queue_start(uint16_t dev_id, uint16_t queue_id) + int rte_bbdev_queue_stop(uint16_t dev_id, uint16_t queue_id) + + +By default, all queues are started when the device is started, but they can be +stopped individually. + +.. code-block:: c + + int rte_bbdev_queue_start(uint16_t dev_id, uint16_t queue_id) + int rte_bbdev_queue_stop(uint16_t dev_id, uint16_t queue_id) + + +Logical Cores, Memory and Queues Relationships +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The bbdev device Library as the Poll Mode Driver library support NUMA for when +a processor’s logical cores and interfaces utilize its local memory. Therefore +baseband operations, the mbuf being operated on should be allocated from memory +pools created in the local memory. The buffers should, if possible, remain on +the local processor to obtain the best performance results and buffer +descriptors should be populated with mbufs allocated from a mempool allocated +from local memory. + +The run-to-completion model also performs better, especially in the case of +virtual bbdev devices, if the baseband operation and data buffers are in local +memory instead of a remote processor's memory. This is also true for the +pipe-line model provided all logical cores used are located on the same processor. + +Multiple logical cores should never share the same queue for enqueuing +operations or dequeuing operations on the same bbdev device since this would +require global locks and hinder performance. It is however possible to use a +different logical core to dequeue an operation on a queue pair from the logical +core which it was enqueued on. This means that a baseband burst enqueue/dequeue +APIs are a logical place to transition from one logical core to another in a +packet processing pipeline. + + +Device Operation Capabilities +----------------------------- + +Capabilities (in terms of operations supported, max number of queues, etc.) +identify what a bbdev is capable of performing that differs from one device to +another. For the full scope of the bbdev capability see the definition of the +structure in the *DPDK API Reference*. + +.. code-block:: c + + struct rte_bbdev_op_cap; + +A device reports its capabilities when registering itself in the bbdev framework. +With the aid of this capabilities mechanism, an application can query devices to +discover which operations within the 3gpp physical layer they are capable of +performing. Below is an example of the capabilities for a PMD it supports in +relation to Turbo Encoding and Decoding operations. + +.. code-block:: c + + static const struct rte_bbdev_op_cap bbdev_capabilities[] = { + { + .type = RTE_BBDEV_OP_TURBO_DEC, + .cap.turbo_dec = { + .capability_flags = + RTE_BBDEV_TURBO_SUBBLOCK_DEINTERLEAVE | + RTE_BBDEV_TURBO_POS_LLR_1_BIT_IN | + RTE_BBDEV_TURBO_NEG_LLR_1_BIT_IN | + RTE_BBDEV_TURBO_CRC_TYPE_24B, + .num_buffers_src = RTE_BBDEV_MAX_CODE_BLOCKS, + .num_buffers_hard_out = + RTE_BBDEV_MAX_CODE_BLOCKS, + .num_buffers_soft_out = 0, + } + }, + { + .type = RTE_BBDEV_OP_TURBO_ENC, + .cap.turbo_enc = { + .capability_flags = + RTE_BBDEV_TURBO_CRC_24B_ATTACH | + RTE_BBDEV_TURBO_RATE_MATCH | + RTE_BBDEV_TURBO_RV_INDEX_BYPASS, + .num_buffers_src = RTE_BBDEV_MAX_CODE_BLOCKS, + .num_buffers_dst = RTE_BBDEV_MAX_CODE_BLOCKS, + } + }, + RTE_BBDEV_END_OF_CAPABILITIES_LIST() + }; + +Capabilities Discovery +~~~~~~~~~~~~~~~~~~~~~~ + +Discovering the features and capabilities of a bbdev device poll mode driver +is achieved through the ``rte_bbdev_info_get()`` function. + +.. code-block:: c + + int rte_bbdev_info_get(uint16_t dev_id, struct rte_bbdev_info *dev_info) + +This allows the user to query a specific bbdev PMD and get all the device +capabilities. The ``rte_bbdev_info`` structure provides two levels of +information: + +- Device relevant information, like: name and related rte_bus. + +- Driver specific information, as defined by the ``struct rte_bbdev_driver_info`` + structure, this is where capabilities reside along with other specifics like: + maximum queue sizes and priority level. + +.. code-block:: c + + struct rte_bbdev_info { + int socket_id; + const char *dev_name; + const struct rte_bus *bus; + uint16_t num_queues; + bool started; + struct rte_bbdev_driver_info drv; + }; + +Operation Processing +-------------------- + +Scheduling of baseband operations on DPDK's application data path is +performed using a burst oriented asynchronous API set. A queue on a bbdev +device accepts a burst of baseband operations using enqueue burst API. On physical +bbdev devices the enqueue burst API will place the operations to be processed +on the device's hardware input queue, for virtual devices the processing of the +baseband operations is usually completed during the enqueue call to the bbdev +device. The dequeue burst API will retrieve any processed operations available +from the queue on the bbdev device, from physical devices this is usually +directly from the device's processed queue, and for virtual device's from a +``rte_ring`` where processed operations are place after being processed on the +enqueue call. + + +Enqueue / Dequeue Burst APIs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The burst enqueue API uses a bbdev device identifier and a queue +identifier to specify the bbdev device queue to schedule the processing on. +The ``num_ops`` parameter is the number of operations to process which are +supplied in the ``ops`` array of ``rte_bbdev_*_op`` structures. +The enqueue function returns the number of operations it actually enqueued for +processing, a return value equal to ``num_ops`` means that all packets have been +enqueued. + +.. code-block:: c + + uint16_t rte_bbdev_enqueue_enc_ops(uint16_t dev_id, uint16_t queue_id, + struct rte_bbdev_enc_op **ops, uint16_t num_ops) + + uint16_t rte_bbdev_enqueue_dec_ops(uint16_t dev_id, uint16_t queue_id, + struct rte_bbdev_dec_op **ops, uint16_t num_ops) + +The dequeue API uses the same format as the enqueue API of processed but +the ``num_ops`` and ``ops`` parameters are now used to specify the max processed +operations the user wishes to retrieve and the location in which to store them. +The API call returns the actual number of processed operations returned, this +can never be larger than ``num_ops``. + +.. code-block:: c + + uint16_t rte_bbdev_dequeue_enc_ops(uint16_t dev_id, uint16_t queue_id, + struct rte_bbdev_enc_op **ops, uint16_t num_ops) + + uint16_t rte_bbdev_dequeue_dec_ops(uint16_t dev_id, uint16_t queue_id, + struct rte_bbdev_dec_op **ops, uint16_t num_ops) + +Operation Representation +~~~~~~~~~~~~~~~~~~~~~~~~ + +An encode bbdev operation is represented by ``rte_bbdev_enc_op`` structure, +and by ``rte_bbdev_dec_op`` for decode. These structures act as metadata +containers for all necessary information required for the bbdev operation to be +processed on a particular bbdev device poll mode driver. + +.. code-block:: c + + struct rte_bbdev_enc_op { + int status; + struct rte_mempool *mempool; + void *opaque_data; + struct rte_bbdev_op_turbo_enc turbo_enc; + }; + + struct rte_bbdev_dec_op { + int status; + struct rte_mempool *mempool; + void *opaque_data; + struct rte_bbdev_op_turbo_dec turbo_dec; + }; + +The operation structure by itself defines the operation type. It includes an +operation status, a reference to the operation specific data, which can vary in +size and content depending on the operation being provisioned. It also contains +the source mempool for the operation, if it is allocated from a mempool. + +If bbdev operations are allocated from a bbdev operation mempool, see next +section, there is also the ability to allocate private memory with the +operation for applications purposes. + +Application software is responsible for specifying all the operation specific +fields in the ``rte_bbdev_*_op`` structure which are then used by the bbdev PMD +to process the requested operation. + + +Operation Management and Allocation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The bbdev library provides an API set for managing bbdev operations which +utilize the Mempool Library to allocate operation buffers. Therefore, it ensures +that the bbdev operation is interleaved optimally across the channels and +ranks for optimal processing. + +.. code-block:: c + + struct rte_mempool * + rte_bbdev_op_pool_create(const char *name, enum rte_bbdev_op_type type, + unsigned int num_elements, unsigned int cache_size, + int socket_id) + +``rte_bbdev_*_op_alloc_bulk()`` and ``rte_bbdev_*_op_free_bulk()`` are used to +allocate bbdev operations of a specific type from a given bbdev operation mempool. + +.. code-block:: c + + int rte_bbdev_enc_op_alloc_bulk(struct rte_mempool *mempool, + struct rte_bbdev_enc_op **ops, uint16_t num_ops) + + int rte_bbdev_dec_op_alloc_bulk(struct rte_mempool *mempool, + struct rte_bbdev_dec_op **ops, uint16_t num_ops) + +``rte_bbdev_*_op_free_bulk()`` is called by the application to return an +operation to its allocating pool. + +.. code-block:: c + + void rte_bbdev_dec_op_free_bulk(struct rte_bbdev_dec_op **ops, + unsigned int num_ops) + void rte_bbdev_enc_op_free_bulk(struct rte_bbdev_enc_op **ops, + unsigned int num_ops) + +BBDEV Operations +~~~~~~~~~~~~~~~~ + +The bbdev operation structure contains all the mutable data relating to +performing Turbo code processing on a referenced mbuf data buffer. It is used +for either encode or decode operations. + +Turbo Encode operation accepts one input and one output. + +Turbo Decode operation accepts one input and two outputs, called *hard-decision* +and *soft-decision* outputs. *Soft-decision* output is optional. + +It is expected that the application provides input and output ``mbuf`` pointers +allocated and ready to use. The baseband framework supports turbo coding on +Code Blocks (CB) and Transport Blocks (TB). + +For the output buffer(s), the application needs only to provide an allocated and +free mbuf (containing only one mbuf segment), so that bbdev can write the +operation outcome. + +**Turbo Encode Op structure** + +.. code-block:: c + + struct rte_bbdev_op_turbo_enc { + struct rte_bbdev_op_data input; + struct rte_bbdev_op_data output; + + uint32_t op_flags; + uint8_t rv_index; + uint8_t code_block_mode; + union { + struct rte_bbdev_op_enc_cb_params cb_params; + struct rte_bbdev_op_enc_tb_params tb_params; + }; + }; + + +**Turbo Decode Op structure** + +.. code-block:: c + + struct rte_bbdev_op_turbo_dec { + struct rte_bbdev_op_data input; + struct rte_bbdev_op_data hard_output; + struct rte_bbdev_op_data soft_output; + + uint32_t op_flags; + uint8_t rv_index; + uint8_t iter_min:4; + uint8_t iter_max:4; + uint8_t iter_count; + uint8_t ext_scale; + uint8_t num_maps; + uint8_t code_block_mode; + union { + struct rte_bbdev_op_dec_cb_params cb_params; + struct rte_bbdev_op_dec_tb_params tb_params; + }; + }; + +Input and output data buffers are identified by ``rte_bbdev_op_data`` structure. +This structure has three elements: + +- ``data`` - This is the mbuf reference + +- ``offset`` - The starting point for the Turbo input/output, in bytes, from the + start of the data in the data buffer. It must be smaller than data_len of the + mbuf's first segment + +- ``length`` - The length, in bytes, of the buffer on which the Turbo operation + will or has been computed. For the input, the length is set by the application. + For the output(s), the length is computed by the bbdev PMD driver. + +Sample code +----------- + +The baseband device sample application gives an introduction on how to use the +bbdev framework, by giving a sample code performing a loop-back operation with a +baseband processor capable of transceiving data packets. + +The following sample C-like pseudo-code shows the basic steps to encode several +buffers using (**sw_trubo**) bbdev PMD. + +.. code-block:: c + + /* EAL Init */ + ret = rte_eal_init(argc, argv); + if (ret < 0) + rte_exit(EXIT_FAILURE, "Invalid EAL arguments\n"); + + /* Get number of available bbdev devices */ + nb_bbdevs = rte_bbdev_count(); + if (nb_bbdevs == 0) + rte_exit(EXIT_FAILURE, "No bbdevs detected!\n"); + + /* Create bbdev op pools */ + bbdev_op_pool[RTE_BBDEV_OP_TURBO_ENC] = + rte_bbdev_op_pool_create("bbdev_op_pool_enc", + RTE_BBDEV_OP_TURBO_ENC, NB_MBUF, 128, rte_socket_id()); + + /* Get information for this device */ + rte_bbdev_info_get(dev_id, &info); + + /* Setup BBDEV device queues */ + ret = rte_bbdev_setup_queues(dev_id, qs_nb, info.socket_id); + if (ret < 0) + rte_exit(EXIT_FAILURE, + "ERROR(%d): BBDEV %u not configured properly\n", + ret, dev_id); + + /* setup device queues */ + qconf.socket = info.socket_id; + qconf.queue_size = info.drv.queue_size_lim; + qconf.op_type = RTE_BBDEV_OP_TURBO_ENC; + + for (q_id = 0; q_id < qs_nb; q_id++) { + /* Configure all queues belonging to this bbdev device */ + ret = rte_bbdev_queue_configure(dev_id, q_id, &qconf); + if (ret < 0) + rte_exit(EXIT_FAILURE, + "ERROR(%d): BBDEV %u queue %u not configured properly\n", + ret, dev_id, q_id); + } + + /* Start bbdev device */ + ret = rte_bbdev_start(dev_id); + + /* Create the mbuf mempool for pkts */ + mbuf_pool = rte_pktmbuf_pool_create("bbdev_mbuf_pool", + NB_MBUF, MEMPOOL_CACHE_SIZE, 0, + RTE_MBUF_DEFAULT_BUF_SIZE, rte_socket_id()); + if (mbuf_pool == NULL) + rte_exit(EXIT_FAILURE, + "Unable to create '%s' pool\n", pool_name); + + while (!global_exit_flag) { + + /* Allocate burst of op structures in preparation for enqueue */ + if (rte_bbdev_enc_op_alloc_bulk(bbdev_op_pool[RTE_BBDEV_OP_TURBO_ENC], + ops_burst, op_num) != 0) + continue; + + /* Allocate input mbuf pkts */ + ret = rte_pktmbuf_alloc_bulk(mbuf_pool, input_pkts_burst, MAX_PKT_BURST); + if (ret < 0) + continue; + + /* Allocate output mbuf pkts */ + ret = rte_pktmbuf_alloc_bulk(mbuf_pool, output_pkts_burst, MAX_PKT_BURST); + if (ret < 0) + continue; + + for (j = 0; j < op_num; j++) { + /* Append the size of the ethernet header */ + rte_pktmbuf_append(input_pkts_burst[j], + sizeof(struct ether_hdr)); + + /* set op */ + + ops_burst[j]->turbo_enc.input.offset = + sizeof(struct ether_hdr); + + ops_burst[j]->turbo_enc->input.length = + rte_pktmbuf_pkt_len(bbdev_pkts[j]); + + ops_burst[j]->turbo_enc->input.data = + input_pkts_burst[j]; + + ops_burst[j]->turbo_enc->output.offset = + sizeof(struct ether_hdr); + + ops_burst[j]->turbo_enc->output.data = + output_pkts_burst[j]; + } + + /* Enqueue packets on BBDEV device */ + op_num = rte_bbdev_enqueue_enc_ops(qconf->bbdev_id, + qconf->bbdev_qs[q], ops_burst, + MAX_PKT_BURST); + + /* Dequeue packets from BBDEV device*/ + op_num = rte_bbdev_dequeue_enc_ops(qconf->bbdev_id, + qconf->bbdev_qs[q], ops_burst, + MAX_PKT_BURST); + } + + +BBDEV Device API +~~~~~~~~~~~~~~~~ + +The bbdev Library API is described in the *DPDK API Reference* document. diff --git a/doc/guides/prog_guide/build_app.rst b/doc/guides/prog_guide/build_app.rst index 138330ad..fa6aa8a2 100644 --- a/doc/guides/prog_guide/build_app.rst +++ b/doc/guides/prog_guide/build_app.rst @@ -1,32 +1,5 @@ -.. 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. +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2010-2014 Intel Corporation. .. _Building_Your_Own_Application: diff --git a/doc/guides/prog_guide/cryptodev_lib.rst b/doc/guides/prog_guide/cryptodev_lib.rst index 2b338b92..066fe2d2 100644 --- a/doc/guides/prog_guide/cryptodev_lib.rst +++ b/doc/guides/prog_guide/cryptodev_lib.rst @@ -1,32 +1,5 @@ -.. BSD LICENSE - Copyright(c) 2016-2017 Intel Corporation. All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in - the documentation and/or other materials provided with the - distribution. - * Neither the name of Intel Corporation nor the names of its - contributors may be used to endorse or promote products derived - from this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS - "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT - OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, - DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY - THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE - OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2016-2017 Intel Corporation. Cryptography Device Library =========================== @@ -70,6 +43,15 @@ From the command line using the --vdev EAL option --vdev 'crypto_aesni_mb0,max_nb_queue_pairs=2,max_nb_sessions=1024,socket_id=0' +.. Note:: + + * If DPDK application requires multiple software crypto PMD devices then required + number of ``--vdev`` with appropriate libraries are to be added. + + * An Application with crypto PMD instaces sharing the same library requires unique ID. + + Example: ``--vdev 'crypto_aesni_mb0' --vdev 'crypto_aesni_mb1'`` + Our using the rte_vdev_init API within the application code. .. code-block:: c diff --git a/doc/guides/prog_guide/dev_kit_build_system.rst b/doc/guides/prog_guide/dev_kit_build_system.rst index ad032c5f..da83a31e 100644 --- a/doc/guides/prog_guide/dev_kit_build_system.rst +++ b/doc/guides/prog_guide/dev_kit_build_system.rst @@ -1,32 +1,5 @@ -.. 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. +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2010-2014 Intel Corporation. .. _Development_Kit_Build_System: diff --git a/doc/guides/prog_guide/dev_kit_root_make_help.rst b/doc/guides/prog_guide/dev_kit_root_make_help.rst index d7c41064..633161f0 100644 --- a/doc/guides/prog_guide/dev_kit_root_make_help.rst +++ b/doc/guides/prog_guide/dev_kit_root_make_help.rst @@ -1,32 +1,5 @@ -.. 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. +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2010-2014 Intel Corporation. .. _Development_Kit_Root_Makefile_Help: diff --git a/doc/guides/prog_guide/efd_lib.rst b/doc/guides/prog_guide/efd_lib.rst index 3f90fa9a..cb1a1df8 100644 --- a/doc/guides/prog_guide/efd_lib.rst +++ b/doc/guides/prog_guide/efd_lib.rst @@ -1,32 +1,5 @@ -.. BSD LICENSE - Copyright(c) 2016-2017 Intel Corporation. All rights reserved. - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in - the documentation and/or other materials provided with the - distribution. - * Neither the name of Intel Corporation nor the names of its - contributors may be used to endorse or promote products derived - from this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS - "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT - OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, - DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY - THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE - OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2016-2017 Intel Corporation. .. _Efd_Library: diff --git a/doc/guides/prog_guide/env_abstraction_layer.rst b/doc/guides/prog_guide/env_abstraction_layer.rst index 34d871c9..9a2fab1e 100644 --- a/doc/guides/prog_guide/env_abstraction_layer.rst +++ b/doc/guides/prog_guide/env_abstraction_layer.rst @@ -1,32 +1,5 @@ -.. 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. +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2010-2014 Intel Corporation. .. _Environment_Abstraction_Layer: @@ -99,6 +72,14 @@ It consist of calls to the pthread library (more specifically, pthread_self(), p The creation and initialization functions for these objects are not multi-thread safe. However, once initialized, the objects themselves can safely be used in multiple threads simultaneously. +Shutdown and Cleanup +~~~~~~~~~~~~~~~~~~~~ + +During the initialization of EAL resources such as hugepage backed memory can be +allocated by core components. The memory allocated during ``rte_eal_init()`` +can be released by calling the ``rte_eal_cleanup()`` function. Refer to the +API documentation for details. + Multi-process Support ~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/guides/prog_guide/event_ethernet_rx_adapter.rst b/doc/guides/prog_guide/event_ethernet_rx_adapter.rst index 4e722219..4ab87a37 100644 --- a/doc/guides/prog_guide/event_ethernet_rx_adapter.rst +++ b/doc/guides/prog_guide/event_ethernet_rx_adapter.rst @@ -1,31 +1,5 @@ -.. BSD LICENSE - Copyright(c) 2017 Intel Corporation. All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in - the documentation and/or other materials provided with the - distribution. - * Neither the name of Intel Corporation nor the names of its - contributors may be used to endorse or promote products derived - from this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS - "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT - OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, - DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY - THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE - OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2017 Intel Corporation. Event Ethernet Rx Adapter Library ================================= diff --git a/doc/guides/prog_guide/eventdev.rst b/doc/guides/prog_guide/eventdev.rst index be9fccdd..ce19997d 100644 --- a/doc/guides/prog_guide/eventdev.rst +++ b/doc/guides/prog_guide/eventdev.rst @@ -1,31 +1,5 @@ -.. BSD LICENSE - Copyright(c) 2017 Intel Corporation. All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in - the documentation and/or other materials provided with the - distribution. - * Neither the name of Intel Corporation nor the names of its - contributors may be used to endorse or promote products derived - from this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS - "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT - OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, - DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY - THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE - OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2017 Intel Corporation. Event Device Library ==================== diff --git a/doc/guides/prog_guide/ext_app_lib_make_help.rst b/doc/guides/prog_guide/ext_app_lib_make_help.rst index c69e62cf..7e8e9fd3 100644 --- a/doc/guides/prog_guide/ext_app_lib_make_help.rst +++ b/doc/guides/prog_guide/ext_app_lib_make_help.rst @@ -1,32 +1,5 @@ -.. 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. +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2010-2014 Intel Corporation. .. _External_Application/Library_Makefile_help: diff --git a/doc/guides/prog_guide/extend_dpdk.rst b/doc/guides/prog_guide/extend_dpdk.rst index 73d81999..725994ee 100644 --- a/doc/guides/prog_guide/extend_dpdk.rst +++ b/doc/guides/prog_guide/extend_dpdk.rst @@ -1,32 +1,5 @@ -.. 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. +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2010-2014 Intel Corporation. Extending the DPDK ========================= diff --git a/doc/guides/prog_guide/flow_classify_lib.rst b/doc/guides/prog_guide/flow_classify_lib.rst index 820dc72a..f0ed5a1a 100644 --- a/doc/guides/prog_guide/flow_classify_lib.rst +++ b/doc/guides/prog_guide/flow_classify_lib.rst @@ -1,32 +1,5 @@ -.. BSD LICENSE - Copyright(c) 2017 Intel Corporation. All rights reserved. - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in - the documentation and/or other materials provided with the - distribution. - * Neither the name of Intel Corporation nor the names of its - contributors may be used to endorse or promote products derived - from this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS - "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT - OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, - DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY - THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE - OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2017 Intel Corporation. Flow Classification Library =========================== @@ -101,30 +74,50 @@ The library has the following API's * Handle to flow classifier instance * @param params * Parameters for flow_classify table creation - * @param table_id - * Table ID. Valid only within the scope of table IDs of the current - * classifier. Only returned after a successful invocation. * @return * 0 on success, error code otherwise */ int rte_flow_classify_table_create(struct rte_flow_classifier *cls, - struct rte_flow_classify_table_params *params, - uint32_t *table_id); + struct rte_flow_classify_table_params *params); + + /** + * Validate the flow classify rule + * + * @param[in] cls + * Handle to flow classifier instance + * @param[in] attr + * Flow rule attributes + * @param[in] pattern + * Pattern specification (list terminated by the END pattern item). + * @param[in] actions + * Associated actions (list terminated by the END pattern item). + * @param[out] error + * Perform verbose error reporting if not NULL. Structure + * initialised in case of error only. + * @return + * 0 on success, error code otherwise + */ + int + rte_flow_classify_validate(struct rte_flow_classifier *cls, + const struct rte_flow_attr *attr, + const struct rte_flow_item pattern[], + const struct rte_flow_action actions[], + struct rte_flow_error *error); /** * Add a flow classify rule to the flow_classifier table. * * @param[in] cls * Flow classifier handle - * @param[in] table_id - * id of table * @param[in] attr * Flow rule attributes * @param[in] pattern * Pattern specification (list terminated by the END pattern item). * @param[in] actions * Associated actions (list terminated by the END pattern item). + * @param[out] key_found + * returns 1 if rule present already, 0 otherwise. * @param[out] error * Perform verbose error reporting if not NULL. Structure * initialised in case of error only. @@ -133,10 +126,10 @@ The library has the following API's */ struct rte_flow_classify_rule * rte_flow_classify_table_entry_add(struct rte_flow_classifier *cls, - uint32_t table_id, const struct rte_flow_attr *attr, const struct rte_flow_item pattern[], const struct rte_flow_action actions[], + int *key_found; struct rte_flow_error *error); /** @@ -144,8 +137,6 @@ The library has the following API's * * @param[in] cls * Flow classifier handle - * @param[in] table_id - * id of table * @param[in] rule * Flow classify rule * @return @@ -153,7 +144,6 @@ The library has the following API's */ int rte_flow_classify_table_entry_delete(struct rte_flow_classifier *cls, - uint32_t table_id, struct rte_flow_classify_rule *rule); /** @@ -161,8 +151,6 @@ The library has the following API's * * @param[in] cls * Flow classifier handle - * @param[in] table_id - * id of table * @param[in] pkts * Pointer to packets to process * @param[in] nb_pkts @@ -177,7 +165,6 @@ The library has the following API's */ int rte_flow_classifier_query(struct rte_flow_classifier *cls, - uint32_t table_id, struct rte_mbuf **pkts, const uint16_t nb_pkts, struct rte_flow_classify_rule *rule, @@ -200,16 +187,13 @@ application before calling the API. /** CPU socket ID where memory for the flow classifier and its */ /** elements (tables) should be allocated */ int socket_id; - - /** Table type */ - enum rte_flow_classify_table_type type; }; The ``Classifier`` has the following internal structures: .. code-block:: c - struct rte_table { + struct rte_cls_table { /* Input parameters */ struct rte_table_ops ops; uint32_t entry_size; @@ -225,11 +209,16 @@ The ``Classifier`` has the following internal structures: /* Input parameters */ char name[RTE_FLOW_CLASSIFIER_MAX_NAME_SZ]; int socket_id; - enum rte_flow_classify_table_type type; - /* Internal tables */ - struct rte_table tables[RTE_FLOW_CLASSIFY_TABLE_MAX]; + /* Internal */ + /* ntuple_filter */ + struct rte_eth_ntuple_filter ntuple_filter; + + /* classifier tables */ + struct rte_cls_table tables[RTE_FLOW_CLASSIFY_TABLE_MAX]; + uint32_t table_mask; uint32_t num_tables; + uint16_t nb_pkts; struct rte_flow_classify_table_entry *entries[RTE_PORT_IN_BURST_SIZE_MAX]; @@ -252,9 +241,8 @@ application before calling the API. /** Opaque param to be passed to the table create operation */ void *arg_create; - /** Memory size to be reserved per classifier object entry for */ - /** storing meta data */ - uint32_t table_metadata_size; + /** Classifier table type */ + enum rte_flow_classify_table_type type; }; To create an ACL table the ``rte_table_acl_params`` structure must be @@ -314,14 +302,14 @@ and SCTP. RTE_FLOW_ITEM_TYPE_END, }; -The internal function ``flow_classify_parse_flow`` parses the +The API function ``rte_flow_classify_validate`` parses the IPv4 5-tuple pattern, attributes and actions and returns the 5-tuple data in the ``rte_eth_ntuple_filter`` structure. .. code-block:: c static int - flow_classify_parse_flow( + rte_flow_classify_validate(struct rte_flow_classifier *cls, const struct rte_flow_attr *attr, const struct rte_flow_item pattern[], const struct rte_flow_action actions[], @@ -333,7 +321,7 @@ Adding Flow Rules The ``rte_flow_classify_table_entry_add`` API creates an ``rte_flow_classify`` object which contains the flow_classify id and type, the action, a union of add and delete keys and a union of rules. -It uses the ``flow_classify_parse_flow`` internal function for parsing the +It uses the ``rte_flow_classify_validate`` API function for parsing the flow parameters. The 5-tuple ACL key data is obtained from the ``rte_eth_ntuple_filter`` structure populated by the ``classify_parse_ntuple_filter`` function which @@ -343,7 +331,7 @@ parses the Flow rule. struct acl_keys { struct rte_table_acl_rule_add_params key_add; /* add key */ - struct rte_table_acl_rule_delete_params key_del; /* delete key */ + struct rte_table_acl_rule_delete_params key_del; /* delete key */ }; struct classify_rules { @@ -355,24 +343,24 @@ parses the Flow rule. struct rte_flow_classify { uint32_t id; /* unique ID of classify object */ - struct rte_flow_action action; /* action when match found */ - struct classify_rules rules; /* union of rules */ + enum rte_flow_classify_table_type tbl_type; /* rule table */ + struct classify_rules rules; /* union of rules */ union { struct acl_keys key; } u; int key_found; /* rule key found in table */ - void *entry; /* pointer to buffer to hold rule meta data */ + struct rte_flow_classify_table_entry entry; /* rule meta data */ void *entry_ptr; /* handle to the table entry for rule meta data */ }; -It then calls the ``table[table_id].ops.f_add`` API to add the rule to the ACL +It then calls the ``table.ops.f_add`` API to add the rule to the ACL table. Deleting Flow Rules ~~~~~~~~~~~~~~~~~~~ The ``rte_flow_classify_table_entry_delete`` API calls the -``table[table_id].ops.f_delete`` API to delete a rule from the ACL table. +``table.ops.f_delete`` API to delete a rule from the ACL table. Packet Matching ~~~~~~~~~~~~~~~ @@ -380,7 +368,7 @@ Packet Matching The ``rte_flow_classifier_query`` API is used to find packets which match a given flow Flow rule in the table. This API calls the flow_classify_run internal function which calls the -``table[table_id].ops.f_lookup`` API to see if any packets in a burst match any +``table.ops.f_lookup`` API to see if any packets in a burst match any of the Flow rules in the table. The meta data for the highest priority rule matched for each packet is returned in the entries array in the ``rte_flow_classify`` object. diff --git a/doc/guides/prog_guide/generic_receive_offload_lib.rst b/doc/guides/prog_guide/generic_receive_offload_lib.rst index 22e50ecb..9c6a4d08 100644 --- a/doc/guides/prog_guide/generic_receive_offload_lib.rst +++ b/doc/guides/prog_guide/generic_receive_offload_lib.rst @@ -1,159 +1,193 @@ -.. BSD LICENSE - Copyright(c) 2017 Intel Corporation. All rights reserved. - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in - the documentation and/or other materials provided with the - distribution. - * Neither the name of Intel Corporation nor the names of its - contributors may be used to endorse or promote products derived - from this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS - "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT - OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, - DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY - THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE - OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2017 Intel Corporation. Generic Receive Offload Library =============================== Generic Receive Offload (GRO) is a widely used SW-based offloading -technique to reduce per-packet processing overhead. It gains performance -by reassembling small packets into large ones. To enable more flexibility -to applications, DPDK implements GRO as a standalone library. Applications -explicitly use the GRO library to merge small packets into large ones. - -The GRO library assumes all input packets have correct checksums. In -addition, the GRO library doesn't re-calculate checksums for merged -packets. If input packets are IP fragmented, the GRO library assumes -they are complete packets (i.e. with L4 headers). - -Currently, the GRO library implements TCP/IPv4 packet reassembly. - -Reassembly Modes ----------------- - -The GRO library provides two reassembly modes: lightweight and -heavyweight mode. If applications want to merge packets in a simple way, -they can use the lightweight mode API. If applications want more -fine-grained controls, they can choose the heavyweight mode API. - -Lightweight Mode -~~~~~~~~~~~~~~~~ - -The ``rte_gro_reassemble_burst()`` function is used for reassembly in -lightweight mode. It tries to merge N input packets at a time, where -N should be less than or equal to ``RTE_GRO_MAX_BURST_ITEM_NUM``. - -In each invocation, ``rte_gro_reassemble_burst()`` allocates temporary -reassembly tables for the desired GRO types. Note that the reassembly -table is a table structure used to reassemble packets and different GRO -types (e.g. TCP/IPv4 GRO and TCP/IPv6 GRO) have different reassembly table -structures. The ``rte_gro_reassemble_burst()`` function uses the reassembly -tables to merge the N input packets. - -For applications, performing GRO in lightweight mode is simple. They -just need to invoke ``rte_gro_reassemble_burst()``. Applications can get -GROed packets as soon as ``rte_gro_reassemble_burst()`` returns. - -Heavyweight Mode -~~~~~~~~~~~~~~~~ - -The ``rte_gro_reassemble()`` function is used for reassembly in heavyweight -mode. Compared with the lightweight mode, performing GRO in heavyweight mode -is relatively complicated. - -Before performing GRO, applications need to create a GRO context object -by calling ``rte_gro_ctx_create()``. A GRO context object holds the -reassembly tables of desired GRO types. Note that all update/lookup -operations on the context object are not thread safe. So if different -processes or threads want to access the same context object simultaneously, -some external syncing mechanisms must be used. - -Once the GRO context is created, applications can then use the -``rte_gro_reassemble()`` function to merge packets. In each invocation, -``rte_gro_reassemble()`` tries to merge input packets with the packets -in the reassembly tables. If an input packet is an unsupported GRO type, -or other errors happen (e.g. SYN bit is set), ``rte_gro_reassemble()`` -returns the packet to applications. Otherwise, the input packet is either -merged or inserted into a reassembly table. - -When applications want to get GRO processed packets, they need to use -``rte_gro_timeout_flush()`` to flush them from the tables manually. +technique to reduce per-packet processing overheads. By reassembling +small packets into larger ones, GRO enables applications to process +fewer large packets directly, thus reducing the number of packets to +be processed. To benefit DPDK-based applications, like Open vSwitch, +DPDK also provides own GRO implementation. In DPDK, GRO is implemented +as a standalone library. Applications explicitly use the GRO library to +reassemble packets. + +Overview +-------- + +In the GRO library, there are many GRO types which are defined by packet +types. One GRO type is in charge of process one kind of packets. For +example, TCP/IPv4 GRO processes TCP/IPv4 packets. + +Each GRO type has a reassembly function, which defines own algorithm and +table structure to reassemble packets. We assign input packets to the +corresponding GRO functions by MBUF->packet_type. + +The GRO library doesn't check if input packets have correct checksums and +doesn't re-calculate checksums for merged packets. The GRO library +assumes the packets are complete (i.e., MF==0 && frag_off==0), when IP +fragmentation is possible (i.e., DF==0). Additionally, it complies RFC +6864 to process the IPv4 ID field. + +Currently, the GRO library provides GRO supports for TCP/IPv4 packets and +VxLAN packets which contain an outer IPv4 header and an inner TCP/IPv4 +packet. + +Two Sets of API +--------------- + +For different usage scenarios, the GRO library provides two sets of API. +The one is called the lightweight mode API, which enables applications to +merge a small number of packets rapidly; the other is called the +heavyweight mode API, which provides fine-grained controls to +applications and supports to merge a large number of packets. + +Lightweight Mode API +~~~~~~~~~~~~~~~~~~~~ + +The lightweight mode only has one function ``rte_gro_reassemble_burst()``, +which process N packets at a time. Using the lightweight mode API to +merge packets is very simple. Calling ``rte_gro_reassemble_burst()`` is +enough. The GROed packets are returned to applications as soon as it +finishes. + +In ``rte_gro_reassemble_burst()``, table structures of different GRO +types are allocated in the stack. This design simplifies applications' +operations. However, limited by the stack size, the maximum number of +packets that ``rte_gro_reassemble_burst()`` can process in an invocation +should be less than or equal to ``RTE_GRO_MAX_BURST_ITEM_NUM``. + +Heavyweight Mode API +~~~~~~~~~~~~~~~~~~~~ + +Compared with the lightweight mode, using the heavyweight mode API is +relatively complex. Firstly, applications need to create a GRO context +by ``rte_gro_ctx_create()``. ``rte_gro_ctx_create()`` allocates tables +structures in the heap and stores their pointers in the GRO context. +Secondly, applications use ``rte_gro_reassemble()`` to merge packets. +If input packets have invalid parameters, ``rte_gro_reassemble()`` +returns them to applications. For example, packets of unsupported GRO +types or TCP SYN packets are returned. Otherwise, the input packets are +either merged with the existed packets in the tables or inserted into the +tables. Finally, applications use ``rte_gro_timeout_flush()`` to flush +packets from the tables, when they want to get the GROed packets. + +Note that all update/lookup operations on the GRO context are not thread +safe. So if different processes or threads want to access the same +context object simultaneously, some external syncing mechanisms must be +used. + +Reassembly Algorithm +-------------------- + +The reassembly algorithm is used for reassembling packets. In the GRO +library, different GRO types can use different algorithms. In this +section, we will introduce an algorithm, which is used by TCP/IPv4 GRO +and VxLAN GRO. + +Challenges +~~~~~~~~~~ + +The reassembly algorithm determines the efficiency of GRO. There are two +challenges in the algorithm design: + +- a high cost algorithm/implementation would cause packet dropping in a + high speed network. + +- packet reordering makes it hard to merge packets. For example, Linux + GRO fails to merge packets when encounters packet reordering. + +The above two challenges require our algorithm is: + +- lightweight enough to scale fast networking speed + +- capable of handling packet reordering + +In DPDK GRO, we use a key-based algorithm to address the two challenges. + +Key-based Reassembly Algorithm +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:numref:`figure_gro-key-algorithm` illustrates the procedure of the +key-based algorithm. Packets are classified into "flows" by some header +fields (we call them as "key"). To process an input packet, the algorithm +searches for a matched "flow" (i.e., the same value of key) for the +packet first, then checks all packets in the "flow" and tries to find a +"neighbor" for it. If find a "neighbor", merge the two packets together. +If can't find a "neighbor", store the packet into its "flow". If can't +find a matched "flow", insert a new "flow" and store the packet into the +"flow". + +.. note:: + Packets in the same "flow" that can't merge are always caused + by packet reordering. + +The key-based algorithm has two characters: + +- classifying packets into "flows" to accelerate packet aggregation is + simple (address challenge 1). + +- storing out-of-order packets makes it possible to merge later (address + challenge 2). + +.. _figure_gro-key-algorithm: + +.. figure:: img/gro-key-algorithm.* + :align: center + + Key-based Reassembly Algorithm TCP/IPv4 GRO ------------ -TCP/IPv4 GRO supports merging small TCP/IPv4 packets into large ones, -using a table structure called the TCP/IPv4 reassembly table. +The table structure used by TCP/IPv4 GRO contains two arrays: flow array +and item array. The flow array keeps flow information, and the item array +keeps packet information. -TCP/IPv4 Reassembly Table -~~~~~~~~~~~~~~~~~~~~~~~~~ +Header fields used to define a TCP/IPv4 flow include: -A TCP/IPv4 reassembly table includes a "key" array and an "item" array. -The key array keeps the criteria to merge packets and the item array -keeps the packet information. +- source and destination: Ethernet and IP address, TCP port -Each key in the key array points to an item group, which consists of -packets which have the same criteria values but can't be merged. A key -in the key array includes two parts: +- TCP acknowledge number -* ``criteria``: the criteria to merge packets. If two packets can be - merged, they must have the same criteria values. +TCP/IPv4 packets whose FIN, SYN, RST, URG, PSH, ECE or CWR bit is set +won't be processed. -* ``start_index``: the item array index of the first packet in the item - group. +Header fields deciding if two packets are neighbors include: -Each element in the item array keeps the information of a packet. An item -in the item array mainly includes three parts: +- TCP sequence number -* ``firstseg``: the mbuf address of the first segment of the packet. +- IPv4 ID. The IPv4 ID fields of the packets, whose DF bit is 0, should + be increased by 1. -* ``lastseg``: the mbuf address of the last segment of the packet. +VxLAN GRO +--------- -* ``next_pkt_index``: the item array index of the next packet in the same - item group. TCP/IPv4 GRO uses ``next_pkt_index`` to chain the packets - that have the same criteria value but can't be merged together. +The table structure used by VxLAN GRO, which is in charge of processing +VxLAN packets with an outer IPv4 header and inner TCP/IPv4 packet, is +similar with that of TCP/IPv4 GRO. Differently, the header fields used +to define a VxLAN flow include: -Procedure to Reassemble a Packet -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +- outer source and destination: Ethernet and IP address, UDP port -To reassemble an incoming packet needs three steps: +- VxLAN header (VNI and flag) -#. Check if the packet should be processed. Packets with one of the - following properties aren't processed and are returned immediately: +- inner source and destination: Ethernet and IP address, TCP port - * FIN, SYN, RST, URG, PSH, ECE or CWR bit is set. +Header fields deciding if packets are neighbors include: - * L4 payload length is 0. +- outer IPv4 ID. The IPv4 ID fields of the packets, whose DF bit in the + outer IPv4 header is 0, should be increased by 1. -#. Traverse the key array to find a key which has the same criteria - value with the incoming packet. If found, go to the next step. - Otherwise, insert a new key and a new item for the packet. +- inner TCP sequence number -#. Locate the first packet in the item group via ``start_index``. Then - traverse all packets in the item group via ``next_pkt_index``. If a - packet is found which can be merged with the incoming one, merge them - together. If one isn't found, insert the packet into this item group. - Note that to merge two packets is to link them together via mbuf's - ``next`` field. +- inner IPv4 ID. The IPv4 ID fields of the packets, whose DF bit in the + inner IPv4 header is 0, should be increased by 1. -When packets are flushed from the reassembly table, TCP/IPv4 GRO updates -packet header fields for the merged packets. Note that before reassembling -the packet, TCP/IPv4 GRO doesn't check if the checksums of packets are -correct. Also, TCP/IPv4 GRO doesn't re-calculate checksums for merged -packets. +.. note:: + We comply RFC 6864 to process the IPv4 ID field. Specifically, + we check IPv4 ID fields for the packets whose DF bit is 0 and + ignore IPv4 ID fields for the packets whose DF bit is 1. + Additionally, packets which have different value of DF bit can't + be merged. diff --git a/doc/guides/prog_guide/generic_segmentation_offload_lib.rst b/doc/guides/prog_guide/generic_segmentation_offload_lib.rst index ef1de53d..9959f0d2 100644 --- a/doc/guides/prog_guide/generic_segmentation_offload_lib.rst +++ b/doc/guides/prog_guide/generic_segmentation_offload_lib.rst @@ -1,32 +1,5 @@ -.. BSD LICENSE - Copyright(c) 2017 Intel Corporation. All rights reserved. - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in - the documentation and/or other materials provided with the - distribution. - * Neither the name of Intel Corporation nor the names of its - contributors may be used to endorse or promote products derived - from this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS - "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT - OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, - DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY - THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE - OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2017 Intel Corporation. Generic Segmentation Offload Library ==================================== diff --git a/doc/guides/prog_guide/glossary.rst b/doc/guides/prog_guide/glossary.rst index 4cbed4c6..e101bc02 100644 --- a/doc/guides/prog_guide/glossary.rst +++ b/doc/guides/prog_guide/glossary.rst @@ -1,32 +1,5 @@ -.. 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. +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2010-2014 Intel Corporation. Glossary ======== diff --git a/doc/guides/prog_guide/hash_lib.rst b/doc/guides/prog_guide/hash_lib.rst index 7944640c..180c776e 100644 --- a/doc/guides/prog_guide/hash_lib.rst +++ b/doc/guides/prog_guide/hash_lib.rst @@ -1,32 +1,5 @@ -.. BSD LICENSE - Copyright(c) 2010-2015 Intel Corporation. All rights reserved. - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in - the documentation and/or other materials provided with the - distribution. - * Neither the name of Intel Corporation nor the names of its - contributors may be used to endorse or promote products derived - from this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS - "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT - OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, - DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY - THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE - OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2010-2015 Intel Corporation. .. _Hash_Library: diff --git a/doc/guides/prog_guide/img/architecture-overview.svg b/doc/guides/prog_guide/img/architecture-overview.svg index c0f85bf2..cd8efaae 100644 --- a/doc/guides/prog_guide/img/architecture-overview.svg +++ b/doc/guides/prog_guide/img/architecture-overview.svg @@ -1,39 +1,8 @@ - + + - + + - + + - + + - + + - + + - + + - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Page-1 + + + + Rounded rectangle + Categorize into an existed “flow” + + + + + + + + + Categorize into an existed “flow” + + Rounded rectangle.2 + Search for a “neighbor” + + + + + + + + + Search for a “neighbor” + + Rounded rectangle.3 + Insert a new “flow” and store the packet + + + + + + + + + Insert a new “flow” and store the packet + + Rounded rectangle.4 + Store the packet + + + + + + + + + Store the packet + + Rounded rectangle.5 + Merge the packet + + + + + + + + + Merge the packet + + Dynamic connector + + + + + + + + + Dynamic connector.7 + + + + + + + + + Dynamic connector.8 + + + + + + + + + Dynamic connector.9 + + + + + + + + + Dynamic connector.10 + + + + + + + + + Sheet.11 + packet + + + + + + + + packet + + Sheet.14 + find a “flow” + + + + + + + + find a “flow” + + Sheet.15 + find a “neighbor” + + + + + + + + find a “neighbor” + + Sheet.13 + not find + + + + + + + + not find + + Sheet.12 + not find + + + + + + + + not find + + diff --git a/doc/guides/prog_guide/img/linuxapp_launch.svg b/doc/guides/prog_guide/img/linuxapp_launch.svg index 0ac450df..af685897 100644 --- a/doc/guides/prog_guide/img/linuxapp_launch.svg +++ b/doc/guides/prog_guide/img/linuxapp_launch.svg @@ -1,39 +1,8 @@ - + + - + + - + + - + + - + + - + + - + + - + + - + + - + + - + + - + + - + + - + + - + + - + + - + + - + + - + + - + + - + + - + +