[PATCH v1 1/7] ACPI: enumeration: Discourage to use custom _DSM methods

[PATCH v1 1/7] ACPI: enumeration: Discourage to use custom _DSM methods

[Andy Shevchenko]

Since we have _DSD established and specified (ACPI v5.1+) there is no
need to use custom _DSM methods. Rewrite documentation to use _DSD.

Fixes: f60e7074902a ("misc: at25: Make use of device property API")
Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
---
 .../firmware-guide/acpi/enumeration.rst       | 48 ++++++++-----------
 1 file changed, 21 insertions(+), 27 deletions(-)

diff --git a/Documentation/firmware-guide/acpi/enumeration.rst b/Documentation/firmware-guide/acpi/enumeration.rst
index d0022567c022..3b221cc9ff5f 100644
--- a/Documentation/firmware-guide/acpi/enumeration.rst
+++ b/Documentation/firmware-guide/acpi/enumeration.rst
@@ -227,43 +227,37 @@ to at25 SPI eeprom driver (this is meant for the above ACPI snippet)::
 	};
 
 Note that this driver actually needs more information like page size of the
-eeprom etc. but at the time writing this there is no standard way of
-passing those. One idea is to return this in _DSM method like::
+eeprom, etc. This information can be passed via _DSD method like::
 
 	Device (EEP0)
 	{
 		...
-		Method (_DSM, 4, NotSerialized)
+		Name (_DSD, Package ()
 		{
-			Store (Package (6)
+			ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+			Package ()
 			{
-				"byte-len", 1024,
-				"addr-mode", 2,
-				"page-size, 32
-			}, Local0)
-
-			// Check UUIDs etc.
-
-			Return (Local0)
-		}
-
-Then the at25 SPI driver can get this configuration by calling _DSM on its
-ACPI handle like::
-
-	struct acpi_buffer output = { ACPI_ALLOCATE_BUFFER, NULL };
-	struct acpi_object_list input;
-	acpi_status status;
+				Package () { "size", 1024 },
+				Package () { "pagesize", 32 },
+				Package () { "address-width", 16 },
+			}
+		})
+	}
 
-	/* Fill in the input buffer */
+Then the at25 SPI driver can get this configuration by calling device property
+APIs during ->probe() phase like::
 
-	status = acpi_evaluate_object(ACPI_HANDLE(&spi->dev), "_DSM",
-				      &input, &output);
-	if (ACPI_FAILURE(status))
-		/* Handle the error */
+	err = device_property_read_u32(dev, "size", &size);
+	if (err)
+		...error handling...
 
-	/* Extract the data here */
+	err = device_property_read_u32(dev, "pagesize", &page_size);
+	if (err)
+		...error handling...
 
-	kfree(output.pointer);
+	err = device_property_read_u32(dev, "address-width", &addr_width);
+	if (err)
+		...error handling...
 
 I2C serial bus support
 ======================
-- 
2.34.1

[PATCH v1 2/7] ACPI: enumeration: Update UART serial bus resource documentation

[Andy Shevchenko]

In some cases UART serial bus resource may be represented by struct
serdev_device.

Fixes: 53c7626356c7 ("serdev: Add ACPI support")
Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
---
 Documentation/firmware-guide/acpi/enumeration.rst | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/Documentation/firmware-guide/acpi/enumeration.rst b/Documentation/firmware-guide/acpi/enumeration.rst
index 3b221cc9ff5f..f4bb5ddca528 100644
--- a/Documentation/firmware-guide/acpi/enumeration.rst
+++ b/Documentation/firmware-guide/acpi/enumeration.rst
@@ -19,16 +19,17 @@ possible we decided to do following:
     platform devices.
 
   - Devices behind real busses where there is a connector resource
-    are represented as struct spi_device or struct i2c_device
-    (standard UARTs are not busses so there is no struct uart_device).
+    are represented as struct spi_device or struct i2c_device. Note
+    that standard UARTs are not busses so there is no struct uart_device,
+    although some of them may be represented by sturct serdev_device.
 
 As both ACPI and Device Tree represent a tree of devices (and their
 resources) this implementation follows the Device Tree way as much as
 possible.
 
-The ACPI implementation enumerates devices behind busses (platform, SPI and
-I2C), creates the physical devices and binds them to their ACPI handle in
-the ACPI namespace.
+The ACPI implementation enumerates devices behind busses (platform, SPI,
+I2C, and in some cases UART), creates the physical devices and binds them
+to their ACPI handle in the ACPI namespace.
 
 This means that when ACPI_HANDLE(dev) returns non-NULL the device was
 enumerated from ACPI namespace. This handle can be used to extract other
-- 
2.34.1

[PATCH v1 3/7] ACPI: enumeration: Remove redundant .owner assignment

[Andy Shevchenko]

The owner member of the struct i2c_driver is assigned by a corresponding macro.
No need to assign it explicitly.

Fixes: 59c3987805a9 ("ACPI: add documentation about ACPI 5 enumeration")
Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
---
 Documentation/firmware-guide/acpi/enumeration.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/firmware-guide/acpi/enumeration.rst b/Documentation/firmware-guide/acpi/enumeration.rst
index f4bb5ddca528..c7dbf79d45b0 100644
--- a/Documentation/firmware-guide/acpi/enumeration.rst
+++ b/Documentation/firmware-guide/acpi/enumeration.rst
@@ -282,7 +282,6 @@ input driver::
 	static struct i2c_driver mpu3050_i2c_driver = {
 		.driver	= {
 			.name	= "mpu3050",
-			.owner	= THIS_MODULE,
 			.pm	= &mpu3050_pm,
 			.of_match_table = mpu3050_of_match,
 			.acpi_match_table = ACPI_PTR(mpu3050_acpi_match),
@@ -291,6 +290,7 @@ input driver::
 		.remove		= mpu3050_remove,
 		.id_table	= mpu3050_ids,
 	};
+	module_i2c_driver(mpu3050_i2c_driver);
 
 Reference to PWM device
 =======================
-- 
2.34.1

[PATCH v1 4/7] ACPI: enumeration: Amend PWM enumeration ASL example

[Andy Shevchenko]

Drop blank line and add a closing curly brace to make ASL example closer
to the reality.

Fixes: ef3d13b86763 ("docs: firmware-guide: ACPI: Add a PWM example")
Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
---
 Documentation/firmware-guide/acpi/enumeration.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/firmware-guide/acpi/enumeration.rst b/Documentation/firmware-guide/acpi/enumeration.rst
index c7dbf79d45b0..96179d2a8871 100644
--- a/Documentation/firmware-guide/acpi/enumeration.rst
+++ b/Documentation/firmware-guide/acpi/enumeration.rst
@@ -316,9 +316,9 @@ introduced, i.e.::
                     }
                 }
             }
-
         })
         ...
+    }
 
 In the above example the PWM-based LED driver references to the PWM channel 0
 of \_SB.PCI0.PWM device with initial period setting equal to 600 ms (note that
-- 
2.34.1

[PATCH v1 5/7] ACPI: enumeration: Drop ugly ifdeffery from the examples

[Andy Shevchenko]

The ifdeffery around ACPI ID tables are ugly and in some cases
even less valuable than plain definitions. Drop them for good
to avoid spreading rather bad pattern.

Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
---
 Documentation/firmware-guide/acpi/enumeration.rst | 12 +++---------
 1 file changed, 3 insertions(+), 9 deletions(-)

diff --git a/Documentation/firmware-guide/acpi/enumeration.rst b/Documentation/firmware-guide/acpi/enumeration.rst
index 96179d2a8871..93fdc04de9c3 100644
--- a/Documentation/firmware-guide/acpi/enumeration.rst
+++ b/Documentation/firmware-guide/acpi/enumeration.rst
@@ -47,18 +47,16 @@ some minor changes.
 Adding ACPI support for an existing driver should be pretty
 straightforward. Here is the simplest example::
 
-	#ifdef CONFIG_ACPI
 	static const struct acpi_device_id mydrv_acpi_match[] = {
 		/* ACPI IDs here */
 		{ }
 	};
 	MODULE_DEVICE_TABLE(acpi, mydrv_acpi_match);
-	#endif
 
 	static struct platform_driver my_driver = {
 		...
 		.driver = {
-			.acpi_match_table = ACPI_PTR(mydrv_acpi_match),
+			.acpi_match_table = mydrv_acpi_match,
 		},
 	};
 
@@ -212,18 +210,16 @@ The SPI device drivers only need to add ACPI IDs in a similar way than with
 the platform device drivers. Below is an example where we add ACPI support
 to at25 SPI eeprom driver (this is meant for the above ACPI snippet)::
 
-	#ifdef CONFIG_ACPI
 	static const struct acpi_device_id at25_acpi_match[] = {
 		{ "AT25", 0 },
 		{ },
 	};
 	MODULE_DEVICE_TABLE(acpi, at25_acpi_match);
-	#endif
 
 	static struct spi_driver at25_driver = {
 		.driver = {
 			...
-			.acpi_match_table = ACPI_PTR(at25_acpi_match),
+			.acpi_match_table = at25_acpi_match,
 		},
 	};
 
@@ -271,20 +267,18 @@ registered.
 Below is an example of how to add ACPI support to the existing mpu3050
 input driver::
 
-	#ifdef CONFIG_ACPI
 	static const struct acpi_device_id mpu3050_acpi_match[] = {
 		{ "MPU3050", 0 },
 		{ },
 	};
 	MODULE_DEVICE_TABLE(acpi, mpu3050_acpi_match);
-	#endif
 
 	static struct i2c_driver mpu3050_i2c_driver = {
 		.driver	= {
 			.name	= "mpu3050",
 			.pm	= &mpu3050_pm,
 			.of_match_table = mpu3050_of_match,
-			.acpi_match_table = ACPI_PTR(mpu3050_acpi_match),
+			.acpi_match_table = mpu3050_acpi_match,
 		},
 		.probe		= mpu3050_probe,
 		.remove		= mpu3050_remove,
-- 
2.34.1

[PATCH v1 6/7] ACPI: enumeration: Unify Package () for properties

[Andy Shevchenko]

Unify Package () representation for properties:
 - make them one line where it's possible
 - add spaces between parentheses and curly braces
 - drop the explicit size of package

Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
---
 Documentation/firmware-guide/acpi/enumeration.rst | 13 ++++++-------
 1 file changed, 6 insertions(+), 7 deletions(-)

diff --git a/Documentation/firmware-guide/acpi/enumeration.rst b/Documentation/firmware-guide/acpi/enumeration.rst
index 93fdc04de9c3..2e0cffb88d67 100644
--- a/Documentation/firmware-guide/acpi/enumeration.rst
+++ b/Documentation/firmware-guide/acpi/enumeration.rst
@@ -167,8 +167,7 @@ The table below shows an example of its usage::
         Name (_DSD, Package () {
             ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
             Package () {
-                Package () {"interrupt-names",
-                Package (2) {"default", "alert"}},
+                Package () { "interrupt-names", Package () { "default", "alert" } },
             }
         ...
         })
@@ -193,7 +192,7 @@ Here is what the ACPI namespace for a SPI slave might look like::
 	Device (EEP0)
 	{
 		Name (_ADR, 1)
-		Name (_CID, Package() {
+		Name (_CID, Package () {
 			"ATML0025",
 			"AT25",
 		})
@@ -365,8 +364,8 @@ For example::
 			ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
 			Package ()
 			{
-				Package () {"power-gpios", Package() {^DEV, 0, 0, 0 }},
-				Package () {"irq-gpios", Package() {^DEV, 1, 0, 0 }},
+				Package () { "power-gpios", Package () { ^DEV, 0, 0, 0 } },
+				Package () { "irq-gpios", Package () { ^DEV, 1, 0, 0 } },
 			}
 		})
 		...
@@ -488,10 +487,10 @@ namespace link::
 	Device (TMP0)
 	{
 		Name (_HID, "PRP0001")
-		Name (_DSD, Package() {
+		Name (_DSD, Package () {
 			ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
 			Package () {
-				Package (2) { "compatible", "ti,tmp75" },
+				Package () { "compatible", "ti,tmp75" },
 			}
 		})
 		Method (_CRS, 0, Serialized)
-- 
2.34.1

[PATCH v1 7/7] ACPI: enumeration: Drop comma for terminator entry

[Andy Shevchenko]

Drop comma for terminator entry to avoid copy'n'paste of this pattern.

Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
---
 Documentation/firmware-guide/acpi/enumeration.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/firmware-guide/acpi/enumeration.rst b/Documentation/firmware-guide/acpi/enumeration.rst
index 2e0cffb88d67..8c9e758f6e9b 100644
--- a/Documentation/firmware-guide/acpi/enumeration.rst
+++ b/Documentation/firmware-guide/acpi/enumeration.rst
@@ -211,7 +211,7 @@ to at25 SPI eeprom driver (this is meant for the above ACPI snippet)::
 
 	static const struct acpi_device_id at25_acpi_match[] = {
 		{ "AT25", 0 },
-		{ },
+		{ }
 	};
 	MODULE_DEVICE_TABLE(acpi, at25_acpi_match);
 
@@ -268,7 +268,7 @@ input driver::
 
 	static const struct acpi_device_id mpu3050_acpi_match[] = {
 		{ "MPU3050", 0 },
-		{ },
+		{ }
 	};
 	MODULE_DEVICE_TABLE(acpi, mpu3050_acpi_match);
 
-- 
2.34.1

Re: [PATCH v1 1/7] ACPI: enumeration: Discourage to use custom _DSM methods

[Rafael J. Wysocki]

On Mon, Feb 28, 2022 at 11:39 PM Andy Shevchenko
<andriy.shevchenko@linux.intel.com> wrote:
>
> Since we have _DSD established and specified (ACPI v5.1+) there is no
> need to use custom _DSM methods. Rewrite documentation to use _DSD.
>
> Fixes: f60e7074902a ("misc: at25: Make use of device property API")
> Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
> ---
>  .../firmware-guide/acpi/enumeration.rst       | 48 ++++++++-----------
>  1 file changed, 21 insertions(+), 27 deletions(-)
>
> diff --git a/Documentation/firmware-guide/acpi/enumeration.rst b/Documentation/firmware-guide/acpi/enumeration.rst
> index d0022567c022..3b221cc9ff5f 100644
> --- a/Documentation/firmware-guide/acpi/enumeration.rst
> +++ b/Documentation/firmware-guide/acpi/enumeration.rst
> @@ -227,43 +227,37 @@ to at25 SPI eeprom driver (this is meant for the above ACPI snippet)::
>         };
>
>  Note that this driver actually needs more information like page size of the
> -eeprom etc. but at the time writing this there is no standard way of
> -passing those. One idea is to return this in _DSM method like::
> +eeprom, etc. This information can be passed via _DSD method like::
>
>         Device (EEP0)
>         {
>                 ...
> -               Method (_DSM, 4, NotSerialized)
> +               Name (_DSD, Package ()
>                 {
> -                       Store (Package (6)
> +                       ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
> +                       Package ()
>                         {
> -                               "byte-len", 1024,
> -                               "addr-mode", 2,
> -                               "page-size, 32
> -                       }, Local0)
> -
> -                       // Check UUIDs etc.
> -
> -                       Return (Local0)
> -               }
> -
> -Then the at25 SPI driver can get this configuration by calling _DSM on its
> -ACPI handle like::
> -
> -       struct acpi_buffer output = { ACPI_ALLOCATE_BUFFER, NULL };
> -       struct acpi_object_list input;
> -       acpi_status status;
> +                               Package () { "size", 1024 },
> +                               Package () { "pagesize", 32 },
> +                               Package () { "address-width", 16 },
> +                       }
> +               })
> +       }
>
> -       /* Fill in the input buffer */
> +Then the at25 SPI driver can get this configuration by calling device property
> +APIs during ->probe() phase like::
>
> -       status = acpi_evaluate_object(ACPI_HANDLE(&spi->dev), "_DSM",
> -                                     &input, &output);
> -       if (ACPI_FAILURE(status))
> -               /* Handle the error */
> +       err = device_property_read_u32(dev, "size", &size);
> +       if (err)
> +               ...error handling...
>
> -       /* Extract the data here */
> +       err = device_property_read_u32(dev, "pagesize", &page_size);
> +       if (err)
> +               ...error handling...
>
> -       kfree(output.pointer);
> +       err = device_property_read_u32(dev, "address-width", &addr_width);
> +       if (err)
> +               ...error handling...
>
>  I2C serial bus support
>  ======================
> --

Applied as 5.18 material along with the rest of the series, but I
dropped the first hunk in patch [6/7] which didn't apply.

Thanks!