From 973d55e590beeca13fece60596ee3b511d36d9da Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 1 May 2020 16:44:23 +0200 Subject: docs: networking: convert tuntap.txt to ReST - add SPDX header; - use copyright symbol; - adjust titles and chapters, adding proper markups; - mark code blocks and literals as such; - adjust identation, whitespaces and blank lines where needed; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: David S. Miller --- Documentation/networking/index.rst | 1 + Documentation/networking/tuntap.rst | 259 ++++++++++++++++++++++++++++++++++++ Documentation/networking/tuntap.txt | 227 ------------------------------- MAINTAINERS | 2 +- drivers/net/Kconfig | 2 +- 5 files changed, 262 insertions(+), 229 deletions(-) create mode 100644 Documentation/networking/tuntap.rst delete mode 100644 Documentation/networking/tuntap.txt diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index b423b2db5f96..e7a683f0528d 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -111,6 +111,7 @@ Contents: team timestamping tproxy + tuntap .. only:: subproject and html diff --git a/Documentation/networking/tuntap.rst b/Documentation/networking/tuntap.rst new file mode 100644 index 000000000000..a59d1dd6fdcc --- /dev/null +++ b/Documentation/networking/tuntap.rst @@ -0,0 +1,259 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: + +=============================== +Universal TUN/TAP device driver +=============================== + +Copyright |copy| 1999-2000 Maxim Krasnyansky + + Linux, Solaris drivers + Copyright |copy| 1999-2000 Maxim Krasnyansky + + FreeBSD TAP driver + Copyright |copy| 1999-2000 Maksim Yevmenkin + + Revision of this document 2002 by Florian Thiel + +1. Description +============== + + TUN/TAP provides packet reception and transmission for user space programs. + It can be seen as a simple Point-to-Point or Ethernet device, which, + instead of receiving packets from physical media, receives them from + user space program and instead of sending packets via physical media + writes them to the user space program. + + In order to use the driver a program has to open /dev/net/tun and issue a + corresponding ioctl() to register a network device with the kernel. A network + device will appear as tunXX or tapXX, depending on the options chosen. When + the program closes the file descriptor, the network device and all + corresponding routes will disappear. + + Depending on the type of device chosen the userspace program has to read/write + IP packets (with tun) or ethernet frames (with tap). Which one is being used + depends on the flags given with the ioctl(). + + The package from http://vtun.sourceforge.net/tun contains two simple examples + for how to use tun and tap devices. Both programs work like a bridge between + two network interfaces. + br_select.c - bridge based on select system call. + br_sigio.c - bridge based on async io and SIGIO signal. + However, the best example is VTun http://vtun.sourceforge.net :)) + +2. Configuration +================ + + Create device node:: + + mkdir /dev/net (if it doesn't exist already) + mknod /dev/net/tun c 10 200 + + Set permissions:: + + e.g. chmod 0666 /dev/net/tun + + There's no harm in allowing the device to be accessible by non-root users, + since CAP_NET_ADMIN is required for creating network devices or for + connecting to network devices which aren't owned by the user in question. + If you want to create persistent devices and give ownership of them to + unprivileged users, then you need the /dev/net/tun device to be usable by + those users. + + Driver module autoloading + + Make sure that "Kernel module loader" - module auto-loading + support is enabled in your kernel. The kernel should load it on + first access. + + Manual loading + + insert the module by hand:: + + modprobe tun + + If you do it the latter way, you have to load the module every time you + need it, if you do it the other way it will be automatically loaded when + /dev/net/tun is being opened. + +3. Program interface +==================== + +3.1 Network device allocation +----------------------------- + +``char *dev`` should be the name of the device with a format string (e.g. +"tun%d"), but (as far as I can see) this can be any valid network device name. +Note that the character pointer becomes overwritten with the real device name +(e.g. "tun0"):: + + #include + #include + + int tun_alloc(char *dev) + { + struct ifreq ifr; + int fd, err; + + if( (fd = open("/dev/net/tun", O_RDWR)) < 0 ) + return tun_alloc_old(dev); + + memset(&ifr, 0, sizeof(ifr)); + + /* Flags: IFF_TUN - TUN device (no Ethernet headers) + * IFF_TAP - TAP device + * + * IFF_NO_PI - Do not provide packet information + */ + ifr.ifr_flags = IFF_TUN; + if( *dev ) + strncpy(ifr.ifr_name, dev, IFNAMSIZ); + + if( (err = ioctl(fd, TUNSETIFF, (void *) &ifr)) < 0 ){ + close(fd); + return err; + } + strcpy(dev, ifr.ifr_name); + return fd; + } + +3.2 Frame format +---------------- + +If flag IFF_NO_PI is not set each frame format is:: + + Flags [2 bytes] + Proto [2 bytes] + Raw protocol(IP, IPv6, etc) frame. + +3.3 Multiqueue tuntap interface +------------------------------- + +From version 3.8, Linux supports multiqueue tuntap which can uses multiple +file descriptors (queues) to parallelize packets sending or receiving. The +device allocation is the same as before, and if user wants to create multiple +queues, TUNSETIFF with the same device name must be called many times with +IFF_MULTI_QUEUE flag. + +``char *dev`` should be the name of the device, queues is the number of queues +to be created, fds is used to store and return the file descriptors (queues) +created to the caller. Each file descriptor were served as the interface of a +queue which could be accessed by userspace. + +:: + + #include + #include + + int tun_alloc_mq(char *dev, int queues, int *fds) + { + struct ifreq ifr; + int fd, err, i; + + if (!dev) + return -1; + + memset(&ifr, 0, sizeof(ifr)); + /* Flags: IFF_TUN - TUN device (no Ethernet headers) + * IFF_TAP - TAP device + * + * IFF_NO_PI - Do not provide packet information + * IFF_MULTI_QUEUE - Create a queue of multiqueue device + */ + ifr.ifr_flags = IFF_TAP | IFF_NO_PI | IFF_MULTI_QUEUE; + strcpy(ifr.ifr_name, dev); + + for (i = 0; i < queues; i++) { + if ((fd = open("/dev/net/tun", O_RDWR)) < 0) + goto err; + err = ioctl(fd, TUNSETIFF, (void *)&ifr); + if (err) { + close(fd); + goto err; + } + fds[i] = fd; + } + + return 0; + err: + for (--i; i >= 0; i--) + close(fds[i]); + return err; + } + +A new ioctl(TUNSETQUEUE) were introduced to enable or disable a queue. When +calling it with IFF_DETACH_QUEUE flag, the queue were disabled. And when +calling it with IFF_ATTACH_QUEUE flag, the queue were enabled. The queue were +enabled by default after it was created through TUNSETIFF. + +fd is the file descriptor (queue) that we want to enable or disable, when +enable is true we enable it, otherwise we disable it:: + + #include + #include + + int tun_set_queue(int fd, int enable) + { + struct ifreq ifr; + + memset(&ifr, 0, sizeof(ifr)); + + if (enable) + ifr.ifr_flags = IFF_ATTACH_QUEUE; + else + ifr.ifr_flags = IFF_DETACH_QUEUE; + + return ioctl(fd, TUNSETQUEUE, (void *)&ifr); + } + +Universal TUN/TAP device driver Frequently Asked Question +========================================================= + +1. What platforms are supported by TUN/TAP driver ? + +Currently driver has been written for 3 Unices: + + - Linux kernels 2.2.x, 2.4.x + - FreeBSD 3.x, 4.x, 5.x + - Solaris 2.6, 7.0, 8.0 + +2. What is TUN/TAP driver used for? + +As mentioned above, main purpose of TUN/TAP driver is tunneling. +It is used by VTun (http://vtun.sourceforge.net). + +Another interesting application using TUN/TAP is pipsecd +(http://perso.enst.fr/~beyssac/pipsec/), a userspace IPSec +implementation that can use complete kernel routing (unlike FreeS/WAN). + +3. How does Virtual network device actually work ? + +Virtual network device can be viewed as a simple Point-to-Point or +Ethernet device, which instead of receiving packets from a physical +media, receives them from user space program and instead of sending +packets via physical media sends them to the user space program. + +Let's say that you configured IPv6 on the tap0, then whenever +the kernel sends an IPv6 packet to tap0, it is passed to the application +(VTun for example). The application encrypts, compresses and sends it to +the other side over TCP or UDP. The application on the other side decompresses +and decrypts the data received and writes the packet to the TAP device, +the kernel handles the packet like it came from real physical device. + +4. What is the difference between TUN driver and TAP driver? + +TUN works with IP frames. TAP works with Ethernet frames. + +This means that you have to read/write IP packets when you are using tun and +ethernet frames when using tap. + +5. What is the difference between BPF and TUN/TAP driver? + +BPF is an advanced packet filter. It can be attached to existing +network interface. It does not provide a virtual network interface. +A TUN/TAP driver does provide a virtual network interface and it is possible +to attach BPF to this interface. + +6. Does TAP driver support kernel Ethernet bridging? + +Yes. Linux and FreeBSD drivers support Ethernet bridging. diff --git a/Documentation/networking/tuntap.txt b/Documentation/networking/tuntap.txt deleted file mode 100644 index 0104830d5075..000000000000 --- a/Documentation/networking/tuntap.txt +++ /dev/null @@ -1,227 +0,0 @@ -Universal TUN/TAP device driver. -Copyright (C) 1999-2000 Maxim Krasnyansky - - Linux, Solaris drivers - Copyright (C) 1999-2000 Maxim Krasnyansky - - FreeBSD TAP driver - Copyright (c) 1999-2000 Maksim Yevmenkin - - Revision of this document 2002 by Florian Thiel - -1. Description - TUN/TAP provides packet reception and transmission for user space programs. - It can be seen as a simple Point-to-Point or Ethernet device, which, - instead of receiving packets from physical media, receives them from - user space program and instead of sending packets via physical media - writes them to the user space program. - - In order to use the driver a program has to open /dev/net/tun and issue a - corresponding ioctl() to register a network device with the kernel. A network - device will appear as tunXX or tapXX, depending on the options chosen. When - the program closes the file descriptor, the network device and all - corresponding routes will disappear. - - Depending on the type of device chosen the userspace program has to read/write - IP packets (with tun) or ethernet frames (with tap). Which one is being used - depends on the flags given with the ioctl(). - - The package from http://vtun.sourceforge.net/tun contains two simple examples - for how to use tun and tap devices. Both programs work like a bridge between - two network interfaces. - br_select.c - bridge based on select system call. - br_sigio.c - bridge based on async io and SIGIO signal. - However, the best example is VTun http://vtun.sourceforge.net :)) - -2. Configuration - Create device node: - mkdir /dev/net (if it doesn't exist already) - mknod /dev/net/tun c 10 200 - - Set permissions: - e.g. chmod 0666 /dev/net/tun - There's no harm in allowing the device to be accessible by non-root users, - since CAP_NET_ADMIN is required for creating network devices or for - connecting to network devices which aren't owned by the user in question. - If you want to create persistent devices and give ownership of them to - unprivileged users, then you need the /dev/net/tun device to be usable by - those users. - - Driver module autoloading - - Make sure that "Kernel module loader" - module auto-loading - support is enabled in your kernel. The kernel should load it on - first access. - - Manual loading - insert the module by hand: - modprobe tun - - If you do it the latter way, you have to load the module every time you - need it, if you do it the other way it will be automatically loaded when - /dev/net/tun is being opened. - -3. Program interface - 3.1 Network device allocation: - - char *dev should be the name of the device with a format string (e.g. - "tun%d"), but (as far as I can see) this can be any valid network device name. - Note that the character pointer becomes overwritten with the real device name - (e.g. "tun0") - - #include - #include - - int tun_alloc(char *dev) - { - struct ifreq ifr; - int fd, err; - - if( (fd = open("/dev/net/tun", O_RDWR)) < 0 ) - return tun_alloc_old(dev); - - memset(&ifr, 0, sizeof(ifr)); - - /* Flags: IFF_TUN - TUN device (no Ethernet headers) - * IFF_TAP - TAP device - * - * IFF_NO_PI - Do not provide packet information - */ - ifr.ifr_flags = IFF_TUN; - if( *dev ) - strncpy(ifr.ifr_name, dev, IFNAMSIZ); - - if( (err = ioctl(fd, TUNSETIFF, (void *) &ifr)) < 0 ){ - close(fd); - return err; - } - strcpy(dev, ifr.ifr_name); - return fd; - } - - 3.2 Frame format: - If flag IFF_NO_PI is not set each frame format is: - Flags [2 bytes] - Proto [2 bytes] - Raw protocol(IP, IPv6, etc) frame. - - 3.3 Multiqueue tuntap interface: - - From version 3.8, Linux supports multiqueue tuntap which can uses multiple - file descriptors (queues) to parallelize packets sending or receiving. The - device allocation is the same as before, and if user wants to create multiple - queues, TUNSETIFF with the same device name must be called many times with - IFF_MULTI_QUEUE flag. - - char *dev should be the name of the device, queues is the number of queues to - be created, fds is used to store and return the file descriptors (queues) - created to the caller. Each file descriptor were served as the interface of a - queue which could be accessed by userspace. - - #include - #include - - int tun_alloc_mq(char *dev, int queues, int *fds) - { - struct ifreq ifr; - int fd, err, i; - - if (!dev) - return -1; - - memset(&ifr, 0, sizeof(ifr)); - /* Flags: IFF_TUN - TUN device (no Ethernet headers) - * IFF_TAP - TAP device - * - * IFF_NO_PI - Do not provide packet information - * IFF_MULTI_QUEUE - Create a queue of multiqueue device - */ - ifr.ifr_flags = IFF_TAP | IFF_NO_PI | IFF_MULTI_QUEUE; - strcpy(ifr.ifr_name, dev); - - for (i = 0; i < queues; i++) { - if ((fd = open("/dev/net/tun", O_RDWR)) < 0) - goto err; - err = ioctl(fd, TUNSETIFF, (void *)&ifr); - if (err) { - close(fd); - goto err; - } - fds[i] = fd; - } - - return 0; - err: - for (--i; i >= 0; i--) - close(fds[i]); - return err; - } - - A new ioctl(TUNSETQUEUE) were introduced to enable or disable a queue. When - calling it with IFF_DETACH_QUEUE flag, the queue were disabled. And when - calling it with IFF_ATTACH_QUEUE flag, the queue were enabled. The queue were - enabled by default after it was created through TUNSETIFF. - - fd is the file descriptor (queue) that we want to enable or disable, when - enable is true we enable it, otherwise we disable it - - #include - #include - - int tun_set_queue(int fd, int enable) - { - struct ifreq ifr; - - memset(&ifr, 0, sizeof(ifr)); - - if (enable) - ifr.ifr_flags = IFF_ATTACH_QUEUE; - else - ifr.ifr_flags = IFF_DETACH_QUEUE; - - return ioctl(fd, TUNSETQUEUE, (void *)&ifr); - } - -Universal TUN/TAP device driver Frequently Asked Question. - -1. What platforms are supported by TUN/TAP driver ? -Currently driver has been written for 3 Unices: - Linux kernels 2.2.x, 2.4.x - FreeBSD 3.x, 4.x, 5.x - Solaris 2.6, 7.0, 8.0 - -2. What is TUN/TAP driver used for? -As mentioned above, main purpose of TUN/TAP driver is tunneling. -It is used by VTun (http://vtun.sourceforge.net). - -Another interesting application using TUN/TAP is pipsecd -(http://perso.enst.fr/~beyssac/pipsec/), a userspace IPSec -implementation that can use complete kernel routing (unlike FreeS/WAN). - -3. How does Virtual network device actually work ? -Virtual network device can be viewed as a simple Point-to-Point or -Ethernet device, which instead of receiving packets from a physical -media, receives them from user space program and instead of sending -packets via physical media sends them to the user space program. - -Let's say that you configured IPv6 on the tap0, then whenever -the kernel sends an IPv6 packet to tap0, it is passed to the application -(VTun for example). The application encrypts, compresses and sends it to -the other side over TCP or UDP. The application on the other side decompresses -and decrypts the data received and writes the packet to the TAP device, -the kernel handles the packet like it came from real physical device. - -4. What is the difference between TUN driver and TAP driver? -TUN works with IP frames. TAP works with Ethernet frames. - -This means that you have to read/write IP packets when you are using tun and -ethernet frames when using tap. - -5. What is the difference between BPF and TUN/TAP driver? -BPF is an advanced packet filter. It can be attached to existing -network interface. It does not provide a virtual network interface. -A TUN/TAP driver does provide a virtual network interface and it is possible -to attach BPF to this interface. - -6. Does TAP driver support kernel Ethernet bridging? -Yes. Linux and FreeBSD drivers support Ethernet bridging. diff --git a/MAINTAINERS b/MAINTAINERS index 0ac9cec0bce6..6456c5bb02f1 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -17161,7 +17161,7 @@ TUN/TAP driver M: Maxim Krasnyansky S: Maintained W: http://vtun.sourceforge.net/tun -F: Documentation/networking/tuntap.txt +F: Documentation/networking/tuntap.rst F: arch/um/os-Linux/drivers/ TURBOCHANNEL SUBSYSTEM diff --git a/drivers/net/Kconfig b/drivers/net/Kconfig index ad64be98330f..3f2c98a7906c 100644 --- a/drivers/net/Kconfig +++ b/drivers/net/Kconfig @@ -355,7 +355,7 @@ config TUN devices, driver will automatically delete tunXX or tapXX device and all routes corresponding to it. - Please read for more + Please read for more information. To compile this driver as a module, choose M here: the module -- cgit From 961fb1ff412a2cefaf50f4f56bb60a10ed071df5 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 1 May 2020 16:44:24 +0200 Subject: docs: networking: convert udplite.txt to ReST - add SPDX header; - adjust titles and chapters, adding proper markups; - mark lists as such; - mark tables as such; - mark code blocks and literals as such; - adjust identation, whitespaces and blank lines where needed; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: David S. Miller --- Documentation/networking/index.rst | 1 + Documentation/networking/udplite.rst | 291 +++++++++++++++++++++++++++++++++++ Documentation/networking/udplite.txt | 278 --------------------------------- 3 files changed, 292 insertions(+), 278 deletions(-) create mode 100644 Documentation/networking/udplite.rst delete mode 100644 Documentation/networking/udplite.txt diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index e7a683f0528d..ca0b0dbfd9ad 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -112,6 +112,7 @@ Contents: timestamping tproxy tuntap + udplite .. only:: subproject and html diff --git a/Documentation/networking/udplite.rst b/Documentation/networking/udplite.rst new file mode 100644 index 000000000000..2c225f28b7b2 --- /dev/null +++ b/Documentation/networking/udplite.rst @@ -0,0 +1,291 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================ +The UDP-Lite protocol (RFC 3828) +================================ + + + UDP-Lite is a Standards-Track IETF transport protocol whose characteristic + is a variable-length checksum. This has advantages for transport of multimedia + (video, VoIP) over wireless networks, as partly damaged packets can still be + fed into the codec instead of being discarded due to a failed checksum test. + + This file briefly describes the existing kernel support and the socket API. + For in-depth information, you can consult: + + - The UDP-Lite Homepage: + http://web.archive.org/web/%2E/http://www.erg.abdn.ac.uk/users/gerrit/udp-lite/ + + From here you can also download some example application source code. + + - The UDP-Lite HOWTO on + http://web.archive.org/web/%2E/http://www.erg.abdn.ac.uk/users/gerrit/udp-lite/files/UDP-Lite-HOWTO.txt + + - The Wireshark UDP-Lite WiKi (with capture files): + https://wiki.wireshark.org/Lightweight_User_Datagram_Protocol + + - The Protocol Spec, RFC 3828, http://www.ietf.org/rfc/rfc3828.txt + + +1. Applications +=============== + + Several applications have been ported successfully to UDP-Lite. Ethereal + (now called wireshark) has UDP-Litev4/v6 support by default. + + Porting applications to UDP-Lite is straightforward: only socket level and + IPPROTO need to be changed; senders additionally set the checksum coverage + length (default = header length = 8). Details are in the next section. + +2. Programming API +================== + + UDP-Lite provides a connectionless, unreliable datagram service and hence + uses the same socket type as UDP. In fact, porting from UDP to UDP-Lite is + very easy: simply add ``IPPROTO_UDPLITE`` as the last argument of the + socket(2) call so that the statement looks like:: + + s = socket(PF_INET, SOCK_DGRAM, IPPROTO_UDPLITE); + + or, respectively, + + :: + + s = socket(PF_INET6, SOCK_DGRAM, IPPROTO_UDPLITE); + + With just the above change you are able to run UDP-Lite services or connect + to UDP-Lite servers. The kernel will assume that you are not interested in + using partial checksum coverage and so emulate UDP mode (full coverage). + + To make use of the partial checksum coverage facilities requires setting a + single socket option, which takes an integer specifying the coverage length: + + * Sender checksum coverage: UDPLITE_SEND_CSCOV + + For example:: + + int val = 20; + setsockopt(s, SOL_UDPLITE, UDPLITE_SEND_CSCOV, &val, sizeof(int)); + + sets the checksum coverage length to 20 bytes (12b data + 8b header). + Of each packet only the first 20 bytes (plus the pseudo-header) will be + checksummed. This is useful for RTP applications which have a 12-byte + base header. + + + * Receiver checksum coverage: UDPLITE_RECV_CSCOV + + This option is the receiver-side analogue. It is truly optional, i.e. not + required to enable traffic with partial checksum coverage. Its function is + that of a traffic filter: when enabled, it instructs the kernel to drop + all packets which have a coverage _less_ than this value. For example, if + RTP and UDP headers are to be protected, a receiver can enforce that only + packets with a minimum coverage of 20 are admitted:: + + int min = 20; + setsockopt(s, SOL_UDPLITE, UDPLITE_RECV_CSCOV, &min, sizeof(int)); + + The calls to getsockopt(2) are analogous. Being an extension and not a stand- + alone protocol, all socket options known from UDP can be used in exactly the + same manner as before, e.g. UDP_CORK or UDP_ENCAP. + + A detailed discussion of UDP-Lite checksum coverage options is in section IV. + +3. Header Files +=============== + + The socket API requires support through header files in /usr/include: + + * /usr/include/netinet/in.h + to define IPPROTO_UDPLITE + + * /usr/include/netinet/udplite.h + for UDP-Lite header fields and protocol constants + + For testing purposes, the following can serve as a ``mini`` header file:: + + #define IPPROTO_UDPLITE 136 + #define SOL_UDPLITE 136 + #define UDPLITE_SEND_CSCOV 10 + #define UDPLITE_RECV_CSCOV 11 + + Ready-made header files for various distros are in the UDP-Lite tarball. + +4. Kernel Behaviour with Regards to the Various Socket Options +============================================================== + + + To enable debugging messages, the log level need to be set to 8, as most + messages use the KERN_DEBUG level (7). + + 1) Sender Socket Options + + If the sender specifies a value of 0 as coverage length, the module + assumes full coverage, transmits a packet with coverage length of 0 + and according checksum. If the sender specifies a coverage < 8 and + different from 0, the kernel assumes 8 as default value. Finally, + if the specified coverage length exceeds the packet length, the packet + length is used instead as coverage length. + + 2) Receiver Socket Options + + The receiver specifies the minimum value of the coverage length it + is willing to accept. A value of 0 here indicates that the receiver + always wants the whole of the packet covered. In this case, all + partially covered packets are dropped and an error is logged. + + It is not possible to specify illegal values (<0 and <8); in these + cases the default of 8 is assumed. + + All packets arriving with a coverage value less than the specified + threshold are discarded, these events are also logged. + + 3) Disabling the Checksum Computation + + On both sender and receiver, checksumming will always be performed + and cannot be disabled using SO_NO_CHECK. Thus:: + + setsockopt(sockfd, SOL_SOCKET, SO_NO_CHECK, ... ); + + will always will be ignored, while the value of:: + + getsockopt(sockfd, SOL_SOCKET, SO_NO_CHECK, &value, ...); + + is meaningless (as in TCP). Packets with a zero checksum field are + illegal (cf. RFC 3828, sec. 3.1) and will be silently discarded. + + 4) Fragmentation + + The checksum computation respects both buffersize and MTU. The size + of UDP-Lite packets is determined by the size of the send buffer. The + minimum size of the send buffer is 2048 (defined as SOCK_MIN_SNDBUF + in include/net/sock.h), the default value is configurable as + net.core.wmem_default or via setting the SO_SNDBUF socket(7) + option. The maximum upper bound for the send buffer is determined + by net.core.wmem_max. + + Given a payload size larger than the send buffer size, UDP-Lite will + split the payload into several individual packets, filling up the + send buffer size in each case. + + The precise value also depends on the interface MTU. The interface MTU, + in turn, may trigger IP fragmentation. In this case, the generated + UDP-Lite packet is split into several IP packets, of which only the + first one contains the L4 header. + + The send buffer size has implications on the checksum coverage length. + Consider the following example:: + + Payload: 1536 bytes Send Buffer: 1024 bytes + MTU: 1500 bytes Coverage Length: 856 bytes + + UDP-Lite will ship the 1536 bytes in two separate packets:: + + Packet 1: 1024 payload + 8 byte header + 20 byte IP header = 1052 bytes + Packet 2: 512 payload + 8 byte header + 20 byte IP header = 540 bytes + + The coverage packet covers the UDP-Lite header and 848 bytes of the + payload in the first packet, the second packet is fully covered. Note + that for the second packet, the coverage length exceeds the packet + length. The kernel always re-adjusts the coverage length to the packet + length in such cases. + + As an example of what happens when one UDP-Lite packet is split into + several tiny fragments, consider the following example:: + + Payload: 1024 bytes Send buffer size: 1024 bytes + MTU: 300 bytes Coverage length: 575 bytes + + +-+-----------+--------------+--------------+--------------+ + |8| 272 | 280 | 280 | 280 | + +-+-----------+--------------+--------------+--------------+ + 280 560 840 1032 + ^ + *****checksum coverage************* + + The UDP-Lite module generates one 1032 byte packet (1024 + 8 byte + header). According to the interface MTU, these are split into 4 IP + packets (280 byte IP payload + 20 byte IP header). The kernel module + sums the contents of the entire first two packets, plus 15 bytes of + the last packet before releasing the fragments to the IP module. + + To see the analogous case for IPv6 fragmentation, consider a link + MTU of 1280 bytes and a write buffer of 3356 bytes. If the checksum + coverage is less than 1232 bytes (MTU minus IPv6/fragment header + lengths), only the first fragment needs to be considered. When using + larger checksum coverage lengths, each eligible fragment needs to be + checksummed. Suppose we have a checksum coverage of 3062. The buffer + of 3356 bytes will be split into the following fragments:: + + Fragment 1: 1280 bytes carrying 1232 bytes of UDP-Lite data + Fragment 2: 1280 bytes carrying 1232 bytes of UDP-Lite data + Fragment 3: 948 bytes carrying 900 bytes of UDP-Lite data + + The first two fragments have to be checksummed in full, of the last + fragment only 598 (= 3062 - 2*1232) bytes are checksummed. + + While it is important that such cases are dealt with correctly, they + are (annoyingly) rare: UDP-Lite is designed for optimising multimedia + performance over wireless (or generally noisy) links and thus smaller + coverage lengths are likely to be expected. + +5. UDP-Lite Runtime Statistics and their Meaning +================================================ + + Exceptional and error conditions are logged to syslog at the KERN_DEBUG + level. Live statistics about UDP-Lite are available in /proc/net/snmp + and can (with newer versions of netstat) be viewed using:: + + netstat -svu + + This displays UDP-Lite statistics variables, whose meaning is as follows. + + ============ ===================================================== + InDatagrams The total number of datagrams delivered to users. + + NoPorts Number of packets received to an unknown port. + These cases are counted separately (not as InErrors). + + InErrors Number of erroneous UDP-Lite packets. Errors include: + + * internal socket queue receive errors + * packet too short (less than 8 bytes or stated + coverage length exceeds received length) + * xfrm4_policy_check() returned with error + * application has specified larger min. coverage + length than that of incoming packet + * checksum coverage violated + * bad checksum + + OutDatagrams Total number of sent datagrams. + ============ ===================================================== + + These statistics derive from the UDP MIB (RFC 2013). + +6. IPtables +=========== + + There is packet match support for UDP-Lite as well as support for the LOG target. + If you copy and paste the following line into /etc/protocols:: + + udplite 136 UDP-Lite # UDP-Lite [RFC 3828] + + then:: + + iptables -A INPUT -p udplite -j LOG + + will produce logging output to syslog. Dropping and rejecting packets also works. + +7. Maintainer Address +===================== + + The UDP-Lite patch was developed at + + University of Aberdeen + Electronics Research Group + Department of Engineering + Fraser Noble Building + Aberdeen AB24 3UE; UK + + The current maintainer is Gerrit Renker, . Initial + code was developed by William Stanislaus, . diff --git a/Documentation/networking/udplite.txt b/Documentation/networking/udplite.txt deleted file mode 100644 index 53a726855e49..000000000000 --- a/Documentation/networking/udplite.txt +++ /dev/null @@ -1,278 +0,0 @@ - =========================================================================== - The UDP-Lite protocol (RFC 3828) - =========================================================================== - - - UDP-Lite is a Standards-Track IETF transport protocol whose characteristic - is a variable-length checksum. This has advantages for transport of multimedia - (video, VoIP) over wireless networks, as partly damaged packets can still be - fed into the codec instead of being discarded due to a failed checksum test. - - This file briefly describes the existing kernel support and the socket API. - For in-depth information, you can consult: - - o The UDP-Lite Homepage: - http://web.archive.org/web/*/http://www.erg.abdn.ac.uk/users/gerrit/udp-lite/ - From here you can also download some example application source code. - - o The UDP-Lite HOWTO on - http://web.archive.org/web/*/http://www.erg.abdn.ac.uk/users/gerrit/udp-lite/ - files/UDP-Lite-HOWTO.txt - - o The Wireshark UDP-Lite WiKi (with capture files): - https://wiki.wireshark.org/Lightweight_User_Datagram_Protocol - - o The Protocol Spec, RFC 3828, http://www.ietf.org/rfc/rfc3828.txt - - - I) APPLICATIONS - - Several applications have been ported successfully to UDP-Lite. Ethereal - (now called wireshark) has UDP-Litev4/v6 support by default. - Porting applications to UDP-Lite is straightforward: only socket level and - IPPROTO need to be changed; senders additionally set the checksum coverage - length (default = header length = 8). Details are in the next section. - - - II) PROGRAMMING API - - UDP-Lite provides a connectionless, unreliable datagram service and hence - uses the same socket type as UDP. In fact, porting from UDP to UDP-Lite is - very easy: simply add `IPPROTO_UDPLITE' as the last argument of the socket(2) - call so that the statement looks like: - - s = socket(PF_INET, SOCK_DGRAM, IPPROTO_UDPLITE); - - or, respectively, - - s = socket(PF_INET6, SOCK_DGRAM, IPPROTO_UDPLITE); - - With just the above change you are able to run UDP-Lite services or connect - to UDP-Lite servers. The kernel will assume that you are not interested in - using partial checksum coverage and so emulate UDP mode (full coverage). - - To make use of the partial checksum coverage facilities requires setting a - single socket option, which takes an integer specifying the coverage length: - - * Sender checksum coverage: UDPLITE_SEND_CSCOV - - For example, - - int val = 20; - setsockopt(s, SOL_UDPLITE, UDPLITE_SEND_CSCOV, &val, sizeof(int)); - - sets the checksum coverage length to 20 bytes (12b data + 8b header). - Of each packet only the first 20 bytes (plus the pseudo-header) will be - checksummed. This is useful for RTP applications which have a 12-byte - base header. - - - * Receiver checksum coverage: UDPLITE_RECV_CSCOV - - This option is the receiver-side analogue. It is truly optional, i.e. not - required to enable traffic with partial checksum coverage. Its function is - that of a traffic filter: when enabled, it instructs the kernel to drop - all packets which have a coverage _less_ than this value. For example, if - RTP and UDP headers are to be protected, a receiver can enforce that only - packets with a minimum coverage of 20 are admitted: - - int min = 20; - setsockopt(s, SOL_UDPLITE, UDPLITE_RECV_CSCOV, &min, sizeof(int)); - - The calls to getsockopt(2) are analogous. Being an extension and not a stand- - alone protocol, all socket options known from UDP can be used in exactly the - same manner as before, e.g. UDP_CORK or UDP_ENCAP. - - A detailed discussion of UDP-Lite checksum coverage options is in section IV. - - - III) HEADER FILES - - The socket API requires support through header files in /usr/include: - - * /usr/include/netinet/in.h - to define IPPROTO_UDPLITE - - * /usr/include/netinet/udplite.h - for UDP-Lite header fields and protocol constants - - For testing purposes, the following can serve as a `mini' header file: - - #define IPPROTO_UDPLITE 136 - #define SOL_UDPLITE 136 - #define UDPLITE_SEND_CSCOV 10 - #define UDPLITE_RECV_CSCOV 11 - - Ready-made header files for various distros are in the UDP-Lite tarball. - - - IV) KERNEL BEHAVIOUR WITH REGARD TO THE VARIOUS SOCKET OPTIONS - - To enable debugging messages, the log level need to be set to 8, as most - messages use the KERN_DEBUG level (7). - - 1) Sender Socket Options - - If the sender specifies a value of 0 as coverage length, the module - assumes full coverage, transmits a packet with coverage length of 0 - and according checksum. If the sender specifies a coverage < 8 and - different from 0, the kernel assumes 8 as default value. Finally, - if the specified coverage length exceeds the packet length, the packet - length is used instead as coverage length. - - 2) Receiver Socket Options - - The receiver specifies the minimum value of the coverage length it - is willing to accept. A value of 0 here indicates that the receiver - always wants the whole of the packet covered. In this case, all - partially covered packets are dropped and an error is logged. - - It is not possible to specify illegal values (<0 and <8); in these - cases the default of 8 is assumed. - - All packets arriving with a coverage value less than the specified - threshold are discarded, these events are also logged. - - 3) Disabling the Checksum Computation - - On both sender and receiver, checksumming will always be performed - and cannot be disabled using SO_NO_CHECK. Thus - - setsockopt(sockfd, SOL_SOCKET, SO_NO_CHECK, ... ); - - will always will be ignored, while the value of - - getsockopt(sockfd, SOL_SOCKET, SO_NO_CHECK, &value, ...); - - is meaningless (as in TCP). Packets with a zero checksum field are - illegal (cf. RFC 3828, sec. 3.1) and will be silently discarded. - - 4) Fragmentation - - The checksum computation respects both buffersize and MTU. The size - of UDP-Lite packets is determined by the size of the send buffer. The - minimum size of the send buffer is 2048 (defined as SOCK_MIN_SNDBUF - in include/net/sock.h), the default value is configurable as - net.core.wmem_default or via setting the SO_SNDBUF socket(7) - option. The maximum upper bound for the send buffer is determined - by net.core.wmem_max. - - Given a payload size larger than the send buffer size, UDP-Lite will - split the payload into several individual packets, filling up the - send buffer size in each case. - - The precise value also depends on the interface MTU. The interface MTU, - in turn, may trigger IP fragmentation. In this case, the generated - UDP-Lite packet is split into several IP packets, of which only the - first one contains the L4 header. - - The send buffer size has implications on the checksum coverage length. - Consider the following example: - - Payload: 1536 bytes Send Buffer: 1024 bytes - MTU: 1500 bytes Coverage Length: 856 bytes - - UDP-Lite will ship the 1536 bytes in two separate packets: - - Packet 1: 1024 payload + 8 byte header + 20 byte IP header = 1052 bytes - Packet 2: 512 payload + 8 byte header + 20 byte IP header = 540 bytes - - The coverage packet covers the UDP-Lite header and 848 bytes of the - payload in the first packet, the second packet is fully covered. Note - that for the second packet, the coverage length exceeds the packet - length. The kernel always re-adjusts the coverage length to the packet - length in such cases. - - As an example of what happens when one UDP-Lite packet is split into - several tiny fragments, consider the following example. - - Payload: 1024 bytes Send buffer size: 1024 bytes - MTU: 300 bytes Coverage length: 575 bytes - - +-+-----------+--------------+--------------+--------------+ - |8| 272 | 280 | 280 | 280 | - +-+-----------+--------------+--------------+--------------+ - 280 560 840 1032 - ^ - *****checksum coverage************* - - The UDP-Lite module generates one 1032 byte packet (1024 + 8 byte - header). According to the interface MTU, these are split into 4 IP - packets (280 byte IP payload + 20 byte IP header). The kernel module - sums the contents of the entire first two packets, plus 15 bytes of - the last packet before releasing the fragments to the IP module. - - To see the analogous case for IPv6 fragmentation, consider a link - MTU of 1280 bytes and a write buffer of 3356 bytes. If the checksum - coverage is less than 1232 bytes (MTU minus IPv6/fragment header - lengths), only the first fragment needs to be considered. When using - larger checksum coverage lengths, each eligible fragment needs to be - checksummed. Suppose we have a checksum coverage of 3062. The buffer - of 3356 bytes will be split into the following fragments: - - Fragment 1: 1280 bytes carrying 1232 bytes of UDP-Lite data - Fragment 2: 1280 bytes carrying 1232 bytes of UDP-Lite data - Fragment 3: 948 bytes carrying 900 bytes of UDP-Lite data - - The first two fragments have to be checksummed in full, of the last - fragment only 598 (= 3062 - 2*1232) bytes are checksummed. - - While it is important that such cases are dealt with correctly, they - are (annoyingly) rare: UDP-Lite is designed for optimising multimedia - performance over wireless (or generally noisy) links and thus smaller - coverage lengths are likely to be expected. - - - V) UDP-LITE RUNTIME STATISTICS AND THEIR MEANING - - Exceptional and error conditions are logged to syslog at the KERN_DEBUG - level. Live statistics about UDP-Lite are available in /proc/net/snmp - and can (with newer versions of netstat) be viewed using - - netstat -svu - - This displays UDP-Lite statistics variables, whose meaning is as follows. - - InDatagrams: The total number of datagrams delivered to users. - - NoPorts: Number of packets received to an unknown port. - These cases are counted separately (not as InErrors). - - InErrors: Number of erroneous UDP-Lite packets. Errors include: - * internal socket queue receive errors - * packet too short (less than 8 bytes or stated - coverage length exceeds received length) - * xfrm4_policy_check() returned with error - * application has specified larger min. coverage - length than that of incoming packet - * checksum coverage violated - * bad checksum - - OutDatagrams: Total number of sent datagrams. - - These statistics derive from the UDP MIB (RFC 2013). - - - VI) IPTABLES - - There is packet match support for UDP-Lite as well as support for the LOG target. - If you copy and paste the following line into /etc/protocols, - - udplite 136 UDP-Lite # UDP-Lite [RFC 3828] - - then - iptables -A INPUT -p udplite -j LOG - - will produce logging output to syslog. Dropping and rejecting packets also works. - - - VII) MAINTAINER ADDRESS - - The UDP-Lite patch was developed at - University of Aberdeen - Electronics Research Group - Department of Engineering - Fraser Noble Building - Aberdeen AB24 3UE; UK - The current maintainer is Gerrit Renker, . Initial - code was developed by William Stanislaus, . -- cgit From 58ccb2b2e87d52ec0b4cbd40b94e0b63e90af873 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 1 May 2020 16:44:25 +0200 Subject: docs: networking: convert vrf.txt to ReST - add SPDX header; - adjust title markup; - Add a subtitle for the first section; - mark code blocks and literals as such; - adjust identation, whitespaces and blank lines; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab Acked-by: David Ahern Signed-off-by: David S. Miller --- Documentation/networking/index.rst | 1 + Documentation/networking/vrf.rst | 451 +++++++++++++++++++++++++++++++++++++ Documentation/networking/vrf.txt | 418 ---------------------------------- MAINTAINERS | 2 +- 4 files changed, 453 insertions(+), 419 deletions(-) create mode 100644 Documentation/networking/vrf.rst delete mode 100644 Documentation/networking/vrf.txt diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index ca0b0dbfd9ad..2227b9f4509d 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -113,6 +113,7 @@ Contents: tproxy tuntap udplite + vrf .. only:: subproject and html diff --git a/Documentation/networking/vrf.rst b/Documentation/networking/vrf.rst new file mode 100644 index 000000000000..0dde145043bc --- /dev/null +++ b/Documentation/networking/vrf.rst @@ -0,0 +1,451 @@ +.. SPDX-License-Identifier: GPL-2.0 + +==================================== +Virtual Routing and Forwarding (VRF) +==================================== + +The VRF Device +============== + +The VRF device combined with ip rules provides the ability to create virtual +routing and forwarding domains (aka VRFs, VRF-lite to be specific) in the +Linux network stack. One use case is the multi-tenancy problem where each +tenant has their own unique routing tables and in the very least need +different default gateways. + +Processes can be "VRF aware" by binding a socket to the VRF device. Packets +through the socket then use the routing table associated with the VRF +device. An important feature of the VRF device implementation is that it +impacts only Layer 3 and above so L2 tools (e.g., LLDP) are not affected +(ie., they do not need to be run in each VRF). The design also allows +the use of higher priority ip rules (Policy Based Routing, PBR) to take +precedence over the VRF device rules directing specific traffic as desired. + +In addition, VRF devices allow VRFs to be nested within namespaces. For +example network namespaces provide separation of network interfaces at the +device layer, VLANs on the interfaces within a namespace provide L2 separation +and then VRF devices provide L3 separation. + +Design +------ +A VRF device is created with an associated route table. Network interfaces +are then enslaved to a VRF device:: + + +-----------------------------+ + | vrf-blue | ===> route table 10 + +-----------------------------+ + | | | + +------+ +------+ +-------------+ + | eth1 | | eth2 | ... | bond1 | + +------+ +------+ +-------------+ + | | + +------+ +------+ + | eth8 | | eth9 | + +------+ +------+ + +Packets received on an enslaved device and are switched to the VRF device +in the IPv4 and IPv6 processing stacks giving the impression that packets +flow through the VRF device. Similarly on egress routing rules are used to +send packets to the VRF device driver before getting sent out the actual +interface. This allows tcpdump on a VRF device to capture all packets into +and out of the VRF as a whole\ [1]_. Similarly, netfilter\ [2]_ and tc rules +can be applied using the VRF device to specify rules that apply to the VRF +domain as a whole. + +.. [1] Packets in the forwarded state do not flow through the device, so those + packets are not seen by tcpdump. Will revisit this limitation in a + future release. + +.. [2] Iptables on ingress supports PREROUTING with skb->dev set to the real + ingress device and both INPUT and PREROUTING rules with skb->dev set to + the VRF device. For egress POSTROUTING and OUTPUT rules can be written + using either the VRF device or real egress device. + +Setup +----- +1. VRF device is created with an association to a FIB table. + e.g,:: + + ip link add vrf-blue type vrf table 10 + ip link set dev vrf-blue up + +2. An l3mdev FIB rule directs lookups to the table associated with the device. + A single l3mdev rule is sufficient for all VRFs. The VRF device adds the + l3mdev rule for IPv4 and IPv6 when the first device is created with a + default preference of 1000. Users may delete the rule if desired and add + with a different priority or install per-VRF rules. + + Prior to the v4.8 kernel iif and oif rules are needed for each VRF device:: + + ip ru add oif vrf-blue table 10 + ip ru add iif vrf-blue table 10 + +3. Set the default route for the table (and hence default route for the VRF):: + + ip route add table 10 unreachable default metric 4278198272 + + This high metric value ensures that the default unreachable route can + be overridden by a routing protocol suite. FRRouting interprets + kernel metrics as a combined admin distance (upper byte) and priority + (lower 3 bytes). Thus the above metric translates to [255/8192]. + +4. Enslave L3 interfaces to a VRF device:: + + ip link set dev eth1 master vrf-blue + + Local and connected routes for enslaved devices are automatically moved to + the table associated with VRF device. Any additional routes depending on + the enslaved device are dropped and will need to be reinserted to the VRF + FIB table following the enslavement. + + The IPv6 sysctl option keep_addr_on_down can be enabled to keep IPv6 global + addresses as VRF enslavement changes:: + + sysctl -w net.ipv6.conf.all.keep_addr_on_down=1 + +5. Additional VRF routes are added to associated table:: + + ip route add table 10 ... + + +Applications +------------ +Applications that are to work within a VRF need to bind their socket to the +VRF device:: + + setsockopt(sd, SOL_SOCKET, SO_BINDTODEVICE, dev, strlen(dev)+1); + +or to specify the output device using cmsg and IP_PKTINFO. + +By default the scope of the port bindings for unbound sockets is +limited to the default VRF. That is, it will not be matched by packets +arriving on interfaces enslaved to an l3mdev and processes may bind to +the same port if they bind to an l3mdev. + +TCP & UDP services running in the default VRF context (ie., not bound +to any VRF device) can work across all VRF domains by enabling the +tcp_l3mdev_accept and udp_l3mdev_accept sysctl options:: + + sysctl -w net.ipv4.tcp_l3mdev_accept=1 + sysctl -w net.ipv4.udp_l3mdev_accept=1 + +These options are disabled by default so that a socket in a VRF is only +selected for packets in that VRF. There is a similar option for RAW +sockets, which is enabled by default for reasons of backwards compatibility. +This is so as to specify the output device with cmsg and IP_PKTINFO, but +using a socket not bound to the corresponding VRF. This allows e.g. older ping +implementations to be run with specifying the device but without executing it +in the VRF. This option can be disabled so that packets received in a VRF +context are only handled by a raw socket bound to the VRF, and packets in the +default VRF are only handled by a socket not bound to any VRF:: + + sysctl -w net.ipv4.raw_l3mdev_accept=0 + +netfilter rules on the VRF device can be used to limit access to services +running in the default VRF context as well. + +-------------------------------------------------------------------------------- + +Using iproute2 for VRFs +======================= +iproute2 supports the vrf keyword as of v4.7. For backwards compatibility this +section lists both commands where appropriate -- with the vrf keyword and the +older form without it. + +1. Create a VRF + + To instantiate a VRF device and associate it with a table:: + + $ ip link add dev NAME type vrf table ID + + As of v4.8 the kernel supports the l3mdev FIB rule where a single rule + covers all VRFs. The l3mdev rule is created for IPv4 and IPv6 on first + device create. + +2. List VRFs + + To list VRFs that have been created:: + + $ ip [-d] link show type vrf + NOTE: The -d option is needed to show the table id + + For example:: + + $ ip -d link show type vrf + 11: mgmt: mtu 1500 qdisc pfifo_fast state UP mode DEFAULT group default qlen 1000 + link/ether 72:b3:ba:91:e2:24 brd ff:ff:ff:ff:ff:ff promiscuity 0 + vrf table 1 addrgenmode eui64 + 12: red: mtu 1500 qdisc pfifo_fast state UP mode DEFAULT group default qlen 1000 + link/ether b6:6f:6e:f6:da:73 brd ff:ff:ff:ff:ff:ff promiscuity 0 + vrf table 10 addrgenmode eui64 + 13: blue: mtu 1500 qdisc pfifo_fast state UP mode DEFAULT group default qlen 1000 + link/ether 36:62:e8:7d:bb:8c brd ff:ff:ff:ff:ff:ff promiscuity 0 + vrf table 66 addrgenmode eui64 + 14: green: mtu 1500 qdisc pfifo_fast state UP mode DEFAULT group default qlen 1000 + link/ether e6:28:b8:63:70:bb brd ff:ff:ff:ff:ff:ff promiscuity 0 + vrf table 81 addrgenmode eui64 + + + Or in brief output:: + + $ ip -br link show type vrf + mgmt UP 72:b3:ba:91:e2:24 + red UP b6:6f:6e:f6:da:73 + blue UP 36:62:e8:7d:bb:8c + green UP e6:28:b8:63:70:bb + + +3. Assign a Network Interface to a VRF + + Network interfaces are assigned to a VRF by enslaving the netdevice to a + VRF device:: + + $ ip link set dev NAME master NAME + + On enslavement connected and local routes are automatically moved to the + table associated with the VRF device. + + For example:: + + $ ip link set dev eth0 master mgmt + + +4. Show Devices Assigned to a VRF + + To show devices that have been assigned to a specific VRF add the master + option to the ip command:: + + $ ip link show vrf NAME + $ ip link show master NAME + + For example:: + + $ ip link show vrf red + 3: eth1: mtu 1500 qdisc pfifo_fast master red state UP mode DEFAULT group default qlen 1000 + link/ether 02:00:00:00:02:02 brd ff:ff:ff:ff:ff:ff + 4: eth2: mtu 1500 qdisc pfifo_fast master red state UP mode DEFAULT group default qlen 1000 + link/ether 02:00:00:00:02:03 brd ff:ff:ff:ff:ff:ff + 7: eth5: mtu 1500 qdisc noop master red state DOWN mode DEFAULT group default qlen 1000 + link/ether 02:00:00:00:02:06 brd ff:ff:ff:ff:ff:ff + + + Or using the brief output:: + + $ ip -br link show vrf red + eth1 UP 02:00:00:00:02:02 + eth2 UP 02:00:00:00:02:03 + eth5 DOWN 02:00:00:00:02:06 + + +5. Show Neighbor Entries for a VRF + + To list neighbor entries associated with devices enslaved to a VRF device + add the master option to the ip command:: + + $ ip [-6] neigh show vrf NAME + $ ip [-6] neigh show master NAME + + For example:: + + $ ip neigh show vrf red + 10.2.1.254 dev eth1 lladdr a6:d9:c7:4f:06:23 REACHABLE + 10.2.2.254 dev eth2 lladdr 5e:54:01:6a:ee:80 REACHABLE + + $ ip -6 neigh show vrf red + 2002:1::64 dev eth1 lladdr a6:d9:c7:4f:06:23 REACHABLE + + +6. Show Addresses for a VRF + + To show addresses for interfaces associated with a VRF add the master + option to the ip command:: + + $ ip addr show vrf NAME + $ ip addr show master NAME + + For example:: + + $ ip addr show vrf red + 3: eth1: mtu 1500 qdisc pfifo_fast master red state UP group default qlen 1000 + link/ether 02:00:00:00:02:02 brd ff:ff:ff:ff:ff:ff + inet 10.2.1.2/24 brd 10.2.1.255 scope global eth1 + valid_lft forever preferred_lft forever + inet6 2002:1::2/120 scope global + valid_lft forever preferred_lft forever + inet6 fe80::ff:fe00:202/64 scope link + valid_lft forever preferred_lft forever + 4: eth2: mtu 1500 qdisc pfifo_fast master red state UP group default qlen 1000 + link/ether 02:00:00:00:02:03 brd ff:ff:ff:ff:ff:ff + inet 10.2.2.2/24 brd 10.2.2.255 scope global eth2 + valid_lft forever preferred_lft forever + inet6 2002:2::2/120 scope global + valid_lft forever preferred_lft forever + inet6 fe80::ff:fe00:203/64 scope link + valid_lft forever preferred_lft forever + 7: eth5: mtu 1500 qdisc noop master red state DOWN group default qlen 1000 + link/ether 02:00:00:00:02:06 brd ff:ff:ff:ff:ff:ff + + Or in brief format:: + + $ ip -br addr show vrf red + eth1 UP 10.2.1.2/24 2002:1::2/120 fe80::ff:fe00:202/64 + eth2 UP 10.2.2.2/24 2002:2::2/120 fe80::ff:fe00:203/64 + eth5 DOWN + + +7. Show Routes for a VRF + + To show routes for a VRF use the ip command to display the table associated + with the VRF device:: + + $ ip [-6] route show vrf NAME + $ ip [-6] route show table ID + + For example:: + + $ ip route show vrf red + unreachable default metric 4278198272 + broadcast 10.2.1.0 dev eth1 proto kernel scope link src 10.2.1.2 + 10.2.1.0/24 dev eth1 proto kernel scope link src 10.2.1.2 + local 10.2.1.2 dev eth1 proto kernel scope host src 10.2.1.2 + broadcast 10.2.1.255 dev eth1 proto kernel scope link src 10.2.1.2 + broadcast 10.2.2.0 dev eth2 proto kernel scope link src 10.2.2.2 + 10.2.2.0/24 dev eth2 proto kernel scope link src 10.2.2.2 + local 10.2.2.2 dev eth2 proto kernel scope host src 10.2.2.2 + broadcast 10.2.2.255 dev eth2 proto kernel scope link src 10.2.2.2 + + $ ip -6 route show vrf red + local 2002:1:: dev lo proto none metric 0 pref medium + local 2002:1::2 dev lo proto none metric 0 pref medium + 2002:1::/120 dev eth1 proto kernel metric 256 pref medium + local 2002:2:: dev lo proto none metric 0 pref medium + local 2002:2::2 dev lo proto none metric 0 pref medium + 2002:2::/120 dev eth2 proto kernel metric 256 pref medium + local fe80:: dev lo proto none metric 0 pref medium + local fe80:: dev lo proto none metric 0 pref medium + local fe80::ff:fe00:202 dev lo proto none metric 0 pref medium + local fe80::ff:fe00:203 dev lo proto none metric 0 pref medium + fe80::/64 dev eth1 proto kernel metric 256 pref medium + fe80::/64 dev eth2 proto kernel metric 256 pref medium + ff00::/8 dev red metric 256 pref medium + ff00::/8 dev eth1 metric 256 pref medium + ff00::/8 dev eth2 metric 256 pref medium + unreachable default dev lo metric 4278198272 error -101 pref medium + +8. Route Lookup for a VRF + + A test route lookup can be done for a VRF:: + + $ ip [-6] route get vrf NAME ADDRESS + $ ip [-6] route get oif NAME ADDRESS + + For example:: + + $ ip route get 10.2.1.40 vrf red + 10.2.1.40 dev eth1 table red src 10.2.1.2 + cache + + $ ip -6 route get 2002:1::32 vrf red + 2002:1::32 from :: dev eth1 table red proto kernel src 2002:1::2 metric 256 pref medium + + +9. Removing Network Interface from a VRF + + Network interfaces are removed from a VRF by breaking the enslavement to + the VRF device:: + + $ ip link set dev NAME nomaster + + Connected routes are moved back to the default table and local entries are + moved to the local table. + + For example:: + + $ ip link set dev eth0 nomaster + +-------------------------------------------------------------------------------- + +Commands used in this example:: + + cat >> /etc/iproute2/rt_tables.d/vrf.conf < route table 10 - +-----------------------------+ - | | | - +------+ +------+ +-------------+ - | eth1 | | eth2 | ... | bond1 | - +------+ +------+ +-------------+ - | | - +------+ +------+ - | eth8 | | eth9 | - +------+ +------+ - -Packets received on an enslaved device and are switched to the VRF device -in the IPv4 and IPv6 processing stacks giving the impression that packets -flow through the VRF device. Similarly on egress routing rules are used to -send packets to the VRF device driver before getting sent out the actual -interface. This allows tcpdump on a VRF device to capture all packets into -and out of the VRF as a whole.[1] Similarly, netfilter[2] and tc rules can be -applied using the VRF device to specify rules that apply to the VRF domain -as a whole. - -[1] Packets in the forwarded state do not flow through the device, so those - packets are not seen by tcpdump. Will revisit this limitation in a - future release. - -[2] Iptables on ingress supports PREROUTING with skb->dev set to the real - ingress device and both INPUT and PREROUTING rules with skb->dev set to - the VRF device. For egress POSTROUTING and OUTPUT rules can be written - using either the VRF device or real egress device. - -Setup ------ -1. VRF device is created with an association to a FIB table. - e.g, ip link add vrf-blue type vrf table 10 - ip link set dev vrf-blue up - -2. An l3mdev FIB rule directs lookups to the table associated with the device. - A single l3mdev rule is sufficient for all VRFs. The VRF device adds the - l3mdev rule for IPv4 and IPv6 when the first device is created with a - default preference of 1000. Users may delete the rule if desired and add - with a different priority or install per-VRF rules. - - Prior to the v4.8 kernel iif and oif rules are needed for each VRF device: - ip ru add oif vrf-blue table 10 - ip ru add iif vrf-blue table 10 - -3. Set the default route for the table (and hence default route for the VRF). - ip route add table 10 unreachable default metric 4278198272 - - This high metric value ensures that the default unreachable route can - be overridden by a routing protocol suite. FRRouting interprets - kernel metrics as a combined admin distance (upper byte) and priority - (lower 3 bytes). Thus the above metric translates to [255/8192]. - -4. Enslave L3 interfaces to a VRF device. - ip link set dev eth1 master vrf-blue - - Local and connected routes for enslaved devices are automatically moved to - the table associated with VRF device. Any additional routes depending on - the enslaved device are dropped and will need to be reinserted to the VRF - FIB table following the enslavement. - - The IPv6 sysctl option keep_addr_on_down can be enabled to keep IPv6 global - addresses as VRF enslavement changes. - sysctl -w net.ipv6.conf.all.keep_addr_on_down=1 - -5. Additional VRF routes are added to associated table. - ip route add table 10 ... - - -Applications ------------- -Applications that are to work within a VRF need to bind their socket to the -VRF device: - - setsockopt(sd, SOL_SOCKET, SO_BINDTODEVICE, dev, strlen(dev)+1); - -or to specify the output device using cmsg and IP_PKTINFO. - -By default the scope of the port bindings for unbound sockets is -limited to the default VRF. That is, it will not be matched by packets -arriving on interfaces enslaved to an l3mdev and processes may bind to -the same port if they bind to an l3mdev. - -TCP & UDP services running in the default VRF context (ie., not bound -to any VRF device) can work across all VRF domains by enabling the -tcp_l3mdev_accept and udp_l3mdev_accept sysctl options: - - sysctl -w net.ipv4.tcp_l3mdev_accept=1 - sysctl -w net.ipv4.udp_l3mdev_accept=1 - -These options are disabled by default so that a socket in a VRF is only -selected for packets in that VRF. There is a similar option for RAW -sockets, which is enabled by default for reasons of backwards compatibility. -This is so as to specify the output device with cmsg and IP_PKTINFO, but -using a socket not bound to the corresponding VRF. This allows e.g. older ping -implementations to be run with specifying the device but without executing it -in the VRF. This option can be disabled so that packets received in a VRF -context are only handled by a raw socket bound to the VRF, and packets in the -default VRF are only handled by a socket not bound to any VRF: - - sysctl -w net.ipv4.raw_l3mdev_accept=0 - -netfilter rules on the VRF device can be used to limit access to services -running in the default VRF context as well. - -################################################################################ - -Using iproute2 for VRFs -======================= -iproute2 supports the vrf keyword as of v4.7. For backwards compatibility this -section lists both commands where appropriate -- with the vrf keyword and the -older form without it. - -1. Create a VRF - - To instantiate a VRF device and associate it with a table: - $ ip link add dev NAME type vrf table ID - - As of v4.8 the kernel supports the l3mdev FIB rule where a single rule - covers all VRFs. The l3mdev rule is created for IPv4 and IPv6 on first - device create. - -2. List VRFs - - To list VRFs that have been created: - $ ip [-d] link show type vrf - NOTE: The -d option is needed to show the table id - - For example: - $ ip -d link show type vrf - 11: mgmt: mtu 1500 qdisc pfifo_fast state UP mode DEFAULT group default qlen 1000 - link/ether 72:b3:ba:91:e2:24 brd ff:ff:ff:ff:ff:ff promiscuity 0 - vrf table 1 addrgenmode eui64 - 12: red: mtu 1500 qdisc pfifo_fast state UP mode DEFAULT group default qlen 1000 - link/ether b6:6f:6e:f6:da:73 brd ff:ff:ff:ff:ff:ff promiscuity 0 - vrf table 10 addrgenmode eui64 - 13: blue: mtu 1500 qdisc pfifo_fast state UP mode DEFAULT group default qlen 1000 - link/ether 36:62:e8:7d:bb:8c brd ff:ff:ff:ff:ff:ff promiscuity 0 - vrf table 66 addrgenmode eui64 - 14: green: mtu 1500 qdisc pfifo_fast state UP mode DEFAULT group default qlen 1000 - link/ether e6:28:b8:63:70:bb brd ff:ff:ff:ff:ff:ff promiscuity 0 - vrf table 81 addrgenmode eui64 - - - Or in brief output: - - $ ip -br link show type vrf - mgmt UP 72:b3:ba:91:e2:24 - red UP b6:6f:6e:f6:da:73 - blue UP 36:62:e8:7d:bb:8c - green UP e6:28:b8:63:70:bb - - -3. Assign a Network Interface to a VRF - - Network interfaces are assigned to a VRF by enslaving the netdevice to a - VRF device: - $ ip link set dev NAME master NAME - - On enslavement connected and local routes are automatically moved to the - table associated with the VRF device. - - For example: - $ ip link set dev eth0 master mgmt - - -4. Show Devices Assigned to a VRF - - To show devices that have been assigned to a specific VRF add the master - option to the ip command: - $ ip link show vrf NAME - $ ip link show master NAME - - For example: - $ ip link show vrf red - 3: eth1: mtu 1500 qdisc pfifo_fast master red state UP mode DEFAULT group default qlen 1000 - link/ether 02:00:00:00:02:02 brd ff:ff:ff:ff:ff:ff - 4: eth2: mtu 1500 qdisc pfifo_fast master red state UP mode DEFAULT group default qlen 1000 - link/ether 02:00:00:00:02:03 brd ff:ff:ff:ff:ff:ff - 7: eth5: mtu 1500 qdisc noop master red state DOWN mode DEFAULT group default qlen 1000 - link/ether 02:00:00:00:02:06 brd ff:ff:ff:ff:ff:ff - - - Or using the brief output: - $ ip -br link show vrf red - eth1 UP 02:00:00:00:02:02 - eth2 UP 02:00:00:00:02:03 - eth5 DOWN 02:00:00:00:02:06 - - -5. Show Neighbor Entries for a VRF - - To list neighbor entries associated with devices enslaved to a VRF device - add the master option to the ip command: - $ ip [-6] neigh show vrf NAME - $ ip [-6] neigh show master NAME - - For example: - $ ip neigh show vrf red - 10.2.1.254 dev eth1 lladdr a6:d9:c7:4f:06:23 REACHABLE - 10.2.2.254 dev eth2 lladdr 5e:54:01:6a:ee:80 REACHABLE - - $ ip -6 neigh show vrf red - 2002:1::64 dev eth1 lladdr a6:d9:c7:4f:06:23 REACHABLE - - -6. Show Addresses for a VRF - - To show addresses for interfaces associated with a VRF add the master - option to the ip command: - $ ip addr show vrf NAME - $ ip addr show master NAME - - For example: - $ ip addr show vrf red - 3: eth1: mtu 1500 qdisc pfifo_fast master red state UP group default qlen 1000 - link/ether 02:00:00:00:02:02 brd ff:ff:ff:ff:ff:ff - inet 10.2.1.2/24 brd 10.2.1.255 scope global eth1 - valid_lft forever preferred_lft forever - inet6 2002:1::2/120 scope global - valid_lft forever preferred_lft forever - inet6 fe80::ff:fe00:202/64 scope link - valid_lft forever preferred_lft forever - 4: eth2: mtu 1500 qdisc pfifo_fast master red state UP group default qlen 1000 - link/ether 02:00:00:00:02:03 brd ff:ff:ff:ff:ff:ff - inet 10.2.2.2/24 brd 10.2.2.255 scope global eth2 - valid_lft forever preferred_lft forever - inet6 2002:2::2/120 scope global - valid_lft forever preferred_lft forever - inet6 fe80::ff:fe00:203/64 scope link - valid_lft forever preferred_lft forever - 7: eth5: mtu 1500 qdisc noop master red state DOWN group default qlen 1000 - link/ether 02:00:00:00:02:06 brd ff:ff:ff:ff:ff:ff - - Or in brief format: - $ ip -br addr show vrf red - eth1 UP 10.2.1.2/24 2002:1::2/120 fe80::ff:fe00:202/64 - eth2 UP 10.2.2.2/24 2002:2::2/120 fe80::ff:fe00:203/64 - eth5 DOWN - - -7. Show Routes for a VRF - - To show routes for a VRF use the ip command to display the table associated - with the VRF device: - $ ip [-6] route show vrf NAME - $ ip [-6] route show table ID - - For example: - $ ip route show vrf red - unreachable default metric 4278198272 - broadcast 10.2.1.0 dev eth1 proto kernel scope link src 10.2.1.2 - 10.2.1.0/24 dev eth1 proto kernel scope link src 10.2.1.2 - local 10.2.1.2 dev eth1 proto kernel scope host src 10.2.1.2 - broadcast 10.2.1.255 dev eth1 proto kernel scope link src 10.2.1.2 - broadcast 10.2.2.0 dev eth2 proto kernel scope link src 10.2.2.2 - 10.2.2.0/24 dev eth2 proto kernel scope link src 10.2.2.2 - local 10.2.2.2 dev eth2 proto kernel scope host src 10.2.2.2 - broadcast 10.2.2.255 dev eth2 proto kernel scope link src 10.2.2.2 - - $ ip -6 route show vrf red - local 2002:1:: dev lo proto none metric 0 pref medium - local 2002:1::2 dev lo proto none metric 0 pref medium - 2002:1::/120 dev eth1 proto kernel metric 256 pref medium - local 2002:2:: dev lo proto none metric 0 pref medium - local 2002:2::2 dev lo proto none metric 0 pref medium - 2002:2::/120 dev eth2 proto kernel metric 256 pref medium - local fe80:: dev lo proto none metric 0 pref medium - local fe80:: dev lo proto none metric 0 pref medium - local fe80::ff:fe00:202 dev lo proto none metric 0 pref medium - local fe80::ff:fe00:203 dev lo proto none metric 0 pref medium - fe80::/64 dev eth1 proto kernel metric 256 pref medium - fe80::/64 dev eth2 proto kernel metric 256 pref medium - ff00::/8 dev red metric 256 pref medium - ff00::/8 dev eth1 metric 256 pref medium - ff00::/8 dev eth2 metric 256 pref medium - unreachable default dev lo metric 4278198272 error -101 pref medium - -8. Route Lookup for a VRF - - A test route lookup can be done for a VRF: - $ ip [-6] route get vrf NAME ADDRESS - $ ip [-6] route get oif NAME ADDRESS - - For example: - $ ip route get 10.2.1.40 vrf red - 10.2.1.40 dev eth1 table red src 10.2.1.2 - cache - - $ ip -6 route get 2002:1::32 vrf red - 2002:1::32 from :: dev eth1 table red proto kernel src 2002:1::2 metric 256 pref medium - - -9. Removing Network Interface from a VRF - - Network interfaces are removed from a VRF by breaking the enslavement to - the VRF device: - $ ip link set dev NAME nomaster - - Connected routes are moved back to the default table and local entries are - moved to the local table. - - For example: - $ ip link set dev eth0 nomaster - --------------------------------------------------------------------------------- - -Commands used in this example: - -cat >> /etc/iproute2/rt_tables.d/vrf.conf < M: Shrijeet Mukherjee L: netdev@vger.kernel.org S: Maintained -F: Documentation/networking/vrf.txt +F: Documentation/networking/vrf.rst F: drivers/net/vrf.c VSPRINTF -- cgit From d2a85c184ac6e738daa5e42f89b1f353910d6a89 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 1 May 2020 16:44:26 +0200 Subject: docs: networking: convert vxlan.txt to ReST - add SPDX header; - adjust title markup; - mark code blocks and literals as such; - adjust identation, whitespaces and blank lines where needed; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: David S. Miller --- Documentation/networking/index.rst | 1 + Documentation/networking/vxlan.rst | 60 ++++++++++++++++++++++++++++++++++++++ Documentation/networking/vxlan.txt | 51 -------------------------------- 3 files changed, 61 insertions(+), 51 deletions(-) create mode 100644 Documentation/networking/vxlan.rst delete mode 100644 Documentation/networking/vxlan.txt diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index 2227b9f4509d..a72fdfb391b6 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -114,6 +114,7 @@ Contents: tuntap udplite vrf + vxlan .. only:: subproject and html diff --git a/Documentation/networking/vxlan.rst b/Documentation/networking/vxlan.rst new file mode 100644 index 000000000000..ce239fa01848 --- /dev/null +++ b/Documentation/networking/vxlan.rst @@ -0,0 +1,60 @@ +.. SPDX-License-Identifier: GPL-2.0 + +====================================================== +Virtual eXtensible Local Area Networking documentation +====================================================== + +The VXLAN protocol is a tunnelling protocol designed to solve the +problem of limited VLAN IDs (4096) in IEEE 802.1q. With VXLAN the +size of the identifier is expanded to 24 bits (16777216). + +VXLAN is described by IETF RFC 7348, and has been implemented by a +number of vendors. The protocol runs over UDP using a single +destination port. This document describes the Linux kernel tunnel +device, there is also a separate implementation of VXLAN for +Openvswitch. + +Unlike most tunnels, a VXLAN is a 1 to N network, not just point to +point. A VXLAN device can learn the IP address of the other endpoint +either dynamically in a manner similar to a learning bridge, or make +use of statically-configured forwarding entries. + +The management of vxlan is done in a manner similar to its two closest +neighbors GRE and VLAN. Configuring VXLAN requires the version of +iproute2 that matches the kernel release where VXLAN was first merged +upstream. + +1. Create vxlan device:: + + # ip link add vxlan0 type vxlan id 42 group 239.1.1.1 dev eth1 dstport 4789 + +This creates a new device named vxlan0. The device uses the multicast +group 239.1.1.1 over eth1 to handle traffic for which there is no +entry in the forwarding table. The destination port number is set to +the IANA-assigned value of 4789. The Linux implementation of VXLAN +pre-dates the IANA's selection of a standard destination port number +and uses the Linux-selected value by default to maintain backwards +compatibility. + +2. Delete vxlan device:: + + # ip link delete vxlan0 + +3. Show vxlan info:: + + # ip -d link show vxlan0 + +It is possible to create, destroy and display the vxlan +forwarding table using the new bridge command. + +1. Create forwarding table entry:: + + # bridge fdb add to 00:17:42:8a:b4:05 dst 192.19.0.2 dev vxlan0 + +2. Delete forwarding table entry:: + + # bridge fdb delete 00:17:42:8a:b4:05 dev vxlan0 + +3. Show forwarding table:: + + # bridge fdb show dev vxlan0 diff --git a/Documentation/networking/vxlan.txt b/Documentation/networking/vxlan.txt deleted file mode 100644 index c28f4989c3f0..000000000000 --- a/Documentation/networking/vxlan.txt +++ /dev/null @@ -1,51 +0,0 @@ -Virtual eXtensible Local Area Networking documentation -====================================================== - -The VXLAN protocol is a tunnelling protocol designed to solve the -problem of limited VLAN IDs (4096) in IEEE 802.1q. With VXLAN the -size of the identifier is expanded to 24 bits (16777216). - -VXLAN is described by IETF RFC 7348, and has been implemented by a -number of vendors. The protocol runs over UDP using a single -destination port. This document describes the Linux kernel tunnel -device, there is also a separate implementation of VXLAN for -Openvswitch. - -Unlike most tunnels, a VXLAN is a 1 to N network, not just point to -point. A VXLAN device can learn the IP address of the other endpoint -either dynamically in a manner similar to a learning bridge, or make -use of statically-configured forwarding entries. - -The management of vxlan is done in a manner similar to its two closest -neighbors GRE and VLAN. Configuring VXLAN requires the version of -iproute2 that matches the kernel release where VXLAN was first merged -upstream. - -1. Create vxlan device - # ip link add vxlan0 type vxlan id 42 group 239.1.1.1 dev eth1 dstport 4789 - -This creates a new device named vxlan0. The device uses the multicast -group 239.1.1.1 over eth1 to handle traffic for which there is no -entry in the forwarding table. The destination port number is set to -the IANA-assigned value of 4789. The Linux implementation of VXLAN -pre-dates the IANA's selection of a standard destination port number -and uses the Linux-selected value by default to maintain backwards -compatibility. - -2. Delete vxlan device - # ip link delete vxlan0 - -3. Show vxlan info - # ip -d link show vxlan0 - -It is possible to create, destroy and display the vxlan -forwarding table using the new bridge command. - -1. Create forwarding table entry - # bridge fdb add to 00:17:42:8a:b4:05 dst 192.19.0.2 dev vxlan0 - -2. Delete forwarding table entry - # bridge fdb delete 00:17:42:8a:b4:05 dev vxlan0 - -3. Show forwarding table - # bridge fdb show dev vxlan0 -- cgit From 883780af72090daf9ab53779a3085a6ddfc468ca Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 1 May 2020 16:44:27 +0200 Subject: docs: networking: convert x25-iface.txt to ReST Not much to be done here: - add SPDX header; - adjust title markup; - remove a tail whitespace; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: David S. Miller --- Documentation/networking/index.rst | 1 + Documentation/networking/x25-iface.rst | 129 +++++++++++++++++++++++++++++++++ Documentation/networking/x25-iface.txt | 123 ------------------------------- include/uapi/linux/if_x25.h | 2 +- net/x25/Kconfig | 2 +- 5 files changed, 132 insertions(+), 125 deletions(-) create mode 100644 Documentation/networking/x25-iface.rst delete mode 100644 Documentation/networking/x25-iface.txt diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index a72fdfb391b6..7a4bdbc111b0 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -115,6 +115,7 @@ Contents: udplite vrf vxlan + x25-iface .. only:: subproject and html diff --git a/Documentation/networking/x25-iface.rst b/Documentation/networking/x25-iface.rst new file mode 100644 index 000000000000..df401891dce6 --- /dev/null +++ b/Documentation/networking/x25-iface.rst @@ -0,0 +1,129 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================- +X.25 Device Driver Interface +============================- + +Version 1.1 + + Jonathan Naylor 26.12.96 + +This is a description of the messages to be passed between the X.25 Packet +Layer and the X.25 device driver. They are designed to allow for the easy +setting of the LAPB mode from within the Packet Layer. + +The X.25 device driver will be coded normally as per the Linux device driver +standards. Most X.25 device drivers will be moderately similar to the +already existing Ethernet device drivers. However unlike those drivers, the +X.25 device driver has a state associated with it, and this information +needs to be passed to and from the Packet Layer for proper operation. + +All messages are held in sk_buff's just like real data to be transmitted +over the LAPB link. The first byte of the skbuff indicates the meaning of +the rest of the skbuff, if any more information does exist. + + +Packet Layer to Device Driver +----------------------------- + +First Byte = 0x00 (X25_IFACE_DATA) + +This indicates that the rest of the skbuff contains data to be transmitted +over the LAPB link. The LAPB link should already exist before any data is +passed down. + +First Byte = 0x01 (X25_IFACE_CONNECT) + +Establish the LAPB link. If the link is already established then the connect +confirmation message should be returned as soon as possible. + +First Byte = 0x02 (X25_IFACE_DISCONNECT) + +Terminate the LAPB link. If it is already disconnected then the disconnect +confirmation message should be returned as soon as possible. + +First Byte = 0x03 (X25_IFACE_PARAMS) + +LAPB parameters. To be defined. + + +Device Driver to Packet Layer +----------------------------- + +First Byte = 0x00 (X25_IFACE_DATA) + +This indicates that the rest of the skbuff contains data that has been +received over the LAPB link. + +First Byte = 0x01 (X25_IFACE_CONNECT) + +LAPB link has been established. The same message is used for both a LAPB +link connect_confirmation and a connect_indication. + +First Byte = 0x02 (X25_IFACE_DISCONNECT) + +LAPB link has been terminated. This same message is used for both a LAPB +link disconnect_confirmation and a disconnect_indication. + +First Byte = 0x03 (X25_IFACE_PARAMS) + +LAPB parameters. To be defined. + + + +Possible Problems +================= + +(Henner Eisen, 2000-10-28) + +The X.25 packet layer protocol depends on a reliable datalink service. +The LAPB protocol provides such reliable service. But this reliability +is not preserved by the Linux network device driver interface: + +- With Linux 2.4.x (and above) SMP kernels, packet ordering is not + preserved. Even if a device driver calls netif_rx(skb1) and later + netif_rx(skb2), skb2 might be delivered to the network layer + earlier that skb1. +- Data passed upstream by means of netif_rx() might be dropped by the + kernel if the backlog queue is congested. + +The X.25 packet layer protocol will detect this and reset the virtual +call in question. But many upper layer protocols are not designed to +handle such N-Reset events gracefully. And frequent N-Reset events +will always degrade performance. + +Thus, driver authors should make netif_rx() as reliable as possible: + +SMP re-ordering will not occur if the driver's interrupt handler is +always executed on the same CPU. Thus, + +- Driver authors should use irq affinity for the interrupt handler. + +The probability of packet loss due to backlog congestion can be +reduced by the following measures or a combination thereof: + +(1) Drivers for kernel versions 2.4.x and above should always check the + return value of netif_rx(). If it returns NET_RX_DROP, the + driver's LAPB protocol must not confirm reception of the frame + to the peer. + This will reliably suppress packet loss. The LAPB protocol will + automatically cause the peer to re-transmit the dropped packet + later. + The lapb module interface was modified to support this. Its + data_indication() method should now transparently pass the + netif_rx() return value to the (lapb module) caller. +(2) Drivers for kernel versions 2.2.x should always check the global + variable netdev_dropping when a new frame is received. The driver + should only call netif_rx() if netdev_dropping is zero. Otherwise + the driver should not confirm delivery of the frame and drop it. + Alternatively, the driver can queue the frame internally and call + netif_rx() later when netif_dropping is 0 again. In that case, delivery + confirmation should also be deferred such that the internal queue + cannot grow to much. + This will not reliably avoid packet loss, but the probability + of packet loss in netif_rx() path will be significantly reduced. +(3) Additionally, driver authors might consider to support + CONFIG_NET_HW_FLOWCONTROL. This allows the driver to be woken up + when a previously congested backlog queue becomes empty again. + The driver could uses this for flow-controlling the peer by means + of the LAPB protocol's flow-control service. diff --git a/Documentation/networking/x25-iface.txt b/Documentation/networking/x25-iface.txt deleted file mode 100644 index 7f213b556e85..000000000000 --- a/Documentation/networking/x25-iface.txt +++ /dev/null @@ -1,123 +0,0 @@ - X.25 Device Driver Interface 1.1 - - Jonathan Naylor 26.12.96 - -This is a description of the messages to be passed between the X.25 Packet -Layer and the X.25 device driver. They are designed to allow for the easy -setting of the LAPB mode from within the Packet Layer. - -The X.25 device driver will be coded normally as per the Linux device driver -standards. Most X.25 device drivers will be moderately similar to the -already existing Ethernet device drivers. However unlike those drivers, the -X.25 device driver has a state associated with it, and this information -needs to be passed to and from the Packet Layer for proper operation. - -All messages are held in sk_buff's just like real data to be transmitted -over the LAPB link. The first byte of the skbuff indicates the meaning of -the rest of the skbuff, if any more information does exist. - - -Packet Layer to Device Driver ------------------------------ - -First Byte = 0x00 (X25_IFACE_DATA) - -This indicates that the rest of the skbuff contains data to be transmitted -over the LAPB link. The LAPB link should already exist before any data is -passed down. - -First Byte = 0x01 (X25_IFACE_CONNECT) - -Establish the LAPB link. If the link is already established then the connect -confirmation message should be returned as soon as possible. - -First Byte = 0x02 (X25_IFACE_DISCONNECT) - -Terminate the LAPB link. If it is already disconnected then the disconnect -confirmation message should be returned as soon as possible. - -First Byte = 0x03 (X25_IFACE_PARAMS) - -LAPB parameters. To be defined. - - -Device Driver to Packet Layer ------------------------------ - -First Byte = 0x00 (X25_IFACE_DATA) - -This indicates that the rest of the skbuff contains data that has been -received over the LAPB link. - -First Byte = 0x01 (X25_IFACE_CONNECT) - -LAPB link has been established. The same message is used for both a LAPB -link connect_confirmation and a connect_indication. - -First Byte = 0x02 (X25_IFACE_DISCONNECT) - -LAPB link has been terminated. This same message is used for both a LAPB -link disconnect_confirmation and a disconnect_indication. - -First Byte = 0x03 (X25_IFACE_PARAMS) - -LAPB parameters. To be defined. - - - -Possible Problems -================= - -(Henner Eisen, 2000-10-28) - -The X.25 packet layer protocol depends on a reliable datalink service. -The LAPB protocol provides such reliable service. But this reliability -is not preserved by the Linux network device driver interface: - -- With Linux 2.4.x (and above) SMP kernels, packet ordering is not - preserved. Even if a device driver calls netif_rx(skb1) and later - netif_rx(skb2), skb2 might be delivered to the network layer - earlier that skb1. -- Data passed upstream by means of netif_rx() might be dropped by the - kernel if the backlog queue is congested. - -The X.25 packet layer protocol will detect this and reset the virtual -call in question. But many upper layer protocols are not designed to -handle such N-Reset events gracefully. And frequent N-Reset events -will always degrade performance. - -Thus, driver authors should make netif_rx() as reliable as possible: - -SMP re-ordering will not occur if the driver's interrupt handler is -always executed on the same CPU. Thus, - -- Driver authors should use irq affinity for the interrupt handler. - -The probability of packet loss due to backlog congestion can be -reduced by the following measures or a combination thereof: - -(1) Drivers for kernel versions 2.4.x and above should always check the - return value of netif_rx(). If it returns NET_RX_DROP, the - driver's LAPB protocol must not confirm reception of the frame - to the peer. - This will reliably suppress packet loss. The LAPB protocol will - automatically cause the peer to re-transmit the dropped packet - later. - The lapb module interface was modified to support this. Its - data_indication() method should now transparently pass the - netif_rx() return value to the (lapb module) caller. -(2) Drivers for kernel versions 2.2.x should always check the global - variable netdev_dropping when a new frame is received. The driver - should only call netif_rx() if netdev_dropping is zero. Otherwise - the driver should not confirm delivery of the frame and drop it. - Alternatively, the driver can queue the frame internally and call - netif_rx() later when netif_dropping is 0 again. In that case, delivery - confirmation should also be deferred such that the internal queue - cannot grow to much. - This will not reliably avoid packet loss, but the probability - of packet loss in netif_rx() path will be significantly reduced. -(3) Additionally, driver authors might consider to support - CONFIG_NET_HW_FLOWCONTROL. This allows the driver to be woken up - when a previously congested backlog queue becomes empty again. - The driver could uses this for flow-controlling the peer by means - of the LAPB protocol's flow-control service. diff --git a/include/uapi/linux/if_x25.h b/include/uapi/linux/if_x25.h index 5d962448345f..3a5938e38370 100644 --- a/include/uapi/linux/if_x25.h +++ b/include/uapi/linux/if_x25.h @@ -18,7 +18,7 @@ #include -/* Documentation/networking/x25-iface.txt */ +/* Documentation/networking/x25-iface.rst */ #define X25_IFACE_DATA 0x00 #define X25_IFACE_CONNECT 0x01 #define X25_IFACE_DISCONNECT 0x02 diff --git a/net/x25/Kconfig b/net/x25/Kconfig index 2ecb2e5e241e..a328f79885d1 100644 --- a/net/x25/Kconfig +++ b/net/x25/Kconfig @@ -21,7 +21,7 @@ config X25 . Information about X.25 for Linux is contained in the files and - . + . One connects to an X.25 network either with a dedicated network card using the X.21 protocol (not yet supported by Linux) or one can do -- cgit From c4ea03fdfd122b4ff293bff643c2369852e9cc1c Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 1 May 2020 16:44:28 +0200 Subject: docs: networking: convert x25.txt to ReST Not much to be done here: - add SPDX header; - add a document title; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: David S. Miller --- Documentation/networking/index.rst | 1 + Documentation/networking/x25.rst | 48 ++++++++++++++++++++++++++++++++++++++ Documentation/networking/x25.txt | 44 ---------------------------------- net/x25/Kconfig | 2 +- 4 files changed, 50 insertions(+), 45 deletions(-) create mode 100644 Documentation/networking/x25.rst delete mode 100644 Documentation/networking/x25.txt diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index 7a4bdbc111b0..75521e6c473b 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -116,6 +116,7 @@ Contents: vrf vxlan x25-iface + x25 .. only:: subproject and html diff --git a/Documentation/networking/x25.rst b/Documentation/networking/x25.rst new file mode 100644 index 000000000000..00e45d384ba0 --- /dev/null +++ b/Documentation/networking/x25.rst @@ -0,0 +1,48 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================== +Linux X.25 Project +================== + +As my third year dissertation at University I have taken it upon myself to +write an X.25 implementation for Linux. My aim is to provide a complete X.25 +Packet Layer and a LAPB module to allow for "normal" X.25 to be run using +Linux. There are two sorts of X.25 cards available, intelligent ones that +implement LAPB on the card itself, and unintelligent ones that simply do +framing, bit-stuffing and checksumming. These both need to be handled by the +system. + +I therefore decided to write the implementation such that as far as the +Packet Layer is concerned, the link layer was being performed by a lower +layer of the Linux kernel and therefore it did not concern itself with +implementation of LAPB. Therefore the LAPB modules would be called by +unintelligent X.25 card drivers and not by intelligent ones, this would +provide a uniform device driver interface, and simplify configuration. + +To confuse matters a little, an 802.2 LLC implementation for Linux is being +written which will allow X.25 to be run over an Ethernet (or Token Ring) and +conform with the JNT "Pink Book", this will have a different interface to +the Packet Layer but there will be no confusion since the class of device +being served by the LLC will be completely separate from LAPB. The LLC +implementation is being done as part of another protocol project (SNA) and +by a different author. + +Just when you thought that it could not become more confusing, another +option appeared, XOT. This allows X.25 Packet Layer frames to operate over +the Internet using TCP/IP as a reliable link layer. RFC1613 specifies the +format and behaviour of the protocol. If time permits this option will also +be actively considered. + +A linux-x25 mailing list has been created at vger.kernel.org to support the +development and use of Linux X.25. It is early days yet, but interested +parties are welcome to subscribe to it. Just send a message to +majordomo@vger.kernel.org with the following in the message body: + +subscribe linux-x25 +end + +The contents of the Subject line are ignored. + +Jonathan + +g4klx@g4klx.demon.co.uk diff --git a/Documentation/networking/x25.txt b/Documentation/networking/x25.txt deleted file mode 100644 index c91c6d7159ff..000000000000 --- a/Documentation/networking/x25.txt +++ /dev/null @@ -1,44 +0,0 @@ -Linux X.25 Project - -As my third year dissertation at University I have taken it upon myself to -write an X.25 implementation for Linux. My aim is to provide a complete X.25 -Packet Layer and a LAPB module to allow for "normal" X.25 to be run using -Linux. There are two sorts of X.25 cards available, intelligent ones that -implement LAPB on the card itself, and unintelligent ones that simply do -framing, bit-stuffing and checksumming. These both need to be handled by the -system. - -I therefore decided to write the implementation such that as far as the -Packet Layer is concerned, the link layer was being performed by a lower -layer of the Linux kernel and therefore it did not concern itself with -implementation of LAPB. Therefore the LAPB modules would be called by -unintelligent X.25 card drivers and not by intelligent ones, this would -provide a uniform device driver interface, and simplify configuration. - -To confuse matters a little, an 802.2 LLC implementation for Linux is being -written which will allow X.25 to be run over an Ethernet (or Token Ring) and -conform with the JNT "Pink Book", this will have a different interface to -the Packet Layer but there will be no confusion since the class of device -being served by the LLC will be completely separate from LAPB. The LLC -implementation is being done as part of another protocol project (SNA) and -by a different author. - -Just when you thought that it could not become more confusing, another -option appeared, XOT. This allows X.25 Packet Layer frames to operate over -the Internet using TCP/IP as a reliable link layer. RFC1613 specifies the -format and behaviour of the protocol. If time permits this option will also -be actively considered. - -A linux-x25 mailing list has been created at vger.kernel.org to support the -development and use of Linux X.25. It is early days yet, but interested -parties are welcome to subscribe to it. Just send a message to -majordomo@vger.kernel.org with the following in the message body: - -subscribe linux-x25 -end - -The contents of the Subject line are ignored. - -Jonathan - -g4klx@g4klx.demon.co.uk diff --git a/net/x25/Kconfig b/net/x25/Kconfig index a328f79885d1..9f0d58b0b90b 100644 --- a/net/x25/Kconfig +++ b/net/x25/Kconfig @@ -20,7 +20,7 @@ config X25 You can read more about X.25 at and . Information about X.25 for Linux is contained in the files - and + and . One connects to an X.25 network either with a dedicated network card -- cgit From c4a0eb9350183d1d188793c534e4141bcf2ccea8 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 1 May 2020 16:44:29 +0200 Subject: docs: networking: convert xfrm_device.txt to ReST - add SPDX header; - mark code blocks and literals as such; - mark tables as such; - adjust identation, whitespaces and blank lines where needed; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: David S. Miller --- Documentation/networking/index.rst | 1 + Documentation/networking/xfrm_device.rst | 151 +++++++++++++++++++++++++++++++ Documentation/networking/xfrm_device.txt | 140 ---------------------------- 3 files changed, 152 insertions(+), 140 deletions(-) create mode 100644 Documentation/networking/xfrm_device.rst delete mode 100644 Documentation/networking/xfrm_device.txt diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index 75521e6c473b..e31f6cb564b4 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -117,6 +117,7 @@ Contents: vxlan x25-iface x25 + xfrm_device .. only:: subproject and html diff --git a/Documentation/networking/xfrm_device.rst b/Documentation/networking/xfrm_device.rst new file mode 100644 index 000000000000..da1073acda96 --- /dev/null +++ b/Documentation/networking/xfrm_device.rst @@ -0,0 +1,151 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=============================================== +XFRM device - offloading the IPsec computations +=============================================== + +Shannon Nelson + + +Overview +======== + +IPsec is a useful feature for securing network traffic, but the +computational cost is high: a 10Gbps link can easily be brought down +to under 1Gbps, depending on the traffic and link configuration. +Luckily, there are NICs that offer a hardware based IPsec offload which +can radically increase throughput and decrease CPU utilization. The XFRM +Device interface allows NIC drivers to offer to the stack access to the +hardware offload. + +Userland access to the offload is typically through a system such as +libreswan or KAME/raccoon, but the iproute2 'ip xfrm' command set can +be handy when experimenting. An example command might look something +like this:: + + ip x s add proto esp dst 14.0.0.70 src 14.0.0.52 spi 0x07 mode transport \ + reqid 0x07 replay-window 32 \ + aead 'rfc4106(gcm(aes))' 0x44434241343332312423222114131211f4f3f2f1 128 \ + sel src 14.0.0.52/24 dst 14.0.0.70/24 proto tcp \ + offload dev eth4 dir in + +Yes, that's ugly, but that's what shell scripts and/or libreswan are for. + + + +Callbacks to implement +====================== + +:: + + /* from include/linux/netdevice.h */ + struct xfrmdev_ops { + int (*xdo_dev_state_add) (struct xfrm_state *x); + void (*xdo_dev_state_delete) (struct xfrm_state *x); + void (*xdo_dev_state_free) (struct xfrm_state *x); + bool (*xdo_dev_offload_ok) (struct sk_buff *skb, + struct xfrm_state *x); + void (*xdo_dev_state_advance_esn) (struct xfrm_state *x); + }; + +The NIC driver offering ipsec offload will need to implement these +callbacks to make the offload available to the network stack's +XFRM subsytem. Additionally, the feature bits NETIF_F_HW_ESP and +NETIF_F_HW_ESP_TX_CSUM will signal the availability of the offload. + + + +Flow +==== + +At probe time and before the call to register_netdev(), the driver should +set up local data structures and XFRM callbacks, and set the feature bits. +The XFRM code's listener will finish the setup on NETDEV_REGISTER. + +:: + + adapter->netdev->xfrmdev_ops = &ixgbe_xfrmdev_ops; + adapter->netdev->features |= NETIF_F_HW_ESP; + adapter->netdev->hw_enc_features |= NETIF_F_HW_ESP; + +When new SAs are set up with a request for "offload" feature, the +driver's xdo_dev_state_add() will be given the new SA to be offloaded +and an indication of whether it is for Rx or Tx. The driver should + + - verify the algorithm is supported for offloads + - store the SA information (key, salt, target-ip, protocol, etc) + - enable the HW offload of the SA + - return status value: + + =========== =================================== + 0 success + -EOPNETSUPP offload not supported, try SW IPsec + other fail the request + =========== =================================== + +The driver can also set an offload_handle in the SA, an opaque void pointer +that can be used to convey context into the fast-path offload requests:: + + xs->xso.offload_handle = context; + + +When the network stack is preparing an IPsec packet for an SA that has +been setup for offload, it first calls into xdo_dev_offload_ok() with +the skb and the intended offload state to ask the driver if the offload +will serviceable. This can check the packet information to be sure the +offload can be supported (e.g. IPv4 or IPv6, no IPv4 options, etc) and +return true of false to signify its support. + +When ready to send, the driver needs to inspect the Tx packet for the +offload information, including the opaque context, and set up the packet +send accordingly:: + + xs = xfrm_input_state(skb); + context = xs->xso.offload_handle; + set up HW for send + +The stack has already inserted the appropriate IPsec headers in the +packet data, the offload just needs to do the encryption and fix up the +header values. + + +When a packet is received and the HW has indicated that it offloaded a +decryption, the driver needs to add a reference to the decoded SA into +the packet's skb. At this point the data should be decrypted but the +IPsec headers are still in the packet data; they are removed later up +the stack in xfrm_input(). + + find and hold the SA that was used to the Rx skb:: + + get spi, protocol, and destination IP from packet headers + xs = find xs from (spi, protocol, dest_IP) + xfrm_state_hold(xs); + + store the state information into the skb:: + + sp = secpath_set(skb); + if (!sp) return; + sp->xvec[sp->len++] = xs; + sp->olen++; + + indicate the success and/or error status of the offload:: + + xo = xfrm_offload(skb); + xo->flags = CRYPTO_DONE; + xo->status = crypto_status; + + hand the packet to napi_gro_receive() as usual + +In ESN mode, xdo_dev_state_advance_esn() is called from xfrm_replay_advance_esn(). +Driver will check packet seq number and update HW ESN state machine if needed. + +When the SA is removed by the user, the driver's xdo_dev_state_delete() +is asked to disable the offload. Later, xdo_dev_state_free() is called +from a garbage collection routine after all reference counts to the state +have been removed and any remaining resources can be cleared for the +offload state. How these are used by the driver will depend on specific +hardware needs. + +As a netdev is set to DOWN the XFRM stack's netdev listener will call +xdo_dev_state_delete() and xdo_dev_state_free() on any remaining offloaded +states. diff --git a/Documentation/networking/xfrm_device.txt b/Documentation/networking/xfrm_device.txt deleted file mode 100644 index a1c904dc70dc..000000000000 --- a/Documentation/networking/xfrm_device.txt +++ /dev/null @@ -1,140 +0,0 @@ - -=============================================== -XFRM device - offloading the IPsec computations -=============================================== -Shannon Nelson - - -Overview -======== - -IPsec is a useful feature for securing network traffic, but the -computational cost is high: a 10Gbps link can easily be brought down -to under 1Gbps, depending on the traffic and link configuration. -Luckily, there are NICs that offer a hardware based IPsec offload which -can radically increase throughput and decrease CPU utilization. The XFRM -Device interface allows NIC drivers to offer to the stack access to the -hardware offload. - -Userland access to the offload is typically through a system such as -libreswan or KAME/raccoon, but the iproute2 'ip xfrm' command set can -be handy when experimenting. An example command might look something -like this: - - ip x s add proto esp dst 14.0.0.70 src 14.0.0.52 spi 0x07 mode transport \ - reqid 0x07 replay-window 32 \ - aead 'rfc4106(gcm(aes))' 0x44434241343332312423222114131211f4f3f2f1 128 \ - sel src 14.0.0.52/24 dst 14.0.0.70/24 proto tcp \ - offload dev eth4 dir in - -Yes, that's ugly, but that's what shell scripts and/or libreswan are for. - - - -Callbacks to implement -====================== - -/* from include/linux/netdevice.h */ -struct xfrmdev_ops { - int (*xdo_dev_state_add) (struct xfrm_state *x); - void (*xdo_dev_state_delete) (struct xfrm_state *x); - void (*xdo_dev_state_free) (struct xfrm_state *x); - bool (*xdo_dev_offload_ok) (struct sk_buff *skb, - struct xfrm_state *x); - void (*xdo_dev_state_advance_esn) (struct xfrm_state *x); -}; - -The NIC driver offering ipsec offload will need to implement these -callbacks to make the offload available to the network stack's -XFRM subsytem. Additionally, the feature bits NETIF_F_HW_ESP and -NETIF_F_HW_ESP_TX_CSUM will signal the availability of the offload. - - - -Flow -==== - -At probe time and before the call to register_netdev(), the driver should -set up local data structures and XFRM callbacks, and set the feature bits. -The XFRM code's listener will finish the setup on NETDEV_REGISTER. - - adapter->netdev->xfrmdev_ops = &ixgbe_xfrmdev_ops; - adapter->netdev->features |= NETIF_F_HW_ESP; - adapter->netdev->hw_enc_features |= NETIF_F_HW_ESP; - -When new SAs are set up with a request for "offload" feature, the -driver's xdo_dev_state_add() will be given the new SA to be offloaded -and an indication of whether it is for Rx or Tx. The driver should - - verify the algorithm is supported for offloads - - store the SA information (key, salt, target-ip, protocol, etc) - - enable the HW offload of the SA - - return status value: - 0 success - -EOPNETSUPP offload not supported, try SW IPsec - other fail the request - -The driver can also set an offload_handle in the SA, an opaque void pointer -that can be used to convey context into the fast-path offload requests. - - xs->xso.offload_handle = context; - - -When the network stack is preparing an IPsec packet for an SA that has -been setup for offload, it first calls into xdo_dev_offload_ok() with -the skb and the intended offload state to ask the driver if the offload -will serviceable. This can check the packet information to be sure the -offload can be supported (e.g. IPv4 or IPv6, no IPv4 options, etc) and -return true of false to signify its support. - -When ready to send, the driver needs to inspect the Tx packet for the -offload information, including the opaque context, and set up the packet -send accordingly. - - xs = xfrm_input_state(skb); - context = xs->xso.offload_handle; - set up HW for send - -The stack has already inserted the appropriate IPsec headers in the -packet data, the offload just needs to do the encryption and fix up the -header values. - - -When a packet is received and the HW has indicated that it offloaded a -decryption, the driver needs to add a reference to the decoded SA into -the packet's skb. At this point the data should be decrypted but the -IPsec headers are still in the packet data; they are removed later up -the stack in xfrm_input(). - - find and hold the SA that was used to the Rx skb - get spi, protocol, and destination IP from packet headers - xs = find xs from (spi, protocol, dest_IP) - xfrm_state_hold(xs); - - store the state information into the skb - sp = secpath_set(skb); - if (!sp) return; - sp->xvec[sp->len++] = xs; - sp->olen++; - - indicate the success and/or error status of the offload - xo = xfrm_offload(skb); - xo->flags = CRYPTO_DONE; - xo->status = crypto_status; - - hand the packet to napi_gro_receive() as usual - -In ESN mode, xdo_dev_state_advance_esn() is called from xfrm_replay_advance_esn(). -Driver will check packet seq number and update HW ESN state machine if needed. - -When the SA is removed by the user, the driver's xdo_dev_state_delete() -is asked to disable the offload. Later, xdo_dev_state_free() is called -from a garbage collection routine after all reference counts to the state -have been removed and any remaining resources can be cleared for the -offload state. How these are used by the driver will depend on specific -hardware needs. - -As a netdev is set to DOWN the XFRM stack's netdev listener will call -xdo_dev_state_delete() and xdo_dev_state_free() on any remaining offloaded -states. - - -- cgit From da62baada5cc94037ef91ed0c414a930a3a06520 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 1 May 2020 16:44:30 +0200 Subject: docs: networking: convert xfrm_proc.txt to ReST - add SPDX header; - adjust title markup; - adjust identation, whitespaces and blank lines where needed; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: David S. Miller --- Documentation/networking/index.rst | 1 + Documentation/networking/xfrm_proc.rst | 113 +++++++++++++++++++++++++++++++++ Documentation/networking/xfrm_proc.txt | 82 ------------------------ 3 files changed, 114 insertions(+), 82 deletions(-) create mode 100644 Documentation/networking/xfrm_proc.rst delete mode 100644 Documentation/networking/xfrm_proc.txt diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index e31f6cb564b4..3fe70efb632e 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -118,6 +118,7 @@ Contents: x25-iface x25 xfrm_device + xfrm_proc .. only:: subproject and html diff --git a/Documentation/networking/xfrm_proc.rst b/Documentation/networking/xfrm_proc.rst new file mode 100644 index 000000000000..0a771c5a7399 --- /dev/null +++ b/Documentation/networking/xfrm_proc.rst @@ -0,0 +1,113 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================== +XFRM proc - /proc/net/xfrm_* files +================================== + +Masahide NAKAMURA + + +Transformation Statistics +------------------------- + +The xfrm_proc code is a set of statistics showing numbers of packets +dropped by the transformation code and why. These counters are defined +as part of the linux private MIB. These counters can be viewed in +/proc/net/xfrm_stat. + + +Inbound errors +~~~~~~~~~~~~~~ + +XfrmInError: + All errors which is not matched others + +XfrmInBufferError: + No buffer is left + +XfrmInHdrError: + Header error + +XfrmInNoStates: + No state is found + i.e. Either inbound SPI, address, or IPsec protocol at SA is wrong + +XfrmInStateProtoError: + Transformation protocol specific error + e.g. SA key is wrong + +XfrmInStateModeError: + Transformation mode specific error + +XfrmInStateSeqError: + Sequence error + i.e. Sequence number is out of window + +XfrmInStateExpired: + State is expired + +XfrmInStateMismatch: + State has mismatch option + e.g. UDP encapsulation type is mismatch + +XfrmInStateInvalid: + State is invalid + +XfrmInTmplMismatch: + No matching template for states + e.g. Inbound SAs are correct but SP rule is wrong + +XfrmInNoPols: + No policy is found for states + e.g. Inbound SAs are correct but no SP is found + +XfrmInPolBlock: + Policy discards + +XfrmInPolError: + Policy error + +XfrmAcquireError: + State hasn't been fully acquired before use + +XfrmFwdHdrError: + Forward routing of a packet is not allowed + +Outbound errors +~~~~~~~~~~~~~~~ +XfrmOutError: + All errors which is not matched others + +XfrmOutBundleGenError: + Bundle generation error + +XfrmOutBundleCheckError: + Bundle check error + +XfrmOutNoStates: + No state is found + +XfrmOutStateProtoError: + Transformation protocol specific error + +XfrmOutStateModeError: + Transformation mode specific error + +XfrmOutStateSeqError: + Sequence error + i.e. Sequence number overflow + +XfrmOutStateExpired: + State is expired + +XfrmOutPolBlock: + Policy discards + +XfrmOutPolDead: + Policy is dead + +XfrmOutPolError: + Policy error + +XfrmOutStateInvalid: + State is invalid, perhaps expired diff --git a/Documentation/networking/xfrm_proc.txt b/Documentation/networking/xfrm_proc.txt deleted file mode 100644 index 2eae619ab67b..000000000000 --- a/Documentation/networking/xfrm_proc.txt +++ /dev/null @@ -1,82 +0,0 @@ -XFRM proc - /proc/net/xfrm_* files -================================== -Masahide NAKAMURA - - -Transformation Statistics -------------------------- - -The xfrm_proc code is a set of statistics showing numbers of packets -dropped by the transformation code and why. These counters are defined -as part of the linux private MIB. These counters can be viewed in -/proc/net/xfrm_stat. - - -Inbound errors -~~~~~~~~~~~~~~ -XfrmInError: - All errors which is not matched others -XfrmInBufferError: - No buffer is left -XfrmInHdrError: - Header error -XfrmInNoStates: - No state is found - i.e. Either inbound SPI, address, or IPsec protocol at SA is wrong -XfrmInStateProtoError: - Transformation protocol specific error - e.g. SA key is wrong -XfrmInStateModeError: - Transformation mode specific error -XfrmInStateSeqError: - Sequence error - i.e. Sequence number is out of window -XfrmInStateExpired: - State is expired -XfrmInStateMismatch: - State has mismatch option - e.g. UDP encapsulation type is mismatch -XfrmInStateInvalid: - State is invalid -XfrmInTmplMismatch: - No matching template for states - e.g. Inbound SAs are correct but SP rule is wrong -XfrmInNoPols: - No policy is found for states - e.g. Inbound SAs are correct but no SP is found -XfrmInPolBlock: - Policy discards -XfrmInPolError: - Policy error -XfrmAcquireError: - State hasn't been fully acquired before use -XfrmFwdHdrError: - Forward routing of a packet is not allowed - -Outbound errors -~~~~~~~~~~~~~~~ -XfrmOutError: - All errors which is not matched others -XfrmOutBundleGenError: - Bundle generation error -XfrmOutBundleCheckError: - Bundle check error -XfrmOutNoStates: - No state is found -XfrmOutStateProtoError: - Transformation protocol specific error -XfrmOutStateModeError: - Transformation mode specific error -XfrmOutStateSeqError: - Sequence error - i.e. Sequence number overflow -XfrmOutStateExpired: - State is expired -XfrmOutPolBlock: - Policy discards -XfrmOutPolDead: - Policy is dead -XfrmOutPolError: - Policy error -XfrmOutStateInvalid: - State is invalid, perhaps expired -- cgit From a5cfea33e5e54854fa541deb08b85b782f21bab5 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 1 May 2020 16:44:31 +0200 Subject: docs: networking: convert xfrm_sync.txt to ReST - add SPDX header; - add a document title; - adjust titles and chapters, adding proper markups; - mark code blocks and literals as such; - adjust identation, whitespaces and blank lines where needed; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: David S. Miller --- Documentation/networking/index.rst | 1 + Documentation/networking/xfrm_sync.rst | 189 +++++++++++++++++++++++++++++++++ Documentation/networking/xfrm_sync.txt | 169 ----------------------------- 3 files changed, 190 insertions(+), 169 deletions(-) create mode 100644 Documentation/networking/xfrm_sync.rst delete mode 100644 Documentation/networking/xfrm_sync.txt diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index 3fe70efb632e..ec83bd95e4e9 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -119,6 +119,7 @@ Contents: x25 xfrm_device xfrm_proc + xfrm_sync .. only:: subproject and html diff --git a/Documentation/networking/xfrm_sync.rst b/Documentation/networking/xfrm_sync.rst new file mode 100644 index 000000000000..6246503ceab2 --- /dev/null +++ b/Documentation/networking/xfrm_sync.rst @@ -0,0 +1,189 @@ +.. SPDX-License-Identifier: GPL-2.0 + +==== +XFRM +==== + +The sync patches work is based on initial patches from +Krisztian and others and additional patches +from Jamal . + +The end goal for syncing is to be able to insert attributes + generate +events so that the SA can be safely moved from one machine to another +for HA purposes. +The idea is to synchronize the SA so that the takeover machine can do +the processing of the SA as accurate as possible if it has access to it. + +We already have the ability to generate SA add/del/upd events. +These patches add ability to sync and have accurate lifetime byte (to +ensure proper decay of SAs) and replay counters to avoid replay attacks +with as minimal loss at failover time. +This way a backup stays as closely up-to-date as an active member. + +Because the above items change for every packet the SA receives, +it is possible for a lot of the events to be generated. +For this reason, we also add a nagle-like algorithm to restrict +the events. i.e we are going to set thresholds to say "let me +know if the replay sequence threshold is reached or 10 secs have passed" +These thresholds are set system-wide via sysctls or can be updated +per SA. + +The identified items that need to be synchronized are: +- the lifetime byte counter +note that: lifetime time limit is not important if you assume the failover +machine is known ahead of time since the decay of the time countdown +is not driven by packet arrival. +- the replay sequence for both inbound and outbound + +1) Message Structure +---------------------- + +nlmsghdr:aevent_id:optional-TLVs. + +The netlink message types are: + +XFRM_MSG_NEWAE and XFRM_MSG_GETAE. + +A XFRM_MSG_GETAE does not have TLVs. + +A XFRM_MSG_NEWAE will have at least two TLVs (as is +discussed further below). + +aevent_id structure looks like:: + + struct xfrm_aevent_id { + struct xfrm_usersa_id sa_id; + xfrm_address_t saddr; + __u32 flags; + __u32 reqid; + }; + +The unique SA is identified by the combination of xfrm_usersa_id, +reqid and saddr. + +flags are used to indicate different things. The possible +flags are:: + + XFRM_AE_RTHR=1, /* replay threshold*/ + XFRM_AE_RVAL=2, /* replay value */ + XFRM_AE_LVAL=4, /* lifetime value */ + XFRM_AE_ETHR=8, /* expiry timer threshold */ + XFRM_AE_CR=16, /* Event cause is replay update */ + XFRM_AE_CE=32, /* Event cause is timer expiry */ + XFRM_AE_CU=64, /* Event cause is policy update */ + +How these flags are used is dependent on the direction of the +message (kernel<->user) as well the cause (config, query or event). +This is described below in the different messages. + +The pid will be set appropriately in netlink to recognize direction +(0 to the kernel and pid = processid that created the event +when going from kernel to user space) + +A program needs to subscribe to multicast group XFRMNLGRP_AEVENTS +to get notified of these events. + +2) TLVS reflect the different parameters: +----------------------------------------- + +a) byte value (XFRMA_LTIME_VAL) + +This TLV carries the running/current counter for byte lifetime since +last event. + +b)replay value (XFRMA_REPLAY_VAL) + +This TLV carries the running/current counter for replay sequence since +last event. + +c)replay threshold (XFRMA_REPLAY_THRESH) + +This TLV carries the threshold being used by the kernel to trigger events +when the replay sequence is exceeded. + +d) expiry timer (XFRMA_ETIMER_THRESH) + +This is a timer value in milliseconds which is used as the nagle +value to rate limit the events. + +3) Default configurations for the parameters: +--------------------------------------------- + +By default these events should be turned off unless there is +at least one listener registered to listen to the multicast +group XFRMNLGRP_AEVENTS. + +Programs installing SAs will need to specify the two thresholds, however, +in order to not change existing applications such as racoon +we also provide default threshold values for these different parameters +in case they are not specified. + +the two sysctls/proc entries are: + +a) /proc/sys/net/core/sysctl_xfrm_aevent_etime +used to provide default values for the XFRMA_ETIMER_THRESH in incremental +units of time of 100ms. The default is 10 (1 second) + +b) /proc/sys/net/core/sysctl_xfrm_aevent_rseqth +used to provide default values for XFRMA_REPLAY_THRESH parameter +in incremental packet count. The default is two packets. + +4) Message types +---------------- + +a) XFRM_MSG_GETAE issued by user-->kernel. + XFRM_MSG_GETAE does not carry any TLVs. + +The response is a XFRM_MSG_NEWAE which is formatted based on what +XFRM_MSG_GETAE queried for. + +The response will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs. +* if XFRM_AE_RTHR flag is set, then XFRMA_REPLAY_THRESH is also retrieved +* if XFRM_AE_ETHR flag is set, then XFRMA_ETIMER_THRESH is also retrieved + +b) XFRM_MSG_NEWAE is issued by either user space to configure + or kernel to announce events or respond to a XFRM_MSG_GETAE. + +i) user --> kernel to configure a specific SA. + +any of the values or threshold parameters can be updated by passing the +appropriate TLV. + +A response is issued back to the sender in user space to indicate success +or failure. + +In the case of success, additionally an event with +XFRM_MSG_NEWAE is also issued to any listeners as described in iii). + +ii) kernel->user direction as a response to XFRM_MSG_GETAE + +The response will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs. + +The threshold TLVs will be included if explicitly requested in +the XFRM_MSG_GETAE message. + +iii) kernel->user to report as event if someone sets any values or + thresholds for an SA using XFRM_MSG_NEWAE (as described in #i above). + In such a case XFRM_AE_CU flag is set to inform the user that + the change happened as a result of an update. + The message will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs. + +iv) kernel->user to report event when replay threshold or a timeout + is exceeded. + +In such a case either XFRM_AE_CR (replay exceeded) or XFRM_AE_CE (timeout +happened) is set to inform the user what happened. +Note the two flags are mutually exclusive. +The message will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs. + +Exceptions to threshold settings +-------------------------------- + +If you have an SA that is getting hit by traffic in bursts such that +there is a period where the timer threshold expires with no packets +seen, then an odd behavior is seen as follows: +The first packet arrival after a timer expiry will trigger a timeout +event; i.e we don't wait for a timeout period or a packet threshold +to be reached. This is done for simplicity and efficiency reasons. + +-JHS diff --git a/Documentation/networking/xfrm_sync.txt b/Documentation/networking/xfrm_sync.txt deleted file mode 100644 index 8d88e0f2ec49..000000000000 --- a/Documentation/networking/xfrm_sync.txt +++ /dev/null @@ -1,169 +0,0 @@ - -The sync patches work is based on initial patches from -Krisztian and others and additional patches -from Jamal . - -The end goal for syncing is to be able to insert attributes + generate -events so that the SA can be safely moved from one machine to another -for HA purposes. -The idea is to synchronize the SA so that the takeover machine can do -the processing of the SA as accurate as possible if it has access to it. - -We already have the ability to generate SA add/del/upd events. -These patches add ability to sync and have accurate lifetime byte (to -ensure proper decay of SAs) and replay counters to avoid replay attacks -with as minimal loss at failover time. -This way a backup stays as closely up-to-date as an active member. - -Because the above items change for every packet the SA receives, -it is possible for a lot of the events to be generated. -For this reason, we also add a nagle-like algorithm to restrict -the events. i.e we are going to set thresholds to say "let me -know if the replay sequence threshold is reached or 10 secs have passed" -These thresholds are set system-wide via sysctls or can be updated -per SA. - -The identified items that need to be synchronized are: -- the lifetime byte counter -note that: lifetime time limit is not important if you assume the failover -machine is known ahead of time since the decay of the time countdown -is not driven by packet arrival. -- the replay sequence for both inbound and outbound - -1) Message Structure ----------------------- - -nlmsghdr:aevent_id:optional-TLVs. - -The netlink message types are: - -XFRM_MSG_NEWAE and XFRM_MSG_GETAE. - -A XFRM_MSG_GETAE does not have TLVs. -A XFRM_MSG_NEWAE will have at least two TLVs (as is -discussed further below). - -aevent_id structure looks like: - - struct xfrm_aevent_id { - struct xfrm_usersa_id sa_id; - xfrm_address_t saddr; - __u32 flags; - __u32 reqid; - }; - -The unique SA is identified by the combination of xfrm_usersa_id, -reqid and saddr. - -flags are used to indicate different things. The possible -flags are: - XFRM_AE_RTHR=1, /* replay threshold*/ - XFRM_AE_RVAL=2, /* replay value */ - XFRM_AE_LVAL=4, /* lifetime value */ - XFRM_AE_ETHR=8, /* expiry timer threshold */ - XFRM_AE_CR=16, /* Event cause is replay update */ - XFRM_AE_CE=32, /* Event cause is timer expiry */ - XFRM_AE_CU=64, /* Event cause is policy update */ - -How these flags are used is dependent on the direction of the -message (kernel<->user) as well the cause (config, query or event). -This is described below in the different messages. - -The pid will be set appropriately in netlink to recognize direction -(0 to the kernel and pid = processid that created the event -when going from kernel to user space) - -A program needs to subscribe to multicast group XFRMNLGRP_AEVENTS -to get notified of these events. - -2) TLVS reflect the different parameters: ------------------------------------------ - -a) byte value (XFRMA_LTIME_VAL) -This TLV carries the running/current counter for byte lifetime since -last event. - -b)replay value (XFRMA_REPLAY_VAL) -This TLV carries the running/current counter for replay sequence since -last event. - -c)replay threshold (XFRMA_REPLAY_THRESH) -This TLV carries the threshold being used by the kernel to trigger events -when the replay sequence is exceeded. - -d) expiry timer (XFRMA_ETIMER_THRESH) -This is a timer value in milliseconds which is used as the nagle -value to rate limit the events. - -3) Default configurations for the parameters: ----------------------------------------------- - -By default these events should be turned off unless there is -at least one listener registered to listen to the multicast -group XFRMNLGRP_AEVENTS. - -Programs installing SAs will need to specify the two thresholds, however, -in order to not change existing applications such as racoon -we also provide default threshold values for these different parameters -in case they are not specified. - -the two sysctls/proc entries are: -a) /proc/sys/net/core/sysctl_xfrm_aevent_etime -used to provide default values for the XFRMA_ETIMER_THRESH in incremental -units of time of 100ms. The default is 10 (1 second) - -b) /proc/sys/net/core/sysctl_xfrm_aevent_rseqth -used to provide default values for XFRMA_REPLAY_THRESH parameter -in incremental packet count. The default is two packets. - -4) Message types ----------------- - -a) XFRM_MSG_GETAE issued by user-->kernel. -XFRM_MSG_GETAE does not carry any TLVs. -The response is a XFRM_MSG_NEWAE which is formatted based on what -XFRM_MSG_GETAE queried for. -The response will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs. -*if XFRM_AE_RTHR flag is set, then XFRMA_REPLAY_THRESH is also retrieved -*if XFRM_AE_ETHR flag is set, then XFRMA_ETIMER_THRESH is also retrieved - -b) XFRM_MSG_NEWAE is issued by either user space to configure -or kernel to announce events or respond to a XFRM_MSG_GETAE. - -i) user --> kernel to configure a specific SA. -any of the values or threshold parameters can be updated by passing the -appropriate TLV. -A response is issued back to the sender in user space to indicate success -or failure. -In the case of success, additionally an event with -XFRM_MSG_NEWAE is also issued to any listeners as described in iii). - -ii) kernel->user direction as a response to XFRM_MSG_GETAE -The response will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs. -The threshold TLVs will be included if explicitly requested in -the XFRM_MSG_GETAE message. - -iii) kernel->user to report as event if someone sets any values or -thresholds for an SA using XFRM_MSG_NEWAE (as described in #i above). -In such a case XFRM_AE_CU flag is set to inform the user that -the change happened as a result of an update. -The message will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs. - -iv) kernel->user to report event when replay threshold or a timeout -is exceeded. -In such a case either XFRM_AE_CR (replay exceeded) or XFRM_AE_CE (timeout -happened) is set to inform the user what happened. -Note the two flags are mutually exclusive. -The message will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs. - -Exceptions to threshold settings --------------------------------- - -If you have an SA that is getting hit by traffic in bursts such that -there is a period where the timer threshold expires with no packets -seen, then an odd behavior is seen as follows: -The first packet arrival after a timer expiry will trigger a timeout -event; i.e we don't wait for a timeout period or a packet threshold -to be reached. This is done for simplicity and efficiency reasons. - --JHS -- cgit From a6c34b476ca27d0e5c14e58aefdbbdc4c509dd5f Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 1 May 2020 16:44:32 +0200 Subject: docs: networking: convert xfrm_sysctl.txt to ReST Not much to be done here: - add SPDX header; - add a document title; - add a chapter's markup; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: David S. Miller --- Documentation/networking/index.rst | 1 + Documentation/networking/xfrm_sysctl.rst | 11 +++++++++++ Documentation/networking/xfrm_sysctl.txt | 4 ---- 3 files changed, 12 insertions(+), 4 deletions(-) create mode 100644 Documentation/networking/xfrm_sysctl.rst delete mode 100644 Documentation/networking/xfrm_sysctl.txt diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index ec83bd95e4e9..1630801cec19 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -120,6 +120,7 @@ Contents: xfrm_device xfrm_proc xfrm_sync + xfrm_sysctl .. only:: subproject and html diff --git a/Documentation/networking/xfrm_sysctl.rst b/Documentation/networking/xfrm_sysctl.rst new file mode 100644 index 000000000000..47b9bbdd0179 --- /dev/null +++ b/Documentation/networking/xfrm_sysctl.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============ +XFRM Syscall +============ + +/proc/sys/net/core/xfrm_* Variables: +==================================== + +xfrm_acq_expires - INTEGER + default 30 - hard timeout in seconds for acquire requests diff --git a/Documentation/networking/xfrm_sysctl.txt b/Documentation/networking/xfrm_sysctl.txt deleted file mode 100644 index 5bbd16792fe1..000000000000 --- a/Documentation/networking/xfrm_sysctl.txt +++ /dev/null @@ -1,4 +0,0 @@ -/proc/sys/net/core/xfrm_* Variables: - -xfrm_acq_expires - INTEGER - default 30 - hard timeout in seconds for acquire requests -- cgit From 0046db09d539523ef1470bcad2f2614cc3ef7ddf Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 1 May 2020 16:44:33 +0200 Subject: docs: networking: convert z8530drv.txt to ReST - add SPDX header; - use copyright symbol; - adjust titles and chapters, adding proper markups; - mark tables as such; - mark code blocks and literals as such; - adjust identation, whitespaces and blank lines where needed; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: David S. Miller --- Documentation/networking/index.rst | 1 + Documentation/networking/z8530drv.rst | 686 ++++++++++++++++++++++++++++++++++ Documentation/networking/z8530drv.txt | 657 -------------------------------- MAINTAINERS | 2 +- drivers/net/hamradio/Kconfig | 4 +- drivers/net/hamradio/scc.c | 2 +- 6 files changed, 691 insertions(+), 661 deletions(-) create mode 100644 Documentation/networking/z8530drv.rst delete mode 100644 Documentation/networking/z8530drv.txt diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index 1630801cec19..f5733ca4fbcb 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -121,6 +121,7 @@ Contents: xfrm_proc xfrm_sync xfrm_sysctl + z8530drv .. only:: subproject and html diff --git a/Documentation/networking/z8530drv.rst b/Documentation/networking/z8530drv.rst new file mode 100644 index 000000000000..d2942760f167 --- /dev/null +++ b/Documentation/networking/z8530drv.rst @@ -0,0 +1,686 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: + +========================================================= +SCC.C - Linux driver for Z8530 based HDLC cards for AX.25 +========================================================= + + +This is a subset of the documentation. To use this driver you MUST have the +full package from: + +Internet: + + 1. ftp://ftp.ccac.rwth-aachen.de/pub/jr/z8530drv-utils_3.0-3.tar.gz + + 2. ftp://ftp.pspt.fi/pub/ham/linux/ax25/z8530drv-utils_3.0-3.tar.gz + +Please note that the information in this document may be hopelessly outdated. +A new version of the documentation, along with links to other important +Linux Kernel AX.25 documentation and programs, is available on +http://yaina.de/jreuter + +Copyright |copy| 1993,2000 by Joerg Reuter DL1BKE + +portions Copyright |copy| 1993 Guido ten Dolle PE1NNZ + +for the complete copyright notice see >> Copying.Z8530DRV << + +1. Initialization of the driver +=============================== + +To use the driver, 3 steps must be performed: + + 1. if compiled as module: loading the module + 2. Setup of hardware, MODEM and KISS parameters with sccinit + 3. Attach each channel to the Linux kernel AX.25 with "ifconfig" + +Unlike the versions below 2.4 this driver is a real network device +driver. If you want to run xNOS instead of our fine kernel AX.25 +use a 2.x version (available from above sites) or read the +AX.25-HOWTO on how to emulate a KISS TNC on network device drivers. + + +1.1 Loading the module +====================== + +(If you're going to compile the driver as a part of the kernel image, + skip this chapter and continue with 1.2) + +Before you can use a module, you'll have to load it with:: + + insmod scc.o + +please read 'man insmod' that comes with module-init-tools. + +You should include the insmod in one of the /etc/rc.d/rc.* files, +and don't forget to insert a call of sccinit after that. It +will read your /etc/z8530drv.conf. + +1.2. /etc/z8530drv.conf +======================= + +To setup all parameters you must run /sbin/sccinit from one +of your rc.*-files. This has to be done BEFORE you can +"ifconfig" an interface. Sccinit reads the file /etc/z8530drv.conf +and sets the hardware, MODEM and KISS parameters. A sample file is +delivered with this package. Change it to your needs. + +The file itself consists of two main sections. + +1.2.1 configuration of hardware parameters +========================================== + +The hardware setup section defines the following parameters for each +Z8530:: + + chip 1 + data_a 0x300 # data port A + ctrl_a 0x304 # control port A + data_b 0x301 # data port B + ctrl_b 0x305 # control port B + irq 5 # IRQ No. 5 + pclock 4915200 # clock + board BAYCOM # hardware type + escc no # enhanced SCC chip? (8580/85180/85280) + vector 0 # latch for interrupt vector + special no # address of special function register + option 0 # option to set via sfr + + +chip + - this is just a delimiter to make sccinit a bit simpler to + program. A parameter has no effect. + +data_a + - the address of the data port A of this Z8530 (needed) +ctrl_a + - the address of the control port A (needed) +data_b + - the address of the data port B (needed) +ctrl_b + - the address of the control port B (needed) + +irq + - the used IRQ for this chip. Different chips can use different + IRQs or the same. If they share an interrupt, it needs to be + specified within one chip-definition only. + +pclock - the clock at the PCLK pin of the Z8530 (option, 4915200 is + default), measured in Hertz + +board + - the "type" of the board: + + ======================= ======== + SCC type value + ======================= ======== + PA0HZP SCC card PA0HZP + EAGLE card EAGLE + PC100 card PC100 + PRIMUS-PC (DG9BL) card PRIMUS + BayCom (U)SCC card BAYCOM + ======================= ======== + +escc + - if you want support for ESCC chips (8580, 85180, 85280), set + this to "yes" (option, defaults to "no") + +vector + - address of the vector latch (aka "intack port") for PA0HZP + cards. There can be only one vector latch for all chips! + (option, defaults to 0) + +special + - address of the special function register on several cards. + (option, defaults to 0) + +option - The value you write into that register (option, default is 0) + +You can specify up to four chips (8 channels). If this is not enough, +just change:: + + #define MAXSCC 4 + +to a higher value. + +Example for the BAYCOM USCC: +---------------------------- + +:: + + chip 1 + data_a 0x300 # data port A + ctrl_a 0x304 # control port A + data_b 0x301 # data port B + ctrl_b 0x305 # control port B + irq 5 # IRQ No. 5 (#) + board BAYCOM # hardware type (*) + # + # SCC chip 2 + # + chip 2 + data_a 0x302 + ctrl_a 0x306 + data_b 0x303 + ctrl_b 0x307 + board BAYCOM + +An example for a PA0HZP card: +----------------------------- + +:: + + chip 1 + data_a 0x153 + data_b 0x151 + ctrl_a 0x152 + ctrl_b 0x150 + irq 9 + pclock 4915200 + board PA0HZP + vector 0x168 + escc no + # + # + # + chip 2 + data_a 0x157 + data_b 0x155 + ctrl_a 0x156 + ctrl_b 0x154 + irq 9 + pclock 4915200 + board PA0HZP + vector 0x168 + escc no + +A DRSI would should probably work with this: +-------------------------------------------- +(actually: two DRSI cards...) + +:: + + chip 1 + data_a 0x303 + data_b 0x301 + ctrl_a 0x302 + ctrl_b 0x300 + irq 7 + pclock 4915200 + board DRSI + escc no + # + # + # + chip 2 + data_a 0x313 + data_b 0x311 + ctrl_a 0x312 + ctrl_b 0x310 + irq 7 + pclock 4915200 + board DRSI + escc no + +Note that you cannot use the on-board baudrate generator off DRSI +cards. Use "mode dpll" for clock source (see below). + +This is based on information provided by Mike Bilow (and verified +by Paul Helay) + +The utility "gencfg" +-------------------- + +If you only know the parameters for the PE1CHL driver for DOS, +run gencfg. It will generate the correct port addresses (I hope). +Its parameters are exactly the same as the ones you use with +the "attach scc" command in net, except that the string "init" must +not appear. Example:: + + gencfg 2 0x150 4 2 0 1 0x168 9 4915200 + +will print a skeleton z8530drv.conf for the OptoSCC to stdout. + +:: + + gencfg 2 0x300 2 4 5 -4 0 7 4915200 0x10 + +does the same for the BAYCOM USCC card. In my opinion it is much easier +to edit scc_config.h... + + +1.2.2 channel configuration +=========================== + +The channel definition is divided into three sub sections for each +channel: + +An example for scc0:: + + # DEVICE + + device scc0 # the device for the following params + + # MODEM / BUFFERS + + speed 1200 # the default baudrate + clock dpll # clock source: + # dpll = normal half duplex operation + # external = MODEM provides own Rx/Tx clock + # divider = use full duplex divider if + # installed (1) + mode nrzi # HDLC encoding mode + # nrzi = 1k2 MODEM, G3RUH 9k6 MODEM + # nrz = DF9IC 9k6 MODEM + # + bufsize 384 # size of buffers. Note that this must include + # the AX.25 header, not only the data field! + # (optional, defaults to 384) + + # KISS (Layer 1) + + txdelay 36 # (see chapter 1.4) + persist 64 + slot 8 + tail 8 + fulldup 0 + wait 12 + min 3 + maxkey 7 + idle 3 + maxdef 120 + group 0 + txoff off + softdcd on + slip off + +The order WITHIN these sections is unimportant. The order OF these +sections IS important. The MODEM parameters are set with the first +recognized KISS parameter... + +Please note that you can initialize the board only once after boot +(or insmod). You can change all parameters but "mode" and "clock" +later with the Sccparam program or through KISS. Just to avoid +security holes... + +(1) this divider is usually mounted on the SCC-PBC (PA0HZP) or not + present at all (BayCom). It feeds back the output of the DPLL + (digital pll) as transmit clock. Using this mode without a divider + installed will normally result in keying the transceiver until + maxkey expires --- of course without sending anything (useful). + +2. Attachment of a channel by your AX.25 software +================================================= + +2.1 Kernel AX.25 +================ + +To set up an AX.25 device you can simply type:: + + ifconfig scc0 44.128.1.1 hw ax25 dl0tha-7 + +This will create a network interface with the IP number 44.128.20.107 +and the callsign "dl0tha". If you do not have any IP number (yet) you +can use any of the 44.128.0.0 network. Note that you do not need +axattach. The purpose of axattach (like slattach) is to create a KISS +network device linked to a TTY. Please read the documentation of the +ax25-utils and the AX.25-HOWTO to learn how to set the parameters of +the kernel AX.25. + +2.2 NOS, NET and TFKISS +======================= + +Since the TTY driver (aka KISS TNC emulation) is gone you need +to emulate the old behaviour. The cost of using these programs is +that you probably need to compile the kernel AX.25, regardless of whether +you actually use it or not. First setup your /etc/ax25/axports, +for example:: + + 9k6 dl0tha-9 9600 255 4 9600 baud port (scc3) + axlink dl0tha-15 38400 255 4 Link to NOS + +Now "ifconfig" the scc device:: + + ifconfig scc3 44.128.1.1 hw ax25 dl0tha-9 + +You can now axattach a pseudo-TTY:: + + axattach /dev/ptys0 axlink + +and start your NOS and attach /dev/ptys0 there. The problem is that +NOS is reachable only via digipeating through the kernel AX.25 +(disastrous on a DAMA controlled channel). To solve this problem, +configure "rxecho" to echo the incoming frames from "9k6" to "axlink" +and outgoing frames from "axlink" to "9k6" and start:: + + rxecho + +Or simply use "kissbridge" coming with z8530drv-utils:: + + ifconfig scc3 hw ax25 dl0tha-9 + kissbridge scc3 /dev/ptys0 + + +3. Adjustment and Display of parameters +======================================= + +3.1 Displaying SCC Parameters: +============================== + +Once a SCC channel has been attached, the parameter settings and +some statistic information can be shown using the param program:: + + dl1bke-u:~$ sccstat scc0 + + Parameters: + + speed : 1200 baud + txdelay : 36 + persist : 255 + slottime : 0 + txtail : 8 + fulldup : 1 + waittime : 12 + mintime : 3 sec + maxkeyup : 7 sec + idletime : 3 sec + maxdefer : 120 sec + group : 0x00 + txoff : off + softdcd : on + SLIP : off + + Status: + + HDLC Z8530 Interrupts Buffers + ----------------------------------------------------------------------- + Sent : 273 RxOver : 0 RxInts : 125074 Size : 384 + Received : 1095 TxUnder: 0 TxInts : 4684 NoSpace : 0 + RxErrors : 1591 ExInts : 11776 + TxErrors : 0 SpInts : 1503 + Tx State : idle + + +The status info shown is: + +============== ============================================================== +Sent number of frames transmitted +Received number of frames received +RxErrors number of receive errors (CRC, ABORT) +TxErrors number of discarded Tx frames (due to various reasons) +Tx State status of the Tx interrupt handler: idle/busy/active/tail (2) +RxOver number of receiver overruns +TxUnder number of transmitter underruns +RxInts number of receiver interrupts +TxInts number of transmitter interrupts +EpInts number of receiver special condition interrupts +SpInts number of external/status interrupts +Size maximum size of an AX.25 frame (*with* AX.25 headers!) +NoSpace number of times a buffer could not get allocated +============== ============================================================== + +An overrun is abnormal. If lots of these occur, the product of +baudrate and number of interfaces is too high for the processing +power of your computer. NoSpace errors are unlikely to be caused by the +driver or the kernel AX.25. + + +3.2 Setting Parameters +====================== + + +The setting of parameters of the emulated KISS TNC is done in the +same way in the SCC driver. You can change parameters by using +the kissparms program from the ax25-utils package or use the program +"sccparam":: + + sccparam + +You can change the following parameters: + +=========== ===== +param value +=========== ===== +speed 1200 +txdelay 36 +persist 255 +slottime 0 +txtail 8 +fulldup 1 +waittime 12 +mintime 3 +maxkeyup 7 +idletime 3 +maxdefer 120 +group 0x00 +txoff off +softdcd on +SLIP off +=========== ===== + + +The parameters have the following meaning: + +speed: + The baudrate on this channel in bits/sec + + Example: sccparam /dev/scc3 speed 9600 + +txdelay: + The delay (in units of 10 ms) after keying of the + transmitter, until the first byte is sent. This is usually + called "TXDELAY" in a TNC. When 0 is specified, the driver + will just wait until the CTS signal is asserted. This + assumes the presence of a timer or other circuitry in the + MODEM and/or transmitter, that asserts CTS when the + transmitter is ready for data. + A normal value of this parameter is 30-36. + + Example: sccparam /dev/scc0 txd 20 + +persist: + This is the probability that the transmitter will be keyed + when the channel is found to be free. It is a value from 0 + to 255, and the probability is (value+1)/256. The value + should be somewhere near 50-60, and should be lowered when + the channel is used more heavily. + + Example: sccparam /dev/scc2 persist 20 + +slottime: + This is the time between samples of the channel. It is + expressed in units of 10 ms. About 200-300 ms (value 20-30) + seems to be a good value. + + Example: sccparam /dev/scc0 slot 20 + +tail: + The time the transmitter will remain keyed after the last + byte of a packet has been transferred to the SCC. This is + necessary because the CRC and a flag still have to leave the + SCC before the transmitter is keyed down. The value depends + on the baudrate selected. A few character times should be + sufficient, e.g. 40ms at 1200 baud. (value 4) + The value of this parameter is in 10 ms units. + + Example: sccparam /dev/scc2 4 + +full: + The full-duplex mode switch. This can be one of the following + values: + + 0: The interface will operate in CSMA mode (the normal + half-duplex packet radio operation) + 1: Fullduplex mode, i.e. the transmitter will be keyed at + any time, without checking the received carrier. It + will be unkeyed when there are no packets to be sent. + 2: Like 1, but the transmitter will remain keyed, also + when there are no packets to be sent. Flags will be + sent in that case, until a timeout (parameter 10) + occurs. + + Example: sccparam /dev/scc0 fulldup off + +wait: + The initial waittime before any transmit attempt, after the + frame has been queue for transmit. This is the length of + the first slot in CSMA mode. In full duplex modes it is + set to 0 for maximum performance. + The value of this parameter is in 10 ms units. + + Example: sccparam /dev/scc1 wait 4 + +maxkey: + The maximal time the transmitter will be keyed to send + packets, in seconds. This can be useful on busy CSMA + channels, to avoid "getting a bad reputation" when you are + generating a lot of traffic. After the specified time has + elapsed, no new frame will be started. Instead, the trans- + mitter will be switched off for a specified time (parameter + min), and then the selected algorithm for keyup will be + started again. + The value 0 as well as "off" will disable this feature, + and allow infinite transmission time. + + Example: sccparam /dev/scc0 maxk 20 + +min: + This is the time the transmitter will be switched off when + the maximum transmission time is exceeded. + + Example: sccparam /dev/scc3 min 10 + +idle: + This parameter specifies the maximum idle time in full duplex + 2 mode, in seconds. When no frames have been sent for this + time, the transmitter will be keyed down. A value of 0 is + has same result as the fullduplex mode 1. This parameter + can be disabled. + + Example: sccparam /dev/scc2 idle off # transmit forever + +maxdefer + This is the maximum time (in seconds) to wait for a free channel + to send. When this timer expires the transmitter will be keyed + IMMEDIATELY. If you love to get trouble with other users you + should set this to a very low value ;-) + + Example: sccparam /dev/scc0 maxdefer 240 # 2 minutes + + +txoff: + When this parameter has the value 0, the transmission of packets + is enable. Otherwise it is disabled. + + Example: sccparam /dev/scc2 txoff on + +group: + It is possible to build special radio equipment to use more than + one frequency on the same band, e.g. using several receivers and + only one transmitter that can be switched between frequencies. + Also, you can connect several radios that are active on the same + band. In these cases, it is not possible, or not a good idea, to + transmit on more than one frequency. The SCC driver provides a + method to lock transmitters on different interfaces, using the + "param group " command. This will only work when + you are using CSMA mode (parameter full = 0). + + The number must be 0 if you want no group restrictions, and + can be computed as follows to create restricted groups: + is the sum of some OCTAL numbers: + + + === ======================================================= + 200 This transmitter will only be keyed when all other + transmitters in the group are off. + 100 This transmitter will only be keyed when the carrier + detect of all other interfaces in the group is off. + 0xx A byte that can be used to define different groups. + Interfaces are in the same group, when the logical AND + between their xx values is nonzero. + === ======================================================= + + Examples: + + When 2 interfaces use group 201, their transmitters will never be + keyed at the same time. + + When 2 interfaces use group 101, the transmitters will only key + when both channels are clear at the same time. When group 301, + the transmitters will not be keyed at the same time. + + Don't forget to convert the octal numbers into decimal before + you set the parameter. + + Example: (to be written) + +softdcd: + use a software dcd instead of the real one... Useful for a very + slow squelch. + + Example: sccparam /dev/scc0 soft on + + +4. Problems +=========== + +If you have tx-problems with your BayCom USCC card please check +the manufacturer of the 8530. SGS chips have a slightly +different timing. Try Zilog... A solution is to write to register 8 +instead to the data port, but this won't work with the ESCC chips. +*SIGH!* + +A very common problem is that the PTT locks until the maxkeyup timer +expires, although interrupts and clock source are correct. In most +cases compiling the driver with CONFIG_SCC_DELAY (set with +make config) solves the problems. For more hints read the (pseudo) FAQ +and the documentation coming with z8530drv-utils. + +I got reports that the driver has problems on some 386-based systems. +(i.e. Amstrad) Those systems have a bogus AT bus timing which will +lead to delayed answers on interrupts. You can recognize these +problems by looking at the output of Sccstat for the suspected +port. If it shows under- and overruns you own such a system. + +Delayed processing of received data: This depends on + +- the kernel version + +- kernel profiling compiled or not + +- a high interrupt load + +- a high load of the machine --- running X, Xmorph, XV and Povray, + while compiling the kernel... hmm ... even with 32 MB RAM ... ;-) + Or running a named for the whole .ampr.org domain on an 8 MB + box... + +- using information from rxecho or kissbridge. + +Kernel panics: please read /linux/README and find out if it +really occurred within the scc driver. + +If you cannot solve a problem, send me + +- a description of the problem, +- information on your hardware (computer system, scc board, modem) +- your kernel version +- the output of cat /proc/net/z8530 + +4. Thor RLC100 +============== + +Mysteriously this board seems not to work with the driver. Anyone +got it up-and-running? + + +Many thanks to Linus Torvalds and Alan Cox for including the driver +in the Linux standard distribution and their support. + +:: + + Joerg Reuter ampr-net: dl1bke@db0pra.ampr.org + AX-25 : DL1BKE @ DB0ABH.#BAY.DEU.EU + Internet: jreuter@yaina.de + WWW : http://yaina.de/jreuter diff --git a/Documentation/networking/z8530drv.txt b/Documentation/networking/z8530drv.txt deleted file mode 100644 index 2206abbc3e1b..000000000000 --- a/Documentation/networking/z8530drv.txt +++ /dev/null @@ -1,657 +0,0 @@ -This is a subset of the documentation. To use this driver you MUST have the -full package from: - -Internet: -========= - -1. ftp://ftp.ccac.rwth-aachen.de/pub/jr/z8530drv-utils_3.0-3.tar.gz - -2. ftp://ftp.pspt.fi/pub/ham/linux/ax25/z8530drv-utils_3.0-3.tar.gz - -Please note that the information in this document may be hopelessly outdated. -A new version of the documentation, along with links to other important -Linux Kernel AX.25 documentation and programs, is available on -http://yaina.de/jreuter - ------------------------------------------------------------------------------ - - - SCC.C - Linux driver for Z8530 based HDLC cards for AX.25 - - ******************************************************************** - - (c) 1993,2000 by Joerg Reuter DL1BKE - - portions (c) 1993 Guido ten Dolle PE1NNZ - - for the complete copyright notice see >> Copying.Z8530DRV << - - ******************************************************************** - - -1. Initialization of the driver -=============================== - -To use the driver, 3 steps must be performed: - - 1. if compiled as module: loading the module - 2. Setup of hardware, MODEM and KISS parameters with sccinit - 3. Attach each channel to the Linux kernel AX.25 with "ifconfig" - -Unlike the versions below 2.4 this driver is a real network device -driver. If you want to run xNOS instead of our fine kernel AX.25 -use a 2.x version (available from above sites) or read the -AX.25-HOWTO on how to emulate a KISS TNC on network device drivers. - - -1.1 Loading the module -====================== - -(If you're going to compile the driver as a part of the kernel image, - skip this chapter and continue with 1.2) - -Before you can use a module, you'll have to load it with - - insmod scc.o - -please read 'man insmod' that comes with module-init-tools. - -You should include the insmod in one of the /etc/rc.d/rc.* files, -and don't forget to insert a call of sccinit after that. It -will read your /etc/z8530drv.conf. - -1.2. /etc/z8530drv.conf -======================= - -To setup all parameters you must run /sbin/sccinit from one -of your rc.*-files. This has to be done BEFORE you can -"ifconfig" an interface. Sccinit reads the file /etc/z8530drv.conf -and sets the hardware, MODEM and KISS parameters. A sample file is -delivered with this package. Change it to your needs. - -The file itself consists of two main sections. - -1.2.1 configuration of hardware parameters -========================================== - -The hardware setup section defines the following parameters for each -Z8530: - -chip 1 -data_a 0x300 # data port A -ctrl_a 0x304 # control port A -data_b 0x301 # data port B -ctrl_b 0x305 # control port B -irq 5 # IRQ No. 5 -pclock 4915200 # clock -board BAYCOM # hardware type -escc no # enhanced SCC chip? (8580/85180/85280) -vector 0 # latch for interrupt vector -special no # address of special function register -option 0 # option to set via sfr - - -chip - this is just a delimiter to make sccinit a bit simpler to - program. A parameter has no effect. - -data_a - the address of the data port A of this Z8530 (needed) -ctrl_a - the address of the control port A (needed) -data_b - the address of the data port B (needed) -ctrl_b - the address of the control port B (needed) - -irq - the used IRQ for this chip. Different chips can use different - IRQs or the same. If they share an interrupt, it needs to be - specified within one chip-definition only. - -pclock - the clock at the PCLK pin of the Z8530 (option, 4915200 is - default), measured in Hertz - -board - the "type" of the board: - - SCC type value - --------------------------------- - PA0HZP SCC card PA0HZP - EAGLE card EAGLE - PC100 card PC100 - PRIMUS-PC (DG9BL) card PRIMUS - BayCom (U)SCC card BAYCOM - -escc - if you want support for ESCC chips (8580, 85180, 85280), set - this to "yes" (option, defaults to "no") - -vector - address of the vector latch (aka "intack port") for PA0HZP - cards. There can be only one vector latch for all chips! - (option, defaults to 0) - -special - address of the special function register on several cards. - (option, defaults to 0) - -option - The value you write into that register (option, default is 0) - -You can specify up to four chips (8 channels). If this is not enough, -just change - - #define MAXSCC 4 - -to a higher value. - -Example for the BAYCOM USCC: ----------------------------- - -chip 1 -data_a 0x300 # data port A -ctrl_a 0x304 # control port A -data_b 0x301 # data port B -ctrl_b 0x305 # control port B -irq 5 # IRQ No. 5 (#) -board BAYCOM # hardware type (*) -# -# SCC chip 2 -# -chip 2 -data_a 0x302 -ctrl_a 0x306 -data_b 0x303 -ctrl_b 0x307 -board BAYCOM - -An example for a PA0HZP card: ------------------------------ - -chip 1 -data_a 0x153 -data_b 0x151 -ctrl_a 0x152 -ctrl_b 0x150 -irq 9 -pclock 4915200 -board PA0HZP -vector 0x168 -escc no -# -# -# -chip 2 -data_a 0x157 -data_b 0x155 -ctrl_a 0x156 -ctrl_b 0x154 -irq 9 -pclock 4915200 -board PA0HZP -vector 0x168 -escc no - -A DRSI would should probably work with this: --------------------------------------------- -(actually: two DRSI cards...) - -chip 1 -data_a 0x303 -data_b 0x301 -ctrl_a 0x302 -ctrl_b 0x300 -irq 7 -pclock 4915200 -board DRSI -escc no -# -# -# -chip 2 -data_a 0x313 -data_b 0x311 -ctrl_a 0x312 -ctrl_b 0x310 -irq 7 -pclock 4915200 -board DRSI -escc no - -Note that you cannot use the on-board baudrate generator off DRSI -cards. Use "mode dpll" for clock source (see below). - -This is based on information provided by Mike Bilow (and verified -by Paul Helay) - -The utility "gencfg" --------------------- - -If you only know the parameters for the PE1CHL driver for DOS, -run gencfg. It will generate the correct port addresses (I hope). -Its parameters are exactly the same as the ones you use with -the "attach scc" command in net, except that the string "init" must -not appear. Example: - -gencfg 2 0x150 4 2 0 1 0x168 9 4915200 - -will print a skeleton z8530drv.conf for the OptoSCC to stdout. - -gencfg 2 0x300 2 4 5 -4 0 7 4915200 0x10 - -does the same for the BAYCOM USCC card. In my opinion it is much easier -to edit scc_config.h... - - -1.2.2 channel configuration -=========================== - -The channel definition is divided into three sub sections for each -channel: - -An example for scc0: - -# DEVICE - -device scc0 # the device for the following params - -# MODEM / BUFFERS - -speed 1200 # the default baudrate -clock dpll # clock source: - # dpll = normal half duplex operation - # external = MODEM provides own Rx/Tx clock - # divider = use full duplex divider if - # installed (1) -mode nrzi # HDLC encoding mode - # nrzi = 1k2 MODEM, G3RUH 9k6 MODEM - # nrz = DF9IC 9k6 MODEM - # -bufsize 384 # size of buffers. Note that this must include - # the AX.25 header, not only the data field! - # (optional, defaults to 384) - -# KISS (Layer 1) - -txdelay 36 # (see chapter 1.4) -persist 64 -slot 8 -tail 8 -fulldup 0 -wait 12 -min 3 -maxkey 7 -idle 3 -maxdef 120 -group 0 -txoff off -softdcd on -slip off - -The order WITHIN these sections is unimportant. The order OF these -sections IS important. The MODEM parameters are set with the first -recognized KISS parameter... - -Please note that you can initialize the board only once after boot -(or insmod). You can change all parameters but "mode" and "clock" -later with the Sccparam program or through KISS. Just to avoid -security holes... - -(1) this divider is usually mounted on the SCC-PBC (PA0HZP) or not - present at all (BayCom). It feeds back the output of the DPLL - (digital pll) as transmit clock. Using this mode without a divider - installed will normally result in keying the transceiver until - maxkey expires --- of course without sending anything (useful). - -2. Attachment of a channel by your AX.25 software -================================================= - -2.1 Kernel AX.25 -================ - -To set up an AX.25 device you can simply type: - - ifconfig scc0 44.128.1.1 hw ax25 dl0tha-7 - -This will create a network interface with the IP number 44.128.20.107 -and the callsign "dl0tha". If you do not have any IP number (yet) you -can use any of the 44.128.0.0 network. Note that you do not need -axattach. The purpose of axattach (like slattach) is to create a KISS -network device linked to a TTY. Please read the documentation of the -ax25-utils and the AX.25-HOWTO to learn how to set the parameters of -the kernel AX.25. - -2.2 NOS, NET and TFKISS -======================= - -Since the TTY driver (aka KISS TNC emulation) is gone you need -to emulate the old behaviour. The cost of using these programs is -that you probably need to compile the kernel AX.25, regardless of whether -you actually use it or not. First setup your /etc/ax25/axports, -for example: - - 9k6 dl0tha-9 9600 255 4 9600 baud port (scc3) - axlink dl0tha-15 38400 255 4 Link to NOS - -Now "ifconfig" the scc device: - - ifconfig scc3 44.128.1.1 hw ax25 dl0tha-9 - -You can now axattach a pseudo-TTY: - - axattach /dev/ptys0 axlink - -and start your NOS and attach /dev/ptys0 there. The problem is that -NOS is reachable only via digipeating through the kernel AX.25 -(disastrous on a DAMA controlled channel). To solve this problem, -configure "rxecho" to echo the incoming frames from "9k6" to "axlink" -and outgoing frames from "axlink" to "9k6" and start: - - rxecho - -Or simply use "kissbridge" coming with z8530drv-utils: - - ifconfig scc3 hw ax25 dl0tha-9 - kissbridge scc3 /dev/ptys0 - - -3. Adjustment and Display of parameters -======================================= - -3.1 Displaying SCC Parameters: -============================== - -Once a SCC channel has been attached, the parameter settings and -some statistic information can be shown using the param program: - -dl1bke-u:~$ sccstat scc0 - -Parameters: - -speed : 1200 baud -txdelay : 36 -persist : 255 -slottime : 0 -txtail : 8 -fulldup : 1 -waittime : 12 -mintime : 3 sec -maxkeyup : 7 sec -idletime : 3 sec -maxdefer : 120 sec -group : 0x00 -txoff : off -softdcd : on -SLIP : off - -Status: - -HDLC Z8530 Interrupts Buffers ------------------------------------------------------------------------ -Sent : 273 RxOver : 0 RxInts : 125074 Size : 384 -Received : 1095 TxUnder: 0 TxInts : 4684 NoSpace : 0 -RxErrors : 1591 ExInts : 11776 -TxErrors : 0 SpInts : 1503 -Tx State : idle - - -The status info shown is: - -Sent - number of frames transmitted -Received - number of frames received -RxErrors - number of receive errors (CRC, ABORT) -TxErrors - number of discarded Tx frames (due to various reasons) -Tx State - status of the Tx interrupt handler: idle/busy/active/tail (2) -RxOver - number of receiver overruns -TxUnder - number of transmitter underruns -RxInts - number of receiver interrupts -TxInts - number of transmitter interrupts -EpInts - number of receiver special condition interrupts -SpInts - number of external/status interrupts -Size - maximum size of an AX.25 frame (*with* AX.25 headers!) -NoSpace - number of times a buffer could not get allocated - -An overrun is abnormal. If lots of these occur, the product of -baudrate and number of interfaces is too high for the processing -power of your computer. NoSpace errors are unlikely to be caused by the -driver or the kernel AX.25. - - -3.2 Setting Parameters -====================== - - -The setting of parameters of the emulated KISS TNC is done in the -same way in the SCC driver. You can change parameters by using -the kissparms program from the ax25-utils package or use the program -"sccparam": - - sccparam - -You can change the following parameters: - -param : value ------------------------- -speed : 1200 -txdelay : 36 -persist : 255 -slottime : 0 -txtail : 8 -fulldup : 1 -waittime : 12 -mintime : 3 -maxkeyup : 7 -idletime : 3 -maxdefer : 120 -group : 0x00 -txoff : off -softdcd : on -SLIP : off - - -The parameters have the following meaning: - -speed: - The baudrate on this channel in bits/sec - - Example: sccparam /dev/scc3 speed 9600 - -txdelay: - The delay (in units of 10 ms) after keying of the - transmitter, until the first byte is sent. This is usually - called "TXDELAY" in a TNC. When 0 is specified, the driver - will just wait until the CTS signal is asserted. This - assumes the presence of a timer or other circuitry in the - MODEM and/or transmitter, that asserts CTS when the - transmitter is ready for data. - A normal value of this parameter is 30-36. - - Example: sccparam /dev/scc0 txd 20 - -persist: - This is the probability that the transmitter will be keyed - when the channel is found to be free. It is a value from 0 - to 255, and the probability is (value+1)/256. The value - should be somewhere near 50-60, and should be lowered when - the channel is used more heavily. - - Example: sccparam /dev/scc2 persist 20 - -slottime: - This is the time between samples of the channel. It is - expressed in units of 10 ms. About 200-300 ms (value 20-30) - seems to be a good value. - - Example: sccparam /dev/scc0 slot 20 - -tail: - The time the transmitter will remain keyed after the last - byte of a packet has been transferred to the SCC. This is - necessary because the CRC and a flag still have to leave the - SCC before the transmitter is keyed down. The value depends - on the baudrate selected. A few character times should be - sufficient, e.g. 40ms at 1200 baud. (value 4) - The value of this parameter is in 10 ms units. - - Example: sccparam /dev/scc2 4 - -full: - The full-duplex mode switch. This can be one of the following - values: - - 0: The interface will operate in CSMA mode (the normal - half-duplex packet radio operation) - 1: Fullduplex mode, i.e. the transmitter will be keyed at - any time, without checking the received carrier. It - will be unkeyed when there are no packets to be sent. - 2: Like 1, but the transmitter will remain keyed, also - when there are no packets to be sent. Flags will be - sent in that case, until a timeout (parameter 10) - occurs. - - Example: sccparam /dev/scc0 fulldup off - -wait: - The initial waittime before any transmit attempt, after the - frame has been queue for transmit. This is the length of - the first slot in CSMA mode. In full duplex modes it is - set to 0 for maximum performance. - The value of this parameter is in 10 ms units. - - Example: sccparam /dev/scc1 wait 4 - -maxkey: - The maximal time the transmitter will be keyed to send - packets, in seconds. This can be useful on busy CSMA - channels, to avoid "getting a bad reputation" when you are - generating a lot of traffic. After the specified time has - elapsed, no new frame will be started. Instead, the trans- - mitter will be switched off for a specified time (parameter - min), and then the selected algorithm for keyup will be - started again. - The value 0 as well as "off" will disable this feature, - and allow infinite transmission time. - - Example: sccparam /dev/scc0 maxk 20 - -min: - This is the time the transmitter will be switched off when - the maximum transmission time is exceeded. - - Example: sccparam /dev/scc3 min 10 - -idle - This parameter specifies the maximum idle time in full duplex - 2 mode, in seconds. When no frames have been sent for this - time, the transmitter will be keyed down. A value of 0 is - has same result as the fullduplex mode 1. This parameter - can be disabled. - - Example: sccparam /dev/scc2 idle off # transmit forever - -maxdefer - This is the maximum time (in seconds) to wait for a free channel - to send. When this timer expires the transmitter will be keyed - IMMEDIATELY. If you love to get trouble with other users you - should set this to a very low value ;-) - - Example: sccparam /dev/scc0 maxdefer 240 # 2 minutes - - -txoff: - When this parameter has the value 0, the transmission of packets - is enable. Otherwise it is disabled. - - Example: sccparam /dev/scc2 txoff on - -group: - It is possible to build special radio equipment to use more than - one frequency on the same band, e.g. using several receivers and - only one transmitter that can be switched between frequencies. - Also, you can connect several radios that are active on the same - band. In these cases, it is not possible, or not a good idea, to - transmit on more than one frequency. The SCC driver provides a - method to lock transmitters on different interfaces, using the - "param group " command. This will only work when - you are using CSMA mode (parameter full = 0). - The number must be 0 if you want no group restrictions, and - can be computed as follows to create restricted groups: - is the sum of some OCTAL numbers: - - 200 This transmitter will only be keyed when all other - transmitters in the group are off. - 100 This transmitter will only be keyed when the carrier - detect of all other interfaces in the group is off. - 0xx A byte that can be used to define different groups. - Interfaces are in the same group, when the logical AND - between their xx values is nonzero. - - Examples: - When 2 interfaces use group 201, their transmitters will never be - keyed at the same time. - When 2 interfaces use group 101, the transmitters will only key - when both channels are clear at the same time. When group 301, - the transmitters will not be keyed at the same time. - - Don't forget to convert the octal numbers into decimal before - you set the parameter. - - Example: (to be written) - -softdcd: - use a software dcd instead of the real one... Useful for a very - slow squelch. - - Example: sccparam /dev/scc0 soft on - - -4. Problems -=========== - -If you have tx-problems with your BayCom USCC card please check -the manufacturer of the 8530. SGS chips have a slightly -different timing. Try Zilog... A solution is to write to register 8 -instead to the data port, but this won't work with the ESCC chips. -*SIGH!* - -A very common problem is that the PTT locks until the maxkeyup timer -expires, although interrupts and clock source are correct. In most -cases compiling the driver with CONFIG_SCC_DELAY (set with -make config) solves the problems. For more hints read the (pseudo) FAQ -and the documentation coming with z8530drv-utils. - -I got reports that the driver has problems on some 386-based systems. -(i.e. Amstrad) Those systems have a bogus AT bus timing which will -lead to delayed answers on interrupts. You can recognize these -problems by looking at the output of Sccstat for the suspected -port. If it shows under- and overruns you own such a system. - -Delayed processing of received data: This depends on - -- the kernel version - -- kernel profiling compiled or not - -- a high interrupt load - -- a high load of the machine --- running X, Xmorph, XV and Povray, - while compiling the kernel... hmm ... even with 32 MB RAM ... ;-) - Or running a named for the whole .ampr.org domain on an 8 MB - box... - -- using information from rxecho or kissbridge. - -Kernel panics: please read /linux/README and find out if it -really occurred within the scc driver. - -If you cannot solve a problem, send me - -- a description of the problem, -- information on your hardware (computer system, scc board, modem) -- your kernel version -- the output of cat /proc/net/z8530 - -4. Thor RLC100 -============== - -Mysteriously this board seems not to work with the driver. Anyone -got it up-and-running? - - -Many thanks to Linus Torvalds and Alan Cox for including the driver -in the Linux standard distribution and their support. - -Joerg Reuter ampr-net: dl1bke@db0pra.ampr.org - AX-25 : DL1BKE @ DB0ABH.#BAY.DEU.EU - Internet: jreuter@yaina.de - WWW : http://yaina.de/jreuter diff --git a/MAINTAINERS b/MAINTAINERS index d59455c27c42..bee65ebdc67e 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -18644,7 +18644,7 @@ L: linux-hams@vger.kernel.org S: Maintained W: http://yaina.de/jreuter/ W: http://www.qsl.net/dl1bke/ -F: Documentation/networking/z8530drv.txt +F: Documentation/networking/z8530drv.rst F: drivers/net/hamradio/*scc.c F: drivers/net/hamradio/z8530.h diff --git a/drivers/net/hamradio/Kconfig b/drivers/net/hamradio/Kconfig index fe409819b56d..f4500f04147d 100644 --- a/drivers/net/hamradio/Kconfig +++ b/drivers/net/hamradio/Kconfig @@ -84,7 +84,7 @@ config SCC ---help--- These cards are used to connect your Linux box to an amateur radio in order to communicate with other computers. If you want to use - this, read and the + this, read and the AX25-HOWTO, available from . Also make sure to say Y to "Amateur Radio AX.25 Level 2" support. @@ -98,7 +98,7 @@ config SCC_DELAY help Say Y here if you experience problems with the SCC driver not working properly; please read - for details. + for details. If unsure, say N. diff --git a/drivers/net/hamradio/scc.c b/drivers/net/hamradio/scc.c index 6c03932d8a6b..33fdd55c6122 100644 --- a/drivers/net/hamradio/scc.c +++ b/drivers/net/hamradio/scc.c @@ -7,7 +7,7 @@ * ------------------ * * You can find a subset of the documentation in - * Documentation/networking/z8530drv.txt. + * Documentation/networking/z8530drv.rst. */ /* -- cgit From c79773e83e66fb2c22627eda3cd768f9e2bc10b5 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 1 May 2020 16:44:34 +0200 Subject: docs: networking: device drivers: convert 3com/3c509.txt to ReST - add SPDX header; - adjust titles and chapters, adding proper markups; - mark code blocks and literals as such; - add notes markups; - mark tables as such; - adjust identation, whitespaces and blank lines where needed; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: David S. Miller --- .../networking/device_drivers/3com/3c509.rst | 249 +++++++++++++++++++++ .../networking/device_drivers/3com/3c509.txt | 213 ------------------ Documentation/networking/device_drivers/index.rst | 1 + 3 files changed, 250 insertions(+), 213 deletions(-) create mode 100644 Documentation/networking/device_drivers/3com/3c509.rst delete mode 100644 Documentation/networking/device_drivers/3com/3c509.txt diff --git a/Documentation/networking/device_drivers/3com/3c509.rst b/Documentation/networking/device_drivers/3com/3c509.rst new file mode 100644 index 000000000000..47f706bacdd9 --- /dev/null +++ b/Documentation/networking/device_drivers/3com/3c509.rst @@ -0,0 +1,249 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================================================================= +Linux and the 3Com EtherLink III Series Ethercards (driver v1.18c and higher) +============================================================================= + +This file contains the instructions and caveats for v1.18c and higher versions +of the 3c509 driver. You should not use the driver without reading this file. + +release 1.0 + +28 February 2002 + +Current maintainer (corrections to): + David Ruggiero + +Introduction +============ + +The following are notes and information on using the 3Com EtherLink III series +ethercards in Linux. These cards are commonly known by the most widely-used +card's 3Com model number, 3c509. They are all 10mb/s ISA-bus cards and shouldn't +be (but sometimes are) confused with the similarly-numbered PCI-bus "3c905" +(aka "Vortex" or "Boomerang") series. Kernel support for the 3c509 family is +provided by the module 3c509.c, which has code to support all of the following +models: + + - 3c509 (original ISA card) + - 3c509B (later revision of the ISA card; supports full-duplex) + - 3c589 (PCMCIA) + - 3c589B (later revision of the 3c589; supports full-duplex) + - 3c579 (EISA) + +Large portions of this documentation were heavily borrowed from the guide +written the original author of the 3c509 driver, Donald Becker. The master +copy of that document, which contains notes on older versions of the driver, +currently resides on Scyld web server: http://www.scyld.com/. + + +Special Driver Features +======================= + +Overriding card settings + +The driver allows boot- or load-time overriding of the card's detected IOADDR, +IRQ, and transceiver settings, although this capability shouldn't generally be +needed except to enable full-duplex mode (see below). An example of the syntax +for LILO parameters for doing this:: + + ether=10,0x310,3,0x3c509,eth0 + +This configures the first found 3c509 card for IRQ 10, base I/O 0x310, and +transceiver type 3 (10base2). The flag "0x3c509" must be set to avoid conflicts +with other card types when overriding the I/O address. When the driver is +loaded as a module, only the IRQ may be overridden. For example, +setting two cards to IRQ10 and IRQ11 is done by using the irq module +option:: + + options 3c509 irq=10,11 + + +Full-duplex mode +================ + +The v1.18c driver added support for the 3c509B's full-duplex capabilities. +In order to enable and successfully use full-duplex mode, three conditions +must be met: + +(a) You must have a Etherlink III card model whose hardware supports full- +duplex operations. Currently, the only members of the 3c509 family that are +positively known to support full-duplex are the 3c509B (ISA bus) and 3c589B +(PCMCIA) cards. Cards without the "B" model designation do *not* support +full-duplex mode; these include the original 3c509 (no "B"), the original +3c589, the 3c529 (MCA bus), and the 3c579 (EISA bus). + +(b) You must be using your card's 10baseT transceiver (i.e., the RJ-45 +connector), not its AUI (thick-net) or 10base2 (thin-net/coax) interfaces. +AUI and 10base2 network cabling is physically incapable of full-duplex +operation. + +(c) Most importantly, your 3c509B must be connected to a link partner that is +itself full-duplex capable. This is almost certainly one of two things: a full- +duplex-capable Ethernet switch (*not* a hub), or a full-duplex-capable NIC on +another system that's connected directly to the 3c509B via a crossover cable. + +Full-duplex mode can be enabled using 'ethtool'. + +.. warning:: + + Extremely important caution concerning full-duplex mode + + Understand that the 3c509B's hardware's full-duplex support is much more + limited than that provide by more modern network interface cards. Although + at the physical layer of the network it fully supports full-duplex operation, + the card was designed before the current Ethernet auto-negotiation (N-way) + spec was written. This means that the 3c509B family ***cannot and will not + auto-negotiate a full-duplex connection with its link partner under any + circumstances, no matter how it is initialized***. If the full-duplex mode + of the 3c509B is enabled, its link partner will very likely need to be + independently _forced_ into full-duplex mode as well; otherwise various nasty + failures will occur - at the very least, you'll see massive numbers of packet + collisions. This is one of very rare circumstances where disabling auto- + negotiation and forcing the duplex mode of a network interface card or switch + would ever be necessary or desirable. + + +Available Transceiver Types +=========================== + +For versions of the driver v1.18c and above, the available transceiver types are: + +== ========================================================================= +0 transceiver type from EEPROM config (normally 10baseT); force half-duplex +1 AUI (thick-net / DB15 connector) +2 (undefined) +3 10base2 (thin-net == coax / BNC connector) +4 10baseT (RJ-45 connector); force half-duplex mode +8 transceiver type and duplex mode taken from card's EEPROM config settings +12 10baseT (RJ-45 connector); force full-duplex mode +== ========================================================================= + +Prior to driver version 1.18c, only transceiver codes 0-4 were supported. Note +that the new transceiver codes 8 and 12 are the *only* ones that will enable +full-duplex mode, no matter what the card's detected EEPROM settings might be. +This insured that merely upgrading the driver from an earlier version would +never automatically enable full-duplex mode in an existing installation; +it must always be explicitly enabled via one of these code in order to be +activated. + +The transceiver type can be changed using 'ethtool'. + + +Interpretation of error messages and common problems +---------------------------------------------------- + +Error Messages +^^^^^^^^^^^^^^ + +eth0: Infinite loop in interrupt, status 2011. +These are "mostly harmless" message indicating that the driver had too much +work during that interrupt cycle. With a status of 0x2011 you are receiving +packets faster than they can be removed from the card. This should be rare +or impossible in normal operation. Possible causes of this error report are: + + - a "green" mode enabled that slows the processor down when there is no + keyboard activity. + + - some other device or device driver hogging the bus or disabling interrupts. + Check /proc/interrupts for excessive interrupt counts. The timer tick + interrupt should always be incrementing faster than the others. + +No received packets +^^^^^^^^^^^^^^^^^^^ + +If a 3c509, 3c562 or 3c589 can successfully transmit packets, but never +receives packets (as reported by /proc/net/dev or 'ifconfig') you likely +have an interrupt line problem. Check /proc/interrupts to verify that the +card is actually generating interrupts. If the interrupt count is not +increasing you likely have a physical conflict with two devices trying to +use the same ISA IRQ line. The common conflict is with a sound card on IRQ10 +or IRQ5, and the easiest solution is to move the 3c509 to a different +interrupt line. If the device is receiving packets but 'ping' doesn't work, +you have a routing problem. + +Tx Carrier Errors Reported in /proc/net/dev +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + +If an EtherLink III appears to transmit packets, but the "Tx carrier errors" +field in /proc/net/dev increments as quickly as the Tx packet count, you +likely have an unterminated network or the incorrect media transceiver selected. + +3c509B card is not detected on machines with an ISA PnP BIOS. +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +While the updated driver works with most PnP BIOS programs, it does not work +with all. This can be fixed by disabling PnP support using the 3Com-supplied +setup program. + +3c509 card is not detected on overclocked machines +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Increase the delay time in id_read_eeprom() from the current value, 500, +to an absurdly high value, such as 5000. + + +Decoding Status and Error Messages +---------------------------------- + + +The bits in the main status register are: + +===== ====================================== +value description +===== ====================================== +0x01 Interrupt latch +0x02 Tx overrun, or Rx underrun +0x04 Tx complete +0x08 Tx FIFO room available +0x10 A complete Rx packet has arrived +0x20 A Rx packet has started to arrive +0x40 The driver has requested an interrupt +0x80 Statistics counter nearly full +===== ====================================== + +The bits in the transmit (Tx) status word are: + +===== ============================================ +value description +===== ============================================ +0x02 Out-of-window collision. +0x04 Status stack overflow (normally impossible). +0x08 16 collisions. +0x10 Tx underrun (not enough PCI bus bandwidth). +0x20 Tx jabber. +0x40 Tx interrupt requested. +0x80 Status is valid (this should always be set). +===== ============================================ + + +When a transmit error occurs the driver produces a status message such as:: + + eth0: Transmit error, Tx status register 82 + +The two values typically seen here are: + +0x82 +^^^^ + +Out of window collision. This typically occurs when some other Ethernet +host is incorrectly set to full duplex on a half duplex network. + +0x88 +^^^^ + +16 collisions. This typically occurs when the network is exceptionally busy +or when another host doesn't correctly back off after a collision. If this +error is mixed with 0x82 errors it is the result of a host incorrectly set +to full duplex (see above). + +Both of these errors are the result of network problems that should be +corrected. They do not represent driver malfunction. + + +Revision history (this file) +============================ + +28Feb02 v1.0 DR New; major portions based on Becker original 3c509 docs + diff --git a/Documentation/networking/device_drivers/3com/3c509.txt b/Documentation/networking/device_drivers/3com/3c509.txt deleted file mode 100644 index fbf722e15ac3..000000000000 --- a/Documentation/networking/device_drivers/3com/3c509.txt +++ /dev/null @@ -1,213 +0,0 @@ -Linux and the 3Com EtherLink III Series Ethercards (driver v1.18c and higher) ----------------------------------------------------------------------------- - -This file contains the instructions and caveats for v1.18c and higher versions -of the 3c509 driver. You should not use the driver without reading this file. - -release 1.0 -28 February 2002 -Current maintainer (corrections to): - David Ruggiero - ----------------------------------------------------------------------------- - -(0) Introduction - -The following are notes and information on using the 3Com EtherLink III series -ethercards in Linux. These cards are commonly known by the most widely-used -card's 3Com model number, 3c509. They are all 10mb/s ISA-bus cards and shouldn't -be (but sometimes are) confused with the similarly-numbered PCI-bus "3c905" -(aka "Vortex" or "Boomerang") series. Kernel support for the 3c509 family is -provided by the module 3c509.c, which has code to support all of the following -models: - - 3c509 (original ISA card) - 3c509B (later revision of the ISA card; supports full-duplex) - 3c589 (PCMCIA) - 3c589B (later revision of the 3c589; supports full-duplex) - 3c579 (EISA) - -Large portions of this documentation were heavily borrowed from the guide -written the original author of the 3c509 driver, Donald Becker. The master -copy of that document, which contains notes on older versions of the driver, -currently resides on Scyld web server: http://www.scyld.com/. - - -(1) Special Driver Features - -Overriding card settings - -The driver allows boot- or load-time overriding of the card's detected IOADDR, -IRQ, and transceiver settings, although this capability shouldn't generally be -needed except to enable full-duplex mode (see below). An example of the syntax -for LILO parameters for doing this: - - ether=10,0x310,3,0x3c509,eth0 - -This configures the first found 3c509 card for IRQ 10, base I/O 0x310, and -transceiver type 3 (10base2). The flag "0x3c509" must be set to avoid conflicts -with other card types when overriding the I/O address. When the driver is -loaded as a module, only the IRQ may be overridden. For example, -setting two cards to IRQ10 and IRQ11 is done by using the irq module -option: - - options 3c509 irq=10,11 - - -(2) Full-duplex mode - -The v1.18c driver added support for the 3c509B's full-duplex capabilities. -In order to enable and successfully use full-duplex mode, three conditions -must be met: - -(a) You must have a Etherlink III card model whose hardware supports full- -duplex operations. Currently, the only members of the 3c509 family that are -positively known to support full-duplex are the 3c509B (ISA bus) and 3c589B -(PCMCIA) cards. Cards without the "B" model designation do *not* support -full-duplex mode; these include the original 3c509 (no "B"), the original -3c589, the 3c529 (MCA bus), and the 3c579 (EISA bus). - -(b) You must be using your card's 10baseT transceiver (i.e., the RJ-45 -connector), not its AUI (thick-net) or 10base2 (thin-net/coax) interfaces. -AUI and 10base2 network cabling is physically incapable of full-duplex -operation. - -(c) Most importantly, your 3c509B must be connected to a link partner that is -itself full-duplex capable. This is almost certainly one of two things: a full- -duplex-capable Ethernet switch (*not* a hub), or a full-duplex-capable NIC on -another system that's connected directly to the 3c509B via a crossover cable. - -Full-duplex mode can be enabled using 'ethtool'. - -/////Extremely important caution concerning full-duplex mode///// -Understand that the 3c509B's hardware's full-duplex support is much more -limited than that provide by more modern network interface cards. Although -at the physical layer of the network it fully supports full-duplex operation, -the card was designed before the current Ethernet auto-negotiation (N-way) -spec was written. This means that the 3c509B family ***cannot and will not -auto-negotiate a full-duplex connection with its link partner under any -circumstances, no matter how it is initialized***. If the full-duplex mode -of the 3c509B is enabled, its link partner will very likely need to be -independently _forced_ into full-duplex mode as well; otherwise various nasty -failures will occur - at the very least, you'll see massive numbers of packet -collisions. This is one of very rare circumstances where disabling auto- -negotiation and forcing the duplex mode of a network interface card or switch -would ever be necessary or desirable. - - -(3) Available Transceiver Types - -For versions of the driver v1.18c and above, the available transceiver types are: - -0 transceiver type from EEPROM config (normally 10baseT); force half-duplex -1 AUI (thick-net / DB15 connector) -2 (undefined) -3 10base2 (thin-net == coax / BNC connector) -4 10baseT (RJ-45 connector); force half-duplex mode -8 transceiver type and duplex mode taken from card's EEPROM config settings -12 10baseT (RJ-45 connector); force full-duplex mode - -Prior to driver version 1.18c, only transceiver codes 0-4 were supported. Note -that the new transceiver codes 8 and 12 are the *only* ones that will enable -full-duplex mode, no matter what the card's detected EEPROM settings might be. -This insured that merely upgrading the driver from an earlier version would -never automatically enable full-duplex mode in an existing installation; -it must always be explicitly enabled via one of these code in order to be -activated. - -The transceiver type can be changed using 'ethtool'. - - -(4a) Interpretation of error messages and common problems - -Error Messages - -eth0: Infinite loop in interrupt, status 2011. -These are "mostly harmless" message indicating that the driver had too much -work during that interrupt cycle. With a status of 0x2011 you are receiving -packets faster than they can be removed from the card. This should be rare -or impossible in normal operation. Possible causes of this error report are: - - - a "green" mode enabled that slows the processor down when there is no - keyboard activity. - - - some other device or device driver hogging the bus or disabling interrupts. - Check /proc/interrupts for excessive interrupt counts. The timer tick - interrupt should always be incrementing faster than the others. - -No received packets -If a 3c509, 3c562 or 3c589 can successfully transmit packets, but never -receives packets (as reported by /proc/net/dev or 'ifconfig') you likely -have an interrupt line problem. Check /proc/interrupts to verify that the -card is actually generating interrupts. If the interrupt count is not -increasing you likely have a physical conflict with two devices trying to -use the same ISA IRQ line. The common conflict is with a sound card on IRQ10 -or IRQ5, and the easiest solution is to move the 3c509 to a different -interrupt line. If the device is receiving packets but 'ping' doesn't work, -you have a routing problem. - -Tx Carrier Errors Reported in /proc/net/dev -If an EtherLink III appears to transmit packets, but the "Tx carrier errors" -field in /proc/net/dev increments as quickly as the Tx packet count, you -likely have an unterminated network or the incorrect media transceiver selected. - -3c509B card is not detected on machines with an ISA PnP BIOS. -While the updated driver works with most PnP BIOS programs, it does not work -with all. This can be fixed by disabling PnP support using the 3Com-supplied -setup program. - -3c509 card is not detected on overclocked machines -Increase the delay time in id_read_eeprom() from the current value, 500, -to an absurdly high value, such as 5000. - - -(4b) Decoding Status and Error Messages - -The bits in the main status register are: - -value description -0x01 Interrupt latch -0x02 Tx overrun, or Rx underrun -0x04 Tx complete -0x08 Tx FIFO room available -0x10 A complete Rx packet has arrived -0x20 A Rx packet has started to arrive -0x40 The driver has requested an interrupt -0x80 Statistics counter nearly full - -The bits in the transmit (Tx) status word are: - -value description -0x02 Out-of-window collision. -0x04 Status stack overflow (normally impossible). -0x08 16 collisions. -0x10 Tx underrun (not enough PCI bus bandwidth). -0x20 Tx jabber. -0x40 Tx interrupt requested. -0x80 Status is valid (this should always be set). - - -When a transmit error occurs the driver produces a status message such as - - eth0: Transmit error, Tx status register 82 - -The two values typically seen here are: - -0x82 -Out of window collision. This typically occurs when some other Ethernet -host is incorrectly set to full duplex on a half duplex network. - -0x88 -16 collisions. This typically occurs when the network is exceptionally busy -or when another host doesn't correctly back off after a collision. If this -error is mixed with 0x82 errors it is the result of a host incorrectly set -to full duplex (see above). - -Both of these errors are the result of network problems that should be -corrected. They do not represent driver malfunction. - - -(5) Revision history (this file) - -28Feb02 v1.0 DR New; major portions based on Becker original 3c509 docs - diff --git a/Documentation/networking/device_drivers/index.rst b/Documentation/networking/device_drivers/index.rst index a191faaf97de..402a9188f446 100644 --- a/Documentation/networking/device_drivers/index.rst +++ b/Documentation/networking/device_drivers/index.rst @@ -27,6 +27,7 @@ Contents: netronome/nfp pensando/ionic stmicro/stmmac + 3com/3c509 .. only:: subproject and html -- cgit From 9ea2af8d16f5612168ed52cb0ec6752bac0877a9 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 1 May 2020 16:44:35 +0200 Subject: docs: networking: device drivers: convert 3com/vortex.txt to ReST - add SPDX header; - add a document title; - mark code blocks and literals as such; - mark tables as such; - adjust identation, whitespaces and blank lines where needed; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: David S. Miller --- .../networking/device_drivers/3com/vortex.rst | 461 +++++++++++++++++++++ .../networking/device_drivers/3com/vortex.txt | 448 -------------------- Documentation/networking/device_drivers/index.rst | 1 + MAINTAINERS | 2 +- drivers/net/ethernet/3com/3c59x.c | 4 +- drivers/net/ethernet/3com/Kconfig | 2 +- 6 files changed, 466 insertions(+), 452 deletions(-) create mode 100644 Documentation/networking/device_drivers/3com/vortex.rst delete mode 100644 Documentation/networking/device_drivers/3com/vortex.txt diff --git a/Documentation/networking/device_drivers/3com/vortex.rst b/Documentation/networking/device_drivers/3com/vortex.rst new file mode 100644 index 000000000000..800add5be338 --- /dev/null +++ b/Documentation/networking/device_drivers/3com/vortex.rst @@ -0,0 +1,461 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================= +3Com Vortex device driver +========================= + +Documentation/networking/device_drivers/3com/vortex.rst + +Andrew Morton + +30 April 2000 + + +This document describes the usage and errata of the 3Com "Vortex" device +driver for Linux, 3c59x.c. + +The driver was written by Donald Becker + +Don is no longer the prime maintainer of this version of the driver. +Please report problems to one or more of: + +- Andrew Morton +- Netdev mailing list +- Linux kernel mailing list + +Please note the 'Reporting and Diagnosing Problems' section at the end +of this file. + + +Since kernel 2.3.99-pre6, this driver incorporates the support for the +3c575-series Cardbus cards which used to be handled by 3c575_cb.c. + +This driver supports the following hardware: + + - 3c590 Vortex 10Mbps + - 3c592 EISA 10Mbps Demon/Vortex + - 3c597 EISA Fast Demon/Vortex + - 3c595 Vortex 100baseTx + - 3c595 Vortex 100baseT4 + - 3c595 Vortex 100base-MII + - 3c900 Boomerang 10baseT + - 3c900 Boomerang 10Mbps Combo + - 3c900 Cyclone 10Mbps TPO + - 3c900 Cyclone 10Mbps Combo + - 3c900 Cyclone 10Mbps TPC + - 3c900B-FL Cyclone 10base-FL + - 3c905 Boomerang 100baseTx + - 3c905 Boomerang 100baseT4 + - 3c905B Cyclone 100baseTx + - 3c905B Cyclone 10/100/BNC + - 3c905B-FX Cyclone 100baseFx + - 3c905C Tornado + - 3c920B-EMB-WNM (ATI Radeon 9100 IGP) + - 3c980 Cyclone + - 3c980C Python-T + - 3cSOHO100-TX Hurricane + - 3c555 Laptop Hurricane + - 3c556 Laptop Tornado + - 3c556B Laptop Hurricane + - 3c575 [Megahertz] 10/100 LAN CardBus + - 3c575 Boomerang CardBus + - 3CCFE575BT Cyclone CardBus + - 3CCFE575CT Tornado CardBus + - 3CCFE656 Cyclone CardBus + - 3CCFEM656B Cyclone+Winmodem CardBus + - 3CXFEM656C Tornado+Winmodem CardBus + - 3c450 HomePNA Tornado + - 3c920 Tornado + - 3c982 Hydra Dual Port A + - 3c982 Hydra Dual Port B + - 3c905B-T4 + - 3c920B-EMB-WNM Tornado + +Module parameters +================= + +There are several parameters which may be provided to the driver when +its module is loaded. These are usually placed in ``/etc/modprobe.d/*.conf`` +configuration files. Example:: + + options 3c59x debug=3 rx_copybreak=300 + +If you are using the PCMCIA tools (cardmgr) then the options may be +placed in /etc/pcmcia/config.opts:: + + module "3c59x" opts "debug=3 rx_copybreak=300" + + +The supported parameters are: + +debug=N + + Where N is a number from 0 to 7. Anything above 3 produces a lot + of output in your system logs. debug=1 is default. + +options=N1,N2,N3,... + + Each number in the list provides an option to the corresponding + network card. So if you have two 3c905's and you wish to provide + them with option 0x204 you would use:: + + options=0x204,0x204 + + The individual options are composed of a number of bitfields which + have the following meanings: + + Possible media type settings + + == ================================= + 0 10baseT + 1 10Mbs AUI + 2 undefined + 3 10base2 (BNC) + 4 100base-TX + 5 100base-FX + 6 MII (Media Independent Interface) + 7 Use default setting from EEPROM + 8 Autonegotiate + 9 External MII + 10 Use default setting from EEPROM + == ================================= + + When generating a value for the 'options' setting, the above media + selection values may be OR'ed (or added to) the following: + + ====== ============================================= + 0x8000 Set driver debugging level to 7 + 0x4000 Set driver debugging level to 2 + 0x0400 Enable Wake-on-LAN + 0x0200 Force full duplex mode. + 0x0010 Bus-master enable bit (Old Vortex cards only) + ====== ============================================= + + For example:: + + insmod 3c59x options=0x204 + + will force full-duplex 100base-TX, rather than allowing the usual + autonegotiation. + +global_options=N + + Sets the ``options`` parameter for all 3c59x NICs in the machine. + Entries in the ``options`` array above will override any setting of + this. + +full_duplex=N1,N2,N3... + + Similar to bit 9 of 'options'. Forces the corresponding card into + full-duplex mode. Please use this in preference to the ``options`` + parameter. + + In fact, please don't use this at all! You're better off getting + autonegotiation working properly. + +global_full_duplex=N1 + + Sets full duplex mode for all 3c59x NICs in the machine. Entries + in the ``full_duplex`` array above will override any setting of this. + +flow_ctrl=N1,N2,N3... + + Use 802.3x MAC-layer flow control. The 3com cards only support the + PAUSE command, which means that they will stop sending packets for a + short period if they receive a PAUSE frame from the link partner. + + The driver only allows flow control on a link which is operating in + full duplex mode. + + This feature does not appear to work on the 3c905 - only 3c905B and + 3c905C have been tested. + + The 3com cards appear to only respond to PAUSE frames which are + sent to the reserved destination address of 01:80:c2:00:00:01. They + do not honour PAUSE frames which are sent to the station MAC address. + +rx_copybreak=M + + The driver preallocates 32 full-sized (1536 byte) network buffers + for receiving. When a packet arrives, the driver has to decide + whether to leave the packet in its full-sized buffer, or to allocate + a smaller buffer and copy the packet across into it. + + This is a speed/space tradeoff. + + The value of rx_copybreak is used to decide when to make the copy. + If the packet size is less than rx_copybreak, the packet is copied. + The default value for rx_copybreak is 200 bytes. + +max_interrupt_work=N + + The driver's interrupt service routine can handle many receive and + transmit packets in a single invocation. It does this in a loop. + The value of max_interrupt_work governs how many times the interrupt + service routine will loop. The default value is 32 loops. If this + is exceeded the interrupt service routine gives up and generates a + warning message "eth0: Too much work in interrupt". + +hw_checksums=N1,N2,N3,... + + Recent 3com NICs are able to generate IPv4, TCP and UDP checksums + in hardware. Linux has used the Rx checksumming for a long time. + The "zero copy" patch which is planned for the 2.4 kernel series + allows you to make use of the NIC's DMA scatter/gather and transmit + checksumming as well. + + The driver is set up so that, when the zerocopy patch is applied, + all Tornado and Cyclone devices will use S/G and Tx checksums. + + This module parameter has been provided so you can override this + decision. If you think that Tx checksums are causing a problem, you + may disable the feature with ``hw_checksums=0``. + + If you think your NIC should be performing Tx checksumming and the + driver isn't enabling it, you can force the use of hardware Tx + checksumming with ``hw_checksums=1``. + + The driver drops a message in the logfiles to indicate whether or + not it is using hardware scatter/gather and hardware Tx checksums. + + Scatter/gather and hardware checksums provide considerable + performance improvement for the sendfile() system call, but a small + decrease in throughput for send(). There is no effect upon receive + efficiency. + +compaq_ioaddr=N, +compaq_irq=N, +compaq_device_id=N + + "Variables to work-around the Compaq PCI BIOS32 problem".... + +watchdog=N + + Sets the time duration (in milliseconds) after which the kernel + decides that the transmitter has become stuck and needs to be reset. + This is mainly for debugging purposes, although it may be advantageous + to increase this value on LANs which have very high collision rates. + The default value is 5000 (5.0 seconds). + +enable_wol=N1,N2,N3,... + + Enable Wake-on-LAN support for the relevant interface. Donald + Becker's ``ether-wake`` application may be used to wake suspended + machines. + + Also enables the NIC's power management support. + +global_enable_wol=N + + Sets enable_wol mode for all 3c59x NICs in the machine. Entries in + the ``enable_wol`` array above will override any setting of this. + +Media selection +--------------- + +A number of the older NICs such as the 3c590 and 3c900 series have +10base2 and AUI interfaces. + +Prior to January, 2001 this driver would autoeselect the 10base2 or AUI +port if it didn't detect activity on the 10baseT port. It would then +get stuck on the 10base2 port and a driver reload was necessary to +switch back to 10baseT. This behaviour could not be prevented with a +module option override. + +Later (current) versions of the driver _do_ support locking of the +media type. So if you load the driver module with + + modprobe 3c59x options=0 + +it will permanently select the 10baseT port. Automatic selection of +other media types does not occur. + + +Transmit error, Tx status register 82 +------------------------------------- + +This is a common error which is almost always caused by another host on +the same network being in full-duplex mode, while this host is in +half-duplex mode. You need to find that other host and make it run in +half-duplex mode or fix this host to run in full-duplex mode. + +As a last resort, you can force the 3c59x driver into full-duplex mode +with + + options 3c59x full_duplex=1 + +but this has to be viewed as a workaround for broken network gear and +should only really be used for equipment which cannot autonegotiate. + + +Additional resources +-------------------- + +Details of the device driver implementation are at the top of the source file. + +Additional documentation is available at Don Becker's Linux Drivers site: + + http://www.scyld.com/vortex.html + +Donald Becker's driver development site: + + http://www.scyld.com/network.html + +Donald's vortex-diag program is useful for inspecting the NIC's state: + + http://www.scyld.com/ethercard_diag.html + +Donald's mii-diag program may be used for inspecting and manipulating +the NIC's Media Independent Interface subsystem: + + http://www.scyld.com/ethercard_diag.html#mii-diag + +Donald's wake-on-LAN page: + + http://www.scyld.com/wakeonlan.html + +3Com's DOS-based application for setting up the NICs EEPROMs: + + ftp://ftp.3com.com/pub/nic/3c90x/3c90xx2.exe + + +Autonegotiation notes +--------------------- + + The driver uses a one-minute heartbeat for adapting to changes in + the external LAN environment if link is up and 5 seconds if link is down. + This means that when, for example, a machine is unplugged from a hubbed + 10baseT LAN plugged into a switched 100baseT LAN, the throughput + will be quite dreadful for up to sixty seconds. Be patient. + + Cisco interoperability note from Walter Wong : + + On a side note, adding HAS_NWAY seems to share a problem with the + Cisco 6509 switch. Specifically, you need to change the spanning + tree parameter for the port the machine is plugged into to 'portfast' + mode. Otherwise, the negotiation fails. This has been an issue + we've noticed for a while but haven't had the time to track down. + + Cisco switches (Jeff Busch ) + + My "standard config" for ports to which PC's/servers connect directly:: + + interface FastEthernet0/N + description machinename + load-interval 30 + spanning-tree portfast + + If autonegotiation is a problem, you may need to specify "speed + 100" and "duplex full" as well (or "speed 10" and "duplex half"). + + WARNING: DO NOT hook up hubs/switches/bridges to these + specially-configured ports! The switch will become very confused. + + +Reporting and diagnosing problems +--------------------------------- + +Maintainers find that accurate and complete problem reports are +invaluable in resolving driver problems. We are frequently not able to +reproduce problems and must rely on your patience and efforts to get to +the bottom of the problem. + +If you believe you have a driver problem here are some of the +steps you should take: + +- Is it really a driver problem? + + Eliminate some variables: try different cards, different + computers, different cables, different ports on the switch/hub, + different versions of the kernel or of the driver, etc. + +- OK, it's a driver problem. + + You need to generate a report. Typically this is an email to the + maintainer and/or netdev@vger.kernel.org. The maintainer's + email address will be in the driver source or in the MAINTAINERS file. + +- The contents of your report will vary a lot depending upon the + problem. If it's a kernel crash then you should refer to the + admin-guide/reporting-bugs.rst file. + + But for most problems it is useful to provide the following: + + - Kernel version, driver version + + - A copy of the banner message which the driver generates when + it is initialised. For example: + + eth0: 3Com PCI 3c905C Tornado at 0xa400, 00:50:da:6a:88:f0, IRQ 19 + 8K byte-wide RAM 5:3 Rx:Tx split, autoselect/Autonegotiate interface. + MII transceiver found at address 24, status 782d. + Enabling bus-master transmits and whole-frame receives. + + NOTE: You must provide the ``debug=2`` modprobe option to generate + a full detection message. Please do this:: + + modprobe 3c59x debug=2 + + - If it is a PCI device, the relevant output from 'lspci -vx', eg:: + + 00:09.0 Ethernet controller: 3Com Corporation 3c905C-TX [Fast Etherlink] (rev 74) + Subsystem: 3Com Corporation: Unknown device 9200 + Flags: bus master, medium devsel, latency 32, IRQ 19 + I/O ports at a400 [size=128] + Memory at db000000 (32-bit, non-prefetchable) [size=128] + Expansion ROM at [disabled] [size=128K] + Capabilities: [dc] Power Management version 2 + 00: b7 10 00 92 07 00 10 02 74 00 00 02 08 20 00 00 + 10: 01 a4 00 00 00 00 00 db 00 00 00 00 00 00 00 00 + 20: 00 00 00 00 00 00 00 00 00 00 00 00 b7 10 00 10 + 30: 00 00 00 00 dc 00 00 00 00 00 00 00 05 01 0a 0a + + - A description of the environment: 10baseT? 100baseT? + full/half duplex? switched or hubbed? + + - Any additional module parameters which you may be providing to the driver. + + - Any kernel logs which are produced. The more the merrier. + If this is a large file and you are sending your report to a + mailing list, mention that you have the logfile, but don't send + it. If you're reporting direct to the maintainer then just send + it. + + To ensure that all kernel logs are available, add the + following line to /etc/syslog.conf:: + + kern.* /var/log/messages + + Then restart syslogd with:: + + /etc/rc.d/init.d/syslog restart + + (The above may vary, depending upon which Linux distribution you use). + + - If your problem is reproducible then that's great. Try the + following: + + 1) Increase the debug level. Usually this is done via: + + a) modprobe driver debug=7 + b) In /etc/modprobe.d/driver.conf: + options driver debug=7 + + 2) Recreate the problem with the higher debug level, + send all logs to the maintainer. + + 3) Download you card's diagnostic tool from Donald + Becker's website . + Download mii-diag.c as well. Build these. + + a) Run 'vortex-diag -aaee' and 'mii-diag -v' when the card is + working correctly. Save the output. + + b) Run the above commands when the card is malfunctioning. Send + both sets of output. + +Finally, please be patient and be prepared to do some work. You may +end up working on this problem for a week or more as the maintainer +asks more questions, asks for more tests, asks for patches to be +applied, etc. At the end of it all, the problem may even remain +unresolved. diff --git a/Documentation/networking/device_drivers/3com/vortex.txt b/Documentation/networking/device_drivers/3com/vortex.txt deleted file mode 100644 index 587f3fcfbcae..000000000000 --- a/Documentation/networking/device_drivers/3com/vortex.txt +++ /dev/null @@ -1,448 +0,0 @@ -Documentation/networking/device_drivers/3com/vortex.txt -Andrew Morton -30 April 2000 - - -This document describes the usage and errata of the 3Com "Vortex" device -driver for Linux, 3c59x.c. - -The driver was written by Donald Becker - -Don is no longer the prime maintainer of this version of the driver. -Please report problems to one or more of: - - Andrew Morton - Netdev mailing list - Linux kernel mailing list - -Please note the 'Reporting and Diagnosing Problems' section at the end -of this file. - - -Since kernel 2.3.99-pre6, this driver incorporates the support for the -3c575-series Cardbus cards which used to be handled by 3c575_cb.c. - -This driver supports the following hardware: - - 3c590 Vortex 10Mbps - 3c592 EISA 10Mbps Demon/Vortex - 3c597 EISA Fast Demon/Vortex - 3c595 Vortex 100baseTx - 3c595 Vortex 100baseT4 - 3c595 Vortex 100base-MII - 3c900 Boomerang 10baseT - 3c900 Boomerang 10Mbps Combo - 3c900 Cyclone 10Mbps TPO - 3c900 Cyclone 10Mbps Combo - 3c900 Cyclone 10Mbps TPC - 3c900B-FL Cyclone 10base-FL - 3c905 Boomerang 100baseTx - 3c905 Boomerang 100baseT4 - 3c905B Cyclone 100baseTx - 3c905B Cyclone 10/100/BNC - 3c905B-FX Cyclone 100baseFx - 3c905C Tornado - 3c920B-EMB-WNM (ATI Radeon 9100 IGP) - 3c980 Cyclone - 3c980C Python-T - 3cSOHO100-TX Hurricane - 3c555 Laptop Hurricane - 3c556 Laptop Tornado - 3c556B Laptop Hurricane - 3c575 [Megahertz] 10/100 LAN CardBus - 3c575 Boomerang CardBus - 3CCFE575BT Cyclone CardBus - 3CCFE575CT Tornado CardBus - 3CCFE656 Cyclone CardBus - 3CCFEM656B Cyclone+Winmodem CardBus - 3CXFEM656C Tornado+Winmodem CardBus - 3c450 HomePNA Tornado - 3c920 Tornado - 3c982 Hydra Dual Port A - 3c982 Hydra Dual Port B - 3c905B-T4 - 3c920B-EMB-WNM Tornado - -Module parameters -================= - -There are several parameters which may be provided to the driver when -its module is loaded. These are usually placed in /etc/modprobe.d/*.conf -configuration files. Example: - -options 3c59x debug=3 rx_copybreak=300 - -If you are using the PCMCIA tools (cardmgr) then the options may be -placed in /etc/pcmcia/config.opts: - -module "3c59x" opts "debug=3 rx_copybreak=300" - - -The supported parameters are: - -debug=N - - Where N is a number from 0 to 7. Anything above 3 produces a lot - of output in your system logs. debug=1 is default. - -options=N1,N2,N3,... - - Each number in the list provides an option to the corresponding - network card. So if you have two 3c905's and you wish to provide - them with option 0x204 you would use: - - options=0x204,0x204 - - The individual options are composed of a number of bitfields which - have the following meanings: - - Possible media type settings - 0 10baseT - 1 10Mbs AUI - 2 undefined - 3 10base2 (BNC) - 4 100base-TX - 5 100base-FX - 6 MII (Media Independent Interface) - 7 Use default setting from EEPROM - 8 Autonegotiate - 9 External MII - 10 Use default setting from EEPROM - - When generating a value for the 'options' setting, the above media - selection values may be OR'ed (or added to) the following: - - 0x8000 Set driver debugging level to 7 - 0x4000 Set driver debugging level to 2 - 0x0400 Enable Wake-on-LAN - 0x0200 Force full duplex mode. - 0x0010 Bus-master enable bit (Old Vortex cards only) - - For example: - - insmod 3c59x options=0x204 - - will force full-duplex 100base-TX, rather than allowing the usual - autonegotiation. - -global_options=N - - Sets the `options' parameter for all 3c59x NICs in the machine. - Entries in the `options' array above will override any setting of - this. - -full_duplex=N1,N2,N3... - - Similar to bit 9 of 'options'. Forces the corresponding card into - full-duplex mode. Please use this in preference to the `options' - parameter. - - In fact, please don't use this at all! You're better off getting - autonegotiation working properly. - -global_full_duplex=N1 - - Sets full duplex mode for all 3c59x NICs in the machine. Entries - in the `full_duplex' array above will override any setting of this. - -flow_ctrl=N1,N2,N3... - - Use 802.3x MAC-layer flow control. The 3com cards only support the - PAUSE command, which means that they will stop sending packets for a - short period if they receive a PAUSE frame from the link partner. - - The driver only allows flow control on a link which is operating in - full duplex mode. - - This feature does not appear to work on the 3c905 - only 3c905B and - 3c905C have been tested. - - The 3com cards appear to only respond to PAUSE frames which are - sent to the reserved destination address of 01:80:c2:00:00:01. They - do not honour PAUSE frames which are sent to the station MAC address. - -rx_copybreak=M - - The driver preallocates 32 full-sized (1536 byte) network buffers - for receiving. When a packet arrives, the driver has to decide - whether to leave the packet in its full-sized buffer, or to allocate - a smaller buffer and copy the packet across into it. - - This is a speed/space tradeoff. - - The value of rx_copybreak is used to decide when to make the copy. - If the packet size is less than rx_copybreak, the packet is copied. - The default value for rx_copybreak is 200 bytes. - -max_interrupt_work=N - - The driver's interrupt service routine can handle many receive and - transmit packets in a single invocation. It does this in a loop. - The value of max_interrupt_work governs how many times the interrupt - service routine will loop. The default value is 32 loops. If this - is exceeded the interrupt service routine gives up and generates a - warning message "eth0: Too much work in interrupt". - -hw_checksums=N1,N2,N3,... - - Recent 3com NICs are able to generate IPv4, TCP and UDP checksums - in hardware. Linux has used the Rx checksumming for a long time. - The "zero copy" patch which is planned for the 2.4 kernel series - allows you to make use of the NIC's DMA scatter/gather and transmit - checksumming as well. - - The driver is set up so that, when the zerocopy patch is applied, - all Tornado and Cyclone devices will use S/G and Tx checksums. - - This module parameter has been provided so you can override this - decision. If you think that Tx checksums are causing a problem, you - may disable the feature with `hw_checksums=0'. - - If you think your NIC should be performing Tx checksumming and the - driver isn't enabling it, you can force the use of hardware Tx - checksumming with `hw_checksums=1'. - - The driver drops a message in the logfiles to indicate whether or - not it is using hardware scatter/gather and hardware Tx checksums. - - Scatter/gather and hardware checksums provide considerable - performance improvement for the sendfile() system call, but a small - decrease in throughput for send(). There is no effect upon receive - efficiency. - -compaq_ioaddr=N -compaq_irq=N -compaq_device_id=N - - "Variables to work-around the Compaq PCI BIOS32 problem".... - -watchdog=N - - Sets the time duration (in milliseconds) after which the kernel - decides that the transmitter has become stuck and needs to be reset. - This is mainly for debugging purposes, although it may be advantageous - to increase this value on LANs which have very high collision rates. - The default value is 5000 (5.0 seconds). - -enable_wol=N1,N2,N3,... - - Enable Wake-on-LAN support for the relevant interface. Donald - Becker's `ether-wake' application may be used to wake suspended - machines. - - Also enables the NIC's power management support. - -global_enable_wol=N - - Sets enable_wol mode for all 3c59x NICs in the machine. Entries in - the `enable_wol' array above will override any setting of this. - -Media selection ---------------- - -A number of the older NICs such as the 3c590 and 3c900 series have -10base2 and AUI interfaces. - -Prior to January, 2001 this driver would autoeselect the 10base2 or AUI -port if it didn't detect activity on the 10baseT port. It would then -get stuck on the 10base2 port and a driver reload was necessary to -switch back to 10baseT. This behaviour could not be prevented with a -module option override. - -Later (current) versions of the driver _do_ support locking of the -media type. So if you load the driver module with - - modprobe 3c59x options=0 - -it will permanently select the 10baseT port. Automatic selection of -other media types does not occur. - - -Transmit error, Tx status register 82 -------------------------------------- - -This is a common error which is almost always caused by another host on -the same network being in full-duplex mode, while this host is in -half-duplex mode. You need to find that other host and make it run in -half-duplex mode or fix this host to run in full-duplex mode. - -As a last resort, you can force the 3c59x driver into full-duplex mode -with - - options 3c59x full_duplex=1 - -but this has to be viewed as a workaround for broken network gear and -should only really be used for equipment which cannot autonegotiate. - - -Additional resources --------------------- - -Details of the device driver implementation are at the top of the source file. - -Additional documentation is available at Don Becker's Linux Drivers site: - - http://www.scyld.com/vortex.html - -Donald Becker's driver development site: - - http://www.scyld.com/network.html - -Donald's vortex-diag program is useful for inspecting the NIC's state: - - http://www.scyld.com/ethercard_diag.html - -Donald's mii-diag program may be used for inspecting and manipulating -the NIC's Media Independent Interface subsystem: - - http://www.scyld.com/ethercard_diag.html#mii-diag - -Donald's wake-on-LAN page: - - http://www.scyld.com/wakeonlan.html - -3Com's DOS-based application for setting up the NICs EEPROMs: - - ftp://ftp.3com.com/pub/nic/3c90x/3c90xx2.exe - - -Autonegotiation notes ---------------------- - - The driver uses a one-minute heartbeat for adapting to changes in - the external LAN environment if link is up and 5 seconds if link is down. - This means that when, for example, a machine is unplugged from a hubbed - 10baseT LAN plugged into a switched 100baseT LAN, the throughput - will be quite dreadful for up to sixty seconds. Be patient. - - Cisco interoperability note from Walter Wong : - - On a side note, adding HAS_NWAY seems to share a problem with the - Cisco 6509 switch. Specifically, you need to change the spanning - tree parameter for the port the machine is plugged into to 'portfast' - mode. Otherwise, the negotiation fails. This has been an issue - we've noticed for a while but haven't had the time to track down. - - Cisco switches (Jeff Busch ) - - My "standard config" for ports to which PC's/servers connect directly: - - interface FastEthernet0/N - description machinename - load-interval 30 - spanning-tree portfast - - If autonegotiation is a problem, you may need to specify "speed - 100" and "duplex full" as well (or "speed 10" and "duplex half"). - - WARNING: DO NOT hook up hubs/switches/bridges to these - specially-configured ports! The switch will become very confused. - - -Reporting and diagnosing problems ---------------------------------- - -Maintainers find that accurate and complete problem reports are -invaluable in resolving driver problems. We are frequently not able to -reproduce problems and must rely on your patience and efforts to get to -the bottom of the problem. - -If you believe you have a driver problem here are some of the -steps you should take: - -- Is it really a driver problem? - - Eliminate some variables: try different cards, different - computers, different cables, different ports on the switch/hub, - different versions of the kernel or of the driver, etc. - -- OK, it's a driver problem. - - You need to generate a report. Typically this is an email to the - maintainer and/or netdev@vger.kernel.org. The maintainer's - email address will be in the driver source or in the MAINTAINERS file. - -- The contents of your report will vary a lot depending upon the - problem. If it's a kernel crash then you should refer to the - admin-guide/reporting-bugs.rst file. - - But for most problems it is useful to provide the following: - - o Kernel version, driver version - - o A copy of the banner message which the driver generates when - it is initialised. For example: - - eth0: 3Com PCI 3c905C Tornado at 0xa400, 00:50:da:6a:88:f0, IRQ 19 - 8K byte-wide RAM 5:3 Rx:Tx split, autoselect/Autonegotiate interface. - MII transceiver found at address 24, status 782d. - Enabling bus-master transmits and whole-frame receives. - - NOTE: You must provide the `debug=2' modprobe option to generate - a full detection message. Please do this: - - modprobe 3c59x debug=2 - - o If it is a PCI device, the relevant output from 'lspci -vx', eg: - - 00:09.0 Ethernet controller: 3Com Corporation 3c905C-TX [Fast Etherlink] (rev 74) - Subsystem: 3Com Corporation: Unknown device 9200 - Flags: bus master, medium devsel, latency 32, IRQ 19 - I/O ports at a400 [size=128] - Memory at db000000 (32-bit, non-prefetchable) [size=128] - Expansion ROM at [disabled] [size=128K] - Capabilities: [dc] Power Management version 2 - 00: b7 10 00 92 07 00 10 02 74 00 00 02 08 20 00 00 - 10: 01 a4 00 00 00 00 00 db 00 00 00 00 00 00 00 00 - 20: 00 00 00 00 00 00 00 00 00 00 00 00 b7 10 00 10 - 30: 00 00 00 00 dc 00 00 00 00 00 00 00 05 01 0a 0a - - o A description of the environment: 10baseT? 100baseT? - full/half duplex? switched or hubbed? - - o Any additional module parameters which you may be providing to the driver. - - o Any kernel logs which are produced. The more the merrier. - If this is a large file and you are sending your report to a - mailing list, mention that you have the logfile, but don't send - it. If you're reporting direct to the maintainer then just send - it. - - To ensure that all kernel logs are available, add the - following line to /etc/syslog.conf: - - kern.* /var/log/messages - - Then restart syslogd with: - - /etc/rc.d/init.d/syslog restart - - (The above may vary, depending upon which Linux distribution you use). - - o If your problem is reproducible then that's great. Try the - following: - - 1) Increase the debug level. Usually this is done via: - - a) modprobe driver debug=7 - b) In /etc/modprobe.d/driver.conf: - options driver debug=7 - - 2) Recreate the problem with the higher debug level, - send all logs to the maintainer. - - 3) Download you card's diagnostic tool from Donald - Becker's website . - Download mii-diag.c as well. Build these. - - a) Run 'vortex-diag -aaee' and 'mii-diag -v' when the card is - working correctly. Save the output. - - b) Run the above commands when the card is malfunctioning. Send - both sets of output. - -Finally, please be patient and be prepared to do some work. You may -end up working on this problem for a week or more as the maintainer -asks more questions, asks for more tests, asks for patches to be -applied, etc. At the end of it all, the problem may even remain -unresolved. diff --git a/Documentation/networking/device_drivers/index.rst b/Documentation/networking/device_drivers/index.rst index 402a9188f446..aaac502b81ea 100644 --- a/Documentation/networking/device_drivers/index.rst +++ b/Documentation/networking/device_drivers/index.rst @@ -28,6 +28,7 @@ Contents: pensando/ionic stmicro/stmmac 3com/3c509 + 3com/vortex .. only:: subproject and html diff --git a/MAINTAINERS b/MAINTAINERS index bee65ebdc67e..eaea5f1994c9 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -147,7 +147,7 @@ Maintainers List M: Steffen Klassert L: netdev@vger.kernel.org S: Odd Fixes -F: Documentation/networking/device_drivers/3com/vortex.txt +F: Documentation/networking/device_drivers/3com/vortex.rst F: drivers/net/ethernet/3com/3c59x.c 3CR990 NETWORK DRIVER diff --git a/drivers/net/ethernet/3com/3c59x.c b/drivers/net/ethernet/3com/3c59x.c index a2b7f7ab8170..5984b7033999 100644 --- a/drivers/net/ethernet/3com/3c59x.c +++ b/drivers/net/ethernet/3com/3c59x.c @@ -1149,7 +1149,7 @@ static int vortex_probe1(struct device *gendev, void __iomem *ioaddr, int irq, print_info = (vortex_debug > 1); if (print_info) - pr_info("See Documentation/networking/device_drivers/3com/vortex.txt\n"); + pr_info("See Documentation/networking/device_drivers/3com/vortex.rst\n"); pr_info("%s: 3Com %s %s at %p.\n", print_name, @@ -1954,7 +1954,7 @@ vortex_error(struct net_device *dev, int status) dev->name, tx_status); if (tx_status == 0x82) { pr_err("Probably a duplex mismatch. See " - "Documentation/networking/device_drivers/3com/vortex.txt\n"); + "Documentation/networking/device_drivers/3com/vortex.rst\n"); } dump_tx_ring(dev); } diff --git a/drivers/net/ethernet/3com/Kconfig b/drivers/net/ethernet/3com/Kconfig index 3a6fc99c6f32..7cc259893cb9 100644 --- a/drivers/net/ethernet/3com/Kconfig +++ b/drivers/net/ethernet/3com/Kconfig @@ -76,7 +76,7 @@ config VORTEX "Hurricane" (3c555/3cSOHO) PCI If you have such a card, say Y here. More specific information is in - and + and in the comments at the beginning of . -- cgit From 8d299c7e912bd8ebb88b9ac2b8e336c9878783aa Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 1 May 2020 16:44:36 +0200 Subject: docs: networking: device drivers: convert amazon/ena.txt to ReST - add SPDX header; - adjust titles and chapters, adding proper markups; - mark code blocks and literals as such; - mark tables as such; - adjust identation, whitespaces and blank lines where needed; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: David S. Miller --- .../networking/device_drivers/amazon/ena.rst | 344 +++++++++++++++++++++ .../networking/device_drivers/amazon/ena.txt | 308 ------------------ Documentation/networking/device_drivers/index.rst | 1 + MAINTAINERS | 2 +- 4 files changed, 346 insertions(+), 309 deletions(-) create mode 100644 Documentation/networking/device_drivers/amazon/ena.rst delete mode 100644 Documentation/networking/device_drivers/amazon/ena.txt diff --git a/Documentation/networking/device_drivers/amazon/ena.rst b/Documentation/networking/device_drivers/amazon/ena.rst new file mode 100644 index 000000000000..11af6388ea87 --- /dev/null +++ b/Documentation/networking/device_drivers/amazon/ena.rst @@ -0,0 +1,344 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================================================ +Linux kernel driver for Elastic Network Adapter (ENA) family +============================================================ + +Overview +======== + +ENA is a networking interface designed to make good use of modern CPU +features and system architectures. + +The ENA device exposes a lightweight management interface with a +minimal set of memory mapped registers and extendable command set +through an Admin Queue. + +The driver supports a range of ENA devices, is link-speed independent +(i.e., the same driver is used for 10GbE, 25GbE, 40GbE, etc.), and has +a negotiated and extendable feature set. + +Some ENA devices support SR-IOV. This driver is used for both the +SR-IOV Physical Function (PF) and Virtual Function (VF) devices. + +ENA devices enable high speed and low overhead network traffic +processing by providing multiple Tx/Rx queue pairs (the maximum number +is advertised by the device via the Admin Queue), a dedicated MSI-X +interrupt vector per Tx/Rx queue pair, adaptive interrupt moderation, +and CPU cacheline optimized data placement. + +The ENA driver supports industry standard TCP/IP offload features such +as checksum offload and TCP transmit segmentation offload (TSO). +Receive-side scaling (RSS) is supported for multi-core scaling. + +The ENA driver and its corresponding devices implement health +monitoring mechanisms such as watchdog, enabling the device and driver +to recover in a manner transparent to the application, as well as +debug logs. + +Some of the ENA devices support a working mode called Low-latency +Queue (LLQ), which saves several more microseconds. + +Supported PCI vendor ID/device IDs +================================== + +========= ======================= +1d0f:0ec2 ENA PF +1d0f:1ec2 ENA PF with LLQ support +1d0f:ec20 ENA VF +1d0f:ec21 ENA VF with LLQ support +========= ======================= + +ENA Source Code Directory Structure +=================================== + +================= ====================================================== +ena_com.[ch] Management communication layer. This layer is + responsible for the handling all the management + (admin) communication between the device and the + driver. +ena_eth_com.[ch] Tx/Rx data path. +ena_admin_defs.h Definition of ENA management interface. +ena_eth_io_defs.h Definition of ENA data path interface. +ena_common_defs.h Common definitions for ena_com layer. +ena_regs_defs.h Definition of ENA PCI memory-mapped (MMIO) registers. +ena_netdev.[ch] Main Linux kernel driver. +ena_syfsfs.[ch] Sysfs files. +ena_ethtool.c ethtool callbacks. +ena_pci_id_tbl.h Supported device IDs. +================= ====================================================== + +Management Interface: +===================== + +ENA management interface is exposed by means of: + +- PCIe Configuration Space +- Device Registers +- Admin Queue (AQ) and Admin Completion Queue (ACQ) +- Asynchronous Event Notification Queue (AENQ) + +ENA device MMIO Registers are accessed only during driver +initialization and are not involved in further normal device +operation. + +AQ is used for submitting management commands, and the +results/responses are reported asynchronously through ACQ. + +ENA introduces a small set of management commands with room for +vendor-specific extensions. Most of the management operations are +framed in a generic Get/Set feature command. + +The following admin queue commands are supported: + +- Create I/O submission queue +- Create I/O completion queue +- Destroy I/O submission queue +- Destroy I/O completion queue +- Get feature +- Set feature +- Configure AENQ +- Get statistics + +Refer to ena_admin_defs.h for the list of supported Get/Set Feature +properties. + +The Asynchronous Event Notification Queue (AENQ) is a uni-directional +queue used by the ENA device to send to the driver events that cannot +be reported using ACQ. AENQ events are subdivided into groups. Each +group may have multiple syndromes, as shown below + +The events are: + + ==================== =============== + Group Syndrome + ==================== =============== + Link state change **X** + Fatal error **X** + Notification Suspend traffic + Notification Resume traffic + Keep-Alive **X** + ==================== =============== + +ACQ and AENQ share the same MSI-X vector. + +Keep-Alive is a special mechanism that allows monitoring of the +device's health. The driver maintains a watchdog (WD) handler which, +if fired, logs the current state and statistics then resets and +restarts the ENA device and driver. A Keep-Alive event is delivered by +the device every second. The driver re-arms the WD upon reception of a +Keep-Alive event. A missed Keep-Alive event causes the WD handler to +fire. + +Data Path Interface +=================== +I/O operations are based on Tx and Rx Submission Queues (Tx SQ and Rx +SQ correspondingly). Each SQ has a completion queue (CQ) associated +with it. + +The SQs and CQs are implemented as descriptor rings in contiguous +physical memory. + +The ENA driver supports two Queue Operation modes for Tx SQs: + +- Regular mode + + * In this mode the Tx SQs reside in the host's memory. The ENA + device fetches the ENA Tx descriptors and packet data from host + memory. + +- Low Latency Queue (LLQ) mode or "push-mode". + + * In this mode the driver pushes the transmit descriptors and the + first 128 bytes of the packet directly to the ENA device memory + space. The rest of the packet payload is fetched by the + device. For this operation mode, the driver uses a dedicated PCI + device memory BAR, which is mapped with write-combine capability. + +The Rx SQs support only the regular mode. + +Note: Not all ENA devices support LLQ, and this feature is negotiated + with the device upon initialization. If the ENA device does not + support LLQ mode, the driver falls back to the regular mode. + +The driver supports multi-queue for both Tx and Rx. This has various +benefits: + +- Reduced CPU/thread/process contention on a given Ethernet interface. +- Cache miss rate on completion is reduced, particularly for data + cache lines that hold the sk_buff structures. +- Increased process-level parallelism when handling received packets. +- Increased data cache hit rate, by steering kernel processing of + packets to the CPU, where the application thread consuming the + packet is running. +- In hardware interrupt re-direction. + +Interrupt Modes +=============== +The driver assigns a single MSI-X vector per queue pair (for both Tx +and Rx directions). The driver assigns an additional dedicated MSI-X vector +for management (for ACQ and AENQ). + +Management interrupt registration is performed when the Linux kernel +probes the adapter, and it is de-registered when the adapter is +removed. I/O queue interrupt registration is performed when the Linux +interface of the adapter is opened, and it is de-registered when the +interface is closed. + +The management interrupt is named:: + + ena-mgmnt@pci: + +and for each queue pair, an interrupt is named:: + + -Tx-Rx- + +The ENA device operates in auto-mask and auto-clear interrupt +modes. That is, once MSI-X is delivered to the host, its Cause bit is +automatically cleared and the interrupt is masked. The interrupt is +unmasked by the driver after NAPI processing is complete. + +Interrupt Moderation +==================== +ENA driver and device can operate in conventional or adaptive interrupt +moderation mode. + +In conventional mode the driver instructs device to postpone interrupt +posting according to static interrupt delay value. The interrupt delay +value can be configured through ethtool(8). The following ethtool +parameters are supported by the driver: tx-usecs, rx-usecs + +In adaptive interrupt moderation mode the interrupt delay value is +updated by the driver dynamically and adjusted every NAPI cycle +according to the traffic nature. + +By default ENA driver applies adaptive coalescing on Rx traffic and +conventional coalescing on Tx traffic. + +Adaptive coalescing can be switched on/off through ethtool(8) +adaptive_rx on|off parameter. + +The driver chooses interrupt delay value according to the number of +bytes and packets received between interrupt unmasking and interrupt +posting. The driver uses interrupt delay table that subdivides the +range of received bytes/packets into 5 levels and assigns interrupt +delay value to each level. + +The user can enable/disable adaptive moderation, modify the interrupt +delay table and restore its default values through sysfs. + +RX copybreak +============ +The rx_copybreak is initialized by default to ENA_DEFAULT_RX_COPYBREAK +and can be configured by the ETHTOOL_STUNABLE command of the +SIOCETHTOOL ioctl. + +SKB +=== +The driver-allocated SKB for frames received from Rx handling using +NAPI context. The allocation method depends on the size of the packet. +If the frame length is larger than rx_copybreak, napi_get_frags() +is used, otherwise netdev_alloc_skb_ip_align() is used, the buffer +content is copied (by CPU) to the SKB, and the buffer is recycled. + +Statistics +========== +The user can obtain ENA device and driver statistics using ethtool. +The driver can collect regular or extended statistics (including +per-queue stats) from the device. + +In addition the driver logs the stats to syslog upon device reset. + +MTU +=== +The driver supports an arbitrarily large MTU with a maximum that is +negotiated with the device. The driver configures MTU using the +SetFeature command (ENA_ADMIN_MTU property). The user can change MTU +via ip(8) and similar legacy tools. + +Stateless Offloads +================== +The ENA driver supports: + +- TSO over IPv4/IPv6 +- TSO with ECN +- IPv4 header checksum offload +- TCP/UDP over IPv4/IPv6 checksum offloads + +RSS +=== +- The ENA device supports RSS that allows flexible Rx traffic + steering. +- Toeplitz and CRC32 hash functions are supported. +- Different combinations of L2/L3/L4 fields can be configured as + inputs for hash functions. +- The driver configures RSS settings using the AQ SetFeature command + (ENA_ADMIN_RSS_HASH_FUNCTION, ENA_ADMIN_RSS_HASH_INPUT and + ENA_ADMIN_RSS_REDIRECTION_TABLE_CONFIG properties). +- If the NETIF_F_RXHASH flag is set, the 32-bit result of the hash + function delivered in the Rx CQ descriptor is set in the received + SKB. +- The user can provide a hash key, hash function, and configure the + indirection table through ethtool(8). + +DATA PATH +========= +Tx +-- + +end_start_xmit() is called by the stack. This function does the following: + +- Maps data buffers (skb->data and frags). +- Populates ena_buf for the push buffer (if the driver and device are + in push mode.) +- Prepares ENA bufs for the remaining frags. +- Allocates a new request ID from the empty req_id ring. The request + ID is the index of the packet in the Tx info. This is used for + out-of-order TX completions. +- Adds the packet to the proper place in the Tx ring. +- Calls ena_com_prepare_tx(), an ENA communication layer that converts + the ena_bufs to ENA descriptors (and adds meta ENA descriptors as + needed.) + + * This function also copies the ENA descriptors and the push buffer + to the Device memory space (if in push mode.) + +- Writes doorbell to the ENA device. +- When the ENA device finishes sending the packet, a completion + interrupt is raised. +- The interrupt handler schedules NAPI. +- The ena_clean_tx_irq() function is called. This function handles the + completion descriptors generated by the ENA, with a single + completion descriptor per completed packet. + + * req_id is retrieved from the completion descriptor. The tx_info of + the packet is retrieved via the req_id. The data buffers are + unmapped and req_id is returned to the empty req_id ring. + * The function stops when the completion descriptors are completed or + the budget is reached. + +Rx +-- + +- When a packet is received from the ENA device. +- The interrupt handler schedules NAPI. +- The ena_clean_rx_irq() function is called. This function calls + ena_rx_pkt(), an ENA communication layer function, which returns the + number of descriptors used for a new unhandled packet, and zero if + no new packet is found. +- Then it calls the ena_clean_rx_irq() function. +- ena_eth_rx_skb() checks packet length: + + * If the packet is small (len < rx_copybreak), the driver allocates + a SKB for the new packet, and copies the packet payload into the + SKB data buffer. + + - In this way the original data buffer is not passed to the stack + and is reused for future Rx packets. + + * Otherwise the function unmaps the Rx buffer, then allocates the + new SKB structure and hooks the Rx buffer to the SKB frags. + +- The new SKB is updated with the necessary information (protocol, + checksum hw verify result, etc.), and then passed to the network + stack, using the NAPI interface function napi_gro_receive(). diff --git a/Documentation/networking/device_drivers/amazon/ena.txt b/Documentation/networking/device_drivers/amazon/ena.txt deleted file mode 100644 index 1bb55c7b604c..000000000000 --- a/Documentation/networking/device_drivers/amazon/ena.txt +++ /dev/null @@ -1,308 +0,0 @@ -Linux kernel driver for Elastic Network Adapter (ENA) family: -============================================================= - -Overview: -========= -ENA is a networking interface designed to make good use of modern CPU -features and system architectures. - -The ENA device exposes a lightweight management interface with a -minimal set of memory mapped registers and extendable command set -through an Admin Queue. - -The driver supports a range of ENA devices, is link-speed independent -(i.e., the same driver is used for 10GbE, 25GbE, 40GbE, etc.), and has -a negotiated and extendable feature set. - -Some ENA devices support SR-IOV. This driver is used for both the -SR-IOV Physical Function (PF) and Virtual Function (VF) devices. - -ENA devices enable high speed and low overhead network traffic -processing by providing multiple Tx/Rx queue pairs (the maximum number -is advertised by the device via the Admin Queue), a dedicated MSI-X -interrupt vector per Tx/Rx queue pair, adaptive interrupt moderation, -and CPU cacheline optimized data placement. - -The ENA driver supports industry standard TCP/IP offload features such -as checksum offload and TCP transmit segmentation offload (TSO). -Receive-side scaling (RSS) is supported for multi-core scaling. - -The ENA driver and its corresponding devices implement health -monitoring mechanisms such as watchdog, enabling the device and driver -to recover in a manner transparent to the application, as well as -debug logs. - -Some of the ENA devices support a working mode called Low-latency -Queue (LLQ), which saves several more microseconds. - -Supported PCI vendor ID/device IDs: -=================================== -1d0f:0ec2 - ENA PF -1d0f:1ec2 - ENA PF with LLQ support -1d0f:ec20 - ENA VF -1d0f:ec21 - ENA VF with LLQ support - -ENA Source Code Directory Structure: -==================================== -ena_com.[ch] - Management communication layer. This layer is - responsible for the handling all the management - (admin) communication between the device and the - driver. -ena_eth_com.[ch] - Tx/Rx data path. -ena_admin_defs.h - Definition of ENA management interface. -ena_eth_io_defs.h - Definition of ENA data path interface. -ena_common_defs.h - Common definitions for ena_com layer. -ena_regs_defs.h - Definition of ENA PCI memory-mapped (MMIO) registers. -ena_netdev.[ch] - Main Linux kernel driver. -ena_syfsfs.[ch] - Sysfs files. -ena_ethtool.c - ethtool callbacks. -ena_pci_id_tbl.h - Supported device IDs. - -Management Interface: -===================== -ENA management interface is exposed by means of: -- PCIe Configuration Space -- Device Registers -- Admin Queue (AQ) and Admin Completion Queue (ACQ) -- Asynchronous Event Notification Queue (AENQ) - -ENA device MMIO Registers are accessed only during driver -initialization and are not involved in further normal device -operation. - -AQ is used for submitting management commands, and the -results/responses are reported asynchronously through ACQ. - -ENA introduces a small set of management commands with room for -vendor-specific extensions. Most of the management operations are -framed in a generic Get/Set feature command. - -The following admin queue commands are supported: -- Create I/O submission queue -- Create I/O completion queue -- Destroy I/O submission queue -- Destroy I/O completion queue -- Get feature -- Set feature -- Configure AENQ -- Get statistics - -Refer to ena_admin_defs.h for the list of supported Get/Set Feature -properties. - -The Asynchronous Event Notification Queue (AENQ) is a uni-directional -queue used by the ENA device to send to the driver events that cannot -be reported using ACQ. AENQ events are subdivided into groups. Each -group may have multiple syndromes, as shown below - -The events are: - Group Syndrome - Link state change - X - - Fatal error - X - - Notification Suspend traffic - Notification Resume traffic - Keep-Alive - X - - -ACQ and AENQ share the same MSI-X vector. - -Keep-Alive is a special mechanism that allows monitoring of the -device's health. The driver maintains a watchdog (WD) handler which, -if fired, logs the current state and statistics then resets and -restarts the ENA device and driver. A Keep-Alive event is delivered by -the device every second. The driver re-arms the WD upon reception of a -Keep-Alive event. A missed Keep-Alive event causes the WD handler to -fire. - -Data Path Interface: -==================== -I/O operations are based on Tx and Rx Submission Queues (Tx SQ and Rx -SQ correspondingly). Each SQ has a completion queue (CQ) associated -with it. - -The SQs and CQs are implemented as descriptor rings in contiguous -physical memory. - -The ENA driver supports two Queue Operation modes for Tx SQs: -- Regular mode - * In this mode the Tx SQs reside in the host's memory. The ENA - device fetches the ENA Tx descriptors and packet data from host - memory. -- Low Latency Queue (LLQ) mode or "push-mode". - * In this mode the driver pushes the transmit descriptors and the - first 128 bytes of the packet directly to the ENA device memory - space. The rest of the packet payload is fetched by the - device. For this operation mode, the driver uses a dedicated PCI - device memory BAR, which is mapped with write-combine capability. - -The Rx SQs support only the regular mode. - -Note: Not all ENA devices support LLQ, and this feature is negotiated - with the device upon initialization. If the ENA device does not - support LLQ mode, the driver falls back to the regular mode. - -The driver supports multi-queue for both Tx and Rx. This has various -benefits: -- Reduced CPU/thread/process contention on a given Ethernet interface. -- Cache miss rate on completion is reduced, particularly for data - cache lines that hold the sk_buff structures. -- Increased process-level parallelism when handling received packets. -- Increased data cache hit rate, by steering kernel processing of - packets to the CPU, where the application thread consuming the - packet is running. -- In hardware interrupt re-direction. - -Interrupt Modes: -================ -The driver assigns a single MSI-X vector per queue pair (for both Tx -and Rx directions). The driver assigns an additional dedicated MSI-X vector -for management (for ACQ and AENQ). - -Management interrupt registration is performed when the Linux kernel -probes the adapter, and it is de-registered when the adapter is -removed. I/O queue interrupt registration is performed when the Linux -interface of the adapter is opened, and it is de-registered when the -interface is closed. - -The management interrupt is named: - ena-mgmnt@pci: -and for each queue pair, an interrupt is named: - -Tx-Rx- - -The ENA device operates in auto-mask and auto-clear interrupt -modes. That is, once MSI-X is delivered to the host, its Cause bit is -automatically cleared and the interrupt is masked. The interrupt is -unmasked by the driver after NAPI processing is complete. - -Interrupt Moderation: -===================== -ENA driver and device can operate in conventional or adaptive interrupt -moderation mode. - -In conventional mode the driver instructs device to postpone interrupt -posting according to static interrupt delay value. The interrupt delay -value can be configured through ethtool(8). The following ethtool -parameters are supported by the driver: tx-usecs, rx-usecs - -In adaptive interrupt moderation mode the interrupt delay value is -updated by the driver dynamically and adjusted every NAPI cycle -according to the traffic nature. - -By default ENA driver applies adaptive coalescing on Rx traffic and -conventional coalescing on Tx traffic. - -Adaptive coalescing can be switched on/off through ethtool(8) -adaptive_rx on|off parameter. - -The driver chooses interrupt delay value according to the number of -bytes and packets received between interrupt unmasking and interrupt -posting. The driver uses interrupt delay table that subdivides the -range of received bytes/packets into 5 levels and assigns interrupt -delay value to each level. - -The user can enable/disable adaptive moderation, modify the interrupt -delay table and restore its default values through sysfs. - -RX copybreak: -============= -The rx_copybreak is initialized by default to ENA_DEFAULT_RX_COPYBREAK -and can be configured by the ETHTOOL_STUNABLE command of the -SIOCETHTOOL ioctl. - -SKB: -==== -The driver-allocated SKB for frames received from Rx handling using -NAPI context. The allocation method depends on the size of the packet. -If the frame length is larger than rx_copybreak, napi_get_frags() -is used, otherwise netdev_alloc_skb_ip_align() is used, the buffer -content is copied (by CPU) to the SKB, and the buffer is recycled. - -Statistics: -=========== -The user can obtain ENA device and driver statistics using ethtool. -The driver can collect regular or extended statistics (including -per-queue stats) from the device. - -In addition the driver logs the stats to syslog upon device reset. - -MTU: -==== -The driver supports an arbitrarily large MTU with a maximum that is -negotiated with the device. The driver configures MTU using the -SetFeature command (ENA_ADMIN_MTU property). The user can change MTU -via ip(8) and similar legacy tools. - -Stateless Offloads: -=================== -The ENA driver supports: -- TSO over IPv4/IPv6 -- TSO with ECN -- IPv4 header checksum offload -- TCP/UDP over IPv4/IPv6 checksum offloads - -RSS: -==== -- The ENA device supports RSS that allows flexible Rx traffic - steering. -- Toeplitz and CRC32 hash functions are supported. -- Different combinations of L2/L3/L4 fields can be configured as - inputs for hash functions. -- The driver configures RSS settings using the AQ SetFeature command - (ENA_ADMIN_RSS_HASH_FUNCTION, ENA_ADMIN_RSS_HASH_INPUT and - ENA_ADMIN_RSS_REDIRECTION_TABLE_CONFIG properties). -- If the NETIF_F_RXHASH flag is set, the 32-bit result of the hash - function delivered in the Rx CQ descriptor is set in the received - SKB. -- The user can provide a hash key, hash function, and configure the - indirection table through ethtool(8). - -DATA PATH: -========== -Tx: ---- -end_start_xmit() is called by the stack. This function does the following: -- Maps data buffers (skb->data and frags). -- Populates ena_buf for the push buffer (if the driver and device are - in push mode.) -- Prepares ENA bufs for the remaining frags. -- Allocates a new request ID from the empty req_id ring. The request - ID is the index of the packet in the Tx info. This is used for - out-of-order TX completions. -- Adds the packet to the proper place in the Tx ring. -- Calls ena_com_prepare_tx(), an ENA communication layer that converts - the ena_bufs to ENA descriptors (and adds meta ENA descriptors as - needed.) - * This function also copies the ENA descriptors and the push buffer - to the Device memory space (if in push mode.) -- Writes doorbell to the ENA device. -- When the ENA device finishes sending the packet, a completion - interrupt is raised. -- The interrupt handler schedules NAPI. -- The ena_clean_tx_irq() function is called. This function handles the - completion descriptors generated by the ENA, with a single - completion descriptor per completed packet. - * req_id is retrieved from the completion descriptor. The tx_info of - the packet is retrieved via the req_id. The data buffers are - unmapped and req_id is returned to the empty req_id ring. - * The function stops when the completion descriptors are completed or - the budget is reached. - -Rx: ---- -- When a packet is received from the ENA device. -- The interrupt handler schedules NAPI. -- The ena_clean_rx_irq() function is called. This function calls - ena_rx_pkt(), an ENA communication layer function, which returns the - number of descriptors used for a new unhandled packet, and zero if - no new packet is found. -- Then it calls the ena_clean_rx_irq() function. -- ena_eth_rx_skb() checks packet length: - * If the packet is small (len < rx_copybreak), the driver allocates - a SKB for the new packet, and copies the packet payload into the - SKB data buffer. - - In this way the original data buffer is not passed to the stack - and is reused for future Rx packets. - * Otherwise the function unmaps the Rx buffer, then allocates the - new SKB structure and hooks the Rx buffer to the SKB frags. -- The new SKB is updated with the necessary information (protocol, - checksum hw verify result, etc.), and then passed to the network - stack, using the NAPI interface function napi_gro_receive(). diff --git a/Documentation/networking/device_drivers/index.rst b/Documentation/networking/device_drivers/index.rst index aaac502b81ea..019a0d2efe67 100644 --- a/Documentation/networking/device_drivers/index.rst +++ b/Documentation/networking/device_drivers/index.rst @@ -29,6 +29,7 @@ Contents: stmicro/stmmac 3com/3c509 3com/vortex + amazon/ena .. only:: subproject and html diff --git a/MAINTAINERS b/MAINTAINERS index eaea5f1994c9..7b6c13cc832f 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -815,7 +815,7 @@ R: Saeed Bishara R: Zorik Machulsky L: netdev@vger.kernel.org S: Supported -F: Documentation/networking/device_drivers/amazon/ena.txt +F: Documentation/networking/device_drivers/amazon/ena.rst F: drivers/net/ethernet/amazon/ AMAZON RDMA EFA DRIVER -- cgit From c958119a487ec4578f50b352f45e965a30daa020 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 1 May 2020 16:44:37 +0200 Subject: docs: networking: device drivers: convert aquantia/atlantic.txt to ReST - add SPDX header; - use copyright symbol; - adjust title and its markup; - comment out text-only TOC from html/pdf output; - mark code blocks and literals as such; - adjust identation, whitespaces and blank lines where needed; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: David S. Miller --- .../device_drivers/aquantia/atlantic.rst | 556 +++++++++++++++++++++ .../device_drivers/aquantia/atlantic.txt | 479 ------------------ Documentation/networking/device_drivers/index.rst | 1 + MAINTAINERS | 2 +- 4 files changed, 558 insertions(+), 480 deletions(-) create mode 100644 Documentation/networking/device_drivers/aquantia/atlantic.rst delete mode 100644 Documentation/networking/device_drivers/aquantia/atlantic.txt diff --git a/Documentation/networking/device_drivers/aquantia/atlantic.rst b/Documentation/networking/device_drivers/aquantia/atlantic.rst new file mode 100644 index 000000000000..595ddef1c8b3 --- /dev/null +++ b/Documentation/networking/device_drivers/aquantia/atlantic.rst @@ -0,0 +1,556 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: + +=============================== +Marvell(Aquantia) AQtion Driver +=============================== + +For the aQuantia Multi-Gigabit PCI Express Family of Ethernet Adapters + +.. Contents + + - Identifying Your Adapter + - Configuration + - Supported ethtool options + - Command Line Parameters + - Config file parameters + - Support + - License + +Identifying Your Adapter +======================== + +The driver in this release is compatible with AQC-100, AQC-107, AQC-108 +based ethernet adapters. + + +SFP+ Devices (for AQC-100 based adapters) +----------------------------------------- + +This release tested with passive Direct Attach Cables (DAC) and SFP+/LC +Optical Transceiver. + +Configuration +============= + +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:: + + dmesg -n 8 + + .. note:: + + This setting is not saved across reboots. + +Jumbo Frames +------------ + The driver supports Jumbo Frames for all adapters. Jumbo Frames support is + enabled by changing the MTU to a value larger than the default of 1500. + The maximum value for the MTU is 16000. Use the `ip` command to + increase the MTU size. For example:: + + ip link set mtu 16000 dev enp1s0 + +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. + +NAPI +---- + NAPI (Rx polling mode) is supported in the atlantic driver. + +Supported ethtool options +========================= + +Viewing adapter settings +------------------------ + + :: + + ethtool + + Output example:: + + Settings for enp1s0: + Supported ports: [ TP ] + Supported link modes: 100baseT/Full + 1000baseT/Full + 10000baseT/Full + 2500baseT/Full + 5000baseT/Full + Supported pause frame use: Symmetric + Supports auto-negotiation: Yes + Supported FEC modes: Not reported + Advertised link modes: 100baseT/Full + 1000baseT/Full + 10000baseT/Full + 2500baseT/Full + 5000baseT/Full + Advertised pause frame use: Symmetric + Advertised auto-negotiation: Yes + Advertised FEC modes: Not reported + Speed: 10000Mb/s + Duplex: Full + Port: Twisted Pair + PHYAD: 0 + Transceiver: internal + Auto-negotiation: on + MDI-X: Unknown + Supports Wake-on: g + Wake-on: d + Link detected: yes + + + .. note:: + + AQrate speeds (2.5/5 Gb/s) will be displayed only with linux kernels > 4.10. + But you can still use these speeds:: + + ethtool -s eth0 autoneg off speed 2500 + +Viewing adapter information +--------------------------- + + :: + + ethtool -i + + Output example:: + + driver: atlantic + version: 5.2.0-050200rc5-generic-kern + firmware-version: 3.1.78 + expansion-rom-version: + bus-info: 0000:01:00.0 + supports-statistics: yes + supports-test: no + supports-eeprom-access: no + supports-register-dump: yes + supports-priv-flags: no + + +Viewing Ethernet adapter statistics +----------------------------------- + + :: + + ethtool -S + + Output example:: + + NIC statistics: + InPackets: 13238607 + InUCast: 13293852 + InMCast: 52 + InBCast: 3 + InErrors: 0 + OutPackets: 23703019 + OutUCast: 23704941 + OutMCast: 67 + OutBCast: 11 + InUCastOctects: 213182760 + OutUCastOctects: 22698443 + InMCastOctects: 6600 + OutMCastOctects: 8776 + InBCastOctects: 192 + OutBCastOctects: 704 + InOctects: 2131839552 + OutOctects: 226938073 + InPacketsDma: 95532300 + OutPacketsDma: 59503397 + InOctetsDma: 1137102462 + OutOctetsDma: 2394339518 + InDroppedDma: 0 + Queue[0] InPackets: 23567131 + Queue[0] OutPackets: 20070028 + Queue[0] InJumboPackets: 0 + Queue[0] InLroPackets: 0 + Queue[0] InErrors: 0 + Queue[1] InPackets: 45428967 + Queue[1] OutPackets: 11306178 + Queue[1] InJumboPackets: 0 + Queue[1] InLroPackets: 0 + Queue[1] InErrors: 0 + Queue[2] InPackets: 3187011 + Queue[2] OutPackets: 13080381 + Queue[2] InJumboPackets: 0 + Queue[2] InLroPackets: 0 + Queue[2] InErrors: 0 + Queue[3] InPackets: 23349136 + Queue[3] OutPackets: 15046810 + Queue[3] InJumboPackets: 0 + Queue[3] InLroPackets: 0 + Queue[3] InErrors: 0 + +Interrupt coalescing support +---------------------------- + + ITR mode, TX/RX coalescing timings could be viewed with:: + + ethtool -c + + and changed with:: + + ethtool -C tx-usecs rx-usecs + + To disable coalescing:: + + ethtool -C tx-usecs 0 rx-usecs 0 tx-max-frames 1 tx-max-frames 1 + +Wake on LAN support +------------------- + + WOL support by magic packet:: + + ethtool -s wol g + + To disable WOL:: + + ethtool -s wol d + +Set and check the driver message level +-------------------------------------- + + Set message level + + :: + + ethtool -s msglvl + + Level values: + + ====== ============================= + 0x0001 general driver status. + 0x0002 hardware probing. + 0x0004 link state. + 0x0008 periodic status check. + 0x0010 interface being brought down. + 0x0020 interface being brought up. + 0x0040 receive error. + 0x0080 transmit error. + 0x0200 interrupt handling. + 0x0400 transmit completion. + 0x0800 receive completion. + 0x1000 packet contents. + 0x2000 hardware status. + 0x4000 Wake-on-LAN status. + ====== ============================= + + By default, the level of debugging messages is set 0x0001(general driver status). + + Check message level + + :: + + ethtool | grep "Current message level" + + If you want to disable the output of messages:: + + ethtool -s msglvl 0 + +RX flow rules (ntuple filters) +------------------------------ + + There are separate rules supported, that applies in that order: + + 1. 16 VLAN ID rules + 2. 16 L2 EtherType rules + 3. 8 L3/L4 5-Tuple rules + + + The driver utilizes the ethtool interface for configuring ntuple filters, + via ``ethtool -N ``. + + To enable or disable the RX flow rules:: + + ethtool -K ethX ntuple + + When disabling ntuple filters, all the user programed filters are + flushed from the driver cache and hardware. All needed filters must + be re-added when ntuple is re-enabled. + + Because of the fixed order of the rules, the location of filters is also fixed: + + - Locations 0 - 15 for VLAN ID filters + - Locations 16 - 31 for L2 EtherType filters + - Locations 32 - 39 for L3/L4 5-tuple filters (locations 32, 36 for IPv6) + + The L3/L4 5-tuple (protocol, source and destination IP address, source and + destination TCP/UDP/SCTP port) is compared against 8 filters. For IPv4, up to + 8 source and destination addresses can be matched. For IPv6, up to 2 pairs of + addresses can be supported. Source and destination ports are only compared for + TCP/UDP/SCTP packets. + + To add a filter that directs packet to queue 5, use + ``<-N|-U|--config-nfc|--config-ntuple>`` switch:: + + ethtool -N flow-type udp4 src-ip 10.0.0.1 dst-ip 10.0.0.2 src-port 2000 dst-port 2001 action 5 + + - action is the queue number. + - loc is the rule number. + + For ``flow-type ip4|udp4|tcp4|sctp4|ip6|udp6|tcp6|sctp6`` you must set the loc + number within 32 - 39. + For ``flow-type ip4|udp4|tcp4|sctp4|ip6|udp6|tcp6|sctp6`` you can set 8 rules + for traffic IPv4 or you can set 2 rules for traffic IPv6. Loc number traffic + IPv6 is 32 and 36. + At the moment you can not use IPv4 and IPv6 filters at the same time. + + Example filter for IPv6 filter traffic:: + + sudo ethtool -N flow-type tcp6 src-ip 2001:db8:0:f101::1 dst-ip 2001:db8:0:f101::2 action 1 loc 32 + sudo ethtool -N flow-type ip6 src-ip 2001:db8:0:f101::2 dst-ip 2001:db8:0:f101::5 action -1 loc 36 + + Example filter for IPv4 filter traffic:: + + sudo ethtool -N flow-type udp4 src-ip 10.0.0.4 dst-ip 10.0.0.7 src-port 2000 dst-port 2001 loc 32 + sudo ethtool -N flow-type tcp4 src-ip 10.0.0.3 dst-ip 10.0.0.9 src-port 2000 dst-port 2001 loc 33 + sudo ethtool -N flow-type ip4 src-ip 10.0.0.6 dst-ip 10.0.0.4 loc 34 + + If you set action -1, then all traffic corresponding to the filter will be discarded. + + The maximum value action is 31. + + + The VLAN filter (VLAN id) is compared against 16 filters. + VLAN id must be accompanied by mask 0xF000. That is to distinguish VLAN filter + from L2 Ethertype filter with UserPriority since both User Priority and VLAN ID + are passed in the same 'vlan' parameter. + + To add a filter that directs packets from VLAN 2001 to queue 5:: + + ethtool -N flow-type ip4 vlan 2001 m 0xF000 action 1 loc 0 + + + L2 EtherType filters allows filter packet by EtherType field or both EtherType + and User Priority (PCP) field of 802.1Q. + UserPriority (vlan) parameter must be accompanied by mask 0x1FFF. That is to + distinguish VLAN filter from L2 Ethertype filter with UserPriority since both + User Priority and VLAN ID are passed in the same 'vlan' parameter. + + To add a filter that directs IP4 packess of priority 3 to queue 3:: + + ethtool -N flow-type ether proto 0x800 vlan 0x600 m 0x1FFF action 3 loc 16 + + To see the list of filters currently present:: + + ethtool <-u|-n|--show-nfc|--show-ntuple> + + Rules may be deleted from the table itself. This is done using:: + + sudo ethtool <-N|-U|--config-nfc|--config-ntuple> delete + + - loc is the rule number to be deleted. + + Rx filters is an interface to load the filter table that funnels all flow + into queue 0 unless an alternative queue is specified using "action". In that + case, any flow that matches the filter criteria will be directed to the + appropriate queue. RX filters is supported on all kernels 2.6.30 and later. + +RSS for UDP +----------- + + Currently, NIC does not support RSS for fragmented IP packets, which leads to + incorrect working of RSS for fragmented UDP traffic. To disable RSS for UDP the + RX Flow L3/L4 rule may be used. + + Example:: + + ethtool -N eth0 flow-type udp4 action 0 loc 32 + +UDP GSO hardware offload +------------------------ + + UDP GSO allows to boost UDP tx rates by offloading UDP headers allocation + into hardware. A special userspace socket option is required for this, + could be validated with /kernel/tools/testing/selftests/net/:: + + udpgso_bench_tx -u -4 -D 10.0.1.1 -s 6300 -S 100 + + Will cause sending out of 100 byte sized UDP packets formed from single + 6300 bytes user buffer. + + UDP GSO is configured by:: + + ethtool -K eth0 tx-udp-segmentation on + +Private flags (testing) +----------------------- + + Atlantic driver supports private flags for hardware custom features:: + + $ ethtool --show-priv-flags ethX + + Private flags for ethX: + DMASystemLoopback : off + PKTSystemLoopback : off + DMANetworkLoopback : off + PHYInternalLoopback: off + PHYExternalLoopback: off + + Example:: + + $ ethtool --set-priv-flags ethX DMASystemLoopback on + + DMASystemLoopback: DMA Host loopback. + PKTSystemLoopback: Packet buffer host loopback. + DMANetworkLoopback: Network side loopback on DMA block. + PHYInternalLoopback: Internal loopback on Phy. + PHYExternalLoopback: External loopback on Phy (with loopback ethernet cable). + + +Command Line Parameters +======================= +The following command line parameters are available on atlantic driver: + +aq_itr -Interrupt throttling mode +--------------------------------- +Accepted values: 0, 1, 0xFFFF + +Default value: 0xFFFF + +====== ============================================================== +0 Disable interrupt throttling. +1 Enable interrupt throttling and use specified tx and rx rates. +0xFFFF Auto throttling mode. Driver will choose the best RX and TX + interrupt throtting settings based on link speed. +====== ============================================================== + +aq_itr_tx - TX interrupt throttle rate +-------------------------------------- + +Accepted values: 0 - 0x1FF + +Default value: 0 + +TX side throttling in microseconds. Adapter will setup maximum interrupt delay +to this value. Minimum interrupt delay will be a half of this value + +aq_itr_rx - RX interrupt throttle rate +-------------------------------------- + +Accepted values: 0 - 0x1FF + +Default value: 0 + +RX side throttling in microseconds. Adapter will setup maximum interrupt delay +to this value. Minimum interrupt delay will be a half of this value + +.. note:: + + ITR settings could be changed in runtime by ethtool -c means (see below) + +Config file parameters +====================== + +For some fine tuning and performance optimizations, +some parameters can be changed in the {source_dir}/aq_cfg.h file. + +AQ_CFG_RX_PAGEORDER +------------------- + +Default value: 0 + +RX page order override. Thats a power of 2 number of RX pages allocated for +each descriptor. Received descriptor size is still limited by +AQ_CFG_RX_FRAME_MAX. + +Increasing pageorder makes page reuse better (actual on iommu enabled systems). + +AQ_CFG_RX_REFILL_THRES +---------------------- + +Default value: 32 + +RX refill threshold. RX path will not refill freed descriptors until the +specified number of free descriptors is observed. Larger values may help +better page reuse but may lead to packet drops as well. + +AQ_CFG_VECS_DEF +--------------- + +Number of queues + +Valid Range: 0 - 8 (up to AQ_CFG_VECS_MAX) + +Default value: 8 + +Notice this value will be capped by the number of cores available on the system. + +AQ_CFG_IS_RSS_DEF +----------------- + +Enable/disable Receive Side Scaling + +This feature allows the adapter to distribute receive processing +across multiple CPU-cores and to prevent from overloading a single CPU core. + +Valid values + +== ======== +0 disabled +1 enabled +== ======== + +Default value: 1 + +AQ_CFG_NUM_RSS_QUEUES_DEF +------------------------- + +Number of queues for Receive Side Scaling + +Valid Range: 0 - 8 (up to AQ_CFG_VECS_DEF) + +Default value: AQ_CFG_VECS_DEF + +AQ_CFG_IS_LRO_DEF +----------------- + +Enable/disable Large Receive Offload + +This offload enables the adapter to coalesce multiple TCP segments and indicate +them as a single coalesced unit to the OS networking subsystem. + +The system consumes less energy but it also introduces more latency in packets +processing. + +Valid values + +== ======== +0 disabled +1 enabled +== ======== + +Default value: 1 + +AQ_CFG_TX_CLEAN_BUDGET +---------------------- + +Maximum descriptors to cleanup on TX at once. + +Default value: 256 + +After the aq_cfg.h file changed the driver must be rebuilt to take effect. + +Support +======= + +If an issue is identified with the released source code on the supported +kernel with a supported adapter, email the specific information related +to the issue to aqn_support@marvell.com + +License +======= + +aQuantia Corporation Network Driver + +Copyright |copy| 2014 - 2019 aQuantia Corporation. + +This program is free software; you can redistribute it and/or modify it +under the terms and conditions of the GNU General Public License, +version 2, as published by the Free Software Foundation. diff --git a/Documentation/networking/device_drivers/aquantia/atlantic.txt b/Documentation/networking/device_drivers/aquantia/atlantic.txt deleted file mode 100644 index 2013fcedc2da..000000000000 --- a/Documentation/networking/device_drivers/aquantia/atlantic.txt +++ /dev/null @@ -1,479 +0,0 @@ -Marvell(Aquantia) AQtion Driver for the aQuantia Multi-Gigabit PCI Express -Family of Ethernet Adapters -============================================================================= - -Contents -======== - -- Identifying Your Adapter -- Configuration -- Supported ethtool options -- Command Line Parameters -- Config file parameters -- Support -- License - -Identifying Your Adapter -======================== - -The driver in this release is compatible with AQC-100, AQC-107, AQC-108 based ethernet adapters. - - -SFP+ Devices (for AQC-100 based adapters) ----------------------------------- - -This release tested with passive Direct Attach Cables (DAC) and SFP+/LC Optical Transceiver. - -Configuration -========================= - 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: - - dmesg -n 8 - - NOTE: This setting is not saved across reboots. - - Jumbo Frames - ------------ - The driver supports Jumbo Frames for all adapters. Jumbo Frames support is - enabled by changing the MTU to a value larger than the default of 1500. - The maximum value for the MTU is 16000. Use the `ip` command to - increase the MTU size. For example: - - ip link set mtu 16000 dev enp1s0 - - 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. - - NAPI - ---- - NAPI (Rx polling mode) is supported in the atlantic driver. - -Supported ethtool options -============================ - Viewing adapter settings - --------------------- - ethtool - - Output example: - - Settings for enp1s0: - Supported ports: [ TP ] - Supported link modes: 100baseT/Full - 1000baseT/Full - 10000baseT/Full - 2500baseT/Full - 5000baseT/Full - Supported pause frame use: Symmetric - Supports auto-negotiation: Yes - Supported FEC modes: Not reported - Advertised link modes: 100baseT/Full - 1000baseT/Full - 10000baseT/Full - 2500baseT/Full - 5000baseT/Full - Advertised pause frame use: Symmetric - Advertised auto-negotiation: Yes - Advertised FEC modes: Not reported - Speed: 10000Mb/s - Duplex: Full - Port: Twisted Pair - PHYAD: 0 - Transceiver: internal - Auto-negotiation: on - MDI-X: Unknown - Supports Wake-on: g - Wake-on: d - Link detected: yes - - --- - Note: AQrate speeds (2.5/5 Gb/s) will be displayed only with linux kernels > 4.10. - But you can still use these speeds: - ethtool -s eth0 autoneg off speed 2500 - - Viewing adapter information - --------------------- - ethtool -i - - Output example: - - driver: atlantic - version: 5.2.0-050200rc5-generic-kern - firmware-version: 3.1.78 - expansion-rom-version: - bus-info: 0000:01:00.0 - supports-statistics: yes - supports-test: no - supports-eeprom-access: no - supports-register-dump: yes - supports-priv-flags: no - - - Viewing Ethernet adapter statistics: - --------------------- - ethtool -S - - Output example: - NIC statistics: - InPackets: 13238607 - InUCast: 13293852 - InMCast: 52 - InBCast: 3 - InErrors: 0 - OutPackets: 23703019 - OutUCast: 23704941 - OutMCast: 67 - OutBCast: 11 - InUCastOctects: 213182760 - OutUCastOctects: 22698443 - InMCastOctects: 6600 - OutMCastOctects: 8776 - InBCastOctects: 192 - OutBCastOctects: 704 - InOctects: 2131839552 - OutOctects: 226938073 - InPacketsDma: 95532300 - OutPacketsDma: 59503397 - InOctetsDma: 1137102462 - OutOctetsDma: 2394339518 - InDroppedDma: 0 - Queue[0] InPackets: 23567131 - Queue[0] OutPackets: 20070028 - Queue[0] InJumboPackets: 0 - Queue[0] InLroPackets: 0 - Queue[0] InErrors: 0 - Queue[1] InPackets: 45428967 - Queue[1] OutPackets: 11306178 - Queue[1] InJumboPackets: 0 - Queue[1] InLroPackets: 0 - Queue[1] InErrors: 0 - Queue[2] InPackets: 3187011 - Queue[2] OutPackets: 13080381 - Queue[2] InJumboPackets: 0 - Queue[2] InLroPackets: 0 - Queue[2] InErrors: 0 - Queue[3] InPackets: 23349136 - Queue[3] OutPackets: 15046810 - Queue[3] InJumboPackets: 0 - Queue[3] InLroPackets: 0 - Queue[3] InErrors: 0 - - Interrupt coalescing support - --------------------------------- - ITR mode, TX/RX coalescing timings could be viewed with: - - ethtool -c - - and changed with: - - ethtool -C tx-usecs rx-usecs - - To disable coalescing: - - ethtool -C tx-usecs 0 rx-usecs 0 tx-max-frames 1 tx-max-frames 1 - - Wake on LAN support - --------------------------------- - - WOL support by magic packet: - - ethtool -s wol g - - To disable WOL: - - ethtool -s wol d - - Set and check the driver message level - --------------------------------- - - Set message level - - ethtool -s msglvl - - Level values: - - 0x0001 - general driver status. - 0x0002 - hardware probing. - 0x0004 - link state. - 0x0008 - periodic status check. - 0x0010 - interface being brought down. - 0x0020 - interface being brought up. - 0x0040 - receive error. - 0x0080 - transmit error. - 0x0200 - interrupt handling. - 0x0400 - transmit completion. - 0x0800 - receive completion. - 0x1000 - packet contents. - 0x2000 - hardware status. - 0x4000 - Wake-on-LAN status. - - By default, the level of debugging messages is set 0x0001(general driver status). - - Check message level - - ethtool | grep "Current message level" - - If you want to disable the output of messages - - ethtool -s msglvl 0 - - RX flow rules (ntuple filters) - --------------------------------- - There are separate rules supported, that applies in that order: - 1. 16 VLAN ID rules - 2. 16 L2 EtherType rules - 3. 8 L3/L4 5-Tuple rules - - - The driver utilizes the ethtool interface for configuring ntuple filters, - via "ethtool -N ". - - To enable or disable the RX flow rules: - - ethtool -K ethX ntuple - - When disabling ntuple filters, all the user programed filters are - flushed from the driver cache and hardware. All needed filters must - be re-added when ntuple is re-enabled. - - Because of the fixed order of the rules, the location of filters is also fixed: - - Locations 0 - 15 for VLAN ID filters - - Locations 16 - 31 for L2 EtherType filters - - Locations 32 - 39 for L3/L4 5-tuple filters (locations 32, 36 for IPv6) - - The L3/L4 5-tuple (protocol, source and destination IP address, source and - destination TCP/UDP/SCTP port) is compared against 8 filters. For IPv4, up to - 8 source and destination addresses can be matched. For IPv6, up to 2 pairs of - addresses can be supported. Source and destination ports are only compared for - TCP/UDP/SCTP packets. - - To add a filter that directs packet to queue 5, use <-N|-U|--config-nfc|--config-ntuple> switch: - - ethtool -N flow-type udp4 src-ip 10.0.0.1 dst-ip 10.0.0.2 src-port 2000 dst-port 2001 action 5 - - - action is the queue number. - - loc is the rule number. - - For "flow-type ip4|udp4|tcp4|sctp4|ip6|udp6|tcp6|sctp6" you must set the loc - number within 32 - 39. - For "flow-type ip4|udp4|tcp4|sctp4|ip6|udp6|tcp6|sctp6" you can set 8 rules - for traffic IPv4 or you can set 2 rules for traffic IPv6. Loc number traffic - IPv6 is 32 and 36. - At the moment you can not use IPv4 and IPv6 filters at the same time. - - Example filter for IPv6 filter traffic: - - sudo ethtool -N flow-type tcp6 src-ip 2001:db8:0:f101::1 dst-ip 2001:db8:0:f101::2 action 1 loc 32 - sudo ethtool -N flow-type ip6 src-ip 2001:db8:0:f101::2 dst-ip 2001:db8:0:f101::5 action -1 loc 36 - - Example filter for IPv4 filter traffic: - - sudo ethtool -N flow-type udp4 src-ip 10.0.0.4 dst-ip 10.0.0.7 src-port 2000 dst-port 2001 loc 32 - sudo ethtool -N flow-type tcp4 src-ip 10.0.0.3 dst-ip 10.0.0.9 src-port 2000 dst-port 2001 loc 33 - sudo ethtool -N flow-type ip4 src-ip 10.0.0.6 dst-ip 10.0.0.4 loc 34 - - If you set action -1, then all traffic corresponding to the filter will be discarded. - The maximum value action is 31. - - - The VLAN filter (VLAN id) is compared against 16 filters. - VLAN id must be accompanied by mask 0xF000. That is to distinguish VLAN filter - from L2 Ethertype filter with UserPriority since both User Priority and VLAN ID - are passed in the same 'vlan' parameter. - - To add a filter that directs packets from VLAN 2001 to queue 5: - ethtool -N flow-type ip4 vlan 2001 m 0xF000 action 1 loc 0 - - - L2 EtherType filters allows filter packet by EtherType field or both EtherType - and User Priority (PCP) field of 802.1Q. - UserPriority (vlan) parameter must be accompanied by mask 0x1FFF. That is to - distinguish VLAN filter from L2 Ethertype filter with UserPriority since both - User Priority and VLAN ID are passed in the same 'vlan' parameter. - - To add a filter that directs IP4 packess of priority 3 to queue 3: - ethtool -N flow-type ether proto 0x800 vlan 0x600 m 0x1FFF action 3 loc 16 - - - To see the list of filters currently present: - - ethtool <-u|-n|--show-nfc|--show-ntuple> - - Rules may be deleted from the table itself. This is done using: - - sudo ethtool <-N|-U|--config-nfc|--config-ntuple> delete - - - loc is the rule number to be deleted. - - Rx filters is an interface to load the filter table that funnels all flow - into queue 0 unless an alternative queue is specified using "action". In that - case, any flow that matches the filter criteria will be directed to the - appropriate queue. RX filters is supported on all kernels 2.6.30 and later. - - RSS for UDP - --------------------------------- - Currently, NIC does not support RSS for fragmented IP packets, which leads to - incorrect working of RSS for fragmented UDP traffic. To disable RSS for UDP the - RX Flow L3/L4 rule may be used. - - Example: - ethtool -N eth0 flow-type udp4 action 0 loc 32 - - UDP GSO hardware offload - --------------------------------- - UDP GSO allows to boost UDP tx rates by offloading UDP headers allocation - into hardware. A special userspace socket option is required for this, - could be validated with /kernel/tools/testing/selftests/net/ - - udpgso_bench_tx -u -4 -D 10.0.1.1 -s 6300 -S 100 - - Will cause sending out of 100 byte sized UDP packets formed from single - 6300 bytes user buffer. - - UDP GSO is configured by: - - ethtool -K eth0 tx-udp-segmentation on - - Private flags (testing) - --------------------------------- - - Atlantic driver supports private flags for hardware custom features: - - $ ethtool --show-priv-flags ethX - - Private flags for ethX: - DMASystemLoopback : off - PKTSystemLoopback : off - DMANetworkLoopback : off - PHYInternalLoopback: off - PHYExternalLoopback: off - - Example: - - $ ethtool --set-priv-flags ethX DMASystemLoopback on - - DMASystemLoopback: DMA Host loopback. - PKTSystemLoopback: Packet buffer host loopback. - DMANetworkLoopback: Network side loopback on DMA block. - PHYInternalLoopback: Internal loopback on Phy. - PHYExternalLoopback: External loopback on Phy (with loopback ethernet cable). - - -Command Line Parameters -======================= -The following command line parameters are available on atlantic driver: - -aq_itr -Interrupt throttling mode ----------------------------------------- -Accepted values: 0, 1, 0xFFFF -Default value: 0xFFFF -0 - Disable interrupt throttling. -1 - Enable interrupt throttling and use specified tx and rx rates. -0xFFFF - Auto throttling mode. Driver will choose the best RX and TX - interrupt throtting settings based on link speed. - -aq_itr_tx - TX interrupt throttle rate ----------------------------------------- -Accepted values: 0 - 0x1FF -Default value: 0 -TX side throttling in microseconds. Adapter will setup maximum interrupt delay -to this value. Minimum interrupt delay will be a half of this value - -aq_itr_rx - RX interrupt throttle rate ----------------------------------------- -Accepted values: 0 - 0x1FF -Default value: 0 -RX side throttling in microseconds. Adapter will setup maximum interrupt delay -to this value. Minimum interrupt delay will be a half of this value - -Note: ITR settings could be changed in runtime by ethtool -c means (see below) - -Config file parameters -======================= -For some fine tuning and performance optimizations, -some parameters can be changed in the {source_dir}/aq_cfg.h file. - -AQ_CFG_RX_PAGEORDER ----------------------------------------- -Default value: 0 -RX page order override. Thats a power of 2 number of RX pages allocated for -each descriptor. Received descriptor size is still limited by AQ_CFG_RX_FRAME_MAX. -Increasing pageorder makes page reuse better (actual on iommu enabled systems). - -AQ_CFG_RX_REFILL_THRES ----------------------------------------- -Default value: 32 -RX refill threshold. RX path will not refill freed descriptors until the -specified number of free descriptors is observed. Larger values may help -better page reuse but may lead to packet drops as well. - -AQ_CFG_VECS_DEF ------------------------------------------------------------- -Number of queues -Valid Range: 0 - 8 (up to AQ_CFG_VECS_MAX) -Default value: 8 -Notice this value will be capped by the number of cores available on the system. - -AQ_CFG_IS_RSS_DEF ------------------------------------------------------------- -Enable/disable Receive Side Scaling - -This feature allows the adapter to distribute receive processing -across multiple CPU-cores and to prevent from overloading a single CPU core. - -Valid values -0 - disabled -1 - enabled - -Default value: 1 - -AQ_CFG_NUM_RSS_QUEUES_DEF ------------------------------------------------------------- -Number of queues for Receive Side Scaling -Valid Range: 0 - 8 (up to AQ_CFG_VECS_DEF) - -Default value: AQ_CFG_VECS_DEF - -AQ_CFG_IS_LRO_DEF ------------------------------------------------------------- -Enable/disable Large Receive Offload - -This offload enables the adapter to coalesce multiple TCP segments and indicate -them as a single coalesced unit to the OS networking subsystem. -The system consumes less energy but it also introduces more latency in packets processing. - -Valid values -0 - disabled -1 - enabled - -Default value: 1 - -AQ_CFG_TX_CLEAN_BUDGET ----------------------------------------- -Maximum descriptors to cleanup on TX at once. -Default value: 256 - -After the aq_cfg.h file changed the driver must be rebuilt to take effect. - -Support -======= - -If an issue is identified with the released source code on the supported -kernel with a supported adapter, email the specific information related -to the issue to aqn_support@marvell.com - -License -======= - -aQuantia Corporation Network Driver -Copyright(c) 2014 - 2019 aQuantia Corporation. - -This program is free software; you can redistribute it and/or modify it -under the terms and conditions of the GNU General Public License, -version 2, as published by the Free Software Foundation. diff --git a/Documentation/networking/device_drivers/index.rst b/Documentation/networking/device_drivers/index.rst index 019a0d2efe67..7dde314fc957 100644 --- a/Documentation/networking/device_drivers/index.rst +++ b/Documentation/networking/device_drivers/index.rst @@ -30,6 +30,7 @@ Contents: 3com/3c509 3com/vortex amazon/ena + aquantia/atlantic .. only:: subproject and html diff --git a/MAINTAINERS b/MAINTAINERS index 7b6c13cc832f..b5cfee17635e 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -1275,7 +1275,7 @@ L: netdev@vger.kernel.org S: Supported W: https://www.marvell.com/ Q: http://patchwork.ozlabs.org/project/netdev/list/ -F: Documentation/networking/device_drivers/aquantia/atlantic.txt +F: Documentation/networking/device_drivers/aquantia/atlantic.rst F: drivers/net/ethernet/aquantia/atlantic/ AQUANTIA ETHERNET DRIVER PTP SUBSYSTEM -- cgit From c839ce557b35de084d06f91c4e37948bdcef9709 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 1 May 2020 16:44:38 +0200 Subject: docs: networking: device drivers: convert chelsio/cxgb.txt to ReST - add SPDX header; - use copyright symbol; - adjust titles and chapters, adding proper markups; - comment out text-only TOC from html/pdf output; - mark code blocks and literals as such; - add notes markups; - mark tables as such; - mark lists as such; - adjust identation, whitespaces and blank lines where needed; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: David S. Miller --- .../networking/device_drivers/chelsio/cxgb.rst | 393 +++++++++++++++++++++ .../networking/device_drivers/chelsio/cxgb.txt | 352 ------------------ Documentation/networking/device_drivers/index.rst | 1 + drivers/net/ethernet/chelsio/Kconfig | 2 +- 4 files changed, 395 insertions(+), 353 deletions(-) create mode 100644 Documentation/networking/device_drivers/chelsio/cxgb.rst delete mode 100644 Documentation/networking/device_drivers/chelsio/cxgb.txt diff --git a/Documentation/networking/device_drivers/chelsio/cxgb.rst b/Documentation/networking/device_drivers/chelsio/cxgb.rst new file mode 100644 index 000000000000..435dce5fa2c7 --- /dev/null +++ b/Documentation/networking/device_drivers/chelsio/cxgb.rst @@ -0,0 +1,393 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: + +============================================= +Chelsio N210 10Gb Ethernet Network Controller +============================================= + +Driver Release Notes for Linux + +Version 2.1.1 + +June 20, 2005 + +.. Contents + + INTRODUCTION + FEATURES + PERFORMANCE + DRIVER MESSAGES + KNOWN ISSUES + SUPPORT + + +Introduction +============ + + This document describes the Linux driver for Chelsio 10Gb Ethernet Network + Controller. This driver supports the Chelsio N210 NIC and is backward + compatible with the Chelsio N110 model 10Gb NICs. + + +Features +======== + +Adaptive Interrupts (adaptive-rx) +--------------------------------- + + This feature provides an adaptive algorithm that adjusts the interrupt + coalescing parameters, allowing the driver to dynamically adapt the latency + settings to achieve the highest performance during various types of network + load. + + The interface used to control this feature is ethtool. Please see the + ethtool manpage for additional usage information. + + By default, adaptive-rx is disabled. + To enable adaptive-rx:: + + ethtool -C adaptive-rx on + + To disable adaptive-rx, use ethtool:: + + ethtool -C adaptive-rx off + + After disabling adaptive-rx, the timer latency value will be set to 50us. + You may set the timer latency after disabling adaptive-rx:: + + ethtool -C rx-usecs + + An example to set the timer latency value to 100us on eth0:: + + ethtool -C eth0 rx-usecs 100 + + You may also provide a timer latency value while disabling adaptive-rx:: + + ethtool -C adaptive-rx off rx-usecs + + If adaptive-rx is disabled and a timer latency value is specified, the timer + will be set to the specified value until changed by the user or until + adaptive-rx is enabled. + + To view the status of the adaptive-rx and timer latency values:: + + ethtool -c + + +TCP Segmentation Offloading (TSO) Support +----------------------------------------- + + This feature, also known as "large send", enables a system's protocol stack + to offload portions of outbound TCP processing to a network interface card + thereby reducing system CPU utilization and enhancing performance. + + The interface used to control this feature is ethtool version 1.8 or higher. + Please see the ethtool manpage for additional usage information. + + By default, TSO is enabled. + To disable TSO:: + + ethtool -K tso off + + To enable TSO:: + + ethtool -K tso on + + To view the status of TSO:: + + ethtool -k + + +Performance +=========== + + The following information is provided as an example of how to change system + parameters for "performance tuning" an what value to use. You may or may not + want to change these system parameters, depending on your server/workstation + application. Doing so is not warranted in any way by Chelsio Communications, + and is done at "YOUR OWN RISK". Chelsio will not be held responsible for loss + of data or damage to equipment. + + Your distribution may have a different way of doing things, or you may prefer + a different method. These commands are shown only to provide an example of + what to do and are by no means definitive. + + Making any of the following system changes will only last until you reboot + your system. You may want to write a script that runs at boot-up which + includes the optimal settings for your system. + + Setting PCI Latency Timer:: + + setpci -d 1425:: + +* 0x0c.l=0x0000F800 + + Disabling TCP timestamp:: + + sysctl -w net.ipv4.tcp_timestamps=0 + + Disabling SACK:: + + sysctl -w net.ipv4.tcp_sack=0 + + Setting large number of incoming connection requests:: + + sysctl -w net.ipv4.tcp_max_syn_backlog=3000 + + Setting maximum receive socket buffer size:: + + sysctl -w net.core.rmem_max=1024000 + + Setting maximum send socket buffer size:: + + sysctl -w net.core.wmem_max=1024000 + + Set smp_affinity (on a multiprocessor system) to a single CPU:: + + echo 1 > /proc/irq//smp_affinity + + Setting default receive socket buffer size:: + + sysctl -w net.core.rmem_default=524287 + + Setting default send socket buffer size:: + + sysctl -w net.core.wmem_default=524287 + + Setting maximum option memory buffers:: + + sysctl -w net.core.optmem_max=524287 + + Setting maximum backlog (# of unprocessed packets before kernel drops):: + + sysctl -w net.core.netdev_max_backlog=300000 + + Setting TCP read buffers (min/default/max):: + + sysctl -w net.ipv4.tcp_rmem="10000000 10000000 10000000" + + Setting TCP write buffers (min/pressure/max):: + + sysctl -w net.ipv4.tcp_wmem="10000000 10000000 10000000" + + Setting TCP buffer space (min/pressure/max):: + + sysctl -w net.ipv4.tcp_mem="10000000 10000000 10000000" + + TCP window size for single connections: + + The receive buffer (RX_WINDOW) size must be at least as large as the + Bandwidth-Delay Product of the communication link between the sender and + receiver. Due to the variations of RTT, you may want to increase the buffer + size up to 2 times the Bandwidth-Delay Product. Reference page 289 of + "TCP/IP Illustrated, Volume 1, The Protocols" by W. Richard Stevens. + + At 10Gb speeds, use the following formula:: + + RX_WINDOW >= 1.25MBytes * RTT(in milliseconds) + Example for RTT with 100us: RX_WINDOW = (1,250,000 * 0.1) = 125,000 + + RX_WINDOW sizes of 256KB - 512KB should be sufficient. + + Setting the min, max, and default receive buffer (RX_WINDOW) size:: + + sysctl -w net.ipv4.tcp_rmem=" " + + TCP window size for multiple connections: + The receive buffer (RX_WINDOW) size may be calculated the same as single + connections, but should be divided by the number of connections. The + smaller window prevents congestion and facilitates better pacing, + especially if/when MAC level flow control does not work well or when it is + not supported on the machine. Experimentation may be necessary to attain + the correct value. This method is provided as a starting point for the + correct receive buffer size. + + Setting the min, max, and default receive buffer (RX_WINDOW) size is + performed in the same manner as single connection. + + +Driver Messages +=============== + + The following messages are the most common messages logged by syslog. These + may be found in /var/log/messages. + + Driver up:: + + Chelsio Network Driver - version 2.1.1 + + NIC detected:: + + eth#: Chelsio N210 1x10GBaseX NIC (rev #), PCIX 133MHz/64-bit + + Link up:: + + eth#: link is up at 10 Gbps, full duplex + + Link down:: + + eth#: link is down + + +Known Issues +============ + + These issues have been identified during testing. The following information + is provided as a workaround to the problem. In some cases, this problem is + inherent to Linux or to a particular Linux Distribution and/or hardware + platform. + + 1. Large number of TCP retransmits on a multiprocessor (SMP) system. + + On a system with multiple CPUs, the interrupt (IRQ) for the network + controller may be bound to more than one CPU. This will cause TCP + retransmits if the packet data were to be split across different CPUs + and re-assembled in a different order than expected. + + To eliminate the TCP retransmits, set smp_affinity on the particular + interrupt to a single CPU. You can locate the interrupt (IRQ) used on + the N110/N210 by using ifconfig:: + + ifconfig | grep Interrupt + + Set the smp_affinity to a single CPU:: + + echo 1 > /proc/irq//smp_affinity + + It is highly suggested that you do not run the irqbalance daemon on your + system, as this will change any smp_affinity setting you have applied. + The irqbalance daemon runs on a 10 second interval and binds interrupts + to the least loaded CPU determined by the daemon. To disable this daemon:: + + chkconfig --level 2345 irqbalance off + + By default, some Linux distributions enable the kernel feature, + irqbalance, which performs the same function as the daemon. To disable + this feature, add the following line to your bootloader:: + + noirqbalance + + Example using the Grub bootloader:: + + title Red Hat Enterprise Linux AS (2.4.21-27.ELsmp) + root (hd0,0) + kernel /vmlinuz-2.4.21-27.ELsmp ro root=/dev/hda3 noirqbalance + initrd /initrd-2.4.21-27.ELsmp.img + + 2. After running insmod, the driver is loaded and the incorrect network + interface is brought up without running ifup. + + When using 2.4.x kernels, including RHEL kernels, the Linux kernel + invokes a script named "hotplug". This script is primarily used to + automatically bring up USB devices when they are plugged in, however, + the script also attempts to automatically bring up a network interface + after loading the kernel module. The hotplug script does this by scanning + the ifcfg-eth# config files in /etc/sysconfig/network-scripts, looking + for HWADDR=. + + If the hotplug script does not find the HWADDRR within any of the + ifcfg-eth# files, it will bring up the device with the next available + interface name. If this interface is already configured for a different + network card, your new interface will have incorrect IP address and + network settings. + + To solve this issue, you can add the HWADDR= key to the + interface config file of your network controller. + + To disable this "hotplug" feature, you may add the driver (module name) + to the "blacklist" file located in /etc/hotplug. It has been noted that + this does not work for network devices because the net.agent script + does not use the blacklist file. Simply remove, or rename, the net.agent + script located in /etc/hotplug to disable this feature. + + 3. Transport Protocol (TP) hangs when running heavy multi-connection traffic + on an AMD Opteron system with HyperTransport PCI-X Tunnel chipset. + + If your AMD Opteron system uses the AMD-8131 HyperTransport PCI-X Tunnel + chipset, you may experience the "133-Mhz Mode Split Completion Data + Corruption" bug identified by AMD while using a 133Mhz PCI-X card on the + bus PCI-X bus. + + AMD states, "Under highly specific conditions, the AMD-8131 PCI-X Tunnel + can provide stale data via split completion cycles to a PCI-X card that + is operating at 133 Mhz", causing data corruption. + + AMD's provides three workarounds for this problem, however, Chelsio + recommends the first option for best performance with this bug: + + For 133Mhz secondary bus operation, limit the transaction length and + the number of outstanding transactions, via BIOS configuration + programming of the PCI-X card, to the following: + + Data Length (bytes): 1k + + Total allowed outstanding transactions: 2 + + Please refer to AMD 8131-HT/PCI-X Errata 26310 Rev 3.08 August 2004, + section 56, "133-MHz Mode Split Completion Data Corruption" for more + details with this bug and workarounds suggested by AMD. + + It may be possible to work outside AMD's recommended PCI-X settings, try + increasing the Data Length to 2k bytes for increased performance. If you + have issues with these settings, please revert to the "safe" settings + and duplicate the problem before submitting a bug or asking for support. + + .. note:: + + The default setting on most systems is 8 outstanding transactions + and 2k bytes data length. + + 4. On multiprocessor systems, it has been noted that an application which + is handling 10Gb networking can switch between CPUs causing degraded + and/or unstable performance. + + If running on an SMP system and taking performance measurements, it + is suggested you either run the latest netperf-2.4.0+ or use a binding + tool such as Tim Hockin's procstate utilities (runon) + . + + Binding netserver and netperf (or other applications) to particular + CPUs will have a significant difference in performance measurements. + You may need to experiment which CPU to bind the application to in + order to achieve the best performance for your system. + + If you are developing an application designed for 10Gb networking, + please keep in mind you may want to look at kernel functions + sched_setaffinity & sched_getaffinity to bind your application. + + If you are just running user-space applications such as ftp, telnet, + etc., you may want to try the runon tool provided by Tim Hockin's + procstate utility. You could also try binding the interface to a + particular CPU: runon 0 ifup eth0 + + +Support +======= + + If you have problems with the software or hardware, please contact our + customer support team via email at support@chelsio.com or check our website + at http://www.chelsio.com + +------------------------------------------------------------------------------- + +:: + + Chelsio Communications + 370 San Aleso Ave. + Suite 100 + Sunnyvale, CA 94085 + http://www.chelsio.com + +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License, version 2, as +published by the Free Software Foundation. + +You should have received a copy of the GNU General Public License along +with this program; if not, write to the Free Software Foundation, Inc., +59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. + +THIS SOFTWARE IS PROVIDED ``AS IS`` AND WITHOUT ANY EXPRESS OR IMPLIED +WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. + +Copyright |copy| 2003-2005 Chelsio Communications. All rights reserved. diff --git a/Documentation/networking/device_drivers/chelsio/cxgb.txt b/Documentation/networking/device_drivers/chelsio/cxgb.txt deleted file mode 100644 index 20a887615c4a..000000000000 --- a/Documentation/networking/device_drivers/chelsio/cxgb.txt +++ /dev/null @@ -1,352 +0,0 @@ - Chelsio N210 10Gb Ethernet Network Controller - - Driver Release Notes for Linux - - Version 2.1.1 - - June 20, 2005 - -CONTENTS -======== - INTRODUCTION - FEATURES - PERFORMANCE - DRIVER MESSAGES - KNOWN ISSUES - SUPPORT - - -INTRODUCTION -============ - - This document describes the Linux driver for Chelsio 10Gb Ethernet Network - Controller. This driver supports the Chelsio N210 NIC and is backward - compatible with the Chelsio N110 model 10Gb NICs. - - -FEATURES -======== - - Adaptive Interrupts (adaptive-rx) - --------------------------------- - - This feature provides an adaptive algorithm that adjusts the interrupt - coalescing parameters, allowing the driver to dynamically adapt the latency - settings to achieve the highest performance during various types of network - load. - - The interface used to control this feature is ethtool. Please see the - ethtool manpage for additional usage information. - - By default, adaptive-rx is disabled. - To enable adaptive-rx: - - ethtool -C adaptive-rx on - - To disable adaptive-rx, use ethtool: - - ethtool -C adaptive-rx off - - After disabling adaptive-rx, the timer latency value will be set to 50us. - You may set the timer latency after disabling adaptive-rx: - - ethtool -C rx-usecs - - An example to set the timer latency value to 100us on eth0: - - ethtool -C eth0 rx-usecs 100 - - You may also provide a timer latency value while disabling adaptive-rx: - - ethtool -C adaptive-rx off rx-usecs - - If adaptive-rx is disabled and a timer latency value is specified, the timer - will be set to the specified value until changed by the user or until - adaptive-rx is enabled. - - To view the status of the adaptive-rx and timer latency values: - - ethtool -c - - - TCP Segmentation Offloading (TSO) Support - ----------------------------------------- - - This feature, also known as "large send", enables a system's protocol stack - to offload portions of outbound TCP processing to a network interface card - thereby reducing system CPU utilization and enhancing performance. - - The interface used to control this feature is ethtool version 1.8 or higher. - Please see the ethtool manpage for additional usage information. - - By default, TSO is enabled. - To disable TSO: - - ethtool -K tso off - - To enable TSO: - - ethtool -K tso on - - To view the status of TSO: - - ethtool -k - - -PERFORMANCE -=========== - - The following information is provided as an example of how to change system - parameters for "performance tuning" an what value to use. You may or may not - want to change these system parameters, depending on your server/workstation - application. Doing so is not warranted in any way by Chelsio Communications, - and is done at "YOUR OWN RISK". Chelsio will not be held responsible for loss - of data or damage to equipment. - - Your distribution may have a different way of doing things, or you may prefer - a different method. These commands are shown only to provide an example of - what to do and are by no means definitive. - - Making any of the following system changes will only last until you reboot - your system. You may want to write a script that runs at boot-up which - includes the optimal settings for your system. - - Setting PCI Latency Timer: - setpci -d 1425:* 0x0c.l=0x0000F800 - - Disabling TCP timestamp: - sysctl -w net.ipv4.tcp_timestamps=0 - - Disabling SACK: - sysctl -w net.ipv4.tcp_sack=0 - - Setting large number of incoming connection requests: - sysctl -w net.ipv4.tcp_max_syn_backlog=3000 - - Setting maximum receive socket buffer size: - sysctl -w net.core.rmem_max=1024000 - - Setting maximum send socket buffer size: - sysctl -w net.core.wmem_max=1024000 - - Set smp_affinity (on a multiprocessor system) to a single CPU: - echo 1 > /proc/irq//smp_affinity - - Setting default receive socket buffer size: - sysctl -w net.core.rmem_default=524287 - - Setting default send socket buffer size: - sysctl -w net.core.wmem_default=524287 - - Setting maximum option memory buffers: - sysctl -w net.core.optmem_max=524287 - - Setting maximum backlog (# of unprocessed packets before kernel drops): - sysctl -w net.core.netdev_max_backlog=300000 - - Setting TCP read buffers (min/default/max): - sysctl -w net.ipv4.tcp_rmem="10000000 10000000 10000000" - - Setting TCP write buffers (min/pressure/max): - sysctl -w net.ipv4.tcp_wmem="10000000 10000000 10000000" - - Setting TCP buffer space (min/pressure/max): - sysctl -w net.ipv4.tcp_mem="10000000 10000000 10000000" - - TCP window size for single connections: - The receive buffer (RX_WINDOW) size must be at least as large as the - Bandwidth-Delay Product of the communication link between the sender and - receiver. Due to the variations of RTT, you may want to increase the buffer - size up to 2 times the Bandwidth-Delay Product. Reference page 289 of - "TCP/IP Illustrated, Volume 1, The Protocols" by W. Richard Stevens. - At 10Gb speeds, use the following formula: - RX_WINDOW >= 1.25MBytes * RTT(in milliseconds) - Example for RTT with 100us: RX_WINDOW = (1,250,000 * 0.1) = 125,000 - RX_WINDOW sizes of 256KB - 512KB should be sufficient. - Setting the min, max, and default receive buffer (RX_WINDOW) size: - sysctl -w net.ipv4.tcp_rmem=" " - - TCP window size for multiple connections: - The receive buffer (RX_WINDOW) size may be calculated the same as single - connections, but should be divided by the number of connections. The - smaller window prevents congestion and facilitates better pacing, - especially if/when MAC level flow control does not work well or when it is - not supported on the machine. Experimentation may be necessary to attain - the correct value. This method is provided as a starting point for the - correct receive buffer size. - Setting the min, max, and default receive buffer (RX_WINDOW) size is - performed in the same manner as single connection. - - -DRIVER MESSAGES -=============== - - The following messages are the most common messages logged by syslog. These - may be found in /var/log/messages. - - Driver up: - Chelsio Network Driver - version 2.1.1 - - NIC detected: - eth#: Chelsio N210 1x10GBaseX NIC (rev #), PCIX 133MHz/64-bit - - Link up: - eth#: link is up at 10 Gbps, full duplex - - Link down: - eth#: link is down - - -KNOWN ISSUES -============ - - These issues have been identified during testing. The following information - is provided as a workaround to the problem. In some cases, this problem is - inherent to Linux or to a particular Linux Distribution and/or hardware - platform. - - 1. Large number of TCP retransmits on a multiprocessor (SMP) system. - - On a system with multiple CPUs, the interrupt (IRQ) for the network - controller may be bound to more than one CPU. This will cause TCP - retransmits if the packet data were to be split across different CPUs - and re-assembled in a different order than expected. - - To eliminate the TCP retransmits, set smp_affinity on the particular - interrupt to a single CPU. You can locate the interrupt (IRQ) used on - the N110/N210 by using ifconfig: - ifconfig | grep Interrupt - Set the smp_affinity to a single CPU: - echo 1 > /proc/irq//smp_affinity - - It is highly suggested that you do not run the irqbalance daemon on your - system, as this will change any smp_affinity setting you have applied. - The irqbalance daemon runs on a 10 second interval and binds interrupts - to the least loaded CPU determined by the daemon. To disable this daemon: - chkconfig --level 2345 irqbalance off - - By default, some Linux distributions enable the kernel feature, - irqbalance, which performs the same function as the daemon. To disable - this feature, add the following line to your bootloader: - noirqbalance - - Example using the Grub bootloader: - title Red Hat Enterprise Linux AS (2.4.21-27.ELsmp) - root (hd0,0) - kernel /vmlinuz-2.4.21-27.ELsmp ro root=/dev/hda3 noirqbalance - initrd /initrd-2.4.21-27.ELsmp.img - - 2. After running insmod, the driver is loaded and the incorrect network - interface is brought up without running ifup. - - When using 2.4.x kernels, including RHEL kernels, the Linux kernel - invokes a script named "hotplug". This script is primarily used to - automatically bring up USB devices when they are plugged in, however, - the script also attempts to automatically bring up a network interface - after loading the kernel module. The hotplug script does this by scanning - the ifcfg-eth# config files in /etc/sysconfig/network-scripts, looking - for HWADDR=. - - If the hotplug script does not find the HWADDRR within any of the - ifcfg-eth# files, it will bring up the device with the next available - interface name. If this interface is already configured for a different - network card, your new interface will have incorrect IP address and - network settings. - - To solve this issue, you can add the HWADDR= key to the - interface config file of your network controller. - - To disable this "hotplug" feature, you may add the driver (module name) - to the "blacklist" file located in /etc/hotplug. It has been noted that - this does not work for network devices because the net.agent script - does not use the blacklist file. Simply remove, or rename, the net.agent - script located in /etc/hotplug to disable this feature. - - 3. Transport Protocol (TP) hangs when running heavy multi-connection traffic - on an AMD Opteron system with HyperTransport PCI-X Tunnel chipset. - - If your AMD Opteron system uses the AMD-8131 HyperTransport PCI-X Tunnel - chipset, you may experience the "133-Mhz Mode Split Completion Data - Corruption" bug identified by AMD while using a 133Mhz PCI-X card on the - bus PCI-X bus. - - AMD states, "Under highly specific conditions, the AMD-8131 PCI-X Tunnel - can provide stale data via split completion cycles to a PCI-X card that - is operating at 133 Mhz", causing data corruption. - - AMD's provides three workarounds for this problem, however, Chelsio - recommends the first option for best performance with this bug: - - For 133Mhz secondary bus operation, limit the transaction length and - the number of outstanding transactions, via BIOS configuration - programming of the PCI-X card, to the following: - - Data Length (bytes): 1k - Total allowed outstanding transactions: 2 - - Please refer to AMD 8131-HT/PCI-X Errata 26310 Rev 3.08 August 2004, - section 56, "133-MHz Mode Split Completion Data Corruption" for more - details with this bug and workarounds suggested by AMD. - - It may be possible to work outside AMD's recommended PCI-X settings, try - increasing the Data Length to 2k bytes for increased performance. If you - have issues with these settings, please revert to the "safe" settings - and duplicate the problem before submitting a bug or asking for support. - - NOTE: The default setting on most systems is 8 outstanding transactions - and 2k bytes data length. - - 4. On multiprocessor systems, it has been noted that an application which - is handling 10Gb networking can switch between CPUs causing degraded - and/or unstable performance. - - If running on an SMP system and taking performance measurements, it - is suggested you either run the latest netperf-2.4.0+ or use a binding - tool such as Tim Hockin's procstate utilities (runon) - . - - Binding netserver and netperf (or other applications) to particular - CPUs will have a significant difference in performance measurements. - You may need to experiment which CPU to bind the application to in - order to achieve the best performance for your system. - - If you are developing an application designed for 10Gb networking, - please keep in mind you may want to look at kernel functions - sched_setaffinity & sched_getaffinity to bind your application. - - If you are just running user-space applications such as ftp, telnet, - etc., you may want to try the runon tool provided by Tim Hockin's - procstate utility. You could also try binding the interface to a - particular CPU: runon 0 ifup eth0 - - -SUPPORT -======= - - If you have problems with the software or hardware, please contact our - customer support team via email at support@chelsio.com or check our website - at http://www.chelsio.com - -=============================================================================== - - Chelsio Communications - 370 San Aleso Ave. - Suite 100 - Sunnyvale, CA 94085 - http://www.chelsio.com - -This program is free software; you can redistribute it and/or modify -it under the terms of the GNU General Public License, version 2, as -published by the Free Software Foundation. - -You should have received a copy of the GNU General Public License along -with this program; if not, write to the Free Software Foundation, Inc., -59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. - -THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED -WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF -MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. - - Copyright (c) 2003-2005 Chelsio Communications. All rights reserved. - -=============================================================================== diff --git a/Documentation/networking/device_drivers/index.rst b/Documentation/networking/device_drivers/index.rst index 7dde314fc957..23c4ec9c9125 100644 --- a/Documentation/networking/device_drivers/index.rst +++ b/Documentation/networking/device_drivers/index.rst @@ -31,6 +31,7 @@ Contents: 3com/vortex amazon/ena aquantia/atlantic + chelsio/cxgb .. only:: subproject and html diff --git a/drivers/net/ethernet/chelsio/Kconfig b/drivers/net/ethernet/chelsio/Kconfig index 9909bfda167e..82cdfa51ce37 100644 --- a/drivers/net/ethernet/chelsio/Kconfig +++ b/drivers/net/ethernet/chelsio/Kconfig @@ -26,7 +26,7 @@ config CHELSIO_T1 This driver supports Chelsio gigabit and 10-gigabit Ethernet cards. More information about adapter features and performance tuning is in - . + . For general information about Chelsio and our products, visit our website at . -- cgit From 714a4da450c03bdc53a0d5fa6a4b3192b30c5cda Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 1 May 2020 16:44:39 +0200 Subject: docs: networking: device drivers: convert cirrus/cs89x0.txt to ReST - add SPDX header; - adjust title markup; - mark code blocks and literals as such; - adjust identation, whitespaces and blank lines where needed; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: David S. Miller --- .../networking/device_drivers/cirrus/cs89x0.rst | 647 +++++++++++++++++++++ .../networking/device_drivers/cirrus/cs89x0.txt | 624 -------------------- Documentation/networking/device_drivers/index.rst | 1 + drivers/net/ethernet/cirrus/Kconfig | 2 +- 4 files changed, 649 insertions(+), 625 deletions(-) create mode 100644 Documentation/networking/device_drivers/cirrus/cs89x0.rst delete mode 100644 Documentation/networking/device_drivers/cirrus/cs89x0.txt diff --git a/Documentation/networking/device_drivers/cirrus/cs89x0.rst b/Documentation/networking/device_drivers/cirrus/cs89x0.rst new file mode 100644 index 000000000000..e5c283940ac5 --- /dev/null +++ b/Documentation/networking/device_drivers/cirrus/cs89x0.rst @@ -0,0 +1,647 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================================ +Cirrus Logic LAN CS8900/CS8920 Ethernet Adapters +================================================ + +.. note:: + + This document was contributed by Cirrus Logic for kernel 2.2.5. This version + has been updated for 2.3.48 by Andrew Morton. + + Still, this is too outdated! A major cleanup is needed here. + +Cirrus make a copy of this driver available at their website, as +described below. In general, you should use the driver version which +comes with your Linux distribution. + + +Linux Network Interface Driver ver. 2.00 + + +.. TABLE OF CONTENTS + + 1.0 CIRRUS LOGIC LAN CS8900/CS8920 ETHERNET ADAPTERS + 1.1 Product Overview + 1.2 Driver Description + 1.2.1 Driver Name + 1.2.2 File in the Driver Package + 1.3 System Requirements + 1.4 Licensing Information + + 2.0 ADAPTER INSTALLATION and CONFIGURATION + 2.1 CS8900-based Adapter Configuration + 2.2 CS8920-based Adapter Configuration + + 3.0 LOADING THE DRIVER AS A MODULE + + 4.0 COMPILING THE DRIVER + 4.1 Compiling the Driver as a Loadable Module + 4.2 Compiling the driver to support memory mode + 4.3 Compiling the driver to support Rx DMA + + 5.0 TESTING AND TROUBLESHOOTING + 5.1 Known Defects and Limitations + 5.2 Testing the Adapter + 5.2.1 Diagnostic Self-Test + 5.2.2 Diagnostic Network Test + 5.3 Using the Adapter's LEDs + 5.4 Resolving I/O Conflicts + + 6.0 TECHNICAL SUPPORT + 6.1 Contacting Cirrus Logic's Technical Support + 6.2 Information Required Before Contacting Technical Support + 6.3 Obtaining the Latest Driver Version + 6.4 Current maintainer + 6.5 Kernel boot parameters + + +1. Cirrus Logic LAN CS8900/CS8920 Ethernet Adapters +=================================================== + + +1.1. Product Overview +===================== + +The CS8900-based ISA Ethernet Adapters from Cirrus Logic follow +IEEE 802.3 standards and support half or full-duplex operation in ISA bus +computers on 10 Mbps Ethernet networks. The adapters are designed for operation +in 16-bit ISA or EISA bus expansion slots and are available in +10BaseT-only or 3-media configurations (10BaseT, 10Base2, and AUI for 10Base-5 +or fiber networks). + +CS8920-based adapters are similar to the CS8900-based adapter with additional +features for Plug and Play (PnP) support and Wakeup Frame recognition. As +such, the configuration procedures differ somewhat between the two types of +adapters. Refer to the "Adapter Configuration" section for details on +configuring both types of adapters. + + +1.2. Driver Description +======================= + +The CS8900/CS8920 Ethernet Adapter driver for Linux supports the Linux +v2.3.48 or greater kernel. It can be compiled directly into the kernel +or loaded at run-time as a device driver module. + +1.2.1 Driver Name: cs89x0 + +1.2.2 Files in the Driver Archive: + +The files in the driver at Cirrus' website include: + + =================== ==================================================== + readme.txt this file + build batch file to compile cs89x0.c. + cs89x0.c driver C code + cs89x0.h driver header file + cs89x0.o pre-compiled module (for v2.2.5 kernel) + config/Config.in sample file to include cs89x0 driver in the kernel. + config/Makefile sample file to include cs89x0 driver in the kernel. + config/Space.c sample file to include cs89x0 driver in the kernel. + =================== ==================================================== + + + +1.3. System Requirements +------------------------ + +The following hardware is required: + + * Cirrus Logic LAN (CS8900/20-based) Ethernet ISA Adapter + + * IBM or IBM-compatible PC with: + * An 80386 or higher processor + * 16 bytes of contiguous IO space available between 210h - 370h + * One available IRQ (5,10,11,or 12 for the CS8900, 3-7,9-15 for CS8920). + + * Appropriate cable (and connector for AUI, 10BASE-2) for your network + topology. + +The following software is required: + +* LINUX kernel version 2.3.48 or higher + + * CS8900/20 Setup Utility (DOS-based) + + * LINUX kernel sources for your kernel (if compiling into kernel) + + * GNU Toolkit (gcc and make) v2.6 or above (if compiling into kernel + or a module) + + + +1.4. Licensing Information +-------------------------- + +This program is free software; you can redistribute it and/or modify it under +the terms of the GNU General Public License as published by the Free Software +Foundation, version 1. + +This program is distributed in the hope that it will be useful, but WITHOUT +ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for +more details. + +For a full copy of the GNU General Public License, write to the Free Software +Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + + + +2. Adapter Installation and Configuration +========================================= + +Both the CS8900 and CS8920-based adapters can be configured using parameters +stored in an on-board EEPROM. You must use the DOS-based CS8900/20 Setup +Utility if you want to change the adapter's configuration in EEPROM. + +When loading the driver as a module, you can specify many of the adapter's +configuration parameters on the command-line to override the EEPROM's settings +or for interface configuration when an EEPROM is not used. (CS8920-based +adapters must use an EEPROM.) See Section 3.0 LOADING THE DRIVER AS A MODULE. + +Since the CS8900/20 Setup Utility is a DOS-based application, you must install +and configure the adapter in a DOS-based system using the CS8900/20 Setup +Utility before installation in the target LINUX system. (Not required if +installing a CS8900-based adapter and the default configuration is acceptable.) + + +2.1. CS8900-based Adapter Configuration +--------------------------------------- + +CS8900-based adapters shipped from Cirrus Logic have been configured +with the following "default" settings:: + + Operation Mode: Memory Mode + IRQ: 10 + Base I/O Address: 300 + Memory Base Address: D0000 + Optimization: DOS Client + Transmission Mode: Half-duplex + BootProm: None + Media Type: Autodetect (3-media cards) or + 10BASE-T (10BASE-T only adapter) + +You should only change the default configuration settings if conflicts with +another adapter exists. To change the adapter's configuration, run the +CS8900/20 Setup Utility. + + +2.2. CS8920-based Adapter Configuration +--------------------------------------- + +CS8920-based adapters are shipped from Cirrus Logic configured as Plug +and Play (PnP) enabled. However, since the cs89x0 driver does NOT +support PnP, you must install the CS8920 adapter in a DOS-based PC and +run the CS8900/20 Setup Utility to disable PnP and configure the +adapter before installation in the target Linux system. Failure to do +this will leave the adapter inactive and the driver will be unable to +communicate with the adapter. + +:: + + **************************************************************** + * CS8920-BASED ADAPTERS: * + * * + * CS8920-BASED ADAPTERS ARE PLUG and PLAY ENABLED BY DEFAULT. * + * THE CS89X0 DRIVER DOES NOT SUPPORT PnP. THEREFORE, YOU MUST * + * RUN THE CS8900/20 SETUP UTILITY TO DISABLE PnP SUPPORT AND * + * TO ACTIVATE THE ADAPTER. * + **************************************************************** + + + + +3. Loading the Driver as a Module +================================= + +If the driver is compiled as a loadable module, you can load the driver module +with the 'modprobe' command. Many of the adapter's configuration parameters can +be specified as command-line arguments to the load command. This facility +provides a means to override the EEPROM's settings or for interface +configuration when an EEPROM is not used. + +Example:: + + insmod cs89x0.o io=0x200 irq=0xA media=aui + +This example loads the module and configures the adapter to use an IO port base +address of 200h, interrupt 10, and use the AUI media connection. The following +configuration options are available on the command line:: + + io=### - specify IO address (200h-360h) + irq=## - specify interrupt level + use_dma=1 - Enable DMA + dma=# - specify dma channel (Driver is compiled to support + Rx DMA only) + dmasize=# (16 or 64) - DMA size 16K or 64K. Default value is set to 16. + media=rj45 - specify media type + or media=bnc + or media=aui + or media=auto + duplex=full - specify forced half/full/autonegotiate duplex + or duplex=half + or duplex=auto + debug=# - debug level (only available if the driver was compiled + for debugging) + +**Notes:** + +a) If an EEPROM is present, any specified command-line parameter + will override the corresponding configuration value stored in + EEPROM. + +b) The "io" parameter must be specified on the command-line. + +c) The driver's hardware probe routine is designed to avoid + writing to I/O space until it knows that there is a cs89x0 + card at the written addresses. This could cause problems + with device probing. To avoid this behaviour, add one + to the ``io=`` module parameter. This doesn't actually change + the I/O address, but it is a flag to tell the driver + to partially initialise the hardware before trying to + identify the card. This could be dangerous if you are + not sure that there is a cs89x0 card at the provided address. + + For example, to scan for an adapter located at IO base 0x300, + specify an IO address of 0x301. + +d) The "duplex=auto" parameter is only supported for the CS8920. + +e) The minimum command-line configuration required if an EEPROM is + not present is: + + io + irq + media type (no autodetect) + +f) The following additional parameters are CS89XX defaults (values + used with no EEPROM or command-line argument). + + * DMA Burst = enabled + * IOCHRDY Enabled = enabled + * UseSA = enabled + * CS8900 defaults to half-duplex if not specified on command-line + * CS8920 defaults to autoneg if not specified on command-line + * Use reset defaults for other config parameters + * dma_mode = 0 + +g) You can use ifconfig to set the adapter's Ethernet address. + +h) Many Linux distributions use the 'modprobe' command to load + modules. This program uses the '/etc/conf.modules' file to + determine configuration information which is passed to a driver + module when it is loaded. All the configuration options which are + described above may be placed within /etc/conf.modules. + + For example:: + + > cat /etc/conf.modules + ... + alias eth0 cs89x0 + options cs89x0 io=0x0200 dma=5 use_dma=1 + ... + + In this example we are telling the module system that the + ethernet driver for this machine should use the cs89x0 driver. We + are asking 'modprobe' to pass the 'io', 'dma' and 'use_dma' + arguments to the driver when it is loaded. + +i) Cirrus recommend that the cs89x0 use the ISA DMA channels 5, 6 or + 7. You will probably find that other DMA channels will not work. + +j) The cs89x0 supports DMA for receiving only. DMA mode is + significantly more efficient. Flooding a 400 MHz Celeron machine + with large ping packets consumes 82% of its CPU capacity in non-DMA + mode. With DMA this is reduced to 45%. + +k) If your Linux kernel was compiled with inbuilt plug-and-play + support you will be able to find information about the cs89x0 card + with the command:: + + cat /proc/isapnp + +l) If during DMA operation you find erratic behavior or network data + corruption you should use your PC's BIOS to slow the EISA bus clock. + +m) If the cs89x0 driver is compiled directly into the kernel + (non-modular) then its I/O address is automatically determined by + ISA bus probing. The IRQ number, media options, etc are determined + from the card's EEPROM. + +n) If the cs89x0 driver is compiled directly into the kernel, DMA + mode may be selected by providing the kernel with a boot option + 'cs89x0_dma=N' where 'N' is the desired DMA channel number (5, 6 or 7). + + Kernel boot options may be provided on the LILO command line:: + + LILO boot: linux cs89x0_dma=5 + + or they may be placed in /etc/lilo.conf:: + + image=/boot/bzImage-2.3.48 + append="cs89x0_dma=5" + label=linux + root=/dev/hda5 + read-only + + The DMA Rx buffer size is hardwired to 16 kbytes in this mode. + (64k mode is not available). + + +4. Compiling the Driver +======================= + +The cs89x0 driver can be compiled directly into the kernel or compiled into +a loadable device driver module. + +Just use the standard way to configure the driver and compile the Kernel. + + +4.1. Compiling the Driver to Support Rx DMA +------------------------------------------- + +The compile-time optionality for DMA was removed in the 2.3 kernel +series. DMA support is now unconditionally part of the driver. It is +enabled by the 'use_dma=1' module option. + + +5. Testing and Troubleshooting +============================== + +5.1. Known Defects and Limitations +---------------------------------- + +Refer to the RELEASE.TXT file distributed as part of this archive for a list of +known defects, driver limitations, and work arounds. + + +5.2. Testing the Adapter +------------------------ + +Once the adapter has been installed and configured, the diagnostic option of +the CS8900/20 Setup Utility can be used to test the functionality of the +adapter and its network connection. Use the diagnostics 'Self Test' option to +test the functionality of the adapter with the hardware configuration you have +assigned. You can use the diagnostics 'Network Test' to test the ability of the +adapter to communicate across the Ethernet with another PC equipped with a +CS8900/20-based adapter card (it must also be running the CS8900/20 Setup +Utility). + +.. note:: + + The Setup Utility's diagnostics are designed to run in a + DOS-only operating system environment. DO NOT run the diagnostics + from a DOS or command prompt session under Windows 95, Windows NT, + OS/2, or other operating system. + +To run the diagnostics tests on the CS8900/20 adapter: + + 1. Boot DOS on the PC and start the CS8900/20 Setup Utility. + + 2. The adapter's current configuration is displayed. Hit the ENTER key to + get to the main menu. + + 4. Select 'Diagnostics' (ALT-G) from the main menu. + * Select 'Self-Test' to test the adapter's basic functionality. + * Select 'Network Test' to test the network connection and cabling. + + +5.2.1. Diagnostic Self-test +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The diagnostic self-test checks the adapter's basic functionality as well as +its ability to communicate across the ISA bus based on the system resources +assigned during hardware configuration. The following tests are performed: + + * IO Register Read/Write Test + + The IO Register Read/Write test insures that the CS8900/20 can be + accessed in IO mode, and that the IO base address is correct. + + * Shared Memory Test + + The Shared Memory test insures the CS8900/20 can be accessed in memory + mode and that the range of memory addresses assigned does not conflict + with other devices in the system. + + * Interrupt Test + + The Interrupt test insures there are no conflicts with the assigned IRQ + signal. + + * EEPROM Test + + The EEPROM test insures the EEPROM can be read. + + * Chip RAM Test + + The Chip RAM test insures the 4K of memory internal to the CS8900/20 is + working properly. + + * Internal Loop-back Test + + The Internal Loop Back test insures the adapter's transmitter and + receiver are operating properly. If this test fails, make sure the + adapter's cable is connected to the network (check for LED activity for + example). + + * Boot PROM Test + + The Boot PROM test insures the Boot PROM is present, and can be read. + Failure indicates the Boot PROM was not successfully read due to a + hardware problem or due to a conflicts on the Boot PROM address + assignment. (Test only applies if the adapter is configured to use the + Boot PROM option.) + +Failure of a test item indicates a possible system resource conflict with +another device on the ISA bus. In this case, you should use the Manual Setup +option to reconfigure the adapter by selecting a different value for the system +resource that failed. + + +5.2.2. Diagnostic Network Test +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The Diagnostic Network Test verifies a working network connection by +transferring data between two CS8900/20 adapters installed in different PCs +on the same network. (Note: the diagnostic network test should not be run +between two nodes across a router.) + +This test requires that each of the two PCs have a CS8900/20-based adapter +installed and have the CS8900/20 Setup Utility running. The first PC is +configured as a Responder and the other PC is configured as an Initiator. +Once the Initiator is started, it sends data frames to the Responder which +returns the frames to the Initiator. + +The total number of frames received and transmitted are displayed on the +Initiator's display, along with a count of the number of frames received and +transmitted OK or in error. The test can be terminated anytime by the user at +either PC. + +To setup the Diagnostic Network Test: + + 1. Select a PC with a CS8900/20-based adapter and a known working network + connection to act as the Responder. Run the CS8900/20 Setup Utility + and select 'Diagnostics -> Network Test -> Responder' from the main + menu. Hit ENTER to start the Responder. + + 2. Return to the PC with the CS8900/20-based adapter you want to test and + start the CS8900/20 Setup Utility. + + 3. From the main menu, Select 'Diagnostic -> Network Test -> Initiator'. + Hit ENTER to start the test. + +You may stop the test on the Initiator at any time while allowing the Responder +to continue running. In this manner, you can move to additional PCs and test +them by starting the Initiator on another PC without having to stop/start the +Responder. + + + +5.3. Using the Adapter's LEDs +----------------------------- + +The 2 and 3-media adapters have two LEDs visible on the back end of the board +located near the 10Base-T connector. + +Link Integrity LED: A "steady" ON of the green LED indicates a valid 10Base-T +connection. (Only applies to 10Base-T. The green LED has no significance for +a 10Base-2 or AUI connection.) + +TX/RX LED: The yellow LED lights briefly each time the adapter transmits or +receives data. (The yellow LED will appear to "flicker" on a typical network.) + + +5.4. Resolving I/O Conflicts +---------------------------- + +An IO conflict occurs when two or more adapter use the same ISA resource (IO +address, memory address or IRQ). You can usually detect an IO conflict in one +of four ways after installing and or configuring the CS8900/20-based adapter: + + 1. The system does not boot properly (or at all). + + 2. The driver cannot communicate with the adapter, reporting an "Adapter + not found" error message. + + 3. You cannot connect to the network or the driver will not load. + + 4. If you have configured the adapter to run in memory mode but the driver + reports it is using IO mode when loading, this is an indication of a + memory address conflict. + +If an IO conflict occurs, run the CS8900/20 Setup Utility and perform a +diagnostic self-test. Normally, the ISA resource in conflict will fail the +self-test. If so, reconfigure the adapter selecting another choice for the +resource in conflict. Run the diagnostics again to check for further IO +conflicts. + +In some cases, such as when the PC will not boot, it may be necessary to remove +the adapter and reconfigure it by installing it in another PC to run the +CS8900/20 Setup Utility. Once reinstalled in the target system, run the +diagnostics self-test to ensure the new configuration is free of conflicts +before loading the driver again. + +When manually configuring the adapter, keep in mind the typical ISA system +resource usage as indicated in the tables below. + +:: + + I/O Address Device IRQ Device + ----------- -------- --- -------- + 200-20F Game I/O adapter 3 COM2, Bus Mouse + 230-23F Bus Mouse 4 COM1 + 270-27F LPT3: third parallel port 5 LPT2 + 2F0-2FF COM2: second serial port 6 Floppy Disk controller + 320-32F Fixed disk controller 7 LPT1 + 8 Real-time Clock + 9 EGA/VGA display adapter + 12 Mouse (PS/2) + Memory Address Device 13 Math Coprocessor + -------------- --------------------- 14 Hard Disk controller + A000-BFFF EGA Graphics Adapter + A000-C7FF VGA Graphics Adapter + B000-BFFF Mono Graphics Adapter + B800-BFFF Color Graphics Adapter + E000-FFFF AT BIOS + + + + +6. Technical Support +==================== + +6.1. Contacting Cirrus Logic's Technical Support +------------------------------------------------ + +Cirrus Logic's CS89XX Technical Application Support can be reached at:: + + Telephone :(800) 888-5016 (from inside U.S. and Canada) + :(512) 442-7555 (from outside the U.S. and Canada) + Fax :(512) 912-3871 + Email :ethernet@crystal.cirrus.com + WWW :http://www.cirrus.com + + +6.2. Information Required before Contacting Technical Support +------------------------------------------------------------- + +Before contacting Cirrus Logic for technical support, be prepared to provide as +Much of the following information as possible. + +1.) Adapter type (CRD8900, CDB8900, CDB8920, etc.) + +2.) Adapter configuration + + * IO Base, Memory Base, IO or memory mode enabled, IRQ, DMA channel + * Plug and Play enabled/disabled (CS8920-based adapters only) + * Configured for media auto-detect or specific media type (which type). + +3.) PC System's Configuration + + * Plug and Play system (yes/no) + * BIOS (make and version) + * System make and model + * CPU (type and speed) + * System RAM + * SCSI Adapter + +4.) Software + + * CS89XX driver and version + * Your network operating system and version + * Your system's OS version + * Version of all protocol support files + +5.) Any Error Message displayed. + + + +6.3 Obtaining the Latest Driver Version +--------------------------------------- + +You can obtain the latest CS89XX drivers and support software from Cirrus Logic's +Web site. You can also contact Cirrus Logic's Technical Support (email: +ethernet@crystal.cirrus.com) and request that you be registered for automatic +software-update notification. + +Cirrus Logic maintains a web page at http://www.cirrus.com with the +latest drivers and technical publications. + + +6.4. Current maintainer +----------------------- + +In February 2000 the maintenance of this driver was assumed by Andrew +Morton. + +6.5 Kernel module parameters +---------------------------- + +For use in embedded environments with no cs89x0 EEPROM, the kernel boot +parameter ``cs89x0_media=`` has been implemented. Usage is:: + + cs89x0_media=rj45 or + cs89x0_media=aui or + cs89x0_media=bnc diff --git a/Documentation/networking/device_drivers/cirrus/cs89x0.txt b/Documentation/networking/device_drivers/cirrus/cs89x0.txt deleted file mode 100644 index 0e190180eec8..000000000000 --- a/Documentation/networking/device_drivers/cirrus/cs89x0.txt +++ /dev/null @@ -1,624 +0,0 @@ - -NOTE ----- - -This document was contributed by Cirrus Logic for kernel 2.2.5. This version -has been updated for 2.3.48 by Andrew Morton. - -Cirrus make a copy of this driver available at their website, as -described below. In general, you should use the driver version which -comes with your Linux distribution. - - - -CIRRUS LOGIC LAN CS8900/CS8920 ETHERNET ADAPTERS -Linux Network Interface Driver ver. 2.00 -=============================================================================== - - -TABLE OF CONTENTS - -1.0 CIRRUS LOGIC LAN CS8900/CS8920 ETHERNET ADAPTERS - 1.1 Product Overview - 1.2 Driver Description - 1.2.1 Driver Name - 1.2.2 File in the Driver Package - 1.3 System Requirements - 1.4 Licensing Information - -2.0 ADAPTER INSTALLATION and CONFIGURATION - 2.1 CS8900-based Adapter Configuration - 2.2 CS8920-based Adapter Configuration - -3.0 LOADING THE DRIVER AS A MODULE - -4.0 COMPILING THE DRIVER - 4.1 Compiling the Driver as a Loadable Module - 4.2 Compiling the driver to support memory mode - 4.3 Compiling the driver to support Rx DMA - -5.0 TESTING AND TROUBLESHOOTING - 5.1 Known Defects and Limitations - 5.2 Testing the Adapter - 5.2.1 Diagnostic Self-Test - 5.2.2 Diagnostic Network Test - 5.3 Using the Adapter's LEDs - 5.4 Resolving I/O Conflicts - -6.0 TECHNICAL SUPPORT - 6.1 Contacting Cirrus Logic's Technical Support - 6.2 Information Required Before Contacting Technical Support - 6.3 Obtaining the Latest Driver Version - 6.4 Current maintainer - 6.5 Kernel boot parameters - - -1.0 CIRRUS LOGIC LAN CS8900/CS8920 ETHERNET ADAPTERS -=============================================================================== - - -1.1 PRODUCT OVERVIEW - -The CS8900-based ISA Ethernet Adapters from Cirrus Logic follow -IEEE 802.3 standards and support half or full-duplex operation in ISA bus -computers on 10 Mbps Ethernet networks. The adapters are designed for operation -in 16-bit ISA or EISA bus expansion slots and are available in -10BaseT-only or 3-media configurations (10BaseT, 10Base2, and AUI for 10Base-5 -or fiber networks). - -CS8920-based adapters are similar to the CS8900-based adapter with additional -features for Plug and Play (PnP) support and Wakeup Frame recognition. As -such, the configuration procedures differ somewhat between the two types of -adapters. Refer to the "Adapter Configuration" section for details on -configuring both types of adapters. - - -1.2 DRIVER DESCRIPTION - -The CS8900/CS8920 Ethernet Adapter driver for Linux supports the Linux -v2.3.48 or greater kernel. It can be compiled directly into the kernel -or loaded at run-time as a device driver module. - -1.2.1 Driver Name: cs89x0 - -1.2.2 Files in the Driver Archive: - -The files in the driver at Cirrus' website include: - - readme.txt - this file - build - batch file to compile cs89x0.c. - cs89x0.c - driver C code - cs89x0.h - driver header file - cs89x0.o - pre-compiled module (for v2.2.5 kernel) - config/Config.in - sample file to include cs89x0 driver in the kernel. - config/Makefile - sample file to include cs89x0 driver in the kernel. - config/Space.c - sample file to include cs89x0 driver in the kernel. - - - -1.3 SYSTEM REQUIREMENTS - -The following hardware is required: - - * Cirrus Logic LAN (CS8900/20-based) Ethernet ISA Adapter - - * IBM or IBM-compatible PC with: - * An 80386 or higher processor - * 16 bytes of contiguous IO space available between 210h - 370h - * One available IRQ (5,10,11,or 12 for the CS8900, 3-7,9-15 for CS8920). - - * Appropriate cable (and connector for AUI, 10BASE-2) for your network - topology. - -The following software is required: - -* LINUX kernel version 2.3.48 or higher - - * CS8900/20 Setup Utility (DOS-based) - - * LINUX kernel sources for your kernel (if compiling into kernel) - - * GNU Toolkit (gcc and make) v2.6 or above (if compiling into kernel - or a module) - - - -1.4 LICENSING INFORMATION - -This program is free software; you can redistribute it and/or modify it under -the terms of the GNU General Public License as published by the Free Software -Foundation, version 1. - -This program is distributed in the hope that it will be useful, but WITHOUT -ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or -FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for -more details. - -For a full copy of the GNU General Public License, write to the Free Software -Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. - - - -2.0 ADAPTER INSTALLATION and CONFIGURATION -=============================================================================== - -Both the CS8900 and CS8920-based adapters can be configured using parameters -stored in an on-board EEPROM. You must use the DOS-based CS8900/20 Setup -Utility if you want to change the adapter's configuration in EEPROM. - -When loading the driver as a module, you can specify many of the adapter's -configuration parameters on the command-line to override the EEPROM's settings -or for interface configuration when an EEPROM is not used. (CS8920-based -adapters must use an EEPROM.) See Section 3.0 LOADING THE DRIVER AS A MODULE. - -Since the CS8900/20 Setup Utility is a DOS-based application, you must install -and configure the adapter in a DOS-based system using the CS8900/20 Setup -Utility before installation in the target LINUX system. (Not required if -installing a CS8900-based adapter and the default configuration is acceptable.) - - -2.1 CS8900-BASED ADAPTER CONFIGURATION - -CS8900-based adapters shipped from Cirrus Logic have been configured -with the following "default" settings: - - Operation Mode: Memory Mode - IRQ: 10 - Base I/O Address: 300 - Memory Base Address: D0000 - Optimization: DOS Client - Transmission Mode: Half-duplex - BootProm: None - Media Type: Autodetect (3-media cards) or - 10BASE-T (10BASE-T only adapter) - -You should only change the default configuration settings if conflicts with -another adapter exists. To change the adapter's configuration, run the -CS8900/20 Setup Utility. - - -2.2 CS8920-BASED ADAPTER CONFIGURATION - -CS8920-based adapters are shipped from Cirrus Logic configured as Plug -and Play (PnP) enabled. However, since the cs89x0 driver does NOT -support PnP, you must install the CS8920 adapter in a DOS-based PC and -run the CS8900/20 Setup Utility to disable PnP and configure the -adapter before installation in the target Linux system. Failure to do -this will leave the adapter inactive and the driver will be unable to -communicate with the adapter. - - - **************************************************************** - * CS8920-BASED ADAPTERS: * - * * - * CS8920-BASED ADAPTERS ARE PLUG and PLAY ENABLED BY DEFAULT. * - * THE CS89X0 DRIVER DOES NOT SUPPORT PnP. THEREFORE, YOU MUST * - * RUN THE CS8900/20 SETUP UTILITY TO DISABLE PnP SUPPORT AND * - * TO ACTIVATE THE ADAPTER. * - **************************************************************** - - - - -3.0 LOADING THE DRIVER AS A MODULE -=============================================================================== - -If the driver is compiled as a loadable module, you can load the driver module -with the 'modprobe' command. Many of the adapter's configuration parameters can -be specified as command-line arguments to the load command. This facility -provides a means to override the EEPROM's settings or for interface -configuration when an EEPROM is not used. - -Example: - - insmod cs89x0.o io=0x200 irq=0xA media=aui - -This example loads the module and configures the adapter to use an IO port base -address of 200h, interrupt 10, and use the AUI media connection. The following -configuration options are available on the command line: - -* io=### - specify IO address (200h-360h) -* irq=## - specify interrupt level -* use_dma=1 - Enable DMA -* dma=# - specify dma channel (Driver is compiled to support - Rx DMA only) -* dmasize=# (16 or 64) - DMA size 16K or 64K. Default value is set to 16. -* media=rj45 - specify media type - or media=bnc - or media=aui - or media=auto -* duplex=full - specify forced half/full/autonegotiate duplex - or duplex=half - or duplex=auto -* debug=# - debug level (only available if the driver was compiled - for debugging) - -NOTES: - -a) If an EEPROM is present, any specified command-line parameter - will override the corresponding configuration value stored in - EEPROM. - -b) The "io" parameter must be specified on the command-line. - -c) The driver's hardware probe routine is designed to avoid - writing to I/O space until it knows that there is a cs89x0 - card at the written addresses. This could cause problems - with device probing. To avoid this behaviour, add one - to the `io=' module parameter. This doesn't actually change - the I/O address, but it is a flag to tell the driver - to partially initialise the hardware before trying to - identify the card. This could be dangerous if you are - not sure that there is a cs89x0 card at the provided address. - - For example, to scan for an adapter located at IO base 0x300, - specify an IO address of 0x301. - -d) The "duplex=auto" parameter is only supported for the CS8920. - -e) The minimum command-line configuration required if an EEPROM is - not present is: - - io - irq - media type (no autodetect) - -f) The following additional parameters are CS89XX defaults (values - used with no EEPROM or command-line argument). - - * DMA Burst = enabled - * IOCHRDY Enabled = enabled - * UseSA = enabled - * CS8900 defaults to half-duplex if not specified on command-line - * CS8920 defaults to autoneg if not specified on command-line - * Use reset defaults for other config parameters - * dma_mode = 0 - -g) You can use ifconfig to set the adapter's Ethernet address. - -h) Many Linux distributions use the 'modprobe' command to load - modules. This program uses the '/etc/conf.modules' file to - determine configuration information which is passed to a driver - module when it is loaded. All the configuration options which are - described above may be placed within /etc/conf.modules. - - For example: - - > cat /etc/conf.modules - ... - alias eth0 cs89x0 - options cs89x0 io=0x0200 dma=5 use_dma=1 - ... - - In this example we are telling the module system that the - ethernet driver for this machine should use the cs89x0 driver. We - are asking 'modprobe' to pass the 'io', 'dma' and 'use_dma' - arguments to the driver when it is loaded. - -i) Cirrus recommend that the cs89x0 use the ISA DMA channels 5, 6 or - 7. You will probably find that other DMA channels will not work. - -j) The cs89x0 supports DMA for receiving only. DMA mode is - significantly more efficient. Flooding a 400 MHz Celeron machine - with large ping packets consumes 82% of its CPU capacity in non-DMA - mode. With DMA this is reduced to 45%. - -k) If your Linux kernel was compiled with inbuilt plug-and-play - support you will be able to find information about the cs89x0 card - with the command - - cat /proc/isapnp - -l) If during DMA operation you find erratic behavior or network data - corruption you should use your PC's BIOS to slow the EISA bus clock. - -m) If the cs89x0 driver is compiled directly into the kernel - (non-modular) then its I/O address is automatically determined by - ISA bus probing. The IRQ number, media options, etc are determined - from the card's EEPROM. - -n) If the cs89x0 driver is compiled directly into the kernel, DMA - mode may be selected by providing the kernel with a boot option - 'cs89x0_dma=N' where 'N' is the desired DMA channel number (5, 6 or 7). - - Kernel boot options may be provided on the LILO command line: - - LILO boot: linux cs89x0_dma=5 - - or they may be placed in /etc/lilo.conf: - - image=/boot/bzImage-2.3.48 - append="cs89x0_dma=5" - label=linux - root=/dev/hda5 - read-only - - The DMA Rx buffer size is hardwired to 16 kbytes in this mode. - (64k mode is not available). - - -4.0 COMPILING THE DRIVER -=============================================================================== - -The cs89x0 driver can be compiled directly into the kernel or compiled into -a loadable device driver module. - - -4.1 COMPILING THE DRIVER AS A LOADABLE MODULE - -To compile the driver into a loadable module, use the following command -(single command line, without quotes): - -"gcc -D__KERNEL__ -I/usr/src/linux/include -I/usr/src/linux/net/inet -Wall --Wstrict-prototypes -O2 -fomit-frame-pointer -DMODULE -DCONFIG_MODVERSIONS --c cs89x0.c" - -4.2 COMPILING THE DRIVER TO SUPPORT MEMORY MODE - -Support for memory mode was not carried over into the 2.3 series kernels. - -4.3 COMPILING THE DRIVER TO SUPPORT Rx DMA - -The compile-time optionality for DMA was removed in the 2.3 kernel -series. DMA support is now unconditionally part of the driver. It is -enabled by the 'use_dma=1' module option. - - -5.0 TESTING AND TROUBLESHOOTING -=============================================================================== - -5.1 KNOWN DEFECTS and LIMITATIONS - -Refer to the RELEASE.TXT file distributed as part of this archive for a list of -known defects, driver limitations, and work arounds. - - -5.2 TESTING THE ADAPTER - -Once the adapter has been installed and configured, the diagnostic option of -the CS8900/20 Setup Utility can be used to test the functionality of the -adapter and its network connection. Use the diagnostics 'Self Test' option to -test the functionality of the adapter with the hardware configuration you have -assigned. You can use the diagnostics 'Network Test' to test the ability of the -adapter to communicate across the Ethernet with another PC equipped with a -CS8900/20-based adapter card (it must also be running the CS8900/20 Setup -Utility). - - NOTE: The Setup Utility's diagnostics are designed to run in a - DOS-only operating system environment. DO NOT run the diagnostics - from a DOS or command prompt session under Windows 95, Windows NT, - OS/2, or other operating system. - -To run the diagnostics tests on the CS8900/20 adapter: - - 1.) Boot DOS on the PC and start the CS8900/20 Setup Utility. - - 2.) The adapter's current configuration is displayed. Hit the ENTER key to - get to the main menu. - - 4.) Select 'Diagnostics' (ALT-G) from the main menu. - * Select 'Self-Test' to test the adapter's basic functionality. - * Select 'Network Test' to test the network connection and cabling. - - -5.2.1 DIAGNOSTIC SELF-TEST - -The diagnostic self-test checks the adapter's basic functionality as well as -its ability to communicate across the ISA bus based on the system resources -assigned during hardware configuration. The following tests are performed: - - * IO Register Read/Write Test - The IO Register Read/Write test insures that the CS8900/20 can be - accessed in IO mode, and that the IO base address is correct. - - * Shared Memory Test - The Shared Memory test insures the CS8900/20 can be accessed in memory - mode and that the range of memory addresses assigned does not conflict - with other devices in the system. - - * Interrupt Test - The Interrupt test insures there are no conflicts with the assigned IRQ - signal. - - * EEPROM Test - The EEPROM test insures the EEPROM can be read. - - * Chip RAM Test - The Chip RAM test insures the 4K of memory internal to the CS8900/20 is - working properly. - - * Internal Loop-back Test - The Internal Loop Back test insures the adapter's transmitter and - receiver are operating properly. If this test fails, make sure the - adapter's cable is connected to the network (check for LED activity for - example). - - * Boot PROM Test - The Boot PROM test insures the Boot PROM is present, and can be read. - Failure indicates the Boot PROM was not successfully read due to a - hardware problem or due to a conflicts on the Boot PROM address - assignment. (Test only applies if the adapter is configured to use the - Boot PROM option.) - -Failure of a test item indicates a possible system resource conflict with -another device on the ISA bus. In this case, you should use the Manual Setup -option to reconfigure the adapter by selecting a different value for the system -resource that failed. - - -5.2.2 DIAGNOSTIC NETWORK TEST - -The Diagnostic Network Test verifies a working network connection by -transferring data between two CS8900/20 adapters installed in different PCs -on the same network. (Note: the diagnostic network test should not be run -between two nodes across a router.) - -This test requires that each of the two PCs have a CS8900/20-based adapter -installed and have the CS8900/20 Setup Utility running. The first PC is -configured as a Responder and the other PC is configured as an Initiator. -Once the Initiator is started, it sends data frames to the Responder which -returns the frames to the Initiator. - -The total number of frames received and transmitted are displayed on the -Initiator's display, along with a count of the number of frames received and -transmitted OK or in error. The test can be terminated anytime by the user at -either PC. - -To setup the Diagnostic Network Test: - - 1.) Select a PC with a CS8900/20-based adapter and a known working network - connection to act as the Responder. Run the CS8900/20 Setup Utility - and select 'Diagnostics -> Network Test -> Responder' from the main - menu. Hit ENTER to start the Responder. - - 2.) Return to the PC with the CS8900/20-based adapter you want to test and - start the CS8900/20 Setup Utility. - - 3.) From the main menu, Select 'Diagnostic -> Network Test -> Initiator'. - Hit ENTER to start the test. - -You may stop the test on the Initiator at any time while allowing the Responder -to continue running. In this manner, you can move to additional PCs and test -them by starting the Initiator on another PC without having to stop/start the -Responder. - - - -5.3 USING THE ADAPTER'S LEDs - -The 2 and 3-media adapters have two LEDs visible on the back end of the board -located near the 10Base-T connector. - -Link Integrity LED: A "steady" ON of the green LED indicates a valid 10Base-T -connection. (Only applies to 10Base-T. The green LED has no significance for -a 10Base-2 or AUI connection.) - -TX/RX LED: The yellow LED lights briefly each time the adapter transmits or -receives data. (The yellow LED will appear to "flicker" on a typical network.) - - -5.4 RESOLVING I/O CONFLICTS - -An IO conflict occurs when two or more adapter use the same ISA resource (IO -address, memory address or IRQ). You can usually detect an IO conflict in one -of four ways after installing and or configuring the CS8900/20-based adapter: - - 1.) The system does not boot properly (or at all). - - 2.) The driver cannot communicate with the adapter, reporting an "Adapter - not found" error message. - - 3.) You cannot connect to the network or the driver will not load. - - 4.) If you have configured the adapter to run in memory mode but the driver - reports it is using IO mode when loading, this is an indication of a - memory address conflict. - -If an IO conflict occurs, run the CS8900/20 Setup Utility and perform a -diagnostic self-test. Normally, the ISA resource in conflict will fail the -self-test. If so, reconfigure the adapter selecting another choice for the -resource in conflict. Run the diagnostics again to check for further IO -conflicts. - -In some cases, such as when the PC will not boot, it may be necessary to remove -the adapter and reconfigure it by installing it in another PC to run the -CS8900/20 Setup Utility. Once reinstalled in the target system, run the -diagnostics self-test to ensure the new configuration is free of conflicts -before loading the driver again. - -When manually configuring the adapter, keep in mind the typical ISA system -resource usage as indicated in the tables below. - -I/O Address Device IRQ Device ------------ -------- --- -------- - 200-20F Game I/O adapter 3 COM2, Bus Mouse - 230-23F Bus Mouse 4 COM1 - 270-27F LPT3: third parallel port 5 LPT2 - 2F0-2FF COM2: second serial port 6 Floppy Disk controller - 320-32F Fixed disk controller 7 LPT1 - 8 Real-time Clock - 9 EGA/VGA display adapter - 12 Mouse (PS/2) -Memory Address Device 13 Math Coprocessor --------------- --------------------- 14 Hard Disk controller -A000-BFFF EGA Graphics Adapter -A000-C7FF VGA Graphics Adapter -B000-BFFF Mono Graphics Adapter -B800-BFFF Color Graphics Adapter -E000-FFFF AT BIOS - - - - -6.0 TECHNICAL SUPPORT -=============================================================================== - -6.1 CONTACTING CIRRUS LOGIC'S TECHNICAL SUPPORT - -Cirrus Logic's CS89XX Technical Application Support can be reached at: - -Telephone :(800) 888-5016 (from inside U.S. and Canada) - :(512) 442-7555 (from outside the U.S. and Canada) -Fax :(512) 912-3871 -Email :ethernet@crystal.cirrus.com -WWW :http://www.cirrus.com - - -6.2 INFORMATION REQUIRED BEFORE CONTACTING TECHNICAL SUPPORT - -Before contacting Cirrus Logic for technical support, be prepared to provide as -Much of the following information as possible. - -1.) Adapter type (CRD8900, CDB8900, CDB8920, etc.) - -2.) Adapter configuration - - * IO Base, Memory Base, IO or memory mode enabled, IRQ, DMA channel - * Plug and Play enabled/disabled (CS8920-based adapters only) - * Configured for media auto-detect or specific media type (which type). - -3.) PC System's Configuration - - * Plug and Play system (yes/no) - * BIOS (make and version) - * System make and model - * CPU (type and speed) - * System RAM - * SCSI Adapter - -4.) Software - - * CS89XX driver and version - * Your network operating system and version - * Your system's OS version - * Version of all protocol support files - -5.) Any Error Message displayed. - - - -6.3 OBTAINING THE LATEST DRIVER VERSION - -You can obtain the latest CS89XX drivers and support software from Cirrus Logic's -Web site. You can also contact Cirrus Logic's Technical Support (email: -ethernet@crystal.cirrus.com) and request that you be registered for automatic -software-update notification. - -Cirrus Logic maintains a web page at http://www.cirrus.com with the -latest drivers and technical publications. - - -6.4 Current maintainer - -In February 2000 the maintenance of this driver was assumed by Andrew -Morton. - -6.5 Kernel module parameters - -For use in embedded environments with no cs89x0 EEPROM, the kernel boot -parameter `cs89x0_media=' has been implemented. Usage is: - - cs89x0_media=rj45 or - cs89x0_media=aui or - cs89x0_media=bnc - diff --git a/Documentation/networking/device_drivers/index.rst b/Documentation/networking/device_drivers/index.rst index 23c4ec9c9125..0b39342e2a1f 100644 --- a/Documentation/networking/device_drivers/index.rst +++ b/Documentation/networking/device_drivers/index.rst @@ -32,6 +32,7 @@ Contents: amazon/ena aquantia/atlantic chelsio/cxgb + cirrus/cs89x0 .. only:: subproject and html diff --git a/drivers/net/ethernet/cirrus/Kconfig b/drivers/net/ethernet/cirrus/Kconfig index 48f3198381bc..8d845f5ee0c5 100644 --- a/drivers/net/ethernet/cirrus/Kconfig +++ b/drivers/net/ethernet/cirrus/Kconfig @@ -24,7 +24,7 @@ config CS89x0 ---help--- Support for CS89x0 chipset based Ethernet cards. If you have a network (Ethernet) card of this type, say Y and read the file - . + . To compile this driver as a module, choose M here. The module will be called cs89x0. -- cgit From e1ddedb5cbd6f8ec2f41874bc06e03023fbd9d99 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 1 May 2020 16:44:40 +0200 Subject: docs: networking: device drivers: convert davicom/dm9000.txt to ReST - add SPDX header; - add a document title; - mark lists as such; - mark tables as such; - mark code blocks and literals as such; - use the right horizontal tag markup; - adjust identation, whitespaces and blank lines where needed; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: David S. Miller --- .../networking/device_drivers/davicom/dm9000.rst | 171 +++++++++++++++++++++ .../networking/device_drivers/davicom/dm9000.txt | 167 -------------------- Documentation/networking/device_drivers/index.rst | 1 + 3 files changed, 172 insertions(+), 167 deletions(-) create mode 100644 Documentation/networking/device_drivers/davicom/dm9000.rst delete mode 100644 Documentation/networking/device_drivers/davicom/dm9000.txt diff --git a/Documentation/networking/device_drivers/davicom/dm9000.rst b/Documentation/networking/device_drivers/davicom/dm9000.rst new file mode 100644 index 000000000000..d5458da01083 --- /dev/null +++ b/Documentation/networking/device_drivers/davicom/dm9000.rst @@ -0,0 +1,171 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===================== +DM9000 Network driver +===================== + +Copyright 2008 Simtec Electronics, + + Ben Dooks + + +Introduction +------------ + +This file describes how to use the DM9000 platform-device based network driver +that is contained in the files drivers/net/dm9000.c and drivers/net/dm9000.h. + +The driver supports three DM9000 variants, the DM9000E which is the first chip +supported as well as the newer DM9000A and DM9000B devices. It is currently +maintained and tested by Ben Dooks, who should be CC: to any patches for this +driver. + + +Defining the platform device +---------------------------- + +The minimum set of resources attached to the platform device are as follows: + + 1) The physical address of the address register + 2) The physical address of the data register + 3) The IRQ line the device's interrupt pin is connected to. + +These resources should be specified in that order, as the ordering of the +two address regions is important (the driver expects these to be address +and then data). + +An example from arch/arm/mach-s3c2410/mach-bast.c is:: + + static struct resource bast_dm9k_resource[] = { + [0] = { + .start = S3C2410_CS5 + BAST_PA_DM9000, + .end = S3C2410_CS5 + BAST_PA_DM9000 + 3, + .flags = IORESOURCE_MEM, + }, + [1] = { + .start = S3C2410_CS5 + BAST_PA_DM9000 + 0x40, + .end = S3C2410_CS5 + BAST_PA_DM9000 + 0x40 + 0x3f, + .flags = IORESOURCE_MEM, + }, + [2] = { + .start = IRQ_DM9000, + .end = IRQ_DM9000, + .flags = IORESOURCE_IRQ | IORESOURCE_IRQ_HIGHLEVEL, + } + }; + + static struct platform_device bast_device_dm9k = { + .name = "dm9000", + .id = 0, + .num_resources = ARRAY_SIZE(bast_dm9k_resource), + .resource = bast_dm9k_resource, + }; + +Note the setting of the IRQ trigger flag in bast_dm9k_resource[2].flags, +as this will generate a warning if it is not present. The trigger from +the flags field will be passed to request_irq() when registering the IRQ +handler to ensure that the IRQ is setup correctly. + +This shows a typical platform device, without the optional configuration +platform data supplied. The next example uses the same resources, but adds +the optional platform data to pass extra configuration data:: + + static struct dm9000_plat_data bast_dm9k_platdata = { + .flags = DM9000_PLATF_16BITONLY, + }; + + static struct platform_device bast_device_dm9k = { + .name = "dm9000", + .id = 0, + .num_resources = ARRAY_SIZE(bast_dm9k_resource), + .resource = bast_dm9k_resource, + .dev = { + .platform_data = &bast_dm9k_platdata, + } + }; + +The platform data is defined in include/linux/dm9000.h and described below. + + +Platform data +------------- + +Extra platform data for the DM9000 can describe the IO bus width to the +device, whether or not an external PHY is attached to the device and +the availability of an external configuration EEPROM. + +The flags for the platform data .flags field are as follows: + +DM9000_PLATF_8BITONLY + + The IO should be done with 8bit operations. + +DM9000_PLATF_16BITONLY + + The IO should be done with 16bit operations. + +DM9000_PLATF_32BITONLY + + The IO should be done with 32bit operations. + +DM9000_PLATF_EXT_PHY + + The chip is connected to an external PHY. + +DM9000_PLATF_NO_EEPROM + + This can be used to signify that the board does not have an + EEPROM, or that the EEPROM should be hidden from the user. + +DM9000_PLATF_SIMPLE_PHY + + Switch to using the simpler PHY polling method which does not + try and read the MII PHY state regularly. This is only available + when using the internal PHY. See the section on link state polling + for more information. + + The config symbol DM9000_FORCE_SIMPLE_PHY_POLL, Kconfig entry + "Force simple NSR based PHY polling" allows this flag to be + forced on at build time. + + +PHY Link state polling +---------------------- + +The driver keeps track of the link state and informs the network core +about link (carrier) availability. This is managed by several methods +depending on the version of the chip and on which PHY is being used. + +For the internal PHY, the original (and currently default) method is +to read the MII state, either when the status changes if we have the +necessary interrupt support in the chip or every two seconds via a +periodic timer. + +To reduce the overhead for the internal PHY, there is now the option +of using the DM9000_FORCE_SIMPLE_PHY_POLL config, or DM9000_PLATF_SIMPLE_PHY +platform data option to read the summary information without the +expensive MII accesses. This method is faster, but does not print +as much information. + +When using an external PHY, the driver currently has to poll the MII +link status as there is no method for getting an interrupt on link change. + + +DM9000A / DM9000B +----------------- + +These chips are functionally similar to the DM9000E and are supported easily +by the same driver. The features are: + + 1) Interrupt on internal PHY state change. This means that the periodic + polling of the PHY status may be disabled on these devices when using + the internal PHY. + + 2) TCP/UDP checksum offloading, which the driver does not currently support. + + +ethtool +------- + +The driver supports the ethtool interface for access to the driver +state information, the PHY state and the EEPROM. diff --git a/Documentation/networking/device_drivers/davicom/dm9000.txt b/Documentation/networking/device_drivers/davicom/dm9000.txt deleted file mode 100644 index 5552e2e575c5..000000000000 --- a/Documentation/networking/device_drivers/davicom/dm9000.txt +++ /dev/null @@ -1,167 +0,0 @@ -DM9000 Network driver -===================== - -Copyright 2008 Simtec Electronics, - Ben Dooks - - -Introduction ------------- - -This file describes how to use the DM9000 platform-device based network driver -that is contained in the files drivers/net/dm9000.c and drivers/net/dm9000.h. - -The driver supports three DM9000 variants, the DM9000E which is the first chip -supported as well as the newer DM9000A and DM9000B devices. It is currently -maintained and tested by Ben Dooks, who should be CC: to any patches for this -driver. - - -Defining the platform device ----------------------------- - -The minimum set of resources attached to the platform device are as follows: - - 1) The physical address of the address register - 2) The physical address of the data register - 3) The IRQ line the device's interrupt pin is connected to. - -These resources should be specified in that order, as the ordering of the -two address regions is important (the driver expects these to be address -and then data). - -An example from arch/arm/mach-s3c2410/mach-bast.c is: - -static struct resource bast_dm9k_resource[] = { - [0] = { - .start = S3C2410_CS5 + BAST_PA_DM9000, - .end = S3C2410_CS5 + BAST_PA_DM9000 + 3, - .flags = IORESOURCE_MEM, - }, - [1] = { - .start = S3C2410_CS5 + BAST_PA_DM9000 + 0x40, - .end = S3C2410_CS5 + BAST_PA_DM9000 + 0x40 + 0x3f, - .flags = IORESOURCE_MEM, - }, - [2] = { - .start = IRQ_DM9000, - .end = IRQ_DM9000, - .flags = IORESOURCE_IRQ | IORESOURCE_IRQ_HIGHLEVEL, - } -}; - -static struct platform_device bast_device_dm9k = { - .name = "dm9000", - .id = 0, - .num_resources = ARRAY_SIZE(bast_dm9k_resource), - .resource = bast_dm9k_resource, -}; - -Note the setting of the IRQ trigger flag in bast_dm9k_resource[2].flags, -as this will generate a warning if it is not present. The trigger from -the flags field will be passed to request_irq() when registering the IRQ -handler to ensure that the IRQ is setup correctly. - -This shows a typical platform device, without the optional configuration -platform data supplied. The next example uses the same resources, but adds -the optional platform data to pass extra configuration data: - -static struct dm9000_plat_data bast_dm9k_platdata = { - .flags = DM9000_PLATF_16BITONLY, -}; - -static struct platform_device bast_device_dm9k = { - .name = "dm9000", - .id = 0, - .num_resources = ARRAY_SIZE(bast_dm9k_resource), - .resource = bast_dm9k_resource, - .dev = { - .platform_data = &bast_dm9k_platdata, - } -}; - -The platform data is defined in include/linux/dm9000.h and described below. - - -Platform data -------------- - -Extra platform data for the DM9000 can describe the IO bus width to the -device, whether or not an external PHY is attached to the device and -the availability of an external configuration EEPROM. - -The flags for the platform data .flags field are as follows: - -DM9000_PLATF_8BITONLY - - The IO should be done with 8bit operations. - -DM9000_PLATF_16BITONLY - - The IO should be done with 16bit operations. - -DM9000_PLATF_32BITONLY - - The IO should be done with 32bit operations. - -DM9000_PLATF_EXT_PHY - - The chip is connected to an external PHY. - -DM9000_PLATF_NO_EEPROM - - This can be used to signify that the board does not have an - EEPROM, or that the EEPROM should be hidden from the user. - -DM9000_PLATF_SIMPLE_PHY - - Switch to using the simpler PHY polling method which does not - try and read the MII PHY state regularly. This is only available - when using the internal PHY. See the section on link state polling - for more information. - - The config symbol DM9000_FORCE_SIMPLE_PHY_POLL, Kconfig entry - "Force simple NSR based PHY polling" allows this flag to be - forced on at build time. - - -PHY Link state polling ----------------------- - -The driver keeps track of the link state and informs the network core -about link (carrier) availability. This is managed by several methods -depending on the version of the chip and on which PHY is being used. - -For the internal PHY, the original (and currently default) method is -to read the MII state, either when the status changes if we have the -necessary interrupt support in the chip or every two seconds via a -periodic timer. - -To reduce the overhead for the internal PHY, there is now the option -of using the DM9000_FORCE_SIMPLE_PHY_POLL config, or DM9000_PLATF_SIMPLE_PHY -platform data option to read the summary information without the -expensive MII accesses. This method is faster, but does not print -as much information. - -When using an external PHY, the driver currently has to poll the MII -link status as there is no method for getting an interrupt on link change. - - -DM9000A / DM9000B ------------------ - -These chips are functionally similar to the DM9000E and are supported easily -by the same driver. The features are: - - 1) Interrupt on internal PHY state change. This means that the periodic - polling of the PHY status may be disabled on these devices when using - the internal PHY. - - 2) TCP/UDP checksum offloading, which the driver does not currently support. - - -ethtool -------- - -The driver supports the ethtool interface for access to the driver -state information, the PHY state and the EEPROM. diff --git a/Documentation/networking/device_drivers/index.rst b/Documentation/networking/device_drivers/index.rst index 0b39342e2a1f..e8db57fef2e9 100644 --- a/Documentation/networking/device_drivers/index.rst +++ b/Documentation/networking/device_drivers/index.rst @@ -33,6 +33,7 @@ Contents: aquantia/atlantic chelsio/cxgb cirrus/cs89x0 + davicom/dm9000 .. only:: subproject and html -- cgit From b6671d71ca811aed02f136a6cd812a542f88c483 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 1 May 2020 16:44:41 +0200 Subject: docs: networking: device drivers: convert dec/de4x5.txt to ReST - add SPDX header; - add a document title; - mark code blocks and literals as such; - adjust identation, whitespaces and blank lines where needed; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: David S. Miller --- .../networking/device_drivers/dec/de4x5.rst | 189 +++++++++++++++++++++ .../networking/device_drivers/dec/de4x5.txt | 178 ------------------- Documentation/networking/device_drivers/index.rst | 1 + drivers/net/ethernet/dec/tulip/Kconfig | 2 +- 4 files changed, 191 insertions(+), 179 deletions(-) create mode 100644 Documentation/networking/device_drivers/dec/de4x5.rst delete mode 100644 Documentation/networking/device_drivers/dec/de4x5.txt diff --git a/Documentation/networking/device_drivers/dec/de4x5.rst b/Documentation/networking/device_drivers/dec/de4x5.rst new file mode 100644 index 000000000000..e03e9c631879 --- /dev/null +++ b/Documentation/networking/device_drivers/dec/de4x5.rst @@ -0,0 +1,189 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=================================== +DEC EtherWORKS Ethernet De4x5 cards +=================================== + + Originally, this driver was written for the Digital Equipment + Corporation series of EtherWORKS Ethernet cards: + + - DE425 TP/COAX EISA + - DE434 TP PCI + - DE435 TP/COAX/AUI PCI + - DE450 TP/COAX/AUI PCI + - DE500 10/100 PCI Fasternet + + but it will now attempt to support all cards which conform to the + Digital Semiconductor SROM Specification. The driver currently + recognises the following chips: + + - DC21040 (no SROM) + - DC21041[A] + - DC21140[A] + - DC21142 + - DC21143 + + So far the driver is known to work with the following cards: + + - KINGSTON + - Linksys + - ZNYX342 + - SMC8432 + - SMC9332 (w/new SROM) + - ZNYX31[45] + - ZNYX346 10/100 4 port (can act as a 10/100 bridge!) + + The driver has been tested on a relatively busy network using the DE425, + DE434, DE435 and DE500 cards and benchmarked with 'ttcp': it transferred + 16M of data to a DECstation 5000/200 as follows:: + + TCP UDP + TX RX TX RX + DE425 1030k 997k 1170k 1128k + DE434 1063k 995k 1170k 1125k + DE435 1063k 995k 1170k 1125k + DE500 1063k 998k 1170k 1125k in 10Mb/s mode + + All values are typical (in kBytes/sec) from a sample of 4 for each + measurement. Their error is +/-20k on a quiet (private) network and also + depend on what load the CPU has. + +---------------------------------------------------------------------------- + + The ability to load this driver as a loadable module has been included + and used extensively during the driver development (to save those long + reboot sequences). Loadable module support under PCI and EISA has been + achieved by letting the driver autoprobe as if it were compiled into the + kernel. Do make sure you're not sharing interrupts with anything that + cannot accommodate interrupt sharing! + + To utilise this ability, you have to do 8 things: + + 0) have a copy of the loadable modules code installed on your system. + 1) copy de4x5.c from the /linux/drivers/net directory to your favourite + temporary directory. + 2) for fixed autoprobes (not recommended), edit the source code near + line 5594 to reflect the I/O address you're using, or assign these when + loading by:: + + insmod de4x5 io=0xghh where g = bus number + hh = device number + + .. note:: + + autoprobing for modules is now supported by default. You may just + use:: + + insmod de4x5 + + to load all available boards. For a specific board, still use + the 'io=?' above. + 3) compile de4x5.c, but include -DMODULE in the command line to ensure + that the correct bits are compiled (see end of source code). + 4) if you are wanting to add a new card, goto 5. Otherwise, recompile a + kernel with the de4x5 configuration turned off and reboot. + 5) insmod de4x5 [io=0xghh] + 6) run the net startup bits for your new eth?? interface(s) manually + (usually /etc/rc.inet[12] at boot time). + 7) enjoy! + + To unload a module, turn off the associated interface(s) + 'ifconfig eth?? down' then 'rmmod de4x5'. + + Automedia detection is included so that in principle you can disconnect + from, e.g. TP, reconnect to BNC and things will still work (after a + pause while the driver figures out where its media went). My tests + using ping showed that it appears to work.... + + By default, the driver will now autodetect any DECchip based card. + Should you have a need to restrict the driver to DIGITAL only cards, you + can compile with a DEC_ONLY define, or if loading as a module, use the + 'dec_only=1' parameter. + + I've changed the timing routines to use the kernel timer and scheduling + functions so that the hangs and other assorted problems that occurred + while autosensing the media should be gone. A bonus for the DC21040 + auto media sense algorithm is that it can now use one that is more in + line with the rest (the DC21040 chip doesn't have a hardware timer). + The downside is the 1 'jiffies' (10ms) resolution. + + IEEE 802.3u MII interface code has been added in anticipation that some + products may use it in the future. + + The SMC9332 card has a non-compliant SROM which needs fixing - I have + patched this driver to detect it because the SROM format used complies + to a previous DEC-STD format. + + I have removed the buffer copies needed for receive on Intels. I cannot + remove them for Alphas since the Tulip hardware only does longword + aligned DMA transfers and the Alphas get alignment traps with non + longword aligned data copies (which makes them really slow). No comment. + + I have added SROM decoding routines to make this driver work with any + card that supports the Digital Semiconductor SROM spec. This will help + all cards running the dc2114x series chips in particular. Cards using + the dc2104x chips should run correctly with the basic driver. I'm in + debt to for the testing and feedback that helped get + this feature working. So far we have tested KINGSTON, SMC8432, SMC9332 + (with the latest SROM complying with the SROM spec V3: their first was + broken), ZNYX342 and LinkSys. ZNYX314 (dual 21041 MAC) and ZNYX 315 + (quad 21041 MAC) cards also appear to work despite their incorrectly + wired IRQs. + + I have added a temporary fix for interrupt problems when some SCSI cards + share the same interrupt as the DECchip based cards. The problem occurs + because the SCSI card wants to grab the interrupt as a fast interrupt + (runs the service routine with interrupts turned off) vs. this card + which really needs to run the service routine with interrupts turned on. + This driver will now add the interrupt service routine as a fast + interrupt if it is bounced from the slow interrupt. THIS IS NOT A + RECOMMENDED WAY TO RUN THE DRIVER and has been done for a limited time + until people sort out their compatibility issues and the kernel + interrupt service code is fixed. YOU SHOULD SEPARATE OUT THE FAST + INTERRUPT CARDS FROM THE SLOW INTERRUPT CARDS to ensure that they do not + run on the same interrupt. PCMCIA/CardBus is another can of worms... + + Finally, I think I have really fixed the module loading problem with + more than one DECchip based card. As a side effect, I don't mess with + the device structure any more which means that if more than 1 card in + 2.0.x is installed (4 in 2.1.x), the user will have to edit + linux/drivers/net/Space.c to make room for them. Hence, module loading + is the preferred way to use this driver, since it doesn't have this + limitation. + + Where SROM media detection is used and full duplex is specified in the + SROM, the feature is ignored unless lp->params.fdx is set at compile + time OR during a module load (insmod de4x5 args='eth??:fdx' [see + below]). This is because there is no way to automatically detect full + duplex links except through autonegotiation. When I include the + autonegotiation feature in the SROM autoconf code, this detection will + occur automatically for that case. + + Command line arguments are now allowed, similar to passing arguments + through LILO. This will allow a per adapter board set up of full duplex + and media. The only lexical constraints are: the board name (dev->name) + appears in the list before its parameters. The list of parameters ends + either at the end of the parameter list or with another board name. The + following parameters are allowed: + + ========= =============================================== + fdx for full duplex + autosense to set the media/speed; with the following + sub-parameters: + TP, TP_NW, BNC, AUI, BNC_AUI, 100Mb, 10Mb, AUTO + ========= =============================================== + + Case sensitivity is important for the sub-parameters. They *must* be + upper case. Examples:: + + insmod de4x5 args='eth1:fdx autosense=BNC eth0:autosense=100Mb'. + + For a compiled in driver, in linux/drivers/net/CONFIG, place e.g.:: + + DE4X5_OPTS = -DDE4X5_PARM='"eth0:fdx autosense=AUI eth2:autosense=TP"' + + Yes, I know full duplex isn't permissible on BNC or AUI; they're just + examples. By default, full duplex is turned off and AUTO is the default + autosense setting. In reality, I expect only the full duplex option to + be used. Note the use of single quotes in the two examples above and the + lack of commas to separate items. diff --git a/Documentation/networking/device_drivers/dec/de4x5.txt b/Documentation/networking/device_drivers/dec/de4x5.txt deleted file mode 100644 index 452aac58341d..000000000000 --- a/Documentation/networking/device_drivers/dec/de4x5.txt +++ /dev/null @@ -1,178 +0,0 @@ - Originally, this driver was written for the Digital Equipment - Corporation series of EtherWORKS Ethernet cards: - - DE425 TP/COAX EISA - DE434 TP PCI - DE435 TP/COAX/AUI PCI - DE450 TP/COAX/AUI PCI - DE500 10/100 PCI Fasternet - - but it will now attempt to support all cards which conform to the - Digital Semiconductor SROM Specification. The driver currently - recognises the following chips: - - DC21040 (no SROM) - DC21041[A] - DC21140[A] - DC21142 - DC21143 - - So far the driver is known to work with the following cards: - - KINGSTON - Linksys - ZNYX342 - SMC8432 - SMC9332 (w/new SROM) - ZNYX31[45] - ZNYX346 10/100 4 port (can act as a 10/100 bridge!) - - The driver has been tested on a relatively busy network using the DE425, - DE434, DE435 and DE500 cards and benchmarked with 'ttcp': it transferred - 16M of data to a DECstation 5000/200 as follows: - - TCP UDP - TX RX TX RX - DE425 1030k 997k 1170k 1128k - DE434 1063k 995k 1170k 1125k - DE435 1063k 995k 1170k 1125k - DE500 1063k 998k 1170k 1125k in 10Mb/s mode - - All values are typical (in kBytes/sec) from a sample of 4 for each - measurement. Their error is +/-20k on a quiet (private) network and also - depend on what load the CPU has. - - ========================================================================= - - The ability to load this driver as a loadable module has been included - and used extensively during the driver development (to save those long - reboot sequences). Loadable module support under PCI and EISA has been - achieved by letting the driver autoprobe as if it were compiled into the - kernel. Do make sure you're not sharing interrupts with anything that - cannot accommodate interrupt sharing! - - To utilise this ability, you have to do 8 things: - - 0) have a copy of the loadable modules code installed on your system. - 1) copy de4x5.c from the /linux/drivers/net directory to your favourite - temporary directory. - 2) for fixed autoprobes (not recommended), edit the source code near - line 5594 to reflect the I/O address you're using, or assign these when - loading by: - - insmod de4x5 io=0xghh where g = bus number - hh = device number - - NB: autoprobing for modules is now supported by default. You may just - use: - - insmod de4x5 - - to load all available boards. For a specific board, still use - the 'io=?' above. - 3) compile de4x5.c, but include -DMODULE in the command line to ensure - that the correct bits are compiled (see end of source code). - 4) if you are wanting to add a new card, goto 5. Otherwise, recompile a - kernel with the de4x5 configuration turned off and reboot. - 5) insmod de4x5 [io=0xghh] - 6) run the net startup bits for your new eth?? interface(s) manually - (usually /etc/rc.inet[12] at boot time). - 7) enjoy! - - To unload a module, turn off the associated interface(s) - 'ifconfig eth?? down' then 'rmmod de4x5'. - - Automedia detection is included so that in principle you can disconnect - from, e.g. TP, reconnect to BNC and things will still work (after a - pause while the driver figures out where its media went). My tests - using ping showed that it appears to work.... - - By default, the driver will now autodetect any DECchip based card. - Should you have a need to restrict the driver to DIGITAL only cards, you - can compile with a DEC_ONLY define, or if loading as a module, use the - 'dec_only=1' parameter. - - I've changed the timing routines to use the kernel timer and scheduling - functions so that the hangs and other assorted problems that occurred - while autosensing the media should be gone. A bonus for the DC21040 - auto media sense algorithm is that it can now use one that is more in - line with the rest (the DC21040 chip doesn't have a hardware timer). - The downside is the 1 'jiffies' (10ms) resolution. - - IEEE 802.3u MII interface code has been added in anticipation that some - products may use it in the future. - - The SMC9332 card has a non-compliant SROM which needs fixing - I have - patched this driver to detect it because the SROM format used complies - to a previous DEC-STD format. - - I have removed the buffer copies needed for receive on Intels. I cannot - remove them for Alphas since the Tulip hardware only does longword - aligned DMA transfers and the Alphas get alignment traps with non - longword aligned data copies (which makes them really slow). No comment. - - I have added SROM decoding routines to make this driver work with any - card that supports the Digital Semiconductor SROM spec. This will help - all cards running the dc2114x series chips in particular. Cards using - the dc2104x chips should run correctly with the basic driver. I'm in - debt to for the testing and feedback that helped get - this feature working. So far we have tested KINGSTON, SMC8432, SMC9332 - (with the latest SROM complying with the SROM spec V3: their first was - broken), ZNYX342 and LinkSys. ZNYX314 (dual 21041 MAC) and ZNYX 315 - (quad 21041 MAC) cards also appear to work despite their incorrectly - wired IRQs. - - I have added a temporary fix for interrupt problems when some SCSI cards - share the same interrupt as the DECchip based cards. The problem occurs - because the SCSI card wants to grab the interrupt as a fast interrupt - (runs the service routine with interrupts turned off) vs. this card - which really needs to run the service routine with interrupts turned on. - This driver will now add the interrupt service routine as a fast - interrupt if it is bounced from the slow interrupt. THIS IS NOT A - RECOMMENDED WAY TO RUN THE DRIVER and has been done for a limited time - until people sort out their compatibility issues and the kernel - interrupt service code is fixed. YOU SHOULD SEPARATE OUT THE FAST - INTERRUPT CARDS FROM THE SLOW INTERRUPT CARDS to ensure that they do not - run on the same interrupt. PCMCIA/CardBus is another can of worms... - - Finally, I think I have really fixed the module loading problem with - more than one DECchip based card. As a side effect, I don't mess with - the device structure any more which means that if more than 1 card in - 2.0.x is installed (4 in 2.1.x), the user will have to edit - linux/drivers/net/Space.c to make room for them. Hence, module loading - is the preferred way to use this driver, since it doesn't have this - limitation. - - Where SROM media detection is used and full duplex is specified in the - SROM, the feature is ignored unless lp->params.fdx is set at compile - time OR during a module load (insmod de4x5 args='eth??:fdx' [see - below]). This is because there is no way to automatically detect full - duplex links except through autonegotiation. When I include the - autonegotiation feature in the SROM autoconf code, this detection will - occur automatically for that case. - - Command line arguments are now allowed, similar to passing arguments - through LILO. This will allow a per adapter board set up of full duplex - and media. The only lexical constraints are: the board name (dev->name) - appears in the list before its parameters. The list of parameters ends - either at the end of the parameter list or with another board name. The - following parameters are allowed: - - fdx for full duplex - autosense to set the media/speed; with the following - sub-parameters: - TP, TP_NW, BNC, AUI, BNC_AUI, 100Mb, 10Mb, AUTO - - Case sensitivity is important for the sub-parameters. They *must* be - upper case. Examples: - - insmod de4x5 args='eth1:fdx autosense=BNC eth0:autosense=100Mb'. - - For a compiled in driver, in linux/drivers/net/CONFIG, place e.g. - DE4X5_OPTS = -DDE4X5_PARM='"eth0:fdx autosense=AUI eth2:autosense=TP"' - - Yes, I know full duplex isn't permissible on BNC or AUI; they're just - examples. By default, full duplex is turned off and AUTO is the default - autosense setting. In reality, I expect only the full duplex option to - be used. Note the use of single quotes in the two examples above and the - lack of commas to separate items. diff --git a/Documentation/networking/device_drivers/index.rst b/Documentation/networking/device_drivers/index.rst index e8db57fef2e9..4ad13ffb5800 100644 --- a/Documentation/networking/device_drivers/index.rst +++ b/Documentation/networking/device_drivers/index.rst @@ -34,6 +34,7 @@ Contents: chelsio/cxgb cirrus/cs89x0 davicom/dm9000 + dec/de4x5 .. only:: subproject and html diff --git a/drivers/net/ethernet/dec/tulip/Kconfig b/drivers/net/ethernet/dec/tulip/Kconfig index 8ce6888ea722..8c4245d94bb2 100644 --- a/drivers/net/ethernet/dec/tulip/Kconfig +++ b/drivers/net/ethernet/dec/tulip/Kconfig @@ -114,7 +114,7 @@ config DE4X5 These include the DE425, DE434, DE435, DE450 and DE500 models. If you have a network card of this type, say Y. More specific information is contained in - . + . To compile this driver as a module, choose M here. The module will be called de4x5. -- cgit From c981977d3a5ce55c96b1b77f42d0a9df0a79244e Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 1 May 2020 16:44:42 +0200 Subject: docs: networking: device drivers: convert dec/dmfe.txt to ReST - add SPDX header; - adjust titles and chapters, adding proper markups; - comment out text-only TOC from html/pdf output; - mark code blocks and literals as such; - mark tables as such; - adjust identation, whitespaces and blank lines where needed; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: David S. Miller --- .../networking/device_drivers/dec/dmfe.rst | 71 ++++++++++++++++++++++ .../networking/device_drivers/dec/dmfe.txt | 66 -------------------- Documentation/networking/device_drivers/index.rst | 1 + MAINTAINERS | 2 +- drivers/net/ethernet/dec/tulip/Kconfig | 2 +- 5 files changed, 74 insertions(+), 68 deletions(-) create mode 100644 Documentation/networking/device_drivers/dec/dmfe.rst delete mode 100644 Documentation/networking/device_drivers/dec/dmfe.txt diff --git a/Documentation/networking/device_drivers/dec/dmfe.rst b/Documentation/networking/device_drivers/dec/dmfe.rst new file mode 100644 index 000000000000..c4cf809cad84 --- /dev/null +++ b/Documentation/networking/device_drivers/dec/dmfe.rst @@ -0,0 +1,71 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================================================== +Davicom DM9102(A)/DM9132/DM9801 fast ethernet driver for Linux +============================================================== + +Note: This driver doesn't have a maintainer. + + +This program is free software; you can redistribute it and/or +modify it under the terms of the GNU General Public License +as published by the Free Software Foundation; either version 2 +of the License, or (at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + + +This driver provides kernel support for Davicom DM9102(A)/DM9132/DM9801 ethernet cards ( CNET +10/100 ethernet cards uses Davicom chipset too, so this driver supports CNET cards too ).If you +didn't compile this driver as a module, it will automatically load itself on boot and print a +line similar to:: + + dmfe: Davicom DM9xxx net driver, version 1.36.4 (2002-01-17) + +If you compiled this driver as a module, you have to load it on boot.You can load it with command:: + + insmod dmfe + +This way it will autodetect the device mode.This is the suggested way to load the module.Or you can pass +a mode= setting to module while loading, like:: + + insmod dmfe mode=0 # Force 10M Half Duplex + insmod dmfe mode=1 # Force 100M Half Duplex + insmod dmfe mode=4 # Force 10M Full Duplex + insmod dmfe mode=5 # Force 100M Full Duplex + +Next you should configure your network interface with a command similar to:: + + ifconfig eth0 172.22.3.18 + ^^^^^^^^^^^ + Your IP Address + +Then you may have to modify the default routing table with command:: + + route add default eth0 + + +Now your ethernet card should be up and running. + + +TODO: + +- Implement pci_driver::suspend() and pci_driver::resume() power management methods. +- Check on 64 bit boxes. +- Check and fix on big endian boxes. +- Test and make sure PCI latency is now correct for all cases. + + +Authors: + +Sten Wang : Original Author + +Contributors: + +- Marcelo Tosatti +- Alan Cox +- Jeff Garzik +- Vojtech Pavlik diff --git a/Documentation/networking/device_drivers/dec/dmfe.txt b/Documentation/networking/device_drivers/dec/dmfe.txt deleted file mode 100644 index 25320bf19c86..000000000000 --- a/Documentation/networking/device_drivers/dec/dmfe.txt +++ /dev/null @@ -1,66 +0,0 @@ -Note: This driver doesn't have a maintainer. - -Davicom DM9102(A)/DM9132/DM9801 fast ethernet driver for Linux. - -This program is free software; you can redistribute it and/or -modify it under the terms of the GNU General Public License -as published by the Free Software Foundation; either version 2 -of the License, or (at your option) any later version. - -This program is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - - -This driver provides kernel support for Davicom DM9102(A)/DM9132/DM9801 ethernet cards ( CNET -10/100 ethernet cards uses Davicom chipset too, so this driver supports CNET cards too ).If you -didn't compile this driver as a module, it will automatically load itself on boot and print a -line similar to : - - dmfe: Davicom DM9xxx net driver, version 1.36.4 (2002-01-17) - -If you compiled this driver as a module, you have to load it on boot.You can load it with command : - - insmod dmfe - -This way it will autodetect the device mode.This is the suggested way to load the module.Or you can pass -a mode= setting to module while loading, like : - - insmod dmfe mode=0 # Force 10M Half Duplex - insmod dmfe mode=1 # Force 100M Half Duplex - insmod dmfe mode=4 # Force 10M Full Duplex - insmod dmfe mode=5 # Force 100M Full Duplex - -Next you should configure your network interface with a command similar to : - - ifconfig eth0 172.22.3.18 - ^^^^^^^^^^^ - Your IP Address - -Then you may have to modify the default routing table with command : - - route add default eth0 - - -Now your ethernet card should be up and running. - - -TODO: - -Implement pci_driver::suspend() and pci_driver::resume() power management methods. -Check on 64 bit boxes. -Check and fix on big endian boxes. -Test and make sure PCI latency is now correct for all cases. - - -Authors: - -Sten Wang : Original Author - -Contributors: - -Marcelo Tosatti -Alan Cox -Jeff Garzik -Vojtech Pavlik diff --git a/Documentation/networking/device_drivers/index.rst b/Documentation/networking/device_drivers/index.rst index 4ad13ffb5800..09728e964ce1 100644 --- a/Documentation/networking/device_drivers/index.rst +++ b/Documentation/networking/device_drivers/index.rst @@ -35,6 +35,7 @@ Contents: cirrus/cs89x0 davicom/dm9000 dec/de4x5 + dec/dmfe .. only:: subproject and html diff --git a/MAINTAINERS b/MAINTAINERS index b5cfee17635e..f0b18c156176 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -4694,7 +4694,7 @@ F: net/ax25/sysctl_net_ax25.c DAVICOM FAST ETHERNET (DMFE) NETWORK DRIVER L: netdev@vger.kernel.org S: Orphan -F: Documentation/networking/device_drivers/dec/dmfe.txt +F: Documentation/networking/device_drivers/dec/dmfe.rst F: drivers/net/ethernet/dec/tulip/dmfe.c DC390/AM53C974 SCSI driver diff --git a/drivers/net/ethernet/dec/tulip/Kconfig b/drivers/net/ethernet/dec/tulip/Kconfig index 8c4245d94bb2..177f36f4b89d 100644 --- a/drivers/net/ethernet/dec/tulip/Kconfig +++ b/drivers/net/ethernet/dec/tulip/Kconfig @@ -138,7 +138,7 @@ config DM9102 This driver is for DM9102(A)/DM9132/DM9801 compatible PCI cards from Davicom (). If you have such a network (Ethernet) card, say Y. Some information is contained in the file - . + . To compile this driver as a module, choose M here. The module will be called dmfe. -- cgit From ca705e4793f024afb8e86030e08b1e0f16dcc07c Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 1 May 2020 16:44:43 +0200 Subject: docs: networking: device drivers: convert dlink/dl2k.txt to ReST - add SPDX header; - mark code blocks and literals as such; - mark lists as such; - adjust identation, whitespaces and blank lines where needed; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: David S. Miller --- .../networking/device_drivers/dlink/dl2k.rst | 314 +++++++++++++++++++++ .../networking/device_drivers/dlink/dl2k.txt | 282 ------------------ Documentation/networking/device_drivers/index.rst | 1 + drivers/net/ethernet/dlink/dl2k.c | 2 +- 4 files changed, 316 insertions(+), 283 deletions(-) create mode 100644 Documentation/networking/device_drivers/dlink/dl2k.rst delete mode 100644 Documentation/networking/device_drivers/dlink/dl2k.txt diff --git a/Documentation/networking/device_drivers/dlink/dl2k.rst b/Documentation/networking/device_drivers/dlink/dl2k.rst new file mode 100644 index 000000000000..ccdb5d0d7460 --- /dev/null +++ b/Documentation/networking/device_drivers/dlink/dl2k.rst @@ -0,0 +1,314 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================================================= +D-Link DL2000-based Gigabit Ethernet Adapter Installation +========================================================= + +May 23, 2002 + +.. Contents + + - Compatibility List + - Quick Install + - Compiling the Driver + - Installing the Driver + - Option parameter + - Configuration Script Sample + - Troubleshooting + + +Compatibility List +================== + +Adapter Support: + +- D-Link DGE-550T Gigabit Ethernet Adapter. +- D-Link DGE-550SX Gigabit Ethernet Adapter. +- D-Link DL2000-based Gigabit Ethernet Adapter. + + +The driver support Linux kernel 2.4.7 later. We had tested it +on the environments below. + + . Red Hat v6.2 (update kernel to 2.4.7) + . Red Hat v7.0 (update kernel to 2.4.7) + . Red Hat v7.1 (kernel 2.4.7) + . Red Hat v7.2 (kernel 2.4.7-10) + + +Quick Install +============= +Install linux driver as following command:: + + 1. make all + 2. insmod dl2k.ko + 3. ifconfig eth0 up 10.xxx.xxx.xxx netmask 255.0.0.0 + ^^^^^^^^^^^^^^^\ ^^^^^^^^\ + IP NETMASK + +Now eth0 should active, you can test it by "ping" or get more information by +"ifconfig". If tested ok, continue the next step. + +4. ``cp dl2k.ko /lib/modules/`uname -r`/kernel/drivers/net`` +5. Add the following line to /etc/modprobe.d/dl2k.conf:: + + alias eth0 dl2k + +6. Run ``depmod`` to updated module indexes. +7. Run ``netconfig`` or ``netconf`` to create configuration script ifcfg-eth0 + located at /etc/sysconfig/network-scripts or create it manually. + + [see - Configuration Script Sample] +8. Driver will automatically load and configure at next boot time. + +Compiling the Driver +==================== +In Linux, NIC drivers are most commonly configured as loadable modules. +The approach of building a monolithic kernel has become obsolete. The driver +can be compiled as part of a monolithic kernel, but is strongly discouraged. +The remainder of this section assumes the driver is built as a loadable module. +In the Linux environment, it is a good idea to rebuild the driver from the +source instead of relying on a precompiled version. This approach provides +better reliability since a precompiled driver might depend on libraries or +kernel features that are not present in a given Linux installation. + +The 3 files necessary to build Linux device driver are dl2k.c, dl2k.h and +Makefile. To compile, the Linux installation must include the gcc compiler, +the kernel source, and the kernel headers. The Linux driver supports Linux +Kernels 2.4.7. Copy the files to a directory and enter the following command +to compile and link the driver: + +CD-ROM drive +------------ + +:: + + [root@XXX /] mkdir cdrom + [root@XXX /] mount -r -t iso9660 -o conv=auto /dev/cdrom /cdrom + [root@XXX /] cd root + [root@XXX /root] mkdir dl2k + [root@XXX /root] cd dl2k + [root@XXX dl2k] cp /cdrom/linux/dl2k.tgz /root/dl2k + [root@XXX dl2k] tar xfvz dl2k.tgz + [root@XXX dl2k] make all + +Floppy disc drive +----------------- + +:: + + [root@XXX /] cd root + [root@XXX /root] mkdir dl2k + [root@XXX /root] cd dl2k + [root@XXX dl2k] mcopy a:/linux/dl2k.tgz /root/dl2k + [root@XXX dl2k] tar xfvz dl2k.tgz + [root@XXX dl2k] make all + +Installing the Driver +===================== + +Manual Installation +------------------- + + Once the driver has been compiled, it must be loaded, enabled, and bound + to a protocol stack in order to establish network connectivity. To load a + module enter the command:: + + insmod dl2k.o + + or:: + + insmod dl2k.o ; add parameter + +--------------------------------------------------------- + + example:: + + insmod dl2k.o media=100mbps_hd + + or:: + + insmod dl2k.o media=3 + + or:: + + insmod dl2k.o media=3,2 ; for 2 cards + +--------------------------------------------------------- + + Please reference the list of the command line parameters supported by + the Linux device driver below. + + The insmod command only loads the driver and gives it a name of the form + eth0, eth1, etc. To bring the NIC into an operational state, + it is necessary to issue the following command:: + + ifconfig eth0 up + + Finally, to bind the driver to the active protocol (e.g., TCP/IP with + Linux), enter the following command:: + + ifup eth0 + + Note that this is meaningful only if the system can find a configuration + script that contains the necessary network information. A sample will be + given in the next paragraph. + + The commands to unload a driver are as follows:: + + ifdown eth0 + ifconfig eth0 down + rmmod dl2k.o + + The following are the commands to list the currently loaded modules and + to see the current network configuration:: + + lsmod + ifconfig + + +Automated Installation +---------------------- + This section describes how to install the driver such that it is + automatically loaded and configured at boot time. The following description + is based on a Red Hat 6.0/7.0 distribution, but it can easily be ported to + other distributions as well. + +Red Hat v6.x/v7.x +----------------- + 1. Copy dl2k.o to the network modules directory, typically + /lib/modules/2.x.x-xx/net or /lib/modules/2.x.x/kernel/drivers/net. + 2. Locate the boot module configuration file, most commonly in the + /etc/modprobe.d/ directory. Add the following lines:: + + alias ethx dl2k + options dl2k + + where ethx will be eth0 if the NIC is the only ethernet adapter, eth1 if + one other ethernet adapter is installed, etc. Refer to the table in the + previous section for the list of optional parameters. + 3. Locate the network configuration scripts, normally the + /etc/sysconfig/network-scripts directory, and create a configuration + script named ifcfg-ethx that contains network information. + 4. Note that for most Linux distributions, Red Hat included, a configuration + utility with a graphical user interface is provided to perform steps 2 + and 3 above. + + +Parameter Description +===================== +You can install this driver without any additional parameter. However, if you +are going to have extensive functions then it is necessary to set extra +parameter. Below is a list of the command line parameters supported by the +Linux device +driver. + + +=============================== ============================================== +mtu=packet_size Specifies the maximum packet size. default + is 1500. + +media=media_type Specifies the media type the NIC operates at. + autosense Autosensing active media. + + =========== ========================= + 10mbps_hd 10Mbps half duplex. + 10mbps_fd 10Mbps full duplex. + 100mbps_hd 100Mbps half duplex. + 100mbps_fd 100Mbps full duplex. + 1000mbps_fd 1000Mbps full duplex. + 1000mbps_hd 1000Mbps half duplex. + 0 Autosensing active media. + 1 10Mbps half duplex. + 2 10Mbps full duplex. + 3 100Mbps half duplex. + 4 100Mbps full duplex. + 5 1000Mbps half duplex. + 6 1000Mbps full duplex. + =========== ========================= + + By default, the NIC operates at autosense. + 1000mbps_fd and 1000mbps_hd types are only + available for fiber adapter. + +vlan=n Specifies the VLAN ID. If vlan=0, the + Virtual Local Area Network (VLAN) function is + disable. + +jumbo=[0|1] Specifies the jumbo frame support. If jumbo=1, + the NIC accept jumbo frames. By default, this + function is disabled. + Jumbo frame usually improve the performance + int gigabit. + This feature need jumbo frame compatible + remote. + +rx_coalesce=m Number of rx frame handled each interrupt. +rx_timeout=n Rx DMA wait time for an interrupt. + If set rx_coalesce > 0, hardware only assert + an interrupt for m frames. Hardware won't + assert rx interrupt until m frames received or + reach timeout of n * 640 nano seconds. + Set proper rx_coalesce and rx_timeout can + reduce congestion collapse and overload which + has been a bottleneck for high speed network. + + For example, rx_coalesce=10 rx_timeout=800. + that is, hardware assert only 1 interrupt + for 10 frames received or timeout of 512 us. + +tx_coalesce=n Number of tx frame handled each interrupt. + Set n > 1 can reduce the interrupts + congestion usually lower performance of + high speed network card. Default is 16. + +tx_flow=[1|0] Specifies the Tx flow control. If tx_flow=0, + the Tx flow control disable else driver + autodetect. +rx_flow=[1|0] Specifies the Rx flow control. If rx_flow=0, + the Rx flow control enable else driver + autodetect. +=============================== ============================================== + + +Configuration Script Sample +=========================== +Here is a sample of a simple configuration script:: + + DEVICE=eth0 + USERCTL=no + ONBOOT=yes + POOTPROTO=none + BROADCAST=207.200.5.255 + NETWORK=207.200.5.0 + NETMASK=255.255.255.0 + IPADDR=207.200.5.2 + + +Troubleshooting +=============== +Q1. Source files contain ^ M behind every line. + + Make sure all files are Unix file format (no LF). Try the following + shell command to convert files:: + + cat dl2k.c | col -b > dl2k.tmp + mv dl2k.tmp dl2k.c + + OR:: + + cat dl2k.c | tr -d "\r" > dl2k.tmp + mv dl2k.tmp dl2k.c + +Q2: Could not find header files (``*.h``)? + + To compile the driver, you need kernel header files. After + installing the kernel source, the header files are usually located in + /usr/src/linux/include, which is the default include directory configured + in Makefile. For some distributions, there is a copy of header files in + /usr/src/include/linux and /usr/src/include/asm, that you can change the + INCLUDEDIR in Makefile to /usr/include without installing kernel source. + + Note that RH 7.0 didn't provide correct header files in /usr/include, + including those files will make a wrong version driver. + diff --git a/Documentation/networking/device_drivers/dlink/dl2k.txt b/Documentation/networking/device_drivers/dlink/dl2k.txt deleted file mode 100644 index cba74f7a3abc..000000000000 --- a/Documentation/networking/device_drivers/dlink/dl2k.txt +++ /dev/null @@ -1,282 +0,0 @@ - - D-Link DL2000-based Gigabit Ethernet Adapter Installation - for Linux - May 23, 2002 - -Contents -======== - - Compatibility List - - Quick Install - - Compiling the Driver - - Installing the Driver - - Option parameter - - Configuration Script Sample - - Troubleshooting - - -Compatibility List -================= -Adapter Support: - -D-Link DGE-550T Gigabit Ethernet Adapter. -D-Link DGE-550SX Gigabit Ethernet Adapter. -D-Link DL2000-based Gigabit Ethernet Adapter. - - -The driver support Linux kernel 2.4.7 later. We had tested it -on the environments below. - - . Red Hat v6.2 (update kernel to 2.4.7) - . Red Hat v7.0 (update kernel to 2.4.7) - . Red Hat v7.1 (kernel 2.4.7) - . Red Hat v7.2 (kernel 2.4.7-10) - - -Quick Install -============= -Install linux driver as following command: - -1. make all -2. insmod dl2k.ko -3. ifconfig eth0 up 10.xxx.xxx.xxx netmask 255.0.0.0 - ^^^^^^^^^^^^^^^\ ^^^^^^^^\ - IP NETMASK -Now eth0 should active, you can test it by "ping" or get more information by -"ifconfig". If tested ok, continue the next step. - -4. cp dl2k.ko /lib/modules/`uname -r`/kernel/drivers/net -5. Add the following line to /etc/modprobe.d/dl2k.conf: - alias eth0 dl2k -6. Run depmod to updated module indexes. -7. Run "netconfig" or "netconf" to create configuration script ifcfg-eth0 - located at /etc/sysconfig/network-scripts or create it manually. - [see - Configuration Script Sample] -8. Driver will automatically load and configure at next boot time. - -Compiling the Driver -==================== - In Linux, NIC drivers are most commonly configured as loadable modules. -The approach of building a monolithic kernel has become obsolete. The driver -can be compiled as part of a monolithic kernel, but is strongly discouraged. -The remainder of this section assumes the driver is built as a loadable module. -In the Linux environment, it is a good idea to rebuild the driver from the -source instead of relying on a precompiled version. This approach provides -better reliability since a precompiled driver might depend on libraries or -kernel features that are not present in a given Linux installation. - -The 3 files necessary to build Linux device driver are dl2k.c, dl2k.h and -Makefile. To compile, the Linux installation must include the gcc compiler, -the kernel source, and the kernel headers. The Linux driver supports Linux -Kernels 2.4.7. Copy the files to a directory and enter the following command -to compile and link the driver: - -CD-ROM drive ------------- - -[root@XXX /] mkdir cdrom -[root@XXX /] mount -r -t iso9660 -o conv=auto /dev/cdrom /cdrom -[root@XXX /] cd root -[root@XXX /root] mkdir dl2k -[root@XXX /root] cd dl2k -[root@XXX dl2k] cp /cdrom/linux/dl2k.tgz /root/dl2k -[root@XXX dl2k] tar xfvz dl2k.tgz -[root@XXX dl2k] make all - -Floppy disc drive ------------------ - -[root@XXX /] cd root -[root@XXX /root] mkdir dl2k -[root@XXX /root] cd dl2k -[root@XXX dl2k] mcopy a:/linux/dl2k.tgz /root/dl2k -[root@XXX dl2k] tar xfvz dl2k.tgz -[root@XXX dl2k] make all - -Installing the Driver -===================== - - Manual Installation - ------------------- - Once the driver has been compiled, it must be loaded, enabled, and bound - to a protocol stack in order to establish network connectivity. To load a - module enter the command: - - insmod dl2k.o - - or - - insmod dl2k.o ; add parameter - - =============================================================== - example: insmod dl2k.o media=100mbps_hd - or insmod dl2k.o media=3 - or insmod dl2k.o media=3,2 ; for 2 cards - =============================================================== - - Please reference the list of the command line parameters supported by - the Linux device driver below. - - The insmod command only loads the driver and gives it a name of the form - eth0, eth1, etc. To bring the NIC into an operational state, - it is necessary to issue the following command: - - ifconfig eth0 up - - Finally, to bind the driver to the active protocol (e.g., TCP/IP with - Linux), enter the following command: - - ifup eth0 - - Note that this is meaningful only if the system can find a configuration - script that contains the necessary network information. A sample will be - given in the next paragraph. - - The commands to unload a driver are as follows: - - ifdown eth0 - ifconfig eth0 down - rmmod dl2k.o - - The following are the commands to list the currently loaded modules and - to see the current network configuration. - - lsmod - ifconfig - - - Automated Installation - ---------------------- - This section describes how to install the driver such that it is - automatically loaded and configured at boot time. The following description - is based on a Red Hat 6.0/7.0 distribution, but it can easily be ported to - other distributions as well. - - Red Hat v6.x/v7.x - ----------------- - 1. Copy dl2k.o to the network modules directory, typically - /lib/modules/2.x.x-xx/net or /lib/modules/2.x.x/kernel/drivers/net. - 2. Locate the boot module configuration file, most commonly in the - /etc/modprobe.d/ directory. Add the following lines: - - alias ethx dl2k - options dl2k - - where ethx will be eth0 if the NIC is the only ethernet adapter, eth1 if - one other ethernet adapter is installed, etc. Refer to the table in the - previous section for the list of optional parameters. - 3. Locate the network configuration scripts, normally the - /etc/sysconfig/network-scripts directory, and create a configuration - script named ifcfg-ethx that contains network information. - 4. Note that for most Linux distributions, Red Hat included, a configuration - utility with a graphical user interface is provided to perform steps 2 - and 3 above. - - -Parameter Description -===================== -You can install this driver without any additional parameter. However, if you -are going to have extensive functions then it is necessary to set extra -parameter. Below is a list of the command line parameters supported by the -Linux device -driver. - -mtu=packet_size - Specifies the maximum packet size. default - is 1500. - -media=media_type - Specifies the media type the NIC operates at. - autosense Autosensing active media. - 10mbps_hd 10Mbps half duplex. - 10mbps_fd 10Mbps full duplex. - 100mbps_hd 100Mbps half duplex. - 100mbps_fd 100Mbps full duplex. - 1000mbps_fd 1000Mbps full duplex. - 1000mbps_hd 1000Mbps half duplex. - 0 Autosensing active media. - 1 10Mbps half duplex. - 2 10Mbps full duplex. - 3 100Mbps half duplex. - 4 100Mbps full duplex. - 5 1000Mbps half duplex. - 6 1000Mbps full duplex. - - By default, the NIC operates at autosense. - 1000mbps_fd and 1000mbps_hd types are only - available for fiber adapter. - -vlan=n - Specifies the VLAN ID. If vlan=0, the - Virtual Local Area Network (VLAN) function is - disable. - -jumbo=[0|1] - Specifies the jumbo frame support. If jumbo=1, - the NIC accept jumbo frames. By default, this - function is disabled. - Jumbo frame usually improve the performance - int gigabit. - This feature need jumbo frame compatible - remote. - -rx_coalesce=m - Number of rx frame handled each interrupt. -rx_timeout=n - Rx DMA wait time for an interrupt. - If set rx_coalesce > 0, hardware only assert - an interrupt for m frames. Hardware won't - assert rx interrupt until m frames received or - reach timeout of n * 640 nano seconds. - Set proper rx_coalesce and rx_timeout can - reduce congestion collapse and overload which - has been a bottleneck for high speed network. - - For example, rx_coalesce=10 rx_timeout=800. - that is, hardware assert only 1 interrupt - for 10 frames received or timeout of 512 us. - -tx_coalesce=n - Number of tx frame handled each interrupt. - Set n > 1 can reduce the interrupts - congestion usually lower performance of - high speed network card. Default is 16. - -tx_flow=[1|0] - Specifies the Tx flow control. If tx_flow=0, - the Tx flow control disable else driver - autodetect. -rx_flow=[1|0] - Specifies the Rx flow control. If rx_flow=0, - the Rx flow control enable else driver - autodetect. - - -Configuration Script Sample -=========================== -Here is a sample of a simple configuration script: - -DEVICE=eth0 -USERCTL=no -ONBOOT=yes -POOTPROTO=none -BROADCAST=207.200.5.255 -NETWORK=207.200.5.0 -NETMASK=255.255.255.0 -IPADDR=207.200.5.2 - - -Troubleshooting -=============== -Q1. Source files contain ^ M behind every line. - Make sure all files are Unix file format (no LF). Try the following - shell command to convert files. - - cat dl2k.c | col -b > dl2k.tmp - mv dl2k.tmp dl2k.c - - OR - - cat dl2k.c | tr -d "\r" > dl2k.tmp - mv dl2k.tmp dl2k.c - -Q2: Could not find header files (*.h) ? - To compile the driver, you need kernel header files. After - installing the kernel source, the header files are usually located in - /usr/src/linux/include, which is the default include directory configured - in Makefile. For some distributions, there is a copy of header files in - /usr/src/include/linux and /usr/src/include/asm, that you can change the - INCLUDEDIR in Makefile to /usr/include without installing kernel source. - Note that RH 7.0 didn't provide correct header files in /usr/include, - including those files will make a wrong version driver. - diff --git a/Documentation/networking/device_drivers/index.rst b/Documentation/networking/device_drivers/index.rst index 09728e964ce1..e5d1863379cb 100644 --- a/Documentation/networking/device_drivers/index.rst +++ b/Documentation/networking/device_drivers/index.rst @@ -36,6 +36,7 @@ Contents: davicom/dm9000 dec/de4x5 dec/dmfe + dlink/dl2k .. only:: subproject and html diff --git a/drivers/net/ethernet/dlink/dl2k.c b/drivers/net/ethernet/dlink/dl2k.c index 643090555cc7..5143722c4419 100644 --- a/drivers/net/ethernet/dlink/dl2k.c +++ b/drivers/net/ethernet/dlink/dl2k.c @@ -1869,7 +1869,7 @@ Compile command: gcc -D__KERNEL__ -DMODULE -I/usr/src/linux/include -Wall -Wstrict-prototypes -O2 -c dl2k.c -Read Documentation/networking/device_drivers/dlink/dl2k.txt for details. +Read Documentation/networking/device_drivers/dlink/dl2k.rst for details. */ -- cgit From 0d0d976f59a57e5536ff01825f0bc8a0dbb0fe6b Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 1 May 2020 16:44:44 +0200 Subject: docs: networking: device drivers: convert freescale/dpaa.txt to ReST - add SPDX header; - adjust titles and chapters, adding proper markups; - mark code blocks and literals as such; - use :field: markup; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: David S. Miller --- .../networking/device_drivers/freescale/dpaa.rst | 269 +++++++++++++++++++++ .../networking/device_drivers/freescale/dpaa.txt | 260 -------------------- Documentation/networking/device_drivers/index.rst | 1 + 3 files changed, 270 insertions(+), 260 deletions(-) create mode 100644 Documentation/networking/device_drivers/freescale/dpaa.rst delete mode 100644 Documentation/networking/device_drivers/freescale/dpaa.txt diff --git a/Documentation/networking/device_drivers/freescale/dpaa.rst b/Documentation/networking/device_drivers/freescale/dpaa.rst new file mode 100644 index 000000000000..241c6c6f6e68 --- /dev/null +++ b/Documentation/networking/device_drivers/freescale/dpaa.rst @@ -0,0 +1,269 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================== +The QorIQ DPAA Ethernet Driver +============================== + +Authors: +- Madalin Bucur +- Camelia Groza + +.. Contents + + - DPAA Ethernet Overview + - DPAA Ethernet Supported SoCs + - Configuring DPAA Ethernet in your kernel + - DPAA Ethernet Frame Processing + - DPAA Ethernet Features + - DPAA IRQ Affinity and Receive Side Scaling + - Debugging + +DPAA Ethernet Overview +====================== + +DPAA stands for Data Path Acceleration Architecture and it is a +set of networking acceleration IPs that are available on several +generations of SoCs, both on PowerPC and ARM64. + +The Freescale DPAA architecture consists of a series of hardware blocks +that support Ethernet connectivity. The Ethernet driver depends upon the +following drivers in the Linux kernel: + + - Peripheral Access Memory Unit (PAMU) (* needed only for PPC platforms) + drivers/iommu/fsl_* + - Frame Manager (FMan) + drivers/net/ethernet/freescale/fman + - Queue Manager (QMan), Buffer Manager (BMan) + drivers/soc/fsl/qbman + +A simplified view of the dpaa_eth interfaces mapped to FMan MACs:: + + dpaa_eth /eth0\ ... /ethN\ + driver | | | | + ------------- ---- ----------- ---- ------------- + -Ports / Tx Rx \ ... / Tx Rx \ + FMan | | | | + -MACs | MAC0 | | MACN | + / dtsec0 \ ... / dtsecN \ (or tgec) + / \ / \(or memac) + --------- -------------- --- -------------- --------- + FMan, FMan Port, FMan SP, FMan MURAM drivers + --------------------------------------------------------- + FMan HW blocks: MURAM, MACs, Ports, SP + --------------------------------------------------------- + +The dpaa_eth relation to the QMan, BMan and FMan:: + + ________________________________ + dpaa_eth / eth0 \ + driver / \ + --------- -^- -^- -^- --- --------- + QMan driver / \ / \ / \ \ / | BMan | + |Rx | |Rx | |Tx | |Tx | | driver | + --------- |Dfl| |Err| |Cnf| |FQs| | | + QMan HW |FQ | |FQ | |FQs| | | | | + / \ / \ / \ \ / | | + --------- --- --- --- -v- --------- + | FMan QMI | | + | FMan HW FMan BMI | BMan HW | + ----------------------- -------- + +where the acronyms used above (and in the code) are: + +=============== =========================================================== +DPAA Data Path Acceleration Architecture +FMan DPAA Frame Manager +QMan DPAA Queue Manager +BMan DPAA Buffers Manager +QMI QMan interface in FMan +BMI BMan interface in FMan +FMan SP FMan Storage Profiles +MURAM Multi-user RAM in FMan +FQ QMan Frame Queue +Rx Dfl FQ default reception FQ +Rx Err FQ Rx error frames FQ +Tx Cnf FQ Tx confirmation FQs +Tx FQs transmission frame queues +dtsec datapath three speed Ethernet controller (10/100/1000 Mbps) +tgec ten gigabit Ethernet controller (10 Gbps) +memac multirate Ethernet MAC (10/100/1000/10000) +=============== =========================================================== + +DPAA Ethernet Supported SoCs +============================ + +The DPAA drivers enable the Ethernet controllers present on the following SoCs: + +PPC +- P1023 +- P2041 +- P3041 +- P4080 +- P5020 +- P5040 +- T1023 +- T1024 +- T1040 +- T1042 +- T2080 +- T4240 +- B4860 + +ARM +- LS1043A +- LS1046A + +Configuring DPAA Ethernet in your kernel +======================================== + +To enable the DPAA Ethernet driver, the following Kconfig options are required:: + + # common for arch/arm64 and arch/powerpc platforms + CONFIG_FSL_DPAA=y + CONFIG_FSL_FMAN=y + CONFIG_FSL_DPAA_ETH=y + CONFIG_FSL_XGMAC_MDIO=y + + # for arch/powerpc only + CONFIG_FSL_PAMU=y + + # common options needed for the PHYs used on the RDBs + CONFIG_VITESSE_PHY=y + CONFIG_REALTEK_PHY=y + CONFIG_AQUANTIA_PHY=y + +DPAA Ethernet Frame Processing +============================== + +On Rx, buffers for the incoming frames are retrieved from the buffers found +in the dedicated interface buffer pool. The driver initializes and seeds these +with one page buffers. + +On Tx, all transmitted frames are returned to the driver through Tx +confirmation frame queues. The driver is then responsible for freeing the +buffers. In order to do this properly, a backpointer is added to the buffer +before transmission that points to the skb. When the buffer returns to the +driver on a confirmation FQ, the skb can be correctly consumed. + +DPAA Ethernet Features +====================== + +Currently the DPAA Ethernet driver enables the basic features required for +a Linux Ethernet driver. The support for advanced features will be added +gradually. + +The driver has Rx and Tx checksum offloading for UDP and TCP. Currently the Rx +checksum offload feature is enabled by default and cannot be controlled through +ethtool. Also, rx-flow-hash and rx-hashing was added. The addition of RSS +provides a big performance boost for the forwarding scenarios, allowing +different traffic flows received by one interface to be processed by different +CPUs in parallel. + +The driver has support for multiple prioritized Tx traffic classes. Priorities +range from 0 (lowest) to 3 (highest). These are mapped to HW workqueues with +strict priority levels. Each traffic class contains NR_CPU TX queues. By +default, only one traffic class is enabled and the lowest priority Tx queues +are used. Higher priority traffic classes can be enabled with the mqprio +qdisc. For example, all four traffic classes are enabled on an interface with +the following command. Furthermore, skb priority levels are mapped to traffic +classes as follows: + + * priorities 0 to 3 - traffic class 0 (low priority) + * priorities 4 to 7 - traffic class 1 (medium-low priority) + * priorities 8 to 11 - traffic class 2 (medium-high priority) + * priorities 12 to 15 - traffic class 3 (high priority) + +:: + + tc qdisc add dev root handle 1: \ + mqprio num_tc 4 map 0 0 0 0 1 1 1 1 2 2 2 2 3 3 3 3 hw 1 + +DPAA IRQ Affinity and Receive Side Scaling +========================================== + +Traffic coming on the DPAA Rx queues or on the DPAA Tx confirmation +queues is seen by the CPU as ingress traffic on a certain portal. +The DPAA QMan portal interrupts are affined each to a certain CPU. +The same portal interrupt services all the QMan portal consumers. + +By default the DPAA Ethernet driver enables RSS, making use of the +DPAA FMan Parser and Keygen blocks to distribute traffic on 128 +hardware frame queues using a hash on IP v4/v6 source and destination +and L4 source and destination ports, in present in the received frame. +When RSS is disabled, all traffic received by a certain interface is +received on the default Rx frame queue. The default DPAA Rx frame +queues are configured to put the received traffic into a pool channel +that allows any available CPU portal to dequeue the ingress traffic. +The default frame queues have the HOLDACTIVE option set, ensuring that +traffic bursts from a certain queue are serviced by the same CPU. +This ensures a very low rate of frame reordering. A drawback of this +is that only one CPU at a time can service the traffic received by a +certain interface when RSS is not enabled. + +To implement RSS, the DPAA Ethernet driver allocates an extra set of +128 Rx frame queues that are configured to dedicated channels, in a +round-robin manner. The mapping of the frame queues to CPUs is now +hardcoded, there is no indirection table to move traffic for a certain +FQ (hash result) to another CPU. The ingress traffic arriving on one +of these frame queues will arrive at the same portal and will always +be processed by the same CPU. This ensures intra-flow order preservation +and workload distribution for multiple traffic flows. + +RSS can be turned off for a certain interface using ethtool, i.e.:: + + # ethtool -N fm1-mac9 rx-flow-hash tcp4 "" + +To turn it back on, one needs to set rx-flow-hash for tcp4/6 or udp4/6:: + + # ethtool -N fm1-mac9 rx-flow-hash udp4 sfdn + +There is no independent control for individual protocols, any command +run for one of tcp4|udp4|ah4|esp4|sctp4|tcp6|udp6|ah6|esp6|sctp6 is +going to control the rx-flow-hashing for all protocols on that interface. + +Besides using the FMan Keygen computed hash for spreading traffic on the +128 Rx FQs, the DPAA Ethernet driver also sets the skb hash value when +the NETIF_F_RXHASH feature is on (active by default). This can be turned +on or off through ethtool, i.e.:: + + # ethtool -K fm1-mac9 rx-hashing off + # ethtool -k fm1-mac9 | grep hash + receive-hashing: off + # ethtool -K fm1-mac9 rx-hashing on + Actual changes: + receive-hashing: on + # ethtool -k fm1-mac9 | grep hash + receive-hashing: on + +Please note that Rx hashing depends upon the rx-flow-hashing being on +for that interface - turning off rx-flow-hashing will also disable the +rx-hashing (without ethtool reporting it as off as that depends on the +NETIF_F_RXHASH feature flag). + +Debugging +========= + +The following statistics are exported for each interface through ethtool: + + - interrupt count per CPU + - Rx packets count per CPU + - Tx packets count per CPU + - Tx confirmed packets count per CPU + - Tx S/G frames count per CPU + - Tx error count per CPU + - Rx error count per CPU + - Rx error count per type + - congestion related statistics: + + - congestion status + - time spent in congestion + - number of time the device entered congestion + - dropped packets count per cause + +The driver also exports the following information in sysfs: + + - the FQ IDs for each FQ type + /sys/devices/platform/soc/.fman/.ethernet/dpaa-ethernet./net/fm-mac/fqids + + - the ID of the buffer pool in use + /sys/devices/platform/soc/.fman/.ethernet/dpaa-ethernet./net/fm-mac/bpids diff --git a/Documentation/networking/device_drivers/freescale/dpaa.txt b/Documentation/networking/device_drivers/freescale/dpaa.txt deleted file mode 100644 index b06601ff9200..000000000000 --- a/Documentation/networking/device_drivers/freescale/dpaa.txt +++ /dev/null @@ -1,260 +0,0 @@ -The QorIQ DPAA Ethernet Driver -============================== - -Authors: -Madalin Bucur -Camelia Groza - -Contents -======== - - - DPAA Ethernet Overview - - DPAA Ethernet Supported SoCs - - Configuring DPAA Ethernet in your kernel - - DPAA Ethernet Frame Processing - - DPAA Ethernet Features - - DPAA IRQ Affinity and Receive Side Scaling - - Debugging - -DPAA Ethernet Overview -====================== - -DPAA stands for Data Path Acceleration Architecture and it is a -set of networking acceleration IPs that are available on several -generations of SoCs, both on PowerPC and ARM64. - -The Freescale DPAA architecture consists of a series of hardware blocks -that support Ethernet connectivity. The Ethernet driver depends upon the -following drivers in the Linux kernel: - - - Peripheral Access Memory Unit (PAMU) (* needed only for PPC platforms) - drivers/iommu/fsl_* - - Frame Manager (FMan) - drivers/net/ethernet/freescale/fman - - Queue Manager (QMan), Buffer Manager (BMan) - drivers/soc/fsl/qbman - -A simplified view of the dpaa_eth interfaces mapped to FMan MACs: - - dpaa_eth /eth0\ ... /ethN\ - driver | | | | - ------------- ---- ----------- ---- ------------- - -Ports / Tx Rx \ ... / Tx Rx \ - FMan | | | | - -MACs | MAC0 | | MACN | - / dtsec0 \ ... / dtsecN \ (or tgec) - / \ / \(or memac) - --------- -------------- --- -------------- --------- - FMan, FMan Port, FMan SP, FMan MURAM drivers - --------------------------------------------------------- - FMan HW blocks: MURAM, MACs, Ports, SP - --------------------------------------------------------- - -The dpaa_eth relation to the QMan, BMan and FMan: - ________________________________ - dpaa_eth / eth0 \ - driver / \ - --------- -^- -^- -^- --- --------- - QMan driver / \ / \ / \ \ / | BMan | - |Rx | |Rx | |Tx | |Tx | | driver | - --------- |Dfl| |Err| |Cnf| |FQs| | | - QMan HW |FQ | |FQ | |FQs| | | | | - / \ / \ / \ \ / | | - --------- --- --- --- -v- --------- - | FMan QMI | | - | FMan HW FMan BMI | BMan HW | - ----------------------- -------- - -where the acronyms used above (and in the code) are: -DPAA = Data Path Acceleration Architecture -FMan = DPAA Frame Manager -QMan = DPAA Queue Manager -BMan = DPAA Buffers Manager -QMI = QMan interface in FMan -BMI = BMan interface in FMan -FMan SP = FMan Storage Profiles -MURAM = Multi-user RAM in FMan -FQ = QMan Frame Queue -Rx Dfl FQ = default reception FQ -Rx Err FQ = Rx error frames FQ -Tx Cnf FQ = Tx confirmation FQs -Tx FQs = transmission frame queues -dtsec = datapath three speed Ethernet controller (10/100/1000 Mbps) -tgec = ten gigabit Ethernet controller (10 Gbps) -memac = multirate Ethernet MAC (10/100/1000/10000) - -DPAA Ethernet Supported SoCs -============================ - -The DPAA drivers enable the Ethernet controllers present on the following SoCs: - -# PPC -P1023 -P2041 -P3041 -P4080 -P5020 -P5040 -T1023 -T1024 -T1040 -T1042 -T2080 -T4240 -B4860 - -# ARM -LS1043A -LS1046A - -Configuring DPAA Ethernet in your kernel -======================================== - -To enable the DPAA Ethernet driver, the following Kconfig options are required: - -# common for arch/arm64 and arch/powerpc platforms -CONFIG_FSL_DPAA=y -CONFIG_FSL_FMAN=y -CONFIG_FSL_DPAA_ETH=y -CONFIG_FSL_XGMAC_MDIO=y - -# for arch/powerpc only -CONFIG_FSL_PAMU=y - -# common options needed for the PHYs used on the RDBs -CONFIG_VITESSE_PHY=y -CONFIG_REALTEK_PHY=y -CONFIG_AQUANTIA_PHY=y - -DPAA Ethernet Frame Processing -============================== - -On Rx, buffers for the incoming frames are retrieved from the buffers found -in the dedicated interface buffer pool. The driver initializes and seeds these -with one page buffers. - -On Tx, all transmitted frames are returned to the driver through Tx -confirmation frame queues. The driver is then responsible for freeing the -buffers. In order to do this properly, a backpointer is added to the buffer -before transmission that points to the skb. When the buffer returns to the -driver on a confirmation FQ, the skb can be correctly consumed. - -DPAA Ethernet Features -====================== - -Currently the DPAA Ethernet driver enables the basic features required for -a Linux Ethernet driver. The support for advanced features will be added -gradually. - -The driver has Rx and Tx checksum offloading for UDP and TCP. Currently the Rx -checksum offload feature is enabled by default and cannot be controlled through -ethtool. Also, rx-flow-hash and rx-hashing was added. The addition of RSS -provides a big performance boost for the forwarding scenarios, allowing -different traffic flows received by one interface to be processed by different -CPUs in parallel. - -The driver has support for multiple prioritized Tx traffic classes. Priorities -range from 0 (lowest) to 3 (highest). These are mapped to HW workqueues with -strict priority levels. Each traffic class contains NR_CPU TX queues. By -default, only one traffic class is enabled and the lowest priority Tx queues -are used. Higher priority traffic classes can be enabled with the mqprio -qdisc. For example, all four traffic classes are enabled on an interface with -the following command. Furthermore, skb priority levels are mapped to traffic -classes as follows: - - * priorities 0 to 3 - traffic class 0 (low priority) - * priorities 4 to 7 - traffic class 1 (medium-low priority) - * priorities 8 to 11 - traffic class 2 (medium-high priority) - * priorities 12 to 15 - traffic class 3 (high priority) - -tc qdisc add dev root handle 1: \ - mqprio num_tc 4 map 0 0 0 0 1 1 1 1 2 2 2 2 3 3 3 3 hw 1 - -DPAA IRQ Affinity and Receive Side Scaling -========================================== - -Traffic coming on the DPAA Rx queues or on the DPAA Tx confirmation -queues is seen by the CPU as ingress traffic on a certain portal. -The DPAA QMan portal interrupts are affined each to a certain CPU. -The same portal interrupt services all the QMan portal consumers. - -By default the DPAA Ethernet driver enables RSS, making use of the -DPAA FMan Parser and Keygen blocks to distribute traffic on 128 -hardware frame queues using a hash on IP v4/v6 source and destination -and L4 source and destination ports, in present in the received frame. -When RSS is disabled, all traffic received by a certain interface is -received on the default Rx frame queue. The default DPAA Rx frame -queues are configured to put the received traffic into a pool channel -that allows any available CPU portal to dequeue the ingress traffic. -The default frame queues have the HOLDACTIVE option set, ensuring that -traffic bursts from a certain queue are serviced by the same CPU. -This ensures a very low rate of frame reordering. A drawback of this -is that only one CPU at a time can service the traffic received by a -certain interface when RSS is not enabled. - -To implement RSS, the DPAA Ethernet driver allocates an extra set of -128 Rx frame queues that are configured to dedicated channels, in a -round-robin manner. The mapping of the frame queues to CPUs is now -hardcoded, there is no indirection table to move traffic for a certain -FQ (hash result) to another CPU. The ingress traffic arriving on one -of these frame queues will arrive at the same portal and will always -be processed by the same CPU. This ensures intra-flow order preservation -and workload distribution for multiple traffic flows. - -RSS can be turned off for a certain interface using ethtool, i.e. - - # ethtool -N fm1-mac9 rx-flow-hash tcp4 "" - -To turn it back on, one needs to set rx-flow-hash for tcp4/6 or udp4/6: - - # ethtool -N fm1-mac9 rx-flow-hash udp4 sfdn - -There is no independent control for individual protocols, any command -run for one of tcp4|udp4|ah4|esp4|sctp4|tcp6|udp6|ah6|esp6|sctp6 is -going to control the rx-flow-hashing for all protocols on that interface. - -Besides using the FMan Keygen computed hash for spreading traffic on the -128 Rx FQs, the DPAA Ethernet driver also sets the skb hash value when -the NETIF_F_RXHASH feature is on (active by default). This can be turned -on or off through ethtool, i.e.: - - # ethtool -K fm1-mac9 rx-hashing off - # ethtool -k fm1-mac9 | grep hash - receive-hashing: off - # ethtool -K fm1-mac9 rx-hashing on - Actual changes: - receive-hashing: on - # ethtool -k fm1-mac9 | grep hash - receive-hashing: on - -Please note that Rx hashing depends upon the rx-flow-hashing being on -for that interface - turning off rx-flow-hashing will also disable the -rx-hashing (without ethtool reporting it as off as that depends on the -NETIF_F_RXHASH feature flag). - -Debugging -========= - -The following statistics are exported for each interface through ethtool: - - - interrupt count per CPU - - Rx packets count per CPU - - Tx packets count per CPU - - Tx confirmed packets count per CPU - - Tx S/G frames count per CPU - - Tx error count per CPU - - Rx error count per CPU - - Rx error count per type - - congestion related statistics: - - congestion status - - time spent in congestion - - number of time the device entered congestion - - dropped packets count per cause - -The driver also exports the following information in sysfs: - - - the FQ IDs for each FQ type - /sys/devices/platform/soc/.fman/.ethernet/dpaa-ethernet./net/fm-mac/fqids - - - the ID of the buffer pool in use - /sys/devices/platform/soc/.fman/.ethernet/dpaa-ethernet./net/fm-mac/bpids diff --git a/Documentation/networking/device_drivers/index.rst b/Documentation/networking/device_drivers/index.rst index e5d1863379cb..7e59ee43c030 100644 --- a/Documentation/networking/device_drivers/index.rst +++ b/Documentation/networking/device_drivers/index.rst @@ -37,6 +37,7 @@ Contents: dec/de4x5 dec/dmfe dlink/dl2k + freescale/dpaa .. only:: subproject and html -- cgit From dc67e91e7f7b2245a3a341e62217cb5e7163d60b Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 1 May 2020 16:44:45 +0200 Subject: docs: networking: device drivers: convert freescale/gianfar.txt to ReST - add SPDX header; - adjust titles and chapters, adding proper markups; - use :field: markup; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: David S. Miller --- .../device_drivers/freescale/gianfar.rst | 51 ++++++++++++++++++++++ .../device_drivers/freescale/gianfar.txt | 42 ------------------ Documentation/networking/device_drivers/index.rst | 1 + 3 files changed, 52 insertions(+), 42 deletions(-) create mode 100644 Documentation/networking/device_drivers/freescale/gianfar.rst delete mode 100644 Documentation/networking/device_drivers/freescale/gianfar.txt diff --git a/Documentation/networking/device_drivers/freescale/gianfar.rst b/Documentation/networking/device_drivers/freescale/gianfar.rst new file mode 100644 index 000000000000..9c4a91d3824b --- /dev/null +++ b/Documentation/networking/device_drivers/freescale/gianfar.rst @@ -0,0 +1,51 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=========================== +The Gianfar Ethernet Driver +=========================== + +:Author: Andy Fleming +:Updated: 2005-07-28 + + +Checksum Offloading +=================== + +The eTSEC controller (first included in parts from late 2005 like +the 8548) has the ability to perform TCP, UDP, and IP checksums +in hardware. The Linux kernel only offloads the TCP and UDP +checksums (and always performs the pseudo header checksums), so +the driver only supports checksumming for TCP/IP and UDP/IP +packets. Use ethtool to enable or disable this feature for RX +and TX. + +VLAN +==== + +In order to use VLAN, please consult Linux documentation on +configuring VLANs. The gianfar driver supports hardware insertion and +extraction of VLAN headers, but not filtering. Filtering will be +done by the kernel. + +Multicasting +============ + +The gianfar driver supports using the group hash table on the +TSEC (and the extended hash table on the eTSEC) for multicast +filtering. On the eTSEC, the exact-match MAC registers are used +before the hash tables. See Linux documentation on how to join +multicast groups. + +Padding +======= + +The gianfar driver supports padding received frames with 2 bytes +to align the IP header to a 16-byte boundary, when supported by +hardware. + +Ethtool +======= + +The gianfar driver supports the use of ethtool for many +configuration options. You must run ethtool only on currently +open interfaces. See ethtool documentation for details. diff --git a/Documentation/networking/device_drivers/freescale/gianfar.txt b/Documentation/networking/device_drivers/freescale/gianfar.txt deleted file mode 100644 index ba1daea7f2e4..000000000000 --- a/Documentation/networking/device_drivers/freescale/gianfar.txt +++ /dev/null @@ -1,42 +0,0 @@ -The Gianfar Ethernet Driver - -Author: Andy Fleming -Updated: 2005-07-28 - - -CHECKSUM OFFLOADING - -The eTSEC controller (first included in parts from late 2005 like -the 8548) has the ability to perform TCP, UDP, and IP checksums -in hardware. The Linux kernel only offloads the TCP and UDP -checksums (and always performs the pseudo header checksums), so -the driver only supports checksumming for TCP/IP and UDP/IP -packets. Use ethtool to enable or disable this feature for RX -and TX. - -VLAN - -In order to use VLAN, please consult Linux documentation on -configuring VLANs. The gianfar driver supports hardware insertion and -extraction of VLAN headers, but not filtering. Filtering will be -done by the kernel. - -MULTICASTING - -The gianfar driver supports using the group hash table on the -TSEC (and the extended hash table on the eTSEC) for multicast -filtering. On the eTSEC, the exact-match MAC registers are used -before the hash tables. See Linux documentation on how to join -multicast groups. - -PADDING - -The gianfar driver supports padding received frames with 2 bytes -to align the IP header to a 16-byte boundary, when supported by -hardware. - -ETHTOOL - -The gianfar driver supports the use of ethtool for many -configuration options. You must run ethtool only on currently -open interfaces. See ethtool documentation for details. diff --git a/Documentation/networking/device_drivers/index.rst b/Documentation/networking/device_drivers/index.rst index 7e59ee43c030..cec3415ee459 100644 --- a/Documentation/networking/device_drivers/index.rst +++ b/Documentation/networking/device_drivers/index.rst @@ -38,6 +38,7 @@ Contents: dec/dmfe dlink/dl2k freescale/dpaa + freescale/gianfar .. only:: subproject and html -- cgit From cf7eba49b2b160f98106b33ca12039b05d812140 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 1 May 2020 16:44:46 +0200 Subject: docs: networking: device drivers: convert intel/ipw2100.txt to ReST - add SPDX header; - adjust titles and chapters, adding proper markups; - comment out text-only TOC from html/pdf output; - use copyright symbol; - use :field: markup; - mark code blocks and literals as such; - mark tables as such; - adjust identation, whitespaces and blank lines where needed; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: David S. Miller --- Documentation/networking/device_drivers/index.rst | 1 + .../networking/device_drivers/intel/ipw2100.rst | 323 +++++++++++++++++++++ .../networking/device_drivers/intel/ipw2100.txt | 293 ------------------- MAINTAINERS | 2 +- drivers/net/wireless/intel/ipw2x00/Kconfig | 2 +- drivers/net/wireless/intel/ipw2x00/ipw2100.c | 2 +- 6 files changed, 327 insertions(+), 296 deletions(-) create mode 100644 Documentation/networking/device_drivers/intel/ipw2100.rst delete mode 100644 Documentation/networking/device_drivers/intel/ipw2100.txt diff --git a/Documentation/networking/device_drivers/index.rst b/Documentation/networking/device_drivers/index.rst index cec3415ee459..54ed10f3d1a7 100644 --- a/Documentation/networking/device_drivers/index.rst +++ b/Documentation/networking/device_drivers/index.rst @@ -39,6 +39,7 @@ Contents: dlink/dl2k freescale/dpaa freescale/gianfar + intel/ipw2100 .. only:: subproject and html diff --git a/Documentation/networking/device_drivers/intel/ipw2100.rst b/Documentation/networking/device_drivers/intel/ipw2100.rst new file mode 100644 index 000000000000..d54ad522f937 --- /dev/null +++ b/Documentation/networking/device_drivers/intel/ipw2100.rst @@ -0,0 +1,323 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: + +=========================================== +Intel(R) PRO/Wireless 2100 Driver for Linux +=========================================== + +Support for: + +- Intel(R) PRO/Wireless 2100 Network Connection + +Copyright |copy| 2003-2006, Intel Corporation + +README.ipw2100 + +:Version: git-1.1.5 +:Date: January 25, 2006 + +.. Index + + 0. IMPORTANT INFORMATION BEFORE USING THIS DRIVER + 1. Introduction + 2. Release git-1.1.5 Current Features + 3. Command Line Parameters + 4. Sysfs Helper Files + 5. Radio Kill Switch + 6. Dynamic Firmware + 7. Power Management + 8. Support + 9. License + + +0. IMPORTANT INFORMATION BEFORE USING THIS DRIVER +================================================= + +Important Notice FOR ALL USERS OR DISTRIBUTORS!!!! + +Intel wireless LAN adapters are engineered, manufactured, tested, and +quality checked to ensure that they meet all necessary local and +governmental regulatory agency requirements for the regions that they +are designated and/or marked to ship into. Since wireless LANs are +generally unlicensed devices that share spectrum with radars, +satellites, and other licensed and unlicensed devices, it is sometimes +necessary to dynamically detect, avoid, and limit usage to avoid +interference with these devices. In many instances Intel is required to +provide test data to prove regional and local compliance to regional and +governmental regulations before certification or approval to use the +product is granted. Intel's wireless LAN's EEPROM, firmware, and +software driver are designed to carefully control parameters that affect +radio operation and to ensure electromagnetic compliance (EMC). These +parameters include, without limitation, RF power, spectrum usage, +channel scanning, and human exposure. + +For these reasons Intel cannot permit any manipulation by third parties +of the software provided in binary format with the wireless WLAN +adapters (e.g., the EEPROM and firmware). Furthermore, if you use any +patches, utilities, or code with the Intel wireless LAN adapters that +have been manipulated by an unauthorized party (i.e., patches, +utilities, or code (including open source code modifications) which have +not been validated by Intel), (i) you will be solely responsible for +ensuring the regulatory compliance of the products, (ii) Intel will bear +no liability, under any theory of liability for any issues associated +with the modified products, including without limitation, claims under +the warranty and/or issues arising from regulatory non-compliance, and +(iii) Intel will not provide or be required to assist in providing +support to any third parties for such modified products. + +Note: Many regulatory agencies consider Wireless LAN adapters to be +modules, and accordingly, condition system-level regulatory approval +upon receipt and review of test data documenting that the antennas and +system configuration do not cause the EMC and radio operation to be +non-compliant. + +The drivers available for download from SourceForge are provided as a +part of a development project. Conformance to local regulatory +requirements is the responsibility of the individual developer. As +such, if you are interested in deploying or shipping a driver as part of +solution intended to be used for purposes other than development, please +obtain a tested driver from Intel Customer Support at: + +http://www.intel.com/support/wireless/sb/CS-006408.htm + +1. Introduction +=============== + +This document provides a brief overview of the features supported by the +IPW2100 driver project. The main project website, where the latest +development version of the driver can be found, is: + + http://ipw2100.sourceforge.net + +There you can find the not only the latest releases, but also information about +potential fixes and patches, as well as links to the development mailing list +for the driver project. + + +2. Release git-1.1.5 Current Supported Features +=============================================== + +- Managed (BSS) and Ad-Hoc (IBSS) +- WEP (shared key and open) +- Wireless Tools support +- 802.1x (tested with XSupplicant 1.0.1) + +Enabled (but not supported) features: +- Monitor/RFMon mode +- WPA/WPA2 + +The distinction between officially supported and enabled is a reflection +on the amount of validation and interoperability testing that has been +performed on a given feature. + + +3. Command Line Parameters +========================== + +If the driver is built as a module, the following optional parameters are used +by entering them on the command line with the modprobe command using this +syntax:: + + modprobe ipw2100 [