Re: [PATCH 2/2] libtraceevent: Add man page for the new BTF functions

[Douglas Raillard <douglas.raillard@arm.com>]

On 04-08-2025 13:32, Steven Rostedt wrote:
> On Mon, 4 Aug 2025 12:09:09 +0100
> Douglas Raillard <douglas.raillard@arm.com> wrote:
> 
>>> +The *tep_btf_print_args()* takes a _tep_ handle, a trace_seq _s_ pointer
>>> +(that was initialized by *trace_seq_init(3)*), an _args_ array that holds either
>>> +4 byte or 8 byte values, the _nmem_ that is the number of values in the _args_
>>> +parameter, a _size_ that is either 4 or 8 to denote the size of each value in _args_,
>>> +and a _func_ string that is the name of the function to find the BTF information
>>> +to use for parsing. If BTF is not loaded or the _func_ name is not found it
>>> +will just print a hex value of all the _args_ into the _s_ descriptor.
>>
>> For clarity, it may be best to not call those things "args", as they may well not be args.
>> Before BTF is used to decode, this is merely the values of a bunch of registers assumed to
>> hold arguments value, with an unknown mapping of register value to actual args. For example,
>> both square() and square_struct() map the exact same assembly on arm64, clang 20 (tested with godbolt):
>>
> 
> I can update the description but I still want to keep "args" as they are
> the arg elements that were recorded from the function tracer.
> 
> They may not be registers, even though they are now. For instance, on i386,
> only the first three word size arguments are in registers. The rest comes
> from the stack.
> 
> But I agree that the description should point out that the _args_ are the
> function argument elements that were passed to the function call and are
> used to build the function parameters that the program may see.
> 
>>
>> If "int" is used instead of "unsigned long", you get an even more interesting non-1-1 mapping
>> where a single register is used to hold both 32 bit values, but only when the struct parameter
>> is used:
>>
>>     square_struct:
>>             lsr     x8, x0, #32
>>             mul     w0, w8, w0
>>             ret
>>
>> So there can be more arguments than register used, and also less arguments than register used.
> 
> Correct. But still, I would not call them registers as they may be from the
> stack. I'll stick to calling them _args_ but refer to them in the
> documentation as "argument elements" as they are the building blocks of the
> parameters that are used.

That makes sense. Encoding and decoding of that data will then evolve in fairly arch-specific
and lang-specific ways. Maybe this format should be versioned somewhere to allow future expansion
without breaking change ?

> 
> Thanks for the review.
> 
> -- Steve
>