Commit ca34ce29 authored by Dave Marchevsky's avatar Dave Marchevsky Committed by Andrii Nakryiko

bpf: Improve docstring for BPF_F_USER_BUILD_ID flag

Most tools which use bpf_get_stack or bpf_get_stackid symbolicate the
stack - meaning the stack of addresses in the target process' address
space is transformed into meaningful symbol names. The
BPF_F_USER_BUILD_ID flag eases this process by finding the build_id of
the file-backed vma which the address falls in and translating the
address to an offset within the backing file.

To be more specific, the offset is a "file offset" from the beginning of
the backing file. The symbols in ET_DYN ELF objects have a st_value
which is also described as an "offset" - but an offset in the process
address space, relative to the base address of the object.

It's necessary to translate between the "file offset" and "virtual
address offset" during symbolication before they can be directly
compared. Failure to do so can lead to confusing bugs, so this patch
clarifies language in the documentation in an attempt to keep this from
happening.
Signed-off-by: default avatarDave Marchevsky <davemarchevsky@fb.com>
Signed-off-by: default avatarAndrii Nakryiko <andrii@kernel.org>
Link: https://lore.kernel.org/bpf/20220808164723.3107500-1-davemarchevsky@fb.com
parent 9e32084e
...@@ -3008,8 +3008,18 @@ union bpf_attr { ...@@ -3008,8 +3008,18 @@ union bpf_attr {
* **BPF_F_USER_STACK** * **BPF_F_USER_STACK**
* Collect a user space stack instead of a kernel stack. * Collect a user space stack instead of a kernel stack.
* **BPF_F_USER_BUILD_ID** * **BPF_F_USER_BUILD_ID**
* Collect buildid+offset instead of ips for user stack, * Collect (build_id, file_offset) instead of ips for user
* only valid if **BPF_F_USER_STACK** is also specified. * stack, only valid if **BPF_F_USER_STACK** is also
* specified.
*
* *file_offset* is an offset relative to the beginning
* of the executable or shared object file backing the vma
* which the *ip* falls in. It is *not* an offset relative
* to that object's base address. Accordingly, it must be
* adjusted by adding (sh_addr - sh_offset), where
* sh_{addr,offset} correspond to the executable section
* containing *file_offset* in the object, for comparisons
* to symbols' st_value to be valid.
* *
* **bpf_get_stack**\ () can collect up to * **bpf_get_stack**\ () can collect up to
* **PERF_MAX_STACK_DEPTH** both kernel and user frames, subject * **PERF_MAX_STACK_DEPTH** both kernel and user frames, subject
......
...@@ -3008,8 +3008,18 @@ union bpf_attr { ...@@ -3008,8 +3008,18 @@ union bpf_attr {
* **BPF_F_USER_STACK** * **BPF_F_USER_STACK**
* Collect a user space stack instead of a kernel stack. * Collect a user space stack instead of a kernel stack.
* **BPF_F_USER_BUILD_ID** * **BPF_F_USER_BUILD_ID**
* Collect buildid+offset instead of ips for user stack, * Collect (build_id, file_offset) instead of ips for user
* only valid if **BPF_F_USER_STACK** is also specified. * stack, only valid if **BPF_F_USER_STACK** is also
* specified.
*
* *file_offset* is an offset relative to the beginning
* of the executable or shared object file backing the vma
* which the *ip* falls in. It is *not* an offset relative
* to that object's base address. Accordingly, it must be
* adjusted by adding (sh_addr - sh_offset), where
* sh_{addr,offset} correspond to the executable section
* containing *file_offset* in the object, for comparisons
* to symbols' st_value to be valid.
* *
* **bpf_get_stack**\ () can collect up to * **bpf_get_stack**\ () can collect up to
* **PERF_MAX_STACK_DEPTH** both kernel and user frames, subject * **PERF_MAX_STACK_DEPTH** both kernel and user frames, subject
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment