[dpdk-dev,RFC,3/4] doc: nics guide
Commit Message
Create nics guide by moving chapters about Intel NICS.
Signed-off-by: Thomas Monjalon <thomas.monjalon@6wind.com>
---
MAINTAINERS | 13 +-
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 | 28 ++--
.../intel_vf.rst} | 0
doc/guides/nics/ixgbe.rst | 184 +++++++++++++++++++++
.../pcap_ring.rst} | 0
.../virtio.rst} | 0
.../vmxnet3.rst} | 0
doc/guides/prog_guide/index.rst | 17 --
doc/guides/prog_guide/poll_mode_drv.rst | 152 -----------------
22 files changed, 209 insertions(+), 186 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} (100%)
create mode 100644 doc/guides/nics/ixgbe.rst
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} (100%)
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: Saturday, January 31, 2015 11:35 PM
> To: dev@dpdk.org
> Cc: Butler, Siobhan A; Iremonger, Bernard
> Subject: [RFC PATCH 3/4] doc: nics guide
>
> Create nics guide by moving chapters about Intel NICS.
>
> Signed-off-by: Thomas Monjalon <thomas.monjalon@6wind.com>
> ---
> MAINTAINERS | 13 +-
> 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 | 28 ++--
> .../intel_vf.rst} | 0
> doc/guides/nics/ixgbe.rst | 184 +++++++++++++++++++++
> .../pcap_ring.rst} | 0
> .../virtio.rst} | 0
> .../vmxnet3.rst} | 0
> doc/guides/prog_guide/index.rst | 17 --
> doc/guides/prog_guide/poll_mode_drv.rst | 152 -----------------
> 22 files changed, 209 insertions(+), 186 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} (100%) create mode
> 100644 doc/guides/nics/ixgbe.rst 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} (100%)
> rename doc/guides/{prog_guide/poll_mode_drv_paravirtual_vmxnets_nic.rst => nics/vmxnet3.rst}
> (100%)
>
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 1d9ddbc..343e18f 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -190,16 +190,21 @@ 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
> F: lib/librte_pmd_ixgbe/
> +F: doc/guides/nics/ixgbe.rst
> +F: doc/guides/nics/intel_vf.rst
>
> Intel i40e
> F: lib/librte_pmd_i40e/
> +F: doc/guides/nics/intel_vf.rst
>
> RedHat virtio
> 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/
> @@ -207,15 +212,15 @@ F: doc/guides/sample_app_ug/vhost.rst
>
> VMware vmxnet3
> 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
> 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
>
>
> 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..b9bd56a 100644
> --- a/doc/guides/index.rst
> +++ b/doc/guides/nics/index.rst
> @@ -28,19 +28,21 @@
> (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
> + 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 100% rename from doc/guides/prog_guide/i40e_ixgbe_igb_virt_func_drv.rst
> rename to doc/guides/nics/intel_vf.rst
> 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.
Hi Thomas,
2014 should move to 2015
> + 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/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 100% rename from
> doc/guides/prog_guide/poll_mode_drv_emulated_virtio_nic.rst
> rename to doc/guides/nics/virtio.rst
> 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
> cdc7ea0..4dec828 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
> timer_lib
> hash_lib
> @@ -101,18 +96,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
References to Figures 9 to 17 have been removed have they been reinstated somewhere else ?
> 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
Regards,
Bernard.
Hi Bernard,
Please try to remove useless lines when answering.
I'm digging in the message to find your comments ;)
2015-02-02 14:11, Iremonger, Bernard:
> From: Thomas Monjalon [mailto:thomas.monjalon@6wind.com]
> > --- /dev/null
> > +++ b/doc/guides/nics/ixgbe.rst
> > @@ -0,0 +1,184 @@
> > +.. BSD LICENSE
> > + Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
> Hi Thomas,
>
> 2014 should move to 2015
I think I should keep it as is because I'm only moving sections
and I don't have any right to change an Intel copyright.
> > --- 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
> > timer_lib
> > hash_lib
> > @@ -101,18 +96,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
>
> References to Figures 9 to 17 have been removed have they been reinstated somewhere else ?
Figures 10 to 15 moved in doc/guides/nics/img.
I didn't re-create the references in doc/guides/nics/index.rst nor renumbered
the ones in doc/guides/prog_guide/index.rst.
I think these manual numberings should be removed as it is a pain to update.
Actually I don't really understand what is the usage of such references.
So I suggest to completely remove them or generate them with a script.
Thanks
> Hi Bernard,
>
> Please try to remove useless lines when answering.
> I'm digging in the message to find your comments ;)
Hi Thomas,
Ok, will do in future.
>
> 2015-02-02 14:11, Iremonger, Bernard:
> > From: Thomas Monjalon [mailto:thomas.monjalon@6wind.com]
> > > --- /dev/null
> > > +++ b/doc/guides/nics/ixgbe.rst
> > > @@ -0,0 +1,184 @@
> > > +.. BSD LICENSE
> > > + Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
> > Hi Thomas,
> >
> > 2014 should move to 2015
>
> I think I should keep it as is because I'm only moving sections and I don't have any right to change an
> Intel copyright.
Ok.
>
> > > --- a/doc/guides/prog_guide/index.rst
> > > +++ b/doc/guides/prog_guide/index.rst
> > > @@ -101,18 +96,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(r) DPDK Multi-process
> > > Sample Application <pg_figure_16>`
> > >
> > > :ref:`Figure 17. Components of an Intel(r) DPDK KNI Application
> > > <pg_figure_17>` diff --git
> >
> > References to Figures 9 to 17 have been removed have they been reinstated somewhere else ?
>
> Figures 10 to 15 moved in doc/guides/nics/img.
>
> I didn't re-create the references in doc/guides/nics/index.rst nor renumbered the ones in
> doc/guides/prog_guide/index.rst.
It would be better to recreate the references in doc/guides/nics/index.rst rather than just delete them.
I don't think there is any need to renumber them.
The references are global across documents and must be unique.
> I think these manual numberings should be removed as it is a pain to update.
> Actually I don't really understand what is the usage of such references.
> So I suggest to completely remove them or generate them with a script.
These references were in the original 1.7 MSWord docs.
When reading a document it enabled the reader to jump to another section and jump back, they worked in the HTML docs too.
I think they should be retained.
>
> Thanks
> --
> Thomas
Regards
Bernard.
2015-02-02 14:59, Iremonger, Bernard:
> > 2015-02-02 14:11, Iremonger, Bernard:
> > > > --- a/doc/guides/prog_guide/index.rst
> > > > +++ b/doc/guides/prog_guide/index.rst
> > > > @@ -101,18 +96,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(r) DPDK Multi-process
> > > > Sample Application <pg_figure_16>`
> > > >
> > > > :ref:`Figure 17. Components of an Intel(r) DPDK KNI Application
> > > > <pg_figure_17>` diff --git
> > >
> > > References to Figures 9 to 17 have been removed have they been reinstated somewhere else ?
> >
> > Figures 10 to 15 moved in doc/guides/nics/img.
> >
> > I didn't re-create the references in doc/guides/nics/index.rst nor renumbered the ones in
> > doc/guides/prog_guide/index.rst.
>
> It would be better to recreate the references in doc/guides/nics/index.rst rather than just delete them.
> I don't think there is any need to renumber them.
> The references are global across documents and must be unique.
No the references are not really uniques:
- Figures in doc/guides/sample_app_ug/index.rst start from 1 to 17.
- Figures in doc/guides/prog_guide/index.rst start from 1 to 39.
When adding a new new figure in a document, we must renumber them.
> > I think these manual numberings should be removed as it is a pain to update.
> > Actually I don't really understand what is the usage of such references.
> > So I suggest to completely remove them or generate them with a script.
>
> These references were in the original 1.7 MSWord docs.
> When reading a document it enabled the reader to jump to another section
> and jump back, they worked in the HTML docs too.
> I think they should be retained.
Are you speaking about the figure references at the bottom of this page?
http://dpdk.org/doc/guides/prog_guide
It doesn't really help for browsing.
> -----Original Message-----
> From: Thomas Monjalon [mailto:thomas.monjalon@6wind.com]
> Sent: Monday, February 2, 2015 5:12 PM
> To: Iremonger, Bernard
> Cc: dev@dpdk.org; Butler, Siobhan A
> Subject: Re: [RFC PATCH 3/4] doc: nics guide
>
> 2015-02-02 14:59, Iremonger, Bernard:
> > > 2015-02-02 14:11, Iremonger, Bernard:
> > > > > --- a/doc/guides/prog_guide/index.rst
> > > > > +++ b/doc/guides/prog_guide/index.rst
> > > > > @@ -101,18 +96,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(r) DPDK
> > > > > Multi-process Sample Application <pg_figure_16>`
> > > > >
> > > > > :ref:`Figure 17. Components of an Intel(r) DPDK KNI Application
> > > > > <pg_figure_17>` diff --git
> > > >
> > > > References to Figures 9 to 17 have been removed have they been reinstated somewhere else ?
> > >
> > > Figures 10 to 15 moved in doc/guides/nics/img.
> > >
> > > I didn't re-create the references in doc/guides/nics/index.rst nor
> > > renumbered the ones in doc/guides/prog_guide/index.rst.
> >
> > It would be better to recreate the references in doc/guides/nics/index.rst rather than just delete
> them.
> > I don't think there is any need to renumber them.
> > The references are global across documents and must be unique.
>
> No the references are not really uniques:
> - Figures in doc/guides/sample_app_ug/index.rst start from 1 to 17.
> - Figures in doc/guides/prog_guide/index.rst start from 1 to 39.
> When adding a new new figure in a document, we must renumber them.
I had this problem before with duplicate numbers, so in the prog_guide I prefixed the links with "pg_" so the links are unique.
For example:
:ref:`Figure 16. Memory Sharing inthe Intel(r) DPDK Multi-process Sample Application <pg_figure_16>`
> > > I think these manual numberings should be removed as it is a pain to update.
> > > Actually I don't really understand what is the usage of such references.
> > > So I suggest to completely remove them or generate them with a script.
> >
> > These references were in the original 1.7 MSWord docs.
> > When reading a document it enabled the reader to jump to another
> > section and jump back, they worked in the HTML docs too.
> > I think they should be retained.
>
> Are you speaking about the figure references at the bottom of this page?
> http://dpdk.org/doc/guides/prog_guide
> It doesn't really help for browsing.
No, what I mean is that within a document you can jump to another section and back for example:
file:///home/bairemon/git_home/dpdk_master/build/doc/html/guides/prog_guide/mbuf_lib.html
There is link on this page that allows the reader to jump to Mempool Library
file:///home/bairemon/git_home/dpdk_master/build/doc/html/guides/prog_guide/mempool_lib.html#mempool-library
The reader can use the back arrow in the browser to return to the original page.
All of the links are used for this purpose.
>
> --
> Thomas
Regards,
Bernard.
2015-02-02 17:33, Iremonger, Bernard:
> From: Thomas Monjalon [mailto:thomas.monjalon@6wind.com]
> > 2015-02-02 14:59, Iremonger, Bernard:
> > > > 2015-02-02 14:11, Iremonger, Bernard:
> > > > > > --- a/doc/guides/prog_guide/index.rst
> > > > > > +++ b/doc/guides/prog_guide/index.rst
> > > > > > @@ -101,18 +96,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(r) DPDK
> > > > > > Multi-process Sample Application <pg_figure_16>`
> > > > > >
> > > > > > :ref:`Figure 17. Components of an Intel(r) DPDK KNI Application
> > > > > > <pg_figure_17>` diff --git
> > > > >
> > > > > References to Figures 9 to 17 have been removed have they been reinstated somewhere else ?
> > > >
> > > > Figures 10 to 15 moved in doc/guides/nics/img.
> > > >
> > > > I didn't re-create the references in doc/guides/nics/index.rst nor
> > > > renumbered the ones in doc/guides/prog_guide/index.rst.
> > >
> > > It would be better to recreate the references in doc/guides/nics/index.rst rather than just delete them.
> > > I don't think there is any need to renumber them.
> > > The references are global across documents and must be unique.
> >
> > No the references are not really uniques:
> > - Figures in doc/guides/sample_app_ug/index.rst start from 1 to 17.
> > - Figures in doc/guides/prog_guide/index.rst start from 1 to 39.
> > When adding a new new figure in a document, we must renumber them.
>
> I had this problem before with duplicate numbers, so in the prog_guide I prefixed the links with "pg_" so the links are unique.
> For example:
> :ref:`Figure 16. Memory Sharing inthe Intel(r) DPDK Multi-process Sample Application <pg_figure_16>`
OK I understand what is unique.
But I still think that the number in "Figure 16." should be automatically generated.
Or we can remove this Figure/Table list at the bottom of the index.
> > > > I think these manual numberings should be removed as it is a pain to update.
> > > > Actually I don't really understand what is the usage of such references.
> > > > So I suggest to completely remove them or generate them with a script.
> > >
> > > These references were in the original 1.7 MSWord docs.
> > > When reading a document it enabled the reader to jump to another
> > > section and jump back, they worked in the HTML docs too.
> > > I think they should be retained.
> >
> > Are you speaking about the figure references at the bottom of this page?
> > http://dpdk.org/doc/guides/prog_guide
> > It doesn't really help for browsing.
>
> No, what I mean is that within a document you can jump to another section and back for example:
>
> file:///home/bairemon/git_home/dpdk_master/build/doc/html/guides/prog_guide/mbuf_lib.html
> There is link on this page that allows the reader to jump to Mempool Library
> file:///home/bairemon/git_home/dpdk_master/build/doc/html/guides/prog_guide/mempool_lib.html#mempool-library
> The reader can use the back arrow in the browser to return to the original page.
> All of the links are used for this purpose.
OK, it was a misunderstanding. I agree the cross references are useful.
I'm speaking only about the Figure/Table list at the bottom of the index.
> > > > It would be better to recreate the references in doc/guides/nics/index.rst rather than just
> delete them.
> > > > I don't think there is any need to renumber them.
> > > > The references are global across documents and must be unique.
> > >
> > > No the references are not really uniques:
> > > - Figures in doc/guides/sample_app_ug/index.rst start from 1 to 17.
> > > - Figures in doc/guides/prog_guide/index.rst start from 1 to 39.
> > > When adding a new new figure in a document, we must renumber them.
> >
> > I had this problem before with duplicate numbers, so in the prog_guide I prefixed the links with
> "pg_" so the links are unique.
> > For example:
> > :ref:`Figure 16. Memory Sharing inthe Intel(r) DPDK Multi-process
> > Sample Application <pg_figure_16>`
>
> OK I understand what is unique.
> But I still think that the number in "Figure 16." should be automatically generated.
Hi Thomas,
I looked at this before and I do not think there is a way to automatically generate the number
> > > Are you speaking about the figure references at the bottom of this page?
> > > http://dpdk.org/doc/guides/prog_guide
> > > It doesn't really help for browsing.
> >
> > No, what I mean is that within a document you can jump to another section and back for example:
> >
> > file:///home/bairemon/git_home/dpdk_master/build/doc/html/guides/prog_
> > guide/mbuf_lib.html There is link on this page that allows the reader
> > to jump to Mempool Library
> > file:///home/bairemon/git_home/dpdk_master/build/doc/html/guides/prog_
> > guide/mempool_lib.html#mempool-library
> > The reader can use the back arrow in the browser to return to the original page.
> > All of the links are used for this purpose.
>
> OK, it was a misunderstanding. I agree the cross references are useful.
> I'm speaking only about the Figure/Table list at the bottom of the index.
The references were all gathered here in the original 1.7 MSWord documents.
It also useful for testing the links to have them all in one place.
>
> --
> Thomas
Regards,
Bernard.
@@ -190,16 +190,21 @@ 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
F: lib/librte_pmd_ixgbe/
+F: doc/guides/nics/ixgbe.rst
+F: doc/guides/nics/intel_vf.rst
Intel i40e
F: lib/librte_pmd_i40e/
+F: doc/guides/nics/intel_vf.rst
RedHat virtio
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/
@@ -207,15 +212,15 @@ F: doc/guides/sample_app_ug/vhost.rst
VMware vmxnet3
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
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
@@ -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,21 @@
(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
+ virtio
+ vmxnet3
+ pcap_ring
similarity index 100%
rename from doc/guides/prog_guide/i40e_ixgbe_igb_virt_func_drv.rst
rename to doc/guides/nics/intel_vf.rst
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/libpcap_ring_based_poll_mode_drv.rst
rename to doc/guides/nics/pcap_ring.rst
similarity index 100%
rename from doc/guides/prog_guide/poll_mode_drv_emulated_virtio_nic.rst
rename to doc/guides/nics/virtio.rst
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
timer_lib
hash_lib
@@ -101,18 +96,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.