0001 .. SPDX-License-Identifier: GPL-2.0
0002 .. include:: <isonum.txt>
0003
0004 ==================
0005 ACPI Scan Handlers
0006 ==================
0007
0008 :Copyright: |copy| 2012, Intel Corporation
0009
0010 :Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
0011
0012 During system initialization and ACPI-based device hot-add, the ACPI namespace
0013 is scanned in search of device objects that generally represent various pieces
0014 of hardware. This causes a struct acpi_device object to be created and
0015 registered with the driver core for every device object in the ACPI namespace
0016 and the hierarchy of those struct acpi_device objects reflects the namespace
0017 layout (i.e. parent device objects in the namespace are represented by parent
0018 struct acpi_device objects and analogously for their children). Those struct
0019 acpi_device objects are referred to as "device nodes" in what follows, but they
0020 should not be confused with struct device_node objects used by the Device Trees
0021 parsing code (although their role is analogous to the role of those objects).
0022
0023 During ACPI-based device hot-remove device nodes representing pieces of hardware
0024 being removed are unregistered and deleted.
0025
0026 The core ACPI namespace scanning code in drivers/acpi/scan.c carries out basic
0027 initialization of device nodes, such as retrieving common configuration
0028 information from the device objects represented by them and populating them with
0029 appropriate data, but some of them require additional handling after they have
0030 been registered. For example, if the given device node represents a PCI host
0031 bridge, its registration should cause the PCI bus under that bridge to be
0032 enumerated and PCI devices on that bus to be registered with the driver core.
0033 Similarly, if the device node represents a PCI interrupt link, it is necessary
0034 to configure that link so that the kernel can use it.
0035
0036 Those additional configuration tasks usually depend on the type of the hardware
0037 component represented by the given device node which can be determined on the
0038 basis of the device node's hardware ID (HID). They are performed by objects
0039 called ACPI scan handlers represented by the following structure::
0040
0041 struct acpi_scan_handler {
0042 const struct acpi_device_id *ids;
0043 struct list_head list_node;
0044 int (*attach)(struct acpi_device *dev, const struct acpi_device_id *id);
0045 void (*detach)(struct acpi_device *dev);
0046 };
0047
0048 where ids is the list of IDs of device nodes the given handler is supposed to
0049 take care of, list_node is the hook to the global list of ACPI scan handlers
0050 maintained by the ACPI core and the .attach() and .detach() callbacks are
0051 executed, respectively, after registration of new device nodes and before
0052 unregistration of device nodes the handler attached to previously.
0053
0054 The namespace scanning function, acpi_bus_scan(), first registers all of the
0055 device nodes in the given namespace scope with the driver core. Then, it tries
0056 to match a scan handler against each of them using the ids arrays of the
0057 available scan handlers. If a matching scan handler is found, its .attach()
0058 callback is executed for the given device node. If that callback returns 1,
0059 that means that the handler has claimed the device node and is now responsible
0060 for carrying out any additional configuration tasks related to it. It also will
0061 be responsible for preparing the device node for unregistration in that case.
0062 The device node's handler field is then populated with the address of the scan
0063 handler that has claimed it.
0064
0065 If the .attach() callback returns 0, it means that the device node is not
0066 interesting to the given scan handler and may be matched against the next scan
0067 handler in the list. If it returns a (negative) error code, that means that
0068 the namespace scan should be terminated due to a serious error. The error code
0069 returned should then reflect the type of the error.
0070
0071 The namespace trimming function, acpi_bus_trim(), first executes .detach()
0072 callbacks from the scan handlers of all device nodes in the given namespace
0073 scope (if they have scan handlers). Next, it unregisters all of the device
0074 nodes in that scope.
0075
0076 ACPI scan handlers can be added to the list maintained by the ACPI core with the
0077 help of the acpi_scan_add_handler() function taking a pointer to the new scan
0078 handler as an argument. The order in which scan handlers are added to the list
0079 is the order in which they are matched against device nodes during namespace
0080 scans.
0081
0082 All scan handles must be added to the list before acpi_bus_scan() is run for the
0083 first time and they cannot be removed from it.
