b2cf4835462a2bd2705660c0335691d6817b4c30
[dpdk.git] / doc / guides / prog_guide / poll_mode_drv.rst
1 ..  SPDX-License-Identifier: BSD-3-Clause
2     Copyright(c) 2010-2015 Intel Corporation.
3
4 .. _Poll_Mode_Driver:
5
6 Poll Mode Driver
7 ================
8
9 The DPDK includes 1 Gigabit, 10 Gigabit and 40 Gigabit and para virtualized virtio Poll Mode Drivers.
10
11 A Poll Mode Driver (PMD) consists of APIs, provided through the BSD driver running in user space,
12 to configure the devices and their respective queues.
13 In addition, a PMD accesses the RX and TX descriptors directly without any interrupts
14 (with the exception of Link Status Change interrupts) to quickly receive,
15 process and deliver packets in the user's application.
16 This section describes the requirements of the PMDs,
17 their global design principles and proposes a high-level architecture and a generic external API for the Ethernet PMDs.
18
19 Requirements and Assumptions
20 ----------------------------
21
22 The DPDK environment for packet processing applications allows for two models, run-to-completion and pipe-line:
23
24 *   In the *run-to-completion*  model, a specific port's RX descriptor ring is polled for packets through an API.
25     Packets are then processed on the same core and placed on a port's TX descriptor ring through an API for transmission.
26
27 *   In the *pipe-line*  model, one core polls one or more port's RX descriptor ring through an API.
28     Packets are received and passed to another core via a ring.
29     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.
30
31 In a synchronous run-to-completion model,
32 each logical core assigned to the DPDK executes a packet processing loop that includes the following steps:
33
34 *   Retrieve input packets through the PMD receive API
35
36 *   Process each received packet one at a time, up to its forwarding
37
38 *   Send pending output packets through the PMD transmit API
39
40 Conversely, in an asynchronous pipe-line model, some logical cores may be dedicated to the retrieval of received packets and
41 other logical cores to the processing of previously received packets.
42 Received packets are exchanged between logical cores through rings.
43 The loop for packet retrieval includes the following steps:
44
45 *   Retrieve input packets through the PMD receive API
46
47 *   Provide received packets to processing lcores through packet queues
48
49 The loop for packet processing includes the following steps:
50
51 *   Retrieve the received packet from the packet queue
52
53 *   Process the received packet, up to its retransmission if forwarded
54
55 To avoid any unnecessary interrupt processing overhead, the execution environment must not use any asynchronous notification mechanisms.
56 Whenever needed and appropriate, asynchronous communication should be introduced as much as possible through the use of rings.
57
58 Avoiding lock contention is a key issue in a multi-core environment.
59 To address this issue, PMDs are designed to work with per-core private resources as much as possible.
60 For example, a PMD maintains a separate transmit queue per-core, per-port, if the PMD is not ``DEV_TX_OFFLOAD_MT_LOCKFREE`` capable.
61 In the same way, every receive queue of a port is assigned to and polled by a single logical core (lcore).
62
63 To comply with Non-Uniform Memory Access (NUMA), memory management is designed to assign to each logical core
64 a private buffer pool in local memory to minimize remote memory access.
65 The configuration of packet buffer pools should take into account the underlying physical memory architecture in terms of DIMMS,
66 channels and ranks.
67 The application must ensure that appropriate parameters are given at memory pool creation time.
68 See :ref:`Mempool Library <Mempool_Library>`.
69
70 Design Principles
71 -----------------
72
73 The API and architecture of the Ethernet* PMDs are designed with the following guidelines in mind.
74
75 PMDs must help global policy-oriented decisions to be enforced at the upper application level.
76 Conversely, NIC PMD functions should not impede the benefits expected by upper-level global policies,
77 or worse prevent such policies from being applied.
78
79 For instance, both the receive and transmit functions of a PMD have a maximum number of packets/descriptors to poll.
80 This allows a run-to-completion processing stack to statically fix or
81 to dynamically adapt its overall behavior through different global loop policies, such as:
82
83 *   Receive, process immediately and transmit packets one at a time in a piecemeal fashion.
84
85 *   Receive as many packets as possible, then process all received packets, transmitting them immediately.
86
87 *   Receive a given maximum number of packets, process the received packets, accumulate them and finally send all accumulated packets to transmit.
88
89 To achieve optimal performance, overall software design choices and pure software optimization techniques must be considered and
90 balanced against available low-level hardware-based optimization features (CPU cache properties, bus speed, NIC PCI bandwidth, and so on).
91 The case of packet transmission is an example of this software/hardware tradeoff issue when optimizing burst-oriented network packet processing engines.
92 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.
93 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.
94 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:
95
96 *   Share among multiple packets the un-amortized cost of invoking the rte_eth_tx_one function.
97
98 *   Enable the rte_eth_tx_burst function to take advantage of burst-oriented hardware features (prefetch data in cache, use of NIC head/tail registers)
99     to minimize the number of CPU cycles per packet, for example by avoiding unnecessary read memory accesses to ring transmit descriptors,
100     or by systematically using arrays of pointers that exactly fit cache line boundaries and sizes.
101
102 *   Apply burst-oriented software optimization techniques to remove operations that would otherwise be unavoidable, such as ring index wrap back management.
103
104 Burst-oriented functions are also introduced via the API for services that are intensively used by the PMD.
105 This applies in particular to buffer allocators used to populate NIC rings, which provide functions to allocate/free several buffers at a time.
106 For example, an mbuf_multiple_alloc function returning an array of pointers to rte_mbuf buffers which speeds up the receive poll function of the PMD when
107 replenishing multiple descriptors of the receive ring.
108
109 Logical Cores, Memory and NIC Queues Relationships
110 --------------------------------------------------
111
112 The DPDK supports NUMA allowing for better performance when a processor's logical cores and interfaces utilize its local memory.
113 Therefore, mbuf allocation associated with local PCIe* interfaces should be allocated from memory pools created in the local memory.
114 The buffers should, if possible, remain on the local processor to obtain the best performance results and RX and TX buffer descriptors
115 should be populated with mbufs allocated from a mempool allocated from local memory.
116
117 The run-to-completion model also performs better if packet or data manipulation is in local memory instead of a remote processors memory.
118 This is also true for the pipe-line model provided all logical cores used are located on the same processor.
119
120 Multiple logical cores should never share receive or transmit queues for interfaces since this would require global locks and hinder performance.
121
122 If the PMD is ``DEV_TX_OFFLOAD_MT_LOCKFREE`` capable, multiple threads can invoke ``rte_eth_tx_burst()``
123 concurrently on the same tx queue without SW lock. This PMD feature found in some NICs and useful in the following use cases:
124
125 *  Remove explicit spinlock in some applications where lcores are not mapped to Tx queues with 1:1 relation.
126
127 *  In the eventdev use case, avoid dedicating a separate TX core for transmitting and thus
128    enables more scaling as all workers can send the packets.
129
130 See `Hardware Offload`_ for ``DEV_TX_OFFLOAD_MT_LOCKFREE`` capability probing details.
131
132 Device Identification, Ownership and Configuration
133 --------------------------------------------------
134
135 Device Identification
136 ~~~~~~~~~~~~~~~~~~~~~
137
138 Each NIC port is uniquely designated by its (bus/bridge, device, function) PCI
139 identifiers assigned by the PCI probing/enumeration function executed at DPDK initialization.
140 Based on their PCI identifier, NIC ports are assigned two other identifiers:
141
142 *   A port index used to designate the NIC port in all functions exported by the PMD API.
143
144 *   A port name used to designate the port in console messages, for administration or debugging purposes.
145     For ease of use, the port name includes the port index.
146
147 Port Ownership
148 ~~~~~~~~~~~~~~
149 The Ethernet devices ports can be owned by a single DPDK entity (application, library, PMD, process, etc).
150 The ownership mechanism is controlled by ethdev APIs and allows to set/remove/get a port owner by DPDK entities.
151 Allowing this should prevent any multiple management of Ethernet port by different entities.
152
153 .. note::
154
155     It is the DPDK entity responsibility to set the port owner before using it and to manage the port usage synchronization between different threads or processes.
156
157 Device Configuration
158 ~~~~~~~~~~~~~~~~~~~~
159
160 The configuration of each NIC port includes the following operations:
161
162 *   Allocate PCI resources
163
164 *   Reset the hardware (issue a Global Reset) to a well-known default state
165
166 *   Set up the PHY and the link
167
168 *   Initialize statistics counters
169
170 The PMD API must also export functions to start/stop the all-multicast feature of a port and functions to set/unset the port in promiscuous mode.
171
172 Some hardware offload features must be individually configured at port initialization through specific configuration parameters.
173 This is the case for the Receive Side Scaling (RSS) and Data Center Bridging (DCB) features for example.
174
175 On-the-Fly Configuration
176 ~~~~~~~~~~~~~~~~~~~~~~~~
177
178 All device features that can be started or stopped "on the fly" (that is, without stopping the device) do not require the PMD API to export dedicated functions for this purpose.
179
180 All that is required is the mapping address of the device PCI registers to implement the configuration of these features in specific functions outside of the drivers.
181
182 For this purpose,
183 the PMD API exports a function that provides all the information associated with a device that can be used to set up a given device feature outside of the driver.
184 This includes the PCI vendor identifier, the PCI device identifier, the mapping address of the PCI device registers, and the name of the driver.
185
186 The main advantage of this approach is that it gives complete freedom on the choice of the API used to configure, to start, and to stop such features.
187
188 As an example, refer to the configuration of the IEEE1588 feature for the IntelĀ® 82576 Gigabit Ethernet Controller and
189 the IntelĀ® 82599 10 Gigabit Ethernet Controller controllers in the testpmd application.
190
191 Other features such as the L3/L4 5-Tuple packet filtering feature of a port can be configured in the same way.
192 Ethernet* flow control (pause frame) can be configured on the individual port.
193 Refer to the testpmd source code for details.
194 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.
195
196 Configuration of Transmit Queues
197 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
198
199 Each transmit queue is independently configured with the following information:
200
201 *   The number of descriptors of the transmit ring
202
203 *   The socket identifier used to identify the appropriate DMA memory zone from which to allocate the transmit ring in NUMA architectures
204
205 *   The values of the Prefetch, Host and Write-Back threshold registers of the transmit queue
206
207 *   The *minimum* transmit packets to free threshold (tx_free_thresh).
208     When the number of descriptors used to transmit packets exceeds this threshold, the network adaptor should be checked to see if it has written back descriptors.
209     A value of 0 can be passed during the TX queue configuration to indicate the default value should be used.
210     The default value for tx_free_thresh is 32.
211     This ensures that the PMD does not search for completed descriptors until at least 32 have been processed by the NIC for this queue.
212
213 *   The *minimum*  RS bit threshold. The minimum number of transmit descriptors to use before setting the Report Status (RS) bit in the transmit descriptor.
214     Note that this parameter may only be valid for Intel 10 GbE network adapters.
215     The RS bit is set on the last descriptor used to transmit a packet if the number of descriptors used since the last RS bit setting,
216     up to the first descriptor used to transmit the packet, exceeds the transmit RS bit threshold (tx_rs_thresh).
217     In short, this parameter controls which transmit descriptors are written back to host memory by the network adapter.
218     A value of 0 can be passed during the TX queue configuration to indicate that the default value should be used.
219     The default value for tx_rs_thresh is 32.
220     This ensures that at least 32 descriptors are used before the network adapter writes back the most recently used descriptor.
221     This saves upstream PCIe* bandwidth resulting from TX descriptor write-backs.
222     It is important to note that the TX Write-back threshold (TX wthresh) should be set to 0 when tx_rs_thresh is greater than 1.
223     Refer to the IntelĀ® 82599 10 Gigabit Ethernet Controller Datasheet for more details.
224
225 The following constraints must be satisfied for tx_free_thresh and tx_rs_thresh:
226
227 *   tx_rs_thresh must be greater than 0.
228
229 *   tx_rs_thresh must be less than the size of the ring minus 2.
230
231 *   tx_rs_thresh must be less than or equal to tx_free_thresh.
232
233 *   tx_free_thresh must be greater than 0.
234
235 *   tx_free_thresh must be less than the size of the ring minus 3.
236
237 *   For optimal performance, TX wthresh should be set to 0 when tx_rs_thresh is greater than 1.
238
239 One descriptor in the TX ring is used as a sentinel to avoid a hardware race condition, hence the maximum threshold constraints.
240
241 .. note::
242
243     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.
244
245 Free Tx mbuf on Demand
246 ~~~~~~~~~~~~~~~~~~~~~~
247
248 Many of the drivers do not release the mbuf back to the mempool, or local cache,
249 immediately after the packet has been transmitted.
250 Instead, they leave the mbuf in their Tx ring and
251 either perform a bulk release when the ``tx_rs_thresh`` has been crossed
252 or free the mbuf when a slot in the Tx ring is needed.
253
254 An application can request the driver to release used mbufs with the ``rte_eth_tx_done_cleanup()`` API.
255 This API requests the driver to release mbufs that are no longer in use,
256 independent of whether or not the ``tx_rs_thresh`` has been crossed.
257 There are two scenarios when an application may want the mbuf released immediately:
258
259 * When a given packet needs to be sent to multiple destination interfaces
260   (either for Layer 2 flooding or Layer 3 multi-cast).
261   One option is to make a copy of the packet or a copy of the header portion that needs to be manipulated.
262   A second option is to transmit the packet and then poll the ``rte_eth_tx_done_cleanup()`` API
263   until the reference count on the packet is decremented.
264   Then the same packet can be transmitted to the next destination interface.
265   The application is still responsible for managing any packet manipulations needed
266   between the different destination interfaces, but a packet copy can be avoided.
267   This API is independent of whether the packet was transmitted or dropped,
268   only that the mbuf is no longer in use by the interface.
269
270 * Some applications are designed to make multiple runs, like a packet generator.
271   For performance reasons and consistency between runs,
272   the application may want to reset back to an initial state
273   between each run, where all mbufs are returned to the mempool.
274   In this case, it can call the ``rte_eth_tx_done_cleanup()`` API
275   for each destination interface it has been using
276   to request it to release of all its used mbufs.
277
278 To determine if a driver supports this API, check for the *Free Tx mbuf on demand* feature
279 in the *Network Interface Controller Drivers* document.
280
281 Hardware Offload
282 ~~~~~~~~~~~~~~~~
283
284 Depending on driver capabilities advertised by
285 ``rte_eth_dev_info_get()``, the PMD may support hardware offloading
286 feature like checksumming, TCP segmentation, VLAN insertion or
287 lockfree multithreaded TX burst on the same TX queue.
288
289 The support of these offload features implies the addition of dedicated
290 status bit(s) and value field(s) into the rte_mbuf data structure, along
291 with their appropriate handling by the receive/transmit functions
292 exported by each PMD. The list of flags and their precise meaning is
293 described in the mbuf API documentation and in the in :ref:`Mbuf Library
294 <Mbuf_Library>`, section "Meta Information".
295
296 Per-Port and Per-Queue Offloads
297 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
298
299 In the DPDK offload API, offloads are divided into per-port and per-queue offloads as follows:
300
301 * A per-queue offloading can be enabled on a queue and disabled on another queue at the same time.
302 * A pure per-port offload is the one supported by device but not per-queue type.
303 * A pure per-port offloading can't be enabled on a queue and disabled on another queue at the same time.
304 * A pure per-port offloading must be enabled or disabled on all queues at the same time.
305 * Any offloading is per-queue or pure per-port type, but can't be both types at same devices.
306 * Port capabilities = per-queue capabilities + pure per-port capabilities.
307 * Any supported offloading can be enabled on all queues.
308
309 The different offloads capabilities can be queried using ``rte_eth_dev_info_get()``.
310 The ``dev_info->[rt]x_queue_offload_capa`` returned from ``rte_eth_dev_info_get()`` includes all per-queue offloading capabilities.
311 The ``dev_info->[rt]x_offload_capa`` returned from ``rte_eth_dev_info_get()`` includes all pure per-port and per-queue offloading capabilities.
312 Supported offloads can be either per-port or per-queue.
313
314 Offloads are enabled using the existing ``DEV_TX_OFFLOAD_*`` or ``DEV_RX_OFFLOAD_*`` flags.
315 Any requested offloading by an application must be within the device capabilities.
316 Any offloading is disabled by default if it is not set in the parameter
317 ``dev_conf->[rt]xmode.offloads`` to ``rte_eth_dev_configure()`` and
318 ``[rt]x_conf->offloads`` to ``rte_eth_[rt]x_queue_setup()``.
319
320 If any offloading is enabled in ``rte_eth_dev_configure()`` by an application,
321 it is enabled on all queues no matter whether it is per-queue or
322 per-port type and no matter whether it is set or cleared in
323 ``[rt]x_conf->offloads`` to ``rte_eth_[rt]x_queue_setup()``.
324
325 If a per-queue offloading hasn't been enabled in ``rte_eth_dev_configure()``,
326 it can be enabled or disabled in ``rte_eth_[rt]x_queue_setup()`` for individual queue.
327 A newly added offloads in ``[rt]x_conf->offloads`` to ``rte_eth_[rt]x_queue_setup()`` input by application
328 is the one which hasn't been enabled in ``rte_eth_dev_configure()`` and is requested to be enabled
329 in ``rte_eth_[rt]x_queue_setup()``. It must be per-queue type, otherwise trigger an error log.
330
331 Poll Mode Driver API
332 --------------------
333
334 Generalities
335 ~~~~~~~~~~~~
336
337 By default, all functions exported by a PMD are lock-free functions that are assumed
338 not to be invoked in parallel on different logical cores to work on the same target object.
339 For instance, a PMD receive function cannot be invoked in parallel on two logical cores to poll the same RX queue of the same port.
340 Of course, this function can be invoked in parallel by different logical cores on different RX queues.
341 It is the responsibility of the upper-level application to enforce this rule.
342
343 If needed, parallel accesses by multiple logical cores to shared queues can be explicitly protected by dedicated inline lock-aware functions
344 built on top of their corresponding lock-free functions of the PMD API.
345
346 Generic Packet Representation
347 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
348
349 A packet is represented by an rte_mbuf structure, which is a generic metadata structure containing all necessary housekeeping information.
350 This includes fields and status bits corresponding to offload hardware features, such as checksum computation of IP headers or VLAN tags.
351
352 The rte_mbuf data structure includes specific fields to represent, in a generic way, the offload features provided by network controllers.
353 For an input packet, most fields of the rte_mbuf structure are filled in by the PMD receive function with the information contained in the receive descriptor.
354 Conversely, for output packets, most fields of rte_mbuf structures are used by the PMD transmit function to initialize transmit descriptors.
355
356 The mbuf structure is fully described in the :ref:`Mbuf Library <Mbuf_Library>` chapter.
357
358 Ethernet Device API
359 ~~~~~~~~~~~~~~~~~~~
360
361 The Ethernet device API exported by the Ethernet PMDs is described in the *DPDK API Reference*.
362
363 .. _ethernet_device_standard_device_arguments:
364
365 Ethernet Device Standard Device Arguments
366 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
367
368 Standard Ethernet device arguments allow for a set of commonly used arguments/
369 parameters which are applicable to all Ethernet devices to be available to for
370 specification of specific device and for passing common configuration
371 parameters to those ports.
372
373 * ``representor`` for a device which supports the creation of representor ports
374   this argument allows user to specify which switch ports to enable port
375   representors for.::
376
377    -w BDBF,representor=0
378    -w BDBF,representor=[0,4,6,9]
379    -w BDBF,representor=[0-31]
380
381 Note: PMDs are not required to support the standard device arguments and users
382 should consult the relevant PMD documentation to see support devargs.
383
384 Extended Statistics API
385 ~~~~~~~~~~~~~~~~~~~~~~~
386
387 The extended statistics API allows a PMD to expose all statistics that are
388 available to it, including statistics that are unique to the device.
389 Each statistic has three properties ``name``, ``id`` and ``value``:
390
391 * ``name``: A human readable string formatted by the scheme detailed below.
392 * ``id``: An integer that represents only that statistic.
393 * ``value``: A unsigned 64-bit integer that is the value of the statistic.
394
395 Note that extended statistic identifiers are
396 driver-specific, and hence might not be the same for different ports.
397 The API consists of various ``rte_eth_xstats_*()`` functions, and allows an
398 application to be flexible in how it retrieves statistics.
399
400 Scheme for Human Readable Names
401 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
402
403 A naming scheme exists for the strings exposed to clients of the API. This is
404 to allow scraping of the API for statistics of interest. The naming scheme uses
405 strings split by a single underscore ``_``. The scheme is as follows:
406
407 * direction
408 * detail 1
409 * detail 2
410 * detail n
411 * unit
412
413 Examples of common statistics xstats strings, formatted to comply to the scheme
414 proposed above:
415
416 * ``rx_bytes``
417 * ``rx_crc_errors``
418 * ``tx_multicast_packets``
419
420 The scheme, although quite simple, allows flexibility in presenting and reading
421 information from the statistic strings. The following example illustrates the
422 naming scheme:``rx_packets``. In this example, the string is split into two
423 components. The first component ``rx`` indicates that the statistic is
424 associated with the receive side of the NIC.  The second component ``packets``
425 indicates that the unit of measure is packets.
426
427 A more complicated example: ``tx_size_128_to_255_packets``. In this example,
428 ``tx`` indicates transmission, ``size``  is the first detail, ``128`` etc are
429 more details, and ``packets`` indicates that this is a packet counter.
430
431 Some additions in the metadata scheme are as follows:
432
433 * If the first part does not match ``rx`` or ``tx``, the statistic does not
434   have an affinity with either receive of transmit.
435
436 * If the first letter of the second part is ``q`` and this ``q`` is followed
437   by a number, this statistic is part of a specific queue.
438
439 An example where queue numbers are used is as follows: ``tx_q7_bytes`` which
440 indicates this statistic applies to queue number 7, and represents the number
441 of transmitted bytes on that queue.
442
443 API Design
444 ^^^^^^^^^^
445
446 The xstats API uses the ``name``, ``id``, and ``value`` to allow performant
447 lookup of specific statistics. Performant lookup means two things;
448
449 * No string comparisons with the ``name`` of the statistic in fast-path
450 * Allow requesting of only the statistics of interest
451
452 The API ensures these requirements are met by mapping the ``name`` of the
453 statistic to a unique ``id``, which is used as a key for lookup in the fast-path.
454 The API allows applications to request an array of ``id`` values, so that the
455 PMD only performs the required calculations. Expected usage is that the
456 application scans the ``name`` of each statistic, and caches the ``id``
457 if it has an interest in that statistic. On the fast-path, the integer can be used
458 to retrieve the actual ``value`` of the statistic that the ``id`` represents.
459
460 API Functions
461 ^^^^^^^^^^^^^
462
463 The API is built out of a small number of functions, which can be used to
464 retrieve the number of statistics and the names, IDs and values of those
465 statistics.
466
467 * ``rte_eth_xstats_get_names_by_id()``: returns the names of the statistics. When given a
468   ``NULL`` parameter the function returns the number of statistics that are available.
469
470 * ``rte_eth_xstats_get_id_by_name()``: Searches for the statistic ID that matches
471   ``xstat_name``. If found, the ``id`` integer is set.
472
473 * ``rte_eth_xstats_get_by_id()``: Fills in an array of ``uint64_t`` values
474   with matching the provided ``ids`` array. If the ``ids`` array is NULL, it
475   returns all statistics that are available.
476
477
478 Application Usage
479 ^^^^^^^^^^^^^^^^^
480
481 Imagine an application that wants to view the dropped packet count. If no
482 packets are dropped, the application does not read any other metrics for
483 performance reasons. If packets are dropped, the application has a particular
484 set of statistics that it requests. This "set" of statistics allows the app to
485 decide what next steps to perform. The following code-snippets show how the
486 xstats API can be used to achieve this goal.
487
488 First step is to get all statistics names and list them:
489
490 .. code-block:: c
491
492     struct rte_eth_xstat_name *xstats_names;
493     uint64_t *values;
494     int len, i;
495
496     /* Get number of stats */
497     len = rte_eth_xstats_get_names_by_id(port_id, NULL, NULL, 0);
498     if (len < 0) {
499         printf("Cannot get xstats count\n");
500         goto err;
501     }
502
503     xstats_names = malloc(sizeof(struct rte_eth_xstat_name) * len);
504     if (xstats_names == NULL) {
505         printf("Cannot allocate memory for xstat names\n");
506         goto err;
507     }
508
509     /* Retrieve xstats names, passing NULL for IDs to return all statistics */
510     if (len != rte_eth_xstats_get_names_by_id(port_id, xstats_names, NULL, len)) {
511         printf("Cannot get xstat names\n");
512         goto err;
513     }
514
515     values = malloc(sizeof(values) * len);
516     if (values == NULL) {
517         printf("Cannot allocate memory for xstats\n");
518         goto err;
519     }
520
521     /* Getting xstats values */
522     if (len != rte_eth_xstats_get_by_id(port_id, NULL, values, len)) {
523         printf("Cannot get xstat values\n");
524         goto err;
525     }
526
527     /* Print all xstats names and values */
528     for (i = 0; i < len; i++) {
529         printf("%s: %"PRIu64"\n", xstats_names[i].name, values[i]);
530     }
531
532 The application has access to the names of all of the statistics that the PMD
533 exposes. The application can decide which statistics are of interest, cache the
534 ids of those statistics by looking up the name as follows:
535
536 .. code-block:: c
537
538     uint64_t id;
539     uint64_t value;
540     const char *xstat_name = "rx_errors";
541
542     if(!rte_eth_xstats_get_id_by_name(port_id, xstat_name, &id)) {
543         rte_eth_xstats_get_by_id(port_id, &id, &value, 1);
544         printf("%s: %"PRIu64"\n", xstat_name, value);
545     }
546     else {
547         printf("Cannot find xstats with a given name\n");
548         goto err;
549     }
550
551 The API provides flexibility to the application so that it can look up multiple
552 statistics using an array containing multiple ``id`` numbers. This reduces the
553 function call overhead of retrieving statistics, and makes lookup of multiple
554 statistics simpler for the application.
555
556 .. code-block:: c
557
558     #define APP_NUM_STATS 4
559     /* application cached these ids previously; see above */
560     uint64_t ids_array[APP_NUM_STATS] = {3,4,7,21};
561     uint64_t value_array[APP_NUM_STATS];
562
563     /* Getting multiple xstats values from array of IDs */
564     rte_eth_xstats_get_by_id(port_id, ids_array, value_array, APP_NUM_STATS);
565
566     uint32_t i;
567     for(i = 0; i < APP_NUM_STATS; i++) {
568         printf("%d: %"PRIu64"\n", ids_array[i], value_array[i]);
569     }
570
571
572 This array lookup API for xstats allows the application create multiple
573 "groups" of statistics, and look up the values of those IDs using a single API
574 call. As an end result, the application is able to achieve its goal of
575 monitoring a single statistic ("rx_errors" in this case), and if that shows
576 packets being dropped, it can easily retrieve a "set" of statistics using the
577 IDs array parameter to ``rte_eth_xstats_get_by_id`` function.
578
579 NIC Reset API
580 ~~~~~~~~~~~~~
581
582 .. code-block:: c
583
584     int rte_eth_dev_reset(uint16_t port_id);
585
586 Sometimes a port has to be reset passively. For example when a PF is
587 reset, all its VFs should also be reset by the application to make them
588 consistent with the PF. A DPDK application also can call this function
589 to trigger a port reset. Normally, a DPDK application would invokes this
590 function when an RTE_ETH_EVENT_INTR_RESET event is detected.
591
592 It is the duty of the PMD to trigger RTE_ETH_EVENT_INTR_RESET events and
593 the application should register a callback function to handle these
594 events. When a PMD needs to trigger a reset, it can trigger an
595 RTE_ETH_EVENT_INTR_RESET event. On receiving an RTE_ETH_EVENT_INTR_RESET
596 event, applications can handle it as follows: Stop working queues, stop
597 calling Rx and Tx functions, and then call rte_eth_dev_reset(). For
598 thread safety all these operations should be called from the same thread.
599
600 For example when PF is reset, the PF sends a message to notify VFs of
601 this event and also trigger an interrupt to VFs. Then in the interrupt
602 service routine the VFs detects this notification message and calls
603 _rte_eth_dev_callback_process(dev, RTE_ETH_EVENT_INTR_RESET, NULL).
604 This means that a PF reset triggers an RTE_ETH_EVENT_INTR_RESET
605 event within VFs. The function _rte_eth_dev_callback_process() will
606 call the registered callback function. The callback function can trigger
607 the application to handle all operations the VF reset requires including
608 stopping Rx/Tx queues and calling rte_eth_dev_reset().
609
610 The rte_eth_dev_reset() itself is a generic function which only does
611 some hardware reset operations through calling dev_unint() and
612 dev_init(), and itself does not handle synchronization, which is handled
613 by application.
614
615 The PMD itself should not call rte_eth_dev_reset(). The PMD can trigger
616 the application to handle reset event. It is duty of application to
617 handle all synchronization before it calls rte_eth_dev_reset().