Re: [patch] packet.7: PACKET_LOSS has inverse meaning

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

On 04/23/2014 10:51 AM, Carsten Andrich wrote:
> "Michael Kerrisk (man-pages)" schrieb:
>> 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.
>> ]]
>>
>> ?
> 
> 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
>> 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. 

Yes, that was a concern to me.

> 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.


Okay -- I'll remove the piece "tp_status in the tpacket_hdr structure"

> 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. 

I've added that reference into the SEE ALSO section of the man page.

> 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 ;)

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 :-). 
That would leave me in good conscience to look after the other 
900+ ;-).

Cheers,

Michael

-- 
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