Re: [PATCH V3 2/2] tools/perf: Add kernel-doc comment to auxtrace_record__init() function

[sashiko-bot@kernel.org]

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [Low] Documentation mismatch: `auxtrace_record__init()` can return positive error codes.
--

commit a2b68fba99416692edd38910a4c62adfdf1b490d
Author: Athira Rajeev <atrajeev@linux.ibm.com>

tools/perf: Add kernel-doc comment to auxtrace_record__init() function

This commit adds a kernel-doc comment describing the parameters and return code
for auxtrace_record__init(). It also moves the __maybe_unused attribute to fix
warnings generated by scripts/kernel-doc.

> diff --git a/tools/perf/util/auxtrace.c b/tools/perf/util/auxtrace.c
> index a224687ffbc1..6aeccedc7f2d 100644
> --- a/tools/perf/util/auxtrace.c
> +++ b/tools/perf/util/auxtrace.c
[ ... ]
> @@ -896,8 +896,23 @@ int auxtrace_parse_aux_action(struct evlist *evlist)
>  	return 0;
>  }
>  
> +/**
> + * auxtrace_record__init - Initialize an AUX area tracing record.
> + * @evlist: The list of events to check for AUX area tracing event.
> + * @err: Pointer to an integer to store return code.
> + *
> + * This function looks through the @evlist to determine which AUX area
> + * tracing hardware is being used and initializes the auxtrace_record
> + * structure.
> + *
> + * Return:
> + * a) A pointer to the struct auxtrace_record on success.
> + * b) NULL with @err = 0 if no AUX area tracing event is found/supported
> + *    (not considered an error).
> + * c) NULL with @err < 0 on actual auxtrace_record__init failure.
> + */

Is this description for case 'c' completely accurate?

Looking at the architecture-specific implementations, such as the one in
tools/perf/arch/x86/util/auxtrace.c, it appears the function can return
positive error codes. For instance, the x86 implementation calls get_cpuid(),
which returns ENOBUFS (a positive integer) on failure. This positive value
is then assigned to *err before returning NULL.

Could this comment be updated to reflect that *err can be any non-zero
value on failure, rather than strictly less than zero?

>  struct auxtrace_record *__weak
> -auxtrace_record__init(struct evlist *evlist __maybe_unused, int *err)
> +auxtrace_record__init(struct evlist __maybe_unused *evlist, int *err)
>  {
>  	*err = 0;
>  	return NULL;
>  }

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20260502073924.99965-1-atrajeev@linux.ibm.com?part=2