Merge branch 'skel-fixes' (58d8dc2a) · Commits · 戴 / test

tools/bpf/bpftool/Documentation/bpftool-gen.rst

0 → 100644

+304 −0

Original line number	Diff line number	Diff line
		================
		bpftool-gen
		================
		-------------------------------------------------------------------------------
		tool for BPF code-generation
		-------------------------------------------------------------------------------

		:Manual section: 8

		SYNOPSIS
		========

		bpftool [OPTIONS] gen COMMAND

		OPTIONS := { { -j \| --json } [{ -p \| --pretty }] }

		COMMAND := { skeleton \| help** }

		GEN COMMANDS
		=============

		\| bpftool gen skeleton FILE
		\| bpftool gen help

		DESCRIPTION
		===========
		bpftool gen skeleton FILE
		Generate BPF skeleton C header file for a given FILE.

		BPF skeleton is an alternative interface to existing libbpf
		APIs for working with BPF objects. Skeleton code is intended
		to significantly shorten and simplify code to load and work
		with BPF programs from userspace side. Generated code is
		tailored to specific input BPF object FILE, reflecting its
		structure by listing out available maps, program, variables,
		etc. Skeleton eliminates the need to lookup mentioned
		components by name. Instead, if skeleton instantiation
		succeeds, they are populated in skeleton structure as valid
		libbpf types (e.g., struct bpf_map pointer) and can be
		passed to existing generic libbpf APIs.

		In addition to simple and reliable access to maps and
		programs, skeleton provides a storage for BPF links (struct
		bpf_link) for each BPF program within BPF object. When
		requested, supported BPF programs will be automatically
		attached and resulting BPF links stored for further use by
		user in pre-allocated fields in skeleton struct. For BPF
		programs that can't be automatically attached by libbpf,
		user can attach them manually, but store resulting BPF link
		in per-program link field. All such set up links will be
		automatically destroyed on BPF skeleton destruction. This
		eliminates the need for users to manage links manually and
		rely on libbpf support to detach programs and free up
		resources.

		Another facility provided by BPF skeleton is an interface to
		global variables of all supported kinds: mutable, read-only,
		as well as extern ones. This interface allows to pre-setup
		initial values of variables before BPF object is loaded and
		verified by kernel. For non-read-only variables, the same
		interface can be used to fetch values of global variables on
		userspace side, even if they are modified by BPF code.

		During skeleton generation, contents of source BPF object
		FILE is embedded within generated code and is thus not
		necessary to keep around. This ensures skeleton and BPF
		object file are matching 1-to-1 and always stay in sync.
		Generated code is dual-licensed under LGPL-2.1 and
		BSD-2-Clause licenses.

		It is a design goal and guarantee that skeleton interfaces
		are interoperable with generic libbpf APIs. User should
		always be able to use skeleton API to create and load BPF
		object, and later use libbpf APIs to keep working with
		specific maps, programs, etc.

		As part of skeleton, few custom functions are generated.
		Each of them is prefixed with object name, derived from
		object file name. I.e., if BPF object file name is
		example.o, BPF object name will be example. The
		following custom functions are provided in such case:

		- example__open and example__open_opts.
		These functions are used to instantiate skeleton. It
		corresponds to libbpf's bpf_object__open() API.
		_opts variants accepts extra bpf_object_open_opts
		options.

		- example__load.
		This function creates maps, loads and verifies BPF
		programs, initializes global data maps. It corresponds to
		libppf's bpf_object__load API.

		- example__open_and_load combines example__open and
		example__load invocations in one commonly used
		operation.

		- example__attach and example__detach
		This pair of functions allow to attach and detach,
		correspondingly, already loaded BPF object. Only BPF
		programs of types supported by libbpf for auto-attachment
		will be auto-attached and their corresponding BPF links
		instantiated. For other BPF programs, user can manually
		create a BPF link and assign it to corresponding fields in
		skeleton struct. example__detach will detach both
		links created automatically, as well as those populated by
		user manually.

		- example__destroy
		Detach and unload BPF programs, free up all the resources
		used by skeleton and BPF object.

		If BPF object has global variables, corresponding structs
		with memory layout corresponding to global data data section
		layout will be created. Currently supported ones are: .data,
		.bss, .rodata, and .extern structs/data sections. These
		data sections/structs can be used to set up initial values of
		variables, if set before example__load. Afterwards, if
		target kernel supports memory-mapped BPF arrays, same
		structs can be used to fetch and update (non-read-only)
		data from userspace, with same simplicity as for BPF side.

		bpftool gen help
		Print short help message.

		OPTIONS
		=======
		-h, --help
		Print short generic help message (similar to bpftool help).

		-V, --version
		Print version number (similar to bpftool version).

		-j, --json
		Generate JSON output. For commands that cannot produce JSON,
		this option has no effect.

		-p, --pretty
		Generate human-readable JSON output. Implies -j.

		-d, --debug
		Print all logs available from libbpf, including debug-level
		information.

		EXAMPLES
		========
		$ cat example.c
		::

		#include <stdbool.h>
		#include <linux/ptrace.h>
		#include <linux/bpf.h>
		#include "bpf_helpers.h"

		const volatile int param1 = 42;
		bool global_flag = true;
		struct { int x; } data = {};

		struct {
		__uint(type, BPF_MAP_TYPE_HASH);
		__uint(max_entries, 128);
		__type(key, int);
		__type(value, long);
		} my_map SEC(".maps");

		SEC("raw_tp/sys_enter")
		int handle_sys_enter(struct pt_regs *ctx)
		{
		static long my_static_var;
		if (global_flag)
		my_static_var++;
		else
		data.x += param1;
		return 0;
		}

		SEC("raw_tp/sys_exit")
		int handle_sys_exit(struct pt_regs *ctx)
		{
		int zero = 0;
		bpf_map_lookup_elem(&my_map, &zero);
		return 0;
		}

		This is example BPF application with two BPF programs and a mix of BPF maps
		and global variables.

		$ bpftool gen skeleton example.o
		::

		/* SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) */

		/* THIS FILE IS AUTOGENERATED! */
		#ifndef __EXAMPLE_SKEL_H__
		#define __EXAMPLE_SKEL_H__

		#include <stdlib.h>
		#include <libbpf.h>

		struct example {
		struct bpf_object_skeleton *skeleton;
		struct bpf_object *obj;
		struct {
		struct bpf_map *rodata;
		struct bpf_map *data;
		struct bpf_map *bss;
		struct bpf_map *my_map;
		} maps;
		struct {
		struct bpf_program *handle_sys_enter;
		struct bpf_program *handle_sys_exit;
		} progs;
		struct {
		struct bpf_link *handle_sys_enter;
		struct bpf_link *handle_sys_exit;
		} links;
		struct example__bss {
		struct {
		int x;
		} data;
		} *bss;
		struct example__data {
		_Bool global_flag;
		long int handle_sys_enter_my_static_var;
		} *data;
		struct example__rodata {
		int param1;
		} *rodata;
		};

		static void example__destroy(struct example *obj);
		static inline struct example *example__open_opts(
		const struct bpf_object_open_opts *opts);
		static inline struct example *example__open();
		static inline int example__load(struct example *obj);
		static inline struct example *example__open_and_load();
		static inline int example__attach(struct example *obj);
		static inline void example__detach(struct example *obj);

		#endif /* __EXAMPLE_SKEL_H__ */

		$ cat example_user.c
		::

		#include "example.skel.h"

		int main()
		{
		struct example *skel;
		int err = 0;

		skel = example__open();
		if (!skel)
		goto cleanup;

		skel->rodata->param1 = 128;

		err = example__load(skel);
		if (err)
		goto cleanup;

		err = example__attach(skel);
		if (err)
		goto cleanup;

		/* all libbpf APIs are usable */
		printf("my_map name: %s\n", bpf_map__name(skel->maps.my_map));
		printf("sys_enter prog FD: %d\n",
		bpf_program__fd(skel->progs.handle_sys_enter));

		/* detach and re-attach sys_exit program */
		bpf_link__destroy(skel->links.handle_sys_exit);
		skel->links.handle_sys_exit =
		bpf_program__attach(skel->progs.handle_sys_exit);

		printf("my_static_var: %ld\n",
		skel->bss->handle_sys_enter_my_static_var);

		cleanup:
		example__destroy(skel);
		return err;
		}

		# ./example_user
		::

		my_map name: my_map
		sys_enter prog FD: 8
		my_static_var: 7

		This is a stripped-out version of skeleton generated for above example code.

		SEE ALSO
		========
		bpf\ (2),
		bpf-helpers\ (7),
		bpftool\ (8),
		bpftool-map\ (8),
		bpftool-prog\ (8),
		bpftool-cgroup\ (8),
		bpftool-feature\ (8),
		bpftool-net\ (8),
		bpftool-perf\ (8),
		bpftool-btf\ (8)

tools/bpf/bpftool/Documentation/bpftool.rst

+2 −1

Original line number	Diff line number	Diff line
		@@ -81,4 +81,5 @@ SEE ALSO
		bpftool-feature\ (8),
		bpftool-net\ (8),
		bpftool-perf\ (8),
		bpftool-btf\ (8)
		bpftool-btf\ (8),
		bpftool-gen\ (8),

tools/bpf/bpftool/gen.c

+143 −89

Original line number	Diff line number	Diff line
		@@ -16,6 +16,7 @@
		#include <libbpf.h>
		#include <sys/types.h>
		#include <sys/stat.h>
		#include <sys/mman.h>
		#include <unistd.h>

		#include "btf.h"
		@@ -261,14 +262,16 @@ static int codegen(const char *template, ...)
		static int do_skeleton(int argc, char **argv)
		{
		char header_guard[MAX_OBJ_NAME_LEN + sizeof("__SKEL_H__")];
		size_t i, map_cnt = 0, prog_cnt = 0;
		char obj_name[MAX_OBJ_NAME_LEN];
		size_t i, map_cnt = 0, prog_cnt = 0, file_sz, mmap_sz;
		DECLARE_LIBBPF_OPTS(bpf_object_open_opts, opts);
		char obj_name[MAX_OBJ_NAME_LEN], *obj_data;
		struct bpf_object *obj = NULL;
		const char file, ident;
		struct bpf_program *prog;
		struct bpf_object *obj;
		int fd, len, err = -1;
		struct bpf_map *map;
		struct btf *btf;
		int err = -1;
		struct stat st;

		if (!REQ_ARGS(1)) {
		usage();
		@@ -281,14 +284,31 @@ static int do_skeleton(int argc, char **argv)
		return -1;
		}

		obj = bpf_object__open_file(file, NULL);
		if (IS_ERR(obj)) {
		p_err("failed to open BPF object file: %ld", PTR_ERR(obj));
		if (stat(file, &st)) {
		p_err("failed to stat() %s: %s", file, strerror(errno));
		return -1;
		}

		file_sz = st.st_size;
		mmap_sz = roundup(file_sz, sysconf(_SC_PAGE_SIZE));
		fd = open(file, O_RDONLY);
		if (fd < 0) {
		p_err("failed to open() %s: %s", file, strerror(errno));
		return -1;
		}
		obj_data = mmap(NULL, mmap_sz, PROT_READ, MAP_PRIVATE, fd, 0);
		if (obj_data == MAP_FAILED) {
		obj_data = NULL;
		p_err("failed to mmap() %s: %s", file, strerror(errno));
		goto out;
		}
		get_obj_name(obj_name, file);
		get_header_guard(header_guard, obj_name);
		opts.object_name = obj_name;
		obj = bpf_object__open_mem(obj_data, file_sz, &opts);
		if (IS_ERR(obj)) {
		obj = NULL;
		p_err("failed to open BPF object file: %ld", PTR_ERR(obj));
		goto out;
		}

		bpf_object__for_each_map(map, obj) {
		ident = get_map_ident(map);
		@@ -303,8 +323,11 @@ static int do_skeleton(int argc, char **argv)
		prog_cnt++;
		}

		get_header_guard(header_guard, obj_name);
		codegen("\
		\n\
		/* SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) */ \n\
		\n\
		/* THIS FILE IS AUTOGENERATED! */ \n\
		#ifndef %2$s \n\
		#define %2$s \n\
		@@ -356,19 +379,95 @@ static int do_skeleton(int argc, char **argv)
		\n\
		}; \n\
		\n\
		static inline struct bpf_object_skeleton * \n\
		%1$s__create_skeleton(struct %1$s obj, struct bpf_embed_data embed)\n\
		static void \n\
		%1$s__destroy(struct %1$s *obj) \n\
		{ \n\
		if (!obj) \n\
		return; \n\
		if (obj->skeleton) \n\
		bpf_object__destroy_skeleton(obj->skeleton);\n\
		free(obj); \n\
		} \n\
		\n\
		static inline int \n\
		%1$s__create_skeleton(struct %1$s *obj); \n\
		\n\
		static inline struct %1$s * \n\
		%1$s__open_opts(const struct bpf_object_open_opts *opts) \n\
		{ \n\
		struct %1$s *obj; \n\
		\n\
		obj = calloc(1, sizeof(*obj)); \n\
		if (!obj) \n\
		return NULL; \n\
		if (%1$s__create_skeleton(obj)) \n\
		goto err; \n\
		if (bpf_object__open_skeleton(obj->skeleton, opts)) \n\
		goto err; \n\
		\n\
		return obj; \n\
		err: \n\
		%1$s__destroy(obj); \n\
		return NULL; \n\
		} \n\
		\n\
		static inline struct %1$s * \n\
		%1$s__open(void) \n\
		{ \n\
		return %1$s__open_opts(NULL); \n\
		} \n\
		\n\
		static inline int \n\
		%1$s__load(struct %1$s *obj) \n\
		{ \n\
		return bpf_object__load_skeleton(obj->skeleton); \n\
		} \n\
		\n\
		static inline struct %1$s * \n\
		%1$s__open_and_load(void) \n\
		{ \n\
		struct %1$s *obj; \n\
		\n\
		obj = %1$s__open(); \n\
		if (!obj) \n\
		return NULL; \n\
		if (%1$s__load(obj)) { \n\
		%1$s__destroy(obj); \n\
		return NULL; \n\
		} \n\
		return obj; \n\
		} \n\
		\n\
		static inline int \n\
		%1$s__attach(struct %1$s *obj) \n\
		{ \n\
		return bpf_object__attach_skeleton(obj->skeleton); \n\
		} \n\
		\n\
		static inline void \n\
		%1$s__detach(struct %1$s *obj) \n\
		{ \n\
		return bpf_object__detach_skeleton(obj->skeleton); \n\
		} \n\
		",
		obj_name
		);

		codegen("\
		\n\
		\n\
		static inline int \n\
		%1$s__create_skeleton(struct %1$s *obj) \n\
		{ \n\
		struct bpf_object_skeleton *s; \n\
		\n\
		s = calloc(1, sizeof(*s)); \n\
		if (!s) \n\
		return NULL; \n\
		return -1; \n\
		obj->skeleton = s; \n\
		\n\
		s->sz = sizeof(*s); \n\
		s->name = \"%1$s\"; \n\
		s->data = embed->data; \n\
		s->data_sz = embed->size; \n\
		s->obj = &obj->obj; \n\
		",
		obj_name
		@@ -438,90 +537,45 @@ static int do_skeleton(int argc, char **argv)
		codegen("\
		\n\
		\n\
		return s; \n\
		err: \n\
		bpf_object__destroy_skeleton(s); \n\
		return NULL; \n\
		} \n\
		\n\
		static void \n\
		%1$s__destroy(struct %1$s *obj) \n\
		{ \n\
		if (!obj) \n\
		return; \n\
		if (obj->skeleton) \n\
		bpf_object__destroy_skeleton(obj->skeleton);\n\
		free(obj); \n\
		} \n\
		\n\
		static inline struct %1$s * \n\
		%1$s__open_opts(struct bpf_embed_data embed, const struct bpf_object_open_opts opts)\n\
		{ \n\
		struct %1$s *obj; \n\
		\n\
		obj = calloc(1, sizeof(*obj)); \n\
		if (!obj) \n\
		return NULL; \n\
		\n\
		obj->skeleton = %1$s__create_skeleton(obj, embed); \n\
		if (!obj->skeleton) \n\
		goto err; \n\
		s->data_sz = %d; \n\
		s->data = \"\\ \n\
		",
		file_sz);

		/* embed contents of BPF object file */
		for (i = 0, len = 0; i < file_sz; i++) {
		int w = obj_data[i] ? 4 : 2;

		len += w;
		if (len > 78) {
		printf("\\\n");
		len = w;
		}
		if (!obj_data[i])
		printf("\\0");
		else
		printf("\\x%02x", (unsigned char)obj_data[i]);
		}

		codegen("\
		\n\
		if (bpf_object__open_skeleton(obj->skeleton, opts)) \n\
		goto err; \n\
		\"; \n\
		\n\
		return obj; \n\
		return 0; \n\
		err: \n\
		%1$s__destroy(obj); \n\
		return NULL; \n\
		} \n\
		\n\
		static inline struct %1$s * \n\
		%1$s__open(struct bpf_embed_data *embed) \n\
		{ \n\
		return %1$s__open_opts(embed, NULL); \n\
		} \n\
		\n\
		static inline int \n\
		%1$s__load(struct %1$s *obj) \n\
		{ \n\
		return bpf_object__load_skeleton(obj->skeleton); \n\
		} \n\
		\n\
		static inline struct %1$s * \n\
		%1$s__open_and_load(struct bpf_embed_data *embed) \n\
		{ \n\
		struct %1$s *obj; \n\
		\n\
		obj = %1$s__open(embed); \n\
		if (!obj) \n\
		return NULL; \n\
		if (%1$s__load(obj)) { \n\
		%1$s__destroy(obj); \n\
		return NULL; \n\
		} \n\
		return obj; \n\
		} \n\
		\n\
		static inline int \n\
		%1$s__attach(struct %1$s *obj) \n\
		{ \n\
		return bpf_object__attach_skeleton(obj->skeleton); \n\
		} \n\
		\n\
		static inline void \n\
		%1$s__detach(struct %1$s *obj) \n\
		{ \n\
		return bpf_object__detach_skeleton(obj->skeleton); \n\
		bpf_object__destroy_skeleton(s); \n\
		return -1; \n\
		} \n\
		\n\
		#endif /* %2$s */ \n\
		",
		obj_name, header_guard
		);
		obj_name, header_guard);
		err = 0;
		out:
		bpf_object__close(obj);
		if (obj_data)
		munmap(obj_data, mmap_sz);
		close(fd);
		return err;
		}

tools/lib/bpf/libbpf.h

+0 −35

Original line number	Diff line number	Diff line
		@@ -600,41 +600,6 @@ bpf_program__bpil_offs_to_addr(struct bpf_prog_info_linear *info_linear);
		*/
		LIBBPF_API int libbpf_num_possible_cpus(void);

		struct bpf_embed_data {
		void *data;
		size_t size;
		};

		#define BPF_EMBED_OBJ_DECLARE(NAME) \
		extern struct bpf_embed_data NAME##_embed; \
		extern char NAME##_data[]; \
		extern char NAME##_data_end[];

		#define __BPF_EMBED_OBJ(NAME, PATH, SZ, ASM_TYPE) \
		asm ( \
		" .pushsection \".rodata\", \"a\", @progbits \n" \
		" .global "#NAME"_data \n" \
		#NAME"_data: \n" \
		" .incbin \"" PATH "\" \n" \
		" .global "#NAME"_data_end \n" \
		#NAME"_data_end: \n" \
		" .global "#NAME"_embed \n" \
		" .type "#NAME"_embed, @object \n" \
		" .size "#NAME"_size, "#SZ" \n" \
		" .align 8, \n" \
		#NAME"_embed: \n" \
		" "ASM_TYPE" "#NAME"_data \n" \
		" "ASM_TYPE" "#NAME"_data_end - "#NAME"_data \n" \
		" .popsection \n" \
		); \
		BPF_EMBED_OBJ_DECLARE(NAME)

		#if __SIZEOF_POINTER__ == 4
		#define BPF_EMBED_OBJ(NAME, PATH) __BPF_EMBED_OBJ(NAME, PATH, 8, ".long")
		#else
		#define BPF_EMBED_OBJ(NAME, PATH) __BPF_EMBED_OBJ(NAME, PATH, 16, ".quad")
		#endif

		struct bpf_map_skeleton {
		const char *name;
		struct bpf_map **map;

tools/testing/selftests/bpf/prog_tests/attach_probe.c

+1 −3

Original line number	Diff line number	Diff line
		@@ -22,8 +22,6 @@ ssize_t get_base_addr() {
		return -EINVAL;
		}

		BPF_EMBED_OBJ(probe, "test_attach_probe.o");

		void test_attach_probe(void)
		{
		int duration = 0;
		@@ -39,7 +37,7 @@ void test_attach_probe(void)
		return;
		uprobe_offset = (size_t)&get_base_addr - base_addr;

		skel = test_attach_probe__open_and_load(&probe_embed);
		skel = test_attach_probe__open_and_load();
		if (CHECK(!skel, "skel_open", "failed to open skeleton\n"))
		return;
		if (CHECK(!skel->bss, "check_bss", ".bss wasn't mmap()-ed\n"))

Original line number	Diff line number	Diff line
		@@ -81,4 +81,5 @@ SEE ALSO
		bpftool-feature\ (8),
		bpftool-net\ (8),
		bpftool-perf\ (8),
		bpftool-btf\ (8)
		bpftool-btf\ (8),
		bpftool-gen\ (8),

Admin message