From nobody Thu Oct 2 14:13:38 2025 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 876E230CD95; Mon, 15 Sep 2025 18:30:17 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1757961017; cv=none; b=LVfWMM+RQS7MyxtBbLmoZT6bqbmssufIe4kwJBjAQwv9KRDpeI8J4kTH2o/uN9H/vDNvsw6naGw4w8fC23h0ifvo5NhvISHiSNbooUKVG9WApU0bvb6ZtsKJe9MaHSOJbG/Q31ohB5vFpz5/LcSjQcDY7gXfTZj+R+xCNvf4PQU= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1757961017; c=relaxed/simple; bh=WGVvkUpHbJrKqCuo2vUXTzTO+Jv4JiDs/XNg/A33U+A=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=LjWuwY9HeK87L+3TGc0Xk1qncJ4PR1mN0wzOQpGA9EvcS7UAdjQpRbc6RQ2CcITGIqT0qR5M4WGBaS7UnzQAPyiXYVQ+gMSogQfMU1VtGdQkrkVTDZvqm6yBS8F54SW3hhok7rQZYpXyVk5ylMqpDDynfMzlwXh1tkCJaRuIgWU= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=WqWSpndJ; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="WqWSpndJ" Received: by smtp.kernel.org (Postfix) with ESMTPSA id DD4A0C4CEF7; Mon, 15 Sep 2025 18:30:15 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1757961017; bh=WGVvkUpHbJrKqCuo2vUXTzTO+Jv4JiDs/XNg/A33U+A=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=WqWSpndJe1MVmR4pLgKi5jpBjouTH7LVyMrETWcnDoX44XOAoTWjWhItYeq5nWV9C 7kKBUiK/jOvTquW20rNG7x58xcleYxQv4yXpMeMZZI6uLZCrTy7PqRqCHdNwGl0atr 2aJLQHNjmWM0+rdEozbfqoY7X2nI48vdcAAnDstBmvBJIjzBCZd8nVzEEpLTw2Cca5 R60b+HQMIFjtN6yJSeywUZFUevmrS9YiirvbPMpqLrU77WtjJUc5yGe08ppMwOxlM7 Zdl/g5m24UQ6+DXrgvKhbaf5byfDcPRP+ZtxLMXhQ3mo8aGicOwYv5+TPVaMUuagrj tF2nn5hdc2VcA== From: "Rafael J. Wysocki" To: Linux ACPI Cc: LKML , Mika Westerberg , Andy Shevchenko , Sakari Ailus Subject: [PATCH v2 3/5] ACPI: property: Add code comments explaining what is going on Date: Mon, 15 Sep 2025 20:25:13 +0200 Message-ID: <3008321.e9J7NaK4W3@rafael.j.wysocki> Organization: Linux Kernel Development In-Reply-To: <5922318.DvuYhMxLoT@rafael.j.wysocki> References: <5922318.DvuYhMxLoT@rafael.j.wysocki> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" From: Rafael J. Wysocki 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 knowledge that is not mentioned anywhere. Add code comments explaining these things. Signed-off-by: Rafael J. Wysocki --- v1 -> v2: * Previously [2/4] * Rebase on top of the new [2/5] * Rephrase the comment under ACPI_TYPE_PACKAGE --- drivers/acpi/property.c | 46 +++++++++++++++++++++++++++++++++++++++++++= +-- 1 file changed, 44 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); =20 + /* + * 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 =3D 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 =3D true; =20 @@ -133,6 +144,12 @@ static bool acpi_nondev_subnode_ok(acpi_ acpi_handle handle; acpi_status status; =20 + /* + * 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; =20 @@ -162,6 +179,10 @@ static bool acpi_add_nondev_subnodes(acp bool ret =3D false; int i; =20 + /* + * 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 =3D 0; i < links->package.count; i++) { union acpi_object *link, *desc; bool result; @@ -171,17 +192,38 @@ static bool acpi_add_nondev_subnodes(acp if (link->package.count !=3D 2) continue; =20 - /* The first one must be a string. */ + /* The first one (the key) must be a string. */ if (link->package.elements[0].type !=3D ACPI_TYPE_STRING) continue; =20 - /* The second one may be a string or a package. */ + /* The second one (the target) may be a string 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 =3D acpi_nondev_subnode_ok(scope, link, list, parent); break; case ACPI_TYPE_PACKAGE: + /* + * This happens when a reference is used in AML to + * point to the target. Since the target is expected + * to be a named object, a reference to it will cause it + * to be avaluated in place and its return package will + * be embedded in the links package at the location of + * the 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 =3D &link->package.elements[1]; result =3D acpi_nondev_subnode_extract(desc, NULL, link, list, parent);