doc/guides/nics/bnxt.rst

   1 .. SPDX-License-Identifier: BSD-3-Clause
   2    Copyright 2020 Broadcom Inc.
   3
   4 BNXT Poll Mode Driver
   5 =====================
   6
   7 The Broadcom BNXT PMD (**librte_pmd_bnxt**) implements support for adapters
   8 based on Ethernet controllers and SoCs belonging to the Broadcom
   9 BCM574XX/BCM575XX NetXtreme-E® Family of Ethernet Network Controllers,
  10 the Broadcom BCM588XX Stingray Family of Smart NIC Adapters, and the Broadcom
  11 StrataGX® BCM5873X Series of Communications Processors.
  12
  13 A complete list with links to reference material is in the Appendix section.
  14
  15 CPU Support
  16 -----------
  17
  18 BNXT PMD supports multiple CPU architectures, including x86-32, x86-64, and ARMv8.
  19
  20 Kernel Dependency
  21 -----------------
  22
  23 BNXT PMD requires a kernel module (VFIO or UIO) for setting up a device, mapping
  24 device memory to userspace, registering interrupts, etc.
  25 VFIO is more secure than UIO, relying on IOMMU protection.
  26 UIO requires the IOMMU disabled or configured to pass-through mode.
  27
  28 Operating Systems supported:
  29
  30 * Red Hat Enterprise Linux release 8.1 (Ootpa)
  31 * Red Hat Enterprise Linux release 8.0 (Ootpa)
  32 * Red Hat Enterprise Linux Server release 7.7 (Maipo)
  33 * Red Hat Enterprise Linux Server release 7.6 (Maipo)
  34 * Red Hat Enterprise Linux Server release 7.5 (Maipo)
  35 * Red Hat Enterprise Linux Server release 7.4 (Maipo)
  36 * Red Hat Enterprise Linux Server release 7.3 (Maipo)
  37 * Red Hat Enterprise Linux Server release 7.2 (Maipo)
  38 * CentOS Linux release 8.0
  39 * CentOS Linux release 7.7
  40 * CentOS Linux release 7.6.1810
  41 * CentOS Linux release 7.5.1804
  42 * CentOS Linux release 7.4.1708
  43 * Fedora 31
  44 * FreeBSD 12.1
  45 * Suse 15SP1
  46 * Ubuntu 19.04
  47 * Ubuntu 18.04
  48 * Ubuntu 16.10
  49 * Ubuntu 16.04
  50 * Ubuntu 14.04
  51
  52 The BNXT PMD supports operating with:
  53
  54 * Linux vfio-pci
  55 * Linux uio_pci_generic
  56 * Linux igb_uio
  57 * BSD nic_uio
  58
  59 Compiling BNXT PMD
  60 ------------------
  61
  62 To compile the BNXT PMD:
  63
  64 .. code-block:: console
  65
  66     make config T=x86_64-native-linux-gcc && make // for x86-64
  67     make config T=x86_32-native-linux-gcc && make // for x86-32
  68     make config T=armv8a-linux-gcc && make // for ARMv8
  69
  70 Bind the device to one of the kernel modules listed above
  71
  72 .. code-block:: console
  73
  74     ./dpdk-devbind.py -b vfio-pci|igb_uio|uio_pci_generic bus_id:device_id.function_id
  75
  76 Load an application (e.g. testpmd) with a default configuration (e.g. a single
  77 TX /RX queue):
  78
  79 .. code-block:: console
  80
  81     ./testpmd -c 0xF -n 4 -- -i --portmask=0x1 --nb-cores=2
  82
  83 Running BNXT PMD
  84 ----------------
  85
  86 The BNXT PMD can run on PF or VF.
  87
  88 PCI-SIG Single Root I/O Virtualization (SR-IOV) involves the direct assignment
  89 of part of the network port resources to guest operating systems using the
  90 SR-IOV standard.
  91 NIC is logically distributed among multiple virtual machines (VMs), while still
  92 having global data in common to share with the PF and other VFs.
  93
  94 Sysadmin can create and configure VFs:
  95
  96 .. code-block:: console
  97
  98   echo num_vfs > /sys/bus/pci/devices/domain_id:bus_id:device_id:function_id/sriov_numvfs
  99   (ex) echo 4 > /sys/bus/pci/devices/0000:82:00:0/sriov_numvfs
 100
 101 Sysadmin also can change the VF property such as MAC address, transparent VLAN,
 102 TX rate limit, and trusted VF:
 103
 104 .. code-block:: console
 105
 106   ip link set pf_id vf vf_id mac (mac_address) vlan (vlan_id) txrate (rate_value) trust (enable|disable)
 107   (ex) ip link set 0 vf 0 mac 00:11:22:33:44:55 vlan 0x100 txrate 100 trust disable
 108
 109 Running on VF
 110 ~~~~~~~~~~~~~
 111
 112 Flow Bifurcation
 113 ^^^^^^^^^^^^^^^^
 114
 115 The Flow Bifurcation splits the incoming data traffic to user space applications
 116 (such as DPDK applications) and/or kernel space programs (such as the Linux
 117 kernel stack).
 118 It can direct some traffic, for example data plane traffic, to DPDK.
 119 Rest of the traffic, for example control plane traffic, would be redirected to
 120 the traditional Linux networking stack.
 121
 122 Refer to https://doc.dpdk.org/guides/howto/flow_bifurcation.html
 123
 124 Benefits of the flow bifurcation include:
 125
 126 * Better performance with less CPU overhead, as user application can directly
 127   access the NIC for data path
 128 * NIC is still being controlled by the kernel, as control traffic is forwarded
 129   only to the kernel driver
 130 * Control commands, e.g. ethtool, will work as usual
 131
 132 Running on a VF, the BXNT PMD supports the flow bifurcation with a combination
 133 of SR-IOV and packet classification and/or forwarding capability.
 134 In the simplest case of flow bifurcation, a PF driver configures a NIC to
 135 forward all user traffic directly to VFs with matching destination MAC address,
 136 while the rest of the traffic is forwarded to a PF.
 137 Note that the broadcast packets will be forwarded to both PF and VF.
 138
 139 .. code-block:: console
 140
 141     (ex) ethtool --config-ntuple ens2f0 flow-type ether dst 00:01:02:03:00:01 vlan 10 vlan-mask 0xf000 action 0x100000000
 142
 143 Trusted VF
 144 ^^^^^^^^^^
 145
 146 By default, VFs are *not* allowed to perform privileged operations, such as
 147 modifying the VF’s MAC address in the guest. These security measures are
 148 designed to prevent possible attacks.
 149 However, when a DPDK application can be trusted (e.g., OVS-DPDK, here), these
 150 operations performed by a VF would be legitimate and can be allowed.
 151
 152 To enable VF to request "trusted mode," a new trusted VF concept was introduced
 153 in Linux kernel 4.4 and allowed VFs to become “trusted” and perform some
 154 privileged operations.
 155
 156 The BNXT PMD supports the trusted VF mode of operation. Only a PF can enable the
 157 trusted attribute on the VF. It is preferable to enable the Trusted setting on a
 158 VF before starting applications.
 159 However, the BNXT PMD handles dynamic changes in trusted settings as well.
 160
 161 Note that control commands, e.g., ethtool, will work via the kernel PF driver,
 162 *not* via the trusted VF driver.
 163
 164 Operations supported by trusted VF:
 165
 166 * MAC address configuration
 167 * Flow rule creation
 168
 169 Operations *not* supported by trusted VF:
 170
 171 * Firmware upgrade
 172 * Promiscuous mode setting
 173
 174 Running on PF
 175 ~~~~~~~~~~~~~
 176
 177 Unlike the VF when BNXT PMD runs on a PF there are no restrictions placed on the
 178 features which the PF can enable or request. In a multiport NIC, each port will
 179 have a corresponding PF. Also depending on the configuration of the NIC there
 180 can be more than one PF associated per port.
 181 A sysadmin can load the kernel driver on one PF, and run BNXT PMD on the other
 182 PF or run the PMD on both the PFs. In such cases, the firmware picks one of the
 183 PFs as a master PF.
 184
 185 Much like in the trusted VF, the DPDK application must be *trusted* and expected
 186 to be *well-behaved*.
 187
 188 Features
 189 --------
 190
 191 The BNXT PMD supports the following features:
 192
 193 * Port Control
 194     * Port MTU
 195     * LED
 196     * Flow Control and Autoneg
 197 * Packet Filtering
 198     * Unicast MAC Filter
 199     * Multicast MAC Filter
 200     * VLAN Filtering
 201     * Allmulticast Mode
 202     * Promiscuous Mode
 203 * Stateless Offloads
 204     * CRC Offload
 205     * Checksum Offload (IPv4, TCP, and UDP)
 206     * Multi-Queue (TSS and RSS)
 207     * Segmentation and Reassembly (TSO and LRO)
 208 * VLAN insert strip
 209 * Stats Collection
 210 * Generic Flow Offload
 211
 212 Port Control
 213 ~~~~~~~~~~~~
 214
 215 **Port MTU**: BNXT PMD supports the MTU (Maximum Transmission Unit) up to 9,574
 216 bytes:
 217
 218 .. code-block:: console
 219
 220     testpmd> port config mtu (port_id) mtu_value
 221     testpmd> show port info (port_id)
 222
 223 **LED**: Application tunes on (or off) a port LED, typically for a port
 224 identification:
 225
 226 .. code-block:: console
 227
 228     int rte_eth_led_on (uint16_t port_id)
 229     int rte_eth_led_off (uint16_t port_id)
 230
 231 **Flow Control and Autoneg**: Application tunes on (or off) flow control and/or
 232 auto-negotiation on a port:
 233
 234 .. code-block:: console
 235
 236     testpmd> set flow_ctrl rx (on|off) (port_id)
 237     testpmd> set flow_ctrl tx (on|off) (port_id)
 238     testpmd> set flow_ctrl autoneg (on|off) (port_id)
 239
 240 Note that the BNXT PMD does *not* support some options and ignores them when
 241 requested:
 242
 243 * high_water
 244 * low_water
 245 * pause_time
 246 * mac_ctrl_frame_fwd
 247 * send_xon
 248
 249 Packet Filtering
 250 ~~~~~~~~~~~~~~~~
 251
 252 Applications control the packet-forwarding behaviors with packet filters.
 253
 254 The BNXT PMD supports hardware-based packet filtering:
 255
 256 * UC (Unicast) MAC Filters
 257     * No unicast packets are forwarded to an application except the one with
 258       DMAC address added to the port
 259     * At initialization, the station MAC address is added to the port
 260 * MC (Multicast) MAC Filters
 261     * No multicast packets are forwarded to an application except the one with
 262       MC address added to the port
 263     * When the application listens to a multicast group, it adds the MC address
 264       to the port
 265 * VLAN Filtering Mode
 266     * When enabled, no packets are forwarded to an application except the ones
 267       with the VLAN tag assigned to the port
 268 * Allmulticast Mode
 269     * When enabled, every multicast packet received on the port is forwarded to
 270       the application
 271     * Typical usage is routing applications
 272 * Promiscuous Mode
 273     * When enabled, every packet received on the port is forwarded to the
 274       application
 275
 276 Unicast MAC Filter
 277 ^^^^^^^^^^^^^^^^^^
 278
 279 The application adds (or removes) MAC addresses to enable (or disable)
 280 whitelist filtering to accept packets.
 281
 282 .. code-block:: console
 283
 284     testpmd> show port (port_id) macs
 285     testpmd> mac_addr (add|remove) (port_id) (XX:XX:XX:XX:XX:XX)
 286
 287 Multicast MAC Filter
 288 ^^^^^^^^^^^^^^^^^^^^
 289
 290 Application adds (or removes) Multicast addresses to enable (or disable)
 291 whitelist filtering to accept packets.
 292
 293 .. code-block:: console
 294
 295     testpmd> show port (port_id) mcast_macs
 296     testpmd> mcast_addr (add|remove) (port_id) (XX:XX:XX:XX:XX:XX)
 297
 298 Application adds (or removes) Multicast addresses to enable (or disable)
 299 whitelist filtering to accept packets.
 300
 301 Note that the BNXT PMD supports up to 16 MC MAC filters. if the user adds more
 302 than 16 MC MACs, the BNXT PMD puts the port into the Allmulticast mode.
 303
 304 VLAN Filtering
 305 ^^^^^^^^^^^^^^
 306
 307 The application enables (or disables) VLAN filtering mode. When the mode is
 308 enabled, no packets are forwarded to an application except ones with VLAN tag
 309 assigned for the application.
 310
 311 .. code-block:: console
 312
 313     testpmd> vlan set filter (on|off) (port_id)
 314     testpmd> rx_vlan (add|rm) (vlan_id) (port_id)
 315
 316 Allmulticast Mode
 317 ^^^^^^^^^^^^^^^^^
 318
 319 The application enables (or disables) the allmulticast mode. When the mode is
 320 enabled, every multicast packet received is forwarded to the application.
 321
 322 .. code-block:: console
 323
 324     testpmd> show port info (port_id)
 325     testpmd> set allmulti (port_id) (on|off)
 326
 327 Promiscuous Mode
 328 ^^^^^^^^^^^^^^^^
 329
 330 The application enables (or disables) the promiscuous mode. When the mode is
 331 enabled on a port, every packet received on the port is forwarded to the
 332 application.
 333
 334 .. code-block:: console
 335
 336     testpmd> show port info (port_id)
 337     testpmd> set promisc port_id (on|off)
 338
 339 Stateless Offloads
 340 ~~~~~~~~~~~~~~~~~~
 341
 342 Like Linux, DPDK provides enabling hardware offload of some stateless processing
 343 (such as checksum calculation) of the stack, alleviating the CPU from having to
 344 burn cycles on every packet.
 345
 346 Listed below are the stateless offloads supported by the BNXT PMD:
 347
 348 * CRC offload (for both TX and RX packets)
 349 * Checksum Offload (for both TX and RX packets)
 350     * IPv4 Checksum Offload
 351     * TCP Checksum Offload
 352     * UDP Checksum Offload
 353 * Segmentation/Reassembly Offloads
 354     * TCP Segmentation Offload (TSO)
 355     * Large Receive Offload (LRO)
 356 * Multi-Queue
 357     * Transmit Side Scaling (TSS)
 358     * Receive Side Scaling (RSS)
 359
 360 Also, the BNXT PMD supports stateless offloads on inner frames for tunneled
 361 packets. Listed below are the tunneling protocols supported by the BNXT PMD:
 362
 363 * VXLAN
 364 * GRE
 365 * NVGRE
 366
 367 Note that enabling (or disabling) stateless offloads requires applications to
 368 stop DPDK before changing configuration.
 369
 370 CRC Offload
 371 ^^^^^^^^^^^
 372
 373 The FCS (Frame Check Sequence) in the Ethernet frame is a four-octet CRC (Cyclic
 374 Redundancy Check) that allows detection of corrupted data within the entire
 375 frame as received on the receiver side.
 376
 377 The BNXT PMD supports hardware-based CRC offload:
 378
 379 * TX: calculate and insert CRC
 380 * RX: check and remove CRC, notify the application on CRC error
 381
 382 Note that the CRC offload is always turned on.
 383
 384 Checksum Offload
 385 ^^^^^^^^^^^^^^^^
 386
 387 The application enables hardware checksum calculation for IPv4, TCP, and UDP.
 388
 389 .. code-block:: console
 390
 391     testpmd> port stop (port_id)
 392     testpmd> csum set (ip|tcp|udp|outer-ip|outer-udp) (sw|hw) (port_id)
 393     testpmd> set fwd csum
 394
 395 Multi-Queue
 396 ^^^^^^^^^^^
 397
 398 Multi-Queue, also known as TSS (Transmit Side Scaling) or RSS (Receive Side
 399 Scaling), is a common networking technique that allows for more efficient load
 400 balancing across multiple CPU cores.
 401
 402 The application enables multiple TX and RX queues when it is started.
 403
 404 .. code-block:: console
 405
 406     testpmd -l 1,3,5 --master-lcore 1 --txq=2 –rxq=2 --nb-cores=2
 407
 408 **TSS**
 409
 410 TSS distributes network transmit processing across several hardware-based
 411 transmit queues, allowing outbound network traffic to be processed by multiple
 412 CPU cores.
 413
 414 **RSS**
 415
 416 RSS distributes network receive processing across several hardware-based receive
 417 queues, allowing inbound network traffic to be processed by multiple CPU cores.
 418
 419 The application can select the RSS mode, i.e. select the header fields that are
 420 included for hash calculation. The BNXT PMD supports the RSS mode of
 421 ``default|ip|tcp|udp|none``, where default mode is L3 and L4.
 422
 423 For tunneled packets, RSS hash is calculated over inner frame header fields.
 424 Applications may want to select the tunnel header fields for hash calculation,
 425 and it will be supported in 20.08 using RSS level.
 426
 427 .. code-block:: console
 428
 429     testpmd> port config (port_id) rss (all|default|ip|tcp|udp|none)
 430
 431     // note that the testpmd defaults the RSS mode to ip
 432     // ensure to issue the command below to enable L4 header (TCP or UDP) along with IPv4 header
 433     testpmd> port config (port_id) rss default
 434
 435     // to check the current RSS configuration, such as RSS function and RSS key
 436     testpmd> show port (port_id) rss-hash key
 437
 438     // RSS is enabled by default. However, application can disable RSS as follows
 439     testpmd> port config (port_id) rss none
 440
 441 Application can change the flow distribution, i.e. remap the received traffic to
 442 CPU cores, using RSS RETA (Redirection Table).
 443
 444 .. code-block:: console
 445
 446     // application queries the current RSS RETA configuration
 447     testpmd> show port (port_id) rss reta size (mask0, mask1)
 448
 449     // application changes the RSS RETA configuration
 450     testpmd> port config (port_id) rss reta (hash, queue) [, (hash, queue)]
 451
 452 TSO
 453 ^^^
 454
 455 TSO (TCP Segmentation Offload), also known as LSO (Large Send Offload), enables
 456 the TCP/IP stack to pass to the NIC a larger datagram than the MTU (Maximum
 457 Transmit Unit). NIC breaks it into multiple segments before sending it to the
 458 network.
 459
 460 The BNXT PMD supports hardware-based TSO.
 461
 462 .. code-block:: console
 463
 464     // display the status of TSO
 465     testpmd> tso show (port_id)
 466
 467     // enable/disable TSO
 468     testpmd> port config (port_id) tx_offload tcp_tso (on|off)
 469
 470     // set TSO segment size
 471     testpmd> tso set segment_size (port_id)
 472
 473 The BNXT PMD also supports hardware-based tunneled TSO.
 474
 475 .. code-block:: console
 476
 477     // display the status of tunneled TSO
 478     testpmd> tunnel_tso show (port_id)
 479
 480     // enable/disable tunneled TSO
 481     testpmd> port config (port_id) tx_offload vxlan_tnl_tso|gre_tnl_tso (on|off)
 482
 483     // set tunneled TSO segment size
 484     testpmd> tunnel_tso set segment_size (port_id)
 485
 486 Note that the checksum offload is always assumed to be enabled for TSO.
 487
 488 LRO
 489 ^^^
 490
 491 LRO (Large Receive Offload) enables NIC to aggregate multiple incoming TCP/IP
 492 packets from a single stream into a larger buffer, before passing to the
 493 networking stack.
 494
 495 The BNXT PMD supports hardware-based LRO.
 496
 497 .. code-block:: console
 498
 499     // display the status of LRO
 500     testpmd> show port (port_id) rx_offload capabilities
 501     testpmd> show port (port_id) rx_offload configuration
 502
 503     // enable/disable LRO
 504     testpmd> port config (port_id) rx_offload tcp_lro (on|off)
 505
 506     // set max LRO packet (datagram) size
 507     testpmd> port config (port_id) max-lro-pkt-size (max_size)
 508
 509 The BNXT PMD also supports tunneled LRO.
 510
 511 Some applications, such as routing, should *not* change the packet headers as
 512 they pass through (i.e. received from and sent back to the network). In such a
 513 case, GRO (Generic Receive Offload) should be used instead of LRO.
 514
 515 VLAN Insert/Strip
 516 ~~~~~~~~~~~~~~~~~
 517
 518 DPDK application offloads VLAN insert/strip to improve performance. The BNXT PMD
 519 supports hardware-based VLAN insert/strip offload for both single and double
 520 VLAN packets.
 521
 522
 523 VLAN Insert
 524 ^^^^^^^^^^^
 525
 526 Application configures the VLAN TPID (Tag Protocol ID). By default, the TPID is
 527 0x8100.
 528
 529 .. code-block:: console
 530
 531     // configure outer TPID value for a port
 532     testpmd> vlan set outer tpid (tpid_value) (port_id)
 533
 534 The inner TPID set will be rejected as the BNXT PMD supports inserting only an
 535 outer VLAN. Note that when a packet has a single VLAN, the tag is considered as
 536 outer, i.e. the inner VLAN is relevant only when a packet is double-tagged.
 537
 538 The BNXT PMD supports various TPID values shown below. Any other values will be
 539 rejected.
 540
 541 * ``0x8100``
 542 * ``0x88a8``
 543 * ``0x9100``
 544 * ``0x9200``
 545 * ``0x9300``
 546
 547 The BNXT PMD supports the VLAN insert offload per-packet basis. The application
 548 provides the TCI (Tag Control Info) for a packet via mbuf. In turn, the BNXT PMD
 549 inserts the VLAN tag (via hardware) using the provided TCI along with the
 550 configured TPID.
 551
 552 .. code-block:: console
 553
 554     // enable VLAN insert offload
 555     testpmd> port config (port_id) rx_offload vlan_insert|qinq_insert (on|off)
 556
 557     if (mbuf->ol_flags && PKT_TX_QINQ)       // case-1: insert VLAN to single-tagged packet
 558         tci_value = mbuf->vlan_tci_outer
 559     else if (mbuf->ol_flags && PKT_TX_VLAN)  // case-2: insert VLAN to untagged packet
 560         tci_value = mbuf->vlan_tci
 561
 562 VLAN Strip
 563 ^^^^^^^^^^
 564
 565 The application configures the per-port VLAN strip offload.
 566
 567 .. code-block:: console
 568
 569     // enable VLAN strip on a port
 570     testpmd> port config (port_id) tx_offload vlan_strip (on|off)
 571
 572     // notify application VLAN strip via mbuf
 573     mbuf->ol_flags |= PKT_RX_VLAN | PKT_RX_STRIPPED // outer VLAN is found and stripped
 574     mbuf->vlan_tci = tci_value                      // TCI of the stripped VLAN
 575
 576 Time Synchronization
 577 ~~~~~~~~~~~~~~~~~~~~
 578
 579 System operators may run a PTP (Precision Time Protocol) client application to
 580 synchronize the time on the NIC (and optionally, on the system) to a PTP master.
 581
 582 The BNXT PMD supports a PTP client application to communicate with a PTP master
 583 clock using DPDK IEEE1588 APIs. Note that the PTP client application needs to
 584 run on PF and vector mode needs to be disabled.
 585
 586 For the PTP time synchronization support, the BNXT PMD must be compiled with
 587 ``CONFIG_RTE_LIBRTE_IEEE1588=y`` (this compilation flag is currently pending).
 588
 589 .. code-block:: console
 590
 591     testpmd> set fwd ieee1588 // enable IEEE 1588 mode
 592
 593 When enabled, the BNXT PMD configures hardware to insert IEEE 1588 timestamps to
 594 the outgoing PTP packets and reports IEEE 1588 timestamps from the incoming PTP
 595 packets to application via mbuf.
 596
 597 .. code-block:: console
 598
 599     // RX packet completion will indicate whether the packet is PTP
 600     mbuf->ol_flags |= PKT_RX_IEEE1588_PTP
 601
 602 Statistics Collection
 603 ~~~~~~~~~~~~~~~~~~~~~
 604
 605 In Linux, the *ethtool -S* enables us to query the NIC stats. DPDK provides the
 606 similar functionalities via rte_eth_stats and rte_eth_xstats.
 607
 608 The BNXT PMD supports both basic and extended stats collection:
 609
 610 * Basic stats
 611 * Extended stats
 612
 613 Basic Stats
 614 ^^^^^^^^^^^
 615
 616 The application collects per-port and per-queue stats using rte_eth_stats APIs.
 617
 618 .. code-block:: console
 619
 620     testpmd> show port stats (port_id)
 621
 622 Basic stats include:
 623
 624 * ipackets
 625 * ibytes
 626 * opackets
 627 * obytes
 628 * imissed
 629 * ierrors
 630 * oerrors
 631
 632 By default, per-queue stats for 16 queues are supported. For more than 16
 633 queues, BNXT PMD should be compiled with ``CONFIG_RTE_ETHDEV_QUEUE_STAT_CNTRS``
 634 set to the desired number of queues.
 635
 636 Extended Stats
 637 ^^^^^^^^^^^^^^
 638
 639 Unlike basic stats, the extended stats are vendor-specific, i.e. each vendor
 640 provides its own set of counters.
 641
 642 The BNXT PMD provides a rich set of counters, including per-flow counters,
 643 per-cos counters, per-priority counters, etc.
 644
 645 .. code-block:: console
 646
 647     testpmd> show port xstats (port_id)
 648
 649 Shown below is the elaborated sequence to retrieve extended stats:
 650
 651 .. code-block:: console
 652
 653     // application queries the number of xstats
 654     len = rte_eth_xstats_get(port_id, NULL, 0);
 655     // BNXT PMD returns the size of xstats array (i.e. the number of entries)
 656     // BNXT PMD returns 0, if the feature is compiled out or disabled
 657
 658     // application allocates memory for xstats
 659     struct rte_eth_xstats_name *names; // name is 64 character or less
 660     struct rte_eth_xstats *xstats;
 661     names = calloc(len, sizeof(*names));
 662     xstats = calloc(len, sizeof(*xstats));
 663
 664     // application retrieves xstats // names and values
 665     ret = rte_eth_xstats_get_names(port_id, *names, len);
 666     ret = rte_eth_xstats_get(port_id, *xstats, len);
 667
 668     // application checks the xstats
 669     // application may repeat the below:
 670     len = rte_eth_xstats_reset(port_id); // reset the xstats
 671
 672     // reset can be skipped, if application wants to see accumulated stats
 673     // run traffic
 674     // probably stop the traffic
 675     // retrieve xstats // no need to retrieve xstats names again
 676     // check xstats
 677
 678 Generic Flow Offload
 679 ~~~~~~~~~~~~~~~~~~~~
 680
 681 Applications can get benefit by offloading all or part of flow processing to
 682 hardware. For example, applications can offload packet classification only
 683 (partial offload) or whole match-action (full offload).
 684
 685 DPDK offers the Generic Flow API (rte_flow API) to configure hardware to
 686 perform flow processing.
 687
 688 Listed below are the rte_flow APIs BNXT PMD supports:
 689
 690 * rte_flow_validate
 691 * rte_flow_create
 692 * rte_flow_destroy
 693 * rte_flow_flush
 694
 695 Host Based Flow Table Management
 696 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 697
 698 Starting with 20.05 BNXT PMD supports host based flow table management. This is
 699 a new mechanism that should allow higher flow scalability than what is currently
 700 supported. This new approach also defines a new rte_flow parser, and mapper
 701 which currently supports basic packet classification in the receive path.
 702
 703 The feature uses a newly implemented control-plane firmware interface which
 704 optimizes flow insertions and deletions.
 705
 706 This is a tech preview feature, and is disabled by default. It can be enabled
 707 using bnxt devargs. For ex: "-w 0000:0d:00.0,host-based-truflow=1”.
 708
 709 Application Support
 710 -------------------
 711
 712 Firmware
 713 ~~~~~~~~
 714
 715 The BNXT PMD supports the application to retrieve the firmware version.
 716
 717 .. code-block:: console
 718
 719     testpmd> show port info (port_id)
 720
 721 Note that the applications cannot update the firmware using BNXT PMD.
 722
 723 Multiple Processes
 724 ~~~~~~~~~~~~~~~~~~
 725
 726 When two or more DPDK applications (e.g., testpmd and dpdk-pdump) share a single
 727 instance of DPDK, the BNXT PMD supports a single primary application and one or
 728 more secondary applications. Note that the DPDK-layer (not the PMD) ensures
 729 there is only one primary application.
 730
 731 There are two modes:
 732
 733 Manual mode
 734
 735 * Application notifies whether it is primary or secondary using *proc-type* flag
 736 * 1st process should be spawned with ``--proc-type=primary``
 737 * All subsequent processes should be spawned with ``--proc-type=secondary``
 738
 739 Auto detection mode
 740
 741 * Application is using ``proc-type=auto`` flag
 742 * A process is spawned as a secondary if a primary is already running
 743
 744 The BNXT PMD uses the info to skip a device initialization, i.e. performs a
 745 device initialization only when being brought up by a primary application.
 746
 747 Runtime Queue Setup
 748 ~~~~~~~~~~~~~~~~~~~
 749
 750 Typically, a DPDK application allocates TX and RX queues statically: i.e. queues
 751 are allocated at start. However, an application may want to increase (or
 752 decrease) the number of queues dynamically for various reasons, e.g. power
 753 savings.
 754
 755 The BNXT PMD supports applications to increase or decrease queues at runtime.
 756
 757 .. code-block:: console
 758
 759     testpmd> port config all (rxq|txq) (num_queues)
 760
 761 Note that a DPDK application must allocate default queues (one for TX and one
 762 for RX at minimum) at initialization.
 763
 764 Descriptor Status
 765 ~~~~~~~~~~~~~~~~~
 766
 767 Applications may use the descriptor status for various reasons, e.g. for power
 768 savings. For example, an application may stop polling and change to interrupt
 769 mode when the descriptor status shows no packets to service for a while.
 770
 771 The BNXT PMD supports the application to retrieve both TX and RX descriptor
 772 status.
 773
 774 .. code-block:: console
 775
 776     testpmd> show port (port_id) (rxq|txq) (queue_id) desc (desc_id) status
 777
 778 Bonding
 779 ~~~~~~~
 780
 781 DPDK implements a light-weight library to allow PMDs to be bonded together and provide a single logical PMD to the application.
 782
 783 .. code-block:: console
 784
 785     testpmd -l 0-3 -n4 --vdev 'net_bonding0,mode=0,slave=<PCI B:D.F device 1>,slave=<PCI B:D.F device 2>,mac=XX:XX:XX:XX:XX:XX’ – --socket_num=1 – -i --port-topology=chained
 786     (ex) testpmd -l 1,3,5,7,9 -n4 --vdev 'net_bonding0,mode=0,slave=0000:82:00.0,slave=0000:82:00.1,mac=00:1e:67:1d:fd:1d' – --socket-num=1 – -i --port-topology=chained
 787
 788 Vector Processing
 789 -----------------
 790
 791 Vector processing provides significantly improved performance over scalar
 792 processing (see Vector Processor, here).
 793
 794 The BNXT PMD supports the vector processing using SSE (Streaming SIMD
 795 Extensions) instructions on x86 platforms. The BNXT vPMD (vector mode PMD) is
 796 currently limited to Intel/AMD CPU architecture. Support for ARM is *not*
 797 currently implemented.
 798
 799 This improved performance comes from several optimizations:
 800
 801 * Batching
 802     * TX: processing completions in bulk
 803     * RX: allocating mbufs in bulk
 804 * Chained mbufs are *not* supported, i.e. a packet should fit a single mbuf
 805 * Some stateless offloads are *not* supported with vector processing
 806     * TX: no offloads will be supported
 807     * RX: reduced RX offloads (listed below) will be supported::
 808
 809        DEV_RX_OFFLOAD_VLAN_STRIP
 810        DEV_RX_OFFLOAD_KEEP_CRC
 811        DEV_RX_OFFLOAD_JUMBO_FRAME
 812        DEV_RX_OFFLOAD_IPV4_CKSUM
 813        DEV_RX_OFFLOAD_UDP_CKSUM
 814        DEV_RX_OFFLOAD_TCP_CKSUM
 815        DEV_RX_OFFLOAD_OUTER_IPV4_CKSUM
 816        DEV_RX_OFFLOAD_RSS_HASH
 817        DEV_RX_OFFLOAD_VLAN_FILTER
 818
 819 The BNXT Vector PMD is enabled in DPDK builds by default.
 820
 821 However, a decision to enable vector mode will be made when the port transitions
 822 from stopped to started. Any TX offloads or some RX offloads (other than listed
 823 above) will disable the vector mode.
 824 Offload configuration changes that impact vector mode must be made when the port
 825 is stopped.
 826
 827 Note that TX (or RX) vector mode can be enabled independently from RX (or TX)
 828 vector mode.
 829
 830 Appendix
 831 --------
 832
 833 Supported Chipsets and Adapters
 834 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 835
 836 BCM5730x NetXtreme-C® Family of Ethernet Network Controllers
 837 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 838
 839 Information about Ethernet adapters in the NetXtreme family of adapters can be
 840 found in the `NetXtreme® Brand section <https://www.broadcom.com/products/ethernet-connectivity/network-adapters/>`_ of the `Broadcom website <http://www.broadcom.com/>`_.
 841
 842 * ``M150c ... Single-port 40/50 Gigabit Ethernet Adapter``
 843 * ``P150c ... Single-port 40/50 Gigabit Ethernet Adapter``
 844 * ``P225c ... Dual-port 10/25 Gigabit Ethernet Adapter``
 845
 846 BCM574xx/575xx NetXtreme-E® Family of Ethernet Network Controllers
 847 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 848
 849 Information about Ethernet adapters in the NetXtreme family of adapters can be
 850 found in the `NetXtreme® Brand section <https://www.broadcom.com/products/ethernet-connectivity/network-adapters/>`_ of the `Broadcom website <http://www.broadcom.com/>`_.
 851
 852 * ``M125P .... Single-port OCP 2.0 10/25 Gigabit Ethernet Adapter``
 853 * ``M150P .... Single-port OCP 2.0 50 Gigabit Ethernet Adapter``
 854 * ``M150PM ... Single-port OCP 2.0 Multi-Host 50 Gigabit Ethernet Adapter``
 855 * ``M210P .... Dual-port OCP 2.0 10 Gigabit Ethernet Adapter``
 856 * ``M210TP ... Dual-port OCP 2.0 10 Gigabit Ethernet Adapter``
 857 * ``M1100G ... Single-port OCP 2.0 10/25/50/100 Gigabit Ethernet Adapter``
 858 * ``N150G .... Single-port OCP 3.0 50 Gigabit Ethernet Adapter``
 859 * ``M225P .... Dual-port OCP 2.0 10/25 Gigabit Ethernet Adapter``
 860 * ``N210P .... Dual-port OCP 3.0 10 Gigabit Ethernet Adapter``
 861 * ``N210TP ... Dual-port OCP 3.0 10 Gigabit Ethernet Adapter``
 862 * ``N225P .... Dual-port OCP 3.0 10/25 Gigabit Ethernet Adapter``
 863 * ``N250G .... Dual-port OCP 3.0 50 Gigabit Ethernet Adapter``
 864 * ``N410SG ... Quad-port OCP 3.0 10 Gigabit Ethernet Adapter``
 865 * ``N410SGBT . Quad-port OCP 3.0 10 Gigabit Ethernet Adapter``
 866 * ``N425G .... Quad-port OCP 3.0 10/25 Gigabit Ethernet Adapter``
 867 * ``N1100G ... Single-port OCP 3.0 10/25/50/100 Gigabit Ethernet Adapter``
 868 * ``N2100G ... Dual-port OCP 3.0 10/25/50/100 Gigabit Ethernet Adapter``
 869 * ``N2200G ... Dual-port OCP 3.0 10/25/50/100/200 Gigabit Ethernet Adapter``
 870 * ``P150P .... Single-port 50 Gigabit Ethernet Adapter``
 871 * ``P210P .... Dual-port 10 Gigabit Ethernet Adapter``
 872 * ``P210TP ... Dual-port 10 Gigabit Ethernet Adapter``
 873 * ``P225P .... Dual-port 10/25 Gigabit Ethernet Adapter``
 874 * ``P410SG ... Quad-port 10 Gigabit Ethernet Adapter``
 875 * ``P410SGBT . Quad-port 10 Gigabit Ethernet Adapter``
 876 * ``P425G .... Quad-port 10/25 Gigabit Ethernet Adapter``
 877 * ``P1100G ... Single-port 10/25/50/100 Gigabit Ethernet Adapter``
 878 * ``P2100G ... Dual-port 10/25/50/100 Gigabit Ethernet Adapter``
 879 * ``P2200G ... Dual-port 10/25/50/100/200 Gigabit Ethernet Adapter``
 880
 881 BCM588xx NetXtreme-S® Family of SmartNIC Network Controllers
 882 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 883
 884 Information about the Stingray family of SmartNIC adapters can be found in the
 885 `Stingray® Brand section <https://www.broadcom.com/products/ethernet-connectivity/smartnic/>`_ of the `Broadcom website <http://www.broadcom.com/>`_.
 886
 887 * ``PS225 ... Dual-port 25 Gigabit Ethernet SmartNIC``
 888
 889 BCM5873x StrataGX® Family of Communications Processors
 890 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 891
 892 These ARM-based processors target a broad range of networking applications,
 893 including virtual CPE (vCPE) and NFV appliances, 10G service routers and
 894 gateways, control plane processing for Ethernet switches, and network-attached
 895 storage (NAS).
 896
 897 * ``StrataGX BCM58732 ... Octal-Core 3.0GHz 64-bit ARM®v8 Cortex®-A72 based SoC``