Documentation/networking/device_drivers/aquantia/atlantic.txt

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