1.. SPDX-License-Identifier: GPL-2.0+
2
3=================================================================
4Linux Base Driver for the Intel(R) Ethernet Controller 800 Series
5=================================================================
6
7Intel ice Linux driver.
8Copyright(c) 2018-2021 Intel Corporation.
9
10Contents
11========
12
13- Overview
14- Identifying Your Adapter
15- Important Notes
16- Additional Features & Configurations
17- Performance Optimization
18
19
20The associated Virtual Function (VF) driver for this driver is iavf.
21
22Driver information can be obtained using ethtool and lspci.
23
24For questions related to hardware requirements, refer to the documentation
25supplied with your Intel adapter. All hardware requirements listed apply to use
26with Linux.
27
28This driver supports XDP (Express Data Path) and AF_XDP zero-copy. Note that
29XDP is blocked for frame sizes larger than 3KB.
30
31
32Identifying Your Adapter
33========================
34For information on how to identify your adapter, and for the latest Intel
35network drivers, refer to the Intel Support website:
36https://www.intel.com/support
37
38
39Important Notes
40===============
41
42Packet drops may occur under receive stress
43-------------------------------------------
44Devices based on the Intel(R) Ethernet Controller 800 Series are designed to
45tolerate a limited amount of system latency during PCIe and DMA transactions.
46If these transactions take longer than the tolerated latency, it can impact the
47length of time the packets are buffered in the device and associated memory,
48which may result in dropped packets. These packets drops typically do not have
49a noticeable impact on throughput and performance under standard workloads.
50
51If these packet drops appear to affect your workload, the following may improve
52the situation:
53
541) Make sure that your system's physical memory is in a high-performance
55   configuration, as recommended by the platform vendor. A common
56   recommendation is for all channels to be populated with a single DIMM
57   module.
582) In your system's BIOS/UEFI settings, select the "Performance" profile.
593) Your distribution may provide tools like "tuned," which can help tweak
60   kernel settings to achieve better standard settings for different workloads.
61
62
63Configuring SR-IOV for improved network security
64------------------------------------------------
65In a virtualized environment, on Intel(R) Ethernet Network Adapters that
66support SR-IOV, the virtual function (VF) may be subject to malicious behavior.
67Software-generated layer two frames, like IEEE 802.3x (link flow control), IEEE
68802.1Qbb (priority based flow-control), and others of this type, are not
69expected and can throttle traffic between the host and the virtual switch,
70reducing performance. To resolve this issue, and to ensure isolation from
71unintended traffic streams, configure all SR-IOV enabled ports for VLAN tagging
72from the administrative interface on the PF. This configuration allows
73unexpected, and potentially malicious, frames to be dropped.
74
75See "Configuring VLAN Tagging on SR-IOV Enabled Adapter Ports" later in this
76README for configuration instructions.
77
78
79Do not unload port driver if VF with active VM is bound to it
80-------------------------------------------------------------
81Do not unload a port's driver if a Virtual Function (VF) with an active Virtual
82Machine (VM) is bound to it. Doing so will cause the port to appear to hang.
83Once the VM shuts down, or otherwise releases the VF, the command will
84complete.
85
86
87Important notes for SR-IOV and Link Aggregation
88-----------------------------------------------
89Link Aggregation is mutually exclusive with SR-IOV.
90
91- If Link Aggregation is active, SR-IOV VFs cannot be created on the PF.
92- If SR-IOV is active, you cannot set up Link Aggregation on the interface.
93
94Bridging and MACVLAN are also affected by this. If you wish to use bridging or
95MACVLAN with SR-IOV, you must set up bridging or MACVLAN before enabling
96SR-IOV. If you are using bridging or MACVLAN in conjunction with SR-IOV, and
97you want to remove the interface from the bridge or MACVLAN, you must follow
98these steps:
99
1001. Destroy SR-IOV VFs if they exist
1012. Remove the interface from the bridge or MACVLAN
1023. Recreate SRIOV VFs as needed
103
104
105Additional Features and Configurations
106======================================
107
108ethtool
109-------
110The driver utilizes the ethtool interface for driver configuration and
111diagnostics, as well as displaying statistical information. The latest ethtool
112version is required for this functionality. Download it at:
113https://kernel.org/pub/software/network/ethtool/
114
115NOTE: The rx_bytes value of ethtool does not match the rx_bytes value of
116Netdev, due to the 4-byte CRC being stripped by the device. The difference
117between the two rx_bytes values will be 4 x the number of Rx packets. For
118example, if Rx packets are 10 and Netdev (software statistics) displays
119rx_bytes as "X", then ethtool (hardware statistics) will display rx_bytes as
120"X+40" (4 bytes CRC x 10 packets).
121
122
123Viewing Link Messages
124---------------------
125Link messages will not be displayed to the console if the distribution is
126restricting system messages. In order to see network driver link messages on
127your console, set dmesg to eight by entering the following::
128
129  # dmesg -n 8
130
131NOTE: This setting is not saved across reboots.
132
133
134Dynamic Device Personalization
135------------------------------
136Dynamic Device Personalization (DDP) allows you to change the packet processing
137pipeline of a device by applying a profile package to the device at runtime.
138Profiles can be used to, for example, add support for new protocols, change
139existing protocols, or change default settings. DDP profiles can also be rolled
140back without rebooting the system.
141
142The DDP package loads during device initialization. The driver looks for
143``intel/ice/ddp/ice.pkg`` in your firmware root (typically ``/lib/firmware/``
144or ``/lib/firmware/updates/``) and checks that it contains a valid DDP package
145file.
146
147NOTE: Your distribution should likely have provided the latest DDP file, but if
148ice.pkg is missing, you can find it in the linux-firmware repository or from
149intel.com.
150
151If the driver is unable to load the DDP package, the device will enter Safe
152Mode. Safe Mode disables advanced and performance features and supports only
153basic traffic and minimal functionality, such as updating the NVM or
154downloading a new driver or DDP package. Safe Mode only applies to the affected
155physical function and does not impact any other PFs. See the "Intel(R) Ethernet
156Adapters and Devices User Guide" for more details on DDP and Safe Mode.
157
158NOTES:
159
160- If you encounter issues with the DDP package file, you may need to download
161  an updated driver or DDP package file. See the log messages for more
162  information.
163
164- The ice.pkg file is a symbolic link to the default DDP package file.
165
166- You cannot update the DDP package if any PF drivers are already loaded. To
167  overwrite a package, unload all PFs and then reload the driver with the new
168  package.
169
170- Only the first loaded PF per device can download a package for that device.
171
172You can install specific DDP package files for different physical devices in
173the same system. To install a specific DDP package file:
174
1751. Download the DDP package file you want for your device.
176
1772. Rename the file ice-xxxxxxxxxxxxxxxx.pkg, where 'xxxxxxxxxxxxxxxx' is the
178   unique 64-bit PCI Express device serial number (in hex) of the device you
179   want the package downloaded on. The filename must include the complete
180   serial number (including leading zeros) and be all lowercase. For example,
181   if the 64-bit serial number is b887a3ffffca0568, then the file name would be
182   ice-b887a3ffffca0568.pkg.
183
184   To find the serial number from the PCI bus address, you can use the
185   following command::
186
187     # lspci -vv -s af:00.0 | grep -i Serial
188     Capabilities: [150 v1] Device Serial Number b8-87-a3-ff-ff-ca-05-68
189
190   You can use the following command to format the serial number without the
191   dashes::
192
193     # lspci -vv -s af:00.0 | grep -i Serial | awk '{print $7}' | sed s/-//g
194     b887a3ffffca0568
195
1963. Copy the renamed DDP package file to
197   ``/lib/firmware/updates/intel/ice/ddp/``. If the directory does not yet
198   exist, create it before copying the file.
199
2004. Unload all of the PFs on the device.
201
2025. Reload the driver with the new package.
203
204NOTE: The presence of a device-specific DDP package file overrides the loading
205of the default DDP package file (ice.pkg).
206
207
208Intel(R) Ethernet Flow Director
209-------------------------------
210The Intel Ethernet Flow Director performs the following tasks:
211
212- Directs receive packets according to their flows to different queues
213- Enables tight control on routing a flow in the platform
214- Matches flows and CPU cores for flow affinity
215
216NOTE: This driver supports the following flow types:
217
218- IPv4
219- TCPv4
220- UDPv4
221- SCTPv4
222- IPv6
223- TCPv6
224- UDPv6
225- SCTPv6
226
227Each flow type supports valid combinations of IP addresses (source or
228destination) and UDP/TCP/SCTP ports (source and destination). You can supply
229only a source IP address, a source IP address and a destination port, or any
230combination of one or more of these four parameters.
231
232NOTE: This driver allows you to filter traffic based on a user-defined flexible
233two-byte pattern and offset by using the ethtool user-def and mask fields. Only
234L3 and L4 flow types are supported for user-defined flexible filters. For a
235given flow type, you must clear all Intel Ethernet Flow Director filters before
236changing the input set (for that flow type).
237
238
239Flow Director Filters
240---------------------
241Flow Director filters are used to direct traffic that matches specified
242characteristics. They are enabled through ethtool's ntuple interface. To enable
243or disable the Intel Ethernet Flow Director and these filters::
244
245  # ethtool -K <ethX> ntuple <off|on>
246
247NOTE: When you disable ntuple filters, all the user programmed filters are
248flushed from the driver cache and hardware. All needed filters must be re-added
249when ntuple is re-enabled.
250
251To display all of the active filters::
252
253  # ethtool -u <ethX>
254
255To add a new filter::
256
257  # ethtool -U <ethX> flow-type <type> src-ip <ip> [m <ip_mask>] dst-ip <ip>
258  [m <ip_mask>] src-port <port> [m <port_mask>] dst-port <port> [m <port_mask>]
259  action <queue>
260
261  Where:
262    <ethX> - the Ethernet device to program
263    <type> - can be ip4, tcp4, udp4, sctp4, ip6, tcp6, udp6, sctp6
264    <ip> - the IP address to match on
265    <ip_mask> - the IPv4 address to mask on
266              NOTE: These filters use inverted masks.
267    <port> - the port number to match on
268    <port_mask> - the 16-bit integer for masking
269              NOTE: These filters use inverted masks.
270    <queue> - the queue to direct traffic toward (-1 discards the
271              matched traffic)
272
273To delete a filter::
274
275  # ethtool -U <ethX> delete <N>
276
277  Where <N> is the filter ID displayed when printing all the active filters,
278  and may also have been specified using "loc <N>" when adding the filter.
279
280EXAMPLES:
281
282To add a filter that directs packet to queue 2::
283
284  # ethtool -U <ethX> flow-type tcp4 src-ip 192.168.10.1 dst-ip \
285  192.168.10.2 src-port 2000 dst-port 2001 action 2 [loc 1]
286
287To set a filter using only the source and destination IP address::
288
289  # ethtool -U <ethX> flow-type tcp4 src-ip 192.168.10.1 dst-ip \
290  192.168.10.2 action 2 [loc 1]
291
292To set a filter based on a user-defined pattern and offset::
293
294  # ethtool -U <ethX> flow-type tcp4 src-ip 192.168.10.1 dst-ip \
295  192.168.10.2 user-def 0x4FFFF action 2 [loc 1]
296
297  where the value of the user-def field contains the offset (4 bytes) and
298  the pattern (0xffff).
299
300To match TCP traffic sent from 192.168.0.1, port 5300, directed to 192.168.0.5,
301port 80, and then send it to queue 7::
302
303  # ethtool -U enp130s0 flow-type tcp4 src-ip 192.168.0.1 dst-ip 192.168.0.5
304  src-port 5300 dst-port 80 action 7
305
306To add a TCPv4 filter with a partial mask for a source IP subnet::
307
308  # ethtool -U <ethX> flow-type tcp4 src-ip 192.168.0.0 m 0.255.255.255 dst-ip
309  192.168.5.12 src-port 12600 dst-port 31 action 12
310
311NOTES:
312
313For each flow-type, the programmed filters must all have the same matching
314input set. For example, issuing the following two commands is acceptable::
315
316  # ethtool -U enp130s0 flow-type ip4 src-ip 192.168.0.1 src-port 5300 action 7
317  # ethtool -U enp130s0 flow-type ip4 src-ip 192.168.0.5 src-port 55 action 10
318
319Issuing the next two commands, however, is not acceptable, since the first
320specifies src-ip and the second specifies dst-ip::
321
322  # ethtool -U enp130s0 flow-type ip4 src-ip 192.168.0.1 src-port 5300 action 7
323  # ethtool -U enp130s0 flow-type ip4 dst-ip 192.168.0.5 src-port 55 action 10
324
325The second command will fail with an error. You may program multiple filters
326with the same fields, using different values, but, on one device, you may not
327program two tcp4 filters with different matching fields.
328
329The ice driver does not support matching on a subportion of a field, thus
330partial mask fields are not supported.
331
332
333Flex Byte Flow Director Filters
334-------------------------------
335The driver also supports matching user-defined data within the packet payload.
336This flexible data is specified using the "user-def" field of the ethtool
337command in the following way:
338
339.. table::
340
341    ============================== ============================
342    ``31    28    24    20    16`` ``15    12    8    4    0``
343    ``offset into packet payload`` ``2 bytes of flexible data``
344    ============================== ============================
345
346For example,
347
348::
349
350  ... user-def 0x4FFFF ...
351
352tells the filter to look 4 bytes into the payload and match that value against
3530xFFFF. The offset is based on the beginning of the payload, and not the
354beginning of the packet. Thus
355
356::
357
358  flow-type tcp4 ... user-def 0x8BEAF ...
359
360would match TCP/IPv4 packets which have the value 0xBEAF 8 bytes into the
361TCP/IPv4 payload.
362
363Note that ICMP headers are parsed as 4 bytes of header and 4 bytes of payload.
364Thus to match the first byte of the payload, you must actually add 4 bytes to
365the offset. Also note that ip4 filters match both ICMP frames as well as raw
366(unknown) ip4 frames, where the payload will be the L3 payload of the IP4
367frame.
368
369The maximum offset is 64. The hardware will only read up to 64 bytes of data
370from the payload. The offset must be even because the flexible data is 2 bytes
371long and must be aligned to byte 0 of the packet payload.
372
373The user-defined flexible offset is also considered part of the input set and
374cannot be programmed separately for multiple filters of the same type. However,
375the flexible data is not part of the input set and multiple filters may use the
376same offset but match against different data.
377
378
379RSS Hash Flow
380-------------
381Allows you to set the hash bytes per flow type and any combination of one or
382more options for Receive Side Scaling (RSS) hash byte configuration.
383
384::
385
386  # ethtool -N <ethX> rx-flow-hash <type> <option>
387
388  Where <type> is:
389    tcp4  signifying TCP over IPv4
390    udp4  signifying UDP over IPv4
391    tcp6  signifying TCP over IPv6
392    udp6  signifying UDP over IPv6
393  And <option> is one or more of:
394    s     Hash on the IP source address of the Rx packet.
395    d     Hash on the IP destination address of the Rx packet.
396    f     Hash on bytes 0 and 1 of the Layer 4 header of the Rx packet.
397    n     Hash on bytes 2 and 3 of the Layer 4 header of the Rx packet.
398
399
400Accelerated Receive Flow Steering (aRFS)
401----------------------------------------
402Devices based on the Intel(R) Ethernet Controller 800 Series support
403Accelerated Receive Flow Steering (aRFS) on the PF. aRFS is a load-balancing
404mechanism that allows you to direct packets to the same CPU where an
405application is running or consuming the packets in that flow.
406
407NOTES:
408
409- aRFS requires that ntuple filtering is enabled via ethtool.
410- aRFS support is limited to the following packet types:
411
412    - TCP over IPv4 and IPv6
413    - UDP over IPv4 and IPv6
414    - Nonfragmented packets
415
416- aRFS only supports Flow Director filters, which consist of the
417  source/destination IP addresses and source/destination ports.
418- aRFS and ethtool's ntuple interface both use the device's Flow Director. aRFS
419  and ntuple features can coexist, but you may encounter unexpected results if
420  there's a conflict between aRFS and ntuple requests. See "Intel(R) Ethernet
421  Flow Director" for additional information.
422
423To set up aRFS:
424
4251. Enable the Intel Ethernet Flow Director and ntuple filters using ethtool.
426
427::
428
429   # ethtool -K <ethX> ntuple on
430
4312. Set up the number of entries in the global flow table. For example:
432
433::
434
435   # NUM_RPS_ENTRIES=16384
436   # echo $NUM_RPS_ENTRIES > /proc/sys/net/core/rps_sock_flow_entries
437
4383. Set up the number of entries in the per-queue flow table. For example:
439
440::
441
442   # NUM_RX_QUEUES=64
443   # for file in /sys/class/net/$IFACE/queues/rx-*/rps_flow_cnt; do
444   # echo $(($NUM_RPS_ENTRIES/$NUM_RX_QUEUES)) > $file;
445   # done
446
4474. Disable the IRQ balance daemon (this is only a temporary stop of the service
448   until the next reboot).
449
450::
451
452   # systemctl stop irqbalance
453
4545. Configure the interrupt affinity.
455
456   See ``/Documentation/core-api/irq/irq-affinity.rst``
457
458
459To disable aRFS using ethtool::
460
461  # ethtool -K <ethX> ntuple off
462
463NOTE: This command will disable ntuple filters and clear any aRFS filters in
464software and hardware.
465
466Example Use Case:
467
4681. Set the server application on the desired CPU (e.g., CPU 4).
469
470::
471
472   # taskset -c 4 netserver
473
4742. Use netperf to route traffic from the client to CPU 4 on the server with
475   aRFS configured. This example uses TCP over IPv4.
476
477::
478
479   # netperf -H <Host IPv4 Address> -t TCP_STREAM
480
481
482Enabling Virtual Functions (VFs)
483--------------------------------
484Use sysfs to enable virtual functions (VF).
485
486For example, you can create 4 VFs as follows::
487
488  # echo 4 > /sys/class/net/<ethX>/device/sriov_numvfs
489
490To disable VFs, write 0 to the same file::
491
492  # echo 0 > /sys/class/net/<ethX>/device/sriov_numvfs
493
494The maximum number of VFs for the ice driver is 256 total (all ports). To check
495how many VFs each PF supports, use the following command::
496
497  # cat /sys/class/net/<ethX>/device/sriov_totalvfs
498
499Note: You cannot use SR-IOV when link aggregation (LAG)/bonding is active, and
500vice versa. To enforce this, the driver checks for this mutual exclusion.
501
502
503Displaying VF Statistics on the PF
504----------------------------------
505Use the following command to display the statistics for the PF and its VFs::
506
507  # ip -s link show dev <ethX>
508
509NOTE: The output of this command can be very large due to the maximum number of
510possible VFs.
511
512The PF driver will display a subset of the statistics for the PF and for all
513VFs that are configured. The PF will always print a statistics block for each
514of the possible VFs, and it will show zero for all unconfigured VFs.
515
516
517Configuring VLAN Tagging on SR-IOV Enabled Adapter Ports
518--------------------------------------------------------
519To configure VLAN tagging for the ports on an SR-IOV enabled adapter, use the
520following command. The VLAN configuration should be done before the VF driver
521is loaded or the VM is booted. The VF is not aware of the VLAN tag being
522inserted on transmit and removed on received frames (sometimes called "port
523VLAN" mode).
524
525::
526
527  # ip link set dev <ethX> vf <id> vlan <vlan id>
528
529For example, the following will configure PF eth0 and the first VF on VLAN 10::
530
531  # ip link set dev eth0 vf 0 vlan 10
532
533
534Enabling a VF link if the port is disconnected
535----------------------------------------------
536If the physical function (PF) link is down, you can force link up (from the
537host PF) on any virtual functions (VF) bound to the PF.
538
539For example, to force link up on VF 0 bound to PF eth0::
540
541  # ip link set eth0 vf 0 state enable
542
543Note: If the command does not work, it may not be supported by your system.
544
545
546Setting the MAC Address for a VF
547--------------------------------
548To change the MAC address for the specified VF::
549
550  # ip link set <ethX> vf 0 mac <address>
551
552For example::
553
554  # ip link set <ethX> vf 0 mac 00:01:02:03:04:05
555
556This setting lasts until the PF is reloaded.
557
558NOTE: Assigning a MAC address for a VF from the host will disable any
559subsequent requests to change the MAC address from within the VM. This is a
560security feature. The VM is not aware of this restriction, so if this is
561attempted in the VM, it will trigger MDD events.
562
563
564Trusted VFs and VF Promiscuous Mode
565-----------------------------------
566This feature allows you to designate a particular VF as trusted and allows that
567trusted VF to request selective promiscuous mode on the Physical Function (PF).
568
569To set a VF as trusted or untrusted, enter the following command in the
570Hypervisor::
571
572  # ip link set dev <ethX> vf 1 trust [on|off]
573
574NOTE: It's important to set the VF to trusted before setting promiscuous mode.
575If the VM is not trusted, the PF will ignore promiscuous mode requests from the
576VF. If the VM becomes trusted after the VF driver is loaded, you must make a
577new request to set the VF to promiscuous.
578
579Once the VF is designated as trusted, use the following commands in the VM to
580set the VF to promiscuous mode.
581
582For promiscuous all::
583
584  # ip link set <ethX> promisc on
585  Where <ethX> is a VF interface in the VM
586
587For promiscuous Multicast::
588
589  # ip link set <ethX> allmulticast on
590  Where <ethX> is a VF interface in the VM
591
592NOTE: By default, the ethtool private flag vf-true-promisc-support is set to
593"off," meaning that promiscuous mode for the VF will be limited. To set the
594promiscuous mode for the VF to true promiscuous and allow the VF to see all
595ingress traffic, use the following command::
596
597  # ethtool --set-priv-flags <ethX> vf-true-promisc-support on
598
599The vf-true-promisc-support private flag does not enable promiscuous mode;
600rather, it designates which type of promiscuous mode (limited or true) you will
601get when you enable promiscuous mode using the ip link commands above. Note
602that this is a global setting that affects the entire device. However, the
603vf-true-promisc-support private flag is only exposed to the first PF of the
604device. The PF remains in limited promiscuous mode regardless of the
605vf-true-promisc-support setting.
606
607Next, add a VLAN interface on the VF interface. For example::
608
609  # ip link add link eth2 name eth2.100 type vlan id 100
610
611Note that the order in which you set the VF to promiscuous mode and add the
612VLAN interface does not matter (you can do either first). The result in this
613example is that the VF will get all traffic that is tagged with VLAN 100.
614
615
616Malicious Driver Detection (MDD) for VFs
617----------------------------------------
618Some Intel Ethernet devices use Malicious Driver Detection (MDD) to detect
619malicious traffic from the VF and disable Tx/Rx queues or drop the offending
620packet until a VF driver reset occurs. You can view MDD messages in the PF's
621system log using the dmesg command.
622
623- If the PF driver logs MDD events from the VF, confirm that the correct VF
624  driver is installed.
625- To restore functionality, you can manually reload the VF or VM or enable
626  automatic VF resets.
627- When automatic VF resets are enabled, the PF driver will immediately reset
628  the VF and reenable queues when it detects MDD events on the receive path.
629- If automatic VF resets are disabled, the PF will not automatically reset the
630  VF when it detects MDD events.
631
632To enable or disable automatic VF resets, use the following command::
633
634  # ethtool --set-priv-flags <ethX> mdd-auto-reset-vf on|off
635
636
637MAC and VLAN Anti-Spoofing Feature for VFs
638------------------------------------------
639When a malicious driver on a Virtual Function (VF) interface attempts to send a
640spoofed packet, it is dropped by the hardware and not transmitted.
641
642NOTE: This feature can be disabled for a specific VF::
643
644  # ip link set <ethX> vf <vf id> spoofchk {off|on}
645
646
647Jumbo Frames
648------------
649Jumbo Frames support is enabled by changing the Maximum Transmission Unit (MTU)
650to a value larger than the default value of 1500.
651
652Use the ifconfig command to increase the MTU size. For example, enter the
653following where <ethX> is the interface number::
654
655  # ifconfig <ethX> mtu 9000 up
656
657Alternatively, you can use the ip command as follows::
658
659  # ip link set mtu 9000 dev <ethX>
660  # ip link set up dev <ethX>
661
662This setting is not saved across reboots.
663
664
665NOTE: The maximum MTU setting for jumbo frames is 9702. This corresponds to the
666maximum jumbo frame size of 9728 bytes.
667
668NOTE: This driver will attempt to use multiple page sized buffers to receive
669each jumbo packet. This should help to avoid buffer starvation issues when
670allocating receive packets.
671
672NOTE: Packet loss may have a greater impact on throughput when you use jumbo
673frames. If you observe a drop in performance after enabling jumbo frames,
674enabling flow control may mitigate the issue.
675
676
677Speed and Duplex Configuration
678------------------------------
679In addressing speed and duplex configuration issues, you need to distinguish
680between copper-based adapters and fiber-based adapters.
681
682In the default mode, an Intel(R) Ethernet Network Adapter using copper
683connections will attempt to auto-negotiate with its link partner to determine
684the best setting. If the adapter cannot establish link with the link partner
685using auto-negotiation, you may need to manually configure the adapter and link
686partner to identical settings to establish link and pass packets. This should
687only be needed when attempting to link with an older switch that does not
688support auto-negotiation or one that has been forced to a specific speed or
689duplex mode. Your link partner must match the setting you choose. 1 Gbps speeds
690and higher cannot be forced. Use the autonegotiation advertising setting to
691manually set devices for 1 Gbps and higher.
692
693Speed, duplex, and autonegotiation advertising are configured through the
694ethtool utility. For the latest version, download and install ethtool from the
695following website:
696
697   https://kernel.org/pub/software/network/ethtool/
698
699To see the speed configurations your device supports, run the following::
700
701  # ethtool <ethX>
702
703Caution: Only experienced network administrators should force speed and duplex
704or change autonegotiation advertising manually. The settings at the switch must
705always match the adapter settings. Adapter performance may suffer or your
706adapter may not operate if you configure the adapter differently from your
707switch.
708
709
710Data Center Bridging (DCB)
711--------------------------
712NOTE: The kernel assumes that TC0 is available, and will disable Priority Flow
713Control (PFC) on the device if TC0 is not available. To fix this, ensure TC0 is
714enabled when setting up DCB on your switch.
715
716DCB is a configuration Quality of Service implementation in hardware. It uses
717the VLAN priority tag (802.1p) to filter traffic. That means that there are 8
718different priorities that traffic can be filtered into. It also enables
719priority flow control (802.1Qbb) which can limit or eliminate the number of
720dropped packets during network stress. Bandwidth can be allocated to each of
721these priorities, which is enforced at the hardware level (802.1Qaz).
722
723DCB is normally configured on the network using the DCBX protocol (802.1Qaz), a
724specialization of LLDP (802.1AB). The ice driver supports the following
725mutually exclusive variants of DCBX support:
726
7271) Firmware-based LLDP Agent
7282) Software-based LLDP Agent
729
730In firmware-based mode, firmware intercepts all LLDP traffic and handles DCBX
731negotiation transparently for the user. In this mode, the adapter operates in
732"willing" DCBX mode, receiving DCB settings from the link partner (typically a
733switch). The local user can only query the negotiated DCB configuration. For
734information on configuring DCBX parameters on a switch, please consult the
735switch manufacturer's documentation.
736
737In software-based mode, LLDP traffic is forwarded to the network stack and user
738space, where a software agent can handle it. In this mode, the adapter can
739operate in either "willing" or "nonwilling" DCBX mode and DCB configuration can
740be both queried and set locally. This mode requires the FW-based LLDP Agent to
741be disabled.
742
743NOTE:
744
745- You can enable and disable the firmware-based LLDP Agent using an ethtool
746  private flag. Refer to the "FW-LLDP (Firmware Link Layer Discovery Protocol)"
747  section in this README for more information.
748- In software-based DCBX mode, you can configure DCB parameters using software
749  LLDP/DCBX agents that interface with the Linux kernel's DCB Netlink API. We
750  recommend using OpenLLDP as the DCBX agent when running in software mode. For
751  more information, see the OpenLLDP man pages and
752  https://github.com/intel/openlldp.
753- The driver implements the DCB netlink interface layer to allow the user space
754  to communicate with the driver and query DCB configuration for the port.
755- iSCSI with DCB is not supported.
756
757
758FW-LLDP (Firmware Link Layer Discovery Protocol)
759------------------------------------------------
760Use ethtool to change FW-LLDP settings. The FW-LLDP setting is per port and
761persists across boots.
762
763To enable LLDP::
764
765  # ethtool --set-priv-flags <ethX> fw-lldp-agent on
766
767To disable LLDP::
768
769  # ethtool --set-priv-flags <ethX> fw-lldp-agent off
770
771To check the current LLDP setting::
772
773  # ethtool --show-priv-flags <ethX>
774
775NOTE: You must enable the UEFI HII "LLDP Agent" attribute for this setting to
776take effect. If "LLDP AGENT" is set to disabled, you cannot enable it from the
777OS.
778
779
780Flow Control
781------------
782Ethernet Flow Control (IEEE 802.3x) can be configured with ethtool to enable
783receiving and transmitting pause frames for ice. When transmit is enabled,
784pause frames are generated when the receive packet buffer crosses a predefined
785threshold. When receive is enabled, the transmit unit will halt for the time
786delay specified when a pause frame is received.
787
788NOTE: You must have a flow control capable link partner.
789
790Flow Control is disabled by default.
791
792Use ethtool to change the flow control settings.
793
794To enable or disable Rx or Tx Flow Control::
795
796  # ethtool -A <ethX> rx <on|off> tx <on|off>
797
798Note: This command only enables or disables Flow Control if auto-negotiation is
799disabled. If auto-negotiation is enabled, this command changes the parameters
800used for auto-negotiation with the link partner.
801
802Note: Flow Control auto-negotiation is part of link auto-negotiation. Depending
803on your device, you may not be able to change the auto-negotiation setting.
804
805NOTE:
806
807- The ice driver requires flow control on both the port and link partner. If
808  flow control is disabled on one of the sides, the port may appear to hang on
809  heavy traffic.
810- You may encounter issues with link-level flow control (LFC) after disabling
811  DCB. The LFC status may show as enabled but traffic is not paused. To resolve
812  this issue, disable and reenable LFC using ethtool::
813
814   # ethtool -A <ethX> rx off tx off
815   # ethtool -A <ethX> rx on tx on
816
817
818NAPI
819----
820This driver supports NAPI (Rx polling mode).
821For more information on NAPI, see
822https://wiki.linuxfoundation.org/networking/napi
823
824
825MACVLAN
826-------
827This driver supports MACVLAN. Kernel support for MACVLAN can be tested by
828checking if the MACVLAN driver is loaded. You can run 'lsmod | grep macvlan' to
829see if the MACVLAN driver is loaded or run 'modprobe macvlan' to try to load
830the MACVLAN driver.
831
832NOTE:
833
834- In passthru mode, you can only set up one MACVLAN device. It will inherit the
835  MAC address of the underlying PF (Physical Function) device.
836
837
838IEEE 802.1ad (QinQ) Support
839---------------------------
840The IEEE 802.1ad standard, informally known as QinQ, allows for multiple VLAN
841IDs within a single Ethernet frame. VLAN IDs are sometimes referred to as
842"tags," and multiple VLAN IDs are thus referred to as a "tag stack." Tag stacks
843allow L2 tunneling and the ability to segregate traffic within a particular
844VLAN ID, among other uses.
845
846NOTES:
847
848- Receive checksum offloads and VLAN acceleration are not supported for 802.1ad
849  (QinQ) packets.
850
851- 0x88A8 traffic will not be received unless VLAN stripping is disabled with
852  the following command::
853
854    # ethtool -K <ethX> rxvlan off
855
856- 0x88A8/0x8100 double VLANs cannot be used with 0x8100 or 0x8100/0x8100 VLANS
857  configured on the same port. 0x88a8/0x8100 traffic will not be received if
858  0x8100 VLANs are configured.
859
860- The VF can only transmit 0x88A8/0x8100 (i.e., 802.1ad/802.1Q) traffic if:
861
862    1) The VF is not assigned a port VLAN.
863    2) spoofchk is disabled from the PF. If you enable spoofchk, the VF will
864       not transmit 0x88A8/0x8100 traffic.
865
866- The VF may not receive all network traffic based on the Inner VLAN header
867  when VF true promiscuous mode (vf-true-promisc-support) and double VLANs are
868  enabled in SR-IOV mode.
869
870The following are examples of how to configure 802.1ad (QinQ)::
871
872  # ip link add link eth0 eth0.24 type vlan proto 802.1ad id 24
873  # ip link add link eth0.24 eth0.24.371 type vlan proto 802.1Q id 371
874
875  Where "24" and "371" are example VLAN IDs.
876
877
878Tunnel/Overlay Stateless Offloads
879---------------------------------
880Supported tunnels and overlays include VXLAN, GENEVE, and others depending on
881hardware and software configuration. Stateless offloads are enabled by default.
882
883To view the current state of all offloads::
884
885  # ethtool -k <ethX>
886
887
888UDP Segmentation Offload
889------------------------
890Allows the adapter to offload transmit segmentation of UDP packets with
891payloads up to 64K into valid Ethernet frames. Because the adapter hardware is
892able to complete data segmentation much faster than operating system software,
893this feature may improve transmission performance.
894In addition, the adapter may use fewer CPU resources.
895
896NOTE:
897
898- The application sending UDP packets must support UDP segmentation offload.
899
900To enable/disable UDP Segmentation Offload, issue the following command::
901
902  # ethtool -K <ethX> tx-udp-segmentation [off|on]
903
904
905GNSS module
906-----------
907Requires kernel compiled with CONFIG_GNSS=y or CONFIG_GNSS=m.
908Allows user to read messages from the GNSS hardware module and write supported
909commands. If the module is physically present, a GNSS device is spawned:
910``/dev/gnss<id>``.
911The protocol of write command is dependent on the GNSS hardware module as the
912driver writes raw bytes by the GNSS object to the receiver through i2c. Please
913refer to the hardware GNSS module documentation for configuration details.
914
915
916Performance Optimization
917========================
918Driver defaults are meant to fit a wide variety of workloads, but if further
919optimization is required, we recommend experimenting with the following
920settings.
921
922
923Rx Descriptor Ring Size
924-----------------------
925To reduce the number of Rx packet discards, increase the number of Rx
926descriptors for each Rx ring using ethtool.
927
928  Check if the interface is dropping Rx packets due to buffers being full
929  (rx_dropped.nic can mean that there is no PCIe bandwidth)::
930
931    # ethtool -S <ethX> | grep "rx_dropped"
932
933  If the previous command shows drops on queues, it may help to increase
934  the number of descriptors using 'ethtool -G'::
935
936    # ethtool -G <ethX> rx <N>
937    Where <N> is the desired number of ring entries/descriptors
938
939  This can provide temporary buffering for issues that create latency while
940  the CPUs process descriptors.
941
942
943Interrupt Rate Limiting
944-----------------------
945This driver supports an adaptive interrupt throttle rate (ITR) mechanism that
946is tuned for general workloads. The user can customize the interrupt rate
947control for specific workloads, via ethtool, adjusting the number of
948microseconds between interrupts.
949
950To set the interrupt rate manually, you must disable adaptive mode::
951
952  # ethtool -C <ethX> adaptive-rx off adaptive-tx off
953
954For lower CPU utilization:
955
956  Disable adaptive ITR and lower Rx and Tx interrupts. The examples below
957  affect every queue of the specified interface.
958
959  Setting rx-usecs and tx-usecs to 80 will limit interrupts to about
960  12,500 interrupts per second per queue::
961
962    # ethtool -C <ethX> adaptive-rx off adaptive-tx off rx-usecs 80 tx-usecs 80
963
964For reduced latency:
965
966  Disable adaptive ITR and ITR by setting rx-usecs and tx-usecs to 0
967  using ethtool::
968
969    # ethtool -C <ethX> adaptive-rx off adaptive-tx off rx-usecs 0 tx-usecs 0
970
971Per-queue interrupt rate settings:
972
973  The following examples are for queues 1 and 3, but you can adjust other
974  queues.
975
976  To disable Rx adaptive ITR and set static Rx ITR to 10 microseconds or
977  about 100,000 interrupts/second, for queues 1 and 3::
978
979    # ethtool --per-queue <ethX> queue_mask 0xa --coalesce adaptive-rx off
980    rx-usecs 10
981
982  To show the current coalesce settings for queues 1 and 3::
983
984    # ethtool --per-queue <ethX> queue_mask 0xa --show-coalesce
985
986Bounding interrupt rates using rx-usecs-high:
987
988  :Valid Range: 0-236 (0=no limit)
989
990   The range of 0-236 microseconds provides an effective range of 4,237 to
991   250,000 interrupts per second. The value of rx-usecs-high can be set
992   independently of rx-usecs and tx-usecs in the same ethtool command, and is
993   also independent of the adaptive interrupt moderation algorithm. The
994   underlying hardware supports granularity in 4-microsecond intervals, so
995   adjacent values may result in the same interrupt rate.
996
997  The following command would disable adaptive interrupt moderation, and allow
998  a maximum of 5 microseconds before indicating a receive or transmit was
999  complete. However, instead of resulting in as many as 200,000 interrupts per
1000  second, it limits total interrupts per second to 50,000 via the rx-usecs-high
1001  parameter.
1002
1003  ::
1004
1005    # ethtool -C <ethX> adaptive-rx off adaptive-tx off rx-usecs-high 20
1006    rx-usecs 5 tx-usecs 5
1007
1008
1009Virtualized Environments
1010------------------------
1011In addition to the other suggestions in this section, the following may be
1012helpful to optimize performance in VMs.
1013
1014  Using the appropriate mechanism (vcpupin) in the VM, pin the CPUs to
1015  individual LCPUs, making sure to use a set of CPUs included in the
1016  device's local_cpulist: ``/sys/class/net/<ethX>/device/local_cpulist``.
1017
1018  Configure as many Rx/Tx queues in the VM as available. (See the iavf driver
1019  documentation for the number of queues supported.) For example::
1020
1021    # ethtool -L <virt_interface> rx <max> tx <max>
1022
1023
1024Support
1025=======
1026For general information, go to the Intel support website at:
1027https://www.intel.com/support/
1028
1029or the Intel Wired Networking project hosted by Sourceforge at:
1030https://sourceforge.net/projects/e1000
1031
1032If an issue is identified with the released source code on a supported kernel
1033with a supported adapter, email the specific information related to the issue
1034to e1000-devel@lists.sf.net.
1035
1036
1037Trademarks
1038==========
1039Intel is a trademark or registered trademark of Intel Corporation or its
1040subsidiaries in the United States and/or other countries.
1041
1042* Other names and brands may be claimed as the property of others.
1043