[dpdk-dev,v2,3/3] doc: nics guide
Commit Message
Create nics guide by moving chapters about Intel and Mellanox NICs.
Signed-off-by: Thomas Monjalon <thomas.monjalon@6wind.com>
---
MAINTAINERS | 15 +-
doc/guides/index.rst | 1 +
.../driver_vm_emul_dev.rst => nics/e1000em.rst} | 0
doc/guides/{prog_guide => nics}/img/console.png | Bin
.../{prog_guide => nics}/img/fast_pkt_proc.png | Bin
.../{prog_guide => nics}/img/forward_stats.png | Bin
.../{prog_guide => nics}/img/host_vm_comms.png | Bin
.../img/host_vm_comms_qemu.png | Bin
.../{prog_guide => nics}/img/inter_vm_comms.png | Bin
.../{prog_guide => nics}/img/perf_benchmark.png | Bin
.../{prog_guide => nics}/img/single_port_nic.png | Bin
.../{prog_guide => nics}/img/vm_vm_comms.png | Bin
.../{prog_guide => nics}/img/vmxnet3_int.png | Bin
doc/guides/{prog_guide => nics}/img/vswitch_vm.png | Bin
doc/guides/{ => nics}/index.rst | 29 ++--
.../intel_vf.rst} | 8 +-
doc/guides/nics/ixgbe.rst | 184 +++++++++++++++++++++
.../mlx4_poll_mode_drv.rst => nics/mlx4.rst} | 0
.../pcap_ring.rst} | 0
.../virtio.rst} | 4 +-
.../vmxnet3.rst} | 0
doc/guides/prog_guide/index.rst | 17 --
doc/guides/prog_guide/poll_mode_drv.rst | 152 -----------------
23 files changed, 217 insertions(+), 193 deletions(-)
rename doc/guides/{prog_guide/driver_vm_emul_dev.rst => nics/e1000em.rst} (100%)
rename doc/guides/{prog_guide => nics}/img/console.png (100%)
rename doc/guides/{prog_guide => nics}/img/fast_pkt_proc.png (100%)
rename doc/guides/{prog_guide => nics}/img/forward_stats.png (100%)
rename doc/guides/{prog_guide => nics}/img/host_vm_comms.png (100%)
rename doc/guides/{prog_guide => nics}/img/host_vm_comms_qemu.png (100%)
rename doc/guides/{prog_guide => nics}/img/inter_vm_comms.png (100%)
rename doc/guides/{prog_guide => nics}/img/perf_benchmark.png (100%)
rename doc/guides/{prog_guide => nics}/img/single_port_nic.png (100%)
rename doc/guides/{prog_guide => nics}/img/vm_vm_comms.png (100%)
rename doc/guides/{prog_guide => nics}/img/vmxnet3_int.png (100%)
rename doc/guides/{prog_guide => nics}/img/vswitch_vm.png (100%)
copy doc/guides/{ => nics}/index.rst (88%)
rename doc/guides/{prog_guide/i40e_ixgbe_igb_virt_func_drv.rst => nics/intel_vf.rst} (99%)
create mode 100644 doc/guides/nics/ixgbe.rst
rename doc/guides/{prog_guide/mlx4_poll_mode_drv.rst => nics/mlx4.rst} (100%)
rename doc/guides/{prog_guide/libpcap_ring_based_poll_mode_drv.rst => nics/pcap_ring.rst} (100%)
rename doc/guides/{prog_guide/poll_mode_drv_emulated_virtio_nic.rst => nics/virtio.rst} (99%)
rename doc/guides/{prog_guide/poll_mode_drv_paravirtual_vmxnets_nic.rst => nics/vmxnet3.rst} (100%)
Comments
> -----Original Message-----
> From: Thomas Monjalon [mailto:thomas.monjalon@6wind.com]
> Sent: Thursday, March 19, 2015 4:49 PM
> To: Butler, Siobhan A; Iremonger, Bernard
> Cc: dev@dpdk.org
> Subject: [PATCH v2 3/3] doc: nics guide
>
> Create nics guide by moving chapters about Intel and Mellanox NICs.
>
> Signed-off-by: Thomas Monjalon <thomas.monjalon@6wind.com>
> ---
> MAINTAINERS | 15 +-
> doc/guides/index.rst | 1 +
> .../driver_vm_emul_dev.rst => nics/e1000em.rst} | 0
> doc/guides/{prog_guide => nics}/img/console.png | Bin
> .../{prog_guide => nics}/img/fast_pkt_proc.png | Bin
> .../{prog_guide => nics}/img/forward_stats.png | Bin
> .../{prog_guide => nics}/img/host_vm_comms.png | Bin
> .../img/host_vm_comms_qemu.png | Bin
> .../{prog_guide => nics}/img/inter_vm_comms.png | Bin
> .../{prog_guide => nics}/img/perf_benchmark.png | Bin
> .../{prog_guide => nics}/img/single_port_nic.png | Bin
> .../{prog_guide => nics}/img/vm_vm_comms.png | Bin
> .../{prog_guide => nics}/img/vmxnet3_int.png | Bin
> doc/guides/{prog_guide => nics}/img/vswitch_vm.png | Bin
> doc/guides/{ => nics}/index.rst | 29 ++--
> .../intel_vf.rst} | 8 +-
> doc/guides/nics/ixgbe.rst | 184 +++++++++++++++++++++
> .../mlx4_poll_mode_drv.rst => nics/mlx4.rst} | 0
> .../pcap_ring.rst} | 0
> .../virtio.rst} | 4 +-
> .../vmxnet3.rst} | 0
> doc/guides/prog_guide/index.rst | 17 --
> doc/guides/prog_guide/poll_mode_drv.rst | 152 -----------------
> 23 files changed, 217 insertions(+), 193 deletions(-) rename
> doc/guides/{prog_guide/driver_vm_emul_dev.rst => nics/e1000em.rst} (100%) rename
> doc/guides/{prog_guide => nics}/img/console.png (100%) rename doc/guides/{prog_guide =>
> nics}/img/fast_pkt_proc.png (100%) rename doc/guides/{prog_guide => nics}/img/forward_stats.png
> (100%) rename doc/guides/{prog_guide => nics}/img/host_vm_comms.png (100%) rename
> doc/guides/{prog_guide => nics}/img/host_vm_comms_qemu.png (100%) rename
> doc/guides/{prog_guide => nics}/img/inter_vm_comms.png (100%) rename doc/guides/{prog_guide
> => nics}/img/perf_benchmark.png (100%) rename doc/guides/{prog_guide =>
> nics}/img/single_port_nic.png (100%) rename doc/guides/{prog_guide =>
> nics}/img/vm_vm_comms.png (100%) rename doc/guides/{prog_guide =>
> nics}/img/vmxnet3_int.png (100%) rename doc/guides/{prog_guide => nics}/img/vswitch_vm.png
> (100%) copy doc/guides/{ => nics}/index.rst (88%) rename
> doc/guides/{prog_guide/i40e_ixgbe_igb_virt_func_drv.rst => nics/intel_vf.rst} (99%) create mode
> 100644 doc/guides/nics/ixgbe.rst rename doc/guides/{prog_guide/mlx4_poll_mode_drv.rst =>
> nics/mlx4.rst} (100%) rename doc/guides/{prog_guide/libpcap_ring_based_poll_mode_drv.rst =>
> nics/pcap_ring.rst} (100%) rename doc/guides/{prog_guide/poll_mode_drv_emulated_virtio_nic.rst
> => nics/virtio.rst} (99%) rename
> doc/guides/{prog_guide/poll_mode_drv_paravirtual_vmxnets_nic.rst => nics/vmxnet3.rst} (100%)
>
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 24f0a4c..0afb3f4 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -213,15 +213,20 @@ F: lib/librte_pmd_enic/
>
> Intel e1000
> F: lib/librte_pmd_e1000/
> +F: doc/guides/nics/e1000em.rst
> +F: doc/guides/nics/intel_vf.rst
>
> Intel ixgbe
> M: Helin Zhang <helin.zhang@intel.com>
> M: Konstantin Ananyev <konstantin.ananyev@intel.com>
> F: lib/librte_pmd_ixgbe/
> +F: doc/guides/nics/ixgbe.rst
> +F: doc/guides/nics/intel_vf.rst
>
> Intel i40e
> M: Helin Zhang <helin.zhang@intel.com>
> F: lib/librte_pmd_i40e/
> +F: doc/guides/nics/intel_vf.rst
>
> Intel fm10k
> M: Jing Chen <jing.d.chen@intel.com>
> @@ -230,12 +235,12 @@ F: lib/librte_pmd_fm10k/ Mellanox mlx4
> M: Adrien Mazarguil <adrien.mazarguil@6wind.com>
> F: lib/librte_pmd_mlx4/
> -F: doc/guides/prog_guide/mlx4_poll_mode_drv.rst
> +F: doc/guides/nics/mlx4.rst
>
> RedHat virtio
> M: Changchun Ouyang <changchun.ouyang@intel.com>
> F: lib/librte_pmd_virtio/
> -F: doc/guides/prog_guide/poll_mode_drv_emulated_virtio_nic.rst
> +F: doc/guides/nics/virtio.rst
> F: lib/librte_vhost/
> F: doc/guides/prog_guide/vhost_lib.rst
> F: examples/vhost/
> @@ -244,16 +249,16 @@ F: doc/guides/sample_app_ug/vhost.rst
> VMware vmxnet3
> M: Yong Wang <yongwang@vmware.com>
> F: lib/librte_pmd_vmxnet3/
> -F: doc/guides/prog_guide/poll_mode_drv_paravirtual_vmxnets_nic.rst
> +F: doc/guides/nics/vmxnet3.rst
>
> PCAP PMD
> F: lib/librte_pmd_pcap/
> -F: doc/guides/prog_guide/libpcap_ring_based_poll_mode_drv.rst
> +F: doc/guides/nics/pcap_ring.rst
>
> Ring PMD
> M: Bruce Richardson <bruce.richardson@intel.com>
> F: lib/librte_pmd_ring/
> -F: doc/guides/prog_guide/ring_lib.rst
> +F: doc/guides/nics/pcap_ring.rst
> F: app/test/test_pmd_ring.c
>
> Null PMD
> diff --git a/doc/guides/index.rst b/doc/guides/index.rst index 53f1be1..44e8432 100644
> --- a/doc/guides/index.rst
> +++ b/doc/guides/index.rst
> @@ -41,6 +41,7 @@ Contents:
> freebsd_gsg/index
> xen/index
> prog_guide/index
> + nics/index
> sample_app_ug/index
> testpmd_app_ug/index
> rel_notes/index
> diff --git a/doc/guides/prog_guide/driver_vm_emul_dev.rst b/doc/guides/nics/e1000em.rst similarity
> index 100% rename from doc/guides/prog_guide/driver_vm_emul_dev.rst
> rename to doc/guides/nics/e1000em.rst
> diff --git a/doc/guides/prog_guide/img/console.png b/doc/guides/nics/img/console.png similarity
> index 100% rename from doc/guides/prog_guide/img/console.png
> rename to doc/guides/nics/img/console.png diff --git
> a/doc/guides/prog_guide/img/fast_pkt_proc.png b/doc/guides/nics/img/fast_pkt_proc.png
> similarity index 100%
> rename from doc/guides/prog_guide/img/fast_pkt_proc.png
> rename to doc/guides/nics/img/fast_pkt_proc.png
> diff --git a/doc/guides/prog_guide/img/forward_stats.png b/doc/guides/nics/img/forward_stats.png
> similarity index 100%
> rename from doc/guides/prog_guide/img/forward_stats.png
> rename to doc/guides/nics/img/forward_stats.png
> diff --git a/doc/guides/prog_guide/img/host_vm_comms.png
> b/doc/guides/nics/img/host_vm_comms.png
> similarity index 100%
> rename from doc/guides/prog_guide/img/host_vm_comms.png
> rename to doc/guides/nics/img/host_vm_comms.png
> diff --git a/doc/guides/prog_guide/img/host_vm_comms_qemu.png
> b/doc/guides/nics/img/host_vm_comms_qemu.png
> similarity index 100%
> rename from doc/guides/prog_guide/img/host_vm_comms_qemu.png
> rename to doc/guides/nics/img/host_vm_comms_qemu.png
> diff --git a/doc/guides/prog_guide/img/inter_vm_comms.png
> b/doc/guides/nics/img/inter_vm_comms.png
> similarity index 100%
> rename from doc/guides/prog_guide/img/inter_vm_comms.png
> rename to doc/guides/nics/img/inter_vm_comms.png
> diff --git a/doc/guides/prog_guide/img/perf_benchmark.png
> b/doc/guides/nics/img/perf_benchmark.png
> similarity index 100%
> rename from doc/guides/prog_guide/img/perf_benchmark.png
> rename to doc/guides/nics/img/perf_benchmark.png
> diff --git a/doc/guides/prog_guide/img/single_port_nic.png
> b/doc/guides/nics/img/single_port_nic.png
> similarity index 100%
> rename from doc/guides/prog_guide/img/single_port_nic.png
> rename to doc/guides/nics/img/single_port_nic.png
> diff --git a/doc/guides/prog_guide/img/vm_vm_comms.png
> b/doc/guides/nics/img/vm_vm_comms.png
> similarity index 100%
> rename from doc/guides/prog_guide/img/vm_vm_comms.png
> rename to doc/guides/nics/img/vm_vm_comms.png
> diff --git a/doc/guides/prog_guide/img/vmxnet3_int.png b/doc/guides/nics/img/vmxnet3_int.png
> similarity index 100%
> rename from doc/guides/prog_guide/img/vmxnet3_int.png
> rename to doc/guides/nics/img/vmxnet3_int.png
> diff --git a/doc/guides/prog_guide/img/vswitch_vm.png b/doc/guides/nics/img/vswitch_vm.png
> similarity index 100%
> rename from doc/guides/prog_guide/img/vswitch_vm.png
> rename to doc/guides/nics/img/vswitch_vm.png
> diff --git a/doc/guides/index.rst b/doc/guides/nics/index.rst similarity index 88% copy from
> doc/guides/index.rst copy to doc/guides/nics/index.rst index 53f1be1..6eb2e94 100644
> --- a/doc/guides/index.rst
> +++ b/doc/guides/nics/index.rst
> @@ -28,19 +28,22 @@
> (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 documentation
> -==================
> +Network Interface Controller Drivers
> +====================================
>
> -Contents:
> +|today|
> +
> +
> +**Contents**
>
> .. toctree::
> - :maxdepth: 1
> - :titlesonly:
> -
> - linux_gsg/index
> - freebsd_gsg/index
> - xen/index
> - prog_guide/index
> - sample_app_ug/index
> - testpmd_app_ug/index
> - rel_notes/index
> + :maxdepth: 3
> + :numbered:
> +
> + e1000em
> + ixgbe
> + intel_vf
> + mlx4
> + virtio
> + vmxnet3
> + pcap_ring
> diff --git a/doc/guides/prog_guide/i40e_ixgbe_igb_virt_func_drv.rst b/doc/guides/nics/intel_vf.rst
> similarity index 99% rename from doc/guides/prog_guide/i40e_ixgbe_igb_virt_func_drv.rst
> rename to doc/guides/nics/intel_vf.rst
> index 68d7107..f97b68c 100644
> --- a/doc/guides/prog_guide/i40e_ixgbe_igb_virt_func_drv.rst
> +++ b/doc/guides/nics/intel_vf.rst
> @@ -72,7 +72,7 @@ For more detail on SR-IOV, please refer to the following documents:
>
> * `Scalable I/O Virtualized Servers
> <http://www.intel.com/content/www/us/en/virtualization/server-virtualization/scalable-i-o-
> virtualized-servers-paper.html>`_
>
> -.. _pg_figure_10:
> +.. _nic_figure_1:
>
> **Figure 10. Virtualization for a Single Port NIC in SR-IOV Mode**
>
> @@ -514,7 +514,7 @@ The setup procedure is as follows:
>
> * The Virtual Machine Monitor (see Figure 11) is equivalent to a Host OS with KVM installed as
> described in the instructions.
>
> -.. _pg_figure_11:
> +.. _nic_figure_2:
>
> **Figure 11. Performance Benchmark Setup**
>
> @@ -538,7 +538,7 @@ DPI can be offloaded on the host fast path.
> Figure 12 shows the scenario where some VMs directly communicate externally via a VFs, while
> others connect to a virtual switch and share the same uplink bandwidth.
>
> -.. _pg_figure_12:
> +.. _nic_figure_3:
>
> **Figure 12. Fast Host-based Packet Processing**
>
> @@ -566,7 +566,7 @@ that is, the packet is forwarded to the correct PF pool.
> The SR-IOV NIC switch forwards the packet to a specific VM according to the MAC destination address
> which belongs to the destination VF on the VM.
>
> -.. _pg_figure_13:
> +.. _nic_figure_4:
>
> **Figure 13. Inter-VM Communication**
>
> diff --git a/doc/guides/nics/ixgbe.rst b/doc/guides/nics/ixgbe.rst new file mode 100644 index
> 0000000..d2c124e
> --- /dev/null
> +++ b/doc/guides/nics/ixgbe.rst
> @@ -0,0 +1,184 @@
> +.. 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.
> +
> +IXGBE Driver
> +============
> +
> +Vector PMD for IXGBE
> +--------------------
> +
> +Vector PMD uses Intel® SIMD instructions to optimize packet I/O.
> +It improves load/store bandwidth efficiency of L1 data cache by using a wider SSE/AVX register 1 (1).
> +The wider register gives space to hold multiple packet buffers so as to save instruction number when
> processing bulk of packets.
> +
> +There is no change to PMD API. The RX/TX handler are the only two entries for vPMD packet I/O.
> +They are transparently registered at runtime RX/TX execution if all condition checks pass.
> +
> +1. To date, only an SSE version of IX GBE vPMD is available.
> + To ensure that vPMD is in the binary code, ensure that the option
> CONFIG_RTE_IXGBE_INC_VECTOR=y is in the configure file.
> +
> +Some constraints apply as pre-conditions for specific optimizations on bulk packet transfers.
> +The following sections explain RX and TX constraints in the vPMD.
> +
> +RX Constraints
> +~~~~~~~~~~~~~~
> +
> +Prerequisites and Pre-conditions
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +The following prerequisites apply:
> +
> +* To enable vPMD to work for RX, bulk allocation for Rx must be allowed.
> +
> +* The RTE_LIBRTE_IXGBE_RX_ALLOW_BULK_ALLOC=y configuration MACRO must be set before
> compiling the code.
> +
> +Ensure that the following pre-conditions are satisfied:
> +
> +* rxq->rx_free_thresh >= RTE_PMD_IXGBE_RX_MAX_BURST
> +
> +* rxq->rx_free_thresh < rxq->nb_rx_desc
> +
> +* (rxq->nb_rx_desc % rxq->rx_free_thresh) == 0
> +
> +* rxq->nb_rx_desc < (IXGBE_MAX_RING_DESC - RTE_PMD_IXGBE_RX_MAX_BURST)
> +
> +These conditions are checked in the code.
> +
> +Scattered packets are not supported in this mode.
> +If an incoming packet is greater than the maximum acceptable length of
> +one "mbuf" data size (by default, the size is 2 KB), vPMD for RX would be disabled.
> +
> +By default, IXGBE_MAX_RING_DESC is set to 4096 and RTE_PMD_IXGBE_RX_MAX_BURST is set to
> 32.
> +
> +Feature not Supported by RX Vector PMD
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +Some features are not supported when trying to increase the throughput in vPMD.
> +They are:
> +
> +* IEEE1588
> +
> +* FDIR
> +
> +* Header split
> +
> +* RX checksum off load
> +
> +Other features are supported using optional MACRO configuration. They include:
> +
> +* HW VLAN strip
> +
> +* HW extend dual VLAN
> +
> +* Enabled by RX_OLFLAGS (RTE_IXGBE_RX_OLFLAGS_DISABLE=n)
> +
> +
> +To guarantee the constraint, configuration flags in dev_conf.rxmode will be checked:
> +
> +* hw_vlan_strip
> +
> +* hw_vlan_extend
> +
> +* hw_ip_checksum
> +
> +* header_split
> +
> +* dev_conf
> +
> +fdir_conf->mode will also be checked.
> +
> +RX Burst Size
> +^^^^^^^^^^^^^
> +
> +As vPMD is focused on high throughput, it assumes that the RX burst size is equal to or greater than
> 32 per burst.
> +It returns zero if using nb_pkt < 32 as the expected packet number in the receive handler.
> +
> +TX Constraint
> +~~~~~~~~~~~~~
> +
> +Prerequisite
> +^^^^^^^^^^^^
> +
> +The only prerequisite is related to tx_rs_thresh.
> +The tx_rs_thresh value must be greater than or equal to
> +RTE_PMD_IXGBE_TX_MAX_BURST, but less or equal to RTE_IXGBE_TX_MAX_FREE_BUF_SZ.
> +Consequently, by default the tx_rs_thresh value is in the range 32 to 64.
> +
> +Feature not Supported by RX Vector PMD
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +TX vPMD only works when txq_flags is set to IXGBE_SIMPLE_FLAGS.
> +
> +This means that it does not support TX multi-segment, VLAN offload and TX csum offload.
> +The following MACROs are used for these three features:
> +
> +* ETH_TXQ_FLAGS_NOMULTSEGS
> +
> +* ETH_TXQ_FLAGS_NOVLANOFFL
> +
> +* ETH_TXQ_FLAGS_NOXSUMSCTP
> +
> +* ETH_TXQ_FLAGS_NOXSUMUDP
> +
> +* ETH_TXQ_FLAGS_NOXSUMTCP
> +
> +
> +Sample Application Notes
> +~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +testpmd
> +^^^^^^^
> +
> +By default, using CONFIG_RTE_IXGBE_RX_OLFLAGS_DISABLE=n:
> +
> +.. code-block:: console
> +
> + ./x86_64-native-linuxapp-gcc/app/testpmd -c 300 -n 4 -- -i
> + --burst=32 --rxfreet=32 --mbcache=250 --txpt=32 --rxht=8 --rxwt=0
> + --txfreet=32 --txrst=32 --txqflags=0xf01
> +
> +When CONFIG_RTE_IXGBE_RX_OLFLAGS_DISABLE=y, better performance can be achieved:
> +
> +.. code-block:: console
> +
> + ./x86_64-native-linuxapp-gcc/app/testpmd -c 300 -n 4 -- -i
> + --burst=32 --rxfreet=32 --mbcache=250 --txpt=32 --rxht=8 --rxwt=0
> + --txfreet=32 --txrst=32 --txqflags=0xf01 --disable-hw-vlan
> +
> +If scatter gather lists are not required, set CONFIG_RTE_MBUF_SCATTER_GATHER=n for better
> throughput.
> +
> +l3fwd
> +^^^^^
> +
> +When running l3fwd with vPMD, there is one thing to note.
> +In the configuration, ensure that port_conf.rxmode.hw_ip_checksum=0.
> +Otherwise, by default, RX vPMD is disabled.
> +
> +load_balancer
> +^^^^^^^^^^^^^
> +
> +As in the case of l3fwd, set configure port_conf.rxmode.hw_ip_checksum=0 to enable vPMD.
> +In addition, for improved performance, use -bsz "(32,32),(64,64),(32,32)" in load_balancer to avoid
> using the default burst size of 144.
> diff --git a/doc/guides/prog_guide/mlx4_poll_mode_drv.rst b/doc/guides/nics/mlx4.rst similarity
> index 100% rename from doc/guides/prog_guide/mlx4_poll_mode_drv.rst
> rename to doc/guides/nics/mlx4.rst
> diff --git a/doc/guides/prog_guide/libpcap_ring_based_poll_mode_drv.rst
> b/doc/guides/nics/pcap_ring.rst similarity index 100% rename from
> doc/guides/prog_guide/libpcap_ring_based_poll_mode_drv.rst
> rename to doc/guides/nics/pcap_ring.rst
> diff --git a/doc/guides/prog_guide/poll_mode_drv_emulated_virtio_nic.rst
> b/doc/guides/nics/virtio.rst similarity index 99% rename from
> doc/guides/prog_guide/poll_mode_drv_emulated_virtio_nic.rst
> rename to doc/guides/nics/virtio.rst
> index 113a0cb..5e2a283 100644
> --- a/doc/guides/prog_guide/poll_mode_drv_emulated_virtio_nic.rst
> +++ b/doc/guides/nics/virtio.rst
> @@ -106,7 +106,7 @@ Virtio with kni vhost Back End
>
> This section demonstrates kni vhost back end example setup for Phy-VM Communication.
>
> -.. _pg_figure_14:
> +.. _nic_figure_5:
>
> **Figure 14. Host2VM Communication Example Using kni vhost Back End**
>
> @@ -189,7 +189,7 @@ Host2VM communication example Virtio with qemu virtio Back End
> --------------------------------
>
> -.. _pg_figure_15:
> +.. _nic_figure_6:
>
> **Figure 15. Host2VM Communication Example Using qemu vhost Back End**
>
> diff --git a/doc/guides/prog_guide/poll_mode_drv_paravirtual_vmxnets_nic.rst
> b/doc/guides/nics/vmxnet3.rst similarity index 100% rename from
> doc/guides/prog_guide/poll_mode_drv_paravirtual_vmxnets_nic.rst
> rename to doc/guides/nics/vmxnet3.rst
> diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst index
> b263d31..648757e 100644
> --- a/doc/guides/prog_guide/index.rst
> +++ b/doc/guides/prog_guide/index.rst
> @@ -48,12 +48,7 @@ Programmer's Guide
> mempool_lib
> mbuf_lib
> poll_mode_drv
> - i40e_ixgbe_igb_virt_func_drv
> - driver_vm_emul_dev
> ivshmem_lib
> - poll_mode_drv_emulated_virtio_nic
> - poll_mode_drv_paravirtual_vmxnets_nic
> - libpcap_ring_based_poll_mode_drv
> link_bonding_poll_mode_drv_lib
> mlx4_poll_mode_drv
> timer_lib
> @@ -104,18 +99,6 @@ Programmer's Guide
>
> :ref:`Figure 9. An mbuf with Three Segments <pg_figure_9>`
>
> -:ref:`Figure 10. Virtualization for a Single Port NIC in SR-IOV Mode <pg_figure_10>`
> -
> -:ref:`Figure 11. Performance Benchmark Setup <pg_figure_11>`
> -
> -:ref:`Figure 12. Fast Host-based Packet Processing <pg_figure_12>`
> -
> -:ref:`Figure 13. Inter-VM Communication <pg_figure_13>`
> -
> -:ref:`Figure 14. Host2VM Communication Example Using kni vhost Back End <pg_figure_14>`
> -
> -:ref:`Figure 15. Host2VM Communication Example Using qemu vhost Back End <pg_figure_15>`
> -
Hi Thomas,
The references pg_figure_10 to 15 have been renamed to nic_figure_1 to 6.
The above :ref: lines which have been deleted should be move to nics/index.rst and reworded.
Regards,
Bernard.
> :ref:`Figure 16. Memory Sharing inthe Intel® DPDK Multi-process Sample Application <pg_figure_16>`
>
> :ref:`Figure 17. Components of an Intel® DPDK KNI Application <pg_figure_17>` diff --git
> a/doc/guides/prog_guide/poll_mode_drv.rst b/doc/guides/prog_guide/poll_mode_drv.rst
> index e9e1132..b8b2d1a 100644
> --- a/doc/guides/prog_guide/poll_mode_drv.rst
> +++ b/doc/guides/prog_guide/poll_mode_drv.rst
> @@ -288,155 +288,3 @@ Ethernet Device API ~~~~~~~~~~~~~~~~~~~
>
> The Ethernet device API exported by the Ethernet PMDs is described in the *DPDK API Reference*.
> -
> -Vector PMD for IXGBE
> ---------------------
> -
> -Vector PMD uses Intel® SIMD instructions to optimize packet I/O.
> -It improves load/store bandwidth efficiency of L1 data cache by using a wider SSE/AVX register 1 (1).
> -The wider register gives space to hold multiple packet buffers so as to save instruction number when
> processing bulk of packets.
> -
> -There is no change to PMD API. The RX/TX handler are the only two entries for vPMD packet I/O.
> -They are transparently registered at runtime RX/TX execution if all condition checks pass.
> -
> -1. To date, only an SSE version of IX GBE vPMD is available.
> - To ensure that vPMD is in the binary code, ensure that the option
> CONFIG_RTE_IXGBE_INC_VECTOR=y is in the configure file.
> -
> -Some constraints apply as pre-conditions for specific optimizations on bulk packet transfers.
> -The following sections explain RX and TX constraints in the vPMD.
> -
> -RX Constraints
> -~~~~~~~~~~~~~~
> -
> -Prerequisites and Pre-conditions
> -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> -
> -The following prerequisites apply:
> -
> -* To enable vPMD to work for RX, bulk allocation for Rx must be allowed.
> -
> -* The RTE_LIBRTE_IXGBE_RX_ALLOW_BULK_ALLOC=y configuration MACRO must be set before
> compiling the code.
> -
> -Ensure that the following pre-conditions are satisfied:
> -
> -* rxq->rx_free_thresh >= RTE_PMD_IXGBE_RX_MAX_BURST
> -
> -* rxq->rx_free_thresh < rxq->nb_rx_desc
> -
> -* (rxq->nb_rx_desc % rxq->rx_free_thresh) == 0
> -
> -* rxq->nb_rx_desc < (IXGBE_MAX_RING_DESC - RTE_PMD_IXGBE_RX_MAX_BURST)
> -
> -These conditions are checked in the code.
> -
> -Scattered packets are not supported in this mode.
> -If an incoming packet is greater than the maximum acceptable length of one "mbuf" data size (by
> default, the size is 2 KB), -vPMD for RX would be disabled.
> -
> -By default, IXGBE_MAX_RING_DESC is set to 4096 and RTE_PMD_IXGBE_RX_MAX_BURST is set to
> 32.
> -
> -Feature not Supported by RX Vector PMD
> -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> -
> -Some features are not supported when trying to increase the throughput in vPMD.
> -They are:
> -
> -* IEEE1588
> -
> -* FDIR
> -
> -* Header split
> -
> -* RX checksum off load
> -
> -Other features are supported using optional MACRO configuration. They include:
> -
> -* HW VLAN strip
> -
> -* HW extend dual VLAN
> -
> -* Enabled by RX_OLFLAGS (RTE_IXGBE_RX_OLFLAGS_DISABLE=n)
> -
> -
> -To guarantee the constraint, configuration flags in dev_conf.rxmode will be checked:
> -
> -* hw_vlan_strip
> -
> -* hw_vlan_extend
> -
> -* hw_ip_checksum
> -
> -* header_split
> -
> -* dev_conf
> -
> -fdir_conf->mode will also be checked.
> -
> -RX Burst Size
> -^^^^^^^^^^^^^
> -
> -As vPMD is focused on high throughput, it assumes that the RX burst size is equal to or greater than
> 32 per burst.
> -It returns zero if using nb_pkt < 32 as the expected packet number in the receive handler.
> -
> -TX Constraint
> -~~~~~~~~~~~~~
> -
> -Prerequisite
> -^^^^^^^^^^^^
> -
> -The only prerequisite is related to tx_rs_thresh.
> -The tx_rs_thresh value must be greater than or equal to RTE_PMD_IXGBE_TX_MAX_BURST, -but less
> or equal to RTE_IXGBE_TX_MAX_FREE_BUF_SZ.
> -Consequently, by default the tx_rs_thresh value is in the range 32 to 64.
> -
> -Feature not Supported by RX Vector PMD
> -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> -
> -TX vPMD only works when txq_flags is set to IXGBE_SIMPLE_FLAGS.
> -
> -This means that it does not support TX multi-segment, VLAN offload and TX csum offload.
> -The following MACROs are used for these three features:
> -
> -* ETH_TXQ_FLAGS_NOMULTSEGS
> -
> -* ETH_TXQ_FLAGS_NOVLANOFFL
> -
> -* ETH_TXQ_FLAGS_NOXSUMSCTP
> -
> -* ETH_TXQ_FLAGS_NOXSUMUDP
> -
> -* ETH_TXQ_FLAGS_NOXSUMTCP
> -
> -
> -Sample Application Notes
> -~~~~~~~~~~~~~~~~~~~~~~~~
> -
> -testpmd
> -^^^^^^^
> -
> -By default, using CONFIG_RTE_IXGBE_RX_OLFLAGS_DISABLE=n:
> -
> -.. code-block:: console
> -
> - ./x86_64-native-linuxapp-gcc/app/testpmd -c 300 -n 4 -- -i --burst=32 --rxfreet=32 --mbcache=250 -
> -txpt=32 --rxht=8 --rxwt=0 --txfreet=32 --txrst=32 --txqflags=0xf01
> -
> -When CONFIG_RTE_IXGBE_RX_OLFLAGS_DISABLE=y, better performance can be achieved:
> -
> -.. code-block:: console
> -
> - ./x86_64-native-linuxapp-gcc/app/testpmd -c 300 -n 4 -- -i --burst=32 --rxfreet=32 --mbcache=250 -
> -txpt=32 --rxht=8 --rxwt=0 --txfreet=32 --txrst=32 --txqflags=0xf01 --disable-hw-vlan
> -
> -If scatter gather lists are not required, set CONFIG_RTE_MBUF_SCATTER_GATHER=n for better
> throughput.
> -
> -l3fwd
> -^^^^^
> -
> -When running l3fwd with vPMD, there is one thing to note.
> -In the configuration, ensure that port_conf.rxmode.hw_ip_checksum=0.
> -Otherwise, by default, RX vPMD is disabled.
> -
> -load_balancer
> -^^^^^^^^^^^^^
> -
> -As in the case of l3fwd, set configure port_conf.rxmode.hw_ip_checksum=0 to enable vPMD.
> -In addition, for improved performance, use -bsz "(32,32),(64,64),(32,32)" in load_balancer to avoid
> using the default burst size of 144.
> --
> 2.2.2
> -----Original Message-----
> From: Thomas Monjalon [mailto:thomas.monjalon@6wind.com]
> Sent: Thursday, March 19, 2015 4:49 PM
> To: Butler, Siobhan A; Iremonger, Bernard
> Cc: dev@dpdk.org
> Subject: [PATCH v2 3/3] doc: nics guide
>
> Create nics guide by moving chapters about Intel and Mellanox NICs.
>
> Signed-off-by: Thomas Monjalon <thomas.monjalon@6wind.com>
> ---
> MAINTAINERS | 15 +-
> doc/guides/index.rst | 1 +
> .../driver_vm_emul_dev.rst => nics/e1000em.rst} | 0
> doc/guides/{prog_guide => nics}/img/console.png | Bin
> .../{prog_guide => nics}/img/fast_pkt_proc.png | Bin
> .../{prog_guide => nics}/img/forward_stats.png | Bin
> .../{prog_guide => nics}/img/host_vm_comms.png | Bin
> .../img/host_vm_comms_qemu.png | Bin
> .../{prog_guide => nics}/img/inter_vm_comms.png | Bin
> .../{prog_guide => nics}/img/perf_benchmark.png | Bin
> .../{prog_guide => nics}/img/single_port_nic.png | Bin
> .../{prog_guide => nics}/img/vm_vm_comms.png | Bin
> .../{prog_guide => nics}/img/vmxnet3_int.png | Bin
> doc/guides/{prog_guide => nics}/img/vswitch_vm.png | Bin
> doc/guides/{ => nics}/index.rst | 29 ++--
> .../intel_vf.rst} | 8 +-
> doc/guides/nics/ixgbe.rst | 184 +++++++++++++++++++++
> .../mlx4_poll_mode_drv.rst => nics/mlx4.rst} | 0
> .../pcap_ring.rst} | 0
> .../virtio.rst} | 4 +-
> .../vmxnet3.rst} | 0
> doc/guides/prog_guide/index.rst | 17 --
> doc/guides/prog_guide/poll_mode_drv.rst | 152 -----------------
> 23 files changed, 217 insertions(+), 193 deletions(-) rename
> doc/guides/{prog_guide/driver_vm_emul_dev.rst => nics/e1000em.rst}
> (100%) rename doc/guides/{prog_guide => nics}/img/console.png (100%)
> rename doc/guides/{prog_guide => nics}/img/fast_pkt_proc.png (100%)
> rename doc/guides/{prog_guide => nics}/img/forward_stats.png (100%)
> rename doc/guides/{prog_guide => nics}/img/host_vm_comms.png (100%)
> rename doc/guides/{prog_guide => nics}/img/host_vm_comms_qemu.png
> (100%) rename doc/guides/{prog_guide => nics}/img/inter_vm_comms.png
> (100%) rename doc/guides/{prog_guide => nics}/img/perf_benchmark.png
> (100%) rename doc/guides/{prog_guide => nics}/img/single_port_nic.png
> (100%) rename doc/guides/{prog_guide => nics}/img/vm_vm_comms.png
> (100%) rename doc/guides/{prog_guide => nics}/img/vmxnet3_int.png
> (100%) rename doc/guides/{prog_guide => nics}/img/vswitch_vm.png
> (100%) copy doc/guides/{ => nics}/index.rst (88%) rename
> doc/guides/{prog_guide/i40e_ixgbe_igb_virt_func_drv.rst =>
> nics/intel_vf.rst} (99%) create mode 100644 doc/guides/nics/ixgbe.rst
> rename doc/guides/{prog_guide/mlx4_poll_mode_drv.rst => nics/mlx4.rst}
> (100%) rename
> doc/guides/{prog_guide/libpcap_ring_based_poll_mode_drv.rst =>
> nics/pcap_ring.rst} (100%) rename
> doc/guides/{prog_guide/poll_mode_drv_emulated_virtio_nic.rst =>
> nics/virtio.rst} (99%) rename
> doc/guides/{prog_guide/poll_mode_drv_paravirtual_vmxnets_nic.rst =>
> nics/vmxnet3.rst} (100%)
>
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 24f0a4c..0afb3f4 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -213,15 +213,20 @@ F: lib/librte_pmd_enic/
>
> Intel e1000
> F: lib/librte_pmd_e1000/
> +F: doc/guides/nics/e1000em.rst
> +F: doc/guides/nics/intel_vf.rst
>
> Intel ixgbe
> M: Helin Zhang <helin.zhang@intel.com>
> M: Konstantin Ananyev <konstantin.ananyev@intel.com>
> F: lib/librte_pmd_ixgbe/
> +F: doc/guides/nics/ixgbe.rst
> +F: doc/guides/nics/intel_vf.rst
>
> Intel i40e
> M: Helin Zhang <helin.zhang@intel.com>
> F: lib/librte_pmd_i40e/
> +F: doc/guides/nics/intel_vf.rst
>
> Intel fm10k
> M: Jing Chen <jing.d.chen@intel.com>
> @@ -230,12 +235,12 @@ F: lib/librte_pmd_fm10k/ Mellanox mlx4
> M: Adrien Mazarguil <adrien.mazarguil@6wind.com>
> F: lib/librte_pmd_mlx4/
> -F: doc/guides/prog_guide/mlx4_poll_mode_drv.rst
> +F: doc/guides/nics/mlx4.rst
>
> RedHat virtio
> M: Changchun Ouyang <changchun.ouyang@intel.com>
> F: lib/librte_pmd_virtio/
> -F: doc/guides/prog_guide/poll_mode_drv_emulated_virtio_nic.rst
> +F: doc/guides/nics/virtio.rst
> F: lib/librte_vhost/
> F: doc/guides/prog_guide/vhost_lib.rst
> F: examples/vhost/
> @@ -244,16 +249,16 @@ F: doc/guides/sample_app_ug/vhost.rst
> VMware vmxnet3
> M: Yong Wang <yongwang@vmware.com>
> F: lib/librte_pmd_vmxnet3/
> -F: doc/guides/prog_guide/poll_mode_drv_paravirtual_vmxnets_nic.rst
> +F: doc/guides/nics/vmxnet3.rst
>
> PCAP PMD
> F: lib/librte_pmd_pcap/
> -F: doc/guides/prog_guide/libpcap_ring_based_poll_mode_drv.rst
> +F: doc/guides/nics/pcap_ring.rst
>
> Ring PMD
> M: Bruce Richardson <bruce.richardson@intel.com>
> F: lib/librte_pmd_ring/
> -F: doc/guides/prog_guide/ring_lib.rst
> +F: doc/guides/nics/pcap_ring.rst
> F: app/test/test_pmd_ring.c
>
> Null PMD
> diff --git a/doc/guides/index.rst b/doc/guides/index.rst index
> 53f1be1..44e8432 100644
> --- a/doc/guides/index.rst
> +++ b/doc/guides/index.rst
> @@ -41,6 +41,7 @@ Contents:
> freebsd_gsg/index
> xen/index
> prog_guide/index
> + nics/index
> sample_app_ug/index
> testpmd_app_ug/index
> rel_notes/index
> diff --git a/doc/guides/prog_guide/driver_vm_emul_dev.rst
> b/doc/guides/nics/e1000em.rst similarity index 100% rename from
> doc/guides/prog_guide/driver_vm_emul_dev.rst
> rename to doc/guides/nics/e1000em.rst
> diff --git a/doc/guides/prog_guide/img/console.png
> b/doc/guides/nics/img/console.png similarity index 100% rename from
> doc/guides/prog_guide/img/console.png
> rename to doc/guides/nics/img/console.png diff --git
> a/doc/guides/prog_guide/img/fast_pkt_proc.png
> b/doc/guides/nics/img/fast_pkt_proc.png
> similarity index 100%
> rename from doc/guides/prog_guide/img/fast_pkt_proc.png
> rename to doc/guides/nics/img/fast_pkt_proc.png
> diff --git a/doc/guides/prog_guide/img/forward_stats.png
> b/doc/guides/nics/img/forward_stats.png
> similarity index 100%
> rename from doc/guides/prog_guide/img/forward_stats.png
> rename to doc/guides/nics/img/forward_stats.png
> diff --git a/doc/guides/prog_guide/img/host_vm_comms.png
> b/doc/guides/nics/img/host_vm_comms.png
> similarity index 100%
> rename from doc/guides/prog_guide/img/host_vm_comms.png
> rename to doc/guides/nics/img/host_vm_comms.png
> diff --git a/doc/guides/prog_guide/img/host_vm_comms_qemu.png
> b/doc/guides/nics/img/host_vm_comms_qemu.png
> similarity index 100%
> rename from doc/guides/prog_guide/img/host_vm_comms_qemu.png
> rename to doc/guides/nics/img/host_vm_comms_qemu.png
> diff --git a/doc/guides/prog_guide/img/inter_vm_comms.png
> b/doc/guides/nics/img/inter_vm_comms.png
> similarity index 100%
> rename from doc/guides/prog_guide/img/inter_vm_comms.png
> rename to doc/guides/nics/img/inter_vm_comms.png
> diff --git a/doc/guides/prog_guide/img/perf_benchmark.png
> b/doc/guides/nics/img/perf_benchmark.png
> similarity index 100%
> rename from doc/guides/prog_guide/img/perf_benchmark.png
> rename to doc/guides/nics/img/perf_benchmark.png
> diff --git a/doc/guides/prog_guide/img/single_port_nic.png
> b/doc/guides/nics/img/single_port_nic.png
> similarity index 100%
> rename from doc/guides/prog_guide/img/single_port_nic.png
> rename to doc/guides/nics/img/single_port_nic.png
> diff --git a/doc/guides/prog_guide/img/vm_vm_comms.png
> b/doc/guides/nics/img/vm_vm_comms.png
> similarity index 100%
> rename from doc/guides/prog_guide/img/vm_vm_comms.png
> rename to doc/guides/nics/img/vm_vm_comms.png
> diff --git a/doc/guides/prog_guide/img/vmxnet3_int.png
> b/doc/guides/nics/img/vmxnet3_int.png
> similarity index 100%
> rename from doc/guides/prog_guide/img/vmxnet3_int.png
> rename to doc/guides/nics/img/vmxnet3_int.png
> diff --git a/doc/guides/prog_guide/img/vswitch_vm.png
> b/doc/guides/nics/img/vswitch_vm.png
> similarity index 100%
> rename from doc/guides/prog_guide/img/vswitch_vm.png
> rename to doc/guides/nics/img/vswitch_vm.png
> diff --git a/doc/guides/index.rst b/doc/guides/nics/index.rst similarity index
> 88% copy from doc/guides/index.rst copy to doc/guides/nics/index.rst index
> 53f1be1..6eb2e94 100644
> --- a/doc/guides/index.rst
> +++ b/doc/guides/nics/index.rst
> @@ -28,19 +28,22 @@
> (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 documentation
> -==================
> +Network Interface Controller Drivers
> +====================================
>
> -Contents:
> +|today|
> +
> +
> +**Contents**
>
> .. toctree::
> - :maxdepth: 1
> - :titlesonly:
> -
> - linux_gsg/index
> - freebsd_gsg/index
> - xen/index
> - prog_guide/index
> - sample_app_ug/index
> - testpmd_app_ug/index
> - rel_notes/index
> + :maxdepth: 3
> + :numbered:
> +
> + e1000em
> + ixgbe
> + intel_vf
> + mlx4
> + virtio
> + vmxnet3
> + pcap_ring
> diff --git a/doc/guides/prog_guide/i40e_ixgbe_igb_virt_func_drv.rst
> b/doc/guides/nics/intel_vf.rst similarity index 99% rename from
> doc/guides/prog_guide/i40e_ixgbe_igb_virt_func_drv.rst
> rename to doc/guides/nics/intel_vf.rst
> index 68d7107..f97b68c 100644
> --- a/doc/guides/prog_guide/i40e_ixgbe_igb_virt_func_drv.rst
> +++ b/doc/guides/nics/intel_vf.rst
> @@ -72,7 +72,7 @@ For more detail on SR-IOV, please refer to the following
> documents:
>
> * `Scalable I/O Virtualized Servers
> <http://www.intel.com/content/www/us/en/virtualization/server-
> virtualization/scalable-i-o-virtualized-servers-paper.html>`_
>
> -.. _pg_figure_10:
> +.. _nic_figure_1:
>
> **Figure 10. Virtualization for a Single Port NIC in SR-IOV Mode**
>
> @@ -514,7 +514,7 @@ The setup procedure is as follows:
>
> * The Virtual Machine Monitor (see Figure 11) is equivalent to a Host OS
> with KVM installed as described in the instructions.
>
> -.. _pg_figure_11:
> +.. _nic_figure_2:
>
> **Figure 11. Performance Benchmark Setup**
>
> @@ -538,7 +538,7 @@ DPI can be offloaded on the host fast path.
> Figure 12 shows the scenario where some VMs directly communicate
> externally via a VFs, while others connect to a virtual switch and share the
> same uplink bandwidth.
>
> -.. _pg_figure_12:
> +.. _nic_figure_3:
>
> **Figure 12. Fast Host-based Packet Processing**
>
> @@ -566,7 +566,7 @@ that is, the packet is forwarded to the correct PF pool.
> The SR-IOV NIC switch forwards the packet to a specific VM according to the
> MAC destination address which belongs to the destination VF on the VM.
>
> -.. _pg_figure_13:
> +.. _nic_figure_4:
>
> **Figure 13. Inter-VM Communication**
>
> diff --git a/doc/guides/nics/ixgbe.rst b/doc/guides/nics/ixgbe.rst new file
> mode 100644 index 0000000..d2c124e
> --- /dev/null
> +++ b/doc/guides/nics/ixgbe.rst
> @@ -0,0 +1,184 @@
> +.. 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.
> +
> +IXGBE Driver
> +============
> +
> +Vector PMD for IXGBE
> +--------------------
> +
> +Vector PMD uses Intel® SIMD instructions to optimize packet I/O.
> +It improves load/store bandwidth efficiency of L1 data cache by using a
> wider SSE/AVX register 1 (1).
> +The wider register gives space to hold multiple packet buffers so as to save
> instruction number when processing bulk of packets.
> +
> +There is no change to PMD API. The RX/TX handler are the only two entries
> for vPMD packet I/O.
> +They are transparently registered at runtime RX/TX execution if all condition
> checks pass.
> +
> +1. To date, only an SSE version of IX GBE vPMD is available.
> + To ensure that vPMD is in the binary code, ensure that the option
> CONFIG_RTE_IXGBE_INC_VECTOR=y is in the configure file.
> +
> +Some constraints apply as pre-conditions for specific optimizations on bulk
> packet transfers.
> +The following sections explain RX and TX constraints in the vPMD.
> +
> +RX Constraints
> +~~~~~~~~~~~~~~
> +
> +Prerequisites and Pre-conditions
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +The following prerequisites apply:
> +
> +* To enable vPMD to work for RX, bulk allocation for Rx must be allowed.
> +
> +* The RTE_LIBRTE_IXGBE_RX_ALLOW_BULK_ALLOC=y configuration
> MACRO must be set before compiling the code.
> +
> +Ensure that the following pre-conditions are satisfied:
> +
> +* rxq->rx_free_thresh >= RTE_PMD_IXGBE_RX_MAX_BURST
> +
> +* rxq->rx_free_thresh < rxq->nb_rx_desc
> +
> +* (rxq->nb_rx_desc % rxq->rx_free_thresh) == 0
> +
> +* rxq->nb_rx_desc < (IXGBE_MAX_RING_DESC -
> RTE_PMD_IXGBE_RX_MAX_BURST)
> +
> +These conditions are checked in the code.
> +
> +Scattered packets are not supported in this mode.
> +If an incoming packet is greater than the maximum acceptable length of
> +one "mbuf" data size (by default, the size is 2 KB), vPMD for RX would be
> disabled.
> +
> +By default, IXGBE_MAX_RING_DESC is set to 4096 and
> RTE_PMD_IXGBE_RX_MAX_BURST is set to 32.
> +
> +Feature not Supported by RX Vector PMD
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +Some features are not supported when trying to increase the throughput in
> vPMD.
> +They are:
> +
> +* IEEE1588
> +
> +* FDIR
> +
> +* Header split
> +
> +* RX checksum off load
> +
> +Other features are supported using optional MACRO configuration. They
> include:
> +
> +* HW VLAN strip
> +
> +* HW extend dual VLAN
> +
> +* Enabled by RX_OLFLAGS (RTE_IXGBE_RX_OLFLAGS_DISABLE=n)
> +
> +
> +To guarantee the constraint, configuration flags in dev_conf.rxmode will be
> checked:
> +
> +* hw_vlan_strip
> +
> +* hw_vlan_extend
> +
> +* hw_ip_checksum
> +
> +* header_split
> +
> +* dev_conf
> +
> +fdir_conf->mode will also be checked.
> +
> +RX Burst Size
> +^^^^^^^^^^^^^
> +
> +As vPMD is focused on high throughput, it assumes that the RX burst size is
> equal to or greater than 32 per burst.
> +It returns zero if using nb_pkt < 32 as the expected packet number in the
> receive handler.
> +
> +TX Constraint
> +~~~~~~~~~~~~~
> +
> +Prerequisite
> +^^^^^^^^^^^^
> +
> +The only prerequisite is related to tx_rs_thresh.
> +The tx_rs_thresh value must be greater than or equal to
> +RTE_PMD_IXGBE_TX_MAX_BURST, but less or equal to
> RTE_IXGBE_TX_MAX_FREE_BUF_SZ.
> +Consequently, by default the tx_rs_thresh value is in the range 32 to 64.
> +
> +Feature not Supported by RX Vector PMD
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +TX vPMD only works when txq_flags is set to IXGBE_SIMPLE_FLAGS.
> +
> +This means that it does not support TX multi-segment, VLAN offload and TX
> csum offload.
> +The following MACROs are used for these three features:
> +
> +* ETH_TXQ_FLAGS_NOMULTSEGS
> +
> +* ETH_TXQ_FLAGS_NOVLANOFFL
> +
> +* ETH_TXQ_FLAGS_NOXSUMSCTP
> +
> +* ETH_TXQ_FLAGS_NOXSUMUDP
> +
> +* ETH_TXQ_FLAGS_NOXSUMTCP
> +
> +
> +Sample Application Notes
> +~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +testpmd
> +^^^^^^^
> +
> +By default, using CONFIG_RTE_IXGBE_RX_OLFLAGS_DISABLE=n:
> +
> +.. code-block:: console
> +
> + ./x86_64-native-linuxapp-gcc/app/testpmd -c 300 -n 4 -- -i
> + --burst=32 --rxfreet=32 --mbcache=250 --txpt=32 --rxht=8 --rxwt=0
> + --txfreet=32 --txrst=32 --txqflags=0xf01
> +
> +When CONFIG_RTE_IXGBE_RX_OLFLAGS_DISABLE=y, better performance
> can be achieved:
> +
> +.. code-block:: console
> +
> + ./x86_64-native-linuxapp-gcc/app/testpmd -c 300 -n 4 -- -i
> + --burst=32 --rxfreet=32 --mbcache=250 --txpt=32 --rxht=8 --rxwt=0
> + --txfreet=32 --txrst=32 --txqflags=0xf01 --disable-hw-vlan
> +
> +If scatter gather lists are not required, set
> CONFIG_RTE_MBUF_SCATTER_GATHER=n for better throughput.
> +
> +l3fwd
> +^^^^^
> +
> +When running l3fwd with vPMD, there is one thing to note.
> +In the configuration, ensure that port_conf.rxmode.hw_ip_checksum=0.
> +Otherwise, by default, RX vPMD is disabled.
> +
> +load_balancer
> +^^^^^^^^^^^^^
> +
> +As in the case of l3fwd, set configure
> port_conf.rxmode.hw_ip_checksum=0 to enable vPMD.
> +In addition, for improved performance, use -bsz "(32,32),(64,64),(32,32)" in
> load_balancer to avoid using the default burst size of 144.
> diff --git a/doc/guides/prog_guide/mlx4_poll_mode_drv.rst
> b/doc/guides/nics/mlx4.rst similarity index 100% rename from
> doc/guides/prog_guide/mlx4_poll_mode_drv.rst
> rename to doc/guides/nics/mlx4.rst
> diff --git a/doc/guides/prog_guide/libpcap_ring_based_poll_mode_drv.rst
> b/doc/guides/nics/pcap_ring.rst similarity index 100% rename from
> doc/guides/prog_guide/libpcap_ring_based_poll_mode_drv.rst
> rename to doc/guides/nics/pcap_ring.rst
> diff --git a/doc/guides/prog_guide/poll_mode_drv_emulated_virtio_nic.rst
> b/doc/guides/nics/virtio.rst similarity index 99% rename from
> doc/guides/prog_guide/poll_mode_drv_emulated_virtio_nic.rst
> rename to doc/guides/nics/virtio.rst
> index 113a0cb..5e2a283 100644
> --- a/doc/guides/prog_guide/poll_mode_drv_emulated_virtio_nic.rst
> +++ b/doc/guides/nics/virtio.rst
> @@ -106,7 +106,7 @@ Virtio with kni vhost Back End
>
> This section demonstrates kni vhost back end example setup for Phy-VM
> Communication.
>
> -.. _pg_figure_14:
> +.. _nic_figure_5:
>
> **Figure 14. Host2VM Communication Example Using kni vhost Back End**
>
> @@ -189,7 +189,7 @@ Host2VM communication example Virtio with qemu
> virtio Back End
> --------------------------------
>
> -.. _pg_figure_15:
> +.. _nic_figure_6:
>
> **Figure 15. Host2VM Communication Example Using qemu vhost Back
> End**
>
> diff --git
> a/doc/guides/prog_guide/poll_mode_drv_paravirtual_vmxnets_nic.rst
> b/doc/guides/nics/vmxnet3.rst similarity index 100% rename from
> doc/guides/prog_guide/poll_mode_drv_paravirtual_vmxnets_nic.rst
> rename to doc/guides/nics/vmxnet3.rst
> diff --git a/doc/guides/prog_guide/index.rst
> b/doc/guides/prog_guide/index.rst index b263d31..648757e 100644
> --- a/doc/guides/prog_guide/index.rst
> +++ b/doc/guides/prog_guide/index.rst
> @@ -48,12 +48,7 @@ Programmer's Guide
> mempool_lib
> mbuf_lib
> poll_mode_drv
> - i40e_ixgbe_igb_virt_func_drv
> - driver_vm_emul_dev
> ivshmem_lib
> - poll_mode_drv_emulated_virtio_nic
> - poll_mode_drv_paravirtual_vmxnets_nic
> - libpcap_ring_based_poll_mode_drv
> link_bonding_poll_mode_drv_lib
> mlx4_poll_mode_drv
> timer_lib
> @@ -104,18 +99,6 @@ Programmer's Guide
>
> :ref:`Figure 9. An mbuf with Three Segments <pg_figure_9>`
>
> -:ref:`Figure 10. Virtualization for a Single Port NIC in SR-IOV Mode
> <pg_figure_10>`
> -
> -:ref:`Figure 11. Performance Benchmark Setup <pg_figure_11>`
> -
> -:ref:`Figure 12. Fast Host-based Packet Processing <pg_figure_12>`
> -
> -:ref:`Figure 13. Inter-VM Communication <pg_figure_13>`
> -
> -:ref:`Figure 14. Host2VM Communication Example Using kni vhost Back End
> <pg_figure_14>`
> -
> -:ref:`Figure 15. Host2VM Communication Example Using qemu vhost Back
> End <pg_figure_15>`
> -
> :ref:`Figure 16. Memory Sharing inthe Intel® DPDK Multi-process Sample
> Application <pg_figure_16>`
>
> :ref:`Figure 17. Components of an Intel® DPDK KNI Application
> <pg_figure_17>` diff --git a/doc/guides/prog_guide/poll_mode_drv.rst
> b/doc/guides/prog_guide/poll_mode_drv.rst
> index e9e1132..b8b2d1a 100644
> --- a/doc/guides/prog_guide/poll_mode_drv.rst
> +++ b/doc/guides/prog_guide/poll_mode_drv.rst
> @@ -288,155 +288,3 @@ Ethernet Device API ~~~~~~~~~~~~~~~~~~~
>
> The Ethernet device API exported by the Ethernet PMDs is described in the
> *DPDK API Reference*.
> -
> -Vector PMD for IXGBE
> ---------------------
> -
> -Vector PMD uses Intel® SIMD instructions to optimize packet I/O.
> -It improves load/store bandwidth efficiency of L1 data cache by using a
> wider SSE/AVX register 1 (1).
> -The wider register gives space to hold multiple packet buffers so as to save
> instruction number when processing bulk of packets.
> -
> -There is no change to PMD API. The RX/TX handler are the only two entries
> for vPMD packet I/O.
> -They are transparently registered at runtime RX/TX execution if all condition
> checks pass.
> -
> -1. To date, only an SSE version of IX GBE vPMD is available.
> - To ensure that vPMD is in the binary code, ensure that the option
> CONFIG_RTE_IXGBE_INC_VECTOR=y is in the configure file.
> -
> -Some constraints apply as pre-conditions for specific optimizations on bulk
> packet transfers.
> -The following sections explain RX and TX constraints in the vPMD.
> -
> -RX Constraints
> -~~~~~~~~~~~~~~
> -
> -Prerequisites and Pre-conditions
> -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> -
> -The following prerequisites apply:
> -
> -* To enable vPMD to work for RX, bulk allocation for Rx must be allowed.
> -
> -* The RTE_LIBRTE_IXGBE_RX_ALLOW_BULK_ALLOC=y configuration
> MACRO must be set before compiling the code.
> -
> -Ensure that the following pre-conditions are satisfied:
> -
> -* rxq->rx_free_thresh >= RTE_PMD_IXGBE_RX_MAX_BURST
> -
> -* rxq->rx_free_thresh < rxq->nb_rx_desc
> -
> -* (rxq->nb_rx_desc % rxq->rx_free_thresh) == 0
> -
> -* rxq->nb_rx_desc < (IXGBE_MAX_RING_DESC -
> RTE_PMD_IXGBE_RX_MAX_BURST)
> -
> -These conditions are checked in the code.
> -
> -Scattered packets are not supported in this mode.
> -If an incoming packet is greater than the maximum acceptable length of one
> "mbuf" data size (by default, the size is 2 KB), -vPMD for RX would be
> disabled.
> -
> -By default, IXGBE_MAX_RING_DESC is set to 4096 and
> RTE_PMD_IXGBE_RX_MAX_BURST is set to 32.
> -
> -Feature not Supported by RX Vector PMD
> -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> -
> -Some features are not supported when trying to increase the throughput in
> vPMD.
> -They are:
> -
> -* IEEE1588
> -
> -* FDIR
> -
> -* Header split
> -
> -* RX checksum off load
> -
> -Other features are supported using optional MACRO configuration. They
> include:
> -
> -* HW VLAN strip
> -
> -* HW extend dual VLAN
> -
> -* Enabled by RX_OLFLAGS (RTE_IXGBE_RX_OLFLAGS_DISABLE=n)
> -
> -
> -To guarantee the constraint, configuration flags in dev_conf.rxmode will be
> checked:
> -
> -* hw_vlan_strip
> -
> -* hw_vlan_extend
> -
> -* hw_ip_checksum
> -
> -* header_split
> -
> -* dev_conf
> -
> -fdir_conf->mode will also be checked.
> -
> -RX Burst Size
> -^^^^^^^^^^^^^
> -
> -As vPMD is focused on high throughput, it assumes that the RX burst size is
> equal to or greater than 32 per burst.
> -It returns zero if using nb_pkt < 32 as the expected packet number in the
> receive handler.
> -
> -TX Constraint
> -~~~~~~~~~~~~~
> -
> -Prerequisite
> -^^^^^^^^^^^^
> -
> -The only prerequisite is related to tx_rs_thresh.
> -The tx_rs_thresh value must be greater than or equal to
> RTE_PMD_IXGBE_TX_MAX_BURST, -but less or equal to
> RTE_IXGBE_TX_MAX_FREE_BUF_SZ.
> -Consequently, by default the tx_rs_thresh value is in the range 32 to 64.
> -
> -Feature not Supported by RX Vector PMD
> -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> -
> -TX vPMD only works when txq_flags is set to IXGBE_SIMPLE_FLAGS.
> -
> -This means that it does not support TX multi-segment, VLAN offload and TX
> csum offload.
> -The following MACROs are used for these three features:
> -
> -* ETH_TXQ_FLAGS_NOMULTSEGS
> -
> -* ETH_TXQ_FLAGS_NOVLANOFFL
> -
> -* ETH_TXQ_FLAGS_NOXSUMSCTP
> -
> -* ETH_TXQ_FLAGS_NOXSUMUDP
> -
> -* ETH_TXQ_FLAGS_NOXSUMTCP
> -
> -
> -Sample Application Notes
> -~~~~~~~~~~~~~~~~~~~~~~~~
> -
> -testpmd
> -^^^^^^^
> -
> -By default, using CONFIG_RTE_IXGBE_RX_OLFLAGS_DISABLE=n:
> -
> -.. code-block:: console
> -
> - ./x86_64-native-linuxapp-gcc/app/testpmd -c 300 -n 4 -- -i --burst=32 --
> rxfreet=32 --mbcache=250 --txpt=32 --rxht=8 --rxwt=0 --txfreet=32 --
> txrst=32 --txqflags=0xf01
> -
> -When CONFIG_RTE_IXGBE_RX_OLFLAGS_DISABLE=y, better performance
> can be achieved:
> -
> -.. code-block:: console
> -
> - ./x86_64-native-linuxapp-gcc/app/testpmd -c 300 -n 4 -- -i --burst=32 --
> rxfreet=32 --mbcache=250 --txpt=32 --rxht=8 --rxwt=0 --txfreet=32 --
> txrst=32 --txqflags=0xf01 --disable-hw-vlan
> -
> -If scatter gather lists are not required, set
> CONFIG_RTE_MBUF_SCATTER_GATHER=n for better throughput.
> -
> -l3fwd
> -^^^^^
> -
> -When running l3fwd with vPMD, there is one thing to note.
> -In the configuration, ensure that port_conf.rxmode.hw_ip_checksum=0.
> -Otherwise, by default, RX vPMD is disabled.
> -
> -load_balancer
> -^^^^^^^^^^^^^
> -
> -As in the case of l3fwd, set configure port_conf.rxmode.hw_ip_checksum=0
> to enable vPMD.
> -In addition, for improved performance, use -bsz "(32,32),(64,64),(32,32)" in
> load_balancer to avoid using the default burst size of 144.
> --
> 2.2.2
Acked-by Siobhan Butler <siobhan.a.butler@intel.com>
@@ -213,15 +213,20 @@ F: lib/librte_pmd_enic/
Intel e1000
F: lib/librte_pmd_e1000/
+F: doc/guides/nics/e1000em.rst
+F: doc/guides/nics/intel_vf.rst
Intel ixgbe
M: Helin Zhang <helin.zhang@intel.com>
M: Konstantin Ananyev <konstantin.ananyev@intel.com>
F: lib/librte_pmd_ixgbe/
+F: doc/guides/nics/ixgbe.rst
+F: doc/guides/nics/intel_vf.rst
Intel i40e
M: Helin Zhang <helin.zhang@intel.com>
F: lib/librte_pmd_i40e/
+F: doc/guides/nics/intel_vf.rst
Intel fm10k
M: Jing Chen <jing.d.chen@intel.com>
@@ -230,12 +235,12 @@ F: lib/librte_pmd_fm10k/
Mellanox mlx4
M: Adrien Mazarguil <adrien.mazarguil@6wind.com>
F: lib/librte_pmd_mlx4/
-F: doc/guides/prog_guide/mlx4_poll_mode_drv.rst
+F: doc/guides/nics/mlx4.rst
RedHat virtio
M: Changchun Ouyang <changchun.ouyang@intel.com>
F: lib/librte_pmd_virtio/
-F: doc/guides/prog_guide/poll_mode_drv_emulated_virtio_nic.rst
+F: doc/guides/nics/virtio.rst
F: lib/librte_vhost/
F: doc/guides/prog_guide/vhost_lib.rst
F: examples/vhost/
@@ -244,16 +249,16 @@ F: doc/guides/sample_app_ug/vhost.rst
VMware vmxnet3
M: Yong Wang <yongwang@vmware.com>
F: lib/librte_pmd_vmxnet3/
-F: doc/guides/prog_guide/poll_mode_drv_paravirtual_vmxnets_nic.rst
+F: doc/guides/nics/vmxnet3.rst
PCAP PMD
F: lib/librte_pmd_pcap/
-F: doc/guides/prog_guide/libpcap_ring_based_poll_mode_drv.rst
+F: doc/guides/nics/pcap_ring.rst
Ring PMD
M: Bruce Richardson <bruce.richardson@intel.com>
F: lib/librte_pmd_ring/
-F: doc/guides/prog_guide/ring_lib.rst
+F: doc/guides/nics/pcap_ring.rst
F: app/test/test_pmd_ring.c
Null PMD
@@ -41,6 +41,7 @@ Contents:
freebsd_gsg/index
xen/index
prog_guide/index
+ nics/index
sample_app_ug/index
testpmd_app_ug/index
rel_notes/index
similarity index 100%
rename from doc/guides/prog_guide/driver_vm_emul_dev.rst
rename to doc/guides/nics/e1000em.rst
similarity index 100%
rename from doc/guides/prog_guide/img/console.png
rename to doc/guides/nics/img/console.png
similarity index 100%
rename from doc/guides/prog_guide/img/fast_pkt_proc.png
rename to doc/guides/nics/img/fast_pkt_proc.png
similarity index 100%
rename from doc/guides/prog_guide/img/forward_stats.png
rename to doc/guides/nics/img/forward_stats.png
similarity index 100%
rename from doc/guides/prog_guide/img/host_vm_comms.png
rename to doc/guides/nics/img/host_vm_comms.png
similarity index 100%
rename from doc/guides/prog_guide/img/host_vm_comms_qemu.png
rename to doc/guides/nics/img/host_vm_comms_qemu.png
similarity index 100%
rename from doc/guides/prog_guide/img/inter_vm_comms.png
rename to doc/guides/nics/img/inter_vm_comms.png
similarity index 100%
rename from doc/guides/prog_guide/img/perf_benchmark.png
rename to doc/guides/nics/img/perf_benchmark.png
similarity index 100%
rename from doc/guides/prog_guide/img/single_port_nic.png
rename to doc/guides/nics/img/single_port_nic.png
similarity index 100%
rename from doc/guides/prog_guide/img/vm_vm_comms.png
rename to doc/guides/nics/img/vm_vm_comms.png
similarity index 100%
rename from doc/guides/prog_guide/img/vmxnet3_int.png
rename to doc/guides/nics/img/vmxnet3_int.png
similarity index 100%
rename from doc/guides/prog_guide/img/vswitch_vm.png
rename to doc/guides/nics/img/vswitch_vm.png
similarity index 88%
copy from doc/guides/index.rst
copy to doc/guides/nics/index.rst
@@ -28,19 +28,22 @@
(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 documentation
-==================
+Network Interface Controller Drivers
+====================================
-Contents:
+|today|
+
+
+**Contents**
.. toctree::
- :maxdepth: 1
- :titlesonly:
-
- linux_gsg/index
- freebsd_gsg/index
- xen/index
- prog_guide/index
- sample_app_ug/index
- testpmd_app_ug/index
- rel_notes/index
+ :maxdepth: 3
+ :numbered:
+
+ e1000em
+ ixgbe
+ intel_vf
+ mlx4
+ virtio
+ vmxnet3
+ pcap_ring
similarity index 99%
rename from doc/guides/prog_guide/i40e_ixgbe_igb_virt_func_drv.rst
rename to doc/guides/nics/intel_vf.rst
@@ -72,7 +72,7 @@ For more detail on SR-IOV, please refer to the following documents:
* `Scalable I/O Virtualized Servers <http://www.intel.com/content/www/us/en/virtualization/server-virtualization/scalable-i-o-virtualized-servers-paper.html>`_
-.. _pg_figure_10:
+.. _nic_figure_1:
**Figure 10. Virtualization for a Single Port NIC in SR-IOV Mode**
@@ -514,7 +514,7 @@ The setup procedure is as follows:
* The Virtual Machine Monitor (see Figure 11) is equivalent to a Host OS with KVM installed as described in the instructions.
-.. _pg_figure_11:
+.. _nic_figure_2:
**Figure 11. Performance Benchmark Setup**
@@ -538,7 +538,7 @@ DPI can be offloaded on the host fast path.
Figure 12 shows the scenario where some VMs directly communicate externally via a VFs,
while others connect to a virtual switch and share the same uplink bandwidth.
-.. _pg_figure_12:
+.. _nic_figure_3:
**Figure 12. Fast Host-based Packet Processing**
@@ -566,7 +566,7 @@ that is, the packet is forwarded to the correct PF pool.
The SR-IOV NIC switch forwards the packet to a specific VM according to the MAC destination address
which belongs to the destination VF on the VM.
-.. _pg_figure_13:
+.. _nic_figure_4:
**Figure 13. Inter-VM Communication**
new file mode 100644
@@ -0,0 +1,184 @@
+.. 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.
+
+IXGBE Driver
+============
+
+Vector PMD for IXGBE
+--------------------
+
+Vector PMD uses Intel® SIMD instructions to optimize packet I/O.
+It improves load/store bandwidth efficiency of L1 data cache by using a wider SSE/AVX register 1 (1).
+The wider register gives space to hold multiple packet buffers so as to save instruction number when processing bulk of packets.
+
+There is no change to PMD API. The RX/TX handler are the only two entries for vPMD packet I/O.
+They are transparently registered at runtime RX/TX execution if all condition checks pass.
+
+1. To date, only an SSE version of IX GBE vPMD is available.
+ To ensure that vPMD is in the binary code, ensure that the option CONFIG_RTE_IXGBE_INC_VECTOR=y is in the configure file.
+
+Some constraints apply as pre-conditions for specific optimizations on bulk packet transfers.
+The following sections explain RX and TX constraints in the vPMD.
+
+RX Constraints
+~~~~~~~~~~~~~~
+
+Prerequisites and Pre-conditions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following prerequisites apply:
+
+* To enable vPMD to work for RX, bulk allocation for Rx must be allowed.
+
+* The RTE_LIBRTE_IXGBE_RX_ALLOW_BULK_ALLOC=y configuration MACRO must be set before compiling the code.
+
+Ensure that the following pre-conditions are satisfied:
+
+* rxq->rx_free_thresh >= RTE_PMD_IXGBE_RX_MAX_BURST
+
+* rxq->rx_free_thresh < rxq->nb_rx_desc
+
+* (rxq->nb_rx_desc % rxq->rx_free_thresh) == 0
+
+* rxq->nb_rx_desc < (IXGBE_MAX_RING_DESC - RTE_PMD_IXGBE_RX_MAX_BURST)
+
+These conditions are checked in the code.
+
+Scattered packets are not supported in this mode.
+If an incoming packet is greater than the maximum acceptable length of one "mbuf" data size (by default, the size is 2 KB),
+vPMD for RX would be disabled.
+
+By default, IXGBE_MAX_RING_DESC is set to 4096 and RTE_PMD_IXGBE_RX_MAX_BURST is set to 32.
+
+Feature not Supported by RX Vector PMD
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Some features are not supported when trying to increase the throughput in vPMD.
+They are:
+
+* IEEE1588
+
+* FDIR
+
+* Header split
+
+* RX checksum off load
+
+Other features are supported using optional MACRO configuration. They include:
+
+* HW VLAN strip
+
+* HW extend dual VLAN
+
+* Enabled by RX_OLFLAGS (RTE_IXGBE_RX_OLFLAGS_DISABLE=n)
+
+
+To guarantee the constraint, configuration flags in dev_conf.rxmode will be checked:
+
+* hw_vlan_strip
+
+* hw_vlan_extend
+
+* hw_ip_checksum
+
+* header_split
+
+* dev_conf
+
+fdir_conf->mode will also be checked.
+
+RX Burst Size
+^^^^^^^^^^^^^
+
+As vPMD is focused on high throughput, it assumes that the RX burst size is equal to or greater than 32 per burst.
+It returns zero if using nb_pkt < 32 as the expected packet number in the receive handler.
+
+TX Constraint
+~~~~~~~~~~~~~
+
+Prerequisite
+^^^^^^^^^^^^
+
+The only prerequisite is related to tx_rs_thresh.
+The tx_rs_thresh value must be greater than or equal to RTE_PMD_IXGBE_TX_MAX_BURST,
+but less or equal to RTE_IXGBE_TX_MAX_FREE_BUF_SZ.
+Consequently, by default the tx_rs_thresh value is in the range 32 to 64.
+
+Feature not Supported by RX Vector PMD
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+TX vPMD only works when txq_flags is set to IXGBE_SIMPLE_FLAGS.
+
+This means that it does not support TX multi-segment, VLAN offload and TX csum offload.
+The following MACROs are used for these three features:
+
+* ETH_TXQ_FLAGS_NOMULTSEGS
+
+* ETH_TXQ_FLAGS_NOVLANOFFL
+
+* ETH_TXQ_FLAGS_NOXSUMSCTP
+
+* ETH_TXQ_FLAGS_NOXSUMUDP
+
+* ETH_TXQ_FLAGS_NOXSUMTCP
+
+
+Sample Application Notes
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+testpmd
+^^^^^^^
+
+By default, using CONFIG_RTE_IXGBE_RX_OLFLAGS_DISABLE=n:
+
+.. code-block:: console
+
+ ./x86_64-native-linuxapp-gcc/app/testpmd -c 300 -n 4 -- -i --burst=32 --rxfreet=32 --mbcache=250 --txpt=32 --rxht=8 --rxwt=0 --txfreet=32 --txrst=32 --txqflags=0xf01
+
+When CONFIG_RTE_IXGBE_RX_OLFLAGS_DISABLE=y, better performance can be achieved:
+
+.. code-block:: console
+
+ ./x86_64-native-linuxapp-gcc/app/testpmd -c 300 -n 4 -- -i --burst=32 --rxfreet=32 --mbcache=250 --txpt=32 --rxht=8 --rxwt=0 --txfreet=32 --txrst=32 --txqflags=0xf01 --disable-hw-vlan
+
+If scatter gather lists are not required, set CONFIG_RTE_MBUF_SCATTER_GATHER=n for better throughput.
+
+l3fwd
+^^^^^
+
+When running l3fwd with vPMD, there is one thing to note.
+In the configuration, ensure that port_conf.rxmode.hw_ip_checksum=0.
+Otherwise, by default, RX vPMD is disabled.
+
+load_balancer
+^^^^^^^^^^^^^
+
+As in the case of l3fwd, set configure port_conf.rxmode.hw_ip_checksum=0 to enable vPMD.
+In addition, for improved performance, use -bsz "(32,32),(64,64),(32,32)" in load_balancer to avoid using the default burst size of 144.
similarity index 100%
rename from doc/guides/prog_guide/mlx4_poll_mode_drv.rst
rename to doc/guides/nics/mlx4.rst
similarity index 100%
rename from doc/guides/prog_guide/libpcap_ring_based_poll_mode_drv.rst
rename to doc/guides/nics/pcap_ring.rst
similarity index 99%
rename from doc/guides/prog_guide/poll_mode_drv_emulated_virtio_nic.rst
rename to doc/guides/nics/virtio.rst
@@ -106,7 +106,7 @@ Virtio with kni vhost Back End
This section demonstrates kni vhost back end example setup for Phy-VM Communication.
-.. _pg_figure_14:
+.. _nic_figure_5:
**Figure 14. Host2VM Communication Example Using kni vhost Back End**
@@ -189,7 +189,7 @@ Host2VM communication example
Virtio with qemu virtio Back End
--------------------------------
-.. _pg_figure_15:
+.. _nic_figure_6:
**Figure 15. Host2VM Communication Example Using qemu vhost Back End**
similarity index 100%
rename from doc/guides/prog_guide/poll_mode_drv_paravirtual_vmxnets_nic.rst
rename to doc/guides/nics/vmxnet3.rst
@@ -48,12 +48,7 @@ Programmer's Guide
mempool_lib
mbuf_lib
poll_mode_drv
- i40e_ixgbe_igb_virt_func_drv
- driver_vm_emul_dev
ivshmem_lib
- poll_mode_drv_emulated_virtio_nic
- poll_mode_drv_paravirtual_vmxnets_nic
- libpcap_ring_based_poll_mode_drv
link_bonding_poll_mode_drv_lib
mlx4_poll_mode_drv
timer_lib
@@ -104,18 +99,6 @@ Programmer's Guide
:ref:`Figure 9. An mbuf with Three Segments <pg_figure_9>`
-:ref:`Figure 10. Virtualization for a Single Port NIC in SR-IOV Mode <pg_figure_10>`
-
-:ref:`Figure 11. Performance Benchmark Setup <pg_figure_11>`
-
-:ref:`Figure 12. Fast Host-based Packet Processing <pg_figure_12>`
-
-:ref:`Figure 13. Inter-VM Communication <pg_figure_13>`
-
-:ref:`Figure 14. Host2VM Communication Example Using kni vhost Back End <pg_figure_14>`
-
-:ref:`Figure 15. Host2VM Communication Example Using qemu vhost Back End <pg_figure_15>`
-
:ref:`Figure 16. Memory Sharing inthe Intel® DPDK Multi-process Sample Application <pg_figure_16>`
:ref:`Figure 17. Components of an Intel® DPDK KNI Application <pg_figure_17>`
@@ -288,155 +288,3 @@ Ethernet Device API
~~~~~~~~~~~~~~~~~~~
The Ethernet device API exported by the Ethernet PMDs is described in the *DPDK API Reference*.
-
-Vector PMD for IXGBE
---------------------
-
-Vector PMD uses Intel® SIMD instructions to optimize packet I/O.
-It improves load/store bandwidth efficiency of L1 data cache by using a wider SSE/AVX register 1 (1).
-The wider register gives space to hold multiple packet buffers so as to save instruction number when processing bulk of packets.
-
-There is no change to PMD API. The RX/TX handler are the only two entries for vPMD packet I/O.
-They are transparently registered at runtime RX/TX execution if all condition checks pass.
-
-1. To date, only an SSE version of IX GBE vPMD is available.
- To ensure that vPMD is in the binary code, ensure that the option CONFIG_RTE_IXGBE_INC_VECTOR=y is in the configure file.
-
-Some constraints apply as pre-conditions for specific optimizations on bulk packet transfers.
-The following sections explain RX and TX constraints in the vPMD.
-
-RX Constraints
-~~~~~~~~~~~~~~
-
-Prerequisites and Pre-conditions
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The following prerequisites apply:
-
-* To enable vPMD to work for RX, bulk allocation for Rx must be allowed.
-
-* The RTE_LIBRTE_IXGBE_RX_ALLOW_BULK_ALLOC=y configuration MACRO must be set before compiling the code.
-
-Ensure that the following pre-conditions are satisfied:
-
-* rxq->rx_free_thresh >= RTE_PMD_IXGBE_RX_MAX_BURST
-
-* rxq->rx_free_thresh < rxq->nb_rx_desc
-
-* (rxq->nb_rx_desc % rxq->rx_free_thresh) == 0
-
-* rxq->nb_rx_desc < (IXGBE_MAX_RING_DESC - RTE_PMD_IXGBE_RX_MAX_BURST)
-
-These conditions are checked in the code.
-
-Scattered packets are not supported in this mode.
-If an incoming packet is greater than the maximum acceptable length of one "mbuf" data size (by default, the size is 2 KB),
-vPMD for RX would be disabled.
-
-By default, IXGBE_MAX_RING_DESC is set to 4096 and RTE_PMD_IXGBE_RX_MAX_BURST is set to 32.
-
-Feature not Supported by RX Vector PMD
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Some features are not supported when trying to increase the throughput in vPMD.
-They are:
-
-* IEEE1588
-
-* FDIR
-
-* Header split
-
-* RX checksum off load
-
-Other features are supported using optional MACRO configuration. They include:
-
-* HW VLAN strip
-
-* HW extend dual VLAN
-
-* Enabled by RX_OLFLAGS (RTE_IXGBE_RX_OLFLAGS_DISABLE=n)
-
-
-To guarantee the constraint, configuration flags in dev_conf.rxmode will be checked:
-
-* hw_vlan_strip
-
-* hw_vlan_extend
-
-* hw_ip_checksum
-
-* header_split
-
-* dev_conf
-
-fdir_conf->mode will also be checked.
-
-RX Burst Size
-^^^^^^^^^^^^^
-
-As vPMD is focused on high throughput, it assumes that the RX burst size is equal to or greater than 32 per burst.
-It returns zero if using nb_pkt < 32 as the expected packet number in the receive handler.
-
-TX Constraint
-~~~~~~~~~~~~~
-
-Prerequisite
-^^^^^^^^^^^^
-
-The only prerequisite is related to tx_rs_thresh.
-The tx_rs_thresh value must be greater than or equal to RTE_PMD_IXGBE_TX_MAX_BURST,
-but less or equal to RTE_IXGBE_TX_MAX_FREE_BUF_SZ.
-Consequently, by default the tx_rs_thresh value is in the range 32 to 64.
-
-Feature not Supported by RX Vector PMD
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-TX vPMD only works when txq_flags is set to IXGBE_SIMPLE_FLAGS.
-
-This means that it does not support TX multi-segment, VLAN offload and TX csum offload.
-The following MACROs are used for these three features:
-
-* ETH_TXQ_FLAGS_NOMULTSEGS
-
-* ETH_TXQ_FLAGS_NOVLANOFFL
-
-* ETH_TXQ_FLAGS_NOXSUMSCTP
-
-* ETH_TXQ_FLAGS_NOXSUMUDP
-
-* ETH_TXQ_FLAGS_NOXSUMTCP
-
-
-Sample Application Notes
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-testpmd
-^^^^^^^
-
-By default, using CONFIG_RTE_IXGBE_RX_OLFLAGS_DISABLE=n:
-
-.. code-block:: console
-
- ./x86_64-native-linuxapp-gcc/app/testpmd -c 300 -n 4 -- -i --burst=32 --rxfreet=32 --mbcache=250 --txpt=32 --rxht=8 --rxwt=0 --txfreet=32 --txrst=32 --txqflags=0xf01
-
-When CONFIG_RTE_IXGBE_RX_OLFLAGS_DISABLE=y, better performance can be achieved:
-
-.. code-block:: console
-
- ./x86_64-native-linuxapp-gcc/app/testpmd -c 300 -n 4 -- -i --burst=32 --rxfreet=32 --mbcache=250 --txpt=32 --rxht=8 --rxwt=0 --txfreet=32 --txrst=32 --txqflags=0xf01 --disable-hw-vlan
-
-If scatter gather lists are not required, set CONFIG_RTE_MBUF_SCATTER_GATHER=n for better throughput.
-
-l3fwd
-^^^^^
-
-When running l3fwd with vPMD, there is one thing to note.
-In the configuration, ensure that port_conf.rxmode.hw_ip_checksum=0.
-Otherwise, by default, RX vPMD is disabled.
-
-load_balancer
-^^^^^^^^^^^^^
-
-As in the case of l3fwd, set configure port_conf.rxmode.hw_ip_checksum=0 to enable vPMD.
-In addition, for improved performance, use -bsz "(32,32),(64,64),(32,32)" in load_balancer to avoid using the default burst size of 144.