Documentation/networking/device_drivers/ethernet/aquantia/atlantic.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2 .. include:: <isonum.txt>
   3
   4 ===============================
   5 Marvell(Aquantia) AQtion Driver
   6 ===============================
   7
   8 For the aQuantia Multi-Gigabit PCI Express Family of Ethernet Adapters
   9
  10 .. Contents
  11
  12     - Identifying Your Adapter
  13     - Configuration
  14     - Supported ethtool options
  15     - Command Line Parameters
  16     - Config file parameters
  17     - Support
  18     - License
  19
  20 Identifying Your Adapter
  21 ========================
  22
  23 The driver in this release is compatible with AQC-100, AQC-107, AQC-108
  24 based ethernet adapters.
  25
  26
  27 SFP+ Devices (for AQC-100 based adapters)
  28 -----------------------------------------
  29
  30 This release tested with passive Direct Attach Cables (DAC) and SFP+/LC
  31 Optical Transceiver.
  32
  33 Configuration
  34 =============
  35
  36 Viewing Link Messages
  37 ---------------------
  38   Link messages will not be displayed to the console if the distribution is
  39   restricting system messages. In order to see network driver link messages on
  40   your console, set dmesg to eight by entering the following::
  41
  42        dmesg -n 8
  43
  44   .. note::
  45
  46      This setting is not saved across reboots.
  47
  48 Jumbo Frames
  49 ------------
  50   The driver supports Jumbo Frames for all adapters. Jumbo Frames support is
  51   enabled by changing the MTU to a value larger than the default of 1500.
  52   The maximum value for the MTU is 16000.  Use the `ip` command to
  53   increase the MTU size.  For example::
  54
  55         ip link set mtu 16000 dev enp1s0
  56
  57 ethtool
  58 -------
  59   The driver utilizes the ethtool interface for driver configuration and
  60   diagnostics, as well as displaying statistical information. The latest
  61   ethtool version is required for this functionality.
  62
  63 NAPI
  64 ----
  65   NAPI (Rx polling mode) is supported in the atlantic driver.
  66
  67 Supported ethtool options
  68 =========================
  69
  70 Viewing adapter settings
  71 ------------------------
  72
  73  ::
  74
  75     ethtool <ethX>
  76
  77  Output example::
  78
  79   Settings for enp1s0:
  80     Supported ports: [ TP ]
  81     Supported link modes:   100baseT/Full
  82                             1000baseT/Full
  83                             10000baseT/Full
  84                             2500baseT/Full
  85                             5000baseT/Full
  86     Supported pause frame use: Symmetric
  87     Supports auto-negotiation: Yes
  88     Supported FEC modes: Not reported
  89     Advertised link modes:  100baseT/Full
  90                             1000baseT/Full
  91                             10000baseT/Full
  92                             2500baseT/Full
  93                             5000baseT/Full
  94     Advertised pause frame use: Symmetric
  95     Advertised auto-negotiation: Yes
  96     Advertised FEC modes: Not reported
  97     Speed: 10000Mb/s
  98     Duplex: Full
  99     Port: Twisted Pair
 100     PHYAD: 0
 101     Transceiver: internal
 102     Auto-negotiation: on
 103     MDI-X: Unknown
 104     Supports Wake-on: g
 105     Wake-on: d
 106     Link detected: yes
 107
 108
 109  .. note::
 110
 111     AQrate speeds (2.5/5 Gb/s) will be displayed only with linux kernels > 4.10.
 112     But you can still use these speeds::
 113
 114         ethtool -s eth0 autoneg off speed 2500
 115
 116 Viewing adapter information
 117 ---------------------------
 118
 119  ::
 120
 121   ethtool -i <ethX>
 122
 123  Output example::
 124
 125   driver: atlantic
 126   version: 5.2.0-050200rc5-generic-kern
 127   firmware-version: 3.1.78
 128   expansion-rom-version:
 129   bus-info: 0000:01:00.0
 130   supports-statistics: yes
 131   supports-test: no
 132   supports-eeprom-access: no
 133   supports-register-dump: yes
 134   supports-priv-flags: no
 135
 136
 137 Viewing Ethernet adapter statistics
 138 -----------------------------------
 139
 140  ::
 141
 142     ethtool -S <ethX>
 143
 144  Output example::
 145
 146   NIC statistics:
 147      InPackets: 13238607
 148      InUCast: 13293852
 149      InMCast: 52
 150      InBCast: 3
 151      InErrors: 0
 152      OutPackets: 23703019
 153      OutUCast: 23704941
 154      OutMCast: 67
 155      OutBCast: 11
 156      InUCastOctects: 213182760
 157      OutUCastOctects: 22698443
 158      InMCastOctects: 6600
 159      OutMCastOctects: 8776
 160      InBCastOctects: 192
 161      OutBCastOctects: 704
 162      InOctects: 2131839552
 163      OutOctects: 226938073
 164      InPacketsDma: 95532300
 165      OutPacketsDma: 59503397
 166      InOctetsDma: 1137102462
 167      OutOctetsDma: 2394339518
 168      InDroppedDma: 0
 169      Queue[0] InPackets: 23567131
 170      Queue[0] OutPackets: 20070028
 171      Queue[0] InJumboPackets: 0
 172      Queue[0] InLroPackets: 0
 173      Queue[0] InErrors: 0
 174      Queue[1] InPackets: 45428967
 175      Queue[1] OutPackets: 11306178
 176      Queue[1] InJumboPackets: 0
 177      Queue[1] InLroPackets: 0
 178      Queue[1] InErrors: 0
 179      Queue[2] InPackets: 3187011
 180      Queue[2] OutPackets: 13080381
 181      Queue[2] InJumboPackets: 0
 182      Queue[2] InLroPackets: 0
 183      Queue[2] InErrors: 0
 184      Queue[3] InPackets: 23349136
 185      Queue[3] OutPackets: 15046810
 186      Queue[3] InJumboPackets: 0
 187      Queue[3] InLroPackets: 0
 188      Queue[3] InErrors: 0
 189
 190 Interrupt coalescing support
 191 ----------------------------
 192
 193  ITR mode, TX/RX coalescing timings could be viewed with::
 194
 195     ethtool -c <ethX>
 196
 197  and changed with::
 198
 199     ethtool -C <ethX> tx-usecs <usecs> rx-usecs <usecs>
 200
 201  To disable coalescing::
 202
 203     ethtool -C <ethX> tx-usecs 0 rx-usecs 0 tx-max-frames 1 tx-max-frames 1
 204
 205 Wake on LAN support
 206 -------------------
 207
 208  WOL support by magic packet::
 209
 210     ethtool -s <ethX> wol g
 211
 212  To disable WOL::
 213
 214     ethtool -s <ethX> wol d
 215
 216 Set and check the driver message level
 217 --------------------------------------
 218
 219  Set message level
 220
 221  ::
 222
 223     ethtool -s <ethX> msglvl <level>
 224
 225  Level values:
 226
 227  ======   =============================
 228  0x0001   general driver status.
 229  0x0002   hardware probing.
 230  0x0004   link state.
 231  0x0008   periodic status check.
 232  0x0010   interface being brought down.
 233  0x0020   interface being brought up.
 234  0x0040   receive error.
 235  0x0080   transmit error.
 236  0x0200   interrupt handling.
 237  0x0400   transmit completion.
 238  0x0800   receive completion.
 239  0x1000   packet contents.
 240  0x2000   hardware status.
 241  0x4000   Wake-on-LAN status.
 242  ======   =============================
 243
 244  By default, the level of debugging messages is set 0x0001(general driver status).
 245
 246  Check message level
 247
 248  ::
 249
 250     ethtool <ethX> | grep "Current message level"
 251
 252  If you want to disable the output of messages::
 253
 254     ethtool -s <ethX> msglvl 0
 255
 256 RX flow rules (ntuple filters)
 257 ------------------------------
 258
 259  There are separate rules supported, that applies in that order:
 260
 261  1. 16 VLAN ID rules
 262  2. 16 L2 EtherType rules
 263  3. 8 L3/L4 5-Tuple rules
 264
 265
 266  The driver utilizes the ethtool interface for configuring ntuple filters,
 267  via ``ethtool -N <device> <filter>``.
 268
 269  To enable or disable the RX flow rules::
 270
 271     ethtool -K ethX ntuple <on|off>
 272
 273  When disabling ntuple filters, all the user programmed filters are
 274  flushed from the driver cache and hardware. All needed filters must
 275  be re-added when ntuple is re-enabled.
 276
 277  Because of the fixed order of the rules, the location of filters is also fixed:
 278
 279  - Locations 0 - 15 for VLAN ID filters
 280  - Locations 16 - 31 for L2 EtherType filters
 281  - Locations 32 - 39 for L3/L4 5-tuple filters (locations 32, 36 for IPv6)
 282
 283  The L3/L4 5-tuple (protocol, source and destination IP address, source and
 284  destination TCP/UDP/SCTP port) is compared against 8 filters. For IPv4, up to
 285  8 source and destination addresses can be matched. For IPv6, up to 2 pairs of
 286  addresses can be supported. Source and destination ports are only compared for
 287  TCP/UDP/SCTP packets.
 288
 289  To add a filter that directs packet to queue 5, use
 290  ``<-N|-U|--config-nfc|--config-ntuple>`` switch::
 291
 292     ethtool -N <ethX> flow-type udp4 src-ip 10.0.0.1 dst-ip 10.0.0.2 src-port 2000 dst-port 2001 action 5 <loc 32>
 293
 294  - action is the queue number.
 295  - loc is the rule number.
 296
 297  For ``flow-type ip4|udp4|tcp4|sctp4|ip6|udp6|tcp6|sctp6`` you must set the loc
 298  number within 32 - 39.
 299  For ``flow-type ip4|udp4|tcp4|sctp4|ip6|udp6|tcp6|sctp6`` you can set 8 rules
 300  for traffic IPv4 or you can set 2 rules for traffic IPv6. Loc number traffic
 301  IPv6 is 32 and 36.
 302  At the moment you can not use IPv4 and IPv6 filters at the same time.
 303
 304  Example filter for IPv6 filter traffic::
 305
 306     sudo ethtool -N <ethX> flow-type tcp6 src-ip 2001:db8:0:f101::1 dst-ip 2001:db8:0:f101::2 action 1 loc 32
 307     sudo ethtool -N <ethX> flow-type ip6 src-ip 2001:db8:0:f101::2 dst-ip 2001:db8:0:f101::5 action -1 loc 36
 308
 309  Example filter for IPv4 filter traffic::
 310
 311     sudo ethtool -N <ethX> flow-type udp4 src-ip 10.0.0.4 dst-ip 10.0.0.7 src-port 2000 dst-port 2001 loc 32
 312     sudo ethtool -N <ethX> flow-type tcp4 src-ip 10.0.0.3 dst-ip 10.0.0.9 src-port 2000 dst-port 2001 loc 33
 313     sudo ethtool -N <ethX> flow-type ip4 src-ip 10.0.0.6 dst-ip 10.0.0.4 loc 34
 314
 315  If you set action -1, then all traffic corresponding to the filter will be discarded.
 316
 317  The maximum value action is 31.
 318
 319
 320  The VLAN filter (VLAN id) is compared against 16 filters.
 321  VLAN id must be accompanied by mask 0xF000. That is to distinguish VLAN filter
 322  from L2 Ethertype filter with UserPriority since both User Priority and VLAN ID
 323  are passed in the same 'vlan' parameter.
 324
 325  To add a filter that directs packets from VLAN 2001 to queue 5::
 326
 327     ethtool -N <ethX> flow-type ip4 vlan 2001 m 0xF000 action 1 loc 0
 328
 329
 330  L2 EtherType filters allows filter packet by EtherType field or both EtherType
 331  and User Priority (PCP) field of 802.1Q.
 332  UserPriority (vlan) parameter must be accompanied by mask 0x1FFF. That is to
 333  distinguish VLAN filter from L2 Ethertype filter with UserPriority since both
 334  User Priority and VLAN ID are passed in the same 'vlan' parameter.
 335
 336  To add a filter that directs IP4 packess of priority 3 to queue 3::
 337
 338     ethtool -N <ethX> flow-type ether proto 0x800 vlan 0x600 m 0x1FFF action 3 loc 16
 339
 340  To see the list of filters currently present::
 341
 342     ethtool <-u|-n|--show-nfc|--show-ntuple> <ethX>
 343
 344  Rules may be deleted from the table itself. This is done using::
 345
 346     sudo ethtool <-N|-U|--config-nfc|--config-ntuple> <ethX> delete <loc>
 347
 348  - loc is the rule number to be deleted.
 349
 350  Rx filters is an interface to load the filter table that funnels all flow
 351  into queue 0 unless an alternative queue is specified using "action". In that
 352  case, any flow that matches the filter criteria will be directed to the
 353  appropriate queue. RX filters is supported on all kernels 2.6.30 and later.
 354
 355 RSS for UDP
 356 -----------
 357
 358  Currently, NIC does not support RSS for fragmented IP packets, which leads to
 359  incorrect working of RSS for fragmented UDP traffic. To disable RSS for UDP the
 360  RX Flow L3/L4 rule may be used.
 361
 362  Example::
 363
 364     ethtool -N eth0 flow-type udp4 action 0 loc 32
 365
 366 UDP GSO hardware offload
 367 ------------------------
 368
 369  UDP GSO allows to boost UDP tx rates by offloading UDP headers allocation
 370  into hardware. A special userspace socket option is required for this,
 371  could be validated with /kernel/tools/testing/selftests/net/::
 372
 373     udpgso_bench_tx -u -4 -D 10.0.1.1 -s 6300 -S 100
 374
 375  Will cause sending out of 100 byte sized UDP packets formed from single
 376  6300 bytes user buffer.
 377
 378  UDP GSO is configured by::
 379
 380     ethtool -K eth0 tx-udp-segmentation on
 381
 382 Private flags (testing)
 383 -----------------------
 384
 385  Atlantic driver supports private flags for hardware custom features::
 386
 387         $ ethtool --show-priv-flags ethX
 388
 389         Private flags for ethX:
 390         DMASystemLoopback  : off
 391         PKTSystemLoopback  : off
 392         DMANetworkLoopback : off
 393         PHYInternalLoopback: off
 394         PHYExternalLoopback: off
 395
 396  Example::
 397
 398         $ ethtool --set-priv-flags ethX DMASystemLoopback on
 399
 400  DMASystemLoopback:   DMA Host loopback.
 401  PKTSystemLoopback:   Packet buffer host loopback.
 402  DMANetworkLoopback:  Network side loopback on DMA block.
 403  PHYInternalLoopback: Internal loopback on Phy.
 404  PHYExternalLoopback: External loopback on Phy (with loopback ethernet cable).
 405
 406
 407 Command Line Parameters
 408 =======================
 409 The following command line parameters are available on atlantic driver:
 410
 411 aq_itr -Interrupt throttling mode
 412 ---------------------------------
 413 Accepted values: 0, 1, 0xFFFF
 414
 415 Default value: 0xFFFF
 416
 417 ======   ==============================================================
 418 0        Disable interrupt throttling.
 419 1        Enable interrupt throttling and use specified tx and rx rates.
 420 0xFFFF   Auto throttling mode. Driver will choose the best RX and TX
 421          interrupt throttling settings based on link speed.
 422 ======   ==============================================================
 423
 424 aq_itr_tx - TX interrupt throttle rate
 425 --------------------------------------
 426
 427 Accepted values: 0 - 0x1FF
 428
 429 Default value: 0
 430
 431 TX side throttling in microseconds. Adapter will setup maximum interrupt delay
 432 to this value. Minimum interrupt delay will be a half of this value
 433
 434 aq_itr_rx - RX interrupt throttle rate
 435 --------------------------------------
 436
 437 Accepted values: 0 - 0x1FF
 438
 439 Default value: 0
 440
 441 RX side throttling in microseconds. Adapter will setup maximum interrupt delay
 442 to this value. Minimum interrupt delay will be a half of this value
 443
 444 .. note::
 445
 446    ITR settings could be changed in runtime by ethtool -c means (see below)
 447
 448 Config file parameters
 449 ======================
 450
 451 For some fine tuning and performance optimizations,
 452 some parameters can be changed in the {source_dir}/aq_cfg.h file.
 453
 454 AQ_CFG_RX_PAGEORDER
 455 -------------------
 456
 457 Default value: 0
 458
 459 RX page order override. That's a power of 2 number of RX pages allocated for
 460 each descriptor. Received descriptor size is still limited by
 461 AQ_CFG_RX_FRAME_MAX.
 462
 463 Increasing pageorder makes page reuse better (actual on iommu enabled systems).
 464
 465 AQ_CFG_RX_REFILL_THRES
 466 ----------------------
 467
 468 Default value: 32
 469
 470 RX refill threshold. RX path will not refill freed descriptors until the
 471 specified number of free descriptors is observed. Larger values may help
 472 better page reuse but may lead to packet drops as well.
 473
 474 AQ_CFG_VECS_DEF
 475 ---------------
 476
 477 Number of queues
 478
 479 Valid Range: 0 - 8 (up to AQ_CFG_VECS_MAX)
 480
 481 Default value: 8
 482
 483 Notice this value will be capped by the number of cores available on the system.
 484
 485 AQ_CFG_IS_RSS_DEF
 486 -----------------
 487
 488 Enable/disable Receive Side Scaling
 489
 490 This feature allows the adapter to distribute receive processing
 491 across multiple CPU-cores and to prevent from overloading a single CPU core.
 492
 493 Valid values
 494
 495 ==  ========
 496 0   disabled
 497 1   enabled
 498 ==  ========
 499
 500 Default value: 1
 501
 502 AQ_CFG_NUM_RSS_QUEUES_DEF
 503 -------------------------
 504
 505 Number of queues for Receive Side Scaling
 506
 507 Valid Range: 0 - 8 (up to AQ_CFG_VECS_DEF)
 508
 509 Default value: AQ_CFG_VECS_DEF
 510
 511 AQ_CFG_IS_LRO_DEF
 512 -----------------
 513
 514 Enable/disable Large Receive Offload
 515
 516 This offload enables the adapter to coalesce multiple TCP segments and indicate
 517 them as a single coalesced unit to the OS networking subsystem.
 518
 519 The system consumes less energy but it also introduces more latency in packets
 520 processing.
 521
 522 Valid values
 523
 524 ==  ========
 525 0   disabled
 526 1   enabled
 527 ==  ========
 528
 529 Default value: 1
 530
 531 AQ_CFG_TX_CLEAN_BUDGET
 532 ----------------------
 533
 534 Maximum descriptors to cleanup on TX at once.
 535
 536 Default value: 256
 537
 538 After the aq_cfg.h file changed the driver must be rebuilt to take effect.
 539
 540 Support
 541 =======
 542
 543 If an issue is identified with the released source code on the supported
 544 kernel with a supported adapter, email the specific information related
 545 to the issue to aqn_support@marvell.com
 546
 547 License
 548 =======
 549
 550 aQuantia Corporation Network Driver
 551
 552 Copyright |copy| 2014 - 2019 aQuantia Corporation.
 553
 554 This program is free software; you can redistribute it and/or modify it
 555 under the terms and conditions of the GNU General Public License,
 556 version 2, as published by the Free Software Foundation.