Documentation/driver-api/acpi/scan_handlers.rst

Source file repositories/reference/linux-study-clean/Documentation/driver-api/acpi/scan_handlers.rst

File Facts

System
Linux kernel
Corpus path
Documentation/driver-api/acpi/scan_handlers.rst
Extension
.rst
Size
4489 bytes
Lines
84
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

struct acpi_scan_handler {
		const struct acpi_device_id *ids;
		struct list_head list_node;
		int (*attach)(struct acpi_device *dev, const struct acpi_device_id *id);
		void (*detach)(struct acpi_device *dev);
	};

where ids is the list of IDs of device nodes the given handler is supposed to
take care of, list_node is the hook to the global list of ACPI scan handlers
maintained by the ACPI core and the .attach() and .detach() callbacks are
executed, respectively, after registration of new device nodes and before
unregistration of device nodes the handler attached to previously.

The namespace scanning function, acpi_bus_scan(), first registers all of the
device nodes in the given namespace scope with the driver core.  Then, it tries
to match a scan handler against each of them using the ids arrays of the
available scan handlers.  If a matching scan handler is found, its .attach()
callback is executed for the given device node.  If that callback returns 1,
that means that the handler has claimed the device node and is now responsible
for carrying out any additional configuration tasks related to it.  It also will
be responsible for preparing the device node for unregistration in that case.
The device node's handler field is then populated with the address of the scan
handler that has claimed it.

If the .attach() callback returns 0, it means that the device node is not
interesting to the given scan handler and may be matched against the next scan
handler in the list.  If it returns a (negative) error code, that means that
the namespace scan should be terminated due to a serious error.  The error code
returned should then reflect the type of the error.

The namespace trimming function, acpi_bus_trim(), first executes .detach()
callbacks from the scan handlers of all device nodes in the given namespace
scope (if they have scan handlers).  Next, it unregisters all of the device
nodes in that scope.

ACPI scan handlers can be added to the list maintained by the ACPI core with the
help of the acpi_scan_add_handler() function taking a pointer to the new scan
handler as an argument.  The order in which scan handlers are added to the list
is the order in which they are matched against device nodes during namespace
scans.

All scan handles must be added to the list before acpi_bus_scan() is run for the
first time and they cannot be removed from it.

Annotation

Implementation Notes