Re: [PATCH 2/2] ACPICA: update documentation of acpi_walk_namespace

Rafael J. Wysocki
2021-02-08T12:44:54Z

On Mon, Feb 8, 2021 at 1:01 PM Marcin Ślusarz <marcin.slusarz@gmail.com> wrote:
>
> From: Marcin Ślusarz <marcin.slusarz@intel.com>
>
> Signed-off-by: Marcin Ślusarz <marcin.slusarz@intel.com>

A changelog would be appreciated, something like "Make the
documentation match the code and add a note regarding the return
values of the callback function and the walk to it".

Anyway, this is ACPICA material, so it should go to Erik & Bob (CCed).

Thanks!

> ---
> drivers/acpi/acpica/nsxfeval.c | 9 +++++++--
> 1 file changed, 7 insertions(+), 2 deletions(-)
>
> diff --git a/drivers/acpi/acpica/nsxfeval.c b/drivers/acpi/acpica/nsxfeval.c
> index f9d059647cc5..7149c8f70a6e 100644
> --- a/drivers/acpi/acpica/nsxfeval.c
> +++ b/drivers/acpi/acpica/nsxfeval.c
> @@ -532,8 +532,8 @@ static void acpi_ns_resolve_references(struct acpi_evaluate_info *info)
> * return_value - Location where return value of
> * user_function is put if terminated early
> *
> - * RETURNS Return value from the user_function if terminated early.
> - * Otherwise, returns NULL.
> + * RETURNS Returns status from the callback function if terminated early.
> + * Otherwise, returns a status of the walk, AE_OK if succeeded.
> *
> * DESCRIPTION: Performs a modified depth-first walk of the namespace tree,
> * starting (and ending) at the object specified by start_handle.
> @@ -542,6 +542,11 @@ static void acpi_ns_resolve_references(struct acpi_evaluate_info *info)
> * a non-zero value, the search is terminated immediately and this
> * value is returned to the caller.
> *
> + * Note that both the callback functions and the walk itself
> + * use overlapping return values (e.g. AE_OK), so user of this
> + * function can't rely only on the return value to tell if
> + * the callback function was called.
> + *
> * The point of this procedure is to provide a generic namespace
> * walk routine that can be called from multiple places to
> * provide multiple services; the callback function(s) can be
> --
> 2.25.1
>