1.. SPDX-License-Identifier: GPL-2.0
2.. include:: <isonum.txt>
3
4===============================
5Marvell(Aquantia) AQtion Driver
6===============================
7
8For 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
20Identifying Your Adapter
21========================
22
23The driver in this release is compatible with AQC-100, AQC-107, AQC-108
24based ethernet adapters.
25
26
27SFP+ Devices (for AQC-100 based adapters)
28-----------------------------------------
29
30This release tested with passive Direct Attach Cables (DAC) and SFP+/LC
31Optical Transceiver.
32
33Configuration
34=============
35
36Viewing 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
48Jumbo 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
57ethtool
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
63NAPI
64----
65  NAPI (Rx polling mode) is supported in the atlantic driver.
66
67Supported ethtool options
68=========================
69
70Viewing 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
116Viewing 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
137Viewing 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
190Interrupt 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
205Wake 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
216Set 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
256RX 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
355RSS 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
366UDP 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
382Private 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
407Command Line Parameters
408=======================
409The following command line parameters are available on atlantic driver:
410
411aq_itr -Interrupt throttling mode
412---------------------------------
413Accepted values: 0, 1, 0xFFFF
414
415Default value: 0xFFFF
416
417======   ==============================================================
4180        Disable interrupt throttling.
4191        Enable interrupt throttling and use specified tx and rx rates.
4200xFFFF   Auto throttling mode. Driver will choose the best RX and TX
421	 interrupt throttling settings based on link speed.
422======   ==============================================================
423
424aq_itr_tx - TX interrupt throttle rate
425--------------------------------------
426
427Accepted values: 0 - 0x1FF
428
429Default value: 0
430
431TX side throttling in microseconds. Adapter will setup maximum interrupt delay
432to this value. Minimum interrupt delay will be a half of this value
433
434aq_itr_rx - RX interrupt throttle rate
435--------------------------------------
436
437Accepted values: 0 - 0x1FF
438
439Default value: 0
440
441RX side throttling in microseconds. Adapter will setup maximum interrupt delay
442to 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
448Config file parameters
449======================
450
451For some fine tuning and performance optimizations,
452some parameters can be changed in the {source_dir}/aq_cfg.h file.
453
454AQ_CFG_RX_PAGEORDER
455-------------------
456
457Default value: 0
458
459RX page order override. That's a power of 2 number of RX pages allocated for
460each descriptor. Received descriptor size is still limited by
461AQ_CFG_RX_FRAME_MAX.
462
463Increasing pageorder makes page reuse better (actual on iommu enabled systems).
464
465AQ_CFG_RX_REFILL_THRES
466----------------------
467
468Default value: 32
469
470RX refill threshold. RX path will not refill freed descriptors until the
471specified number of free descriptors is observed. Larger values may help
472better page reuse but may lead to packet drops as well.
473
474AQ_CFG_VECS_DEF
475---------------
476
477Number of queues
478
479Valid Range: 0 - 8 (up to AQ_CFG_VECS_MAX)
480
481Default value: 8
482
483Notice this value will be capped by the number of cores available on the system.
484
485AQ_CFG_IS_RSS_DEF
486-----------------
487
488Enable/disable Receive Side Scaling
489
490This feature allows the adapter to distribute receive processing
491across multiple CPU-cores and to prevent from overloading a single CPU core.
492
493Valid values
494
495==  ========
4960   disabled
4971   enabled
498==  ========
499
500Default value: 1
501
502AQ_CFG_NUM_RSS_QUEUES_DEF
503-------------------------
504
505Number of queues for Receive Side Scaling
506
507Valid Range: 0 - 8 (up to AQ_CFG_VECS_DEF)
508
509Default value: AQ_CFG_VECS_DEF
510
511AQ_CFG_IS_LRO_DEF
512-----------------
513
514Enable/disable Large Receive Offload
515
516This offload enables the adapter to coalesce multiple TCP segments and indicate
517them as a single coalesced unit to the OS networking subsystem.
518
519The system consumes less energy but it also introduces more latency in packets
520processing.
521
522Valid values
523
524==  ========
5250   disabled
5261   enabled
527==  ========
528
529Default value: 1
530
531AQ_CFG_TX_CLEAN_BUDGET
532----------------------
533
534Maximum descriptors to cleanup on TX at once.
535
536Default value: 256
537
538After the aq_cfg.h file changed the driver must be rebuilt to take effect.
539
540Support
541=======
542
543If an issue is identified with the released source code on the supported
544kernel with a supported adapter, email the specific information related
545to the issue to aqn_support@marvell.com
546
547License
548=======
549
550aQuantia Corporation Network Driver
551
552Copyright |copy| 2014 - 2019 aQuantia Corporation.
553
554This program is free software; you can redistribute it and/or modify it
555under the terms and conditions of the GNU General Public License,
556version 2, as published by the Free Software Foundation.
557