mirror of https://lore.kernel.org/lkml/
 help / color / mirror / Atom feed
From: Sakari Ailus <sakari.ailus@linux.intel.com>
To: "Rafael J. Wysocki" <rafael@kernel.org>
Cc: Linux ACPI <linux-acpi@vger.kernel.org>,
	LKML <linux-kernel@vger.kernel.org>,
	Mika Westerberg <mika.westerberg@linux.intel.com>,
	Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Subject: Re: [PATCH v1 2/4] ACPI: property: Add code comments explaining what is going on
Date: Mon, 15 Sep 2025 14:32:52 +0300	[thread overview]
Message-ID: <aMf5ZNW9t_6tfsjy@kekkonen.localdomain> (raw)
In-Reply-To: <2243680.irdbgypaU6@rafael.j.wysocki>

Hi Rafael,

On Fri, Sep 12, 2025 at 09:40:58PM +0200, Rafael J. Wysocki wrote:
> From: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
> 
> In some places in the ACPI device properties handling code, it is
> unclear why the code is what it is.  Some assumptions are not documented
> and some pieces of code are based on experience that is not mentioned
> anywhere.
> 
> Add code comments explaining these things.
> 
> Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
> ---
>  drivers/acpi/property.c |   51 ++++++++++++++++++++++++++++++++++++++++++++++--
>  1 file changed, 49 insertions(+), 2 deletions(-)
> 
> --- a/drivers/acpi/property.c
> +++ b/drivers/acpi/property.c
> @@ -108,7 +108,18 @@ static bool acpi_nondev_subnode_extract(
>  	if (handle)
>  		acpi_get_parent(handle, &scope);
>  
> +	/*
> +	 * Extract properties from the _DSD-equivalent package pointed to by
> +	 * desc and use scope (if not NULL) for the completion of relative
> +	 * pathname segments.
> +	 *
> +	 * The extracted properties will be held in the new data node dn.
> +	 */
>  	result = acpi_extract_properties(scope, desc, &dn->data);
> +	/*
> +	 * Look for subnodes in the _DSD-equivalent package pointed to by desc
> +	 * and create child nodes of dn if there are any.
> +	 */
>  	if (acpi_enumerate_nondev_subnodes(scope, desc, &dn->data, &dn->fwnode))
>  		result = true;
>  
> @@ -153,6 +164,12 @@ static bool acpi_nondev_subnode_ok(acpi_
>  	acpi_handle handle;
>  	acpi_status status;
>  
> +	/*
> +	 * If the scope is unknown, the _DSD-equivalent package being parsed
> +	 * was embedded in an outer _DSD-equivalent package as a result of
> +	 * direct evaluation of an object pointed to by a reference.  In that
> +	 * case, using a pathname as the target object pointer is invalid.
> +	 */
>  	if (!scope)
>  		return false;
>  
> @@ -172,6 +189,10 @@ static bool acpi_add_nondev_subnodes(acp
>  	bool ret = false;
>  	int i;
>  
> +	/*
> +	 * Every element in the links package is expected to represent a link
> +	 * to a non-device node in a tree containing device-specific data.
> +	 */
>  	for (i = 0; i < links->package.count; i++) {
>  		union acpi_object *link, *desc;
>  		acpi_handle handle;
> @@ -182,22 +203,48 @@ static bool acpi_add_nondev_subnodes(acp
>  		if (link->package.count != 2)
>  			continue;
>  
> -		/* The first one must be a string. */
> +		/* The first one (the key) must be a string. */
>  		if (link->package.elements[0].type != ACPI_TYPE_STRING)
>  			continue;
>  
> -		/* The second one may be a string, a reference or a package. */
> +		/*
> +		 * The second one (the target) may be a string, a reference or
> +		 * a package.
> +		 */
>  		switch (link->package.elements[1].type) {
>  		case ACPI_TYPE_STRING:
> +			/*
> +			 * The string is expected to be a full pathname or a
> +			 * pathname segment relative to the given scope.  That
> +			 * pathname is expected to point to an object returning
> +			 * a package that contains _DSD-equivalent information.
> +			 */
>  			result = acpi_nondev_subnode_ok(scope, link, list,
>  							 parent);
>  			break;
>  		case ACPI_TYPE_LOCAL_REFERENCE:

I think you get ACPI_TYPE_LOCAL_REFERENCE only when you evaluate a
reference to a device object.

> +			/*
> +			 * The reference is expected to point to an object
> +			 * returning a package that contains _DSD-equivalent
> +			 * information.
> +			 */
>  			handle = link->package.elements[1].reference.handle;
>  			result = acpi_nondev_subnode_data_ok(handle, link, list,
>  							     parent);
>  			break;
>  		case ACPI_TYPE_PACKAGE:

And similarly, the result of an evaluation here is a package when a
reference points to a name object (i.e. a data node).

> +			/*
> +			 * This happens when the target package is embedded
> +			 * within the links package as a result of direct
> +			 * evaluation of an object pointed to by a reference.
> +			 *
> +			 * The target package is expected to contain _DSD-
> +			 * equivalent information, but the scope in which it
> +			 * is located in the original AML is unknown.  Thus
> +			 * it cannot contain pathname segments represented as
> +			 * strings because there is no way to build full
> +			 * pathnames out of them.
> +			 */
>  			desc = &link->package.elements[1];
>  			result = acpi_nondev_subnode_extract(desc, NULL, link,
>  							     list, parent);
> 

-- 
Kind regards,

Sakari Ailus

  reply	other threads:[~2025-09-15 11:32 UTC|newest]

Thread overview: 18+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2025-09-12 19:37 [PATCH v1 0/4] ACPI: property: Two fixes, more documentation and a cleanup Rafael J. Wysocki
2025-09-12 19:39 ` [PATCH v1 1/4] ACPI: property: Fix buffer properties extraction for subnodes Rafael J. Wysocki
2025-09-15 11:04   ` Sakari Ailus
2025-09-15 12:09     ` Rafael J. Wysocki
2025-09-12 19:40 ` [PATCH v1 2/4] ACPI: property: Add code comments explaining what is going on Rafael J. Wysocki
2025-09-15 11:32   ` Sakari Ailus [this message]
2025-09-15 12:27     ` Rafael J. Wysocki
2025-09-15 17:12       ` Rafael J. Wysocki
2025-09-15 17:51         ` Sakari Ailus
2025-09-15 18:05           ` Rafael J. Wysocki
2025-09-15 20:23             ` Sakari Ailus
2025-09-15 20:18       ` Sakari Ailus
2025-09-16 11:10         ` Rafael J. Wysocki
2025-09-12 19:42 ` [PATCH v1 3/4] ACPI: property: Do not pass NULL handles to acpi_attach_data() Rafael J. Wysocki
2025-09-15 11:49   ` Sakari Ailus
2025-09-15 12:57     ` Rafael J. Wysocki
2025-09-15 20:43       ` Sakari Ailus
2025-09-12 19:43 ` [PATCH v1 4/4] ACPI: property: Adjust failure handling in acpi_nondev_subnode_extract() Rafael J. Wysocki

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=aMf5ZNW9t_6tfsjy@kekkonen.localdomain \
    --to=sakari.ailus@linux.intel.com \
    --cc=andriy.shevchenko@linux.intel.com \
    --cc=linux-acpi@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=mika.westerberg@linux.intel.com \
    --cc=rafael@kernel.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox

all inboxes | Powered by JetHome®