Orange Pi5 kernel

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