packet.7: PACKET_LOSS has inverse meaning

Hey there,

I stumbled upon an error in packet.7 regarding the meaning of the PACKET_LOSS socket option. According to the current git version of linux-man setting PACKET_LOSS causes malformed packets to *not* be silently dropped.

However it is the other way round. If PACKET_LOSS is *not* set, malformed packets will be marked TP_STATUS_WRONG_FORMAT and the transmission process aborted, leaving untransmitted packets in the ring. If it *is* set, malformed packets will be silently skipped, their status set to TP_STATUS_AVAILABLE and the transmission process continued with the following packet.

This behaviour can be clearly seen in net/packet/af_packet.c:
http://git.kernel.org/cgit/linux/kernel/git/stable/linux-stable.git/tree/net/packet/af_packet.c#n2300

The value accompanying TP_PACKET_LOSS translates into po->tp_loss:
http://git.kernel.org/cgit/linux/kernel/git/stable/linux-stable.git/tree/net/packet/af_packet.c#n3304

I inverted the meaning of PACKET_LOSS and clarified the description in the attached patch.

Hi Daniel, Willem,

Daniel, your patch (dbb4f7516b) added the text on PACKET_LOSS. Could you comment on the patch below please?

Thanks,

Michael

Quoted 22 lines · Carsten Andrich

Hey there,

I stumbled upon an error in packet.7 regarding the meaning of the PACKET_LOSS socket option. According to the current git version of linux-man setting PACKET_LOSS causes malformed packets to *not* be silently dropped.

However it is the other way round. If PACKET_LOSS is *not* set, malformed packets will be marked TP_STATUS_WRONG_FORMAT and the transmission process aborted, leaving untransmitted packets in the ring. If it *is* set, malformed packets will be silently skipped, their status set to TP_STATUS_AVAILABLE and the transmission process continued with the following packet.

This behaviour can be clearly seen in net/packet/af_packet.c:
http://git.kernel.org/cgit/linux/kernel/git/stable/linux-stable.git/tree/net/packet/af_packet.c#n2300

The value accompanying TP_PACKET_LOSS translates into po->tp_loss:
http://git.kernel.org/cgit/linux/kernel/git/stable/linux-stable.git/tree/net/packet/af_packet.c#n3304

I inverted the meaning of PACKET_LOSS and clarified the description in the attached patch.

man7/packet.7 +10 -5

index d8257f9..5085814 100644
@@ -319,9 +319,15 @@ original fanout algorithm selects a backlogged socket, the packet
 rolls over to the next available one.
 .TP
 .BR PACKET_LOSS " (with " PACKET_TX_RING )
-If set, do not silently drop a packet on transmission error, but
-return it with status set to
-.BR TP_STATUS_WRONG_FORMAT .
+When a malformed packet is encountered on a transmit ring, the default is to
+set its status to
+.BR TP_STATUS_WRONG_FORMAT
+and abort the transmission immediately (it and following packets are left
+lingering on the ring). However if
+.BR PACKET_LOSS
+is set, malformed packets will be skipped, their status reset to
+.BR TP_STATUS_AVAILABLE
+and the transmission process continued.
 .TP
 .BR PACKET_RESERVE " (with " PACKET_RX_RING )
 By default, a packet receive ring writes packets immediately following the

@@ -419,7 +425,7 @@ or
 then that overrides the socket default.
 On successful transmission, the socket resets the slot to
 .BR TP_STATUS_AVAILABLE .
-It discards packets silently on error unless
+It immediately aborts the transmission on error unless
 .BR PACKET_LOSS
 is set.
 .TP
 
 
--

Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Quoted 5 lines · Michael Kerrisk (man-pages)

Hi Daniel, Willem,

Daniel, your patch (dbb4f7516b) added the text on PACKET_LOSS. Could you comment on the patch below please?

Carsten is correct. I made a mistake in that explanation, accidentally inverting the branch. My apologies and thanks for following up with a replacement text, Carsten. That looks good to me.

Quoted 62 lines · Carsten Andrich

Quoted 22 lines

Hey there,

I stumbled upon an error in packet.7 regarding the meaning of the PACKET_LOSS socket option. According to the current git version of linux-man setting PACKET_LOSS causes malformed packets to *not* be silently dropped.

However it is the other way round. If PACKET_LOSS is *not* set, malformed packets will be marked TP_STATUS_WRONG_FORMAT and the transmission process aborted, leaving untransmitted packets in the ring. If it *is* set, malformed packets will be silently skipped, their status set to TP_STATUS_AVAILABLE and the transmission process continued with the following packet.

This behaviour can be clearly seen in net/packet/af_packet.c:
http://git.kernel.org/cgit/linux/kernel/git/stable/linux-stable.git/tree/net/packet/af_packet.c#n2300

The value accompanying TP_PACKET_LOSS translates into po->tp_loss:
http://git.kernel.org/cgit/linux/kernel/git/stable/linux-stable.git/tree/net/packet/af_packet.c#n3304

I inverted the meaning of PACKET_LOSS and clarified the description in the attached patch.

man7/packet.7 +10 -5

index d8257f9..5085814 100644
@@ -319,9 +319,15 @@ original fanout algorithm selects a backlogged socket, the packet
 rolls over to the next available one.
 .TP
 .BR PACKET_LOSS " (with " PACKET_TX_RING )
-If set, do not silently drop a packet on transmission error, but
-return it with status set to
-.BR TP_STATUS_WRONG_FORMAT .
+When a malformed packet is encountered on a transmit ring, the default is to
+set its status to
+.BR TP_STATUS_WRONG_FORMAT
+and abort the transmission immediately (it and following packets are left
+lingering on the ring). However if
+.BR PACKET_LOSS
+is set, malformed packets will be skipped, their status reset to
+.BR TP_STATUS_AVAILABLE
+and the transmission process continued.
 .TP
 .BR PACKET_RESERVE " (with " PACKET_RX_RING )
 By default, a packet receive ring writes packets immediately following the

@@ -419,7 +425,7 @@ or
 then that overrides the socket default.
 On successful transmission, the socket resets the slot to
 .BR TP_STATUS_AVAILABLE .
-It discards packets silently on error unless
+It immediately aborts the transmission on error unless
 .BR PACKET_LOSS
 is set.
 .TP
 
 
--

Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

What does "their" in "their status" refer to?

Quoted 5 lines · Michael Kerrisk (man-pages)

Hi Daniel, Willem,

Daniel, your patch (dbb4f7516b) added the text on PACKET_LOSS. Could you comment on the patch below please?

Carsten is correct. I made a mistake in that explanation, accidentally inverting the branch. My apologies and thanks for following up with a replacement text, Carsten. That looks good to me.

Quoted 58 lines · Carsten Andrich

Quoted 22 lines

Hey there,

I stumbled upon an error in packet.7 regarding the meaning of the PACKET_LOSS socket option. According to the current git version of linux-man setting PACKET_LOSS causes malformed packets to *not* be silently dropped.

However it is the other way round. If PACKET_LOSS is *not* set, malformed packets will be marked TP_STATUS_WRONG_FORMAT and the transmission process aborted, leaving untransmitted packets in the ring. If it *is* set, malformed packets will be silently skipped, their status set to TP_STATUS_AVAILABLE and the transmission process continued with the following packet.

This behaviour can be clearly seen in net/packet/af_packet.c:
http://git.kernel.org/cgit/linux/kernel/git/stable/linux-stable.git/tree/net/packet/af_packet.c#n2300

The value accompanying TP_PACKET_LOSS translates into po->tp_loss:
http://git.kernel.org/cgit/linux/kernel/git/stable/linux-stable.git/tree/net/packet/af_packet.c#n3304

I inverted the meaning of PACKET_LOSS and clarified the description in the attached patch.

man7/packet.7 +10 -4

index d8257f9..5085814 100644
@@ -319,9 +319,15 @@ original fanout algorithm selects a backlogged socket, the packet
 rolls over to the next available one.
 .TP
 .BR PACKET_LOSS " (with " PACKET_TX_RING )
-If set, do not silently drop a packet on transmission error, but
-return it with status set to
-.BR TP_STATUS_WRONG_FORMAT .
+When a malformed packet is encountered on a transmit ring, the default is to
+set its status to
+.BR TP_STATUS_WRONG_FORMAT
+and abort the transmission immediately (it and following packets are left
+lingering on the ring). However if
+.BR PACKET_LOSS
+is set, malformed packets will be skipped, their status reset to
+.BR TP_STATUS_AVAILABLE
+and the transmission process continued.
 .TP
 .BR PACKET_RESERVE " (with " PACKET_RX_RING )
 By default, a packet receive ring writes packets immediately following the

@@ -419,7 +425,7 @@ or
 then that overrides the socket default.
 On successful transmission, the socket resets the slot to
 .BR TP_STATUS_AVAILABLE .
-It discards packets silently on error unless
+It immediately aborts the transmission on error unless
 .BR PACKET_LOSS
 is set.
 .TP

Quoted 4 lines

--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Quoted 11 lines · Willem de Bruijn

Quoted 5 lines · Michael Kerrisk (man-pages)

Hi Daniel, Willem,

Daniel, your patch (dbb4f7516b) added the text on PACKET_LOSS. Could you comment on the patch below please?

Carsten is correct. I made a mistake in that explanation, accidentally inverting the branch. My apologies and thanks for following up with a replacement text, Carsten. That looks good to me.

@Willem: thanks for the quick response. That helps so much.

@Carsten: I've applied your patch, but I have a question. You wrote:

[[
However if
.BR PACKET_LOSS
is set, malformed packets will be skipped, their status reset to .BR TP_STATUS_AVAILABLE
]]

What does "their" in "their status" refer to?

Cheers,

Michael

Quoted 58 lines

Quoted 58 lines · Carsten Andrich

Quoted 22 lines

Hey there,

I stumbled upon an error in packet.7 regarding the meaning of the PACKET_LOSS socket option. According to the current git version of linux-man setting PACKET_LOSS causes malformed packets to *not* be silently dropped.

However it is the other way round. If PACKET_LOSS is *not* set, malformed packets will be marked TP_STATUS_WRONG_FORMAT and the transmission process aborted, leaving untransmitted packets in the ring. If it *is* set, malformed packets will be silently skipped, their status set to TP_STATUS_AVAILABLE and the transmission process continued with the following packet.

This behaviour can be clearly seen in net/packet/af_packet.c:
http://git.kernel.org/cgit/linux/kernel/git/stable/linux-stable.git/tree/net/packet/af_packet.c#n2300

The value accompanying TP_PACKET_LOSS translates into po->tp_loss:
http://git.kernel.org/cgit/linux/kernel/git/stable/linux-stable.git/tree/net/packet/af_packet.c#n3304

I inverted the meaning of PACKET_LOSS and clarified the description in the attached patch.

man7/packet.7 +10 -4

index d8257f9..5085814 100644
@@ -319,9 +319,15 @@ original fanout algorithm selects a backlogged socket, the packet
 rolls over to the next available one.
 .TP
 .BR PACKET_LOSS " (with " PACKET_TX_RING )
-If set, do not silently drop a packet on transmission error, but
-return it with status set to
-.BR TP_STATUS_WRONG_FORMAT .
+When a malformed packet is encountered on a transmit ring, the default is to
+set its status to
+.BR TP_STATUS_WRONG_FORMAT
+and abort the transmission immediately (it and following packets are left
+lingering on the ring). However if
+.BR PACKET_LOSS
+is set, malformed packets will be skipped, their status reset to
+.BR TP_STATUS_AVAILABLE
+and the transmission process continued.
 .TP
 .BR PACKET_RESERVE " (with " PACKET_RX_RING )
 By default, a packet receive ring writes packets immediately following the

@@ -419,7 +425,7 @@ or
 then that overrides the socket default.
 On successful transmission, the socket resets the slot to
 .BR TP_STATUS_AVAILABLE .
-It discards packets silently on error unless
+It immediately aborts the transmission on error unless
 .BR PACKET_LOSS
 is set.
 .TP

Quoted 5 lines

Quoted 4 lines

--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

I interpreted this as the tp_status field of the malformed packets. To make clear that it does not refer to the "following packets", it could be revised to

"is set, transmission continues, skipping over any malformed packets. The status of the malformed packets is reset to TP_STATUS_AVAILABLE."

@Carsten: I've applied your patch, but I have a question. You wrote:

[[
However if
.BR PACKET_LOSS
is set, malformed packets will be skipped, their status reset to .BR TP_STATUS_AVAILABLE
]]

What does "their" in "their status" refer to?

@Willem: Sorry for being a smart ass ;)

Quoted 6 lines

I interpreted this as the tp_status field of the malformed packets. To make clear that it does not refer to the "following packets", it could be revised to

"is set, transmission continues, skipping over any malformed packets. The status of the malformed packets is reset to TP_STATUS_AVAILABLE."

There's no need to emphasize that "only" malformed packets have their tp_status set to TP_STATUS_AVAILABLE, since the following packets will share that fate (by being either skipped or actually sent). If this were not the case the ring would be broken, due to multiple non-consecutive occurrences of the same TP_STATUS_xyz. This is why the transmission must be immediately aborted on encountering a malformed packet if PACKET_LOSS is not set.

Aside from this purely academical know-it-all remark (sorry, again), your suggested change is fine, of course. As an alternative, I simply stripped the "theirs" from my initial suggestion:
---
However if
.BR PACKET_LOSS
is set, any malformed packet will be skipped, its status reset to .BR TP_STATUS_AVAILABLE
and the transmission process continued.
---

-------- Weitergeleitete Nachricht --------
Von: Willem de Bruijn <[email protected]>
An: Michael Kerrisk (man-pages) <[email protected]>
Kopie: Carsten Andrich <[email protected]>, Daniel Borkmann <[email protected]>, [email protected]
Betreff: Re: [patch] packet.7: PACKET_LOSS has inverse meaning
Datum: Tue, 22 Apr 2014 15:14:53 -0400

On Tue, Apr 22, 2014 at 2:55 PM, Michael Kerrisk (man-pages) <[email protected]> wrote:
[...]

Quoted 10 lines

@Carsten: I've applied your patch, but I have a question. You wrote:

[[
However if
.BR PACKET_LOSS
is set, malformed packets will be skipped, their status reset to .BR TP_STATUS_AVAILABLE
]]

What does "their" in "their status" refer to?

I interpreted this as the tp_status field of the malformed packets. To make clear that it does not refer to the "following packets", it could be revised to

"is set, transmission continues, skipping over any malformed packets. The status of the malformed packets is reset to TP_STATUS_AVAILABLE."

How would adding just a little more precision be:

[[
However, if
.BR PACKET_LOSS
is set, any malformed packet will be skipped, its status .RI ( tp_status
in the
.I tpacket_hdr
structure) reset to
.BR TP_STATUS_AVAILABLE ,
and the transmission process continued.
]]

?

It tries to balance being informative with exposing kernel detail that is unlikely to be used by most readers or that may change frequently. For implementation details, the manpage points to the documentation in kernel Documentation/networking. Let me know if options should be added or removed.

Quoted 14 lines · Michael Kerrisk (man-pages)

How would adding just a little more precision be:

[[
However, if
.BR PACKET_LOSS
is set, any malformed packet will be skipped, its status .RI ( tp_status
in the
.I tpacket_hdr
structure) reset to
.BR TP_STATUS_AVAILABLE ,
and the transmission process continued.
]]

Quoted 1 line

?

I sense a disturb ... ehm ... general discussion regarding PACKET_MMAP documenation arising.

I agree with Willem's commit message, adding PACKET_MMAP to packet.7:
https://git.kernel.org/cgit/docs/man-pages/man-pages.git/commit/?id=dbb4f7516b

Quoted 5 lines

It tries to balance being informative with exposing kernel detail that is unlikely to be used by most readers or that may change frequently. For implementation details, the manpage points to the documentation in kernel Documentation/networking. Let me know if options should be added or removed.

The entire packet.7 manpage does not mention struct tpacket_hdr a single time,
so mentioning it only when describing the PACKET_LOSS socket option may confuse
the reader.

Particulary since different versions of this struct exist.

In my opinion packet.7 should be complete (and correct), yet brief in describing anything PACKET_MMAP related, so anyone with a basic unterstanding
of PACKET_MMAP internals will comprehend the descriptions in packet.7. packet.7 already refers to Documentation/networking/packet_mmap.txt for additional information. Reading only packet.7 will not enable anyone unfamiliar
with PACKET_MMAP to actually use it.

This brings me to packet_mmap.txt, which -- I am sorry to say -- definitely
needs to be improved. It lacks some information (e.g. PACKET_LOSS is not
mentioned at all), should give some basic usage examples, clarify some details, etc. It does not mention the excellent example code in /tools/testing/selftests/net/psock_tpacket.c at all, which I only stumled upon
yesterday.

It would have been very helpful to me, when I was getting started
with PACKET_MMAP, since packet_mmap.txt was quite puzzling in the beginning.
Both packet.7 and packet_mmap.txt should be synchronized to some extent, so
the former gives basic information and the latter contains implementation
details. But that would be a lot of work ...

Cheers,
Carsten

PS: This is not me volunteering to help in that effort. At least not yet ;)

[...]

Quoted 2 lines

PS: This is not me volunteering to help in that effort. At least not yet ;)

Any way that I could convince you? :-} Some of the API corners in man pages are so dark, dusty, and deep that I just don't have time to get up to speed on the topic in order to fix the pages, and it's really helpful to have someone pick up the reigns on a particular topic. In that sense, Vince Weaver (perf_event_open.2) and Denys Vlasenko (ptrace.2) have been lifesavers.

packet.7 is another one of those dusty corners. I can't see myself ever getting the time to make it better, since there's a lot of base knowledge that I lack, and there are so many other tasks in need of attention. Andi Kleen made a good effort in putting the page together 15 years ago, but since then it has mostly languished, short of real love, except for a couple of patches in the last 18 months (from Daniel/Willem, and Neil Horman). How would you like to become the maintainer of a man page :-).

Am Mittwoch, den 23.04.2014, 12:12 +0200 schrieb Michael Kerrisk (man-pages):

Quoted 11 lines · Carsten Andrich

[...]

Quoted 2 lines

PS: This is not me volunteering to help in that effort. At least not yet ;)

Any way that I could convince you? :-} Some of the API corners in man pages are so dark, dusty, and deep that I just don't have time to get up to speed on the topic in order to fix the pages, and it's really helpful to have someone pick up the reigns on a particular topic. In that sense, Vince Weaver (perf_event_open.2) and Denys Vlasenko (ptrace.2) have been lifesavers.

I consider man-pages an incredibly important effort, since they've been very helpful for me on numerous occasions, and I'd generally be willing to support that effort.

Quoted 8 lines

packet.7 is another one of those dusty corners. I can't see myself ever getting the time to make it better, since there's a lot of base knowledge that I lack, and there are so many other tasks in need of attention. Andi Kleen made a good effort in putting the page together 15 years ago, but since then it has mostly languished, short of real love, except for a couple of patches in the last 18 months (from Daniel/Willem, and Neil Horman). How would you like to become the maintainer of a man page :-).

You must be in dire need of assistance, if you ask me that, despite knowing so little about me :)

Unfortunately my experience with Linux packet sockets is very limited. I messed with them a few times, but only really started using SOCK_RAW packet sockets (including PACKET_MMAP) a few weeks ago (as a part of my Bachelor's thesis). I haven't looked at the linux (networking) code before Monday, when I tried to figure out if either packet.7 or I was wrong regarding PACKET_LOSS. And I've never even touched SOCK_DGRAM.

All this doesn't exactly qualify me for the job :)

Maybe we should continue this discussion in private, so we don't bore everyone to death.

Quoted 9 lines · Carsten Andrich

[...]
Unfortunately my experience with Linux packet sockets is very limited. I messed with them a few times, but only really started using SOCK_RAW packet sockets (including PACKET_MMAP) a few weeks ago (as a part of my Bachelor's thesis). I haven't looked at the linux (networking) code before Monday, when I tried to figure out if either packet.7 or I was wrong regarding PACKET_LOSS. And I've never even touched SOCK_DGRAM.

All this doesn't exactly qualify me for the job :)

Maybe, maybe not. On the other hand, I have the idea (may be wrong) that Vince Weaver was a beginner with perf_event_open() when he started sending me patches. He's continued doing so with a vengeance (thanks again Vince!). That has been a great help, since perf_event_open() is a complex, constantly evolving API surface, and I just don't have the time to track the details. The API described in packet.7 has not changed much over time, but the man page has seen little love over the years. An inquiring mind, willing to test things and read code are the main prerequisites. ANd it sounds like some others might chip with help and Acks.

Quoted 2 lines

Maybe we should continue this discussion in private, so we don't bore everyone to death.

Drop me a private mail if you want, but there are also benefits to public conversations ;-).

Quoted 11 lines · Michael Kerrisk (man-pages)

Quoted 9 lines · Carsten Andrich

[...]
Unfortunately my experience with Linux packet sockets is very limited. I messed with them a few times, but only really started using SOCK_RAW packet sockets (including PACKET_MMAP) a few weeks ago (as a part of my Bachelor's thesis). I haven't looked at the linux (networking) code before Monday, when I tried to figure out if either packet.7 or I was wrong regarding PACKET_LOSS. And I've never even touched SOCK_DGRAM.

All this doesn't exactly qualify me for the job :)

Quoted 10 lines

Maybe, maybe not. On the other hand, I have the idea (may be wrong) that Vince Weaver was a beginner with perf_event_open() when he started sending me patches. He's continued doing so with a vengeance (thanks again Vince!). That has been a great help, since perf_event_open() is a complex, constantly evolving API surface, and I just don't have the time to track the details. The API described in packet.7 has not changed much over time, but the man page has seen little love over the years. An inquiring mind, willing to test things and read code are the main prerequisites. ANd it sounds like some others might chip with help and Acks.

We could give it a shot. It may be of an advantage to not have a deep understanding of the code driving the interface one is trying to document, as to not leave out aspects which appear to be self-evident.

It would make sense to limit our efforts to getting the PACKET_MMAP documentation in good shape, at least for now.
I'd definitely require a reviewer (who's willing to answer some questions in advance) with a good understanding of at_packet.c and since I've already mentioned the need for synchronizing packet.7 and packet_mmap.txt we'd also need a decent plan how to distribute/share information among both.

I'll try to come up with some ideas once I've handed in my Bachelor's thesis (deadline ends 3 weeks from now).
Is there anyone else from the kernel-side we'd need to involve besides Willem and Daniel?

Quoted 5 lines

Quoted 2 lines

Maybe we should continue this discussion in private, so we don't bore everyone to death.

Drop me a private mail if you want, but there are also benefits to public conversations ;-).

I just don't want to annoy anyone, since we kinda force Willem, Daniel and now Vince to read this :)

I'd leave that plan largely to you. It sounds like Willem and Daniel are willing to help out.

Quoted 4 lines · Daniel Borkmann

On 04/24/2014 12:21 PM, Michael Kerrisk (man-pages) wrote:
...

Quoted 5 lines

Quoted 2 lines

I'd leave that plan largely to you. It sounds like Willem and Daniel are willing to help out.

Feel free to keep us in Cc.

Absolutely. I'll be happy to help review any patches.

Great! I'll report back to you with a "plan" as soon as I've recovered from handing in my thesis (3~4 weeks from now).

Cheers,
Carsten

Am Donnerstag, den 24.04.2014, 06:47 -0400 schrieb Willem de Bruijn:

Quoted 15 lines

Quoted 9 lines · Daniel Borkmann

On 04/24/2014 12:21 PM, Michael Kerrisk (man-pages) wrote:
...

Quoted 2 lines

I'd leave that plan largely to you. It sounds like Willem and Daniel are willing to help out.

Feel free to keep us in Cc.

Absolutely. I'll be happy to help review any patches.

Quoted 23 lines · Carsten Andrich

Quoted 11 lines · Michael Kerrisk (man-pages)

Quoted 9 lines · Carsten Andrich

[...]
Unfortunately my experience with Linux packet sockets is very limited. I messed with them a few times, but only really started using SOCK_RAW packet sockets (including PACKET_MMAP) a few weeks ago (as a part of my Bachelor's thesis). I haven't looked at the linux (networking) code before Monday, when I tried to figure out if either packet.7 or I was wrong regarding PACKET_LOSS. And I've never even touched SOCK_DGRAM.

All this doesn't exactly qualify me for the job :)

Quoted 10 lines

Maybe, maybe not. On the other hand, I have the idea (may be wrong) that Vince Weaver was a beginner with perf_event_open() when he started sending me patches. He's continued doing so with a vengeance (thanks again Vince!). That has been a great help, since perf_event_open() is a complex, constantly evolving API surface, and I just don't have the time to track the details. The API described in packet.7 has not changed much over time, but the man page has seen little love over the years. An inquiring mind, willing to test things and read code are the main prerequisites. ANd it sounds like some others might chip with help and Acks.

Quoted 3 lines

We could give it a shot. It may be of an advantage to not have a deep understanding of the code driving the interface one is trying to document, as to not leave out aspects which appear to be self-evident.

(Nod.)

Quoted 7 lines

It would make sense to limit our efforts to getting the PACKET_MMAP documentation in good shape, at least for now.
I'd definitely require a reviewer (who's willing to answer some questions in advance) with a good understanding of at_packet.c and since I've already mentioned the need for synchronizing packet.7 and packet_mmap.txt we'd also need a decent plan how to distribute/share information among both.

I'd leave that plan largely to you. It sounds like Willem and Daniel are willing to help out.

Quoted 4 lines

I'll try to come up with some ideas once I've handed in my Bachelor's thesis (deadline ends 3 weeks from now).
Is there anyone else from the kernel-side we'd need to involve besides Willem and Daniel?

Maybe even Neil and Andi (CCed) might chip in from time to time.

Quoted 7 lines

Quoted 5 lines

Quoted 2 lines

Maybe we should continue this discussion in private, so we don't bore everyone to death.

Drop me a private mail if you want, but there are also benefits to public conversations ;-).

I just don't want to annoy anyone, since we kinda force Willem, Daniel and now Vince to read this :)

So it goes...

Thanks, Carsten.

Cheers,

Michael

Signature · 3 lines

Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

packet.7 is another one of those dusty corners.

Andi Kleen made a good effort in
putting the page together 15 years ago, but since then it has mostly languished, short of real love, except for a couple of patches in the last 18 months (from Daniel/Willem, and Neil Horman).