Re: [patch] getsockopt.2, packet.7: improve sockopt documentation for packet sockets

["Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>]

On 04/28/2014 08:12 PM, Carsten Andrich wrote:
> Am Montag, den 28.04.2014, 13:28 -0400 schrieb Neil Horman:
>> Rather than 'lingernig' perhaps more exact language to indicate that positive
>> action is required from the application.  Perhaps:
>>
>> Packets in the WRONG_FORMAT state block the kernel from sending it and subsequent
>> packets on the ring.  Packet in the WRONG_FORMAT state must be moved to the
>> AVAILABLE or SEND_REQUEST state (after correcting format errors), so that the
>> next application call to send() properly transmits the frame.
> 
> Thanks for the suggestion! I incorporated it into the following updated
> PACKET_LOSS description:
> When a malformed packet is encountered on a transmit ring, the default
> is to reset its tp_status to TP_STATUS_WRONG_FORMAT and abort the
> transmission immediately.  The malformed  packet  blocks  itself  and
> subsequent enqueued  packets from being sent.  The format error must be
> fixed, the associated tp_status reset to TP_STATUS_SEND_REQUEST and the
> transmission process restarted via send(2).  However, if PACKET_LOSS is
> set, any malformed packet will be skipped, its tp_status reset to
> TP_STATUS_AVAILABLE, and the transmission process continued.
> 
> IMHO this should go into the PACKET_TX_RING description, but I'd like to
> defer that until I have a little more spare time on my hands, so I can
> tackle the entire PACKET_MMAP-related part of the man-page in a single
> effort.

Carsten, 

Patch applied, with Neil's Ack.

I added a Signed-off-by: line for you, okay?

Thanks for the patch!

Cheers,

Michael



> diff --git a/man2/getsockopt.2 b/man2/getsockopt.2
> index 925fa90..1287efc 100644
> --- a/man2/getsockopt.2
> +++ b/man2/getsockopt.2
> @@ -41,7 +41,7 @@
>  .\" Modified 1999 by Andi Kleen <ak-h9bWGtP8wOw@public.gmane.org>.
>  .\"     Removed most stuff because it is in socket.7 now.
>  .\"
> -.TH GETSOCKOPT 2 2014-01-24 "Linux" "Linux Programmer's Manual"
> +.TH GETSOCKOPT 2 2014-04-28 "Linux" "Linux Programmer's Manual"
>  .SH NAME
>  getsockopt, setsockopt \- get and set options on sockets
>  .SH SYNOPSIS
> @@ -205,6 +205,7 @@ system.
>  .BR getprotoent (3),
>  .BR protocols (5),
>  .BR ip (7),
> +.BR packet (7),
>  .BR socket (7),
>  .BR tcp (7),
>  .BR udp (7),
> diff --git a/man7/packet.7 b/man7/packet.7
> index 11bca48..fc5fdaf 100644
> --- a/man7/packet.7
> +++ b/man7/packet.7
> @@ -9,7 +9,7 @@
>  .\"
>  .\" $Id: packet.7,v 1.13 2000/08/14 08:03:45 ak Exp $
>  .\"
> -.TH PACKET  7 2014-04-24 "Linux" "Linux Programmer's Manual"
> +.TH PACKET  7 2014-04-28 "Linux" "Linux Programmer's Manual"
>  .SH NAME
>  packet \- packet interface on device level
>  .SH SYNOPSIS
> @@ -319,14 +319,25 @@ original fanout algorithm selects a backlogged socket, the packet
>  rolls over to the next available one.
>  .TP
>  .BR PACKET_LOSS " (with " PACKET_TX_RING )
> -When a malformed packet is encountered on a transmit ring, the default is to
> -set its status to
> +When a malformed packet is encountered on a transmit ring, the default is
> +to reset its
> +.I tp_status
> +to
>  .BR TP_STATUS_WRONG_FORMAT
> -and abort the transmission immediately (it and following packets are left
> -lingering on the ring).
> +and abort the transmission immediately.
> +The malformed packet blocks itself and subsequent enqueued packets from
> +being sent.
> +The format error must be fixed, the associated
> +.I tp_status
> +reset to
> +.BR TP_STATUS_SEND_REQUEST
> +and the transmission process restarted via
> +.BR send (2) .
>  However, if
>  .BR PACKET_LOSS
> -is set, any malformed packet will be skipped, its status reset to
> +is set, any malformed packet will be skipped, its
> +.I tp_status
> +reset to
>  .BR TP_STATUS_AVAILABLE ,
>  and the transmission process continued.
>  .TP
> @@ -360,15 +371,21 @@ Packet socket and application communicate the head and tail of the ring
>  through the
>  .I tp_status
>  field.
> -The packet socket owns all slots with status
> +The packet socket owns all slots with
> +.I tp_status
> +equal to
>  .BR TP_STATUS_KERNEL .
>  After filling a slot, it changes the status of the slot to transfer
>  ownership to the application.
> -During normal operation, the new status has the
> +During normal operation, the new
> +.I tp_status
> +value has at least the
>  .BR TP_STATUS_USER
>  bit set to signal that a received packet has been stored.
>  When the application has finished processing a packet, it transfers
> -ownership of the slot back to the socket by setting the status to
> +ownership of the slot back to the socket by setting
> +.I tp_status
> +equal to
>  .BR TP_STATUS_KERNEL .
>  Packet sockets implement multiple variants of the packet ring.
>  The implementation details are described in
> @@ -407,9 +424,13 @@ Create a memory-mapped ring buffer for packet transmission.
>  This option is similar to
>  .BR PACKET_RX_RING
>  and takes the same arguments.
> -The application writes packets into slots with status
> +The application writes packets into slots with
> +.I tp_status
> +equal to
>  .BR TP_STATUS_AVAILABLE
> -and schedules them for transmission by changing the status to
> +and schedules them for transmission by changing
> +.I tp_status
> +to
>  .BR TP_STATUS_SEND_REQUEST .
>  When packets are ready to be transmitted, the application calls
>  .BR send (2)
> @@ -424,7 +445,9 @@ If an address is passed using
>  or
>  .BR sendmsg (2),
>  then that overrides the socket default.
> -On successful transmission, the socket resets the slot to
> +On successful transmission, the socket resets
> +.I tp_status
> +to
>  .BR TP_STATUS_AVAILABLE .
>  It immediately aborts the transmission on error unless
>  .BR PACKET_LOSS
> @@ -633,6 +656,11 @@ The
>  .I <linux/if_ether.h>
>  include file for physical layer protocols.
>  
> -The example source file
> +The Linux kernel source tree.
> +.IR /Documentation/networking/filter.txt
> +describes how to apply Berkeley Packet Filters to packet sockets.
>  .IR /tools/testing/selftests/net/psock_tpacket.c
> -in the Linux kernel source tree.
> +contains example source code for all available versions of
> +.BR PACKET_RX_RING
> +and
> +.BR PACKET_TX_RING .
> 
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html