.. BSD LICENSE
- Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
+ Copyright(c) 2010-2015 Intel Corporation. All rights reserved.
All rights reserved.
Redistribution and use in source and binary forms, with or without
Poll Mode Driver
================
-The Intel® DPDK includes 1 Gigabit, 10 Gigabit and 40 Gigabit and para virtualized virtio Poll Mode Drivers.
+The DPDK includes 1 Gigabit, 10 Gigabit and 40 Gigabit and para virtualized virtio Poll Mode Drivers.
A Poll Mode Driver (PMD) consists of APIs, provided through the BSD driver running in user space,
to configure the devices and their respective queues.
Requirements and Assumptions
----------------------------
-The Intel® DPDK environment for packet processing applications allows for two models, run-to-completion and pipe-line:
+The DPDK environment for packet processing applications allows for two models, run-to-completion and pipe-line:
* In the *run-to-completion* model, a specific port's RX descriptor ring is polled for packets through an API.
Packets are then processed on the same core and placed on a port's TX descriptor ring through an API for transmission.
The other core continues to process the packet which then may be placed on a port's TX descriptor ring through an API for transmission.
In a synchronous run-to-completion model,
-each logical core assigned to the Intel® DPDK executes a packet processing loop that includes the following steps:
+each logical core assigned to the DPDK executes a packet processing loop that includes the following steps:
* Retrieve input packets through the PMD receive API
To achieve optimal performance, overall software design choices and pure software optimization techniques must be considered and
balanced against available low-level hardware-based optimization features (CPU cache properties, bus speed, NIC PCI bandwidth, and so on).
-The case of packet transmission is an example of this software/ hardware tradeoff issue when optimizing burst-oriented network packet processing engines.
+The case of packet transmission is an example of this software/hardware tradeoff issue when optimizing burst-oriented network packet processing engines.
In the initial case, the PMD could export only an rte_eth_tx_one function to transmit one packet at a time on a given queue.
On top of that, one can easily build an rte_eth_tx_burst function that loops invoking the rte_eth_tx_one function to transmit several packets at a time.
However, an rte_eth_tx_burst function is effectively implemented by the PMD to minimize the driver-level transmit cost per packet through the following optimizations:
Logical Cores, Memory and NIC Queues Relationships
--------------------------------------------------
-The Intel® DPDK supports NUMA allowing for better performance when a processor's logical cores and interfaces utilize its local memory.
+The DPDK supports NUMA allowing for better performance when a processor's logical cores and interfaces utilize its local memory.
Therefore, mbuf allocation associated with local PCIe* interfaces should be allocated from memory pools created in the local memory.
The buffers should, if possible, remain on the local processor to obtain the best performance results and RX and TX buffer descriptors
should be populated with mbufs allocated from a mempool allocated from local memory.
~~~~~~~~~~~~~~~~~~~~~
Each NIC port is uniquely designated by its (bus/bridge, device, function) PCI
-identifiers assigned by the PCI probing/enumeration function executed at Intel® DPDK initialization.
+identifiers assigned by the PCI probing/enumeration function executed at DPDK initialization.
Based on their PCI identifier, NIC ports are assigned two other identifiers:
* A port index used to designate the NIC port in all functions exported by the PMD API.
Other features such as the L3/L4 5-Tuple packet filtering feature of a port can be configured in the same way.
Ethernet* flow control (pause frame) can be configured on the individual port.
Refer to the testpmd source code for details.
-Also, L4 (UDP/TCP/ SCTP) checksum offload by the NIC can be enabled for an individual packet as long as the packet mbuf is set up correctly.
-Refer to the testpmd source code (specifically the csumonly.c file) for details.
-
-That being said, the support of some offload features implies the addition of dedicated status bit(s) and value field(s) into the rte_mbuf
-data structure, along with their appropriate handling by the receive/transmit functions exported by each PMD.
-
-For instance, this is the case for the IEEE1588 packet timestamp mechanism, the VLAN tagging and the IP checksum computation, as described in
-the Section 7.6 "Meta Information".
+Also, L4 (UDP/TCP/ SCTP) checksum offload by the NIC can be enabled for an individual packet as long as the packet mbuf is set up correctly. See `Hardware Offload`_ for details.
Configuration of Transmit and Receive Queues
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When configuring for DCB operation, at port initialization, both the number of transmit queues and the number of receive queues must be set to 128.
+Hardware Offload
+~~~~~~~~~~~~~~~~
+
+Depending on driver capabilities advertised by
+``rte_eth_dev_info_get()``, the PMD may support hardware offloading
+feature like checksumming, TCP segmentation or VLAN insertion.
+
+The support of these offload features implies the addition of dedicated
+status bit(s) and value field(s) into the rte_mbuf data structure, along
+with their appropriate handling by the receive/transmit functions
+exported by each PMD. The list of flags and their precise meaning is
+described in the mbuf API documentation and in the in :ref:`Mbuf Library
+<Mbuf_Library>`, section "Meta Information".
+
Poll Mode Driver API
--------------------
Ethernet Device API
~~~~~~~~~~~~~~~~~~~
-The Ethernet device API exported by the Ethernet PMDs is described in the *Intel® 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
-~~~~~~~~~~~~~~~~~~~~~~~~
+The Ethernet device API exported by the Ethernet PMDs is described in the *DPDK API Reference*.
-testpmd
-^^^^^^^
+Extended Statistics API
+~~~~~~~~~~~~~~~~~~~~~~~
-By default, using CONFIG_RTE_IXGBE_RX_OLFLAGS_DISABLE=n:
+The extended statistics API allows each individual PMD to expose a unique set
+of statistics. The client of the API provides an array of
+``struct rte_eth_xstats`` type. Each ``struct rte_eth_xstats`` contains a
+string and value pair. The amount of xstats exposed, and position of the
+statistic in the array must remain constant during runtime.
-.. code-block:: console
+A naming scheme exists for the strings exposed to clients of the API. This is
+to allow scraping of the API for statistics of interest. The naming scheme uses
+strings split by a single underscore ``_``. The scheme is as follows:
- ./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
+* direction
+* detail 1
+* detail 2
+* detail n
+* unit
-When CONFIG_RTE_IXGBE_RX_OLFLAGS_DISABLE=y, better performance can be achieved:
+Examples of common statistics xstats strings, formatted to comply to the scheme
+proposed above:
-.. code-block:: console
+* ``rx_bytes``
+* ``rx_crc_errors``
+* ``tx_multicast_packets``
- ./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
+The scheme, although quite simple, allows flexibility in presenting and reading
+information from the statistic strings. The following example illustrates the
+naming scheme:``rx_packets``. In this example, the string is split into two
+components. The first component ``rx`` indicates that the statistic is
+associated with the receive side of the NIC. The second component ``packets``
+indicates that the unit of measure is packets.
-If scatter gather lists are not required, set CONFIG_RTE_MBUF_SCATTER_GATHER=n for better throughput.
+A more complicated example: ``tx_size_128_to_255_packets``. In this example,
+``tx`` indicates transmission, ``size`` is the first detail, ``128`` etc are
+more details, and ``packets`` indicates that this is a packet counter.
-l3fwd
-^^^^^
+Some additions in the metadata scheme are as follows:
-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.
+* If the first part does not match ``rx`` or ``tx``, the statistic does not
+ have an affinity with either receive of transmit.
-load_balancer
-^^^^^^^^^^^^^
+* If the first letter of the second part is ``q`` and this ``q`` is followed
+ by a number, this statistic is part of a specific queue.
-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.
+An example where queue numbers are used is as follows: ``tx_q7_bytes`` which
+indicates this statistic applies to queue number 7, and represents the number
+of transmitted bytes on that queue.
git.droids-corp.org / dpdk.git / blobdiff