[PATCH 02/37] docs: networking: convert udplite.txt to ReST
From: Mauro Carvalho Chehab
Date: Fri May 01 2020 - 10:48:05 EST
- add SPDX header;
- adjust titles and chapters, adding proper markups;
- mark lists as such;
- mark tables as such;
- mark code blocks and literals as such;
- adjust identation, whitespaces and blank lines where needed;
- add to networking/index.rst.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx>
---
Documentation/networking/index.rst | 1 +
.../networking/{udplite.txt => udplite.rst} | 175 ++++++++++--------
2 files changed, 95 insertions(+), 81 deletions(-)
rename Documentation/networking/{udplite.txt => udplite.rst} (65%)
diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst
index e7a683f0528d..ca0b0dbfd9ad 100644
--- a/Documentation/networking/index.rst
+++ b/Documentation/networking/index.rst
@@ -112,6 +112,7 @@ Contents:
timestamping
tproxy
tuntap
+ udplite
.. only:: subproject and html
diff --git a/Documentation/networking/udplite.txt b/Documentation/networking/udplite.rst
similarity index 65%
rename from Documentation/networking/udplite.txt
rename to Documentation/networking/udplite.rst
index 53a726855e49..2c225f28b7b2 100644
--- a/Documentation/networking/udplite.txt
+++ b/Documentation/networking/udplite.rst
@@ -1,6 +1,8 @@
- ===========================================================================
- The UDP-Lite protocol (RFC 3828)
- ===========================================================================
+.. SPDX-License-Identifier: GPL-2.0
+
+================================
+The UDP-Lite protocol (RFC 3828)
+================================
UDP-Lite is a Standards-Track IETF transport protocol whose characteristic
@@ -11,39 +13,43 @@
This file briefly describes the existing kernel support and the socket API.
For in-depth information, you can consult:
- o The UDP-Lite Homepage:
- http://web.archive.org/web/*/http://www.erg.abdn.ac.uk/users/gerrit/udp-lite/
- From here you can also download some example application source code.
+ - The UDP-Lite Homepage:
+ http://web.archive.org/web/%2E/http://www.erg.abdn.ac.uk/users/gerrit/udp-lite/
- o The UDP-Lite HOWTO on
- http://web.archive.org/web/*/http://www.erg.abdn.ac.uk/users/gerrit/udp-lite/
- files/UDP-Lite-HOWTO.txt
+ From here you can also download some example application source code.
- o The Wireshark UDP-Lite WiKi (with capture files):
- https://wiki.wireshark.org/Lightweight_User_Datagram_Protocol
+ - The UDP-Lite HOWTO on
+ http://web.archive.org/web/%2E/http://www.erg.abdn.ac.uk/users/gerrit/udp-lite/files/UDP-Lite-HOWTO.txt
- o The Protocol Spec, RFC 3828, http://www.ietf.org/rfc/rfc3828.txt
+ - The Wireshark UDP-Lite WiKi (with capture files):
+ https://wiki.wireshark.org/Lightweight_User_Datagram_Protocol
+ - The Protocol Spec, RFC 3828, http://www.ietf.org/rfc/rfc3828.txt
- I) APPLICATIONS
+
+1. Applications
+===============
Several applications have been ported successfully to UDP-Lite. Ethereal
- (now called wireshark) has UDP-Litev4/v6 support by default.
+ (now called wireshark) has UDP-Litev4/v6 support by default.
+
Porting applications to UDP-Lite is straightforward: only socket level and
IPPROTO need to be changed; senders additionally set the checksum coverage
length (default = header length = 8). Details are in the next section.
-
- II) PROGRAMMING API
+2. Programming API
+==================
UDP-Lite provides a connectionless, unreliable datagram service and hence
uses the same socket type as UDP. In fact, porting from UDP to UDP-Lite is
- very easy: simply add `IPPROTO_UDPLITE' as the last argument of the socket(2)
- call so that the statement looks like:
+ very easy: simply add ``IPPROTO_UDPLITE`` as the last argument of the
+ socket(2) call so that the statement looks like::
s = socket(PF_INET, SOCK_DGRAM, IPPROTO_UDPLITE);
- or, respectively,
+ or, respectively,
+
+ ::
s = socket(PF_INET6, SOCK_DGRAM, IPPROTO_UDPLITE);
@@ -56,10 +62,10 @@
* Sender checksum coverage: UDPLITE_SEND_CSCOV
- For example,
+ For example::
- int val = 20;
- setsockopt(s, SOL_UDPLITE, UDPLITE_SEND_CSCOV, &val, sizeof(int));
+ int val = 20;
+ setsockopt(s, SOL_UDPLITE, UDPLITE_SEND_CSCOV, &val, sizeof(int));
sets the checksum coverage length to 20 bytes (12b data + 8b header).
Of each packet only the first 20 bytes (plus the pseudo-header) will be
@@ -74,10 +80,10 @@
that of a traffic filter: when enabled, it instructs the kernel to drop
all packets which have a coverage _less_ than this value. For example, if
RTP and UDP headers are to be protected, a receiver can enforce that only
- packets with a minimum coverage of 20 are admitted:
+ packets with a minimum coverage of 20 are admitted::
- int min = 20;
- setsockopt(s, SOL_UDPLITE, UDPLITE_RECV_CSCOV, &min, sizeof(int));
+ int min = 20;
+ setsockopt(s, SOL_UDPLITE, UDPLITE_RECV_CSCOV, &min, sizeof(int));
The calls to getsockopt(2) are analogous. Being an extension and not a stand-
alone protocol, all socket options known from UDP can be used in exactly the
@@ -85,18 +91,18 @@
A detailed discussion of UDP-Lite checksum coverage options is in section IV.
-
- III) HEADER FILES
+3. Header Files
+===============
The socket API requires support through header files in /usr/include:
* /usr/include/netinet/in.h
- to define IPPROTO_UDPLITE
+ to define IPPROTO_UDPLITE
* /usr/include/netinet/udplite.h
- for UDP-Lite header fields and protocol constants
+ for UDP-Lite header fields and protocol constants
- For testing purposes, the following can serve as a `mini' header file:
+ For testing purposes, the following can serve as a ``mini`` header file::
#define IPPROTO_UDPLITE 136
#define SOL_UDPLITE 136
@@ -105,8 +111,9 @@
Ready-made header files for various distros are in the UDP-Lite tarball.
+4. Kernel Behaviour with Regards to the Various Socket Options
+==============================================================
- IV) KERNEL BEHAVIOUR WITH REGARD TO THE VARIOUS SOCKET OPTIONS
To enable debugging messages, the log level need to be set to 8, as most
messages use the KERN_DEBUG level (7).
@@ -136,13 +143,13 @@
3) Disabling the Checksum Computation
On both sender and receiver, checksumming will always be performed
- and cannot be disabled using SO_NO_CHECK. Thus
+ and cannot be disabled using SO_NO_CHECK. Thus::
- setsockopt(sockfd, SOL_SOCKET, SO_NO_CHECK, ... );
+ setsockopt(sockfd, SOL_SOCKET, SO_NO_CHECK, ... );
- will always will be ignored, while the value of
+ will always will be ignored, while the value of::
- getsockopt(sockfd, SOL_SOCKET, SO_NO_CHECK, &value, ...);
+ getsockopt(sockfd, SOL_SOCKET, SO_NO_CHECK, &value, ...);
is meaningless (as in TCP). Packets with a zero checksum field are
illegal (cf. RFC 3828, sec. 3.1) and will be silently discarded.
@@ -167,15 +174,15 @@
first one contains the L4 header.
The send buffer size has implications on the checksum coverage length.
- Consider the following example:
+ Consider the following example::
- Payload: 1536 bytes Send Buffer: 1024 bytes
- MTU: 1500 bytes Coverage Length: 856 bytes
+ Payload: 1536 bytes Send Buffer: 1024 bytes
+ MTU: 1500 bytes Coverage Length: 856 bytes
- UDP-Lite will ship the 1536 bytes in two separate packets:
+ UDP-Lite will ship the 1536 bytes in two separate packets::
- Packet 1: 1024 payload + 8 byte header + 20 byte IP header = 1052 bytes
- Packet 2: 512 payload + 8 byte header + 20 byte IP header = 540 bytes
+ Packet 1: 1024 payload + 8 byte header + 20 byte IP header = 1052 bytes
+ Packet 2: 512 payload + 8 byte header + 20 byte IP header = 540 bytes
The coverage packet covers the UDP-Lite header and 848 bytes of the
payload in the first packet, the second packet is fully covered. Note
@@ -184,17 +191,17 @@
length in such cases.
As an example of what happens when one UDP-Lite packet is split into
- several tiny fragments, consider the following example.
+ several tiny fragments, consider the following example::
- Payload: 1024 bytes Send buffer size: 1024 bytes
- MTU: 300 bytes Coverage length: 575 bytes
+ Payload: 1024 bytes Send buffer size: 1024 bytes
+ MTU: 300 bytes Coverage length: 575 bytes
- +-+-----------+--------------+--------------+--------------+
- |8| 272 | 280 | 280 | 280 |
- +-+-----------+--------------+--------------+--------------+
- 280 560 840 1032
- ^
- *****checksum coverage*************
+ +-+-----------+--------------+--------------+--------------+
+ |8| 272 | 280 | 280 | 280 |
+ +-+-----------+--------------+--------------+--------------+
+ 280 560 840 1032
+ ^
+ *****checksum coverage*************
The UDP-Lite module generates one 1032 byte packet (1024 + 8 byte
header). According to the interface MTU, these are split into 4 IP
@@ -208,7 +215,7 @@
lengths), only the first fragment needs to be considered. When using
larger checksum coverage lengths, each eligible fragment needs to be
checksummed. Suppose we have a checksum coverage of 3062. The buffer
- of 3356 bytes will be split into the following fragments:
+ of 3356 bytes will be split into the following fragments::
Fragment 1: 1280 bytes carrying 1232 bytes of UDP-Lite data
Fragment 2: 1280 bytes carrying 1232 bytes of UDP-Lite data
@@ -222,57 +229,63 @@
performance over wireless (or generally noisy) links and thus smaller
coverage lengths are likely to be expected.
-
- V) UDP-LITE RUNTIME STATISTICS AND THEIR MEANING
+5. UDP-Lite Runtime Statistics and their Meaning
+================================================
Exceptional and error conditions are logged to syslog at the KERN_DEBUG
level. Live statistics about UDP-Lite are available in /proc/net/snmp
- and can (with newer versions of netstat) be viewed using
+ and can (with newer versions of netstat) be viewed using::
- netstat -svu
+ netstat -svu
This displays UDP-Lite statistics variables, whose meaning is as follows.
- InDatagrams: The total number of datagrams delivered to users.
+ ============ =====================================================
+ InDatagrams The total number of datagrams delivered to users.
- NoPorts: Number of packets received to an unknown port.
- These cases are counted separately (not as InErrors).
+ NoPorts Number of packets received to an unknown port.
+ These cases are counted separately (not as InErrors).
- InErrors: Number of erroneous UDP-Lite packets. Errors include:
- * internal socket queue receive errors
- * packet too short (less than 8 bytes or stated
- coverage length exceeds received length)
- * xfrm4_policy_check() returned with error
- * application has specified larger min. coverage
- length than that of incoming packet
- * checksum coverage violated
- * bad checksum
+ InErrors Number of erroneous UDP-Lite packets. Errors include:
- OutDatagrams: Total number of sent datagrams.
+ * internal socket queue receive errors
+ * packet too short (less than 8 bytes or stated
+ coverage length exceeds received length)
+ * xfrm4_policy_check() returned with error
+ * application has specified larger min. coverage
+ length than that of incoming packet
+ * checksum coverage violated
+ * bad checksum
+
+ OutDatagrams Total number of sent datagrams.
+ ============ =====================================================
These statistics derive from the UDP MIB (RFC 2013).
-
- VI) IPTABLES
+6. IPtables
+===========
There is packet match support for UDP-Lite as well as support for the LOG target.
- If you copy and paste the following line into /etc/protocols,
+ If you copy and paste the following line into /etc/protocols::
- udplite 136 UDP-Lite # UDP-Lite [RFC 3828]
+ udplite 136 UDP-Lite # UDP-Lite [RFC 3828]
- then
- iptables -A INPUT -p udplite -j LOG
+ then::
+
+ iptables -A INPUT -p udplite -j LOG
will produce logging output to syslog. Dropping and rejecting packets also works.
-
- VII) MAINTAINER ADDRESS
+7. Maintainer Address
+=====================
The UDP-Lite patch was developed at
- University of Aberdeen
- Electronics Research Group
- Department of Engineering
- Fraser Noble Building
- Aberdeen AB24 3UE; UK
+
+ University of Aberdeen
+ Electronics Research Group
+ Department of Engineering
+ Fraser Noble Building
+ Aberdeen AB24 3UE; UK
+
The current maintainer is Gerrit Renker, <gerrit@xxxxxxxxxxxxxx>. Initial
code was developed by William Stanislaus, <william@xxxxxxxxxxxxxx>.
--
2.25.4