Re: [PATCH bpf-next] docs/bpf: Add description for CO-RE relocations

[Yonghong Song <yonghong.song@linux.dev>]

On 8/25/23 4:40 AM, Eduard Zingerman wrote:
> On Thu, 2023-08-24 at 23:05 -0700, Yonghong Song wrote:
>>
>> On 8/24/23 4:01 PM, Eduard Zingerman wrote:
>>> Add a section on CO-RE relocations to llvm_relo.rst.
>>> Describe relevant .BTF.ext structure, `enum bpf_core_relo_kind`
>>> and `struct bpf_core_relo` in some detail.
>>> Description is based on doc-string from include/uapi/linux/bpf.h.
>>
>> Thanks Eduard. This is very helpful to give bpf deverlopers
>> some insight about how different of core relocations are
>> supported in llvm and libbpf.
> 
> Hi Yonghong,
> thank you for taking a look.
> 
>>
>> Some comments below.
>>
>>>
>>> Signed-off-by: Eduard Zingerman <eddyz87@gmail.com>
>>> ---
>>>    Documentation/bpf/btf.rst        |  27 ++++-
>>>    Documentation/bpf/llvm_reloc.rst | 178 +++++++++++++++++++++++++++++++
>>>    2 files changed, 201 insertions(+), 4 deletions(-)
>>>
>>> diff --git a/Documentation/bpf/btf.rst b/Documentation/bpf/btf.rst
>>> index f32db1f44ae9..c0530211c3c1 100644
>>> --- a/Documentation/bpf/btf.rst
>>> +++ b/Documentation/bpf/btf.rst
>>> @@ -726,8 +726,8 @@ same as the one describe in :ref:`BTF_Type_String`.
>>>    4.2 .BTF.ext section
>>>    --------------------
[...]
>>> +
>>> +The complete list of relocation kinds is represented by the following enum:
>>> +
>>> +.. code-block:: c
>>> +
>>> + enum bpf_core_relo_kind {
>>> +	BPF_CORE_FIELD_BYTE_OFFSET = 0,  /* field byte offset */
>>> +	BPF_CORE_FIELD_BYTE_SIZE   = 1,  /* field size in bytes */
>>> +	BPF_CORE_FIELD_EXISTS      = 2,  /* field existence in target kernel */
>>> +	BPF_CORE_FIELD_SIGNED      = 3,  /* field signedness (0 - unsigned, 1 - signed) */
>>> +	BPF_CORE_FIELD_LSHIFT_U64  = 4,  /* bitfield-specific left bitshift */
>>> +	BPF_CORE_FIELD_RSHIFT_U64  = 5,  /* bitfield-specific right bitshift */
>>> +	BPF_CORE_TYPE_ID_LOCAL     = 6,  /* type ID in local BPF object */
>>> +	BPF_CORE_TYPE_ID_TARGET    = 7,  /* type ID in target kernel */
>>> +	BPF_CORE_TYPE_EXISTS       = 8,  /* type existence in target kernel */
>>> +	BPF_CORE_TYPE_SIZE         = 9,  /* type size in bytes */
>>> +	BPF_CORE_ENUMVAL_EXISTS    = 10, /* enum value existence in target kernel */
>>> +	BPF_CORE_ENUMVAL_VALUE     = 11, /* enum value integer value */
>>> +	BPF_CORE_TYPE_MATCHES      = 12, /* type match in target kernel */
>>> + };
>>> +
[...]
>>> +
>>> +CO-RE Relocation Examples
>>> +=========================
>>> +
>>> +For the following C code:
>>> +
>>> +.. code-block:: c
>>> +
>>> + struct foo {
>>> +     int a;
>>> +     int b;
>>> + } __attribute__((preserve_access_index));
>>> +
>>> + enum bar { U, V };
>>> +
>>> + void buz(struct foo *s, volatile unsigned long *g) {
>>> +   s->a = 1;
>>> +   *g = __builtin_preserve_field_info(s->b, 1);
>>> +   *g = __builtin_preserve_type_info(*s, 1);
>>> +   *g = __builtin_preserve_enum_value(*(enum bar *)V, 1);
>>
>> Maybe __builtin_btf_type_id() can be added as well?
>> So far, clang only supports the above 4 builtin's for core
>> relocations.
> 
> Will add __builtin_btf_type_id() as well.
> 
>>
>>> + }
>>> +
>>> +With the following BTF definititions:
>>> +
>>> +.. code-block::
>>> +
>>> + ...
>>> + [2] STRUCT 'foo' size=8 vlen=2
>>> + 	'a' type_id=3 bits_offset=0
>>> + 	'b' type_id=3 bits_offset=32
>>> + [3] INT 'int' size=4 bits_offset=0 nr_bits=32 encoding=SIGNED
>>> + ...
>>> + [9] ENUM 'bar' encoding=UNSIGNED size=4 vlen=2
>>> + 	'U' val=0
>>> + 	'V' val=1
>>> +
>>> +The following relocation entries would be generated:
>>> +
>>> +.. code-block:: c
>>> +
>>> +   <buz>:
>>> +       0:	*(u32 *)(r1 + 0x0) = 0x1
>>> +		00:  CO-RE <byte_off> [2] struct foo::a (0:0)
>>> +       1:	r1 = 0x4
>>> +		08:  CO-RE <byte_sz> [2] struct foo::b (0:1)
>>> +       2:	*(u64 *)(r2 + 0x0) = r1
>>> +       3:	r1 = 0x8
>>> +		18:  CO-RE <type_size> [2] struct foo
>>> +       4:	*(u64 *)(r2 + 0x0) = r1
>>> +       5:	r1 = 0x1 ll
>>> +		28:  CO-RE <enumval_value> [9] enum bar::V = 1
>>> +       7:	*(u64 *)(r2 + 0x0) = r1
>>> +       8:	exit
>>> +
>>
>> It would be great if we can have an example for each of above
>> core relocation kinds.
> 
> You mean all 13 kinds, right?

Yes, it would be great if we have at least one example for each kind
to illustrate what this relo kind intends to do.

> 
>>
>>> +Note: modifications for llvm-objdump to show these relocation entries
>>> +are currently work in progress.
> 
>