lastdragon/linux-kernel
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Resguardo inicial

Browse Source
This commit is contained in:
lastdragon
2026-09-06 12:53:21 -06:00
parent 662efe3c2a
commit ad2088d178
94853 changed files with 43200404 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
linux-7.2.3/Documentation/driver-api/acpi/acpi-drivers.rst
+80
View File
@@ -0,0 +1,80 @@
.. SPDX-License-Identifier: GPL-2.0
.. include:: <isonum.txt>
=========================================
Why using ACPI drivers is not a good idea
=========================================
:Copyright: |copy| 2026, Intel Corporation
:Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
Even though binding drivers directly to struct acpi_device objects, also
referred to as "ACPI device nodes", allows basic functionality to be provided
at least in some cases, there are problems with it, related to general
consistency, sysfs layout, power management operation ordering, and code
cleanliness.
First of all, ACPI device nodes represent firmware entities rather than
hardware and in many cases they provide auxiliary information on devices
enumerated independently (like PCI devices or CPUs). It is therefore generally
questionable to assign resources to them because the entities represented by
them do not decode addresses in the memory or I/O address spaces and do not
generate interrupts or similar (all of that is done by hardware).
Second, as a general rule, a struct acpi_device can only be a parent of another
struct acpi_device. If that is not the case, the location of the child device
in the device hierarchy is at least confusing and it may not be straightforward
to identify the piece of hardware providing functionality represented by it.
However, binding a driver directly to an ACPI device node may cause that to
happen if the given driver registers input devices or wakeup sources under it,
for example.
Next, using system suspend and resume callbacks directly on ACPI device nodes
is also questionable because it may cause ordering problems to appear. Namely,
ACPI device nodes are registered before enumerating hardware corresponding to
them and they land on the PM list in front of the majority of other device
objects. Consequently, the execution ordering of their PM callbacks may be
different from what is generally expected. Also, in general, dependencies
returned by _DEP objects do not affect ACPI device nodes themselves, but the
"physical" devices associated with them, which potentially is one more source
of inconsistency related to treating ACPI device nodes as "real" device
representation.
All of the above means that binding drivers to ACPI device nodes should
generally be avoided and so struct acpi_driver objects should not be used.
Moreover, a device ID is necessary to bind a driver directly to an ACPI device
node, but device IDs are not generally associated with all of them. Some of
them contain alternative information allowing the corresponding pieces of
hardware to be identified, for example represented by an _ADR object return
value, and device IDs are not used in those cases. In consequence, confusingly
enough, binding an ACPI driver to an ACPI device node may even be impossible.
When that happens, the piece of hardware corresponding to the given ACPI device
node is represented by another device object, like a struct pci_dev, and the
ACPI device node is the "ACPI companion" of that device, accessible through its
fwnode pointer used by the ACPI_COMPANION() macro. The ACPI companion holds
additional information on the device configuration and possibly some "recipes"
on device manipulation in the form of AML (ACPI Machine Language) bytecode
provided by the platform firmware. Thus the role of the ACPI device node is
similar to the role of a struct device_node on a system where Device Tree is
used for platform description.
For consistency, this approach has been extended to the cases in which ACPI
device IDs are used. Namely, in those cases, an additional device object is
created to represent the piece of hardware corresponding to a given ACPI device
node. By default, it is a platform device, but it may also be a PNP device, a
CPU device, or another type of device, depending on what the given piece of
hardware actually is. There are even cases in which multiple devices are
"backed" or "accompanied" by one ACPI device node (e.g. ACPI device nodes
corresponding to GPUs that may provide firmware interfaces for backlight
brightness control in addition to GPU configuration information).
This means that it really should never be necessary to bind a driver directly to
an ACPI device node because there is a "proper" device object representing the
corresponding piece of hardware that can be bound to by a "proper" driver using
the given ACPI device node as the device's ACPI companion. Thus, in principle,
there is no reason to use ACPI drivers and if they all were replaced with other
driver types (for example, platform drivers), some code could be dropped and
some complexity would go away.
linux-7.2.3/Documentation/driver-api/acpi/index.rst
+10
View File
@@ -0,0 +1,10 @@
============
ACPI Support
============
.. toctree::
:maxdepth: 2
linuxized-acpica
scan_handlers
acpi-drivers
linux-7.2.3/Documentation/driver-api/acpi/linuxized-acpica.rst
+279
View File
@@ -0,0 +1,279 @@
.. SPDX-License-Identifier: GPL-2.0
.. include:: <isonum.txt>
============================================================
Linuxized ACPICA - Introduction to ACPICA Release Automation
============================================================
:Copyright: |copy| 2013-2016, Intel Corporation
:Author: Lv Zheng <lv.zheng@intel.com>
Abstract
========
This document describes the ACPICA project and the relationship between
ACPICA and Linux. It also describes how ACPICA code in drivers/acpi/acpica,
include/acpi and tools/power/acpi is automatically updated to follow the
upstream.
ACPICA Project
==============
The ACPI Component Architecture (ACPICA) project provides an operating
system (OS)-independent reference implementation of the Advanced
Configuration and Power Interface Specification (ACPI). It has been
adapted by various host OSes. By directly integrating ACPICA, Linux can
also benefit from the application experiences of ACPICA from other host
OSes.
The homepage of ACPICA project is: www.acpica.org, it is maintained and
supported by Intel Corporation.
The following figure depicts the Linux ACPI subsystem where the ACPICA
adaptation is included::
+---------------------------------------------------------+
| |
| +---------------------------------------------------+ |
| | +------------------+ | |
| | | Table Management | | |
| | +------------------+ | |
| | +----------------------+ | |
| | | Namespace Management | | |
| | +----------------------+ | |
| | +------------------+ ACPICA Components | |
| | | Event Management | | |
| | +------------------+ | |
| | +---------------------+ | |
| | | Resource Management | | |
| | +---------------------+ | |
| | +---------------------+ | |
| | | Hardware Management | | |
| | +---------------------+ | |
| +---------------------------------------------------+ | |
| | | +------------------+ | | |
| | | | OS Service Layer | | | |
| | | +------------------+ | | |
| | +-------------------------------------------------|-+ |
| | +--------------------+ | |
| | | Device Enumeration | | |
| | +--------------------+ | |
| | +------------------+ | |
| | | Power Management | | |
| | +------------------+ Linux/ACPI Components | |
| | +--------------------+ | |
| | | Thermal Management | | |
| | +--------------------+ | |
| | +--------------------------+ | |
| | | Drivers for ACPI Devices | | |
| | +--------------------------+ | |
| | +--------+ | |
| | | ...... | | |
| | +--------+ | |
| +---------------------------------------------------+ |
| |
+---------------------------------------------------------+
Figure 1. Linux ACPI Software Components
.. note::
A. OS Service Layer - Provided by Linux to offer OS dependent
implementation of the predefined ACPICA interfaces (acpi_os_*).
::
include/acpi/acpiosxf.h
drivers/acpi/osl.c
include/acpi/platform
include/asm/acenv.h
B. ACPICA Functionality - Released from ACPICA code base to offer
OS independent implementation of the ACPICA interfaces (acpi_*).
::
drivers/acpi/acpica
include/acpi/ac*.h
tools/power/acpi
C. Linux/ACPI Functionality - Providing Linux specific ACPI
functionality to the other Linux kernel subsystems and user space
programs.
::
drivers/acpi
include/linux/acpi.h
include/linux/acpi*.h
include/acpi
tools/power/acpi
D. Architecture Specific ACPICA/ACPI Functionalities - Provided by the
ACPI subsystem to offer architecture specific implementation of the
ACPI interfaces. They are Linux specific components and are out of
the scope of this document.
::
include/asm/acpi.h
include/asm/acpi*.h
arch/*/acpi
ACPICA Release
==============
The ACPICA project maintains its code base at the following repository URL:
https://github.com/acpica/acpica.git. As a rule, a release is made every
month.
As the coding style adopted by the ACPICA project is not acceptable by
Linux, there is a release process to convert the ACPICA git commits into
Linux patches. The patches generated by this process are referred to as
"linuxized ACPICA patches". The release process is carried out on a local
copy the ACPICA git repository. Each commit in the monthly release is
converted into a linuxized ACPICA patch. Together, they form the monthly
ACPICA release patchset for the Linux ACPI community. This process is
illustrated in the following figure::
+-----------------------------+
| acpica / master (-) commits |
+-----------------------------+
/|\ |
| \|/
| /---------------------\ +----------------------+
| < Linuxize repo Utility >-->| old linuxized acpica |--+
| \---------------------/ +----------------------+ |
| |
/---------\ |
< git reset > \
\---------/ \
/|\ /+-+
| / |
+-----------------------------+ | |
| acpica / master (+) commits | | |
+-----------------------------+ | |
| | |
\|/ | |
/-----------------------\ +----------------------+ | |
< Linuxize repo Utilities >-->| new linuxized acpica |--+ |
\-----------------------/ +----------------------+ |
\|/
+--------------------------+ /----------------------\
| Linuxized ACPICA Patches |<----------------< Linuxize patch Utility >
+--------------------------+ \----------------------/
|
\|/
/---------------------------\
< Linux ACPI Community Review >
\---------------------------/
|
\|/
+-----------------------+ /------------------\ +----------------+
| linux-pm / linux-next |-->< Linux Merge Window >-->| linux / master |
+-----------------------+ \------------------/ +----------------+
Figure 2. ACPICA -> Linux Upstream Process
.. note::
A. Linuxize Utilities - Provided by the ACPICA repository, including a
utility located in source/tools/acpisrc folder and a number of
scripts located in generate/linux folder.
B. acpica / master - "master" branch of the git repository at
<https://github.com/acpica/acpica.git>.
C. linux-pm / linux-next - "linux-next" branch of the git repository at
<https://git.kernel.org/pub/scm/linux/kernel/git/rafael/linux-pm.git>.
D. linux / master - "master" branch of the git repository at
<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git>.
Before the linuxized ACPICA patches are sent to the Linux ACPI community
for review, there is a quality assurance build test process to reduce
porting issues. Currently this build process only takes care of the
following kernel configuration options:
CONFIG_ACPI/CONFIG_ACPI_DEBUG/CONFIG_ACPI_DEBUGGER
ACPICA Divergences
==================
Ideally, all of the ACPICA commits should be converted into Linux patches
automatically without manual modifications, the "linux / master" tree should
contain the ACPICA code that exactly corresponds to the ACPICA code
contained in "new linuxized acpica" tree and it should be possible to run
the release process fully automatically.
As a matter of fact, however, there are source code differences between
the ACPICA code in Linux and the upstream ACPICA code, referred to as
"ACPICA Divergences".
The various sources of ACPICA divergences include:
1. Legacy divergences - Before the current ACPICA release process was
established, there already had been divergences between Linux and
ACPICA. Over the past several years those divergences have been greatly
reduced, but there still are several ones and it takes time to figure
out the underlying reasons for their existence.
2. Manual modifications - Any manual modification (eg. coding style fixes)
made directly in the Linux sources obviously hurts the ACPICA release
automation. Thus it is recommended to fix such issues in the ACPICA
upstream source code and generate the linuxized fix using the ACPICA
release utilities (please refer to Section 4 below for the details).
3. Linux specific features - Sometimes it's impossible to use the
current ACPICA APIs to implement features required by the Linux kernel,
so Linux developers occasionally have to change ACPICA code directly.
Those changes may not be acceptable by ACPICA upstream and in such cases
they are left as committed ACPICA divergences unless the ACPICA side can
implement new mechanisms as replacements for them.
4. ACPICA release fixups - ACPICA only tests commits using a set of the
user space simulation utilities, thus the linuxized ACPICA patches may
break the Linux kernel, leaving us build/boot failures. In order to
avoid breaking Linux bisection, fixes are applied directly to the
linuxized ACPICA patches during the release process. When the release
fixups are backported to the upstream ACPICA sources, they must follow
the upstream ACPICA rules and so further modifications may appear.
That may result in the appearance of new divergences.
5. Fast tracking of ACPICA commits - Some ACPICA commits are regression
fixes or stable-candidate material, so they are applied in advance with
respect to the ACPICA release process. If such commits are reverted or
rebased on the ACPICA side in order to offer better solutions, new ACPICA
divergences are generated.
ACPICA Development
==================
This paragraph guides Linux developers to use the ACPICA upstream release
utilities to obtain Linux patches corresponding to upstream ACPICA commits
before they become available from the ACPICA release process.
1. Cherry-pick an ACPICA commit
First you need to git clone the ACPICA repository and the ACPICA change
you want to cherry pick must be committed into the local repository.
Then the gen-patch.sh command can help to cherry-pick an ACPICA commit
from the ACPICA local repository::
$ git clone https://github.com/acpica/acpica
$ cd acpica
$ generate/linux/gen-patch.sh -u [commit ID]
Here the commit ID is the ACPICA local repository commit ID you want to
cherry pick. It can be omitted if the commit is "HEAD".
2. Cherry-pick recent ACPICA commits
Sometimes you need to rebase your code on top of the most recent ACPICA
changes that haven't been applied to Linux yet.
You can generate the ACPICA release series yourself and rebase your code on
top of the generated ACPICA release patches::
$ git clone https://github.com/acpica/acpica
$ cd acpica
$ generate/linux/make-patches.sh -u [commit ID]
The commit ID should be the last ACPICA commit accepted by Linux. Usually,
it is the commit modifying ACPI_CA_VERSION. It can be found by executing
"git blame source/include/acpixf.h" and referencing the line that contains
"ACPI_CA_VERSION".
3. Inspect the current divergences
If you have local copies of both Linux and upstream ACPICA, you can generate
a diff file indicating the state of the current divergences::
# git clone https://github.com/acpica/acpica
# git clone https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
# cd acpica
# generate/linux/divergence.sh -s ../linux
linux-7.2.3/Documentation/driver-api/acpi/scan_handlers.rst
+83
View File
@@ -0,0 +1,83 @@
.. SPDX-License-Identifier: GPL-2.0
.. include:: <isonum.txt>
==================
ACPI Scan Handlers
==================
:Copyright: |copy| 2012, Intel Corporation
:Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
During system initialization and ACPI-based device hot-add, the ACPI namespace
is scanned in search of device objects that generally represent various pieces
of hardware. This causes a struct acpi_device object to be created and
registered with the driver core for every device object in the ACPI namespace
and the hierarchy of those struct acpi_device objects reflects the namespace
layout (i.e. parent device objects in the namespace are represented by parent
struct acpi_device objects and analogously for their children). Those struct
acpi_device objects are referred to as "device nodes" in what follows, but they
should not be confused with struct device_node objects used by the Device Trees
parsing code (although their role is analogous to the role of those objects).
During ACPI-based device hot-remove device nodes representing pieces of hardware
being removed are unregistered and deleted.
The core ACPI namespace scanning code in drivers/acpi/scan.c carries out basic
initialization of device nodes, such as retrieving common configuration
information from the device objects represented by them and populating them with
appropriate data, but some of them require additional handling after they have
been registered. For example, if the given device node represents a PCI host
bridge, its registration should cause the PCI bus under that bridge to be
enumerated and PCI devices on that bus to be registered with the driver core.
Similarly, if the device node represents a PCI interrupt link, it is necessary
to configure that link so that the kernel can use it.
Those additional configuration tasks usually depend on the type of the hardware
component represented by the given device node which can be determined on the
basis of the device node's hardware ID (HID). They are performed by objects
called ACPI scan handlers represented by the following structure::
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.