Blame SOURCES/1404478-mpo-7.4.0-packet.7.patch

0febb9
From ad7e94b35988c8cd03866d47aa6fb21841cfae7c Mon Sep 17 00:00:00 2001
0febb9
From: =?UTF-8?q?Nikola=20Forr=C3=B3?= <nforro@redhat.com>
0febb9
Date: Tue, 28 Mar 2017 15:04:36 +0200
0febb9
Subject: [PATCH 6/6] packet.7: add missing socket options
0febb9
0febb9
---
0febb9
 man-pages/man7/packet.7 | 218 ++++++++++++++++++++++++++++++++++++++++++++++--
0febb9
 1 file changed, 209 insertions(+), 9 deletions(-)
0febb9
0febb9
diff --git a/man-pages/man7/packet.7 b/man-pages/man7/packet.7
0febb9
index f5d990b..b217e5e 100644
0febb9
--- a/man-pages/man7/packet.7
0febb9
+++ b/man-pages/man7/packet.7
0febb9
@@ -177,19 +177,24 @@ and
0febb9
 .I sll_ifindex
0febb9
 are used.
0febb9
 .SS Socket options
0febb9
+Packet socket options are configured by calling
0febb9
+.BR setsockopt (2)
0febb9
+with level
0febb9
+.BR SOL_PACKET .
0febb9
+.TP
0febb9
+.BR PACKET_ADD_MEMBERSHIP
0febb9
+.PD 0
0febb9
+.TP
0febb9
+.BR PACKET_DROP_MEMBERSHIP
0febb9
+.PD
0febb9
 Packet sockets can be used to configure physical layer multicasting
0febb9
 and promiscuous mode.
0febb9
-It works by calling
0febb9
-.BR setsockopt (2)
0febb9
-on a packet socket for
0febb9
-.B SOL_PACKET
0febb9
-and one of the options
0febb9
 .B PACKET_ADD_MEMBERSHIP
0febb9
-to add a binding or
0febb9
+adds a binding and
0febb9
 .B PACKET_DROP_MEMBERSHIP
0febb9
-to drop it.
0febb9
+drops it.
0febb9
 They both expect a
0febb9
-.B packet_mreq
0febb9
+.I packet_mreq
0febb9
 structure as argument:
0febb9
 
0febb9
 .in +4n
0febb9
@@ -222,11 +227,206 @@ and
0febb9
 sets the socket up to receive all multicast packets arriving at
0febb9
 the interface.
0febb9
 
0febb9
-In addition the traditional ioctls
0febb9
+In addition, the traditional ioctls
0febb9
 .BR SIOCSIFFLAGS ,
0febb9
 .BR SIOCADDMULTI ,
0febb9
 .B SIOCDELMULTI
0febb9
 can be used for the same purpose.
0febb9
+.TP
0febb9
+.BR PACKET_AUXDATA " (since Linux 2.6.21)"
0febb9
+.\" commit 8dc4194474159660d7f37c495e3fc3f10d0db8cc
0febb9
+If this binary option is enabled, the packet socket passes a metadata
0febb9
+structure along with each packet in the
0febb9
+.BR recvmsg (2)
0febb9
+control field.
0febb9
+The structure can be read with
0febb9
+.BR cmsg (3).
0febb9
+It is defined as
0febb9
+
0febb9
+.in +4n
0febb9
+.nf
0febb9
+struct tpacket_auxdata {
0febb9
+    __u32 tp_status;
0febb9
+    __u32 tp_len;      /* packet length */
0febb9
+    __u32 tp_snaplen;  /* captured length */
0febb9
+    __u16 tp_mac;
0febb9
+    __u16 tp_net;
0febb9
+    __u16 tp_vlan_tci;
0febb9
+    __u16 tp_padding;
0febb9
+};
0febb9
+.fi
0febb9
+.in
0febb9
+.TP
0febb9
+.BR PACKET_FANOUT " (since Linux 3.1)"
0febb9
+.\" commit dc99f600698dcac69b8f56dda9a8a00d645c5ffc
0febb9
+To scale processing across threads, packet sockets can form a fanout
0febb9
+group.
0febb9
+In this mode, each matching packet is enqueued onto only one
0febb9
+socket in the group.
0febb9
+A socket joins a fanout group by calling
0febb9
+.BR setsockopt (2)
0febb9
+with level
0febb9
+.B SOL_PACKET
0febb9
+and option
0febb9
+.BR PACKET_FANOUT .
0febb9
+Each network namespace can have up to 65536 independent groups.
0febb9
+A socket selects a group by encoding the ID in the first 16 bits of
0febb9
+the integer option value.
0febb9
+The first packet socket to join a group implicitly creates it.
0febb9
+To successfully join an existing group, subsequent packet sockets
0febb9
+must have the same protocol, device settings, fanout mode and
0febb9
+flags (see below).
0febb9
+Packet sockets can leave a fanout group only by closing the socket.
0febb9
+The group is deleted when the last socket is closed.
0febb9
+
0febb9
+Fanout supports multiple algorithms to spread traffic between sockets.
0febb9
+The default mode,
0febb9
+.BR PACKET_FANOUT_HASH ,
0febb9
+sends packets from the same flow to the same socket to maintain
0febb9
+per-flow ordering.
0febb9
+For each packet, it chooses a socket by taking the packet flow hash
0febb9
+modulo the number of sockets in the group, where a flow hash is a hash
0febb9
+over network-layer address and optional transport-layer port fields.
0febb9
+The load-balance mode
0febb9
+.BR PACKET_FANOUT_LB
0febb9
+implements a round-robin algorithm.
0febb9
+.BR PACKET_FANOUT_CPU
0febb9
+selects the socket based on the CPU that the packet arrived on.
0febb9
+.BR PACKET_FANOUT_ROLLOVER
0febb9
+processes all data on a single socket, moves to the next when one
0febb9
+becomes backlogged.
0febb9
+.BR PACKET_FANOUT_RND
0febb9
+selects the socket using a pseudo-random number generator.
0febb9
+
0febb9
+Fanout modes can take additional options.
0febb9
+IP fragmentation causes packets from the same flow to have different
0febb9
+flow hashes.
0febb9
+The flag
0febb9
+.BR PACKET_FANOUT_FLAG_DEFRAG ,
0febb9
+if set, causes packet to be defragmented before fanout is applied, to
0febb9
+preserve order even in this case.
0febb9
+Fanout mode and options are communicated in the second 16 bits of the
0febb9
+integer option value.
0febb9
+The flag
0febb9
+.BR PACKET_FANOUT_FLAG_ROLLOVER
0febb9
+enables the roll over mechanism as a backup strategy: if the
0febb9
+original fanout algorithm selects a backlogged socket, the packet
0febb9
+rolls over to the next available one.
0febb9
+.TP
0febb9
+.BR PACKET_LOSS " (with " PACKET_TX_RING )
0febb9
+If set, do not silently drop a packet on transmission error, but
0febb9
+return it with status set to
0febb9
+.BR TP_STATUS_WRONG_FORMAT .
0febb9
+.TP
0febb9
+.BR PACKET_RESERVE " (with " PACKET_RX_RING )
0febb9
+By default, a packet receive ring writes packets immediately following the
0febb9
+metadata structure and alignment padding.
0febb9
+This integer option reserves additional headroom.
0febb9
+.TP
0febb9
+.BR PACKET_RX_RING
0febb9
+Create a memory-mapped ring buffer for asynchronous packet reception.
0febb9
+The packet socket reserves a contiguous region of application address
0febb9
+space, lays it out into an array of packet slots and copies packets
0febb9
+(up to
0febb9
+.IR tp_snaplen
0febb9
+) into subsequent slots.
0febb9
+Each packet is preceded by a metadata structure similar to
0febb9
+.IR tpacket_auxdata .
0febb9
+The protocol fields encode the offset to the data
0febb9
+from the start of the metadata header.
0febb9
+.I tp_net
0febb9
+stores the offset to the network layer.
0febb9
+If the packet socket is of type
0febb9
+.BR SOCK_DGRAM ,
0febb9
+then
0febb9
+.I tp_mac
0febb9
+is the same.
0febb9
+If it is of type
0febb9
+.BR SOCK_RAW ,
0febb9
+then that field stores the offset to the link-layer frame.
0febb9
+Packet socket and application communicate the head and tail of the ring
0febb9
+through the
0febb9
+.I tp_status
0febb9
+field.
0febb9
+The packet socket owns all slots with status
0febb9
+.BR TP_STATUS_KERNEL .
0febb9
+After filling a slot, it changes the status of the slot to transfer
0febb9
+ownership to the application.
0febb9
+During normal operation, the new status is
0febb9
+.BR TP_STATUS_USER ,
0febb9
+to signal that a correctly received packet has been stored.
0febb9
+When the application has finished processing a packet, it transfers
0febb9
+ownership of the slot back to the socket by setting the status to
0febb9
+.BR TP_STATUS_KERNEL .
0febb9
+Packet sockets implement multiple variants of the packet ring.
0febb9
+The implementation details are described in
0febb9
+.IR Documentation/networking/packet_mmap.txt
0febb9
+in the Linux kernel source tree.
0febb9
+.TP
0febb9
+.BR PACKET_STATISTICS
0febb9
+Retrieve packet socket statistics in the form of a structure
0febb9
+
0febb9
+.in +4n
0febb9
+.nf
0febb9
+struct tpacket_stats {
0febb9
+    unsigned int tp_packets;  /* Total packet count */
0febb9
+    unsigned int tp_drops;    /* Dropped packet count */
0febb9
+};
0febb9
+.fi
0febb9
+.in
0febb9
+
0febb9
+Receiving statistics resets the internal counters.
0febb9
+The statistics structure differs when using a ring of variant
0febb9
+.BR TPACKET_V3 .
0febb9
+.TP
0febb9
+.BR PACKET_TIMESTAMP " (with " PACKET_RX_RING "; since Linux 2.6.36)"
0febb9
+.\" commit 614f60fa9d73a9e8fdff3df83381907fea7c5649
0febb9
+The packet receive ring always stores a timestamp in the metadata header.
0febb9
+By default, this is a software generated timestamp generated when the
0febb9
+packet is copied into the ring.
0febb9
+This integer option selects the type of timestamp.
0febb9
+Besides the default, it support the two hardware formats described in
0febb9
+.IR Documentation/networking/timestamping.txt
0febb9
+in the Linux kernel source tree.
0febb9
+.TP
0febb9
+.BR PACKET_TX_RING " (since Linux 2.6.31)"
0febb9
+.\" commit 69e3c75f4d541a6eb151b3ef91f34033cb3ad6e1
0febb9
+Create a memory-mapped ring buffer for packet transmission.
0febb9
+This option is similar to
0febb9
+.BR PACKET_RX_RING
0febb9
+and takes the same arguments.
0febb9
+The application writes packets into slots with status
0febb9
+.BR TP_STATUS_AVAILABLE
0febb9
+and schedules them for transmission by changing the status to
0febb9
+.BR TP_STATUS_SEND_REQUEST .
0febb9
+When packets are ready to be transmitted, the application calls
0febb9
+.BR send (2)
0febb9
+or a variant thereof.
0febb9
+The
0febb9
+.I buf
0febb9
+and
0febb9
+.I len
0febb9
+fields of this call are ignored.
0febb9
+If an address is passed using
0febb9
+.BR sendto (2)
0febb9
+or
0febb9
+.BR sendmsg (2) ,
0febb9
+then that overrides the socket default.
0febb9
+On successful transmission, the socket resets the slot to
0febb9
+.BR TP_STATUS_AVAILABLE .
0febb9
+It discards packets silently on error unless
0febb9
+.BR PACKET_LOSS
0febb9
+is set.
0febb9
+.TP
0febb9
+.BR PACKET_VERSION " (with " PACKET_RX_RING "; since Linux 2.6.27)"
0febb9
+.\" commit bbd6ef87c544d88c30e4b762b1b61ef267a7d279
0febb9
+By default,
0febb9
+.BR PACKET_RX_RING
0febb9
+creates a packet receive ring of variant
0febb9
+.BR TPACKET_V1 .
0febb9
+To create another variant, configure the desired variant by setting this
0febb9
+integer option before creating the ring.
0febb9
+
0febb9
 .SS Ioctls
0febb9
 .B SIOCGSTAMP
0febb9
 can be used to receive the timestamp of the last received packet.
0febb9
-- 
0febb9
2.7.4
0febb9