Hi Daniel,

On 5/4/21 10:06 PM, Daniel Borkmann wrote:

quoted

On 5/4/21 6:08 PM, Daniel Borkmann wrote:
 >
 > But what /problem/ is this really solving? Why bother to change 
this /now/
 > after so many years?! I think this is causing more confusion than 
solving
 > anything, really. Moreover, what are you doing with all the
 > __{le,be}{16,32,64}
 > types in uapi? Anyway, NAK for bpf.2 specifically, and the idea 
generally..

I'm trying to clarify the manual pages as much as possible, by using 
standard conventions and similar structure all around the pages.  Not 
everyone understands kernel conventions.  Basically, Zack said very 
much what I had in mind with this patch.

But then are you also converting, for example, __{le,be}{16,32,64} to plain
uint{16,32,64}_t in the man pages and thus removing contextual information
(or inventing new equivalent types)?

What about other types exposed to user space like __sum16, __wsum, or 
__poll_t
when they are part of a man page, etc?

Sorry, I forgot to address that part in my answer.  If there's no 
standard way of naming a type without losing information, we can use the 
kernel naming.  I have no objection to that.

These are the only pages that seem to be using those:

$ grep -Enr '\b__[a-z][a-z]+[0-9]+' man?
man2/clone.2:44:clone, __clone2, clone3 \- create a child process
man2/clone.2:1694:.BI "int __clone2(int (*" "fn" ")(void *),"
man2/clone.2:1717:.BR __clone2 ()
man7/sock_diag.7:362:    __be16  idiag_sport;
man7/sock_diag.7:363:    __be16  idiag_dport;
man7/sock_diag.7:364:    __be32  idiag_src[4];
man7/sock_diag.7:365:    __be32  idiag_dst[4];
man7/bpf-helpers.7:514:.B \fBlong bpf_skb_vlan_push(struct sk_buff 
*\fP\fIskb\fP\fB, __be16\fP \fIvlan_proto\fP\fB, u16\fP 
\fIvlan_tci\fP\fB)\fP
man7/bpf-helpers.7:878:.B \fBs64 bpf_csum_diff(__be32 *\fP\fIfrom\fP\fB, 
u32\fP \fIfrom_size\fP\fB, __be32 *\fP\fIto\fP\fB, u32\fP 
\fIto_size\fP\fB, __wsum\fP \fIseed\fP\fB)\fP
man7/bpf-helpers.7:949:.B \fBlong bpf_skb_change_proto(struct sk_buff 
*\fP\fIskb\fP\fB, __be16\fP \fIproto\fP\fB, u64\fP \fIflags\fP\fB)\fP
man7/system_data_types.7:473:.I __int128
man7/system_data_types.7:475:.I __int128
man7/system_data_types.7:1584:.I unsigned __int128
man7/system_data_types.7:1586:.I unsigned __int128
$

So sock_diag.7 and bpf-helpers.7 and only a handful of cases. Not much 
of a problem.  I'd keep those untouched.

Regards,

Alex



-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/