1.. SPDX-License-Identifier: GPL-2.0 2.. include:: <isonum.txt> 3 4================== 5ACPI Scan Handlers 6================== 7 8:Copyright: |copy| 2012, Intel Corporation 9 10:Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com> 11 12During system initialization and ACPI-based device hot-add, the ACPI namespace 13is scanned in search of device objects that generally represent various pieces 14of hardware. This causes a struct acpi_device object to be created and 15registered with the driver core for every device object in the ACPI namespace 16and the hierarchy of those struct acpi_device objects reflects the namespace 17layout (i.e. parent device objects in the namespace are represented by parent 18struct acpi_device objects and analogously for their children). Those struct 19acpi_device objects are referred to as "device nodes" in what follows, but they 20should not be confused with struct device_node objects used by the Device Trees 21parsing code (although their role is analogous to the role of those objects). 22 23During ACPI-based device hot-remove device nodes representing pieces of hardware 24being removed are unregistered and deleted. 25 26The core ACPI namespace scanning code in drivers/acpi/scan.c carries out basic 27initialization of device nodes, such as retrieving common configuration 28information from the device objects represented by them and populating them with 29appropriate data, but some of them require additional handling after they have 30been registered. For example, if the given device node represents a PCI host 31bridge, its registration should cause the PCI bus under that bridge to be 32enumerated and PCI devices on that bus to be registered with the driver core. 33Similarly, if the device node represents a PCI interrupt link, it is necessary 34to configure that link so that the kernel can use it. 35 36Those additional configuration tasks usually depend on the type of the hardware 37component represented by the given device node which can be determined on the 38basis of the device node's hardware ID (HID). They are performed by objects 39called ACPI scan handlers represented by the following structure:: 40 41 struct acpi_scan_handler { 42 const struct acpi_device_id *ids; 43 struct list_head list_node; 44 int (*attach)(struct acpi_device *dev, const struct acpi_device_id *id); 45 void (*detach)(struct acpi_device *dev); 46 }; 47 48where ids is the list of IDs of device nodes the given handler is supposed to 49take care of, list_node is the hook to the global list of ACPI scan handlers 50maintained by the ACPI core and the .attach() and .detach() callbacks are 51executed, respectively, after registration of new device nodes and before 52unregistration of device nodes the handler attached to previously. 53 54The namespace scanning function, acpi_bus_scan(), first registers all of the 55device nodes in the given namespace scope with the driver core. Then, it tries 56to match a scan handler against each of them using the ids arrays of the 57available scan handlers. If a matching scan handler is found, its .attach() 58callback is executed for the given device node. If that callback returns 1, 59that means that the handler has claimed the device node and is now responsible 60for carrying out any additional configuration tasks related to it. It also will 61be responsible for preparing the device node for unregistration in that case. 62The device node's handler field is then populated with the address of the scan 63handler that has claimed it. 64 65If the .attach() callback returns 0, it means that the device node is not 66interesting to the given scan handler and may be matched against the next scan 67handler in the list. If it returns a (negative) error code, that means that 68the namespace scan should be terminated due to a serious error. The error code 69returned should then reflect the type of the error. 70 71The namespace trimming function, acpi_bus_trim(), first executes .detach() 72callbacks from the scan handlers of all device nodes in the given namespace 73scope (if they have scan handlers). Next, it unregisters all of the device 74nodes in that scope. 75 76ACPI scan handlers can be added to the list maintained by the ACPI core with the 77help of the acpi_scan_add_handler() function taking a pointer to the new scan 78handler as an argument. The order in which scan handlers are added to the list 79is the order in which they are matched against device nodes during namespace 80scans. 81 82All scan handles must be added to the list before acpi_bus_scan() is run for the 83first time and they cannot be removed from it. 84