Debian Codegraph @

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

raw
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 [email protected]
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.