On Wed, Nov 21, 2018 at 02:22:14PM -0800, Alexei Starovoitov wrote:
> On 11/21/18 12:18 PM, Yonghong Song wrote:
> >
> >
> > On 11/21/18 9:40 AM, Andrey Ignatov wrote:
> >> More and more projects use libbpf and one day it'll likely be packaged
> >> and distributed as DSO and that requires ABI versioning so that both
> >> compatible and incompatible changes to ABI can be introduced in a safe
> >> way in the future without breaking executables dynamically linked with a
> >> previous version of the library.
> >>
> >> Usual way to do ABI versioning is version script for the linker. Add
> >> such a script for libbpf. All global symbols currently exported via
> >> LIBBPF_API macro are added to the version script libbpf.map.
> >>
> >> The version name LIBBPF_0.0.1 is constructed from the name of the
> >> library + version specified by $(LIBBPF_VERSION) in Makefile.
> >>
> >> Version script does not duplicate the work done by LIBBPF_API macro, it
> >> rather complements it. The macro is used at compile time and can be used
> >> by compiler to do optimization that can't be done at link time, it is
> >> purely about global symbol visibility. The version script, in turn, is
> >> used at link time and takes care of ABI versioning. Both techniques are
> >> described in details in [1].
> >>
> >> Whenever ABI is changed in the future, version script should be changed
> >> appropriately.
> >
> > Maybe we should clarify the policy of how version numbers should be
> > change? Each commit which changes default global symbol ABI? Each kernel
> > release?
> >
> >>
> >> [1] https://www.akkadia.org/drepper/dsohowto.pdf
> >>
> >> Signed-off-by: Andrey Ignatov <r...@fb.com>
> >> ---
> >> tools/lib/bpf/Makefile | 4 +-
> >> tools/lib/bpf/libbpf.map | 120 +++++++++++++++++++++++++++++++++++++++
> >> 2 files changed, 123 insertions(+), 1 deletion(-)
> >> create mode 100644 tools/lib/bpf/libbpf.map
> >>
> >> diff --git a/tools/lib/bpf/Makefile b/tools/lib/bpf/Makefile
> >> index 425b480bda75..d76c41fa2d39 100644
> >> --- a/tools/lib/bpf/Makefile
> >> +++ b/tools/lib/bpf/Makefile
> >> @@ -145,6 +145,7 @@ include $(srctree)/tools/build/Makefile.include
> >>
> >> BPF_IN := $(OUTPUT)libbpf-in.o
> >> LIB_FILE := $(addprefix $(OUTPUT),$(LIB_FILE))
> >> +VERSION_SCRIPT := libbpf.map
> >>
> >> CMD_TARGETS = $(LIB_FILE)
> >>
> >> @@ -170,7 +171,8 @@ $(BPF_IN): force elfdep bpfdep
> >> $(Q)$(MAKE) $(build)=libbpf
> >>
> >> $(OUTPUT)libbpf.so: $(BPF_IN)
> >> - $(QUIET_LINK)$(CC) --shared $^ -o $@
> >> + $(QUIET_LINK)$(CC) --shared -Wl,--version-script=$(VERSION_SCRIPT) \
> >> + $^ -o $@
> >>
> >> $(OUTPUT)libbpf.a: $(BPF_IN)
> >> $(QUIET_LINK)$(RM) $@; $(AR) rcs $@ $^
> >> diff --git a/tools/lib/bpf/libbpf.map b/tools/lib/bpf/libbpf.map
> >> new file mode 100644
> >> index 000000000000..9fe416b68c7d
> >> --- /dev/null
> >> +++ b/tools/lib/bpf/libbpf.map
> >> @@ -0,0 +1,120 @@
> >> +LIBBPF_0.0.1 {
> >> + global:
> >> + bpf_btf_get_fd_by_id;
> >
> > Do you think we could use this opportunities to
> > make naming more consistent? For example,
> > bpf_btf_get_fd_by_id => btf__get_fd_by_id?
>
> I think this one is fine since it matches
> bpf_[map|prog]_get_fd_by_id()
> and it's a wrapper.
Agree with keeping btf's get_fd_by_id() name to match with
other get_fd_by_id() interfaces.
>
> >> + bpf_create_map;
> >> + bpf_create_map_in_map;
> >> + bpf_create_map_in_map_node;
> >> + bpf_create_map_name;
> >> + bpf_create_map_node;
> >> + bpf_create_map_xattr;
> >> + bpf_load_btf;
> >> + bpf_load_program;
> >> + bpf_load_program_xattr;
> >> + bpf_map__btf_key_type_id;
> >> + bpf_map__btf_value_type_id;
> >> + bpf_map__def;
> >> + bpf_map_delete_elem; > + bpf_map__fd;
> >> + bpf_map_get_fd_by_id;
> >> + bpf_map_get_next_id;
> >> + bpf_map_get_next_key; > +
> >> bpf_map__is_offload_neutral;
> >> + bpf_map_lookup_and_delete_elem;
> >> + bpf_map_lookup_elem;
> >> + bpf_map__name;
> >> + bpf_map__next;
> >> + bpf_map__pin;
> >> + bpf_map__prev;
> >> + bpf_map__priv;
> >> + bpf_map__reuse_fd;
> >> + bpf_map__set_ifindex;
> >> + bpf_map__set_priv;
> >> + bpf_map__unpin;
> >> + bpf_map_update_elem;
> >> + bpf_object__btf_fd;
> >> + bpf_object__close;
> >> + bpf_object__find_map_by_name;
> >> + bpf_object__find_map_by_offset;
> >> + bpf_object__find_program_by_title;
> >> + bpf_object__kversion;
> >> + bpf_object__load;
> >> + bpf_object__name;
> >> + bpf_object__next;
> >> + bpf_object__open;
> >> + bpf_object__open_buffer;
> >> + bpf_object__open_xattr;
> >> + bpf_object__pin;
> >> + bpf_object__pin_maps;
> >> + bpf_object__pin_programs;
> >> + bpf_object__priv;
> >> + bpf_object__set_priv;
> >> + bpf_object__unload;
> >> + bpf_object__unpin_maps;
> >> + bpf_object__unpin_programs;
> >> + bpf_obj_get;
> >> + bpf_obj_get_info_by_fd;
> >> + bpf_obj_pin;
> >> + bpf_perf_event_read_simple;
> >> + bpf_prog_attach;
> >> + bpf_prog_detach;
> >> + bpf_prog_detach2;
> >> + bpf_prog_get_fd_by_id;
> >> + bpf_prog_get_next_id;
> >> + bpf_prog_load;
> >> + bpf_prog_load_xattr;
> >> + bpf_prog_query;
> >> + bpf_program__fd;
> >> + bpf_program__is_kprobe;
> >> + bpf_program__is_perf_event;
> >> + bpf_program__is_raw_tracepoint;
> >> + bpf_program__is_sched_act;
> >> + bpf_program__is_sched_cls;
> >> + bpf_program__is_socket_filter;
> >> + bpf_program__is_tracepoint;
> >> + bpf_program__is_xdp;
> >> + bpf_program__load;
> >> + bpf_program__next;
> >> + bpf_program__nth_fd;
> >> + bpf_program__pin;
> >> + bpf_program__pin_instance;
> >> + bpf_program__prev;
> >> + bpf_program__priv;
> >> + bpf_program__set_expected_attach_type;
> >> + bpf_program__set_ifindex;
> >> + bpf_program__set_kprobe;
> >> + bpf_program__set_perf_event;
> >> + bpf_program__set_prep;
> >> + bpf_program__set_priv;
> >> + bpf_program__set_raw_tracepoint;
> >> + bpf_program__set_sched_act;
> >> + bpf_program__set_sched_cls;
> >> + bpf_program__set_socket_filter;
> >> + bpf_program__set_tracepoint;
> >> + bpf_program__set_type;
> >> + bpf_program__set_xdp;
> >> + bpf_program__title;
> >> + bpf_program__unload;
> >> + bpf_program__unpin;
> >> + bpf_program__unpin_instance;
> >> + bpf_prog_test_run;
> >> + bpf_raw_tracepoint_open;
> >> + bpf_set_link_xdp_fd;
> >> + bpf_task_fd_query;
> >> + bpf_verify_program;
> >> + btf__fd;
> >> + btf__find_by_name;
> >> + btf__free;
> >> + btf_get_from_id;
> > btf_get_from_id => btf__get_from_id?
>
> this one makes sense indeed. Martin, thoughts?
Agree. We overlooked this in the earlier func_info patch set.
I also have this change locally in my current working patchset.
I think it makes sense to have the change go with this libbpf version
patchset as a cleanup effort. It is what I have. Feel free
to reuse any of it:
>From 32a1489619184d7965f235a86f082f2710a2ba3c Mon Sep 17 00:00:00 2001
From: Martin KaFai Lau <ka...@fb.com>
Date: Wed, 21 Nov 2018 09:21:17 -0800
Subject: [PATCH 3/8] bpf: libbpf: Name changing for btf_get_from_id
s/btf_get_from_id/btf__get_from_id/ to restore the API naming convention.
Signed-off-by: Martin KaFai Lau <ka...@fb.com>
---
tools/bpf/bpftool/map.c | 4 ++--
tools/bpf/bpftool/prog.c | 2 +-
tools/lib/bpf/btf.c | 2 +-
tools/lib/bpf/btf.h | 2 +-
tools/testing/selftests/bpf/test_btf.c | 2 +-
5 files changed, 6 insertions(+), 6 deletions(-)
diff --git a/tools/bpf/bpftool/map.c b/tools/bpf/bpftool/map.c
index a1ae2a3e9fef..96be42f288f5 100644
--- a/tools/bpf/bpftool/map.c
+++ b/tools/bpf/bpftool/map.c
@@ -711,7 +711,7 @@ static int do_dump(int argc, char **argv)
prev_key = NULL;
- err = btf_get_from_id(info.btf_id, &btf);
+ err = btf__get_from_id(info.btf_id, &btf);
if (err) {
p_err("failed to get btf");
goto exit_free;
@@ -855,7 +855,7 @@ static int do_lookup(int argc, char **argv)
}
/* here means bpf_map_lookup_elem() succeeded */
- err = btf_get_from_id(info.btf_id, &btf);
+ err = btf__get_from_id(info.btf_id, &btf);
if (err) {
p_err("failed to get btf");
goto exit_free;
diff --git a/tools/bpf/bpftool/prog.c b/tools/bpf/bpftool/prog.c
index 37b1daf19da6..521a1073d1b4 100644
--- a/tools/bpf/bpftool/prog.c
+++ b/tools/bpf/bpftool/prog.c
@@ -622,7 +622,7 @@ static int do_dump(int argc, char **argv)
goto err_free;
}
- if (info.btf_id && btf_get_from_id(info.btf_id, &btf)) {
+ if (info.btf_id && btf__get_from_id(info.btf_id, &btf)) {
p_err("failed to get btf");
goto err_free;
}
diff --git a/tools/lib/bpf/btf.c b/tools/lib/bpf/btf.c
index 13ddc4bd24ee..eadcf8dfd295 100644
--- a/tools/lib/bpf/btf.c
+++ b/tools/lib/bpf/btf.c
@@ -415,7 +415,7 @@ const char *btf__name_by_offset(const struct btf *btf,
__u32 offset)
return NULL;
}
-int btf_get_from_id(__u32 id, struct btf **btf)
+int btf__get_from_id(__u32 id, struct btf **btf)
{
struct bpf_btf_info btf_info = { 0 };
__u32 len = sizeof(btf_info);
diff --git a/tools/lib/bpf/btf.h b/tools/lib/bpf/btf.h
index 386b2ffc32a3..2991b9f93e16 100644
--- a/tools/lib/bpf/btf.h
+++ b/tools/lib/bpf/btf.h
@@ -69,7 +69,7 @@ LIBBPF_API __s64 btf__resolve_size(const struct btf *btf,
__u32 type_id);
LIBBPF_API int btf__resolve_type(const struct btf *btf, __u32 type_id);
LIBBPF_API int btf__fd(const struct btf *btf);
LIBBPF_API const char *btf__name_by_offset(const struct btf *btf, __u32
offset);
-LIBBPF_API int btf_get_from_id(__u32 id, struct btf **btf);
+LIBBPF_API int btf__get_from_id(__u32 id, struct btf **btf);
struct btf_ext *btf_ext__new(__u8 *data, __u32 size, btf_print_fn_t err_log);
void btf_ext__free(struct btf_ext *btf_ext);
diff --git a/tools/testing/selftests/bpf/test_btf.c
b/tools/testing/selftests/bpf/test_btf.c
index 7b1b160d6e67..aa779f48cc2b 100644
--- a/tools/testing/selftests/bpf/test_btf.c
+++ b/tools/testing/selftests/bpf/test_btf.c
@@ -2604,7 +2604,7 @@ static int do_test_file(unsigned int test_num)
goto done;
}
- err = btf_get_from_id(info.btf_id, &btf);
+ err = btf__get_from_id(info.btf_id, &btf);
if (CHECK(err, "cannot get btf from kernel, err: %d", err))
goto done;
--
2.17.1
>
> >> + btf__name_by_offset;
> >> + btf__new;
> >> + btf__resolve_size;
> >> + btf__resolve_type;
> >> + btf__type_by_id;
> >> + libbpf_attach_type_by_name;
> >> + libbpf_get_error;
> >> + libbpf_prog_type_by_name;
> >> + libbpf_set_print;
> >> + libbpf_strerror;
> >
> > Anything else? We have btf__, bpf_program__ prefixes with double "_"
> > while with libbpf_, bpf_<wrapper> as single "_". Not sure whether they
> > need change or not.
>
> the convention is that syscall wrappers like bpf_map_lookup_elem()
> have single _ and map one-to-one to syscall commands.
> Double _ is for objects. That's a coding style of perf.
> Today btf, bpf_program, bpf_map, bpf_objects are objects.
> libbpf_ is a prefix for auxiliary funcs.
>
> We need to document it in a readme file.
