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