That's the third part (and the final one) of my work to convert the networking
text files into ReST. it is based on linux-next next-20200430 branch.
The full series (including those ones) are at:
https://git.linuxtv.org/mchehab/experimental.git/log/?h=net-docs
The built output documents, on html format is at:
https://www.infradead.org/~mchehab/kernel_docs/networking/
Mauro Carvalho Chehab (37):
docs: networking: convert tuntap.txt to ReST
docs: networking: convert udplite.txt to ReST
docs: networking: convert vrf.txt to ReST
docs: networking: convert vxlan.txt to ReST
docs: networking: convert x25-iface.txt to ReST
docs: networking: convert x25.txt to ReST
docs: networking: convert xfrm_device.txt to ReST
docs: networking: convert xfrm_proc.txt to ReST
docs: networking: convert xfrm_sync.txt to ReST
docs: networking: convert xfrm_sysctl.txt to ReST
docs: networking: convert z8530drv.txt to ReST
docs: networking: device drivers: convert 3com/3c509.txt to ReST
docs: networking: device drivers: convert 3com/vortex.txt to ReST
docs: networking: device drivers: convert amazon/ena.txt to ReST
docs: networking: device drivers: convert aquantia/atlantic.txt to
ReST
docs: networking: device drivers: convert chelsio/cxgb.txt to ReST
docs: networking: device drivers: convert cirrus/cs89x0.txt to ReST
docs: networking: device drivers: convert davicom/dm9000.txt to ReST
docs: networking: device drivers: convert dec/de4x5.txt to ReST
docs: networking: device drivers: convert dec/dmfe.txt to ReST
docs: networking: device drivers: convert dlink/dl2k.txt to ReST
docs: networking: device drivers: convert freescale/dpaa.txt to ReST
docs: networking: device drivers: convert freescale/gianfar.txt to
ReST
docs: networking: device drivers: convert intel/ipw2100.txt to ReST
docs: networking: device drivers: convert intel/ipw2200.txt to ReST
docs: networking: device drivers: convert microsoft/netvsc.txt to ReST
docs: networking: device drivers: convert neterion/s2io.txt to ReST
docs: networking: device drivers: convert neterion/vxge.txt to ReST
docs: networking: device drivers: convert qualcomm/rmnet.txt to ReST
docs: networking: device drivers: convert sb1000.txt to ReST
docs: networking: device drivers: convert smsc/smc9.txt to ReST
docs: networking: device drivers: convert ti/cpsw_switchdev.txt to
ReST
docs: networking: device drivers: convert ti/cpsw.txt to ReST
docs: networking: device drivers: convert ti/tlan.txt to ReST
docs: networking: device drivers: convert toshiba/spider_net.txt to
ReST
net: docs: add page_pool.rst to index.rst
docs: networking: arcnet-hardware.rst: don't duplicate chapter names
Documentation/networking/arcnet-hardware.rst | 8 +-
.../3com/{3c509.txt => 3c509.rst} | 158 +++--
.../3com/{vortex.txt => vortex.rst} | 223 ++++---
.../amazon/{ena.txt => ena.rst} | 142 ++--
.../aquantia/{atlantic.txt => atlantic.rst} | 373 ++++++-----
.../chelsio/{cxgb.txt => cxgb.rst} | 183 ++++--
.../cirrus/{cs89x0.txt => cs89x0.rst} | 557 ++++++++--------
.../davicom/{dm9000.txt => dm9000.rst} | 24 +-
.../dec/{de4x5.txt => de4x5.rst} | 105 +--
.../device_drivers/dec/{dmfe.txt => dmfe.rst} | 35 +-
.../dlink/{dl2k.txt => dl2k.rst} | 228 ++++---
.../freescale/{dpaa.txt => dpaa.rst} | 139 ++--
.../freescale/{gianfar.txt => gianfar.rst} | 21 +-
.../networking/device_drivers/index.rst | 24 +
.../intel/{ipw2100.txt => ipw2100.rst} | 242 ++++---
.../intel/{ipw2200.txt => ipw2200.rst} | 410 +++++++-----
.../microsoft/{netvsc.txt => netvsc.rst} | 57 +-
.../device_drivers/neterion/s2io.rst | 196 ++++++
.../device_drivers/neterion/s2io.txt | 141 ----
.../neterion/{vxge.txt => vxge.rst} | 60 +-
.../qualcomm/{rmnet.txt => rmnet.rst} | 43 +-
.../networking/device_drivers/sb1000.rst | 222 +++++++
.../networking/device_drivers/sb1000.txt | 207 ------
.../networking/device_drivers/smsc/smc9.rst | 49 ++
.../networking/device_drivers/smsc/smc9.txt | 42 --
.../networking/device_drivers/ti/cpsw.rst | 587 +++++++++++++++++
.../networking/device_drivers/ti/cpsw.txt | 541 ----------------
...{cpsw_switchdev.txt => cpsw_switchdev.rst} | 239 ++++---
.../device_drivers/ti/{tlan.txt => tlan.rst} | 73 ++-
.../{spider_net.txt => spider_net.rst} | 58 +-
Documentation/networking/index.rst | 12 +
.../networking/{tuntap.txt => tuntap.rst} | 200 +++---
.../networking/{udplite.txt => udplite.rst} | 175 ++---
Documentation/networking/vrf.rst | 451 +++++++++++++
Documentation/networking/vrf.txt | 418 ------------
.../networking/{vxlan.txt => vxlan.rst} | 33 +-
.../{x25-iface.txt => x25-iface.rst} | 10 +-
Documentation/networking/{x25.txt => x25.rst} | 4 +
.../{xfrm_device.txt => xfrm_device.rst} | 33 +-
.../{xfrm_proc.txt => xfrm_proc.rst} | 31 +
.../{xfrm_sync.txt => xfrm_sync.rst} | 66 +-
.../{xfrm_sysctl.txt => xfrm_sysctl.rst} | 7 +
.../networking/{z8530drv.txt => z8530drv.rst} | 609 +++++++++---------
MAINTAINERS | 30 +-
drivers/net/Kconfig | 4 +-
drivers/net/ethernet/3com/3c59x.c | 4 +-
drivers/net/ethernet/3com/Kconfig | 2 +-
drivers/net/ethernet/chelsio/Kconfig | 2 +-
drivers/net/ethernet/cirrus/Kconfig | 2 +-
drivers/net/ethernet/dec/tulip/Kconfig | 4 +-
drivers/net/ethernet/dlink/dl2k.c | 2 +-
drivers/net/ethernet/neterion/Kconfig | 4 +-
drivers/net/ethernet/smsc/Kconfig | 4 +-
drivers/net/ethernet/ti/Kconfig | 2 +-
drivers/net/ethernet/ti/tlan.c | 2 +-
drivers/net/hamradio/Kconfig | 4 +-
drivers/net/hamradio/scc.c | 2 +-
drivers/net/wireless/intel/ipw2x00/Kconfig | 4 +-
drivers/net/wireless/intel/ipw2x00/ipw2100.c | 2 +-
include/uapi/linux/if_x25.h | 2 +-
net/x25/Kconfig | 4 +-
61 files changed, 4175 insertions(+), 3341 deletions(-)
rename Documentation/networking/device_drivers/3com/{3c509.txt => 3c509.rst} (68%)
rename Documentation/networking/device_drivers/3com/{vortex.txt => vortex.rst} (72%)
rename Documentation/networking/device_drivers/amazon/{ena.txt => ena.rst} (86%)
rename Documentation/networking/device_drivers/aquantia/{atlantic.txt => atlantic.rst} (63%)
rename Documentation/networking/device_drivers/chelsio/{cxgb.txt => cxgb.rst} (81%)
rename Documentation/networking/device_drivers/cirrus/{cs89x0.txt => cs89x0.rst} (61%)
rename Documentation/networking/device_drivers/davicom/{dm9000.txt => dm9000.rst} (92%)
rename Documentation/networking/device_drivers/dec/{de4x5.txt => de4x5.rst} (78%)
rename Documentation/networking/device_drivers/dec/{dmfe.txt => dmfe.rst} (68%)
rename Documentation/networking/device_drivers/dlink/{dl2k.txt => dl2k.rst} (59%)
rename Documentation/networking/device_drivers/freescale/{dpaa.txt => dpaa.rst} (79%)
rename Documentation/networking/device_drivers/freescale/{gianfar.txt => gianfar.rst} (82%)
rename Documentation/networking/device_drivers/intel/{ipw2100.txt => ipw2100.rst} (70%)
rename Documentation/networking/device_drivers/intel/{ipw2200.txt => ipw2200.rst} (64%)
rename Documentation/networking/device_drivers/microsoft/{netvsc.txt => netvsc.rst} (83%)
create mode 100644 Documentation/networking/device_drivers/neterion/s2io.rst
delete mode 100644 Documentation/networking/device_drivers/neterion/s2io.txt
rename Documentation/networking/device_drivers/neterion/{vxge.txt => vxge.rst} (80%)
rename Documentation/networking/device_drivers/qualcomm/{rmnet.txt => rmnet.rst} (73%)
create mode 100644 Documentation/networking/device_drivers/sb1000.rst
delete mode 100644 Documentation/networking/device_drivers/sb1000.txt
create mode 100644 Documentation/networking/device_drivers/smsc/smc9.rst
delete mode 100644 Documentation/networking/device_drivers/smsc/smc9.txt
create mode 100644 Documentation/networking/device_drivers/ti/cpsw.rst
delete mode 100644 Documentation/networking/device_drivers/ti/cpsw.txt
rename Documentation/networking/device_drivers/ti/{cpsw_switchdev.txt => cpsw_switchdev.rst} (51%)
rename Documentation/networking/device_drivers/ti/{tlan.txt => tlan.rst} (73%)
rename Documentation/networking/device_drivers/toshiba/{spider_net.txt => spider_net.rst} (88%)
rename Documentation/networking/{tuntap.txt => tuntap.rst} (58%)
rename Documentation/networking/{udplite.txt => udplite.rst} (65%)
create mode 100644 Documentation/networking/vrf.rst
delete mode 100644 Documentation/networking/vrf.txt
rename Documentation/networking/{vxlan.txt => vxlan.rst} (73%)
rename Documentation/networking/{x25-iface.txt => x25-iface.rst} (96%)
rename Documentation/networking/{x25.txt => x25.rst} (96%)
rename Documentation/networking/{xfrm_device.txt => xfrm_device.rst} (92%)
rename Documentation/networking/{xfrm_proc.txt => xfrm_proc.rst} (95%)
rename Documentation/networking/{xfrm_sync.txt => xfrm_sync.rst} (82%)
rename Documentation/networking/{xfrm_sysctl.txt => xfrm_sysctl.rst} (52%)
rename Documentation/networking/{z8530drv.txt => z8530drv.rst} (57%)
--
2.25.4
- 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 <[email protected]>
---
.../amazon/{ena.txt => ena.rst} | 142 +++++++++++-------
.../networking/device_drivers/index.rst | 1 +
MAINTAINERS | 2 +-
3 files changed, 91 insertions(+), 54 deletions(-)
rename Documentation/networking/device_drivers/amazon/{ena.txt => ena.rst} (86%)
diff --git a/Documentation/networking/device_drivers/amazon/ena.txt b/Documentation/networking/device_drivers/amazon/ena.rst
similarity index 86%
rename from Documentation/networking/device_drivers/amazon/ena.txt
rename to Documentation/networking/device_drivers/amazon/ena.rst
index 1bb55c7b604c..11af6388ea87 100644
--- a/Documentation/networking/device_drivers/amazon/ena.txt
+++ b/Documentation/networking/device_drivers/amazon/ena.rst
@@ -1,8 +1,12 @@
-Linux kernel driver for Elastic Network Adapter (ENA) family:
-=============================================================
+.. SPDX-License-Identifier: GPL-2.0
+
+============================================================
+Linux kernel driver for Elastic Network Adapter (ENA) family
+============================================================
+
+Overview
+========
-Overview:
-=========
ENA is a networking interface designed to make good use of modern CPU
features and system architectures.
@@ -35,32 +39,40 @@ 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:
+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
===================================
-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.
+================= ======================================================
+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)
@@ -78,6 +90,7 @@ 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
@@ -96,12 +109,16 @@ 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 -
+ ==================== ===============
+ Link state change **X**
+ Fatal error **X**
Notification Suspend traffic
Notification Resume traffic
- Keep-Alive - X -
+ Keep-Alive **X**
+ ==================== ===============
ACQ and AENQ share the same MSI-X vector.
@@ -113,8 +130,8 @@ 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:
-====================
+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.
@@ -123,11 +140,15 @@ 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
@@ -142,6 +163,7 @@ Note: Not all ENA devices support LLQ, and this feature is negotiated
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.
@@ -151,8 +173,8 @@ benefits:
packet is running.
- In hardware interrupt re-direction.
-Interrupt Modes:
-================
+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).
@@ -163,9 +185,12 @@ 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:
+The management interrupt is named::
+
ena-mgmnt@pci:<PCI domain:bus:slot.function>
-and for each queue pair, an interrupt is named:
+
+and for each queue pair, an interrupt is named::
+
<interface name>-Tx-Rx-<queue index>
The ENA device operates in auto-mask and auto-clear interrupt
@@ -173,8 +198,8 @@ 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:
-=====================
+Interrupt Moderation
+====================
ENA driver and device can operate in conventional or adaptive interrupt
moderation mode.
@@ -202,45 +227,46 @@ 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:
-=============
+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:
-====
+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:
-===========
+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:
-====
+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:
-===================
+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:
-====
+RSS
+===
- The ENA device supports RSS that allows flexible Rx traffic
steering.
- Toeplitz and CRC32 hash functions are supported.
@@ -255,11 +281,13 @@ RSS:
- The user can provide a hash key, hash function, and configure the
indirection table through ethtool(8).
-DATA PATH:
-==========
-Tx:
----
+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.)
@@ -271,8 +299,10 @@ end_start_xmit() is called by the stack. This function does the following:
- 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.
@@ -280,14 +310,16 @@ end_start_xmit() is called by the stack. This function does the following:
- 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:
----
+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
@@ -296,13 +328,17 @@ Rx:
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 a45ab6a25942..990d1414ffd6 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -816,7 +816,7 @@ R: Saeed Bishara <[email protected]>
R: Zorik Machulsky <[email protected]>
L: [email protected]
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
--
2.25.4
- 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 <[email protected]>
---
.../dlink/{dl2k.txt => dl2k.rst} | 228 ++++++++++--------
.../networking/device_drivers/index.rst | 1 +
drivers/net/ethernet/dlink/dl2k.c | 2 +-
3 files changed, 132 insertions(+), 99 deletions(-)
rename Documentation/networking/device_drivers/dlink/{dl2k.txt => dl2k.rst} (59%)
diff --git a/Documentation/networking/device_drivers/dlink/dl2k.txt b/Documentation/networking/device_drivers/dlink/dl2k.rst
similarity index 59%
rename from Documentation/networking/device_drivers/dlink/dl2k.txt
rename to Documentation/networking/device_drivers/dlink/dl2k.rst
index cba74f7a3abc..ccdb5d0d7460 100644
--- a/Documentation/networking/device_drivers/dlink/dl2k.txt
+++ b/Documentation/networking/device_drivers/dlink/dl2k.rst
@@ -1,10 +1,13 @@
+.. SPDX-License-Identifier: GPL-2.0
- D-Link DL2000-based Gigabit Ethernet Adapter Installation
- for Linux
- May 23, 2002
+=========================================================
+D-Link DL2000-based Gigabit Ethernet Adapter Installation
+=========================================================
+
+May 23, 2002
+
+.. Contents
-Contents
-========
- Compatibility List
- Quick Install
- Compiling the Driver
@@ -15,12 +18,13 @@ Contents
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.
+- 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
@@ -34,28 +38,32 @@ on the environments below.
Quick Install
=============
-Install linux driver as following command:
+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
-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:
+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
+
+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.
+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.
@@ -73,93 +81,108 @@ 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
+::
+
+ [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
+::
+
+ [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
- -------------------
+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:
+ module enter the command::
- insmod dl2k.o
+ insmod dl2k.o
- or
+ or::
- insmod dl2k.o <optional parameter> ; add parameter
+ insmod dl2k.o <optional parameter> ; 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
- ===============================================================
+---------------------------------------------------------
+
+ 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:
+ it is necessary to issue the following command::
- ifconfig eth0 up
+ ifconfig eth0 up
Finally, to bind the driver to the active protocol (e.g., TCP/IP with
- Linux), enter the following command:
+ Linux), enter the following command::
- ifup eth0
+ 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:
+ The commands to unload a driver are as follows::
- ifdown eth0
- ifconfig eth0 down
- rmmod dl2k.o
+ 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.
+ to see the current network configuration::
- lsmod
- ifconfig
+ lsmod
+ ifconfig
- Automated Installation
- ----------------------
+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
- -----------------
+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:
+ /etc/modprobe.d/ directory. Add the following lines::
- alias ethx dl2k
- options dl2k <optional parameters>
+ alias ethx dl2k
+ options dl2k <optional parameters>
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
@@ -180,11 +203,15 @@ 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
+
+=============================== ==============================================
+mtu=packet_size Specifies the maximum packet size. default
is 1500.
-media=media_type - Specifies the media type the NIC operates at.
+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.
@@ -198,85 +225,90 @@ media=media_type - Specifies the media type the NIC operates at.
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
+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,
+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
+ 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
+
+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
+ 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.
+ 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
+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,
+
+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,
+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:
+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
+ 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.
+
+ 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
+ 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
+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,
+
+ 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.
*/
--
2.25.4
- 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 <[email protected]>
---
.../3com/{3c509.txt => 3c509.rst} | 158 +++++++++++-------
.../networking/device_drivers/index.rst | 1 +
2 files changed, 98 insertions(+), 61 deletions(-)
rename Documentation/networking/device_drivers/3com/{3c509.txt => 3c509.rst} (68%)
diff --git a/Documentation/networking/device_drivers/3com/3c509.txt b/Documentation/networking/device_drivers/3com/3c509.rst
similarity index 68%
rename from Documentation/networking/device_drivers/3com/3c509.txt
rename to Documentation/networking/device_drivers/3com/3c509.rst
index fbf722e15ac3..47f706bacdd9 100644
--- a/Documentation/networking/device_drivers/3com/3c509.txt
+++ b/Documentation/networking/device_drivers/3com/3c509.rst
@@ -1,17 +1,21 @@
+.. 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 <[email protected]>
-----------------------------------------------------------------------------
-
-(0) Introduction
+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
@@ -21,11 +25,11 @@ be (but sometimes are) confused with the similarly-numbered PCI-bus "3c905"
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)
+ - 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
@@ -33,32 +37,34 @@ 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
+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:
+for LILO parameters for doing this::
- ether=10,0x310,3,0x3c509,eth0
+ 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:
+option::
options 3c509 irq=10,11
-(2) Full-duplex mode
+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:
+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
@@ -78,27 +84,32 @@ 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.
+.. warning::
-(3) Available Transceiver Types
+ 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)
@@ -106,6 +117,7 @@ For versions of the driver v1.18c and above, the available transceiver types are
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
@@ -116,26 +128,30 @@ 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
+
+Interpretation of error messages and common problems
+----------------------------------------------------
Error Messages
+^^^^^^^^^^^^^^
-eth0: Infinite loop in interrupt, status 2011.
+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.
+ 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.
+ interrupt should always be incrementing faster than the others.
+
+No received packets
+^^^^^^^^^^^^^^^^^^^
-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
@@ -146,26 +162,37 @@ 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
+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.
+likely have an unterminated network or the incorrect media transceiver selected.
+
+3c509B card is not detected on machines with an ISA PnP BIOS.
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-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.
+setup program.
+
+3c509 card is not detected on overclocked machines
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-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.
+to an absurdly high value, such as 5000.
-(4b) Decoding Status and Error Messages
+Decoding Status and Error Messages
+----------------------------------
-The bits in the main status register are:
+The bits in the main status register are:
+
+===== ======================================
value description
+===== ======================================
0x01 Interrupt latch
0x02 Tx overrun, or Rx underrun
0x04 Tx complete
@@ -174,30 +201,38 @@ value description
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:
+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).
+===== ============================================
+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
+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
+0x82
+^^^^
+
Out of window collision. This typically occurs when some other Ethernet
-host is incorrectly set to full duplex on a half duplex network.
+host is incorrectly set to full duplex on a half duplex network.
+
+0x88
+^^^^
-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
@@ -207,7 +242,8 @@ 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)
+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
--
2.25.4
- 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 <[email protected]>
---
.../freescale/{dpaa.txt => dpaa.rst} | 139 ++++++++++--------
.../networking/device_drivers/index.rst | 1 +
2 files changed, 75 insertions(+), 65 deletions(-)
rename Documentation/networking/device_drivers/freescale/{dpaa.txt => dpaa.rst} (79%)
diff --git a/Documentation/networking/device_drivers/freescale/dpaa.txt b/Documentation/networking/device_drivers/freescale/dpaa.rst
similarity index 79%
rename from Documentation/networking/device_drivers/freescale/dpaa.txt
rename to Documentation/networking/device_drivers/freescale/dpaa.rst
index b06601ff9200..241c6c6f6e68 100644
--- a/Documentation/networking/device_drivers/freescale/dpaa.txt
+++ b/Documentation/networking/device_drivers/freescale/dpaa.rst
@@ -1,12 +1,14 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==============================
The QorIQ DPAA Ethernet Driver
==============================
Authors:
-Madalin Bucur <[email protected]>
-Camelia Groza <[email protected]>
+- Madalin Bucur <[email protected]>
+- Camelia Groza <[email protected]>
-Contents
-========
+.. Contents
- DPAA Ethernet Overview
- DPAA Ethernet Supported SoCs
@@ -34,7 +36,7 @@ following drivers in the Linux kernel:
- Queue Manager (QMan), Buffer Manager (BMan)
drivers/soc/fsl/qbman
-A simplified view of the dpaa_eth interfaces mapped to FMan MACs:
+A simplified view of the dpaa_eth interfaces mapped to FMan MACs::
dpaa_eth /eth0\ ... /ethN\
driver | | | |
@@ -42,89 +44,93 @@ A simplified view of the dpaa_eth interfaces mapped to FMan MACs:
-Ports / Tx Rx \ ... / Tx Rx \
FMan | | | |
-MACs | MAC0 | | MACN |
- / dtsec0 \ ... / dtsecN \ (or tgec)
- / \ / \(or memac)
+ / 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:
- ________________________________
+The dpaa_eth relation to the QMan, BMan and FMan::
+
+ ________________________________
dpaa_eth / eth0 \
driver / \
--------- -^- -^- -^- --- ---------
QMan driver / \ / \ / \ \ / | BMan |
- |Rx | |Rx | |Tx | |Tx | | driver |
+ |Rx | |Rx | |Tx | |Tx | | driver |
--------- |Dfl| |Err| |Cnf| |FQs| | |
QMan HW |FQ | |FQ | |FQs| | | | |
- / \ / \ / \ \ / | |
+ / \ / \ / \ \ / | |
--------- --- --- --- -v- ---------
- | FMan QMI | |
- | FMan HW FMan BMI | BMan HW |
- ----------------------- --------
+ | 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 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
+PPC
+- P1023
+- P2041
+- P3041
+- P4080
+- P5020
+- P5040
+- T1023
+- T1024
+- T1040
+- T1042
+- T2080
+- T4240
+- B4860
-# ARM
-LS1043A
-LS1046A
+ARM
+- LS1043A
+- LS1046A
Configuring DPAA Ethernet in your kernel
========================================
-To enable the DPAA Ethernet driver, the following Kconfig options are required:
+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
+ # 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
+ # 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
+ # 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
==============================
@@ -167,7 +173,9 @@ classes as follows:
* priorities 8 to 11 - traffic class 2 (medium-high priority)
* priorities 12 to 15 - traffic class 3 (high priority)
-tc qdisc add dev <int> root handle 1: \
+::
+
+ tc qdisc add dev <int> 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
@@ -201,11 +209,11 @@ 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.
+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:
+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
@@ -216,7 +224,7 @@ 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.:
+on or off through ethtool, i.e.::
# ethtool -K fm1-mac9 rx-hashing off
# ethtool -k fm1-mac9 | grep hash
@@ -246,6 +254,7 @@ The following statistics are exported for each interface through ethtool:
- 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
@@ -254,7 +263,7 @@ The following statistics are exported for each interface through ethtool:
The driver also exports the following information in sysfs:
- the FQ IDs for each FQ type
- /sys/devices/platform/soc/<addr>.fman/<addr>.ethernet/dpaa-ethernet.<id>/net/fm<nr>-mac<nr>/fqids
+ /sys/devices/platform/soc/<addr>.fman/<addr>.ethernet/dpaa-ethernet.<id>/net/fm<nr>-mac<nr>/fqids
- the ID of the buffer pool in use
- /sys/devices/platform/soc/<addr>.fman/<addr>.ethernet/dpaa-ethernet.<id>/net/fm<nr>-mac<nr>/bpids
+ /sys/devices/platform/soc/<addr>.fman/<addr>.ethernet/dpaa-ethernet.<id>/net/fm<nr>-mac<nr>/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
--
2.25.4
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 <[email protected]>
---
Documentation/networking/index.rst | 1 +
.../networking/{x25-iface.txt => x25-iface.rst} | 10 ++++++++--
include/uapi/linux/if_x25.h | 2 +-
net/x25/Kconfig | 2 +-
4 files changed, 11 insertions(+), 4 deletions(-)
rename Documentation/networking/{x25-iface.txt => x25-iface.rst} (96%)
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.txt b/Documentation/networking/x25-iface.rst
similarity index 96%
rename from Documentation/networking/x25-iface.txt
rename to Documentation/networking/x25-iface.rst
index 7f213b556e85..df401891dce6 100644
--- a/Documentation/networking/x25-iface.txt
+++ b/Documentation/networking/x25-iface.rst
@@ -1,4 +1,10 @@
- X.25 Device Driver Interface 1.1
+.. SPDX-License-Identifier: GPL-2.0
+
+============================-
+X.25 Device Driver Interface
+============================-
+
+Version 1.1
Jonathan Naylor 26.12.96
@@ -99,7 +105,7 @@ 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.
+ to the peer.
This will reliably suppress packet loss. The LAPB protocol will
automatically cause the peer to re-transmit the dropped packet
later.
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 <linux/types.h>
-/* 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
<http://docwiki.cisco.com/wiki/X.25>.
Information about X.25 for Linux is contained in the files
<file:Documentation/networking/x25.txt> and
- <file:Documentation/networking/x25-iface.txt>.
+ <file:Documentation/networking/x25-iface.rst>.
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
--
2.25.4
- 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 <[email protected]>
---
.../dec/{de4x5.txt => de4x5.rst} | 105 ++++++++++--------
.../networking/device_drivers/index.rst | 1 +
drivers/net/ethernet/dec/tulip/Kconfig | 2 +-
3 files changed, 60 insertions(+), 48 deletions(-)
rename Documentation/networking/device_drivers/dec/{de4x5.txt => de4x5.rst} (78%)
diff --git a/Documentation/networking/device_drivers/dec/de4x5.txt b/Documentation/networking/device_drivers/dec/de4x5.rst
similarity index 78%
rename from Documentation/networking/device_drivers/dec/de4x5.txt
rename to Documentation/networking/device_drivers/dec/de4x5.rst
index 452aac58341d..e03e9c631879 100644
--- a/Documentation/networking/device_drivers/dec/de4x5.txt
+++ b/Documentation/networking/device_drivers/dec/de4x5.rst
@@ -1,48 +1,54 @@
+.. 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
+ - 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
+ - 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!)
+ - 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:
+ 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
+ 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
@@ -55,31 +61,33 @@
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.
+ 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:
+ 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
+ insmod de4x5 io=0xghh where g = bus number
+ hh = device number
- NB: autoprobing for modules is now supported by default. You may just
- use:
+ .. note::
- insmod de4x5
+ autoprobing for modules is now supported by default. You may just
+ use::
- to load all available boards. For a specific board, still 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).
+ 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.
+ 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).
+ 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)
+ 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
@@ -90,7 +98,7 @@
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.
+ '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
@@ -158,18 +166,21 @@
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:
+ ========= ===============================================
+ 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:
+ upper case. Examples::
- insmod de4x5 args='eth1:fdx autosense=BNC eth0:autosense=100Mb'.
+ 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"'
+ 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
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
- <file:Documentation/networking/device_drivers/dec/de4x5.txt>.
+ <file:Documentation/networking/device_drivers/dec/de4x5.rst>.
To compile this driver as a module, choose M here. The module will
be called de4x5.
--
2.25.4
- add SPDX header;
- adjust titles and chapters, adding proper markups;
- use :field: markup;
- add to networking/index.rst.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
.../freescale/{gianfar.txt => gianfar.rst} | 21 +++++++++++++------
.../networking/device_drivers/index.rst | 1 +
2 files changed, 16 insertions(+), 6 deletions(-)
rename Documentation/networking/device_drivers/freescale/{gianfar.txt => gianfar.rst} (82%)
diff --git a/Documentation/networking/device_drivers/freescale/gianfar.txt b/Documentation/networking/device_drivers/freescale/gianfar.rst
similarity index 82%
rename from Documentation/networking/device_drivers/freescale/gianfar.txt
rename to Documentation/networking/device_drivers/freescale/gianfar.rst
index ba1daea7f2e4..9c4a91d3824b 100644
--- a/Documentation/networking/device_drivers/freescale/gianfar.txt
+++ b/Documentation/networking/device_drivers/freescale/gianfar.rst
@@ -1,10 +1,15 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===========================
The Gianfar Ethernet Driver
+===========================
-Author: Andy Fleming <[email protected]>
-Updated: 2005-07-28
+:Author: Andy Fleming <[email protected]>
+:Updated: 2005-07-28
-CHECKSUM OFFLOADING
+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
@@ -15,13 +20,15 @@ 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
+Multicasting
+============
The gianfar driver supports using the group hash table on the
TSEC (and the extended hash table on the eTSEC) for multicast
@@ -29,13 +36,15 @@ 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
+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
+Ethtool
+=======
The gianfar driver supports the use of ethtool for many
configuration options. You must run ethtool only on currently
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
--
2.25.4
- 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 <[email protected]>
---
.../aquantia/{atlantic.txt => atlantic.rst} | 373 +++++++++++-------
.../networking/device_drivers/index.rst | 1 +
MAINTAINERS | 2 +-
3 files changed, 227 insertions(+), 149 deletions(-)
rename Documentation/networking/device_drivers/aquantia/{atlantic.txt => atlantic.rst} (63%)
diff --git a/Documentation/networking/device_drivers/aquantia/atlantic.txt b/Documentation/networking/device_drivers/aquantia/atlantic.rst
similarity index 63%
rename from Documentation/networking/device_drivers/aquantia/atlantic.txt
rename to Documentation/networking/device_drivers/aquantia/atlantic.rst
index 2013fcedc2da..595ddef1c8b3 100644
--- a/Documentation/networking/device_drivers/aquantia/atlantic.txt
+++ b/Documentation/networking/device_drivers/aquantia/atlantic.rst
@@ -1,83 +1,96 @@
-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
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
+
+===============================
+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.
+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.
+This release tested with passive Direct Attach Cables (DAC) and SFP+/LC
+Optical Transceiver.
Configuration
-=========================
- Viewing Link Messages
- ---------------------
+=============
+
+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:
+ your console, set dmesg to eight by entering the following::
dmesg -n 8
- NOTE: This setting is not saved across reboots.
+ .. note::
- Jumbo Frames
- ------------
+ 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:
+ increase the MTU size. For example::
- ip link set mtu 16000 dev enp1s0
+ ip link set mtu 16000 dev enp1s0
- ethtool
- -------
+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
+----
NAPI (Rx polling mode) is supported in the atlantic driver.
Supported ethtool options
-============================
- Viewing adapter settings
- ---------------------
- ethtool <ethX>
+=========================
- Output example:
+Viewing adapter settings
+------------------------
+
+ ::
+
+ ethtool <ethX>
+
+ Output example::
Settings for enp1s0:
Supported ports: [ TP ]
Supported link modes: 100baseT/Full
- 1000baseT/Full
- 10000baseT/Full
- 2500baseT/Full
- 5000baseT/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
+ 1000baseT/Full
+ 10000baseT/Full
+ 2500baseT/Full
+ 5000baseT/Full
Advertised pause frame use: Symmetric
Advertised auto-negotiation: Yes
Advertised FEC modes: Not reported
@@ -92,16 +105,22 @@ Supported ethtool options
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:
+
+ .. 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 <ethX>
+Viewing adapter information
+---------------------------
- Output example:
+ ::
+
+ ethtool -i <ethX>
+
+ Output example::
driver: atlantic
version: 5.2.0-050200rc5-generic-kern
@@ -115,12 +134,16 @@ Supported ethtool options
supports-priv-flags: no
- Viewing Ethernet adapter statistics:
- ---------------------
- ethtool -S <ethX>
+Viewing Ethernet adapter statistics
+-----------------------------------
- Output example:
- NIC statistics:
+ ::
+
+ ethtool -S <ethX>
+
+ Output example::
+
+ NIC statistics:
InPackets: 13238607
InUCast: 13293852
InMCast: 52
@@ -164,85 +187,95 @@ Supported ethtool options
Queue[3] InLroPackets: 0
Queue[3] InErrors: 0
- Interrupt coalescing support
- ---------------------------------
- ITR mode, TX/RX coalescing timings could be viewed with:
+Interrupt coalescing support
+----------------------------
- ethtool -c <ethX>
+ ITR mode, TX/RX coalescing timings could be viewed with::
- and changed with:
+ ethtool -c <ethX>
- ethtool -C <ethX> tx-usecs <usecs> rx-usecs <usecs>
+ and changed with::
- To disable coalescing:
+ ethtool -C <ethX> tx-usecs <usecs> rx-usecs <usecs>
- ethtool -C <ethX> tx-usecs 0 rx-usecs 0 tx-max-frames 1 tx-max-frames 1
+ To disable coalescing::
- Wake on LAN support
- ---------------------------------
+ ethtool -C <ethX> tx-usecs 0 rx-usecs 0 tx-max-frames 1 tx-max-frames 1
- WOL support by magic packet:
+Wake on LAN support
+-------------------
- ethtool -s <ethX> wol g
+ WOL support by magic packet::
- To disable WOL:
+ ethtool -s <ethX> wol g
- ethtool -s <ethX> wol d
+ To disable WOL::
- Set and check the driver message level
- ---------------------------------
+ ethtool -s <ethX> wol d
+
+Set and check the driver message level
+--------------------------------------
Set message level
- ethtool -s <ethX> msglvl <level>
+ ::
+
+ ethtool -s <ethX> msglvl <level>
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.
+ ====== =============================
+ 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 <ethX> | grep "Current message level"
+ ::
- If you want to disable the output of messages
+ ethtool <ethX> | grep "Current message level"
- ethtool -s <ethX> msglvl 0
+ If you want to disable the output of messages::
+
+ ethtool -s <ethX> msglvl 0
+
+RX flow rules (ntuple filters)
+------------------------------
- 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 <device> <filter>".
+ via ``ethtool -N <device> <filter>``.
- To enable or disable the RX flow rules:
+ To enable or disable the RX flow rules::
- ethtool -K ethX ntuple <on|off>
+ ethtool -K ethX ntuple <on|off>
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)
@@ -253,32 +286,34 @@ Supported ethtool options
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:
+ To add a filter that directs packet to queue 5, use
+ ``<-N|-U|--config-nfc|--config-ntuple>`` switch::
- ethtool -N <ethX> flow-type udp4 src-ip 10.0.0.1 dst-ip 10.0.0.2 src-port 2000 dst-port 2001 action 5 <loc 32>
+ ethtool -N <ethX> flow-type udp4 src-ip 10.0.0.1 dst-ip 10.0.0.2 src-port 2000 dst-port 2001 action 5 <loc 32>
- 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
+ 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 ``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:
+ Example filter for IPv6 filter traffic::
- sudo ethtool -N <ethX> flow-type tcp6 src-ip 2001:db8:0:f101::1 dst-ip 2001:db8:0:f101::2 action 1 loc 32
- sudo ethtool -N <ethX> flow-type ip6 src-ip 2001:db8:0:f101::2 dst-ip 2001:db8:0:f101::5 action -1 loc 36
+ sudo ethtool -N <ethX> flow-type tcp6 src-ip 2001:db8:0:f101::1 dst-ip 2001:db8:0:f101::2 action 1 loc 32
+ sudo ethtool -N <ethX> flow-type ip6 src-ip 2001:db8:0:f101::2 dst-ip 2001:db8:0:f101::5 action -1 loc 36
- Example filter for IPv4 filter traffic:
+ Example filter for IPv4 filter traffic::
- sudo ethtool -N <ethX> flow-type udp4 src-ip 10.0.0.4 dst-ip 10.0.0.7 src-port 2000 dst-port 2001 loc 32
- sudo ethtool -N <ethX> flow-type tcp4 src-ip 10.0.0.3 dst-ip 10.0.0.9 src-port 2000 dst-port 2001 loc 33
- sudo ethtool -N <ethX> flow-type ip4 src-ip 10.0.0.6 dst-ip 10.0.0.4 loc 34
+ sudo ethtool -N <ethX> flow-type udp4 src-ip 10.0.0.4 dst-ip 10.0.0.7 src-port 2000 dst-port 2001 loc 32
+ sudo ethtool -N <ethX> flow-type tcp4 src-ip 10.0.0.3 dst-ip 10.0.0.9 src-port 2000 dst-port 2001 loc 33
+ sudo ethtool -N <ethX> 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.
@@ -287,8 +322,9 @@ Supported ethtool options
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 <ethX> flow-type ip4 vlan 2001 m 0xF000 action 1 loc 0
+ To add a filter that directs packets from VLAN 2001 to queue 5::
+
+ ethtool -N <ethX> flow-type ip4 vlan 2001 m 0xF000 action 1 loc 0
L2 EtherType filters allows filter packet by EtherType field or both EtherType
@@ -297,17 +333,17 @@ Supported ethtool options
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 <ethX> flow-type ether proto 0x800 vlan 0x600 m 0x1FFF action 3 loc 16
+ To add a filter that directs IP4 packess of priority 3 to queue 3::
+ ethtool -N <ethX> flow-type ether proto 0x800 vlan 0x600 m 0x1FFF action 3 loc 16
- To see the list of filters currently present:
+ To see the list of filters currently present::
- ethtool <-u|-n|--show-nfc|--show-ntuple> <ethX>
+ ethtool <-u|-n|--show-nfc|--show-ntuple> <ethX>
- Rules may be deleted from the table itself. This is done using:
+ Rules may be deleted from the table itself. This is done using::
- sudo ethtool <-N|-U|--config-nfc|--config-ntuple> <ethX> delete <loc>
+ sudo ethtool <-N|-U|--config-nfc|--config-ntuple> <ethX> delete <loc>
- loc is the rule number to be deleted.
@@ -316,34 +352,37 @@ Supported ethtool options
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
- ---------------------------------
+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
+ Example::
+
+ ethtool -N eth0 flow-type udp4 action 0 loc 32
+
+UDP GSO hardware offload
+------------------------
- 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/
+ 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:
+ UDP GSO is configured by::
ethtool -K eth0 tx-udp-segmentation on
- Private flags (testing)
- ---------------------------------
+Private flags (testing)
+-----------------------
- Atlantic driver supports private flags for hardware custom features:
+ Atlantic driver supports private flags for hardware custom features::
$ ethtool --show-priv-flags ethX
@@ -354,7 +393,7 @@ Supported ethtool options
PHYInternalLoopback: off
PHYExternalLoopback: off
- Example:
+ Example::
$ ethtool --set-priv-flags ethX DMASystemLoopback on
@@ -370,93 +409,130 @@ 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.
+
+====== ==============================================================
+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)
+.. 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.
+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
+
+== ========
+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.
+
+The system consumes less energy but it also introduces more latency in packets
+processing.
Valid values
-0 - disabled
-1 - enabled
+
+== ========
+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.
@@ -472,7 +548,8 @@ License
=======
aQuantia Corporation Network Driver
-Copyright(c) 2014 - 2019 aQuantia Corporation.
+
+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,
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 990d1414ffd6..91098b704635 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -1280,7 +1280,7 @@ L: [email protected]
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
--
2.25.4
- 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 <[email protected]>
---
Documentation/networking/index.rst | 1 +
.../{xfrm_proc.txt => xfrm_proc.rst} | 31 +++++++++++++++++++
2 files changed, 32 insertions(+)
rename Documentation/networking/{xfrm_proc.txt => xfrm_proc.rst} (95%)
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.txt b/Documentation/networking/xfrm_proc.rst
similarity index 95%
rename from Documentation/networking/xfrm_proc.txt
rename to Documentation/networking/xfrm_proc.rst
index 2eae619ab67b..0a771c5a7399 100644
--- a/Documentation/networking/xfrm_proc.txt
+++ b/Documentation/networking/xfrm_proc.rst
@@ -1,5 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==================================
XFRM proc - /proc/net/xfrm_* files
==================================
+
Masahide NAKAMURA <[email protected]>
@@ -14,42 +18,58 @@ as part of the linux private MIB. These counters can be viewed in
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
@@ -57,26 +77,37 @@ 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
--
2.25.4
- 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 <[email protected]>
---
Documentation/networking/index.rst | 1 +
.../networking/{tuntap.txt => tuntap.rst} | 200 ++++++++++--------
MAINTAINERS | 2 +-
drivers/net/Kconfig | 2 +-
4 files changed, 119 insertions(+), 86 deletions(-)
rename Documentation/networking/{tuntap.txt => tuntap.rst} (58%)
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.txt b/Documentation/networking/tuntap.rst
similarity index 58%
rename from Documentation/networking/tuntap.txt
rename to Documentation/networking/tuntap.rst
index 0104830d5075..a59d1dd6fdcc 100644
--- a/Documentation/networking/tuntap.txt
+++ b/Documentation/networking/tuntap.rst
@@ -1,20 +1,28 @@
-Universal TUN/TAP device driver.
-Copyright (C) 1999-2000 Maxim Krasnyansky <[email protected]>
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
- Linux, Solaris drivers
- Copyright (C) 1999-2000 Maxim Krasnyansky <[email protected]>
+===============================
+Universal TUN/TAP device driver
+===============================
- FreeBSD TAP driver
- Copyright (c) 1999-2000 Maksim Yevmenkin <[email protected]>
+Copyright |copy| 1999-2000 Maxim Krasnyansky <[email protected]>
+
+ Linux, Solaris drivers
+ Copyright |copy| 1999-2000 Maxim Krasnyansky <[email protected]>
+
+ FreeBSD TAP driver
+ Copyright |copy| 1999-2000 Maksim Yevmenkin <[email protected]>
Revision of this document 2002 by Florian Thiel <[email protected]>
1. Description
- TUN/TAP provides packet reception and transmission for user space programs.
+==============
+
+ 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.
+ 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
@@ -33,41 +41,51 @@ Copyright (C) 1999-2000 Maxim Krasnyansky <[email protected]>
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:
+2. Configuration
+================
+
+ Create device node::
+
mkdir /dev/net (if it doesn't exist already)
mknod /dev/net/tun c 10 200
-
- Set permissions:
+
+ 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.
+
+ 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
+
+ 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:
+3. Program interface
+====================
- 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")
+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 <linux/if.h>
#include <linux/if_tun.h>
@@ -78,45 +96,51 @@ Copyright (C) 1999-2000 Maxim Krasnyansky <[email protected]>
int fd, err;
if( (fd = open("/dev/net/tun", O_RDWR)) < 0 )
- return tun_alloc_old(dev);
+ return tun_alloc_old(dev);
memset(&ifr, 0, sizeof(ifr));
- /* Flags: IFF_TUN - TUN device (no Ethernet headers)
- * IFF_TAP - TAP device
+ /* 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;
+ * IFF_NO_PI - Do not provide packet information
+ */
+ ifr.ifr_flags = IFF_TUN;
if( *dev )
- strncpy(ifr.ifr_name, dev, IFNAMSIZ);
+ strncpy(ifr.ifr_name, dev, IFNAMSIZ);
if( (err = ioctl(fd, TUNSETIFF, (void *) &ifr)) < 0 ){
- close(fd);
- return err;
+ 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:
+ }
+
+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:
+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.
+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.
+``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 <linux/if.h>
#include <linux/if_tun.h>
@@ -127,7 +151,7 @@ Copyright (C) 1999-2000 Maxim Krasnyansky <[email protected]>
int fd, err, i;
if (!dev)
- return -1;
+ return -1;
memset(&ifr, 0, sizeof(ifr));
/* Flags: IFF_TUN - TUN device (no Ethernet headers)
@@ -140,30 +164,30 @@ Copyright (C) 1999-2000 Maxim Krasnyansky <[email protected]>
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;
+ 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]);
+ 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.
+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
+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 <linux/if.h>
#include <linux/if_tun.h>
@@ -175,53 +199,61 @@ Copyright (C) 1999-2000 Maxim Krasnyansky <[email protected]>
memset(&ifr, 0, sizeof(ifr));
if (enable)
- ifr.ifr_flags = IFF_ATTACH_QUEUE;
+ ifr.ifr_flags = IFF_ATTACH_QUEUE;
else
- ifr.ifr_flags = IFF_DETACH_QUEUE;
+ ifr.ifr_flags = IFF_DETACH_QUEUE;
return ioctl(fd, TUNSETQUEUE, (void *)&ifr);
}
-Universal TUN/TAP device driver Frequently Asked Question.
-
+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
+
+ - 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.
+
+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 ?
+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.
+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
+(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,
+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.
+
+Yes. Linux and FreeBSD drivers support Ethernet bridging.
diff --git a/MAINTAINERS b/MAINTAINERS
index 64789b29c085..35bd81b436e1 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -17207,7 +17207,7 @@ TUN/TAP driver
M: Maxim Krasnyansky <[email protected]>
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 <file:Documentation/networking/tuntap.txt> for more
+ Please read <file:Documentation/networking/tuntap.rst> for more
information.
To compile this driver as a module, choose M here: the module
--
2.25.4
- 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 <[email protected]>
---
Documentation/networking/index.rst | 1 +
.../networking/{vxlan.txt => vxlan.rst} | 33 ++++++++++++-------
2 files changed, 22 insertions(+), 12 deletions(-)
rename Documentation/networking/{vxlan.txt => vxlan.rst} (73%)
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.txt b/Documentation/networking/vxlan.rst
similarity index 73%
rename from Documentation/networking/vxlan.txt
rename to Documentation/networking/vxlan.rst
index c28f4989c3f0..ce239fa01848 100644
--- a/Documentation/networking/vxlan.txt
+++ b/Documentation/networking/vxlan.rst
@@ -1,3 +1,6 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+======================================================
Virtual eXtensible Local Area Networking documentation
======================================================
@@ -21,8 +24,9 @@ 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
+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
@@ -32,20 +36,25 @@ 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
+2. Delete vxlan device::
-3. Show vxlan info
- # ip -d link show vxlan0
+ # 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
+1. Create forwarding table entry::
-2. Delete forwarding table entry
- # bridge fdb delete 00:17:42:8a:b4:05 dev vxlan0
+ # bridge fdb add to 00:17:42:8a:b4:05 dst 192.19.0.2 dev vxlan0
-3. Show forwarding table
- # bridge fdb show 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
--
2.25.4
On 01/05/2020 5:44 pm, Mauro Carvalho Chehab wrote:
> External Email
>
> ----------------------------------------------------------------------
> - 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 <[email protected]>
Acked-by: Igor Russkikh <[email protected]>
Thanks alot, Mauro, for this conversion!
Igor