Skip to contentSkip to conversation

ACPI: enumeration: Discourage to use custom _DSM methods

PATCH Applied Andy Shevchenko 2 participants 8 messages Feb 28, 2022 – Mar 3, 2022 ACPI

lore
Share & tools
lore
#0 lore raw

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

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")
---
 .../firmware-guide/acpi/enumeration.rst       | 48 ++++++++-----------
 1 file changed, 21 insertions(+), 27 deletions(-)
Documentation/firmware-guide/acpi/enumeration.rst +21 -27
index d0022567c022..3b221cc9ff5f 100644
@@ -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
 ======================
Signature · 1 line
2.34.1
#1 lore raw

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

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

Fixes 53c7626356c7 ("serdev: Add ACPI support")
---
 Documentation/firmware-guide/acpi/enumeration.rst | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)
Documentation/firmware-guide/acpi/enumeration.rst +6 -5
index 3b221cc9ff5f..f4bb5ddca528 100644
@@ -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
Signature · 1 line
2.34.1
#2 lore raw

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

In reply to 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")
---
 Documentation/firmware-guide/acpi/enumeration.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/firmware-guide/acpi/enumeration.rst +1 -1
index f4bb5ddca528..c7dbf79d45b0 100644
@@ -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
 =======================
Signature · 1 line
2.34.1
#3 lore raw

PATCH 4/7 ACPI: enumeration: Amend PWM enumeration ASL example

In reply to 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")
---
 Documentation/firmware-guide/acpi/enumeration.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/firmware-guide/acpi/enumeration.rst +1 -1
index c7dbf79d45b0..96179d2a8871 100644
@@ -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
Signature · 1 line
2.34.1
#4 lore raw

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

In reply to 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.

---
 Documentation/firmware-guide/acpi/enumeration.rst | 12 +++---------
 1 file changed, 3 insertions(+), 9 deletions(-)
Documentation/firmware-guide/acpi/enumeration.rst +3 -9
index 96179d2a8871..93fdc04de9c3 100644
@@ -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,
Signature · 1 line
2.34.1
#5 lore raw

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

In reply to 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

---
 Documentation/firmware-guide/acpi/enumeration.rst | 13 ++++++-------
 1 file changed, 6 insertions(+), 7 deletions(-)
Documentation/firmware-guide/acpi/enumeration.rst +6 -7
index 93fdc04de9c3..2e0cffb88d67 100644
@@ -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)
Signature · 1 line
2.34.1
#6 lore raw

PATCH 7/7 ACPI: enumeration: Drop comma for terminator entry

In reply to Andy Shevchenko

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

---
 Documentation/firmware-guide/acpi/enumeration.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/firmware-guide/acpi/enumeration.rst +2 -2
index 2e0cffb88d67..8c9e758f6e9b 100644
@@ -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);
 
Signature · 1 line
2.34.1
maintainer Applied
#7 lore raw
In reply to Andy Shevchenko
Quoted 70 lines · 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")
---
 .../firmware-guide/acpi/enumeration.rst       | 48 ++++++++-----------
 1 file changed, 21 insertions(+), 27 deletions(-)
Documentation/firmware-guide/acpi/enumeration.rst +17 -26
index d0022567c022..3b221cc9ff5f 100644
@@ -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)

Documentation/firmware-guide/acpi/enumeration.rst to at25 SPI eeprom driver (this is meant for the above ACPI snippet)::

Quoted 10 lines
Documentation/firmware-guide/acpi/enumeration.rst +4 -2
+               ...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!