From 5f3c10ac34ec2dc199e5bcc3ff856b42cf0e12df Mon Sep 17 00:00:00 2001 From: "Rafael J. Wysocki" Date: Fri, 6 Oct 2023 17:29:53 +0200 Subject: [PATCH 1/2] ACPI: docs: enumeration: Clarify ACPI bus concepts In some cases, ACPI drivers are implemented as a way to manage devices enumerated with the help of the platform firmware through ACPI. This might be confusing, since the preferred way to implement a driver for a device that cannot be enumerated natively, is a platform driver, as stated in the documentation. Clarify relationships between ACPI device objects, platform devices and ACPI Namespace entries. Suggested-by: Elena Reshetova Co-developed-by: Michal Wilczynski Signed-off-by: Michal Wilczynski Signed-off-by: Rafael J. Wysocki --- .../firmware-guide/acpi/enumeration.rst | 43 +++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/Documentation/firmware-guide/acpi/enumeration.rst b/Documentation/firmware-guide/acpi/enumeration.rst index 56d9913a3370..d79f69390991 100644 --- a/Documentation/firmware-guide/acpi/enumeration.rst +++ b/Documentation/firmware-guide/acpi/enumeration.rst @@ -64,6 +64,49 @@ If the driver needs to perform more complex initialization like getting and configuring GPIOs it can get its ACPI handle and extract this information from ACPI tables. +ACPI device objects +=================== + +Generally speaking, there are two categories of devices in a system in which +ACPI is used as an interface between the platform firmware and the OS: Devices +that can be discovered and enumerated natively, through a protocol defined for +the specific bus that they are on (for example, configuration space in PCI), +without the platform firmware assistance, and devices that need to be described +by the platform firmware so that they can be discovered. Still, for any device +known to the platform firmware, regardless of which category it falls into, +there can be a corresponding ACPI device object in the ACPI Namespace in which +case the Linux kernel will create a struct acpi_device object based on it for +that device. + +Those struct acpi_device objects are never used for binding drivers to natively +discoverable devices, because they are represented by other types of device +objects (for example, struct pci_dev for PCI devices) that are bound to by +device drivers (the corresponding struct acpi_device object is then used as +an additional source of information on the configuration of the given device). +Moreover, the core ACPI device enumeration code creates struct platform_device +objects for the majority of devices that are discovered and enumerated with the +help of the platform firmware and those platform device objects can be bound to +by platform drivers in direct analogy with the natively enumerable devices +case. Therefore it is logically inconsistent and so generally invalid to bind +drivers to struct acpi_device objects, including drivers for devices that are +discovered with the help of the platform firmware. + +Historically, ACPI drivers that bound directly to struct acpi_device objects +were implemented for some devices enumerated with the help of the platform +firmware, but this is not recommended for any new drivers. As explained above, +platform device objects are created for those devices as a rule (with a few +exceptions that are not relevant here) and so platform drivers should be used +for handling them, even though the corresponding ACPI device objects are the +only source of device configuration information in that case. + +For every device having a corresponding struct acpi_device object, the pointer +to it is returned by the ACPI_COMPANION() macro, so it is always possible to +get to the device configuration information stored in the ACPI device object +this way. Accordingly, struct acpi_device can be regarded as a part of the +interface between the kernel and the ACPI Namespace, whereas device objects of +other types (for example, struct pci_dev or struct platform_device) are used +for interacting with the rest of the system. + DMA support =========== From 470508f63ad2483b1ae82ed67cd504ad408b2a35 Mon Sep 17 00:00:00 2001 From: "Rafael J. Wysocki" Date: Fri, 6 Oct 2023 17:32:51 +0200 Subject: [PATCH 2/2] ACPI: bus: Add context argument to acpi_dev_install_notify_handler() Add void *context arrgument to the list of arguments of acpi_dev_install_notify_handler() and modify it to pass that argument as context to acpi_install_notify_handler() instead of its first argument which is problematic in general (for example, if platform drivers used it, they would rather get struct platform_device pointers or pointers to their private data from the context arguments of their notify handlers). Make all of the current callers of acpi_dev_install_notify_handler() take this change into account so as to avoid altering the general functionality. Co-developed-by: Michal Wilczynski Signed-off-by: Michal Wilczynski Signed-off-by: Rafael J. Wysocki --- drivers/acpi/ac.c | 2 +- drivers/acpi/acpi_video.c | 2 +- drivers/acpi/battery.c | 2 +- drivers/acpi/bus.c | 4 ++-- drivers/acpi/hed.c | 2 +- drivers/acpi/nfit/core.c | 2 +- drivers/acpi/thermal.c | 2 +- include/acpi/acpi_bus.h | 2 +- 8 files changed, 9 insertions(+), 9 deletions(-) diff --git a/drivers/acpi/ac.c b/drivers/acpi/ac.c index 225dc6818751..aac3e561790c 100644 --- a/drivers/acpi/ac.c +++ b/drivers/acpi/ac.c @@ -257,7 +257,7 @@ static int acpi_ac_add(struct acpi_device *device) register_acpi_notifier(&ac->battery_nb); result = acpi_dev_install_notify_handler(device, ACPI_ALL_NOTIFY, - acpi_ac_notify); + acpi_ac_notify, device); if (result) goto err_unregister; diff --git a/drivers/acpi/acpi_video.c b/drivers/acpi/acpi_video.c index b411948594ff..0b7a01f38b65 100644 --- a/drivers/acpi/acpi_video.c +++ b/drivers/acpi/acpi_video.c @@ -2062,7 +2062,7 @@ static int acpi_video_bus_add(struct acpi_device *device) goto err_del; error = acpi_dev_install_notify_handler(device, ACPI_DEVICE_NOTIFY, - acpi_video_bus_notify); + acpi_video_bus_notify, device); if (error) goto err_remove; diff --git a/drivers/acpi/battery.c b/drivers/acpi/battery.c index 969bf81e8d54..b379401ff1c2 100644 --- a/drivers/acpi/battery.c +++ b/drivers/acpi/battery.c @@ -1214,7 +1214,7 @@ static int acpi_battery_add(struct acpi_device *device) device_init_wakeup(&device->dev, 1); result = acpi_dev_install_notify_handler(device, ACPI_ALL_NOTIFY, - acpi_battery_notify); + acpi_battery_notify, device); if (result) goto fail_pm; diff --git a/drivers/acpi/bus.c b/drivers/acpi/bus.c index f41dda2d3493..88811d813a47 100644 --- a/drivers/acpi/bus.c +++ b/drivers/acpi/bus.c @@ -556,12 +556,12 @@ static void acpi_device_remove_notify_handler(struct acpi_device *device, int acpi_dev_install_notify_handler(struct acpi_device *adev, u32 handler_type, - acpi_notify_handler handler) + acpi_notify_handler handler, void *context) { acpi_status status; status = acpi_install_notify_handler(adev->handle, handler_type, - handler, adev); + handler, context); if (ACPI_FAILURE(status)) return -ENODEV; diff --git a/drivers/acpi/hed.c b/drivers/acpi/hed.c index 46c6f8c35b43..7652515a6be1 100644 --- a/drivers/acpi/hed.c +++ b/drivers/acpi/hed.c @@ -57,7 +57,7 @@ static int acpi_hed_add(struct acpi_device *device) hed_handle = device->handle; err = acpi_dev_install_notify_handler(device, ACPI_DEVICE_NOTIFY, - acpi_hed_notify); + acpi_hed_notify, device); if (err) hed_handle = NULL; diff --git a/drivers/acpi/nfit/core.c b/drivers/acpi/nfit/core.c index f0e6738ae3c9..942b84d94078 100644 --- a/drivers/acpi/nfit/core.c +++ b/drivers/acpi/nfit/core.c @@ -3391,7 +3391,7 @@ static int acpi_nfit_add(struct acpi_device *adev) return rc; rc = acpi_dev_install_notify_handler(adev, ACPI_DEVICE_NOTIFY, - acpi_nfit_notify); + acpi_nfit_notify, adev); if (rc) return rc; diff --git a/drivers/acpi/thermal.c b/drivers/acpi/thermal.c index 312730f8272e..609bc38f75ba 100644 --- a/drivers/acpi/thermal.c +++ b/drivers/acpi/thermal.c @@ -956,7 +956,7 @@ static int acpi_thermal_add(struct acpi_device *device) acpi_device_bid(device), deci_kelvin_to_celsius(tz->temperature)); result = acpi_dev_install_notify_handler(device, ACPI_DEVICE_NOTIFY, - acpi_thermal_notify); + acpi_thermal_notify, device); if (result) goto flush_wq; diff --git a/include/acpi/acpi_bus.h b/include/acpi/acpi_bus.h index 254685085c82..e49a143ac060 100644 --- a/include/acpi/acpi_bus.h +++ b/include/acpi/acpi_bus.h @@ -517,7 +517,7 @@ int acpi_bus_attach_private_data(acpi_handle, void *); void acpi_bus_detach_private_data(acpi_handle); int acpi_dev_install_notify_handler(struct acpi_device *adev, u32 handler_type, - acpi_notify_handler handler); + acpi_notify_handler handler, void *context); void acpi_dev_remove_notify_handler(struct acpi_device *adev, u32 handler_type, acpi_notify_handler handler);