[PATCH bpf-next] bpf: Add document for 'dst_port' of 'struct bpf_sock'

[menglong8 . dong]

From: Menglong Dong <imagedong@xxxxxxxxxxx>

The description of 'dst_port' in 'struct bpf_sock' is not accurated.
In fact, 'dst_port' is not in network byte order, it is 'partly' in
network byte order.

We can see it in bpf_sock_convert_ctx_access():

> case offsetof(struct bpf_sock, dst_port):
> 	*insn++ = BPF_LDX_MEM(
> 		BPF_FIELD_SIZEOF(struct sock_common, skc_dport),
> 		si->dst_reg, si->src_reg,
> 		bpf_target_off(struct sock_common, skc_dport,
> 			       sizeof_field(struct sock_common,
> 					    skc_dport),
> 			       target_size));

It simply passes 'sock_common->skc_dport' to 'bpf_sock->dst_port',
which makes that the low 16-bits of 'dst_port' is equal to 'skc_port'
and is in network byte order, but the high 16-bites of 'dst_port' is
0. And the actual port is 'bpf_ntohs((__u16)dst_port)', and
'bpf_ntohl(dst_port)' is totally not the right port.

This is different form 'remote_port' in 'struct bpf_sock_ops' or
'struct __sk_buff':

> case offsetof(struct __sk_buff, remote_port):
> 	BUILD_BUG_ON(sizeof_field(struct sock_common, skc_dport) != 2);
>
> 	*insn++ = BPF_LDX_MEM(BPF_FIELD_SIZEOF(struct sk_buff, sk),
> 			      si->dst_reg, si->src_reg,
> 				      offsetof(struct sk_buff, sk));
> 	*insn++ = BPF_LDX_MEM(BPF_H, si->dst_reg, si->dst_reg,
> 			      bpf_target_off(struct sock_common,
> 					     skc_dport,
> 					     2, target_size));
> #ifndef __BIG_ENDIAN_BITFIELD
> 	*insn++ = BPF_ALU32_IMM(BPF_LSH, si->dst_reg, 16);
> #endif

We can see that it will left move 16-bits in little endian, which makes
the whole 'remote_port' is in network byte order, and the actual port
is bpf_ntohl(remote_port).

Note this in the document of 'dst_port'. ( Maybe this should be unified
in the code? )

Signed-off-by: Menglong Dong <imagedong@xxxxxxxxxxx>
---
 include/uapi/linux/bpf.h | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/include/uapi/linux/bpf.h b/include/uapi/linux/bpf.h
index b0383d371b9a..891a182a749a 100644
--- a/include/uapi/linux/bpf.h
+++ b/include/uapi/linux/bpf.h
@@ -5500,7 +5500,11 @@ struct bpf_sock {
 	__u32 src_ip4;
 	__u32 src_ip6[4];
 	__u32 src_port;		/* host byte order */
-	__u32 dst_port;		/* network byte order */
+	__u32 dst_port;		/* low 16-bits are in network byte order,
+				 * and high 16-bits are filled by 0.
+				 * So the real port in host byte order is
+				 * bpf_ntohs((__u16)dst_port).
+				 */
 	__u32 dst_ip4;
 	__u32 dst_ip6[4];
 	__u32 state;
-- 
2.34.1