From mboxrd@z Thu Jan 1 00:00:00 1970 From: Shannon Nelson Date: Thu, 11 Oct 2018 09:41:02 -0700 Subject: [Intel-wired-lan] [PATCH v2 08/12] Documentation: i40e: Prepare documentation for RST conversion In-Reply-To: <20181010191613.2770-9-jeffrey.t.kirsher@intel.com> References: <20181010191613.2770-1-jeffrey.t.kirsher@intel.com> <20181010191613.2770-9-jeffrey.t.kirsher@intel.com> Message-ID: <3e65b77a-67af-eff5-7296-654038634a00@oracle.com> MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit To: intel-wired-lan@osuosl.org List-ID: On 10/10/2018 12:16 PM, Jeff Kirsher wrote: > Before making the conversion to the rst (reStructured Text) format, there > are changes needed to the documentation so that there are no build errors. > > Also fixed old/broken URLs to the correct or updated URL. > > Signed-off-by: Jeff Kirsher > --- > Documentation/networking/i40e.txt | 837 +++++++++++++++++++++++++----- > 1 file changed, 714 insertions(+), 123 deletions(-) > > diff --git a/Documentation/networking/i40e.txt b/Documentation/networking/i40e.txt > index c2d6e1824b29..f0c3c8c9d324 100644 > --- a/Documentation/networking/i40e.txt > +++ b/Documentation/networking/i40e.txt > @@ -1,190 +1,781 @@ > -Linux Base Driver for the Intel(R) Ethernet Controller XL710 Family > -=================================================================== > +.. SPDX-License-Identifier: GPL-2.0+ > > -Intel i40e Linux driver. > -Copyright(c) 2013 Intel Corporation. > +Linux* Base Driver for the Intel(R) Ethernet Controller 700 Series > +================================================================== > + > +Intel 40 Gigabit Linux driver. > +Copyright(c) 1999-2018 Intel Corporation. > > Contents > ======== > > +- Overview > - Identifying Your Adapter > +- Intel(R) Ethernet Flow Director > - Additional Configurations > -- Performance Tuning > - Known Issues > - Support > > > +Driver information can be obtained using ethtool, lspci, and ifconfig. > +Instructions on updating ethtool can be found in the section Additional > +Configurations later in this document. > + > +For questions related to hardware requirements, refer to the documentation > +supplied with your Intel adapter. All hardware requirements listed apply to use > +with Linux. > + > + > Identifying Your Adapter > ======================== > +The driver is compatible with devices based on the following: > + > + * Intel(R) Ethernet Controller X710 > + * Intel(R) Ethernet Controller XL710 > + * Intel(R) Ethernet Network Connection X722 > + * Intel(R) Ethernet Controller XXV710 > + > +For the best performance, make sure the latest NVM/FW is installed on your > +device. > + > +For information on how to identify your adapter, and for the latest NVM/FW > +images and Intel network drivers, refer to the Intel Support website: > +https://www.intel.com/support > + > +SFP+ and QSFP+ Devices > +---------------------- > +For information about supported media, refer to this document: > +https://www.intel.com/content/dam/www/public/us/en/documents/release-notes/xl710-ethernet-controller-feature-matrix.pdf > + > +NOTE: Some adapters based on the Intel(R) Ethernet Controller 700 Series only > +support Intel Ethernet Optics modules. On these adapters, other modules are not > +supported and will not function. In all cases Intel recommends using Intel > +Ethernet Optics; other modules may function but are not validated by Intel. > +Contact Intel for supported media types. > + > +NOTE: For connections based on Intel(R) Ethernet Controller 700 Series, support > +is dependent on your system board. Please see your vendor for details. > + > +NOTE: In systems that do not have adequate airflow to cool the adapter and > +optical modules, you must use high temperature optical modules. > + > +Virtual Functions (VFs) > +----------------------- > +Use sysfs to enable VFs. For example: > +#echo $num_vf_enabled > /sys/class/net/$dev/device/sriov_numvfs #enable > +VFs > +#echo 0 > /sys/class/net/$dev/device/sriov_numvfs #disable VFs > + > +For example, the following instructions will configure PF eth0 and the first VF > +on VLAN 10:: > + > + $ ip link set dev eth0 vf 0 vlan 10 > + > +VLAN Tag Packet Steering > +------------------------ > +Allows you to send all packets with a specific VLAN tag to a particular SR-IOV > +virtual function (VF). Further, this feature allows you to designate a > +particular VF as trusted, and allows that trusted VF to request selective > +promiscuous mode on the Physical Function (PF). > + > +To set a VF as trusted or untrusted, enter the following command in the > +Hypervisor:: > + > + # ip link set dev eth0 vf 1 trust [on|off] > + > +Once the VF is designated as trusted, use the following commands in the VM to > +set the VF to promiscuous mode. > + > +:: > + > + For promiscuous all: > + #ip link set eth2 promisc on > + Where eth2 is a VF interface in the VM > + > + For promiscuous Multicast: > + #ip link set eth2 allmulticast on > + Where eth2 is a VF interface in the VM > + > +NOTE: By default, the ethtool priv-flag vf-true-promisc-support is set to > +"off",meaning that promiscuous mode for the VF will be limited. To set the > +promiscuous mode for the VF to true promiscuous and allow the VF to see all > +ingress traffic, use the following command:: > + > + #ethtool -set-priv-flags p261p1 vf-true-promisc-support on > + > +The vf-true-promisc-support priv-flag does not enable promiscuous mode; rather, > +it designates which type of promiscuous mode (limited or true) you will get > +when you enable promiscuous mode using the ip link commands above. Note that > +this is a global setting that affects the entire device. However,the > +vf-true-promisc-support priv-flag is only exposed to the first PF of the > +device. The PF remains in limited promiscuous mode (unless it is in MFP mode) > +regardless of the vf-true-promisc-support setting. > + > +Now add a VLAN interface on the VF interface:: > + > + #ip link add link eth2 name eth2.100 type vlan id 100 > + > +Note that the order in which you set the VF to promiscuous mode and add the > +VLAN interface does not matter (you can do either first). The end result in > +this example is that the VF will get all traffic that is tagged with VLAN 100. > + > +Intel(R) Ethernet Flow Director > +------------------------------- > +The Intel Ethernet Flow Director performs the following tasks: > + > +- Directs receive packets according to their flows to different queues. > +- Enables tight control on routing a flow in the platform. > +- Matches flows and CPU cores for flow affinity. > +- Supports multiple parameters for flexible flow classification and load > + balancing (in SFP mode only). > + > +NOTE: The Linux i40e driver supports the following flow types: IPv4, TCPv4, and > +UDPv4. For a given flow type, it supports valid combinations of IP addresses > +(source or destination) and UDP/TCP ports (source and destination). For > +example, you can supply only a source IP address, a source IP address and a > +destination port, or any combination of one or more of these four parameters. > + > +NOTE: The Linux i40e driver allows you to filter traffic based on a > +user-defined flexible two-byte pattern and offset by using the ethtool user-def > +and mask fields. Only L3 and L4 flow types are supported for user-defined > +flexible filters. For a given flow type, you must clear all Intel Ethernet Flow > +Director filters before changing the input set (for that flow type). > + > +To enable or disable the Intel Ethernet Flow Director:: > + > + # ethtool -K ethX ntuple > + > +When disabling ntuple filters, all the user programmed filters are flushed from > +the driver cache and hardware. All needed filters must be re-added when ntuple > +is re-enabled. > + > +To add a filter that directs packet to queue 2, use -U or -N switch:: > + > + # ethtool -N ethX flow-type tcp4 src-ip 192.168.10.1 dst-ip \ > + 192.168.10.2 src-port 2000 dst-port 2001 action 2 [loc 1] > + > +To set a filter using only the source and destination IP address:: > + > + # ethtool -N ethX flow-type tcp4 src-ip 192.168.10.1 dst-ip \ > + 192.168.10.2 action 2 [loc 1] > + > +To set a filter based on a user defined pattern and offset:: > + > + # ethtool -N ethX flow-type tcp4 src-ip 192.168.10.1 dst-ip \ > + 192.168.10.2 user-def 0xffffffff00000001 m 0x40 action 2 [loc 1] > + > +Where the value of the user-def field (0xffffffff00000001) is the pattern and > +"m" 0x40 is the offset. Repeating earlier comments: 0xffffffff00000001 is certainly not a two-byte pattern. Can you explain this a little better? Is 0x0001 the two-byte pattern being set up here with all the 0xffffffff0000 being scaffolding? Also, has anyone tested this lately? I haven't, but I'm not so sure this is what the code in i40e_parse_rx_flow_user_data() is doing. Actually, the detail below in the Sideband section that talks about "... user-def 0x4FFFF ..." looks much more correct, so why is this stuff here? > + > +Note that in this case, the mask (m 0x40) parameter is used with the user-def > +field, whereas for cloud filter support the mask parameter is not used. > + > +To see the list of filters currently present:: > + > + # ethtool <-u|-n> ethX > + > +Application Targeted Routing (ATR) Perfect Filters > +-------------------------------------------------- > +ATR is enabled by default when the kernel is in multiple transmit queue mode. > +An ATR Intel Ethernet Flow Director filter rule is added when a TCP-IP flow > +starts and is deleted when the flow ends. When a TCP-IP Intel Ethernet Flow > +Director rule is added from ethtool (Sideband filter), ATR is turned off by the > +driver. To re-enable ATR, the sideband can be disabled with the ethtool -K > +option. For example:: > + > + ethtool ?K [adapter] ntuple [off|on] > + > +If sideband is re-enabled after ATR is re-enabled, ATR remains enabled until a > +TCP-IP flow is added. When all TCP-IP sideband rules are deleted, ATR is > +automatically re-enabled. > + > +Packets that match the ATR rules are counted in fdir_atr_match stats in > +ethtool, which also can be used to verify whether ATR rules still exist. > + > +Sideband Perfect Filters > +------------------------ > +Sideband Perfect Filters are used to direct traffic that matches specified > +characteristics. They are enabled through ethtool's ntuple interface. To add a > +new filter use the following command:: > + > + ethtool -U flow-type src-ip dst-ip src-port \ > + dst-port action > + > +Where: > + - the ethernet device to program > + - can be ip4, tcp4, udp4, or sctp4 > + - the ip address to match on > + - the port number to match on > + - the queue to direct traffic towards (-1 discards the matched traffic) > + > +Use the following command to display all of the active filters:: > + > + ethtool -u > + > +Use the following command to delete a filter:: > + > + ethtool -U delete > + > +Where is the filter id displayed when printing all the active filters, and > +may also have been specified using "loc " when adding the filter. > + > +The following example matches TCP traffic sent from 192.168.0.1, port 5300, > +directed to 192.168.0.5, port 80, and sends it to queue 7:: > + > + ethtool -U enp130s0 flow-type tcp4 src-ip 192.168.0.1 dst-ip 192.168.0.5 \ > + src-port 5300 dst-port 80 action 7 > > -The driver in this release is compatible with the Intel Ethernet > -Controller XL710 Family. > +For each flow-type, the programmed filters must all have the same matching > +input set. For example, issuing the following two commands is acceptable:: > > -For more information on how to identify your adapter, go to the Adapter & > -Driver ID Guide at: > + ethtool -U enp130s0 flow-type ip4 src-ip 192.168.0.1 src-port 5300 action 7 > + ethtool -U enp130s0 flow-type ip4 src-ip 192.168.0.5 src-port 55 action 10 > > - http://support.intel.com/support/network/sb/CS-012904.htm > +Issuing the next two commands, however, is not acceptable, since the first > +specifies src-ip and the second specifies dst-ip:: > > + ethtool -U enp130s0 flow-type ip4 src-ip 192.168.0.1 src-port 5300 action 7 > + ethtool -U enp130s0 flow-type ip4 dst-ip 192.168.0.5 src-port 55 action 10 > > -Enabling the driver > -=================== > +The second command will fail with an error. You may program multiple filters > +with the same fields, using different values, but, on one device, you may not > +program two tcp4 filters with different matching fields. > > -The driver is enabled via the standard kernel configuration system, > -using the make command: > +Matching on a sub-portion of a field is not supported by the i40e driver, thus > +partial mask fields are not supported. > > - make config/oldconfig/menuconfig/etc. > +The driver also supports matching user-defined data within the packet payload. > +This flexible data is specified using the "user-def" field of the ethtool > +command in the following way: > > -The driver is located in the menu structure at: > ++----------------------------+--------------------------+ > +| 31 28 24 20 16 | 15 12 8 4 0 | > ++----------------------------+--------------------------+ > +| offset into packet payload | 2 bytes of flexible data | > ++----------------------------+--------------------------+ > > - -> Device Drivers > - -> Network device support (NETDEVICES [=y]) > - -> Ethernet driver support > - -> Intel devices > - -> Intel(R) Ethernet Controller XL710 Family > +For example, > > -Additional Configurations > -========================= > +:: > > - Generic Receive Offload (GRO) > - ----------------------------- > - The driver supports the in-kernel software implementation of GRO. GRO has > - shown that by coalescing Rx traffic into larger chunks of data, CPU > - utilization can be significantly reduced when under large Rx load. GRO is > - an evolution of the previously-used LRO interface. GRO is able to coalesce > - other protocols besides TCP. It's also safe to use with configurations that > - are problematic for LRO, namely bridging and iSCSI. > + ... user-def 0x4FFFF ... > > - Ethtool > - ------- > - The driver utilizes the ethtool interface for driver configuration and > - diagnostics, as well as displaying statistical information. The latest > - ethtool version is required for this functionality. > +tells the filter to look 4 bytes into the payload and match that value against > +0xFFFF. The offset is based on the beginning of the payload, and not the > +beginning of the packet. Thus > > - The latest release of ethtool can be found from > - https://www.kernel.org/pub/software/network/ethtool > +:: > > + flow-type tcp4 ... user-def 0x8BEAF ... > > - Flow Director n-ntuple traffic filters (FDir) > - --------------------------------------------- > - The driver utilizes the ethtool interface for configuring ntuple filters, > - via "ethtool -N ". > +would match TCP/IPv4 packets which have the value 0xBEAF 8 bytes into the > +TCP/IPv4 payload. > > - The sctp4, ip4, udp4, and tcp4 flow types are supported with the standard > - fields including src-ip, dst-ip, src-port and dst-port. The driver only > - supports fully enabling or fully masking the fields, so use of the mask > - fields for partial matches is not supported. > +Note that ICMP headers are parsed as 4 bytes of header and 4 bytes of payload. > +Thus to match the first byte of the payload, you must actually add 4 bytes to > +the offset. Also note that ip4 filters match both ICMP frames as well as raw > +(unknown) ip4 frames, where the payload will be the L3 payload of the IP4 frame. > > - Additionally, the driver supports using the action to specify filters for a > - Virtual Function. You can specify the action as a 64bit value, where the > - lower 32 bits represents the queue number, while the next 8 bits represent > - which VF. Note that 0 is the PF, so the VF identifier is offset by 1. For > - example: > +The maximum offset is 64. The hardware will only read up to 64 bytes of data > +from the payload. The offset must be even because the flexible data is 2 bytes > +long and must be aligned to byte 0 of the packet payload. Hmmm... does this actually mean the end of the pattern can't be beyond the 64 bytes? If the user gives 64 as the offset, then the bytes searched for the pattern would be bytes 65 and 66. Maybe the max offset should be 62? > > - ... action 0x800000002 ... > +The user-defined flexible offset is also considered part of the input set and > +cannot be programmed separately for multiple filters of the same type. However, > +the flexible data is not part of the input set and multiple filters may use the > +same offset but match against different data. > > - Would indicate to direct traffic for Virtual Function 7 (8 minus 1) on queue > - 2 of that VF. > +To create filters that direct traffic to a specific Virtual Function, use the > +"action" parameter. Specify the action as a 64 bit value, where the lower 32 > +bits represents the queue number, while the next 8 bits represent which VF. > +Note that 0 is the PF, so the VF identifier is offset by 1. For example:: > > - The driver also supports using the user-defined field to specify 2 bytes of > - arbitrary data to match within the packet payload in addition to the regular > - fields. The data is specified in the lower 32bits of the user-def field in > - the following way: > + ... action 0x800000002 ... > > - +----------------------------+---------------------------+ > - | 31 28 24 20 16 | 15 12 8 4 0| > - +----------------------------+---------------------------+ > - | offset into packet payload | 2 bytes of flexible data | > - +----------------------------+---------------------------+ > +specifies to direct traffic to Virtual Function 7 (8 minus 1) into queue 2 of > +that VF. > > - As an example, > +Note that these filters will not break internal routing rules, and will not > +route traffic that otherwise would not have been sent to the specified Virtual > +Function. > > - ... user-def 0x4FFFF .... > +Setting the link-down-on-close Private Flag > +------------------------------------------- > +When the link-down-on-close private flag is set to "on", the port's link will > +go down when the interface is brought down using the ifconfig ethX down command. > > - means to match the value 0xFFFF 4 bytes into the packet payload. Note that > - the offset is based on the beginning of the payload, and not the beginning > - of the packet. Thus > +Use ethtool to view and set link-down-on-close, as follows:: > > - flow-type tcp4 ... user-def 0x8BEAF .... > + ethtool --show-priv-flags ethX > + ethtool --set-priv-flags ethX link-down-on-close [on|off] > > - would match TCP/IPv4 packets which have the value 0xBEAF 8bytes into the > - TCP/IPv4 payload. > +Viewing Link Messages > +--------------------- > +Link messages will not be displayed to the console if the distribution is > +restricting system messages. In order to see network driver link messages on > +your console, set dmesg to eight by entering the following:: > > - For ICMP, the hardware parses the ICMP header as 4 bytes of header and 4 > - bytes of payload, so if you want to match an ICMP frames payload you may need > - to add 4 to the offset in order to match the data. > + dmesg -n 8 > > - Furthermore, the offset can only be up to a value of 64, as the hardware > - will only read up to 64 bytes of data from the payload. It must also be even > - as the flexible data is 2 bytes long and must be aligned to byte 0 of the > - packet payload. > +NOTE: This setting is not saved across reboots. > > - When programming filters, the hardware is limited to using a single input > - set for each flow type. This means that it is an error to program two > - different filters with the same type that don't match on the same fields. > - Thus the second of the following two commands will fail: > +Jumbo Frames > +------------ > +Jumbo Frames support is enabled by changing the Maximum Transmission Unit (MTU) > +to a value larger than the default value of 1500. > > - ethtool -N flow-type tcp4 src-ip 192.168.0.7 action 5 > - ethtool -N flow-type tcp4 dst-ip 192.168.15.18 action 1 > +Use the ifconfig command to increase the MTU size. For example, enter the > +following where is the interface number:: > > - This is because the first filter will be accepted and reprogram the input > - set for TCPv4 filters, but the second filter will be unable to reprogram the > - input set until all the conflicting TCPv4 filters are first removed. > + ifconfig eth mtu 9000 up > > - Note that the user-defined flexible offset is also considered part of the > - input set and cannot be programmed separately for multiple filters of the > - same type. However, the flexible data is not part of the input set and > - multiple filters may use the same offset but match against different data. > +Alternatively, you can use the ip command as follows:: > > - Data Center Bridging (DCB) > - -------------------------- > - DCB configuration is not currently supported. > + ip link set mtu 9000 dev eth > + ip link set up dev eth > > - FCoE > - ---- > - The driver supports Fiber Channel over Ethernet (FCoE) and Data Center > - Bridging (DCB) functionality. Configuring DCB and FCoE is outside the scope > - of this driver doc. Refer to http://www.open-fcoe.org/ for FCoE project > - information and http://www.open-lldp.org/ or email list > - e1000-eedc at lists.sourceforge.net for DCB information. > +This setting is not saved across reboots. The setting change can be made > +permanent by adding 'MTU=9000' to the file:: > > - MAC and VLAN anti-spoofing feature > - ---------------------------------- > - When a malicious driver attempts to send a spoofed packet, it is dropped by > - the hardware and not transmitted. An interrupt is sent to the PF driver > - notifying it of the spoof attempt. > + /etc/sysconfig/network-scripts/ifcfg-eth // for RHEL > + /etc/sysconfig/network/ // for SLES > > - When a spoofed packet is detected the PF driver will send the following > - message to the system log (displayed by the "dmesg" command): > +NOTE: The maximum MTU setting for Jumbo Frames is 9702. This value coincides > +with the maximum Jumbo Frames size of 9728 bytes. > > - Spoof event(s) detected on VF (n) > +NOTE: This driver will attempt to use multiple page sized buffers to receive > +each jumbo packet. This should help to avoid buffer starvation issues when > +allocating receive packets. > > - Where n=the VF that attempted to do the spoofing. > +ethtool > +------- > +The driver utilizes the ethtool interface for driver configuration and > +diagnostics, as well as displaying statistical information. The latest ethtool > +version is required for this functionality. Download it at: > +https://www.kernel.org/pub/software/network/ethtool/ > > +Supported ethtool Commands and Options for Filtering > +---------------------------------------------------- > +-n --show-nfc > + Retrieves the receive network flow classification configurations. > > -Performance Tuning > -================== > +rx-flow-hash tcp4|udp4|ah4|esp4|sctp4|tcp6|udp6|ah6|esp6|sctp6 > + Retrieves the hash options for the specified network traffic type. > > -An excellent article on performance tuning can be found at: > +-N --config-nfc > + Configures the receive network flow classification. > > -http://www.redhat.com/promo/summit/2008/downloads/pdf/Thursday/Mark_Wagner.pdf > +rx-flow-hash tcp4|udp4|ah4|esp4|sctp4|tcp6|udp6|ah6|esp6|sctp6 m|v|t|s|d|f|n|r... > + Configures the hash options for the specified network traffic type. > > +udp4 UDP over IPv4 > +udp6 UDP over IPv6 > > -Known Issues > -============ > +f Hash on bytes 0 and 1 of the Layer 4 header of the Rx packet. > +n Hash on bytes 2 and 3 of the Layer 4 header of the Rx packet. > + > +Speed and Duplex Configuration > +------------------------------ > +In addressing speed and duplex configuration issues, you need to distinguish > +between copper-based adapters and fiber-based adapters. > + > +In the default mode, an Intel(R) Ethernet Network Adapter using copper > +connections will attempt to auto-negotiate with its link partner to determine > +the best setting. If the adapter cannot establish link with the link partner > +using auto-negotiation, you may need to manually configure the adapter and link > +partner to identical settings to establish link and pass packets. This should > +only be needed when attempting to link with an older switch that does not > +support auto-negotiation or one that has been forced to a specific speed or > +duplex mode. Your link partner must match the setting you choose. 1 Gbps speeds > +and higher cannot be forced. Use the autonegotiation advertising setting to > +manually set devices for 1 Gbps and higher. > + > +NOTE: You cannot set the speed for devices based on the Intel(R) Ethernet > +Network Adapter XXV710 based devices. > + > +Speed, duplex, and autonegotiation advertising are configured through the > +ethtool* utility. > + > +Caution: Only experienced network administrators should force speed and duplex > +or change autonegotiation advertising manually. The settings at the switch must > +always match the adapter settings. Adapter performance may suffer or your > +adapter may not operate if you configure the adapter differently from your > +switch. > + > +An Intel(R) Ethernet Network Adapter using fiber-based connections, however, > +will not attempt to auto-negotiate with its link partner since those adapters > +operate only in full duplex and only at their native speed. > + > +NAPI > +---- > +NAPI (Rx polling mode) is supported in the i40e driver. > +For more information on NAPI, see > +https://wiki.linuxfoundation.org/networking/napi > + > +Flow Control > +------------ > +Ethernet Flow Control (IEEE 802.3x) can be configured with ethtool to enable > +receiving and transmitting pause frames for i40e. When transmit is enabled, > +pause frames are generated when the receive packet buffer crosses a predefined > +threshold. When receive is enabled, the transmit unit will halt for the time > +delay specified when a pause frame is received. > + > +NOTE: You must have a flow control capable link partner. > + > +Flow Control is on by default. > + > +Use ethtool to change the flow control settings. > + > +To enable or disable Rx or Tx Flow Control:: > + > + ethtool -A eth? rx tx > + > +Note: This command only enables or disables Flow Control if auto-negotiation is > +disabled. If auto-negotiation is enabled, this command changes the parameters > +used for auto-negotiation with the link partner. > + > +To enable or disable auto-negotiation:: > + > + ethtool -s eth? autoneg > + > +Note: Flow Control auto-negotiation is part of link auto-negotiation. Depending > +on your device, you may not be able to change the auto-negotiation setting. > + > +RSS Hash Flow > +------------- > +Allows you to set the hash bytes per flow type and any combination of one or > +more options for Receive Side Scaling (RSS) hash byte configuration. > + > +:: > + > + # ethtool -N rx-flow-hash