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