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

On Mon, 4 Aug 2025 12:09:09 +0100
Douglas Raillard <[email protected]> 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.

Thanks for the review.

-- Steve