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