Commit 05949f63 authored by Alexei Starovoitov's avatar Alexei Starovoitov
Browse files

Merge branch 'autogen-bpf-helpers' 



Andrii Nakryiko says:

====================
This patch set adds ability to auto-generate list of BPF helper definitions.
It relies on existing scripts/bpf_helpers_doc.py and include/uapi/linux/bpf.h
having a well-defined set of comments. bpf_helper_defs.h contains all BPF
helper signatures which stay in sync with latest bpf.h UAPI. This
auto-generated header is included from bpf_helpers.h, while all previously
hand-written BPF helper definitions are simultaneously removed in patch #3.
The end result is less manually maintained and redundant boilerplate code,
while also more consistent and well-documented set of BPF helpers. Generated
helper definitions are completely independent from a specific bpf.h on
a target system, because it doesn't use BPF_FUNC_xxx enums.

v3->v4:
- instead of libbpf's Makefile, integrate with selftest/bpf's Makefile (Alexei);

v2->v3:
- delete bpf_helper_defs.h properly (Alexei);

v1->v2:
- add bpf_helper_defs.h to .gitignore and `make clean` (Alexei).
====================

Signed-off-by: default avatarAlexei Starovoitov <ast@kernel.org>
parents a9eb048d 24f25763

include/uapi/linux/bpf.h

+16 −16
Original line number Diff line number Diff line
@@ -794,7 +794,7 @@ union bpf_attr { 
 * 		A 64-bit integer containing the current GID and UID, and

 * 		created as such: *current_gid* **<< 32 \|** *current_uid*.

 *

 * int bpf_get_current_comm(char *buf, u32 size_of_buf)

 * int bpf_get_current_comm(void *buf, u32 size_of_buf)

 * 	Description

 * 		Copy the **comm** attribute of the current task into *buf* of

 * 		*size_of_buf*. The **comm** attribute contains the name of
@@ -1023,7 +1023,7 @@ union bpf_attr { 
 * 		The realm of the route for the packet associated to *skb*, or 0

 * 		if none was found.

 *

 * int bpf_perf_event_output(struct pt_regs *ctx, struct bpf_map *map, u64 flags, void *data, u64 size)

 * int bpf_perf_event_output(void *ctx, struct bpf_map *map, u64 flags, void *data, u64 size)

 * 	Description

 * 		Write raw *data* blob into a special BPF perf event held by

 * 		*map* of type **BPF_MAP_TYPE_PERF_EVENT_ARRAY**. This perf
@@ -1068,7 +1068,7 @@ union bpf_attr { 
 * 	Return

 * 		0 on success, or a negative error in case of failure.

 *

 * int bpf_skb_load_bytes(const struct sk_buff *skb, u32 offset, void *to, u32 len)

 * int bpf_skb_load_bytes(const void *skb, u32 offset, void *to, u32 len)

 * 	Description

 * 		This helper was provided as an easy way to load data from a

 * 		packet. It can be used to load *len* bytes from *offset* from
@@ -1085,7 +1085,7 @@ union bpf_attr { 
 * 	Return

 * 		0 on success, or a negative error in case of failure.

 *

 * int bpf_get_stackid(struct pt_regs *ctx, struct bpf_map *map, u64 flags)

 * int bpf_get_stackid(void *ctx, struct bpf_map *map, u64 flags)

 * 	Description

 * 		Walk a user or a kernel stack and return its id. To achieve

 * 		this, the helper needs *ctx*, which is a pointer to the context
@@ -1154,7 +1154,7 @@ union bpf_attr { 
 * 		The checksum result, or a negative error code in case of

 * 		failure.

 *

 * int bpf_skb_get_tunnel_opt(struct sk_buff *skb, u8 *opt, u32 size)

 * int bpf_skb_get_tunnel_opt(struct sk_buff *skb, void *opt, u32 size)

 * 	Description

 * 		Retrieve tunnel options metadata for the packet associated to

 * 		*skb*, and store the raw tunnel option data to the buffer *opt*
@@ -1172,7 +1172,7 @@ union bpf_attr { 
 * 	Return

 * 		The size of the option data retrieved.

 *

 * int bpf_skb_set_tunnel_opt(struct sk_buff *skb, u8 *opt, u32 size)

 * int bpf_skb_set_tunnel_opt(struct sk_buff *skb, void *opt, u32 size)

 * 	Description

 * 		Set tunnel options metadata for the packet associated to *skb*

 * 		to the option data contained in the raw buffer *opt* of *size*.
@@ -1511,7 +1511,7 @@ union bpf_attr { 
 * 	Return

 * 		0

 *

 * int bpf_setsockopt(struct bpf_sock_ops *bpf_socket, int level, int optname, char *optval, int optlen)

 * int bpf_setsockopt(struct bpf_sock_ops *bpf_socket, int level, int optname, void *optval, int optlen)

 * 	Description

 * 		Emulate a call to **setsockopt()** on the socket associated to

 * 		*bpf_socket*, which must be a full socket. The *level* at
@@ -1595,7 +1595,7 @@ union bpf_attr { 
 * 	Return

 * 		**XDP_REDIRECT** on success, or **XDP_ABORTED** on error.

 *

 * int bpf_sk_redirect_map(struct bpf_map *map, u32 key, u64 flags)

 * int bpf_sk_redirect_map(struct sk_buff *skb, struct bpf_map *map, u32 key, u64 flags)

 * 	Description

 * 		Redirect the packet to the socket referenced by *map* (of type

 * 		**BPF_MAP_TYPE_SOCKMAP**) at index *key*. Both ingress and
@@ -1715,7 +1715,7 @@ union bpf_attr { 
 * 	Return

 * 		0 on success, or a negative error in case of failure.

 *

 * int bpf_getsockopt(struct bpf_sock_ops *bpf_socket, int level, int optname, char *optval, int optlen)

 * int bpf_getsockopt(struct bpf_sock_ops *bpf_socket, int level, int optname, void *optval, int optlen)

 * 	Description

 * 		Emulate a call to **getsockopt()** on the socket associated to

 * 		*bpf_socket*, which must be a full socket. The *level* at
@@ -1947,7 +1947,7 @@ union bpf_attr { 
 * 	Return

 * 		0 on success, or a negative error in case of failure.

 *

 * int bpf_get_stack(struct pt_regs *regs, void *buf, u32 size, u64 flags)

 * int bpf_get_stack(void *ctx, void *buf, u32 size, u64 flags)

 * 	Description

 * 		Return a user or a kernel stack in bpf program provided buffer.

 * 		To achieve this, the helper needs *ctx*, which is a pointer
@@ -1980,7 +1980,7 @@ union bpf_attr { 
 * 		A non-negative value equal to or less than *size* on success,

 * 		or a negative error in case of failure.

 *

 * int bpf_skb_load_bytes_relative(const struct sk_buff *skb, u32 offset, void *to, u32 len, u32 start_header)

 * int bpf_skb_load_bytes_relative(const void *skb, u32 offset, void *to, u32 len, u32 start_header)

 * 	Description

 * 		This helper is similar to **bpf_skb_load_bytes**\ () in that

 * 		it provides an easy way to load *len* bytes from *offset*
@@ -2033,7 +2033,7 @@ union bpf_attr { 
 *		* > 0 one of **BPF_FIB_LKUP_RET_** codes explaining why the

 *		  packet is not forwarded or needs assist from full stack

 *

 * int bpf_sock_hash_update(struct bpf_sock_ops_kern *skops, struct bpf_map *map, void *key, u64 flags)

 * int bpf_sock_hash_update(struct bpf_sock_ops *skops, struct bpf_map *map, void *key, u64 flags)

 *	Description

 *		Add an entry to, or update a sockhash *map* referencing sockets.

 *		The *skops* is used as a new value for the entry associated to
@@ -2392,7 +2392,7 @@ union bpf_attr { 
 * 	Return

 * 		0 on success, or a negative error in case of failure.

 *

 * int bpf_msg_push_data(struct sk_buff *skb, u32 start, u32 len, u64 flags)

 * int bpf_msg_push_data(struct sk_msg_buff *msg, u32 start, u32 len, u64 flags)

 *	Description

 *		For socket policies, insert *len* bytes into *msg* at offset

 *		*start*.
@@ -2408,9 +2408,9 @@ union bpf_attr { 
 *	Return

 *		0 on success, or a negative error in case of failure.

 *

 * int bpf_msg_pop_data(struct sk_msg_buff *msg, u32 start, u32 pop, u64 flags)

 * int bpf_msg_pop_data(struct sk_msg_buff *msg, u32 start, u32 len, u64 flags)

 *	Description

 *		Will remove *pop* bytes from a *msg* starting at byte *start*.

 *		Will remove *len* bytes from a *msg* starting at byte *start*.

 *		This may result in **ENOMEM** errors under certain situations if

 *		an allocation and copy are required due to a full ring buffer.

 *		However, the helper will try to avoid doing the allocation
@@ -2505,7 +2505,7 @@ union bpf_attr { 
 *		A **struct bpf_tcp_sock** pointer on success, or **NULL** in

 *		case of failure.

 *

 * int bpf_skb_ecn_set_ce(struct sk_buf *skb)

 * int bpf_skb_ecn_set_ce(struct sk_buff *skb)

 *	Description

 *		Set ECN (Explicit Congestion Notification) field of IP header

 *		to **CE** (Congestion Encountered) if current value is **ECT**

scripts/bpf_helpers_doc.py

+154 −1
Original line number Diff line number Diff line
@@ -391,6 +391,154 @@ SEE ALSO 


        print('')



class PrinterHelpers(Printer):

    """

    A printer for dumping collected information about helpers as C header to

    be included from BPF program.

    @helpers: array of Helper objects to print to standard output

    """



    type_fwds = [

            'struct bpf_fib_lookup',

            'struct bpf_perf_event_data',

            'struct bpf_perf_event_value',

            'struct bpf_sock',

            'struct bpf_sock_addr',

            'struct bpf_sock_ops',

            'struct bpf_sock_tuple',

            'struct bpf_spin_lock',

            'struct bpf_sysctl',

            'struct bpf_tcp_sock',

            'struct bpf_tunnel_key',

            'struct bpf_xfrm_state',

            'struct pt_regs',

            'struct sk_reuseport_md',

            'struct sockaddr',

            'struct tcphdr',



            'struct __sk_buff',

            'struct sk_msg_md',

            'struct xpd_md',

    ]

    known_types = {

            '...',

            'void',

            'const void',

            'char',

            'const char',

            'int',

            'long',

            'unsigned long',



            '__be16',

            '__be32',

            '__wsum',



            'struct bpf_fib_lookup',

            'struct bpf_perf_event_data',

            'struct bpf_perf_event_value',

            'struct bpf_sock',

            'struct bpf_sock_addr',

            'struct bpf_sock_ops',

            'struct bpf_sock_tuple',

            'struct bpf_spin_lock',

            'struct bpf_sysctl',

            'struct bpf_tcp_sock',

            'struct bpf_tunnel_key',

            'struct bpf_xfrm_state',

            'struct pt_regs',

            'struct sk_reuseport_md',

            'struct sockaddr',

            'struct tcphdr',

    }

    mapped_types = {

            'u8': '__u8',

            'u16': '__u16',

            'u32': '__u32',

            'u64': '__u64',

            's8': '__s8',

            's16': '__s16',

            's32': '__s32',

            's64': '__s64',

            'size_t': 'unsigned long',

            'struct bpf_map': 'void',

            'struct sk_buff': 'struct __sk_buff',

            'const struct sk_buff': 'const struct __sk_buff',

            'struct sk_msg_buff': 'struct sk_msg_md',

            'struct xdp_buff': 'struct xdp_md',

    }



    def print_header(self):

        header = '''\

/* This is auto-generated file. See bpf_helpers_doc.py for details. */



/* Forward declarations of BPF structs */'''



        print(header)

        for fwd in self.type_fwds:

            print('%s;' % fwd)

        print('')



    def print_footer(self):

        footer = ''

        print(footer)



    def map_type(self, t):

        if t in self.known_types:

            return t

        if t in self.mapped_types:

            return self.mapped_types[t]

        print("")

        print("Unrecognized type '%s', please add it to known types!" % t)

        sys.exit(1)



    seen_helpers = set()



    def print_one(self, helper):

        proto = helper.proto_break_down()



        if proto['name'] in self.seen_helpers:

            return

        self.seen_helpers.add(proto['name'])



        print('/*')

        print(" * %s" % proto['name'])

        print(" *")

        if (helper.desc):

            # Do not strip all newline characters: formatted code at the end of

            # a section must be followed by a blank line.

            for line in re.sub('\n$', '', helper.desc, count=1).split('\n'):

                print(' *{}{}'.format(' \t' if line else '', line))



        if (helper.ret):

            print(' *')

            print(' * Returns')

            for line in helper.ret.rstrip().split('\n'):

                print(' *{}{}'.format(' \t' if line else '', line))



        print(' */')

        print('static %s %s(*%s)(' % (self.map_type(proto['ret_type']),

                                      proto['ret_star'], proto['name']), end='')

        comma = ''

        for i, a in enumerate(proto['args']):

            t = a['type']

            n = a['name']

            if proto['name'] == 'bpf_get_socket_cookie' and i == 0:

                    t = 'void'

                    n = 'ctx'

            one_arg = '{}{}'.format(comma, self.map_type(t))

            if n:

                if a['star']:

                    one_arg += ' {}'.format(a['star'])

                else:

                    one_arg += ' '

                one_arg += '{}'.format(n)

            comma = ', '

            print(one_arg, end='')



        print(') = (void *) %d;' % len(self.seen_helpers))

        print('')



###############################################################################



# If script is launched from scripts/ from kernel tree and can access
@@ -405,6 +553,8 @@ Parse eBPF header file and generate documentation for eBPF helper functions. 
The RST-formatted output produced can be turned into a manual page with the

rst2man utility.

""")

argParser.add_argument('--header', action='store_true',

                       help='generate C header file')

if (os.path.isfile(bpfh)):

    argParser.add_argument('--filename', help='path to include/uapi/linux/bpf.h',

                           default=bpfh)
@@ -417,5 +567,8 @@ headerParser = HeaderParser(args.filename) 
headerParser.run()



# Print formatted output to standard output.

if args.header:

    printer = PrinterHelpers(headerParser.helpers)

else:

    printer = PrinterRST(headerParser.helpers)

printer.print_all()

tools/include/uapi/linux/bpf.h

+16 −16
Original line number Diff line number Diff line
@@ -794,7 +794,7 @@ union bpf_attr { 
 * 		A 64-bit integer containing the current GID and UID, and

 * 		created as such: *current_gid* **<< 32 \|** *current_uid*.

 *

 * int bpf_get_current_comm(char *buf, u32 size_of_buf)

 * int bpf_get_current_comm(void *buf, u32 size_of_buf)

 * 	Description

 * 		Copy the **comm** attribute of the current task into *buf* of

 * 		*size_of_buf*. The **comm** attribute contains the name of
@@ -1023,7 +1023,7 @@ union bpf_attr { 
 * 		The realm of the route for the packet associated to *skb*, or 0

 * 		if none was found.

 *

 * int bpf_perf_event_output(struct pt_regs *ctx, struct bpf_map *map, u64 flags, void *data, u64 size)

 * int bpf_perf_event_output(void *ctx, struct bpf_map *map, u64 flags, void *data, u64 size)

 * 	Description

 * 		Write raw *data* blob into a special BPF perf event held by

 * 		*map* of type **BPF_MAP_TYPE_PERF_EVENT_ARRAY**. This perf
@@ -1068,7 +1068,7 @@ union bpf_attr { 
 * 	Return

 * 		0 on success, or a negative error in case of failure.

 *

 * int bpf_skb_load_bytes(const struct sk_buff *skb, u32 offset, void *to, u32 len)

 * int bpf_skb_load_bytes(const void *skb, u32 offset, void *to, u32 len)

 * 	Description

 * 		This helper was provided as an easy way to load data from a

 * 		packet. It can be used to load *len* bytes from *offset* from
@@ -1085,7 +1085,7 @@ union bpf_attr { 
 * 	Return

 * 		0 on success, or a negative error in case of failure.

 *

 * int bpf_get_stackid(struct pt_regs *ctx, struct bpf_map *map, u64 flags)

 * int bpf_get_stackid(void *ctx, struct bpf_map *map, u64 flags)

 * 	Description

 * 		Walk a user or a kernel stack and return its id. To achieve

 * 		this, the helper needs *ctx*, which is a pointer to the context
@@ -1154,7 +1154,7 @@ union bpf_attr { 
 * 		The checksum result, or a negative error code in case of

 * 		failure.

 *

 * int bpf_skb_get_tunnel_opt(struct sk_buff *skb, u8 *opt, u32 size)

 * int bpf_skb_get_tunnel_opt(struct sk_buff *skb, void *opt, u32 size)

 * 	Description

 * 		Retrieve tunnel options metadata for the packet associated to

 * 		*skb*, and store the raw tunnel option data to the buffer *opt*
@@ -1172,7 +1172,7 @@ union bpf_attr { 
 * 	Return

 * 		The size of the option data retrieved.

 *

 * int bpf_skb_set_tunnel_opt(struct sk_buff *skb, u8 *opt, u32 size)

 * int bpf_skb_set_tunnel_opt(struct sk_buff *skb, void *opt, u32 size)

 * 	Description

 * 		Set tunnel options metadata for the packet associated to *skb*

 * 		to the option data contained in the raw buffer *opt* of *size*.
@@ -1511,7 +1511,7 @@ union bpf_attr { 
 * 	Return

 * 		0

 *

 * int bpf_setsockopt(struct bpf_sock_ops *bpf_socket, int level, int optname, char *optval, int optlen)

 * int bpf_setsockopt(struct bpf_sock_ops *bpf_socket, int level, int optname, void *optval, int optlen)

 * 	Description

 * 		Emulate a call to **setsockopt()** on the socket associated to

 * 		*bpf_socket*, which must be a full socket. The *level* at
@@ -1595,7 +1595,7 @@ union bpf_attr { 
 * 	Return

 * 		**XDP_REDIRECT** on success, or **XDP_ABORTED** on error.

 *

 * int bpf_sk_redirect_map(struct bpf_map *map, u32 key, u64 flags)

 * int bpf_sk_redirect_map(struct sk_buff *skb, struct bpf_map *map, u32 key, u64 flags)

 * 	Description

 * 		Redirect the packet to the socket referenced by *map* (of type

 * 		**BPF_MAP_TYPE_SOCKMAP**) at index *key*. Both ingress and
@@ -1715,7 +1715,7 @@ union bpf_attr { 
 * 	Return

 * 		0 on success, or a negative error in case of failure.

 *

 * int bpf_getsockopt(struct bpf_sock_ops *bpf_socket, int level, int optname, char *optval, int optlen)

 * int bpf_getsockopt(struct bpf_sock_ops *bpf_socket, int level, int optname, void *optval, int optlen)

 * 	Description

 * 		Emulate a call to **getsockopt()** on the socket associated to

 * 		*bpf_socket*, which must be a full socket. The *level* at
@@ -1947,7 +1947,7 @@ union bpf_attr { 
 * 	Return

 * 		0 on success, or a negative error in case of failure.

 *

 * int bpf_get_stack(struct pt_regs *regs, void *buf, u32 size, u64 flags)

 * int bpf_get_stack(void *ctx, void *buf, u32 size, u64 flags)

 * 	Description

 * 		Return a user or a kernel stack in bpf program provided buffer.

 * 		To achieve this, the helper needs *ctx*, which is a pointer
@@ -1980,7 +1980,7 @@ union bpf_attr { 
 * 		A non-negative value equal to or less than *size* on success,

 * 		or a negative error in case of failure.

 *

 * int bpf_skb_load_bytes_relative(const struct sk_buff *skb, u32 offset, void *to, u32 len, u32 start_header)

 * int bpf_skb_load_bytes_relative(const void *skb, u32 offset, void *to, u32 len, u32 start_header)

 * 	Description

 * 		This helper is similar to **bpf_skb_load_bytes**\ () in that

 * 		it provides an easy way to load *len* bytes from *offset*
@@ -2033,7 +2033,7 @@ union bpf_attr { 
 *		* > 0 one of **BPF_FIB_LKUP_RET_** codes explaining why the

 *		  packet is not forwarded or needs assist from full stack

 *

 * int bpf_sock_hash_update(struct bpf_sock_ops_kern *skops, struct bpf_map *map, void *key, u64 flags)

 * int bpf_sock_hash_update(struct bpf_sock_ops *skops, struct bpf_map *map, void *key, u64 flags)

 *	Description

 *		Add an entry to, or update a sockhash *map* referencing sockets.

 *		The *skops* is used as a new value for the entry associated to
@@ -2392,7 +2392,7 @@ union bpf_attr { 
 * 	Return

 * 		0 on success, or a negative error in case of failure.

 *

 * int bpf_msg_push_data(struct sk_buff *skb, u32 start, u32 len, u64 flags)

 * int bpf_msg_push_data(struct sk_msg_buff *msg, u32 start, u32 len, u64 flags)

 *	Description

 *		For socket policies, insert *len* bytes into *msg* at offset

 *		*start*.
@@ -2408,9 +2408,9 @@ union bpf_attr { 
 *	Return

 *		0 on success, or a negative error in case of failure.

 *

 * int bpf_msg_pop_data(struct sk_msg_buff *msg, u32 start, u32 pop, u64 flags)

 * int bpf_msg_pop_data(struct sk_msg_buff *msg, u32 start, u32 len, u64 flags)

 *	Description

 *		Will remove *pop* bytes from a *msg* starting at byte *start*.

 *		Will remove *len* bytes from a *msg* starting at byte *start*.

 *		This may result in **ENOMEM** errors under certain situations if

 *		an allocation and copy are required due to a full ring buffer.

 *		However, the helper will try to avoid doing the allocation
@@ -2505,7 +2505,7 @@ union bpf_attr { 
 *		A **struct bpf_tcp_sock** pointer on success, or **NULL** in

 *		case of failure.

 *

 * int bpf_skb_ecn_set_ce(struct sk_buf *skb)

 * int bpf_skb_ecn_set_ce(struct sk_buff *skb)

 *	Description

 *		Set ECN (Explicit Congestion Notification) field of IP header

 *		to **CE** (Congestion Encountered) if current value is **ECT**

tools/testing/selftests/bpf/.gitignore

+1 −0
Original line number Diff line number Diff line
@@ -39,3 +39,4 @@ libbpf.so.* 
test_hashmap

test_btf_dump

xdping

/bpf_helper_defs.h

tools/testing/selftests/bpf/Makefile

+6 −2
Original line number Diff line number Diff line
@@ -90,6 +90,10 @@ include ../lib.mk 
TEST_CUSTOM_PROGS = $(OUTPUT)/urandom_read

all: $(TEST_CUSTOM_PROGS)



bpf_helper_defs.h: $(APIDIR)/linux/bpf.h

	$(BPFDIR)/../../../scripts/bpf_helpers_doc.py --header 		\

		--file $(APIDIR)/linux/bpf.h > bpf_helper_defs.h



$(OUTPUT)/urandom_read: $(OUTPUT)/%: %.c

	$(CC) -o $@ $< -Wl,--build-id
@@ -123,7 +127,7 @@ $(OUTPUT)/test_cgroup_attach: cgroup_helpers.c 
# force a rebuild of BPFOBJ when its dependencies are updated

force:



$(BPFOBJ): force

$(BPFOBJ): force bpf_helper_defs.h

	$(MAKE) -C $(BPFDIR) OUTPUT=$(OUTPUT)/



PROBE := $(shell $(LLC) -march=bpf -mcpu=probe -filetype=null /dev/null 2>&1)
@@ -319,4 +323,4 @@ $(VERIFIER_TESTS_H): $(VERIFIER_TEST_FILES) | $(VERIFIER_TESTS_DIR) 


EXTRA_CLEAN := $(TEST_CUSTOM_PROGS) $(ALU32_BUILD_DIR) $(BPF_GCC_BUILD_DIR) \

	$(VERIFIER_TESTS_H) $(PROG_TESTS_H) $(MAP_TESTS_H) \

	feature
 
	feature bpf_helper_defs.h

CRA Git | Maintained and supported by SUSTech CRA and CCSE