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

[Rafael J. Wysocki]

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