* [PATCH v2 01/24] Documentation: add Linux ACPI to Sphinx TOC tree
2019-03-29 0:11 [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree Changbin Du
@ 2019-03-29 0:11 ` Changbin Du
2019-03-30 9:51 ` Rafael J. Wysocki
2019-03-29 0:11 ` [PATCH v2 02/24] acpi doc: convert acpi/namespace.txt to rst format Changbin Du
` (23 subsequent siblings)
24 siblings, 1 reply; 39+ messages in thread
From: Changbin Du @ 2019-03-29 0:11 UTC (permalink / raw)
To: Jonathan Corbet
Cc: rjw, lenb, linux-acpi, linux-kernel, linux-doc, Changbin Du
Add a index.rst for trace subsystem. More docs will be added later.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
Documentation/acpi/index.rst | 8 ++++++++
Documentation/index.rst | 1 +
2 files changed, 9 insertions(+)
create mode 100644 Documentation/acpi/index.rst
diff --git a/Documentation/acpi/index.rst b/Documentation/acpi/index.rst
new file mode 100644
index 000000000000..7241ceb1673c
--- /dev/null
+++ b/Documentation/acpi/index.rst
@@ -0,0 +1,8 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=======================================================
+Linux ACPI (Advanced Configuration and Power Interface)
+=======================================================
+
+.. toctree::
+ :maxdepth: 2
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 80a421cb935e..e3aa28275894 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -90,6 +90,7 @@ needed).
filesystems/index
vm/index
bpf/index
+ acpi/index
misc-devices/index
Architecture-specific documentation
--
2.20.1
^ permalink raw reply related [flat|nested] 39+ messages in thread* Re: [PATCH v2 01/24] Documentation: add Linux ACPI to Sphinx TOC tree
2019-03-29 0:11 ` [PATCH v2 01/24] Documentation: add Linux ACPI to " Changbin Du
@ 2019-03-30 9:51 ` Rafael J. Wysocki
2019-03-31 5:13 ` Changbin Du
0 siblings, 1 reply; 39+ messages in thread
From: Rafael J. Wysocki @ 2019-03-30 9:51 UTC (permalink / raw)
To: Changbin Du
Cc: Jonathan Corbet, Rafael J. Wysocki, Len Brown,
ACPI Devel Maling List, Linux Kernel Mailing List,
open list:DOCUMENTATION
On Fri, Mar 29, 2019 at 1:12 AM Changbin Du <changbin.du@gmail.com> wrote:
>
> Add a index.rst for trace subsystem. More docs will be added later.
>
> Signed-off-by: Changbin Du <changbin.du@gmail.com>
> ---
> Documentation/acpi/index.rst | 8 ++++++++
> Documentation/index.rst | 1 +
> 2 files changed, 9 insertions(+)
> create mode 100644 Documentation/acpi/index.rst
>
> diff --git a/Documentation/acpi/index.rst b/Documentation/acpi/index.rst
> new file mode 100644
> index 000000000000..7241ceb1673c
> --- /dev/null
> +++ b/Documentation/acpi/index.rst
> @@ -0,0 +1,8 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +=======================================================
> +Linux ACPI (Advanced Configuration and Power Interface)
"Linux ACPI Support", please.
> +=======================================================
> +
> +.. toctree::
> + :maxdepth: 2
> diff --git a/Documentation/index.rst b/Documentation/index.rst
> index 80a421cb935e..e3aa28275894 100644
> --- a/Documentation/index.rst
> +++ b/Documentation/index.rst
> @@ -90,6 +90,7 @@ needed).
> filesystems/index
> vm/index
> bpf/index
> + acpi/index
> misc-devices/index
>
> Architecture-specific documentation
> --
> 2.20.1
>
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH v2 01/24] Documentation: add Linux ACPI to Sphinx TOC tree
2019-03-30 9:51 ` Rafael J. Wysocki
@ 2019-03-31 5:13 ` Changbin Du
0 siblings, 0 replies; 39+ messages in thread
From: Changbin Du @ 2019-03-31 5:13 UTC (permalink / raw)
To: Rafael J. Wysocki
Cc: Changbin Du, Jonathan Corbet, Rafael J. Wysocki, Len Brown,
ACPI Devel Maling List, Linux Kernel Mailing List,
open list:DOCUMENTATION
On Sat, Mar 30, 2019 at 10:51:50AM +0100, Rafael J. Wysocki wrote:
> On Fri, Mar 29, 2019 at 1:12 AM Changbin Du <changbin.du@gmail.com> wrote:
> >
> > Add a index.rst for trace subsystem. More docs will be added later.
> >
> > Signed-off-by: Changbin Du <changbin.du@gmail.com>
> > ---
> > Documentation/acpi/index.rst | 8 ++++++++
> > Documentation/index.rst | 1 +
> > 2 files changed, 9 insertions(+)
> > create mode 100644 Documentation/acpi/index.rst
> >
> > diff --git a/Documentation/acpi/index.rst b/Documentation/acpi/index.rst
> > new file mode 100644
> > index 000000000000..7241ceb1673c
> > --- /dev/null
> > +++ b/Documentation/acpi/index.rst
> > @@ -0,0 +1,8 @@
> > +.. SPDX-License-Identifier: GPL-2.0
> > +
> > +=======================================================
> > +Linux ACPI (Advanced Configuration and Power Interface)
>
> "Linux ACPI Support", please.
>
sure.
> > +=======================================================
> > +
> > +.. toctree::
> > + :maxdepth: 2
> > diff --git a/Documentation/index.rst b/Documentation/index.rst
> > index 80a421cb935e..e3aa28275894 100644
> > --- a/Documentation/index.rst
> > +++ b/Documentation/index.rst
> > @@ -90,6 +90,7 @@ needed).
> > filesystems/index
> > vm/index
> > bpf/index
> > + acpi/index
> > misc-devices/index
> >
> > Architecture-specific documentation
> > --
> > 2.20.1
> >
--
Cheers,
Changbin Du
^ permalink raw reply [flat|nested] 39+ messages in thread
* [PATCH v2 02/24] acpi doc: convert acpi/namespace.txt to rst format
2019-03-29 0:11 [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree Changbin Du
2019-03-29 0:11 ` [PATCH v2 01/24] Documentation: add Linux ACPI to " Changbin Du
@ 2019-03-29 0:11 ` Changbin Du
2019-03-29 0:11 ` [PATCH v2 03/24] acpi doc: convert acpi/enumeration.txt " Changbin Du
` (22 subsequent siblings)
24 siblings, 0 replies; 39+ messages in thread
From: Changbin Du @ 2019-03-29 0:11 UTC (permalink / raw)
To: Jonathan Corbet
Cc: rjw, lenb, linux-acpi, linux-kernel, linux-doc, Changbin Du
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
Documentation/acpi/index.rst | 4 +-
.../acpi/{namespace.txt => namespace.rst} | 310 +++++++++---------
2 files changed, 163 insertions(+), 151 deletions(-)
rename Documentation/acpi/{namespace.txt => namespace.rst} (54%)
diff --git a/Documentation/acpi/index.rst b/Documentation/acpi/index.rst
index 7241ceb1673c..2f48ffc6061a 100644
--- a/Documentation/acpi/index.rst
+++ b/Documentation/acpi/index.rst
@@ -1,8 +1,10 @@
.. SPDX-License-Identifier: GPL-2.0
=======================================================
-Linux ACPI (Advanced Configuration and Power Interface)
+Linux ACPI (Advanced Configuration and Power Interface)
=======================================================
.. toctree::
:maxdepth: 2
+
+ namespace
diff --git a/Documentation/acpi/namespace.txt b/Documentation/acpi/namespace.rst
similarity index 54%
rename from Documentation/acpi/namespace.txt
rename to Documentation/acpi/namespace.rst
index 1860cb3865c6..443f0e5d0617 100644
--- a/Documentation/acpi/namespace.txt
+++ b/Documentation/acpi/namespace.rst
@@ -1,85 +1,88 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
+
+===================================================
ACPI Device Tree - Representation of ACPI Namespace
+===================================================
+
+:Copyright: |copy| 2013, Intel Corporation
+
+:Author: Lv Zheng <lv.zheng@intel.com>
+
+:Abstract: The Linux ACPI subsystem converts ACPI namespace objects into a Linux
+ device tree under the /sys/devices/LNXSYSTEM:00 and updates it upon
+ receiving ACPI hotplug notification events. For each device object
+ in this hierarchy there is a corresponding symbolic link in the
+ /sys/bus/acpi/devices.
+ This document illustrates the structure of the ACPI device tree.
+
+:Credit: Thanks for the help from Zhang Rui <rui.zhang@intel.com> and
+ Rafael J.Wysocki <rafael.j.wysocki@intel.com>.
+
+
+ACPI Definition Blocks
+======================
+
+The ACPI firmware sets up RSDP (Root System Description Pointer) in the
+system memory address space pointing to the XSDT (Extended System
+Description Table). The XSDT always points to the FADT (Fixed ACPI
+Description Table) using its first entry, the data within the FADT
+includes various fixed-length entries that describe fixed ACPI features
+of the hardware. The FADT contains a pointer to the DSDT
+(Differentiated System Descripition Table). The XSDT also contains
+entries pointing to possibly multiple SSDTs (Secondary System
+Description Table).
+
+The DSDT and SSDT data is organized in data structures called definition
+blocks that contain definitions of various objects, including ACPI
+control methods, encoded in AML (ACPI Machine Language). The data block
+of the DSDT along with the contents of SSDTs represents a hierarchical
+data structure called the ACPI namespace whose topology reflects the
+structure of the underlying hardware platform.
+
+The relationships between ACPI System Definition Tables described above
+are illustrated in the following diagram::
+
+ +---------+ +-------+ +--------+ +------------------------+
+ | RSDP | +->| XSDT | +->| FADT | | +-------------------+ |
+ +---------+ | +-------+ | +--------+ +-|->| DSDT | |
+ | Pointer | | | Entry |-+ | ...... | | | +-------------------+ |
+ +---------+ | +-------+ | X_DSDT |--+ | | Definition Blocks | |
+ | Pointer |-+ | ..... | | ...... | | +-------------------+ |
+ +---------+ +-------+ +--------+ | +-------------------+ |
+ | Entry |------------------|->| SSDT | |
+ +- - - -+ | +-------------------| |
+ | Entry | - - - - - - - -+ | | Definition Blocks | |
+ +- - - -+ | | +-------------------+ |
+ | | +- - - - - - - - - -+ |
+ +-|->| SSDT | |
+ | +-------------------+ |
+ | | Definition Blocks | |
+ | +- - - - - - - - - -+ |
+ +------------------------+
+ |
+ OSPM Loading |
+ \|/
+ +----------------+
+ | ACPI Namespace |
+ +----------------+
+
+ Figure 1. ACPI Definition Blocks
+
+.. note:: RSDP can also contain a pointer to the RSDT (Root System
+ Description Table). Platforms provide RSDT to enable
+ compatibility with ACPI 1.0 operating systems. The OS is expected
+ to use XSDT, if present.
+
+
+Example ACPI Namespace
+======================
+
+All definition blocks are loaded into a single namespace. The namespace
+is a hierarchy of objects identified by names and paths.
+The following naming conventions apply to object names in the ACPI
+namespace:
-Copyright (C) 2013, Intel Corporation
-Author: Lv Zheng <lv.zheng@intel.com>
-
-
-Abstract:
-
-The Linux ACPI subsystem converts ACPI namespace objects into a Linux
-device tree under the /sys/devices/LNXSYSTEM:00 and updates it upon
-receiving ACPI hotplug notification events. For each device object in this
-hierarchy there is a corresponding symbolic link in the
-/sys/bus/acpi/devices.
-This document illustrates the structure of the ACPI device tree.
-
-
-Credit:
-
-Thanks for the help from Zhang Rui <rui.zhang@intel.com> and Rafael J.
-Wysocki <rafael.j.wysocki@intel.com>.
-
-
-1. ACPI Definition Blocks
-
- The ACPI firmware sets up RSDP (Root System Description Pointer) in the
- system memory address space pointing to the XSDT (Extended System
- Description Table). The XSDT always points to the FADT (Fixed ACPI
- Description Table) using its first entry, the data within the FADT
- includes various fixed-length entries that describe fixed ACPI features
- of the hardware. The FADT contains a pointer to the DSDT
- (Differentiated System Descripition Table). The XSDT also contains
- entries pointing to possibly multiple SSDTs (Secondary System
- Description Table).
-
- The DSDT and SSDT data is organized in data structures called definition
- blocks that contain definitions of various objects, including ACPI
- control methods, encoded in AML (ACPI Machine Language). The data block
- of the DSDT along with the contents of SSDTs represents a hierarchical
- data structure called the ACPI namespace whose topology reflects the
- structure of the underlying hardware platform.
-
- The relationships between ACPI System Definition Tables described above
- are illustrated in the following diagram.
-
- +---------+ +-------+ +--------+ +------------------------+
- | RSDP | +->| XSDT | +->| FADT | | +-------------------+ |
- +---------+ | +-------+ | +--------+ +-|->| DSDT | |
- | Pointer | | | Entry |-+ | ...... | | | +-------------------+ |
- +---------+ | +-------+ | X_DSDT |--+ | | Definition Blocks | |
- | Pointer |-+ | ..... | | ...... | | +-------------------+ |
- +---------+ +-------+ +--------+ | +-------------------+ |
- | Entry |------------------|->| SSDT | |
- +- - - -+ | +-------------------| |
- | Entry | - - - - - - - -+ | | Definition Blocks | |
- +- - - -+ | | +-------------------+ |
- | | +- - - - - - - - - -+ |
- +-|->| SSDT | |
- | +-------------------+ |
- | | Definition Blocks | |
- | +- - - - - - - - - -+ |
- +------------------------+
- |
- OSPM Loading |
- \|/
- +----------------+
- | ACPI Namespace |
- +----------------+
-
- Figure 1. ACPI Definition Blocks
-
- NOTE: RSDP can also contain a pointer to the RSDT (Root System
- Description Table). Platforms provide RSDT to enable
- compatibility with ACPI 1.0 operating systems. The OS is expected
- to use XSDT, if present.
-
-
-2. Example ACPI Namespace
-
- All definition blocks are loaded into a single namespace. The namespace
- is a hierarchy of objects identified by names and paths.
- The following naming conventions apply to object names in the ACPI
- namespace:
1. All names are 32 bits long.
2. The first byte of a name must be one of 'A' - 'Z', '_'.
3. Each of the remaining bytes of a name must be one of 'A' - 'Z', '0'
@@ -91,7 +94,7 @@ Wysocki <rafael.j.wysocki@intel.com>.
(i.e. names prepended with '^' are relative to the parent of the
current namespace node).
- The figure below shows an example ACPI namespace.
+The figure below shows an example ACPI namespace::
+------+
| \ | Root
@@ -184,19 +187,20 @@ Wysocki <rafael.j.wysocki@intel.com>.
Figure 2. Example ACPI Namespace
-3. Linux ACPI Device Objects
+Linux ACPI Device Objects
+=========================
- The Linux kernel's core ACPI subsystem creates struct acpi_device
- objects for ACPI namespace objects representing devices, power resources
- processors, thermal zones. Those objects are exported to user space via
- sysfs as directories in the subtree under /sys/devices/LNXSYSTM:00. The
- format of their names is <bus_id:instance>, where 'bus_id' refers to the
- ACPI namespace representation of the given object and 'instance' is used
- for distinguishing different object of the same 'bus_id' (it is
- two-digit decimal representation of an unsigned integer).
+The Linux kernel's core ACPI subsystem creates struct acpi_device
+objects for ACPI namespace objects representing devices, power resources
+processors, thermal zones. Those objects are exported to user space via
+sysfs as directories in the subtree under /sys/devices/LNXSYSTM:00. The
+format of their names is <bus_id:instance>, where 'bus_id' refers to the
+ACPI namespace representation of the given object and 'instance' is used
+for distinguishing different object of the same 'bus_id' (it is
+two-digit decimal representation of an unsigned integer).
- The value of 'bus_id' depends on the type of the object whose name it is
- part of as listed in the table below.
+The value of 'bus_id' depends on the type of the object whose name it is
+part of as listed in the table below::
+---+-----------------+-------+----------+
| | Object/Feature | Table | bus_id |
@@ -226,10 +230,11 @@ Wysocki <rafael.j.wysocki@intel.com>.
Table 1. ACPI Namespace Objects Mapping
- The following rules apply when creating struct acpi_device objects on
- the basis of the contents of ACPI System Description Tables (as
- indicated by the letter in the first column and the notation in the
- second column of the table above):
+The following rules apply when creating struct acpi_device objects on
+the basis of the contents of ACPI System Description Tables (as
+indicated by the letter in the first column and the notation in the
+second column of the table above):
+
N:
The object's source is an ACPI namespace node (as indicated by the
named object's type in the second column). In that case the object's
@@ -249,13 +254,14 @@ Wysocki <rafael.j.wysocki@intel.com>.
struct acpi_device object with LNXVIDEO 'bus_id' will be created for
it.
- The third column of the above table indicates which ACPI System
- Description Tables contain information used for the creation of the
- struct acpi_device objects represented by the given row (xSDT means DSDT
- or SSDT).
+The third column of the above table indicates which ACPI System
+Description Tables contain information used for the creation of the
+struct acpi_device objects represented by the given row (xSDT means DSDT
+or SSDT).
+
+The forth column of the above table indicates the 'bus_id' generation
+rule of the struct acpi_device object:
- The forth column of the above table indicates the 'bus_id' generation
- rule of the struct acpi_device object:
_HID:
_HID in the last column of the table means that the object's bus_id
is derived from the _HID/_CID identification objects present under
@@ -275,45 +281,47 @@ Wysocki <rafael.j.wysocki@intel.com>.
object's bus_id.
-4. Linux ACPI Physical Device Glue
-
- ACPI device (i.e. struct acpi_device) objects may be linked to other
- objects in the Linux' device hierarchy that represent "physical" devices
- (for example, devices on the PCI bus). If that happens, it means that
- the ACPI device object is a "companion" of a device otherwise
- represented in a different way and is used (1) to provide configuration
- information on that device which cannot be obtained by other means and
- (2) to do specific things to the device with the help of its ACPI
- control methods. One ACPI device object may be linked this way to
- multiple "physical" devices.
-
- If an ACPI device object is linked to a "physical" device, its sysfs
- directory contains the "physical_node" symbolic link to the sysfs
- directory of the target device object. In turn, the target device's
- sysfs directory will then contain the "firmware_node" symbolic link to
- the sysfs directory of the companion ACPI device object.
- The linking mechanism relies on device identification provided by the
- ACPI namespace. For example, if there's an ACPI namespace object
- representing a PCI device (i.e. a device object under an ACPI namespace
- object representing a PCI bridge) whose _ADR returns 0x00020000 and the
- bus number of the parent PCI bridge is 0, the sysfs directory
- representing the struct acpi_device object created for that ACPI
- namespace object will contain the 'physical_node' symbolic link to the
- /sys/devices/pci0000:00/0000:00:02:0/ sysfs directory of the
- corresponding PCI device.
-
- The linking mechanism is generally bus-specific. The core of its
- implementation is located in the drivers/acpi/glue.c file, but there are
- complementary parts depending on the bus types in question located
- elsewhere. For example, the PCI-specific part of it is located in
- drivers/pci/pci-acpi.c.
-
-
-5. Example Linux ACPI Device Tree
-
- The sysfs hierarchy of struct acpi_device objects corresponding to the
- example ACPI namespace illustrated in Figure 2 with the addition of
- fixed PWR_BUTTON/SLP_BUTTON devices is shown below.
+Linux ACPI Physical Device Glue
+===============================
+
+ACPI device (i.e. struct acpi_device) objects may be linked to other
+objects in the Linux' device hierarchy that represent "physical" devices
+(for example, devices on the PCI bus). If that happens, it means that
+the ACPI device object is a "companion" of a device otherwise
+represented in a different way and is used (1) to provide configuration
+information on that device which cannot be obtained by other means and
+(2) to do specific things to the device with the help of its ACPI
+control methods. One ACPI device object may be linked this way to
+multiple "physical" devices.
+
+If an ACPI device object is linked to a "physical" device, its sysfs
+directory contains the "physical_node" symbolic link to the sysfs
+directory of the target device object. In turn, the target device's
+sysfs directory will then contain the "firmware_node" symbolic link to
+the sysfs directory of the companion ACPI device object.
+The linking mechanism relies on device identification provided by the
+ACPI namespace. For example, if there's an ACPI namespace object
+representing a PCI device (i.e. a device object under an ACPI namespace
+object representing a PCI bridge) whose _ADR returns 0x00020000 and the
+bus number of the parent PCI bridge is 0, the sysfs directory
+representing the struct acpi_device object created for that ACPI
+namespace object will contain the 'physical_node' symbolic link to the
+/sys/devices/pci0000:00/0000:00:02:0/ sysfs directory of the
+corresponding PCI device.
+
+The linking mechanism is generally bus-specific. The core of its
+implementation is located in the drivers/acpi/glue.c file, but there are
+complementary parts depending on the bus types in question located
+elsewhere. For example, the PCI-specific part of it is located in
+drivers/pci/pci-acpi.c.
+
+
+Example Linux ACPI Device Tree
+=================================
+
+The sysfs hierarchy of struct acpi_device objects corresponding to the
+example ACPI namespace illustrated in Figure 2 with the addition of
+fixed PWR_BUTTON/SLP_BUTTON devices is shown below::
+--------------+---+-----------------+
| LNXSYSTEM:00 | \ | acpi:LNXSYSTEM: |
@@ -377,12 +385,14 @@ Wysocki <rafael.j.wysocki@intel.com>.
Figure 3. Example Linux ACPI Device Tree
- NOTE: Each node is represented as "object/path/modalias", where:
- 1. 'object' is the name of the object's directory in sysfs.
- 2. 'path' is the ACPI namespace path of the corresponding
- ACPI namespace object, as returned by the object's 'path'
- sysfs attribute.
- 3. 'modalias' is the value of the object's 'modalias' sysfs
- attribute (as described earlier in this document).
- NOTE: N/A indicates the device object does not have the 'path' or the
- 'modalias' attribute.
+.. note:: Each node is represented as "object/path/modalias", where:
+
+ 1. 'object' is the name of the object's directory in sysfs.
+ 2. 'path' is the ACPI namespace path of the corresponding
+ ACPI namespace object, as returned by the object's 'path'
+ sysfs attribute.
+ 3. 'modalias' is the value of the object's 'modalias' sysfs
+ attribute (as described earlier in this document).
+
+.. note:: N/A indicates the device object does not have the 'path' or the
+ 'modalias' attribute.
--
2.20.1
^ permalink raw reply related [flat|nested] 39+ messages in thread* [PATCH v2 03/24] acpi doc: convert acpi/enumeration.txt to rst format
2019-03-29 0:11 [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree Changbin Du
2019-03-29 0:11 ` [PATCH v2 01/24] Documentation: add Linux ACPI to " Changbin Du
2019-03-29 0:11 ` [PATCH v2 02/24] acpi doc: convert acpi/namespace.txt to rst format Changbin Du
@ 2019-03-29 0:11 ` Changbin Du
2019-03-29 0:11 ` [PATCH v2 04/24] acpi doc: convert acpi/osi.txt " Changbin Du
` (21 subsequent siblings)
24 siblings, 0 replies; 39+ messages in thread
From: Changbin Du @ 2019-03-29 0:11 UTC (permalink / raw)
To: Jonathan Corbet
Cc: rjw, lenb, linux-acpi, linux-kernel, linux-doc, Changbin Du
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
.../acpi/{enumeration.txt => enumeration.rst} | 135 ++++++++++--------
Documentation/acpi/index.rst | 1 +
2 files changed, 74 insertions(+), 62 deletions(-)
rename Documentation/acpi/{enumeration.txt => enumeration.rst} (87%)
diff --git a/Documentation/acpi/enumeration.txt b/Documentation/acpi/enumeration.rst
similarity index 87%
rename from Documentation/acpi/enumeration.txt
rename to Documentation/acpi/enumeration.rst
index 7bcf9c3d9fbe..ce755e963714 100644
--- a/Documentation/acpi/enumeration.txt
+++ b/Documentation/acpi/enumeration.rst
@@ -1,5 +1,9 @@
-ACPI based device enumeration
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. SPDX-License-Identifier: GPL-2.0
+
+=============================
+ACPI Based Device Enumeration
+=============================
+
ACPI 5 introduced a set of new resources (UartTSerialBus, I2cSerialBus,
SpiSerialBus, GpioIo and GpioInt) which can be used in enumerating slave
devices behind serial bus controllers.
@@ -11,12 +15,12 @@ that are accessed through memory-mapped registers.
In order to support this and re-use the existing drivers as much as
possible we decided to do following:
- o Devices that have no bus connector resource are represented as
- platform devices.
+ - Devices that have no bus connector resource are represented as
+ platform devices.
- o Devices behind real busses where there is a connector resource
- are represented as struct spi_device or struct i2c_device
- (standard UARTs are not busses so there is no struct uart_device).
+ - Devices behind real busses where there is a connector resource
+ are represented as struct spi_device or struct i2c_device
+ (standard UARTs are not busses so there is no struct uart_device).
As both ACPI and Device Tree represent a tree of devices (and their
resources) this implementation follows the Device Tree way as much as
@@ -31,7 +35,8 @@ enumerated from ACPI namespace. This handle can be used to extract other
device-specific configuration. There is an example of this below.
Platform bus support
-~~~~~~~~~~~~~~~~~~~~
+====================
+
Since we are using platform devices to represent devices that are not
connected to any physical bus we only need to implement a platform driver
for the device and add supported ACPI IDs. If this same IP-block is used on
@@ -39,7 +44,7 @@ some other non-ACPI platform, the driver might work out of the box or needs
some minor changes.
Adding ACPI support for an existing driver should be pretty
-straightforward. Here is the simplest example:
+straightforward. Here is the simplest example::
#ifdef CONFIG_ACPI
static const struct acpi_device_id mydrv_acpi_match[] = {
@@ -61,12 +66,13 @@ configuring GPIOs it can get its ACPI handle and extract this information
from ACPI tables.
DMA support
-~~~~~~~~~~~
+===========
+
DMA controllers enumerated via ACPI should be registered in the system to
provide generic access to their resources. For example, a driver that would
like to be accessible to slave devices via generic API call
dma_request_slave_channel() must register itself at the end of the probe
-function like this:
+function like this::
err = devm_acpi_dma_controller_register(dev, xlate_func, dw);
/* Handle the error if it's not a case of !CONFIG_ACPI */
@@ -74,7 +80,7 @@ function like this:
and implement custom xlate function if needed (usually acpi_dma_simple_xlate()
is enough) which converts the FixedDMA resource provided by struct
acpi_dma_spec into the corresponding DMA channel. A piece of code for that case
-could look like:
+could look like::
#ifdef CONFIG_ACPI
struct filter_args {
@@ -114,7 +120,7 @@ provided by struct acpi_dma.
Clients must call dma_request_slave_channel() with the string parameter that
corresponds to a specific FixedDMA resource. By default "tx" means the first
entry of the FixedDMA resource array, "rx" means the second entry. The table
-below shows a layout:
+below shows a layout::
Device (I2C0)
{
@@ -138,12 +144,13 @@ acpi_dma_request_slave_chan_by_index() directly and therefore choose the
specific FixedDMA resource by its index.
SPI serial bus support
-~~~~~~~~~~~~~~~~~~~~~~
+======================
+
Slave devices behind SPI bus have SpiSerialBus resource attached to them.
This is extracted automatically by the SPI core and the slave devices are
enumerated once spi_register_master() is called by the bus driver.
-Here is what the ACPI namespace for a SPI slave might look like:
+Here is what the ACPI namespace for a SPI slave might look like::
Device (EEP0)
{
@@ -163,7 +170,7 @@ Here is what the ACPI namespace for a SPI slave might look like:
The SPI device drivers only need to add ACPI IDs in a similar way than with
the platform device drivers. Below is an example where we add ACPI support
-to at25 SPI eeprom driver (this is meant for the above ACPI snippet):
+to at25 SPI eeprom driver (this is meant for the above ACPI snippet)::
#ifdef CONFIG_ACPI
static const struct acpi_device_id at25_acpi_match[] = {
@@ -182,7 +189,7 @@ to at25 SPI eeprom driver (this is meant for the above ACPI snippet):
Note that this driver actually needs more information like page size of the
eeprom etc. but at the time writing this there is no standard way of
-passing those. One idea is to return this in _DSM method like:
+passing those. One idea is to return this in _DSM method like::
Device (EEP0)
{
@@ -202,7 +209,7 @@ passing those. One idea is to return this in _DSM method like:
}
Then the at25 SPI driver can get this configuration by calling _DSM on its
-ACPI handle like:
+ACPI handle like::
struct acpi_buffer output = { ACPI_ALLOCATE_BUFFER, NULL };
struct acpi_object_list input;
@@ -220,14 +227,15 @@ ACPI handle like:
kfree(output.pointer);
I2C serial bus support
-~~~~~~~~~~~~~~~~~~~~~~
+======================
+
The slaves behind I2C bus controller only need to add the ACPI IDs like
with the platform and SPI drivers. The I2C core automatically enumerates
any slave devices behind the controller device once the adapter is
registered.
Below is an example of how to add ACPI support to the existing mpu3050
-input driver:
+input driver::
#ifdef CONFIG_ACPI
static const struct acpi_device_id mpu3050_acpi_match[] = {
@@ -251,56 +259,57 @@ input driver:
};
GPIO support
-~~~~~~~~~~~~
+============
+
ACPI 5 introduced two new resources to describe GPIO connections: GpioIo
and GpioInt. These resources can be used to pass GPIO numbers used by
the device to the driver. ACPI 5.1 extended this with _DSD (Device
Specific Data) which made it possible to name the GPIOs among other things.
-For example:
+For example::
-Device (DEV)
-{
- Method (_CRS, 0, NotSerialized)
+ Device (DEV)
{
- Name (SBUF, ResourceTemplate()
+ Method (_CRS, 0, NotSerialized)
{
- ...
- // Used to power on/off the device
- GpioIo (Exclusive, PullDefault, 0x0000, 0x0000,
- IoRestrictionOutputOnly, "\\_SB.PCI0.GPI0",
- 0x00, ResourceConsumer,,)
+ Name (SBUF, ResourceTemplate()
{
- // Pin List
- 0x0055
- }
+ ...
+ // Used to power on/off the device
+ GpioIo (Exclusive, PullDefault, 0x0000, 0x0000,
+ IoRestrictionOutputOnly, "\\_SB.PCI0.GPI0",
+ 0x00, ResourceConsumer,,)
+ {
+ // Pin List
+ 0x0055
+ }
+
+ // Interrupt for the device
+ GpioInt (Edge, ActiveHigh, ExclusiveAndWake, PullNone,
+ 0x0000, "\\_SB.PCI0.GPI0", 0x00, ResourceConsumer,,)
+ {
+ // Pin list
+ 0x0058
+ }
+
+ ...
- // Interrupt for the device
- GpioInt (Edge, ActiveHigh, ExclusiveAndWake, PullNone,
- 0x0000, "\\_SB.PCI0.GPI0", 0x00, ResourceConsumer,,)
- {
- // Pin list
- 0x0058
}
- ...
-
+ Return (SBUF)
}
- Return (SBUF)
- }
-
- // ACPI 5.1 _DSD used for naming the GPIOs
- Name (_DSD, Package ()
- {
- ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
- Package ()
+ // ACPI 5.1 _DSD used for naming the GPIOs
+ Name (_DSD, Package ()
{
- Package () {"power-gpios", Package() {^DEV, 0, 0, 0 }},
- Package () {"irq-gpios", Package() {^DEV, 1, 0, 0 }},
- }
- })
- ...
+ ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+ Package ()
+ {
+ Package () {"power-gpios", Package() {^DEV, 0, 0, 0 }},
+ Package () {"irq-gpios", Package() {^DEV, 1, 0, 0 }},
+ }
+ })
+ ...
These GPIO numbers are controller relative and path "\\_SB.PCI0.GPI0"
specifies the path to the controller. In order to use these GPIOs in Linux
@@ -310,7 +319,7 @@ There is a standard GPIO API for that and is documented in
Documentation/gpio/.
In the above example we can get the corresponding two GPIO descriptors with
-a code like this:
+a code like this::
#include <linux/gpio/consumer.h>
...
@@ -334,21 +343,22 @@ See Documentation/acpi/gpio-properties.txt for more information about the
_DSD binding related to GPIOs.
MFD devices
-~~~~~~~~~~~
+===========
+
The MFD devices register their children as platform devices. For the child
devices there needs to be an ACPI handle that they can use to reference
parts of the ACPI namespace that relate to them. In the Linux MFD subsystem
we provide two ways:
- o The children share the parent ACPI handle.
- o The MFD cell can specify the ACPI id of the device.
+ - The children share the parent ACPI handle.
+ - The MFD cell can specify the ACPI id of the device.
For the first case, the MFD drivers do not need to do anything. The
resulting child platform device will have its ACPI_COMPANION() set to point
to the parent device.
If the ACPI namespace has a device that we can match using an ACPI id or ACPI
-adr, the cell should be set like:
+adr, the cell should be set like::
static struct mfd_cell_acpi_match my_subdevice_cell_acpi_match = {
.pnpid = "XYZ0001",
@@ -366,7 +376,8 @@ the MFD device and if found, that ACPI companion device is bound to the
resulting child platform device.
Device Tree namespace link device ID
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+====================================
+
The Device Tree protocol uses device identification based on the "compatible"
property whose value is a string or an array of strings recognized as device
identifiers by drivers and the driver core. The set of all those strings may be
@@ -423,4 +434,4 @@ the _DSD of the device object itself or the _DSD of its ancestor in the
Otherwise, the _DSD itself is regarded as invalid and therefore the "compatible"
property returned by it is meaningless.
-Refer to DSD-properties-rules.txt for more information.
+Refer to :doc:`DSD-properties-rules` for more information.
diff --git a/Documentation/acpi/index.rst b/Documentation/acpi/index.rst
index 2f48ffc6061a..52ff8d0a9ed6 100644
--- a/Documentation/acpi/index.rst
+++ b/Documentation/acpi/index.rst
@@ -8,3 +8,4 @@ Linux ACPI (Advanced Configuration and Power Interface)
:maxdepth: 2
namespace
+ enumeration
--
2.20.1
^ permalink raw reply related [flat|nested] 39+ messages in thread* [PATCH v2 04/24] acpi doc: convert acpi/osi.txt to rst format
2019-03-29 0:11 [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree Changbin Du
` (2 preceding siblings ...)
2019-03-29 0:11 ` [PATCH v2 03/24] acpi doc: convert acpi/enumeration.txt " Changbin Du
@ 2019-03-29 0:11 ` Changbin Du
2019-03-29 0:11 ` [PATCH v2 05/24] acpi doc: convert acpi/linuxized-acpica.txt " Changbin Du
` (20 subsequent siblings)
24 siblings, 0 replies; 39+ messages in thread
From: Changbin Du @ 2019-03-29 0:11 UTC (permalink / raw)
To: Jonathan Corbet
Cc: rjw, lenb, linux-acpi, linux-kernel, linux-doc, Changbin Du
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
Documentation/acpi/index.rst | 1 +
Documentation/acpi/{osi.txt => osi.rst} | 15 +++++++++------
2 files changed, 10 insertions(+), 6 deletions(-)
rename Documentation/acpi/{osi.txt => osi.rst} (97%)
diff --git a/Documentation/acpi/index.rst b/Documentation/acpi/index.rst
index 52ff8d0a9ed6..d69c2a416909 100644
--- a/Documentation/acpi/index.rst
+++ b/Documentation/acpi/index.rst
@@ -9,3 +9,4 @@ Linux ACPI (Advanced Configuration and Power Interface)
namespace
enumeration
+ osi
diff --git a/Documentation/acpi/osi.txt b/Documentation/acpi/osi.rst
similarity index 97%
rename from Documentation/acpi/osi.txt
rename to Documentation/acpi/osi.rst
index 50cde0ceb9b0..29e9ef79ebc0 100644
--- a/Documentation/acpi/osi.txt
+++ b/Documentation/acpi/osi.rst
@@ -1,5 +1,8 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==========================
ACPI _OSI and _REV methods
---------------------------
+==========================
An ACPI BIOS can use the "Operating System Interfaces" method (_OSI)
to find out what the operating system supports. Eg. If BIOS
@@ -14,7 +17,7 @@ This document explains how and why the BIOS and Linux should use these methods.
It also explains how and why they are widely misused.
How to use _OSI
----------------
+===============
Linux runs on two groups of machines -- those that are tested by the OEM
to be compatible with Linux, and those that were never tested with Linux,
@@ -62,7 +65,7 @@ the string when that support is added to the kernel.
That was easy. Read on, to find out how to do it wrong.
Before _OSI, there was _OS
---------------------------
+==========================
ACPI 1.0 specified "_OS" as an
"object that evaluates to a string that identifies the operating system."
@@ -96,7 +99,7 @@ That is the *only* viable strategy, as that is what modern Windows does,
and so doing otherwise could steer the BIOS down an untested path.
_OSI is born, and immediately misused
---------------------------------------
+=====================================
With _OSI, the *BIOS* provides the string describing an interface,
and asks the OS: "YES/NO, are you compatible with this interface?"
@@ -144,7 +147,7 @@ catastrophic failure resulting from the BIOS taking paths that
were never validated under *any* OS.
Do not use _REV
----------------
+===============
Since _OSI("Linux") went away, some BIOS writers used _REV
to support Linux and Windows differences in the same BIOS.
@@ -164,7 +167,7 @@ from mid-2015 onward. The ACPI specification will also be updated
to reflect that _REV is deprecated, and always returns 2.
Apple Mac and _OSI("Darwin")
-----------------------------
+============================
On Apple's Mac platforms, the ACPI BIOS invokes _OSI("Darwin")
to determine if the machine is running Apple OSX.
--
2.20.1
^ permalink raw reply related [flat|nested] 39+ messages in thread* [PATCH v2 05/24] acpi doc: convert acpi/linuxized-acpica.txt to rst format
2019-03-29 0:11 [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree Changbin Du
` (3 preceding siblings ...)
2019-03-29 0:11 ` [PATCH v2 04/24] acpi doc: convert acpi/osi.txt " Changbin Du
@ 2019-03-29 0:11 ` Changbin Du
2019-03-29 0:11 ` [PATCH v2 06/24] acpi doc: convert acpi/scan_handlers.txt " Changbin Du
` (19 subsequent siblings)
24 siblings, 0 replies; 39+ messages in thread
From: Changbin Du @ 2019-03-29 0:11 UTC (permalink / raw)
To: Jonathan Corbet
Cc: rjw, lenb, linux-acpi, linux-kernel, linux-doc, Changbin Du
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
Documentation/acpi/index.rst | 1 +
...uxized-acpica.txt => linuxized-acpica.rst} | 115 ++++++++++--------
2 files changed, 66 insertions(+), 50 deletions(-)
rename Documentation/acpi/{linuxized-acpica.txt => linuxized-acpica.rst} (78%)
diff --git a/Documentation/acpi/index.rst b/Documentation/acpi/index.rst
index d69c2a416909..3747a0286442 100644
--- a/Documentation/acpi/index.rst
+++ b/Documentation/acpi/index.rst
@@ -7,6 +7,7 @@ Linux ACPI (Advanced Configuration and Power Interface)
.. toctree::
:maxdepth: 2
+ linuxized-acpica
namespace
enumeration
osi
diff --git a/Documentation/acpi/linuxized-acpica.txt b/Documentation/acpi/linuxized-acpica.rst
similarity index 78%
rename from Documentation/acpi/linuxized-acpica.txt
rename to Documentation/acpi/linuxized-acpica.rst
index 3ad7b0dfb083..f8aaea668e41 100644
--- a/Documentation/acpi/linuxized-acpica.txt
+++ b/Documentation/acpi/linuxized-acpica.rst
@@ -1,31 +1,35 @@
-Linuxized ACPICA - Introduction to ACPICA Release Automation
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
-Copyright (C) 2013-2016, Intel Corporation
-Author: Lv Zheng <lv.zheng@intel.com>
+============================================================
+Linuxized ACPICA - Introduction to ACPICA Release Automation
+============================================================
+:Copyright: |copy| 2013-2016, Intel Corporation
-Abstract:
+:Author: Lv Zheng <lv.zheng@intel.com>
-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.
+: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.
-1. ACPICA Project
+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 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 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:
+The following figure depicts the Linux ACPI subsystem where the ACPICA
+adaptation is included::
+---------------------------------------------------------+
| |
@@ -71,21 +75,27 @@ upstream.
Figure 1. Linux ACPI Software Components
- NOTE:
+.. 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
@@ -95,24 +105,27 @@ upstream.
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
-2. ACPICA Release
+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.
+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:
+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 |
@@ -153,7 +166,7 @@ upstream.
Figure 2. ACPICA -> Linux Upstream Process
- NOTE:
+.. 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.
@@ -170,19 +183,20 @@ upstream.
following kernel configuration options:
CONFIG_ACPI/CONFIG_ACPI_DEBUG/CONFIG_ACPI_DEBUGGER
-3. ACPICA Divergences
+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.
+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".
+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:
+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
@@ -213,11 +227,12 @@ upstream.
rebased on the ACPICA side in order to offer better solutions, new ACPICA
divergences are generated.
-4. ACPICA Development
+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.
+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
@@ -225,7 +240,7 @@ upstream.
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:
+ from the ACPICA local repository::
$ git clone https://github.com/acpica/acpica
$ cd acpica
@@ -240,7 +255,7 @@ upstream.
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:
+ top of the generated ACPICA release patches::
$ git clone https://github.com/acpica/acpica
$ cd acpica
@@ -254,7 +269,7 @@ upstream.
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:
+ a diff file indicating the state of the current divergences::
# git clone https://github.com/acpica/acpica
# git clone http://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
--
2.20.1
^ permalink raw reply related [flat|nested] 39+ messages in thread* [PATCH v2 06/24] acpi doc: convert acpi/scan_handlers.txt to rst format
2019-03-29 0:11 [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree Changbin Du
` (4 preceding siblings ...)
2019-03-29 0:11 ` [PATCH v2 05/24] acpi doc: convert acpi/linuxized-acpica.txt " Changbin Du
@ 2019-03-29 0:11 ` Changbin Du
2019-03-29 0:11 ` [PATCH v2 07/24] acpi doc: convert acpi/DSD-properties-rules.txt " Changbin Du
` (18 subsequent siblings)
24 siblings, 0 replies; 39+ messages in thread
From: Changbin Du @ 2019-03-29 0:11 UTC (permalink / raw)
To: Jonathan Corbet
Cc: rjw, lenb, linux-acpi, linux-kernel, linux-doc, Changbin Du
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
Documentation/acpi/index.rst | 1 +
.../{scan_handlers.txt => scan_handlers.rst} | 24 ++++++++++++-------
2 files changed, 16 insertions(+), 9 deletions(-)
rename Documentation/acpi/{scan_handlers.txt => scan_handlers.rst} (90%)
diff --git a/Documentation/acpi/index.rst b/Documentation/acpi/index.rst
index 3747a0286442..741fcae251b4 100644
--- a/Documentation/acpi/index.rst
+++ b/Documentation/acpi/index.rst
@@ -11,3 +11,4 @@ Linux ACPI (Advanced Configuration and Power Interface)
namespace
enumeration
osi
+ scan_handlers
diff --git a/Documentation/acpi/scan_handlers.txt b/Documentation/acpi/scan_handlers.rst
similarity index 90%
rename from Documentation/acpi/scan_handlers.txt
rename to Documentation/acpi/scan_handlers.rst
index 3246ccf15992..7a197b3a33fc 100644
--- a/Documentation/acpi/scan_handlers.txt
+++ b/Documentation/acpi/scan_handlers.rst
@@ -1,7 +1,13 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
+
+==================
ACPI Scan Handlers
+==================
+
+:Copyright: |copy| 2012, Intel Corporation
-Copyright (C) 2012, Intel Corporation
-Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
+: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
@@ -30,14 +36,14 @@ 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:
+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);
-};
+ 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
--
2.20.1
^ permalink raw reply related [flat|nested] 39+ messages in thread* [PATCH v2 07/24] acpi doc: convert acpi/DSD-properties-rules.txt to rst format
2019-03-29 0:11 [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree Changbin Du
` (5 preceding siblings ...)
2019-03-29 0:11 ` [PATCH v2 06/24] acpi doc: convert acpi/scan_handlers.txt " Changbin Du
@ 2019-03-29 0:11 ` Changbin Du
2019-03-29 0:11 ` [PATCH v2 08/24] acpi doc: convert acpi/gpio-properties.txt " Changbin Du
` (17 subsequent siblings)
24 siblings, 0 replies; 39+ messages in thread
From: Changbin Du @ 2019-03-29 0:11 UTC (permalink / raw)
To: Jonathan Corbet
Cc: rjw, lenb, linux-acpi, linux-kernel, linux-doc, Changbin Du
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
...ies-rules.txt => DSD-properties-rules.rst} | 21 +++++++++++--------
Documentation/acpi/index.rst | 1 +
2 files changed, 13 insertions(+), 9 deletions(-)
rename Documentation/acpi/{DSD-properties-rules.txt => DSD-properties-rules.rst} (88%)
diff --git a/Documentation/acpi/DSD-properties-rules.txt b/Documentation/acpi/DSD-properties-rules.rst
similarity index 88%
rename from Documentation/acpi/DSD-properties-rules.txt
rename to Documentation/acpi/DSD-properties-rules.rst
index 3e4862bdad98..4306f29b6103 100644
--- a/Documentation/acpi/DSD-properties-rules.txt
+++ b/Documentation/acpi/DSD-properties-rules.rst
@@ -1,8 +1,11 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==================================
_DSD Device Properties Usage Rules
-----------------------------------
+==================================
Properties, Property Sets and Property Subsets
-----------------------------------------------
+==============================================
The _DSD (Device Specific Data) configuration object, introduced in ACPI 5.1,
allows any type of device configuration data to be provided via the ACPI
@@ -18,7 +21,7 @@ specific type) associated with it.
In the ACPI _DSD context it is an element of the sub-package following the
generic Device Properties UUID in the _DSD return package as specified in the
-Device Properties UUID definition document [1].
+Device Properties UUID definition document [1]_.
It also may be regarded as the definition of a key and the associated data type
that can be returned by _DSD in the Device Properties UUID sub-package for a
@@ -33,14 +36,14 @@ Property subsets are nested collections of properties. Each of them is
associated with an additional key (name) allowing the subset to be referred
to as a whole (and to be treated as a separate entity). The canonical
representation of property subsets is via the mechanism specified in the
-Hierarchical Properties Extension UUID definition document [2].
+Hierarchical Properties Extension UUID definition document [2]_.
Property sets may be hierarchical. That is, a property set may contain
multiple property subsets that each may contain property subsets of its
own and so on.
General Validity Rule for Property Sets
----------------------------------------
+=======================================
Valid property sets must follow the guidance given by the Device Properties UUID
definition document [1].
@@ -73,7 +76,7 @@ suitable for the ACPI environment and consequently they cannot belong to a valid
property set.
Property Sets and Device Tree Bindings
---------------------------------------
+======================================
It often is useful to make _DSD return property sets that follow Device Tree
bindings.
@@ -91,7 +94,7 @@ expected to automatically work in the ACPI environment regardless of their
contents.
References
-----------
+==========
-[1] http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf
-[2] http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf
+.. [1] http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf
+.. [2] http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf
diff --git a/Documentation/acpi/index.rst b/Documentation/acpi/index.rst
index 741fcae251b4..d10170942e13 100644
--- a/Documentation/acpi/index.rst
+++ b/Documentation/acpi/index.rst
@@ -11,4 +11,5 @@ Linux ACPI (Advanced Configuration and Power Interface)
namespace
enumeration
osi
+ DSD-properties-rules
scan_handlers
--
2.20.1
^ permalink raw reply related [flat|nested] 39+ messages in thread* [PATCH v2 08/24] acpi doc: convert acpi/gpio-properties.txt to rst format
2019-03-29 0:11 [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree Changbin Du
` (6 preceding siblings ...)
2019-03-29 0:11 ` [PATCH v2 07/24] acpi doc: convert acpi/DSD-properties-rules.txt " Changbin Du
@ 2019-03-29 0:11 ` Changbin Du
2019-03-29 0:11 ` [PATCH v2 09/24] acpi doc: convert acpi/method-customizing.txt " Changbin Du
` (16 subsequent siblings)
24 siblings, 0 replies; 39+ messages in thread
From: Changbin Du @ 2019-03-29 0:11 UTC (permalink / raw)
To: Jonathan Corbet
Cc: rjw, lenb, linux-acpi, linux-kernel, linux-doc, Changbin Du
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
...pio-properties.txt => gpio-properties.rst} | 78 +++++++++++--------
Documentation/acpi/index.rst | 1 +
MAINTAINERS | 2 +-
3 files changed, 46 insertions(+), 35 deletions(-)
rename Documentation/acpi/{gpio-properties.txt => gpio-properties.rst} (81%)
diff --git a/Documentation/acpi/gpio-properties.txt b/Documentation/acpi/gpio-properties.rst
similarity index 81%
rename from Documentation/acpi/gpio-properties.txt
rename to Documentation/acpi/gpio-properties.rst
index 88c65cb5bf0a..89c636963544 100644
--- a/Documentation/acpi/gpio-properties.txt
+++ b/Documentation/acpi/gpio-properties.rst
@@ -1,5 +1,8 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+======================================
_DSD Device Properties Related to GPIO
---------------------------------------
+======================================
With the release of ACPI 5.1, the _DSD configuration object finally
allows names to be given to GPIOs (and other things as well) returned
@@ -8,7 +11,7 @@ the corresponding GPIO, which is pretty error prone (it depends on
the _CRS output ordering, for example).
With _DSD we can now query GPIOs using a name instead of an integer
-index, like the ASL example below shows:
+index, like the ASL example below shows::
// Bluetooth device with reset and shutdown GPIOs
Device (BTH)
@@ -34,15 +37,19 @@ index, like the ASL example below shows:
})
}
-The format of the supported GPIO property is:
+The format of the supported GPIO property is::
Package () { "name", Package () { ref, index, pin, active_low }}
- ref - The device that has _CRS containing GpioIo()/GpioInt() resources,
- typically this is the device itself (BTH in our case).
- index - Index of the GpioIo()/GpioInt() resource in _CRS starting from zero.
- pin - Pin in the GpioIo()/GpioInt() resource. Typically this is zero.
- active_low - If 1 the GPIO is marked as active_low.
+ref
+ The device that has _CRS containing GpioIo()/GpioInt() resources,
+ typically this is the device itself (BTH in our case).
+index
+ Index of the GpioIo()/GpioInt() resource in _CRS starting from zero.
+pin
+ Pin in the GpioIo()/GpioInt() resource. Typically this is zero.
+active_low
+ If 1 the GPIO is marked as active_low.
Since ACPI GpioIo() resource does not have a field saying whether it is
active low or high, the "active_low" argument can be used here. Setting
@@ -55,7 +62,7 @@ It is possible to leave holes in the array of GPIOs. This is useful in
cases like with SPI host controllers where some chip selects may be
implemented as GPIOs and some as native signals. For example a SPI host
controller can have chip selects 0 and 2 implemented as GPIOs and 1 as
-native:
+native::
Package () {
"cs-gpios",
@@ -67,7 +74,7 @@ native:
}
Other supported properties
---------------------------
+==========================
Following Device Tree compatible device properties are also supported by
_DSD device properties for GPIO controllers:
@@ -78,7 +85,7 @@ _DSD device properties for GPIO controllers:
- input
- line-name
-Example:
+Example::
Name (_DSD, Package () {
// _DSD Hierarchical Properties Extension UUID
@@ -100,7 +107,7 @@ Example:
- gpio-line-names
-Example:
+Example::
Package () {
"gpio-line-names",
@@ -114,7 +121,7 @@ See Documentation/devicetree/bindings/gpio/gpio.txt for more information
about these properties.
ACPI GPIO Mappings Provided by Drivers
---------------------------------------
+======================================
There are systems in which the ACPI tables do not contain _DSD but provide _CRS
with GpioIo()/GpioInt() resources and device drivers still need to work with
@@ -139,16 +146,16 @@ line in that resource starting from zero, and the active-low flag for that line,
respectively, in analogy with the _DSD GPIO property format specified above.
For the example Bluetooth device discussed previously the data structures in
-question would look like this:
+question would look like this::
-static const struct acpi_gpio_params reset_gpio = { 1, 1, false };
-static const struct acpi_gpio_params shutdown_gpio = { 0, 0, false };
+ static const struct acpi_gpio_params reset_gpio = { 1, 1, false };
+ static const struct acpi_gpio_params shutdown_gpio = { 0, 0, false };
-static const struct acpi_gpio_mapping bluetooth_acpi_gpios[] = {
- { "reset-gpios", &reset_gpio, 1 },
- { "shutdown-gpios", &shutdown_gpio, 1 },
- { },
-};
+ static const struct acpi_gpio_mapping bluetooth_acpi_gpios[] = {
+ { "reset-gpios", &reset_gpio, 1 },
+ { "shutdown-gpios", &shutdown_gpio, 1 },
+ { },
+ };
Next, the mapping table needs to be passed as the second argument to
acpi_dev_add_driver_gpios() that will register it with the ACPI device object
@@ -158,12 +165,12 @@ calling acpi_dev_remove_driver_gpios() on the ACPI device object where that
table was previously registered.
Using the _CRS fallback
------------------------
+=======================
If a device does not have _DSD or the driver does not create ACPI GPIO
mapping, the Linux GPIO framework refuses to return any GPIOs. This is
because the driver does not know what it actually gets. For example if we
-have a device like below:
+have a device like below::
Device (BTH)
{
@@ -177,7 +184,7 @@ have a device like below:
})
}
-The driver might expect to get the right GPIO when it does:
+The driver might expect to get the right GPIO when it does:：
desc = gpiod_get(dev, "reset", GPIOD_OUT_LOW);
@@ -193,22 +200,25 @@ the ACPI GPIO mapping tables are hardly linked to ACPI ID and certain
objects, as listed in the above chapter, of the device in question.
Getting GPIO descriptor
------------------------
+=======================
+
+There are two main approaches to get GPIO resource from ACPI::
-There are two main approaches to get GPIO resource from ACPI:
- desc = gpiod_get(dev, connection_id, flags);
- desc = gpiod_get_index(dev, connection_id, index, flags);
+ desc = gpiod_get(dev, connection_id, flags);
+ desc = gpiod_get_index(dev, connection_id, index, flags);
We may consider two different cases here, i.e. when connection ID is
provided and otherwise.
-Case 1:
- desc = gpiod_get(dev, "non-null-connection-id", flags);
- desc = gpiod_get_index(dev, "non-null-connection-id", index, flags);
+Case 1::
+
+ desc = gpiod_get(dev, "non-null-connection-id", flags);
+ desc = gpiod_get_index(dev, "non-null-connection-id", index, flags);
+
+Case 2::
-Case 2:
- desc = gpiod_get(dev, NULL, flags);
- desc = gpiod_get_index(dev, NULL, index, flags);
+ desc = gpiod_get(dev, NULL, flags);
+ desc = gpiod_get_index(dev, NULL, index, flags);
Case 1 assumes that corresponding ACPI device description must have
defined device properties and will prevent to getting any GPIO resources
diff --git a/Documentation/acpi/index.rst b/Documentation/acpi/index.rst
index d10170942e13..0fae18cc1eea 100644
--- a/Documentation/acpi/index.rst
+++ b/Documentation/acpi/index.rst
@@ -12,4 +12,5 @@ Linux ACPI (Advanced Configuration and Power Interface)
enumeration
osi
DSD-properties-rules
+ gpio-properties
scan_handlers
diff --git a/MAINTAINERS b/MAINTAINERS
index 3e5a5d263f29..718890f348d4 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -6593,7 +6593,7 @@ M: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
L: linux-gpio@vger.kernel.org
L: linux-acpi@vger.kernel.org
S: Maintained
-F: Documentation/acpi/gpio-properties.txt
+F: Documentation/acpi/gpio-properties.rst
F: drivers/gpio/gpiolib-acpi.c
GPIO IR Transmitter
--
2.20.1
^ permalink raw reply related [flat|nested] 39+ messages in thread* [PATCH v2 09/24] acpi doc: convert acpi/method-customizing.txt to rst format
2019-03-29 0:11 [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree Changbin Du
` (7 preceding siblings ...)
2019-03-29 0:11 ` [PATCH v2 08/24] acpi doc: convert acpi/gpio-properties.txt " Changbin Du
@ 2019-03-29 0:11 ` Changbin Du
2019-03-29 0:11 ` [PATCH v2 10/24] acpi doc: convert acpi/initrd_table_override.txt " Changbin Du
` (15 subsequent siblings)
24 siblings, 0 replies; 39+ messages in thread
From: Changbin Du @ 2019-03-29 0:11 UTC (permalink / raw)
To: Jonathan Corbet
Cc: rjw, lenb, linux-acpi, linux-kernel, linux-doc, Changbin Du
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
Documentation/acpi/index.rst | 1 +
Documentation/acpi/method-customizing.rst | 82 +++++++++++++++++++++++
Documentation/acpi/method-customizing.txt | 73 --------------------
3 files changed, 83 insertions(+), 73 deletions(-)
create mode 100644 Documentation/acpi/method-customizing.rst
delete mode 100644 Documentation/acpi/method-customizing.txt
diff --git a/Documentation/acpi/index.rst b/Documentation/acpi/index.rst
index 0fae18cc1eea..409e98f19748 100644
--- a/Documentation/acpi/index.rst
+++ b/Documentation/acpi/index.rst
@@ -14,3 +14,4 @@ Linux ACPI (Advanced Configuration and Power Interface)
DSD-properties-rules
gpio-properties
scan_handlers
+ method-customizing
diff --git a/Documentation/acpi/method-customizing.rst b/Documentation/acpi/method-customizing.rst
new file mode 100644
index 000000000000..32eb1cdc1549
--- /dev/null
+++ b/Documentation/acpi/method-customizing.rst
@@ -0,0 +1,82 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=======================================
+Linux ACPI Custom Control Method How To
+=======================================
+
+:Author: Zhang Rui <rui.zhang@intel.com>
+
+
+Linux supports customizing ACPI control methods at runtime.
+
+Users can use this to:
+
+1. override an existing method which may not work correctly,
+ or just for debugging purposes.
+2. insert a completely new method in order to create a missing
+ method such as _OFF, _ON, _STA, _INI, etc.
+
+For these cases, it is far simpler to dynamically install a single
+control method rather than override the entire DSDT, because kernel
+rebuild/reboot is not needed and test result can be got in minutes.
+
+.. note:: Only ACPI METHOD can be overridden, any other object types like
+ "Device", "OperationRegion", are not recognized. Methods
+ declared inside scope operators are also not supported.
+.. note:: The same ACPI control method can be overridden for many times,
+ and it's always the latest one that used by Linux/kernel.
+.. note:: To get the ACPI debug object output (Store (AAAA, Debug)),
+ please run "echo 1 > /sys/module/acpi/parameters/aml_debug_output".
+
+1. override an existing method
+==============================
+a) get the ACPI table via ACPI sysfs I/F. e.g. to get the DSDT,
+ just run "cat /sys/firmware/acpi/tables/DSDT > /tmp/dsdt.dat"
+b) disassemble the table by running "iasl -d dsdt.dat".
+c) rewrite the ASL code of the method and save it in a new file,
+d) package the new file (psr.asl) to an ACPI table format.
+ Here is an example of a customized \_SB._AC._PSR method::
+
+ DefinitionBlock ("", "SSDT", 1, "", "", 0x20080715)
+ {
+ Method (\_SB_.AC._PSR, 0, NotSerialized)
+ {
+ Store ("In AC _PSR", Debug)
+ Return (ACON)
+ }
+ }
+
+ Note that the full pathname of the method in ACPI namespace
+ should be used.
+e) assemble the file to generate the AML code of the method.
+ e.g. "iasl -vw 6084 psr.asl" (psr.aml is generated as a result)
+ If parameter "-vw 6084" is not supported by your iASL compiler,
+ please try a newer version.
+f) mount debugfs by "mount -t debugfs none /sys/kernel/debug"
+g) override the old method via the debugfs by running
+ "cat /tmp/psr.aml > /sys/kernel/debug/acpi/custom_method"
+
+2. insert a new method
+======================
+This is easier than overriding an existing method.
+We just need to create the ASL code of the method we want to
+insert and then follow the step c) ~ g) in section 1.
+
+3. undo your changes
+====================
+The "undo" operation is not supported for a new inserted method
+right now, i.e. we can not remove a method currently.
+For an overridden method, in order to undo your changes, please
+save a copy of the method original ASL code in step c) section 1,
+and redo step c) ~ g) to override the method with the original one.
+
+
+.. note:: We can use a kernel with multiple custom ACPI method running,
+ But each individual write to debugfs can implement a SINGLE
+ method override. i.e. if we want to insert/override multiple
+ ACPI methods, we need to redo step c) ~ g) for multiple times.
+
+.. note:: Be aware that root can mis-use this driver to modify arbitrary
+ memory and gain additional rights, if root's privileges got
+ restricted (for example if root is not allowed to load additional
+ modules after boot).
diff --git a/Documentation/acpi/method-customizing.txt b/Documentation/acpi/method-customizing.txt
deleted file mode 100644
index 7235da975f23..000000000000
--- a/Documentation/acpi/method-customizing.txt
+++ /dev/null
@@ -1,73 +0,0 @@
-Linux ACPI Custom Control Method How To
-=======================================
-
-Written by Zhang Rui <rui.zhang@intel.com>
-
-
-Linux supports customizing ACPI control methods at runtime.
-
-Users can use this to
-1. override an existing method which may not work correctly,
- or just for debugging purposes.
-2. insert a completely new method in order to create a missing
- method such as _OFF, _ON, _STA, _INI, etc.
-For these cases, it is far simpler to dynamically install a single
-control method rather than override the entire DSDT, because kernel
-rebuild/reboot is not needed and test result can be got in minutes.
-
-Note: Only ACPI METHOD can be overridden, any other object types like
- "Device", "OperationRegion", are not recognized. Methods
- declared inside scope operators are also not supported.
-Note: The same ACPI control method can be overridden for many times,
- and it's always the latest one that used by Linux/kernel.
-Note: To get the ACPI debug object output (Store (AAAA, Debug)),
- please run "echo 1 > /sys/module/acpi/parameters/aml_debug_output".
-
-1. override an existing method
- a) get the ACPI table via ACPI sysfs I/F. e.g. to get the DSDT,
- just run "cat /sys/firmware/acpi/tables/DSDT > /tmp/dsdt.dat"
- b) disassemble the table by running "iasl -d dsdt.dat".
- c) rewrite the ASL code of the method and save it in a new file,
- d) package the new file (psr.asl) to an ACPI table format.
- Here is an example of a customized \_SB._AC._PSR method,
-
- DefinitionBlock ("", "SSDT", 1, "", "", 0x20080715)
- {
- Method (\_SB_.AC._PSR, 0, NotSerialized)
- {
- Store ("In AC _PSR", Debug)
- Return (ACON)
- }
- }
- Note that the full pathname of the method in ACPI namespace
- should be used.
- e) assemble the file to generate the AML code of the method.
- e.g. "iasl -vw 6084 psr.asl" (psr.aml is generated as a result)
- If parameter "-vw 6084" is not supported by your iASL compiler,
- please try a newer version.
- f) mount debugfs by "mount -t debugfs none /sys/kernel/debug"
- g) override the old method via the debugfs by running
- "cat /tmp/psr.aml > /sys/kernel/debug/acpi/custom_method"
-
-2. insert a new method
- This is easier than overriding an existing method.
- We just need to create the ASL code of the method we want to
- insert and then follow the step c) ~ g) in section 1.
-
-3. undo your changes
- The "undo" operation is not supported for a new inserted method
- right now, i.e. we can not remove a method currently.
- For an overridden method, in order to undo your changes, please
- save a copy of the method original ASL code in step c) section 1,
- and redo step c) ~ g) to override the method with the original one.
-
-
-Note: We can use a kernel with multiple custom ACPI method running,
- But each individual write to debugfs can implement a SINGLE
- method override. i.e. if we want to insert/override multiple
- ACPI methods, we need to redo step c) ~ g) for multiple times.
-
-Note: Be aware that root can mis-use this driver to modify arbitrary
- memory and gain additional rights, if root's privileges got
- restricted (for example if root is not allowed to load additional
- modules after boot).
--
2.20.1
^ permalink raw reply related [flat|nested] 39+ messages in thread* [PATCH v2 10/24] acpi doc: convert acpi/initrd_table_override.txt to rst format
2019-03-29 0:11 [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree Changbin Du
` (8 preceding siblings ...)
2019-03-29 0:11 ` [PATCH v2 09/24] acpi doc: convert acpi/method-customizing.txt " Changbin Du
@ 2019-03-29 0:11 ` Changbin Du
2019-03-29 0:11 ` [PATCH v2 11/24] acpi doc: convert acpi/dsdt-override.txt " Changbin Du
` (14 subsequent siblings)
24 siblings, 0 replies; 39+ messages in thread
From: Changbin Du @ 2019-03-29 0:11 UTC (permalink / raw)
To: Jonathan Corbet
Cc: rjw, lenb, linux-acpi, linux-kernel, linux-doc, Changbin Du
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
Documentation/acpi/index.rst | 1 +
Documentation/acpi/initrd_table_override.rst | 120 +++++++++++++++++++
Documentation/acpi/initrd_table_override.txt | 111 -----------------
3 files changed, 121 insertions(+), 111 deletions(-)
create mode 100644 Documentation/acpi/initrd_table_override.rst
delete mode 100644 Documentation/acpi/initrd_table_override.txt
diff --git a/Documentation/acpi/index.rst b/Documentation/acpi/index.rst
index 409e98f19748..213c4601a42c 100644
--- a/Documentation/acpi/index.rst
+++ b/Documentation/acpi/index.rst
@@ -15,3 +15,4 @@ Linux ACPI (Advanced Configuration and Power Interface)
gpio-properties
scan_handlers
method-customizing
+ initrd_table_override
diff --git a/Documentation/acpi/initrd_table_override.rst b/Documentation/acpi/initrd_table_override.rst
new file mode 100644
index 000000000000..0787b2b91ded
--- /dev/null
+++ b/Documentation/acpi/initrd_table_override.rst
@@ -0,0 +1,120 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+================================
+Upgrading ACPI tables via initrd
+================================
+
+1) Introduction (What is this about)
+2) What is this for
+3) How does it work
+4) References (Where to retrieve userspace tools)
+
+1) What is this about
+=====================
+
+If the ACPI_TABLE_UPGRADE compile option is true, it is possible to
+upgrade the ACPI execution environment that is defined by the ACPI tables
+via upgrading the ACPI tables provided by the BIOS with an instrumented,
+modified, more recent version one, or installing brand new ACPI tables.
+
+When building initrd with kernel in a single image, option
+ACPI_TABLE_OVERRIDE_VIA_BUILTIN_INITRD should also be true for this
+feature to work.
+
+For a full list of ACPI tables that can be upgraded/installed, take a look
+at the char `*table_sigs[MAX_ACPI_SIGNATURE];` definition in
+drivers/acpi/tables.c.
+
+All ACPI tables iasl (Intel's ACPI compiler and disassembler) knows should
+be overridable, except:
+
+ - ACPI_SIG_RSDP (has a signature of 6 bytes)
+ - ACPI_SIG_FACS (does not have an ordinary ACPI table header)
+
+Both could get implemented as well.
+
+
+2) What is this for
+===================
+
+Complain to your platform/BIOS vendor if you find a bug which is so severe
+that a workaround is not accepted in the Linux kernel. And this facility
+allows you to upgrade the buggy tables before your platform/BIOS vendor
+releases an upgraded BIOS binary.
+
+This facility can be used by platform/BIOS vendors to provide a Linux
+compatible environment without modifying the underlying platform firmware.
+
+This facility also provides a powerful feature to easily debug and test
+ACPI BIOS table compatibility with the Linux kernel by modifying old
+platform provided ACPI tables or inserting new ACPI tables.
+
+It can and should be enabled in any kernel because there is no functional
+change with not instrumented initrds.
+
+
+3) How does it work
+===================
+::
+
+ # Extract the machine's ACPI tables:
+ cd /tmp
+ acpidump >acpidump
+ acpixtract -a acpidump
+ # Disassemble, modify and recompile them:
+ iasl -d *.dat
+ # For example add this statement into a _PRT (PCI Routing Table) function
+ # of the DSDT:
+ Store("HELLO WORLD", debug)
+ # And increase the OEM Revision. For example, before modification:
+ DefinitionBlock ("DSDT.aml", "DSDT", 2, "INTEL ", "TEMPLATE", 0x00000000)
+ # After modification:
+ DefinitionBlock ("DSDT.aml", "DSDT", 2, "INTEL ", "TEMPLATE", 0x00000001)
+ iasl -sa dsdt.dsl
+ # Add the raw ACPI tables to an uncompressed cpio archive.
+ # They must be put into a /kernel/firmware/acpi directory inside the cpio
+ # archive. Note that if the table put here matches a platform table
+ # (similar Table Signature, and similar OEMID, and similar OEM Table ID)
+ # with a more recent OEM Revision, the platform table will be upgraded by
+ # this table. If the table put here doesn't match a platform table
+ # (dissimilar Table Signature, or dissimilar OEMID, or dissimilar OEM Table
+ # ID), this table will be appended.
+ mkdir -p kernel/firmware/acpi
+ cp dsdt.aml kernel/firmware/acpi
+ # A maximum of "NR_ACPI_INITRD_TABLES (64)" tables are currently allowed
+ # (see osl.c):
+ iasl -sa facp.dsl
+ iasl -sa ssdt1.dsl
+ cp facp.aml kernel/firmware/acpi
+ cp ssdt1.aml kernel/firmware/acpi
+ # The uncompressed cpio archive must be the first. Other, typically
+ # compressed cpio archives, must be concatenated on top of the uncompressed
+ # one. Following command creates the uncompressed cpio archive and
+ # concatenates the original initrd on top:
+ find kernel | cpio -H newc --create > /boot/instrumented_initrd
+ cat /boot/initrd >>/boot/instrumented_initrd
+ # reboot with increased acpi debug level, e.g. boot params:
+ acpi.debug_level=0x2 acpi.debug_layer=0xFFFFFFFF
+ # and check your syslog:
+ [ 1.268089] ACPI: PCI Interrupt Routing Table [\_SB_.PCI0._PRT]
+ [ 1.272091] [ACPI Debug] String [0x0B] "HELLO WORLD"
+
+iasl is able to disassemble and recompile quite a lot different,
+also static ACPI tables.
+
+
+4) Where to retrieve userspace tools
+====================================
+
+iasl and acpixtract are part of Intel's ACPICA project:
+http://acpica.org/
+
+and should be packaged by distributions (for example in the acpica package
+on SUSE).
+
+acpidump can be found in Len Browns pmtools:
+ftp://kernel.org/pub/linux/kernel/people/lenb/acpi/utils/pmtools/acpidump
+
+This tool is also part of the acpica package on SUSE.
+Alternatively, used ACPI tables can be retrieved via sysfs in latest kernels:
+/sys/firmware/acpi/tables
diff --git a/Documentation/acpi/initrd_table_override.txt b/Documentation/acpi/initrd_table_override.txt
deleted file mode 100644
index 30437a6db373..000000000000
--- a/Documentation/acpi/initrd_table_override.txt
+++ /dev/null
@@ -1,111 +0,0 @@
-Upgrading ACPI tables via initrd
-================================
-
-1) Introduction (What is this about)
-2) What is this for
-3) How does it work
-4) References (Where to retrieve userspace tools)
-
-1) What is this about
----------------------
-
-If the ACPI_TABLE_UPGRADE compile option is true, it is possible to
-upgrade the ACPI execution environment that is defined by the ACPI tables
-via upgrading the ACPI tables provided by the BIOS with an instrumented,
-modified, more recent version one, or installing brand new ACPI tables.
-
-When building initrd with kernel in a single image, option
-ACPI_TABLE_OVERRIDE_VIA_BUILTIN_INITRD should also be true for this
-feature to work.
-
-For a full list of ACPI tables that can be upgraded/installed, take a look
-at the char *table_sigs[MAX_ACPI_SIGNATURE]; definition in
-drivers/acpi/tables.c.
-All ACPI tables iasl (Intel's ACPI compiler and disassembler) knows should
-be overridable, except:
- - ACPI_SIG_RSDP (has a signature of 6 bytes)
- - ACPI_SIG_FACS (does not have an ordinary ACPI table header)
-Both could get implemented as well.
-
-
-2) What is this for
--------------------
-
-Complain to your platform/BIOS vendor if you find a bug which is so severe
-that a workaround is not accepted in the Linux kernel. And this facility
-allows you to upgrade the buggy tables before your platform/BIOS vendor
-releases an upgraded BIOS binary.
-
-This facility can be used by platform/BIOS vendors to provide a Linux
-compatible environment without modifying the underlying platform firmware.
-
-This facility also provides a powerful feature to easily debug and test
-ACPI BIOS table compatibility with the Linux kernel by modifying old
-platform provided ACPI tables or inserting new ACPI tables.
-
-It can and should be enabled in any kernel because there is no functional
-change with not instrumented initrds.
-
-
-3) How does it work
--------------------
-
-# Extract the machine's ACPI tables:
-cd /tmp
-acpidump >acpidump
-acpixtract -a acpidump
-# Disassemble, modify and recompile them:
-iasl -d *.dat
-# For example add this statement into a _PRT (PCI Routing Table) function
-# of the DSDT:
-Store("HELLO WORLD", debug)
-# And increase the OEM Revision. For example, before modification:
-DefinitionBlock ("DSDT.aml", "DSDT", 2, "INTEL ", "TEMPLATE", 0x00000000)
-# After modification:
-DefinitionBlock ("DSDT.aml", "DSDT", 2, "INTEL ", "TEMPLATE", 0x00000001)
-iasl -sa dsdt.dsl
-# Add the raw ACPI tables to an uncompressed cpio archive.
-# They must be put into a /kernel/firmware/acpi directory inside the cpio
-# archive. Note that if the table put here matches a platform table
-# (similar Table Signature, and similar OEMID, and similar OEM Table ID)
-# with a more recent OEM Revision, the platform table will be upgraded by
-# this table. If the table put here doesn't match a platform table
-# (dissimilar Table Signature, or dissimilar OEMID, or dissimilar OEM Table
-# ID), this table will be appended.
-mkdir -p kernel/firmware/acpi
-cp dsdt.aml kernel/firmware/acpi
-# A maximum of "NR_ACPI_INITRD_TABLES (64)" tables are currently allowed
-# (see osl.c):
-iasl -sa facp.dsl
-iasl -sa ssdt1.dsl
-cp facp.aml kernel/firmware/acpi
-cp ssdt1.aml kernel/firmware/acpi
-# The uncompressed cpio archive must be the first. Other, typically
-# compressed cpio archives, must be concatenated on top of the uncompressed
-# one. Following command creates the uncompressed cpio archive and
-# concatenates the original initrd on top:
-find kernel | cpio -H newc --create > /boot/instrumented_initrd
-cat /boot/initrd >>/boot/instrumented_initrd
-# reboot with increased acpi debug level, e.g. boot params:
-acpi.debug_level=0x2 acpi.debug_layer=0xFFFFFFFF
-# and check your syslog:
-[ 1.268089] ACPI: PCI Interrupt Routing Table [\_SB_.PCI0._PRT]
-[ 1.272091] [ACPI Debug] String [0x0B] "HELLO WORLD"
-
-iasl is able to disassemble and recompile quite a lot different,
-also static ACPI tables.
-
-
-4) Where to retrieve userspace tools
-------------------------------------
-
-iasl and acpixtract are part of Intel's ACPICA project:
-http://acpica.org/
-and should be packaged by distributions (for example in the acpica package
-on SUSE).
-
-acpidump can be found in Len Browns pmtools:
-ftp://kernel.org/pub/linux/kernel/people/lenb/acpi/utils/pmtools/acpidump
-This tool is also part of the acpica package on SUSE.
-Alternatively, used ACPI tables can be retrieved via sysfs in latest kernels:
-/sys/firmware/acpi/tables
--
2.20.1
^ permalink raw reply related [flat|nested] 39+ messages in thread* [PATCH v2 11/24] acpi doc: convert acpi/dsdt-override.txt to rst format
2019-03-29 0:11 [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree Changbin Du
` (9 preceding siblings ...)
2019-03-29 0:11 ` [PATCH v2 10/24] acpi doc: convert acpi/initrd_table_override.txt " Changbin Du
@ 2019-03-29 0:11 ` Changbin Du
2019-03-29 0:11 ` [PATCH v2 12/24] acpi doc: convert acpi/i2c-muxes.txt " Changbin Du
` (13 subsequent siblings)
24 siblings, 0 replies; 39+ messages in thread
From: Changbin Du @ 2019-03-29 0:11 UTC (permalink / raw)
To: Jonathan Corbet
Cc: rjw, lenb, linux-acpi, linux-kernel, linux-doc, Changbin Du
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
.../acpi/{dsdt-override.txt => dsdt-override.rst} | 8 +++++++-
Documentation/acpi/index.rst | 1 +
2 files changed, 8 insertions(+), 1 deletion(-)
rename Documentation/acpi/{dsdt-override.txt => dsdt-override.rst} (56%)
diff --git a/Documentation/acpi/dsdt-override.txt b/Documentation/acpi/dsdt-override.rst
similarity index 56%
rename from Documentation/acpi/dsdt-override.txt
rename to Documentation/acpi/dsdt-override.rst
index 784841caa6e6..50bd7f194bf4 100644
--- a/Documentation/acpi/dsdt-override.txt
+++ b/Documentation/acpi/dsdt-override.rst
@@ -1,6 +1,12 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===============
+Overriding DSDT
+===============
+
Linux supports a method of overriding the BIOS DSDT:
-CONFIG_ACPI_CUSTOM_DSDT builds the image into the kernel.
+CONFIG_ACPI_CUSTOM_DSDT - builds the image into the kernel.
When to use this method is described in detail on the
Linux/ACPI home page:
diff --git a/Documentation/acpi/index.rst b/Documentation/acpi/index.rst
index 213c4601a42c..72fe855f567e 100644
--- a/Documentation/acpi/index.rst
+++ b/Documentation/acpi/index.rst
@@ -16,3 +16,4 @@ Linux ACPI (Advanced Configuration and Power Interface)
scan_handlers
method-customizing
initrd_table_override
+ dsdt-override
--
2.20.1
^ permalink raw reply related [flat|nested] 39+ messages in thread* [PATCH v2 12/24] acpi doc: convert acpi/i2c-muxes.txt to rst format
2019-03-29 0:11 [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree Changbin Du
` (10 preceding siblings ...)
2019-03-29 0:11 ` [PATCH v2 11/24] acpi doc: convert acpi/dsdt-override.txt " Changbin Du
@ 2019-03-29 0:11 ` Changbin Du
2019-03-29 0:11 ` [PATCH v2 13/24] acpi doc: convert acpi/acpi-lid.txt " Changbin Du
` (12 subsequent siblings)
24 siblings, 0 replies; 39+ messages in thread
From: Changbin Du @ 2019-03-29 0:11 UTC (permalink / raw)
To: Jonathan Corbet
Cc: rjw, lenb, linux-acpi, linux-kernel, linux-doc, Changbin Du
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
Documentation/acpi/i2c-muxes.rst | 61 ++++++++++++++++++++++++++++++++
Documentation/acpi/i2c-muxes.txt | 58 ------------------------------
Documentation/acpi/index.rst | 1 +
3 files changed, 62 insertions(+), 58 deletions(-)
create mode 100644 Documentation/acpi/i2c-muxes.rst
delete mode 100644 Documentation/acpi/i2c-muxes.txt
diff --git a/Documentation/acpi/i2c-muxes.rst b/Documentation/acpi/i2c-muxes.rst
new file mode 100644
index 000000000000..3a8997ccd7c4
--- /dev/null
+++ b/Documentation/acpi/i2c-muxes.rst
@@ -0,0 +1,61 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==============
+ACPI I2C Muxes
+==============
+
+Describing an I2C device hierarchy that includes I2C muxes requires an ACPI
+Device () scope per mux channel.
+
+Consider this topology::
+
+ +------+ +------+
+ | SMB1 |-->| MUX0 |--CH00--> i2c client A (0x50)
+ | | | 0x70 |--CH01--> i2c client B (0x50)
+ +------+ +------+
+
+which corresponds to the following ASL::
+
+ Device (SMB1)
+ {
+ Name (_HID, ...)
+ Device (MUX0)
+ {
+ Name (_HID, ...)
+ Name (_CRS, ResourceTemplate () {
+ I2cSerialBus (0x70, ControllerInitiated, I2C_SPEED,
+ AddressingMode7Bit, "^SMB1", 0x00,
+ ResourceConsumer,,)
+ }
+
+ Device (CH00)
+ {
+ Name (_ADR, 0)
+
+ Device (CLIA)
+ {
+ Name (_HID, ...)
+ Name (_CRS, ResourceTemplate () {
+ I2cSerialBus (0x50, ControllerInitiated, I2C_SPEED,
+ AddressingMode7Bit, "^CH00", 0x00,
+ ResourceConsumer,,)
+ }
+ }
+ }
+
+ Device (CH01)
+ {
+ Name (_ADR, 1)
+
+ Device (CLIB)
+ {
+ Name (_HID, ...)
+ Name (_CRS, ResourceTemplate () {
+ I2cSerialBus (0x50, ControllerInitiated, I2C_SPEED,
+ AddressingMode7Bit, "^CH01", 0x00,
+ ResourceConsumer,,)
+ }
+ }
+ }
+ }
+ }
diff --git a/Documentation/acpi/i2c-muxes.txt b/Documentation/acpi/i2c-muxes.txt
deleted file mode 100644
index 9fcc4f0b885e..000000000000
--- a/Documentation/acpi/i2c-muxes.txt
+++ /dev/null
@@ -1,58 +0,0 @@
-ACPI I2C Muxes
---------------
-
-Describing an I2C device hierarchy that includes I2C muxes requires an ACPI
-Device () scope per mux channel.
-
-Consider this topology:
-
-+------+ +------+
-| SMB1 |-->| MUX0 |--CH00--> i2c client A (0x50)
-| | | 0x70 |--CH01--> i2c client B (0x50)
-+------+ +------+
-
-which corresponds to the following ASL:
-
-Device (SMB1)
-{
- Name (_HID, ...)
- Device (MUX0)
- {
- Name (_HID, ...)
- Name (_CRS, ResourceTemplate () {
- I2cSerialBus (0x70, ControllerInitiated, I2C_SPEED,
- AddressingMode7Bit, "^SMB1", 0x00,
- ResourceConsumer,,)
- }
-
- Device (CH00)
- {
- Name (_ADR, 0)
-
- Device (CLIA)
- {
- Name (_HID, ...)
- Name (_CRS, ResourceTemplate () {
- I2cSerialBus (0x50, ControllerInitiated, I2C_SPEED,
- AddressingMode7Bit, "^CH00", 0x00,
- ResourceConsumer,,)
- }
- }
- }
-
- Device (CH01)
- {
- Name (_ADR, 1)
-
- Device (CLIB)
- {
- Name (_HID, ...)
- Name (_CRS, ResourceTemplate () {
- I2cSerialBus (0x50, ControllerInitiated, I2C_SPEED,
- AddressingMode7Bit, "^CH01", 0x00,
- ResourceConsumer,,)
- }
- }
- }
- }
-}
diff --git a/Documentation/acpi/index.rst b/Documentation/acpi/index.rst
index 72fe855f567e..78f72a525a3f 100644
--- a/Documentation/acpi/index.rst
+++ b/Documentation/acpi/index.rst
@@ -13,6 +13,7 @@ Linux ACPI (Advanced Configuration and Power Interface)
osi
DSD-properties-rules
gpio-properties
+ i2c-muxes
scan_handlers
method-customizing
initrd_table_override
--
2.20.1
^ permalink raw reply related [flat|nested] 39+ messages in thread* [PATCH v2 13/24] acpi doc: convert acpi/acpi-lid.txt to rst format
2019-03-29 0:11 [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree Changbin Du
` (11 preceding siblings ...)
2019-03-29 0:11 ` [PATCH v2 12/24] acpi doc: convert acpi/i2c-muxes.txt " Changbin Du
@ 2019-03-29 0:11 ` Changbin Du
2019-03-29 0:11 ` [PATCH v2 14/24] acpi doc: convert acpi/dsd/graph.txt " Changbin Du
` (11 subsequent siblings)
24 siblings, 0 replies; 39+ messages in thread
From: Changbin Du @ 2019-03-29 0:11 UTC (permalink / raw)
To: Jonathan Corbet
Cc: rjw, lenb, linux-acpi, linux-kernel, linux-doc, Changbin Du
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
.../acpi/{acpi-lid.txt => acpi-lid.rst} | 48 ++++++++++++-------
Documentation/acpi/index.rst | 1 +
2 files changed, 33 insertions(+), 16 deletions(-)
rename Documentation/acpi/{acpi-lid.txt => acpi-lid.rst} (77%)
diff --git a/Documentation/acpi/acpi-lid.txt b/Documentation/acpi/acpi-lid.rst
similarity index 77%
rename from Documentation/acpi/acpi-lid.txt
rename to Documentation/acpi/acpi-lid.rst
index effe7af3a5af..1d19e15a6945 100644
--- a/Documentation/acpi/acpi-lid.txt
+++ b/Documentation/acpi/acpi-lid.rst
@@ -1,25 +1,29 @@
-Special Usage Model of the ACPI Control Method Lid Device
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
-Copyright (C) 2016, Intel Corporation
-Author: Lv Zheng <lv.zheng@intel.com>
+=========================================================
+Special Usage Model of the ACPI Control Method Lid Device
+=========================================================
+:Copyright: |copy| 2016, Intel Corporation
-Abstract:
+:Author: Lv Zheng <lv.zheng@intel.com>
-Platforms containing lids convey lid state (open/close) to OSPMs using a
-control method lid device. To implement this, the AML tables issue
-Notify(lid_device, 0x80) to notify the OSPMs whenever the lid state has
-changed. The _LID control method for the lid device must be implemented to
-report the "current" state of the lid as either "opened" or "closed".
+:Abstract: Platforms containing lids convey lid state (open/close) to OSPMs
+ using a control method lid device. To implement this, the AML tables issue
+ Notify(lid_device, 0x80) to notify the OSPMs whenever the lid state has
+ changed. The _LID control method for the lid device must be implemented to
+ report the "current" state of the lid as either "opened" or "closed".
-For most platforms, both the _LID method and the lid notifications are
-reliable. However, there are exceptions. In order to work with these
-exceptional buggy platforms, special restrictions and expections should be
-taken into account. This document describes the restrictions and the
-expections of the Linux ACPI lid device driver.
+ For most platforms, both the _LID method and the lid notifications are
+ reliable. However, there are exceptions. In order to work with these
+ exceptional buggy platforms, special restrictions and expections should be
+ taken into account. This document describes the restrictions and the
+ expections of the Linux ACPI lid device driver.
1. Restrictions of the returning value of the _LID control method
+=================================================================
The _LID control method is described to return the "current" lid state.
However the word of "current" has ambiguity, some buggy AML tables return
@@ -31,6 +35,7 @@ with cached value, the initial returning value is likely not reliable.
There are platforms always retun "closed" as initial lid state.
2. Restrictions of the lid state change notifications
+=====================================================
There are buggy AML tables never notifying when the lid device state is
changed to "opened". Thus the "opened" notification is not guaranteed. But
@@ -40,17 +45,21 @@ trigger some system power saving operations on Windows. Since it is fully
tested, it is reliable from all AML tables.
3. Expections for the userspace users of the ACPI lid device driver
+===================================================================
The ACPI button driver exports the lid state to the userspace via the
-following file:
+following file::
+
/proc/acpi/button/lid/LID0/state
+
This file actually calls the _LID control method described above. And given
the previous explanation, it is not reliable enough on some platforms. So
it is advised for the userspace program to not to solely rely on this file
to determine the actual lid state.
The ACPI button driver emits the following input event to the userspace:
- SW_LID
+ * SW_LID
+
The ACPI lid device driver is implemented to try to deliver the platform
triggered events to the userspace. However, given the fact that the buggy
firmware cannot make sure "opened"/"closed" events are paired, the ACPI
@@ -59,20 +68,25 @@ button driver uses the following 3 modes in order not to trigger issues.
If the userspace hasn't been prepared to ignore the unreliable "opened"
events and the unreliable initial state notification, Linux users can use
the following kernel parameters to handle the possible issues:
+
A. button.lid_init_state=method:
When this option is specified, the ACPI button driver reports the
initial lid state using the returning value of the _LID control method
and whether the "opened"/"closed" events are paired fully relies on the
firmware implementation.
+
This option can be used to fix some platforms where the returning value
of the _LID control method is reliable but the initial lid state
notification is missing.
+
This option is the default behavior during the period the userspace
isn't ready to handle the buggy AML tables.
+
B. button.lid_init_state=open:
When this option is specified, the ACPI button driver always reports the
initial lid state as "opened" and whether the "opened"/"closed" events
are paired fully relies on the firmware implementation.
+
This may fix some platforms where the returning value of the _LID
control method is not reliable and the initial lid state notification is
missing.
@@ -80,6 +94,7 @@ B. button.lid_init_state=open:
If the userspace has been prepared to ignore the unreliable "opened" events
and the unreliable initial state notification, Linux users should always
use the following kernel parameter:
+
C. button.lid_init_state=ignore:
When this option is specified, the ACPI button driver never reports the
initial lid state and there is a compensation mechanism implemented to
@@ -89,6 +104,7 @@ C. button.lid_init_state=ignore:
notifications can be delivered to the userspace when the lid is actually
opens given that some AML tables do not send "opened" notifications
reliably.
+
In this mode, if everything is correctly implemented by the platform
firmware, the old userspace programs should still work. Otherwise, the
new userspace programs are required to work with the ACPI button driver.
diff --git a/Documentation/acpi/index.rst b/Documentation/acpi/index.rst
index 78f72a525a3f..909f12833692 100644
--- a/Documentation/acpi/index.rst
+++ b/Documentation/acpi/index.rst
@@ -14,6 +14,7 @@ Linux ACPI (Advanced Configuration and Power Interface)
DSD-properties-rules
gpio-properties
i2c-muxes
+ acpi-lid
scan_handlers
method-customizing
initrd_table_override
--
2.20.1
^ permalink raw reply related [flat|nested] 39+ messages in thread* [PATCH v2 14/24] acpi doc: convert acpi/dsd/graph.txt to rst format
2019-03-29 0:11 [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree Changbin Du
` (12 preceding siblings ...)
2019-03-29 0:11 ` [PATCH v2 13/24] acpi doc: convert acpi/acpi-lid.txt " Changbin Du
@ 2019-03-29 0:11 ` Changbin Du
2019-03-29 0:11 ` [PATCH v2 15/24] acpi doc: convert acpi/dsd/data-node-references.txt " Changbin Du
` (10 subsequent siblings)
24 siblings, 0 replies; 39+ messages in thread
From: Changbin Du @ 2019-03-29 0:11 UTC (permalink / raw)
To: Jonathan Corbet
Cc: rjw, lenb, linux-acpi, linux-kernel, linux-doc, Changbin Du
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
.../acpi/dsd/{graph.txt => graph.rst} | 157 +++++++++---------
Documentation/acpi/index.rst | 1 +
2 files changed, 81 insertions(+), 77 deletions(-)
rename Documentation/acpi/dsd/{graph.txt => graph.rst} (56%)
diff --git a/Documentation/acpi/dsd/graph.txt b/Documentation/acpi/dsd/graph.rst
similarity index 56%
rename from Documentation/acpi/dsd/graph.txt
rename to Documentation/acpi/dsd/graph.rst
index b9ce910781dc..e0baed35b037 100644
--- a/Documentation/acpi/dsd/graph.txt
+++ b/Documentation/acpi/dsd/graph.rst
@@ -1,8 +1,11 @@
-Graphs
+.. SPDX-License-Identifier: GPL-2.0
+======
+Graphs
+======
_DSD
-----
+====
_DSD (Device Specific Data) [7] is a predefined ACPI device
configuration object that can be used to convey information on
@@ -30,7 +33,7 @@ hierarchical data extension array on each depth.
Ports and endpoints
--------------------
+===================
The port and endpoint concepts are very similar to those in Devicetree
[3]. A port represents an interface in a device, and an endpoint
@@ -38,9 +41,9 @@ represents a connection to that interface.
All port nodes are located under the device's "_DSD" node in the hierarchical
data extension tree. The data extension related to each port node must begin
-with "port" and must be followed by the "@" character and the number of the port
-as its key. The target object it refers to should be called "PRTX", where "X" is
-the number of the port. An example of such a package would be:
+with "port" and must be followed by the "@" character and the number of the
+port as its key. The target object it refers to should be called "PRTX", where
+"X" is the number of the port. An example of such a package would be::
Package() { "port@4", PRT4 }
@@ -49,7 +52,7 @@ data extension key of the endpoint nodes must begin with
"endpoint" and must be followed by the "@" character and the number of the
endpoint. The object it refers to should be called "EPXY", where "X" is the
number of the port and "Y" is the number of the endpoint. An example of such a
-package would be:
+package would be::
Package() { "endpoint@0", EP40 }
@@ -62,85 +65,85 @@ of that port shall be zero. Similarly, if a port may only have a single
endpoint, the number of that endpoint shall be zero.
The endpoint reference uses property extension with "remote-endpoint" property
-name followed by a reference in the same package. Such references consist of the
+name followed by a reference in the same package. Such references consist of
the remote device reference, the first package entry of the port data extension
reference under the device and finally the first package entry of the endpoint
-data extension reference under the port. Individual references thus appear as:
+data extension reference under the port. Individual references thus appear as::
Package() { device, "port@X", "endpoint@Y" }
-In the above example, "X" is the number of the port and "Y" is the number of the
-endpoint.
+In the above example, "X" is the number of the port and "Y" is the number of
+the endpoint.
The references to endpoints must be always done both ways, to the
remote endpoint and back from the referred remote endpoint node.
-A simple example of this is show below:
+A simple example of this is show below::
Scope (\_SB.PCI0.I2C2)
{
- Device (CAM0)
- {
- Name (_DSD, Package () {
- ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
- Package () {
- Package () { "compatible", Package () { "nokia,smia" } },
- },
- ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
- Package () {
- Package () { "port@0", PRT0 },
- }
- })
- Name (PRT0, Package() {
- ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
- Package () {
- Package () { "reg", 0 },
- },
- ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
- Package () {
- Package () { "endpoint@0", EP00 },
- }
- })
- Name (EP00, Package() {
- ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
- Package () {
- Package () { "reg", 0 },
- Package () { "remote-endpoint", Package() { \_SB.PCI0.ISP, "port@4", "endpoint@0" } },
- }
- })
- }
+ Device (CAM0)
+ {
+ Name (_DSD, Package () {
+ ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+ Package () {
+ Package () { "compatible", Package () { "nokia,smia" } },
+ },
+ ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
+ Package () {
+ Package () { "port@0", PRT0 },
+ }
+ })
+ Name (PRT0, Package() {
+ ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+ Package () {
+ Package () { "reg", 0 },
+ },
+ ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
+ Package () {
+ Package () { "endpoint@0", EP00 },
+ }
+ })
+ Name (EP00, Package() {
+ ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+ Package () {
+ Package () { "reg", 0 },
+ Package () { "remote-endpoint", Package() { \_SB.PCI0.ISP, "port@4", "endpoint@0" } },
+ }
+ })
+ }
}
Scope (\_SB.PCI0)
{
- Device (ISP)
- {
- Name (_DSD, Package () {
- ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
- Package () {
- Package () { "port@4", PRT4 },
- }
- })
-
- Name (PRT4, Package() {
- ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
- Package () {
- Package () { "reg", 4 }, /* CSI-2 port number */
- },
- ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
- Package () {
- Package () { "endpoint@0", EP40 },
- }
- })
-
- Name (EP40, Package() {
- ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
- Package () {
- Package () { "reg", 0 },
- Package () { "remote-endpoint", Package () { \_SB.PCI0.I2C2.CAM0, "port@0", "endpoint@0" } },
- }
- })
- }
+ Device (ISP)
+ {
+ Name (_DSD, Package () {
+ ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
+ Package () {
+ Package () { "port@4", PRT4 },
+ }
+ })
+
+ Name (PRT4, Package() {
+ ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+ Package () {
+ Package () { "reg", 4 }, /* CSI-2 port number */
+ },
+ ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
+ Package () {
+ Package () { "endpoint@0", EP40 },
+ }
+ })
+
+ Name (EP40, Package() {
+ ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+ Package () {
+ Package () { "reg", 0 },
+ Package () { "remote-endpoint", Package () { \_SB.PCI0.I2C2.CAM0, "port@0", "endpoint@0" } },
+ }
+ })
+ }
}
Here, the port 0 of the "CAM0" device is connected to the port 4 of
@@ -148,27 +151,27 @@ the "ISP" device and vice versa.
References
-----------
+==========
[1] _DSD (Device Specific Data) Implementation Guide.
- <URL:http://www.uefi.org/sites/default/files/resources/_DSD-implementation-guide-toplevel-1_1.htm>,
+ http://www.uefi.org/sites/default/files/resources/_DSD-implementation-guide-toplevel-1_1.htm,
referenced 2016-10-03.
-[2] Devicetree. <URL:http://www.devicetree.org>, referenced 2016-10-03.
+[2] Devicetree. http://www.devicetree.org, referenced 2016-10-03.
[3] Documentation/devicetree/bindings/graph.txt
[4] Device Properties UUID For _DSD.
- <URL:http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>,
+ http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf,
referenced 2016-10-04.
[5] Hierarchical Data Extension UUID For _DSD.
- <URL:http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>,
+ http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf,
referenced 2016-10-04.
[6] Advanced Configuration and Power Interface Specification.
- <URL:http://www.uefi.org/sites/default/files/resources/ACPI_6_1.pdf>,
+ http://www.uefi.org/sites/default/files/resources/ACPI_6_1.pdf,
referenced 2016-10-04.
[7] _DSD Device Properties Usage Rules.
- Documentation/acpi/DSD-properties-rules.txt
+ :doc:`../DSD-properties-rules`
diff --git a/Documentation/acpi/index.rst b/Documentation/acpi/index.rst
index 909f12833692..40a628b2be21 100644
--- a/Documentation/acpi/index.rst
+++ b/Documentation/acpi/index.rst
@@ -9,6 +9,7 @@ Linux ACPI (Advanced Configuration and Power Interface)
linuxized-acpica
namespace
+ dsd/graph
enumeration
osi
DSD-properties-rules
--
2.20.1
^ permalink raw reply related [flat|nested] 39+ messages in thread* [PATCH v2 15/24] acpi doc: convert acpi/dsd/data-node-references.txt to rst format
2019-03-29 0:11 [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree Changbin Du
` (13 preceding siblings ...)
2019-03-29 0:11 ` [PATCH v2 14/24] acpi doc: convert acpi/dsd/graph.txt " Changbin Du
@ 2019-03-29 0:11 ` Changbin Du
2019-03-29 0:11 ` [PATCH v2 16/24] acpi doc: convert acpi/debug.txt " Changbin Du
` (9 subsequent siblings)
24 siblings, 0 replies; 39+ messages in thread
From: Changbin Du @ 2019-03-29 0:11 UTC (permalink / raw)
To: Jonathan Corbet
Cc: rjw, lenb, linux-acpi, linux-kernel, linux-doc, Changbin Du
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
...eferences.txt => data-node-references.rst} | 28 +++++++++++--------
Documentation/acpi/index.rst | 1 +
2 files changed, 17 insertions(+), 12 deletions(-)
rename Documentation/acpi/dsd/{data-node-references.txt => data-node-references.rst} (79%)
diff --git a/Documentation/acpi/dsd/data-node-references.txt b/Documentation/acpi/dsd/data-node-references.rst
similarity index 79%
rename from Documentation/acpi/dsd/data-node-references.txt
rename to Documentation/acpi/dsd/data-node-references.rst
index c3871565c8cf..79c5368eaecf 100644
--- a/Documentation/acpi/dsd/data-node-references.txt
+++ b/Documentation/acpi/dsd/data-node-references.rst
@@ -1,9 +1,12 @@
-Copyright (C) 2018 Intel Corporation
-Author: Sakari Ailus <sakari.ailus@linux.intel.com>
-
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
+===================================
Referencing hierarchical data nodes
------------------------------------
+===================================
+
+:Copyright: |copy| 2018 Intel Corporation
+:Author: Sakari Ailus <sakari.ailus@linux.intel.com>
ACPI in general allows referring to device objects in the tree only.
Hierarchical data extension nodes may not be referred to directly, hence this
@@ -28,13 +31,14 @@ extension key.
Example
--------
+=======
- In the ASL snippet below, the "reference" _DSD property [2] contains a
- device object reference to DEV0 and under that device object, a
- hierarchical data extension key "node@1" referring to the NOD1 object
- and lastly, a hierarchical data extension key "anothernode" referring to
- the ANOD object which is also the final target node of the reference.
+In the ASL snippet below, the "reference" _DSD property [2] contains a
+device object reference to DEV0 and under that device object, a
+hierarchical data extension key "node@1" referring to the NOD1 object
+and lastly, a hierarchical data extension key "anothernode" referring to
+the ANOD object which is also the final target node of the reference.
+::
Device (DEV0)
{
@@ -75,10 +79,10 @@ Example
})
}
-Please also see a graph example in graph.txt .
+Please also see a graph example in :doc:`graph`.
References
-----------
+==========
[1] Hierarchical Data Extension UUID For _DSD.
<URL:http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>,
diff --git a/Documentation/acpi/index.rst b/Documentation/acpi/index.rst
index 40a628b2be21..b680fb13f445 100644
--- a/Documentation/acpi/index.rst
+++ b/Documentation/acpi/index.rst
@@ -10,6 +10,7 @@ Linux ACPI (Advanced Configuration and Power Interface)
linuxized-acpica
namespace
dsd/graph
+ dsd/data-node-references
enumeration
osi
DSD-properties-rules
--
2.20.1
^ permalink raw reply related [flat|nested] 39+ messages in thread* [PATCH v2 16/24] acpi doc: convert acpi/debug.txt to rst format
2019-03-29 0:11 [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree Changbin Du
` (14 preceding siblings ...)
2019-03-29 0:11 ` [PATCH v2 15/24] acpi doc: convert acpi/dsd/data-node-references.txt " Changbin Du
@ 2019-03-29 0:11 ` Changbin Du
2019-03-29 0:11 ` [PATCH v2 17/24] acpi doc: convert acpi/method-tracing.txt " Changbin Du
` (8 subsequent siblings)
24 siblings, 0 replies; 39+ messages in thread
From: Changbin Du @ 2019-03-29 0:11 UTC (permalink / raw)
To: Jonathan Corbet
Cc: rjw, lenb, linux-acpi, linux-kernel, linux-doc, Changbin Du
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
Documentation/acpi/{debug.txt => debug.rst} | 31 +++++++++++----------
Documentation/acpi/index.rst | 1 +
2 files changed, 18 insertions(+), 14 deletions(-)
rename Documentation/acpi/{debug.txt => debug.rst} (91%)
diff --git a/Documentation/acpi/debug.txt b/Documentation/acpi/debug.rst
similarity index 91%
rename from Documentation/acpi/debug.txt
rename to Documentation/acpi/debug.rst
index 65bf47c46b6d..1a152dd1d765 100644
--- a/Documentation/acpi/debug.txt
+++ b/Documentation/acpi/debug.rst
@@ -1,18 +1,21 @@
- ACPI Debug Output
+.. SPDX-License-Identifier: GPL-2.0
+=================
+ACPI Debug Output
+=================
The ACPI CA, the Linux ACPI core, and some ACPI drivers can generate debug
output. This document describes how to use this facility.
Compile-time configuration
---------------------------
+==========================
ACPI debug output is globally enabled by CONFIG_ACPI_DEBUG. If this config
option is turned off, the debug messages are not even built into the
kernel.
Boot- and run-time configuration
---------------------------------
+================================
When CONFIG_ACPI_DEBUG=y, you can select the component and level of messages
you're interested in. At boot-time, use the acpi.debug_layer and
@@ -21,7 +24,7 @@ debug_layer and debug_level files in /sys/module/acpi/parameters/ to control
the debug messages.
debug_layer (component)
------------------------
+=======================
The "debug_layer" is a mask that selects components of interest, e.g., a
specific driver or part of the ACPI interpreter. To build the debug_layer
@@ -33,7 +36,7 @@ to /sys/module/acpi/parameters/debug_layer.
The possible components are defined in include/acpi/acoutput.h and
include/acpi/acpi_drivers.h. Reading /sys/module/acpi/parameters/debug_layer
-shows the supported mask values, currently these:
+shows the supported mask values, currently these::
ACPI_UTILITIES 0x00000001
ACPI_HARDWARE 0x00000002
@@ -65,7 +68,7 @@ shows the supported mask values, currently these:
ACPI_PROCESSOR_COMPONENT 0x20000000
debug_level
------------
+===========
The "debug_level" is a mask that selects different types of messages, e.g.,
those related to initialization, method execution, informational messages, etc.
@@ -81,7 +84,7 @@ to /sys/module/acpi/parameters/debug_level.
The possible levels are defined in include/acpi/acoutput.h. Reading
/sys/module/acpi/parameters/debug_level shows the supported mask values,
-currently these:
+currently these::
ACPI_LV_INIT 0x00000001
ACPI_LV_DEBUG_OBJECT 0x00000002
@@ -113,9 +116,9 @@ currently these:
ACPI_LV_EVENTS 0x80000000
Examples
---------
+========
-For example, drivers/acpi/bus.c contains this:
+For example, drivers/acpi/bus.c contains this::
#define _COMPONENT ACPI_BUS_COMPONENT
...
@@ -127,22 +130,22 @@ statement uses ACPI_DB_INFO, which is macro based on the ACPI_LV_INFO
definition.)
Enable all AML "Debug" output (stores to the Debug object while interpreting
-AML) during boot:
+AML) during boot::
acpi.debug_layer=0xffffffff acpi.debug_level=0x2
-Enable PCI and PCI interrupt routing debug messages:
+Enable PCI and PCI interrupt routing debug messages::
acpi.debug_layer=0x400000 acpi.debug_level=0x4
-Enable all ACPI hardware-related messages:
+Enable all ACPI hardware-related messages::
acpi.debug_layer=0x2 acpi.debug_level=0xffffffff
-Enable all ACPI_DB_INFO messages after boot:
+Enable all ACPI_DB_INFO messages after boot::
# echo 0x4 > /sys/module/acpi/parameters/debug_level
-Show all valid component values:
+Show all valid component values::
# cat /sys/module/acpi/parameters/debug_layer
diff --git a/Documentation/acpi/index.rst b/Documentation/acpi/index.rst
index b680fb13f445..ee0000a396e4 100644
--- a/Documentation/acpi/index.rst
+++ b/Documentation/acpi/index.rst
@@ -21,3 +21,4 @@ Linux ACPI (Advanced Configuration and Power Interface)
method-customizing
initrd_table_override
dsdt-override
+ debug
--
2.20.1
^ permalink raw reply related [flat|nested] 39+ messages in thread* [PATCH v2 17/24] acpi doc: convert acpi/method-tracing.txt to rst format
2019-03-29 0:11 [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree Changbin Du
` (15 preceding siblings ...)
2019-03-29 0:11 ` [PATCH v2 16/24] acpi doc: convert acpi/debug.txt " Changbin Du
@ 2019-03-29 0:11 ` Changbin Du
2019-03-29 0:11 ` [PATCH v2 18/24] acpi doc: convert acpi/aml-debugger.txt " Changbin Du
` (7 subsequent siblings)
24 siblings, 0 replies; 39+ messages in thread
From: Changbin Du @ 2019-03-29 0:11 UTC (permalink / raw)
To: Jonathan Corbet
Cc: rjw, lenb, linux-acpi, linux-kernel, linux-doc, Changbin Du
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
Documentation/acpi/index.rst | 1 +
Documentation/acpi/method-tracing.rst | 225 ++++++++++++++++++++++++++
Documentation/acpi/method-tracing.txt | 192 ----------------------
3 files changed, 226 insertions(+), 192 deletions(-)
create mode 100644 Documentation/acpi/method-tracing.rst
delete mode 100644 Documentation/acpi/method-tracing.txt
diff --git a/Documentation/acpi/index.rst b/Documentation/acpi/index.rst
index ee0000a396e4..a3c5ddb15a0e 100644
--- a/Documentation/acpi/index.rst
+++ b/Documentation/acpi/index.rst
@@ -22,3 +22,4 @@ Linux ACPI (Advanced Configuration and Power Interface)
initrd_table_override
dsdt-override
debug
+ method-tracing
diff --git a/Documentation/acpi/method-tracing.rst b/Documentation/acpi/method-tracing.rst
new file mode 100644
index 000000000000..7a997ba168d7
--- /dev/null
+++ b/Documentation/acpi/method-tracing.rst
@@ -0,0 +1,225 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
+
+=====================
+ACPICA Trace Facility
+=====================
+
+:Copyright: |copy| 2015, Intel Corporation
+:Author: Lv Zheng <lv.zheng@intel.com>
+
+
+:Abstract: This document describes the functions and the interfaces of the
+ method tracing facility.
+
+1. Functionalities and usage examples
+=====================================
+
+ACPICA provides method tracing capability. And two functions are
+currently implemented using this capability.
+
+Log reducer
+--------------
+
+ACPICA subsystem provides debugging outputs when CONFIG_ACPI_DEBUG is
+enabled. The debugging messages which are deployed via
+ACPI_DEBUG_PRINT() macro can be reduced at 2 levels - per-component
+level (known as debug layer, configured via
+/sys/module/acpi/parameters/debug_layer) and per-type level (known as
+debug level, configured via /sys/module/acpi/parameters/debug_level).
+
+But when the particular layer/level is applied to the control method
+evaluations, the quantity of the debugging outputs may still be too
+large to be put into the kernel log buffer. The idea thus is worked out
+to only enable the particular debug layer/level (normally more detailed)
+logs when the control method evaluation is started, and disable the
+detailed logging when the control method evaluation is stopped.
+
+The following command examples illustrate the usage of the "log reducer"
+functionality:
+
+a. Filter out the debug layer/level matched logs when control methods
+ are being evaluated::
+
+ # cd /sys/module/acpi/parameters
+ # echo "0xXXXXXXXX" > trace_debug_layer
+ # echo "0xYYYYYYYY" > trace_debug_level
+ # echo "enable" > trace_state
+
+b. Filter out the debug layer/level matched logs when the specified
+ control method is being evaluated::
+
+ # cd /sys/module/acpi/parameters
+ # echo "0xXXXXXXXX" > trace_debug_layer
+ # echo "0xYYYYYYYY" > trace_debug_level
+ # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
+ # echo "method" > /sys/module/acpi/parameters/trace_state
+
+c. Filter out the debug layer/level matched logs when the specified
+ control method is being evaluated for the first time::
+
+ # cd /sys/module/acpi/parameters
+ # echo "0xXXXXXXXX" > trace_debug_layer
+ # echo "0xYYYYYYYY" > trace_debug_level
+ # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
+ # echo "method-once" > /sys/module/acpi/parameters/trace_state
+
+Where:
+ 0xXXXXXXXX/0xYYYYYYYY
+ Refer to Documentation/acpi/debug.txt for possible debug layer/level
+ masking values.
+ \PPPP.AAAA.TTTT.HHHH
+ Full path of a control method that can be found in the ACPI namespace.
+ It needn't be an entry of a control method evaluation.
+
+AML tracer
+-------------
+
+There are special log entries added by the method tracing facility at
+the "trace points" the AML interpreter starts/stops to execute a control
+method, or an AML opcode. Note that the format of the log entries are
+subject to change::
+
+ [ 0.186427] exdebug-0398 ex_trace_point : Method Begin [0xf58394d8:\_SB.PCI0.LPCB.ECOK] execution.
+ [ 0.186630] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905c88:If] execution.
+ [ 0.186820] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905cc0:LEqual] execution.
+ [ 0.187010] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905a20:-NamePath-] execution.
+ [ 0.187214] exdebug-0398 ex_trace_point : Opcode End [0xf5905a20:-NamePath-] execution.
+ [ 0.187407] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905f60:One] execution.
+ [ 0.187594] exdebug-0398 ex_trace_point : Opcode End [0xf5905f60:One] execution.
+ [ 0.187789] exdebug-0398 ex_trace_point : Opcode End [0xf5905cc0:LEqual] execution.
+ [ 0.187980] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905cc0:Return] execution.
+ [ 0.188146] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905f60:One] execution.
+ [ 0.188334] exdebug-0398 ex_trace_point : Opcode End [0xf5905f60:One] execution.
+ [ 0.188524] exdebug-0398 ex_trace_point : Opcode End [0xf5905cc0:Return] execution.
+ [ 0.188712] exdebug-0398 ex_trace_point : Opcode End [0xf5905c88:If] execution.
+ [ 0.188903] exdebug-0398 ex_trace_point : Method End [0xf58394d8:\_SB.PCI0.LPCB.ECOK] execution.
+
+Developers can utilize these special log entries to track the AML
+interpretion, thus can aid issue debugging and performance tuning. Note
+that, as the "AML tracer" logs are implemented via ACPI_DEBUG_PRINT()
+macro, CONFIG_ACPI_DEBUG is also required to be enabled for enabling
+"AML tracer" logs.
+
+The following command examples illustrate the usage of the "AML tracer"
+functionality:
+
+a. Filter out the method start/stop "AML tracer" logs when control
+ methods are being evaluated::
+
+ # cd /sys/module/acpi/parameters
+ # echo "0x80" > trace_debug_layer
+ # echo "0x10" > trace_debug_level
+ # echo "enable" > trace_state
+
+b. Filter out the method start/stop "AML tracer" when the specified
+ control method is being evaluated::
+
+ # cd /sys/module/acpi/parameters
+ # echo "0x80" > trace_debug_layer
+ # echo "0x10" > trace_debug_level
+ # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
+ # echo "method" > trace_state
+
+c. Filter out the method start/stop "AML tracer" logs when the specified
+ control method is being evaluated for the first time::
+
+ # cd /sys/module/acpi/parameters
+ # echo "0x80" > trace_debug_layer
+ # echo "0x10" > trace_debug_level
+ # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
+ # echo "method-once" > trace_state
+
+d. Filter out the method/opcode start/stop "AML tracer" when the
+ specified control method is being evaluated::
+
+ # cd /sys/module/acpi/parameters
+ # echo "0x80" > trace_debug_layer
+ # echo "0x10" > trace_debug_level
+ # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
+ # echo "opcode" > trace_state
+
+e. Filter out the method/opcode start/stop "AML tracer" when the
+ specified control method is being evaluated for the first time::
+
+ # cd /sys/module/acpi/parameters
+ # echo "0x80" > trace_debug_layer
+ # echo "0x10" > trace_debug_level
+ # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
+ # echo "opcode-opcode" > trace_state
+
+Note that all above method tracing facility related module parameters can
+be used as the boot parameters, for example::
+
+ acpi.trace_debug_layer=0x80 acpi.trace_debug_level=0x10 \
+ acpi.trace_method_name=\_SB.LID0._LID acpi.trace_state=opcode-once
+
+2. Interface descriptions
+=========================
+
+All method tracing functions can be configured via ACPI module
+parameters that are accessible at /sys/module/acpi/parameters/:
+
+trace_method_name
+The full path of the AML method that the user wants to trace.
+Note that the full path shouldn't contain the trailing "_"s in its
+name segments but may contain "\" to form an absolute path.
+
+trace_debug_layer
+The temporary debug_layer used when the tracing feature is enabled.
+Using ACPI_EXECUTER (0x80) by default, which is the debug_layer
+used to match all "AML tracer" logs.
+
+trace_debug_level
+The temporary debug_level used when the tracing feature is enabled.
+Using ACPI_LV_TRACE_POINT (0x10) by default, which is the
+debug_level used to match all "AML tracer" logs.
+
+trace_state
+The status of the tracing feature.
+Users can enable/disable this debug tracing feature by executing
+the following command::
+
+ # echo string > /sys/module/acpi/parameters/trace_state
+
+Where "string" should be one of the following:
+
+"disable"
+ Disable the method tracing feature.
+"enable"
+ Enable the method tracing feature.
+ ACPICA debugging messages matching
+ "trace_debug_layer/trace_debug_level" during any method
+ execution will be logged.
+"method"
+ Enable the method tracing feature.
+ ACPICA debugging messages matching
+ "trace_debug_layer/trace_debug_level" during method execution
+ of "trace_method_name" will be logged.
+"method-once"
+ Enable the method tracing feature.
+ ACPICA debugging messages matching
+ "trace_debug_layer/trace_debug_level" during method execution
+ of "trace_method_name" will be logged only once.
+"opcode"
+ Enable the method tracing feature.
+ ACPICA debugging messages matching
+ "trace_debug_layer/trace_debug_level" during method/opcode
+ execution of "trace_method_name" will be logged.
+"opcode-once"
+ Enable the method tracing feature.
+ ACPICA debugging messages matching
+ "trace_debug_layer/trace_debug_level" during method/opcode
+ execution of "trace_method_name" will be logged only once.
+
+Note that, the difference between the "enable" and other feature
+enabling options are:
+
+1. When "enable" is specified, since
+ "trace_debug_layer/trace_debug_level" shall apply to all control
+ method evaluations, after configuring "trace_state" to "enable",
+ "trace_method_name" will be reset to NULL.
+2. When "method/opcode" is specified, if
+ "trace_method_name" is NULL when "trace_state" is configured to
+ these options, the "trace_debug_layer/trace_debug_level" will
+ apply to all control method evaluations.
diff --git a/Documentation/acpi/method-tracing.txt b/Documentation/acpi/method-tracing.txt
deleted file mode 100644
index 0aba14c8f459..000000000000
--- a/Documentation/acpi/method-tracing.txt
+++ /dev/null
@@ -1,192 +0,0 @@
-ACPICA Trace Facility
-
-Copyright (C) 2015, Intel Corporation
-Author: Lv Zheng <lv.zheng@intel.com>
-
-
-Abstract:
-
-This document describes the functions and the interfaces of the method
-tracing facility.
-
-1. Functionalities and usage examples:
-
- ACPICA provides method tracing capability. And two functions are
- currently implemented using this capability.
-
- A. Log reducer
- ACPICA subsystem provides debugging outputs when CONFIG_ACPI_DEBUG is
- enabled. The debugging messages which are deployed via
- ACPI_DEBUG_PRINT() macro can be reduced at 2 levels - per-component
- level (known as debug layer, configured via
- /sys/module/acpi/parameters/debug_layer) and per-type level (known as
- debug level, configured via /sys/module/acpi/parameters/debug_level).
-
- But when the particular layer/level is applied to the control method
- evaluations, the quantity of the debugging outputs may still be too
- large to be put into the kernel log buffer. The idea thus is worked out
- to only enable the particular debug layer/level (normally more detailed)
- logs when the control method evaluation is started, and disable the
- detailed logging when the control method evaluation is stopped.
-
- The following command examples illustrate the usage of the "log reducer"
- functionality:
- a. Filter out the debug layer/level matched logs when control methods
- are being evaluated:
- # cd /sys/module/acpi/parameters
- # echo "0xXXXXXXXX" > trace_debug_layer
- # echo "0xYYYYYYYY" > trace_debug_level
- # echo "enable" > trace_state
- b. Filter out the debug layer/level matched logs when the specified
- control method is being evaluated:
- # cd /sys/module/acpi/parameters
- # echo "0xXXXXXXXX" > trace_debug_layer
- # echo "0xYYYYYYYY" > trace_debug_level
- # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
- # echo "method" > /sys/module/acpi/parameters/trace_state
- c. Filter out the debug layer/level matched logs when the specified
- control method is being evaluated for the first time:
- # cd /sys/module/acpi/parameters
- # echo "0xXXXXXXXX" > trace_debug_layer
- # echo "0xYYYYYYYY" > trace_debug_level
- # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
- # echo "method-once" > /sys/module/acpi/parameters/trace_state
- Where:
- 0xXXXXXXXX/0xYYYYYYYY: Refer to Documentation/acpi/debug.txt for
- possible debug layer/level masking values.
- \PPPP.AAAA.TTTT.HHHH: Full path of a control method that can be found
- in the ACPI namespace. It needn't be an entry
- of a control method evaluation.
-
- B. AML tracer
-
- There are special log entries added by the method tracing facility at
- the "trace points" the AML interpreter starts/stops to execute a control
- method, or an AML opcode. Note that the format of the log entries are
- subject to change:
- [ 0.186427] exdebug-0398 ex_trace_point : Method Begin [0xf58394d8:\_SB.PCI0.LPCB.ECOK] execution.
- [ 0.186630] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905c88:If] execution.
- [ 0.186820] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905cc0:LEqual] execution.
- [ 0.187010] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905a20:-NamePath-] execution.
- [ 0.187214] exdebug-0398 ex_trace_point : Opcode End [0xf5905a20:-NamePath-] execution.
- [ 0.187407] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905f60:One] execution.
- [ 0.187594] exdebug-0398 ex_trace_point : Opcode End [0xf5905f60:One] execution.
- [ 0.187789] exdebug-0398 ex_trace_point : Opcode End [0xf5905cc0:LEqual] execution.
- [ 0.187980] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905cc0:Return] execution.
- [ 0.188146] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905f60:One] execution.
- [ 0.188334] exdebug-0398 ex_trace_point : Opcode End [0xf5905f60:One] execution.
- [ 0.188524] exdebug-0398 ex_trace_point : Opcode End [0xf5905cc0:Return] execution.
- [ 0.188712] exdebug-0398 ex_trace_point : Opcode End [0xf5905c88:If] execution.
- [ 0.188903] exdebug-0398 ex_trace_point : Method End [0xf58394d8:\_SB.PCI0.LPCB.ECOK] execution.
-
- Developers can utilize these special log entries to track the AML
- interpretion, thus can aid issue debugging and performance tuning. Note
- that, as the "AML tracer" logs are implemented via ACPI_DEBUG_PRINT()
- macro, CONFIG_ACPI_DEBUG is also required to be enabled for enabling
- "AML tracer" logs.
-
- The following command examples illustrate the usage of the "AML tracer"
- functionality:
- a. Filter out the method start/stop "AML tracer" logs when control
- methods are being evaluated:
- # cd /sys/module/acpi/parameters
- # echo "0x80" > trace_debug_layer
- # echo "0x10" > trace_debug_level
- # echo "enable" > trace_state
- b. Filter out the method start/stop "AML tracer" when the specified
- control method is being evaluated:
- # cd /sys/module/acpi/parameters
- # echo "0x80" > trace_debug_layer
- # echo "0x10" > trace_debug_level
- # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
- # echo "method" > trace_state
- c. Filter out the method start/stop "AML tracer" logs when the specified
- control method is being evaluated for the first time:
- # cd /sys/module/acpi/parameters
- # echo "0x80" > trace_debug_layer
- # echo "0x10" > trace_debug_level
- # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
- # echo "method-once" > trace_state
- d. Filter out the method/opcode start/stop "AML tracer" when the
- specified control method is being evaluated:
- # cd /sys/module/acpi/parameters
- # echo "0x80" > trace_debug_layer
- # echo "0x10" > trace_debug_level
- # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
- # echo "opcode" > trace_state
- e. Filter out the method/opcode start/stop "AML tracer" when the
- specified control method is being evaluated for the first time:
- # cd /sys/module/acpi/parameters
- # echo "0x80" > trace_debug_layer
- # echo "0x10" > trace_debug_level
- # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
- # echo "opcode-opcode" > trace_state
-
- Note that all above method tracing facility related module parameters can
- be used as the boot parameters, for example:
- acpi.trace_debug_layer=0x80 acpi.trace_debug_level=0x10 \
- acpi.trace_method_name=\_SB.LID0._LID acpi.trace_state=opcode-once
-
-2. Interface descriptions:
-
- All method tracing functions can be configured via ACPI module
- parameters that are accessible at /sys/module/acpi/parameters/:
-
- trace_method_name
- The full path of the AML method that the user wants to trace.
- Note that the full path shouldn't contain the trailing "_"s in its
- name segments but may contain "\" to form an absolute path.
-
- trace_debug_layer
- The temporary debug_layer used when the tracing feature is enabled.
- Using ACPI_EXECUTER (0x80) by default, which is the debug_layer
- used to match all "AML tracer" logs.
-
- trace_debug_level
- The temporary debug_level used when the tracing feature is enabled.
- Using ACPI_LV_TRACE_POINT (0x10) by default, which is the
- debug_level used to match all "AML tracer" logs.
-
- trace_state
- The status of the tracing feature.
- Users can enable/disable this debug tracing feature by executing
- the following command:
- # echo string > /sys/module/acpi/parameters/trace_state
- Where "string" should be one of the following:
- "disable"
- Disable the method tracing feature.
- "enable"
- Enable the method tracing feature.
- ACPICA debugging messages matching
- "trace_debug_layer/trace_debug_level" during any method
- execution will be logged.
- "method"
- Enable the method tracing feature.
- ACPICA debugging messages matching
- "trace_debug_layer/trace_debug_level" during method execution
- of "trace_method_name" will be logged.
- "method-once"
- Enable the method tracing feature.
- ACPICA debugging messages matching
- "trace_debug_layer/trace_debug_level" during method execution
- of "trace_method_name" will be logged only once.
- "opcode"
- Enable the method tracing feature.
- ACPICA debugging messages matching
- "trace_debug_layer/trace_debug_level" during method/opcode
- execution of "trace_method_name" will be logged.
- "opcode-once"
- Enable the method tracing feature.
- ACPICA debugging messages matching
- "trace_debug_layer/trace_debug_level" during method/opcode
- execution of "trace_method_name" will be logged only once.
- Note that, the difference between the "enable" and other feature
- enabling options are:
- 1. When "enable" is specified, since
- "trace_debug_layer/trace_debug_level" shall apply to all control
- method evaluations, after configuring "trace_state" to "enable",
- "trace_method_name" will be reset to NULL.
- 2. When "method/opcode" is specified, if
- "trace_method_name" is NULL when "trace_state" is configured to
- these options, the "trace_debug_layer/trace_debug_level" will
- apply to all control method evaluations.
--
2.20.1
^ permalink raw reply related [flat|nested] 39+ messages in thread* [PATCH v2 18/24] acpi doc: convert acpi/aml-debugger.txt to rst format
2019-03-29 0:11 [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree Changbin Du
` (16 preceding siblings ...)
2019-03-29 0:11 ` [PATCH v2 17/24] acpi doc: convert acpi/method-tracing.txt " Changbin Du
@ 2019-03-29 0:11 ` Changbin Du
2019-03-29 0:11 ` [PATCH v2 19/24] acpi doc: convert acpi/apei/output_format.txt " Changbin Du
` (6 subsequent siblings)
24 siblings, 0 replies; 39+ messages in thread
From: Changbin Du @ 2019-03-29 0:11 UTC (permalink / raw)
To: Jonathan Corbet
Cc: rjw, lenb, linux-acpi, linux-kernel, linux-doc, Changbin Du
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
Documentation/acpi/aml-debugger.rst | 75 +++++++++++++++++++++++++++++
Documentation/acpi/aml-debugger.txt | 66 -------------------------
Documentation/acpi/index.rst | 1 +
3 files changed, 76 insertions(+), 66 deletions(-)
create mode 100644 Documentation/acpi/aml-debugger.rst
delete mode 100644 Documentation/acpi/aml-debugger.txt
diff --git a/Documentation/acpi/aml-debugger.rst b/Documentation/acpi/aml-debugger.rst
new file mode 100644
index 000000000000..a889d43bc6c5
--- /dev/null
+++ b/Documentation/acpi/aml-debugger.rst
@@ -0,0 +1,75 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
+
+================
+The AML Debugger
+================
+
+:Copyright: |copy| 2016, Intel Corporation
+:Author: Lv Zheng <lv.zheng@intel.com>
+
+
+This document describes the usage of the AML debugger embedded in the Linux
+kernel.
+
+1. Build the debugger
+=====================
+
+The following kernel configuration items are required to enable the AML
+debugger interface from the Linux kernel::
+
+ CONFIG_ACPI_DEBUGGER=y
+ CONFIG_ACPI_DEBUGGER_USER=m
+
+The userspace utilities can be built from the kernel source tree using
+the following commands::
+
+ $ cd tools
+ $ make acpi
+
+The resultant userspace tool binary is then located at::
+
+ tools/power/acpi/acpidbg
+
+It can be installed to system directories by running "make install" (as a
+sufficiently privileged user).
+
+2. Start the userspace debugger interface
+=========================================
+
+After booting the kernel with the debugger built-in, the debugger can be
+started by using the following commands::
+
+ # mount -t debugfs none /sys/kernel/debug
+ # modprobe acpi_dbg
+ # tools/power/acpi/acpidbg
+
+That spawns the interactive AML debugger environment where you can execute
+debugger commands.
+
+The commands are documented in the "ACPICA Overview and Programmer Reference"
+that can be downloaded from
+
+https://acpica.org/documentation
+
+The detailed debugger commands reference is located in Chapter 12 "ACPICA
+Debugger Reference". The "help" command can be used for a quick reference.
+
+3. Stop the userspace debugger interface
+========================================
+
+The interactive debugger interface can be closed by pressing Ctrl+C or using
+the "quit" or "exit" commands. When finished, unload the module with::
+
+ # rmmod acpi_dbg
+
+The module unloading may fail if there is an acpidbg instance running.
+
+4. Run the debugger in a script
+===============================
+
+It may be useful to run the AML debugger in a test script. "acpidbg" supports
+this in a special "batch" mode. For example, the following command outputs
+the entire ACPI namespace::
+
+ # acpidbg -b "namespace"
diff --git a/Documentation/acpi/aml-debugger.txt b/Documentation/acpi/aml-debugger.txt
deleted file mode 100644
index 75ebeb64ab29..000000000000
--- a/Documentation/acpi/aml-debugger.txt
+++ /dev/null
@@ -1,66 +0,0 @@
-The AML Debugger
-
-Copyright (C) 2016, Intel Corporation
-Author: Lv Zheng <lv.zheng@intel.com>
-
-
-This document describes the usage of the AML debugger embedded in the Linux
-kernel.
-
-1. Build the debugger
-
- The following kernel configuration items are required to enable the AML
- debugger interface from the Linux kernel:
-
- CONFIG_ACPI_DEBUGGER=y
- CONFIG_ACPI_DEBUGGER_USER=m
-
- The userspace utilities can be built from the kernel source tree using
- the following commands:
-
- $ cd tools
- $ make acpi
-
- The resultant userspace tool binary is then located at:
-
- tools/power/acpi/acpidbg
-
- It can be installed to system directories by running "make install" (as a
- sufficiently privileged user).
-
-2. Start the userspace debugger interface
-
- After booting the kernel with the debugger built-in, the debugger can be
- started by using the following commands:
-
- # mount -t debugfs none /sys/kernel/debug
- # modprobe acpi_dbg
- # tools/power/acpi/acpidbg
-
- That spawns the interactive AML debugger environment where you can execute
- debugger commands.
-
- The commands are documented in the "ACPICA Overview and Programmer Reference"
- that can be downloaded from
-
- https://acpica.org/documentation
-
- The detailed debugger commands reference is located in Chapter 12 "ACPICA
- Debugger Reference". The "help" command can be used for a quick reference.
-
-3. Stop the userspace debugger interface
-
- The interactive debugger interface can be closed by pressing Ctrl+C or using
- the "quit" or "exit" commands. When finished, unload the module with:
-
- # rmmod acpi_dbg
-
- The module unloading may fail if there is an acpidbg instance running.
-
-4. Run the debugger in a script
-
- It may be useful to run the AML debugger in a test script. "acpidbg" supports
- this in a special "batch" mode. For example, the following command outputs
- the entire ACPI namespace:
-
- # acpidbg -b "namespace"
diff --git a/Documentation/acpi/index.rst b/Documentation/acpi/index.rst
index a3c5ddb15a0e..a1c7ad451099 100644
--- a/Documentation/acpi/index.rst
+++ b/Documentation/acpi/index.rst
@@ -23,3 +23,4 @@ Linux ACPI (Advanced Configuration and Power Interface)
dsdt-override
debug
method-tracing
+ aml-debugger
--
2.20.1
^ permalink raw reply related [flat|nested] 39+ messages in thread* [PATCH v2 19/24] acpi doc: convert acpi/apei/output_format.txt to rst format
2019-03-29 0:11 [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree Changbin Du
` (17 preceding siblings ...)
2019-03-29 0:11 ` [PATCH v2 18/24] acpi doc: convert acpi/aml-debugger.txt " Changbin Du
@ 2019-03-29 0:11 ` Changbin Du
2019-03-29 0:11 ` [PATCH v2 20/24] acpi doc: convert acpi/apei/einj.txt " Changbin Du
` (5 subsequent siblings)
24 siblings, 0 replies; 39+ messages in thread
From: Changbin Du @ 2019-03-29 0:11 UTC (permalink / raw)
To: Jonathan Corbet
Cc: rjw, lenb, linux-acpi, linux-kernel, linux-doc, Changbin Du
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
Documentation/acpi/apei/output_format.rst | 150 ++++++++++++++++++++++
Documentation/acpi/apei/output_format.txt | 147 ---------------------
Documentation/acpi/index.rst | 1 +
3 files changed, 151 insertions(+), 147 deletions(-)
create mode 100644 Documentation/acpi/apei/output_format.rst
delete mode 100644 Documentation/acpi/apei/output_format.txt
diff --git a/Documentation/acpi/apei/output_format.rst b/Documentation/acpi/apei/output_format.rst
new file mode 100644
index 000000000000..c2e7ebddb529
--- /dev/null
+++ b/Documentation/acpi/apei/output_format.rst
@@ -0,0 +1,150 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==================
+APEI output format
+==================
+
+APEI uses printk as hardware error reporting interface, the output
+format is as follow::
+
+ <error record> :=
+ APEI generic hardware error status
+ severity: <integer>, <severity string>
+ section: <integer>, severity: <integer>, <severity string>
+ flags: <integer>
+ <section flags strings>
+ fru_id: <uuid string>
+ fru_text: <string>
+ section_type: <section type string>
+ <section data>
+
+ <severity string>* := recoverable | fatal | corrected | info
+
+ <section flags strings># :=
+ [primary][, containment warning][, reset][, threshold exceeded]\
+ [, resource not accessible][, latent error]
+
+ <section type string> := generic processor error | memory error | \
+ PCIe error | unknown, <uuid string>
+
+ <section data> :=
+ <generic processor section data> | <memory section data> | \
+ <pcie section data> | <null>
+
+ <generic processor section data> :=
+ [processor_type: <integer>, <proc type string>]
+ [processor_isa: <integer>, <proc isa string>]
+ [error_type: <integer>
+ <proc error type strings>]
+ [operation: <integer>, <proc operation string>]
+ [flags: <integer>
+ <proc flags strings>]
+ [level: <integer>]
+ [version_info: <integer>]
+ [processor_id: <integer>]
+ [target_address: <integer>]
+ [requestor_id: <integer>]
+ [responder_id: <integer>]
+ [IP: <integer>]
+
+ <proc type string>* := IA32/X64 | IA64
+
+ <proc isa string>* := IA32 | IA64 | X64
+
+ <processor error type strings># :=
+ [cache error][, TLB error][, bus error][, micro-architectural error]
+
+ <proc operation string>* := unknown or generic | data read | data write | \
+ instruction execution
+
+ <proc flags strings># :=
+ [restartable][, precise IP][, overflow][, corrected]
+
+ <memory section data> :=
+ [error_status: <integer>]
+ [physical_address: <integer>]
+ [physical_address_mask: <integer>]
+ [node: <integer>]
+ [card: <integer>]
+ [module: <integer>]
+ [bank: <integer>]
+ [device: <integer>]
+ [row: <integer>]
+ [column: <integer>]
+ [bit_position: <integer>]
+ [requestor_id: <integer>]
+ [responder_id: <integer>]
+ [target_id: <integer>]
+ [error_type: <integer>, <mem error type string>]
+
+ <mem error type string>* :=
+ unknown | no error | single-bit ECC | multi-bit ECC | \
+ single-symbol chipkill ECC | multi-symbol chipkill ECC | master abort | \
+ target abort | parity error | watchdog timeout | invalid address | \
+ mirror Broken | memory sparing | scrub corrected error | \
+ scrub uncorrected error
+
+ <pcie section data> :=
+ [port_type: <integer>, <pcie port type string>]
+ [version: <integer>.<integer>]
+ [command: <integer>, status: <integer>]
+ [device_id: <integer>:<integer>:<integer>.<integer>
+ slot: <integer>
+ secondary_bus: <integer>
+ vendor_id: <integer>, device_id: <integer>
+ class_code: <integer>]
+ [serial number: <integer>, <integer>]
+ [bridge: secondary_status: <integer>, control: <integer>]
+ [aer_status: <integer>, aer_mask: <integer>
+ <aer status string>
+ [aer_uncor_severity: <integer>]
+ aer_layer=<aer layer string>, aer_agent=<aer agent string>
+ aer_tlp_header: <integer> <integer> <integer> <integer>]
+
+ <pcie port type string>* := PCIe end point | legacy PCI end point | \
+ unknown | unknown | root port | upstream switch port | \
+ downstream switch port | PCIe to PCI/PCI-X bridge | \
+ PCI/PCI-X to PCIe bridge | root complex integrated endpoint device | \
+ root complex event collector
+
+ if section severity is fatal or recoverable
+ <aer status string># :=
+ unknown | unknown | unknown | unknown | Data Link Protocol | \
+ unknown | unknown | unknown | unknown | unknown | unknown | unknown | \
+ Poisoned TLP | Flow Control Protocol | Completion Timeout | \
+ Completer Abort | Unexpected Completion | Receiver Overflow | \
+ Malformed TLP | ECRC | Unsupported Request
+ else
+ <aer status string># :=
+ Receiver Error | unknown | unknown | unknown | unknown | unknown | \
+ Bad TLP | Bad DLLP | RELAY_NUM Rollover | unknown | unknown | unknown | \
+ Replay Timer Timeout | Advisory Non-Fatal
+ fi
+
+ <aer layer string> :=
+ Physical Layer | Data Link Layer | Transaction Layer
+
+ <aer agent string> :=
+ Receiver ID | Requester ID | Completer ID | Transmitter ID
+
+Where, [] designate corresponding content is optional
+
+All <field string> description with * has the following format::
+
+ field: <integer>, <field string>
+
+Where value of <integer> should be the position of "string" in <field
+string> description. Otherwise, <field string> will be "unknown".
+
+All <field strings> description with # has the following format::
+
+ field: <integer>
+ <field strings>
+
+Where each string in <fields strings> corresponding to one set bit of
+<integer>. The bit position is the position of "string" in <field
+strings> description.
+
+For more detailed explanation of every field, please refer to UEFI
+specification version 2.3 or later, section Appendix N: Common
+Platform Error Record.
diff --git a/Documentation/acpi/apei/output_format.txt b/Documentation/acpi/apei/output_format.txt
deleted file mode 100644
index 0c49c197c47a..000000000000
--- a/Documentation/acpi/apei/output_format.txt
+++ /dev/null
@@ -1,147 +0,0 @@
- APEI output format
- ~~~~~~~~~~~~~~~~~~
-
-APEI uses printk as hardware error reporting interface, the output
-format is as follow.
-
-<error record> :=
-APEI generic hardware error status
-severity: <integer>, <severity string>
-section: <integer>, severity: <integer>, <severity string>
-flags: <integer>
-<section flags strings>
-fru_id: <uuid string>
-fru_text: <string>
-section_type: <section type string>
-<section data>
-
-<severity string>* := recoverable | fatal | corrected | info
-
-<section flags strings># :=
-[primary][, containment warning][, reset][, threshold exceeded]\
-[, resource not accessible][, latent error]
-
-<section type string> := generic processor error | memory error | \
-PCIe error | unknown, <uuid string>
-
-<section data> :=
-<generic processor section data> | <memory section data> | \
-<pcie section data> | <null>
-
-<generic processor section data> :=
-[processor_type: <integer>, <proc type string>]
-[processor_isa: <integer>, <proc isa string>]
-[error_type: <integer>
-<proc error type strings>]
-[operation: <integer>, <proc operation string>]
-[flags: <integer>
-<proc flags strings>]
-[level: <integer>]
-[version_info: <integer>]
-[processor_id: <integer>]
-[target_address: <integer>]
-[requestor_id: <integer>]
-[responder_id: <integer>]
-[IP: <integer>]
-
-<proc type string>* := IA32/X64 | IA64
-
-<proc isa string>* := IA32 | IA64 | X64
-
-<processor error type strings># :=
-[cache error][, TLB error][, bus error][, micro-architectural error]
-
-<proc operation string>* := unknown or generic | data read | data write | \
-instruction execution
-
-<proc flags strings># :=
-[restartable][, precise IP][, overflow][, corrected]
-
-<memory section data> :=
-[error_status: <integer>]
-[physical_address: <integer>]
-[physical_address_mask: <integer>]
-[node: <integer>]
-[card: <integer>]
-[module: <integer>]
-[bank: <integer>]
-[device: <integer>]
-[row: <integer>]
-[column: <integer>]
-[bit_position: <integer>]
-[requestor_id: <integer>]
-[responder_id: <integer>]
-[target_id: <integer>]
-[error_type: <integer>, <mem error type string>]
-
-<mem error type string>* :=
-unknown | no error | single-bit ECC | multi-bit ECC | \
-single-symbol chipkill ECC | multi-symbol chipkill ECC | master abort | \
-target abort | parity error | watchdog timeout | invalid address | \
-mirror Broken | memory sparing | scrub corrected error | \
-scrub uncorrected error
-
-<pcie section data> :=
-[port_type: <integer>, <pcie port type string>]
-[version: <integer>.<integer>]
-[command: <integer>, status: <integer>]
-[device_id: <integer>:<integer>:<integer>.<integer>
-slot: <integer>
-secondary_bus: <integer>
-vendor_id: <integer>, device_id: <integer>
-class_code: <integer>]
-[serial number: <integer>, <integer>]
-[bridge: secondary_status: <integer>, control: <integer>]
-[aer_status: <integer>, aer_mask: <integer>
-<aer status string>
-[aer_uncor_severity: <integer>]
-aer_layer=<aer layer string>, aer_agent=<aer agent string>
-aer_tlp_header: <integer> <integer> <integer> <integer>]
-
-<pcie port type string>* := PCIe end point | legacy PCI end point | \
-unknown | unknown | root port | upstream switch port | \
-downstream switch port | PCIe to PCI/PCI-X bridge | \
-PCI/PCI-X to PCIe bridge | root complex integrated endpoint device | \
-root complex event collector
-
-if section severity is fatal or recoverable
-<aer status string># :=
-unknown | unknown | unknown | unknown | Data Link Protocol | \
-unknown | unknown | unknown | unknown | unknown | unknown | unknown | \
-Poisoned TLP | Flow Control Protocol | Completion Timeout | \
-Completer Abort | Unexpected Completion | Receiver Overflow | \
-Malformed TLP | ECRC | Unsupported Request
-else
-<aer status string># :=
-Receiver Error | unknown | unknown | unknown | unknown | unknown | \
-Bad TLP | Bad DLLP | RELAY_NUM Rollover | unknown | unknown | unknown | \
-Replay Timer Timeout | Advisory Non-Fatal
-fi
-
-<aer layer string> :=
-Physical Layer | Data Link Layer | Transaction Layer
-
-<aer agent string> :=
-Receiver ID | Requester ID | Completer ID | Transmitter ID
-
-Where, [] designate corresponding content is optional
-
-All <field string> description with * has the following format:
-
-field: <integer>, <field string>
-
-Where value of <integer> should be the position of "string" in <field
-string> description. Otherwise, <field string> will be "unknown".
-
-All <field strings> description with # has the following format:
-
-field: <integer>
-<field strings>
-
-Where each string in <fields strings> corresponding to one set bit of
-<integer>. The bit position is the position of "string" in <field
-strings> description.
-
-For more detailed explanation of every field, please refer to UEFI
-specification version 2.3 or later, section Appendix N: Common
-Platform Error Record.
diff --git a/Documentation/acpi/index.rst b/Documentation/acpi/index.rst
index a1c7ad451099..39c647386fe2 100644
--- a/Documentation/acpi/index.rst
+++ b/Documentation/acpi/index.rst
@@ -24,3 +24,4 @@ Linux ACPI (Advanced Configuration and Power Interface)
debug
method-tracing
aml-debugger
+ apei/output_format
--
2.20.1
^ permalink raw reply related [flat|nested] 39+ messages in thread* [PATCH v2 20/24] acpi doc: convert acpi/apei/einj.txt to rst format
2019-03-29 0:11 [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree Changbin Du
` (18 preceding siblings ...)
2019-03-29 0:11 ` [PATCH v2 19/24] acpi doc: convert acpi/apei/output_format.txt " Changbin Du
@ 2019-03-29 0:11 ` Changbin Du
2019-03-29 0:11 ` [PATCH v2 21/24] acpi doc: convert acpi/cppc_sysfs.txt " Changbin Du
` (4 subsequent siblings)
24 siblings, 0 replies; 39+ messages in thread
From: Changbin Du @ 2019-03-29 0:11 UTC (permalink / raw)
To: Jonathan Corbet
Cc: rjw, lenb, linux-acpi, linux-kernel, linux-doc, Changbin Du
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
.../acpi/apei/{einj.txt => einj.rst} | 98 ++++++++++---------
Documentation/acpi/index.rst | 1 +
2 files changed, 53 insertions(+), 46 deletions(-)
rename Documentation/acpi/apei/{einj.txt => einj.rst} (67%)
diff --git a/Documentation/acpi/apei/einj.txt b/Documentation/acpi/apei/einj.rst
similarity index 67%
rename from Documentation/acpi/apei/einj.txt
rename to Documentation/acpi/apei/einj.rst
index e550c8b98139..d85e2667155c 100644
--- a/Documentation/acpi/apei/einj.txt
+++ b/Documentation/acpi/apei/einj.rst
@@ -1,13 +1,16 @@
- APEI Error INJection
- ~~~~~~~~~~~~~~~~~~~~
+.. SPDX-License-Identifier: GPL-2.0
+
+====================
+APEI Error INJection
+====================
EINJ provides a hardware error injection mechanism. It is very useful
for debugging and testing APEI and RAS features in general.
You need to check whether your BIOS supports EINJ first. For that, look
-for early boot messages similar to this one:
+for early boot messages similar to this one::
-ACPI: EINJ 0x000000007370A000 000150 (v01 INTEL 00000001 INTL 00000001)
+ ACPI: EINJ 0x000000007370A000 000150 (v01 INTEL 00000001 INTL 00000001)
which shows that the BIOS is exposing an EINJ table - it is the
mechanism through which the injection is done.
@@ -23,11 +26,11 @@ order to see the APEI,EINJ,... functionality supported and exposed by
the BIOS menu.
To use EINJ, make sure the following are options enabled in your kernel
-configuration:
+configuration::
-CONFIG_DEBUG_FS
-CONFIG_ACPI_APEI
-CONFIG_ACPI_APEI_EINJ
+ CONFIG_DEBUG_FS
+ CONFIG_ACPI_APEI
+ CONFIG_ACPI_APEI_EINJ
The EINJ user interface is in <debugfs mount point>/apei/einj.
@@ -35,22 +38,22 @@ The following files belong to it:
- available_error_type
- This file shows which error types are supported:
-
- Error Type Value Error Description
- ================ =================
- 0x00000001 Processor Correctable
- 0x00000002 Processor Uncorrectable non-fatal
- 0x00000004 Processor Uncorrectable fatal
- 0x00000008 Memory Correctable
- 0x00000010 Memory Uncorrectable non-fatal
- 0x00000020 Memory Uncorrectable fatal
- 0x00000040 PCI Express Correctable
- 0x00000080 PCI Express Uncorrectable fatal
- 0x00000100 PCI Express Uncorrectable non-fatal
- 0x00000200 Platform Correctable
- 0x00000400 Platform Uncorrectable non-fatal
- 0x00000800 Platform Uncorrectable fatal
+ This file shows which error types are supported::
+
+ Error Type Value Error Description
+ ================ =================
+ 0x00000001 Processor Correctable
+ 0x00000002 Processor Uncorrectable non-fatal
+ 0x00000004 Processor Uncorrectable fatal
+ 0x00000008 Memory Correctable
+ 0x00000010 Memory Uncorrectable non-fatal
+ 0x00000020 Memory Uncorrectable fatal
+ 0x00000040 PCI Express Correctable
+ 0x00000080 PCI Express Uncorrectable fatal
+ 0x00000100 PCI Express Uncorrectable non-fatal
+ 0x00000200 Platform Correctable
+ 0x00000400 Platform Uncorrectable non-fatal
+ 0x00000800 Platform Uncorrectable fatal
The format of the file contents are as above, except present are only
the available error types.
@@ -73,9 +76,12 @@ The following files belong to it:
injection. Value is a bitmask as specified in ACPI5.0 spec for the
SET_ERROR_TYPE_WITH_ADDRESS data structure:
- Bit 0 - Processor APIC field valid (see param3 below).
- Bit 1 - Memory address and mask valid (param1 and param2).
- Bit 2 - PCIe (seg,bus,dev,fn) valid (see param4 below).
+ Bit 0
+ Processor APIC field valid (see param3 below).
+ Bit 1
+ Memory address and mask valid (param1 and param2).
+ Bit 2
+ PCIe (seg,bus,dev,fn) valid (see param4 below).
If set to zero, legacy behavior is mimicked where the type of
injection specifies just one bit set, and param1 is multiplexed.
@@ -121,7 +127,7 @@ BIOS versions based on the ACPI 5.0 specification have more control over
the target of the injection. For processor-related errors (type 0x1, 0x2
and 0x4), you can set flags to 0x3 (param3 for bit 0, and param1 and
param2 for bit 1) so that you have more information added to the error
-signature being injected. The actual data passed is this:
+signature being injected. The actual data passed is this::
memory_address = param1;
memory_address_range = param2;
@@ -131,7 +137,7 @@ signature being injected. The actual data passed is this:
For memory errors (type 0x8, 0x10 and 0x20) the address is set using
param1 with a mask in param2 (0x0 is equivalent to all ones). For PCI
express errors (type 0x40, 0x80 and 0x100) the segment, bus, device and
-function are specified using param1:
+function are specified using param1::
31 24 23 16 15 11 10 8 7 0
+-------------------------------------------------+
@@ -152,26 +158,26 @@ documentation for details (and expect changes to this API if vendors
creativity in using this feature expands beyond our expectations).
-An error injection example:
+An error injection example::
-# cd /sys/kernel/debug/apei/einj
-# cat available_error_type # See which errors can be injected
-0x00000002 Processor Uncorrectable non-fatal
-0x00000008 Memory Correctable
-0x00000010 Memory Uncorrectable non-fatal
-# echo 0x12345000 > param1 # Set memory address for injection
-# echo $((-1 << 12)) > param2 # Mask 0xfffffffffffff000 - anywhere in this page
-# echo 0x8 > error_type # Choose correctable memory error
-# echo 1 > error_inject # Inject now
+ # cd /sys/kernel/debug/apei/einj
+ # cat available_error_type # See which errors can be injected
+ 0x00000002 Processor Uncorrectable non-fatal
+ 0x00000008 Memory Correctable
+ 0x00000010 Memory Uncorrectable non-fatal
+ # echo 0x12345000 > param1 # Set memory address for injection
+ # echo $((-1 << 12)) > param2 # Mask 0xfffffffffffff000 - anywhere in this page
+ # echo 0x8 > error_type # Choose correctable memory error
+ # echo 1 > error_inject # Inject now
-You should see something like this in dmesg:
+You should see something like this in dmesg::
-[22715.830801] EDAC sbridge MC3: HANDLING MCE MEMORY ERROR
-[22715.834759] EDAC sbridge MC3: CPU 0: Machine Check Event: 0 Bank 7: 8c00004000010090
-[22715.834759] EDAC sbridge MC3: TSC 0
-[22715.834759] EDAC sbridge MC3: ADDR 12345000 EDAC sbridge MC3: MISC 144780c86
-[22715.834759] EDAC sbridge MC3: PROCESSOR 0:306e7 TIME 1422553404 SOCKET 0 APIC 0
-[22716.616173] EDAC MC3: 1 CE memory read error on CPU_SrcID#0_Channel#0_DIMM#0 (channel:0 slot:0 page:0x12345 offset:0x0 grain:32 syndrome:0x0 - area:DRAM err_code:0001:0090 socket:0 channel_mask:1 rank:0)
+ [22715.830801] EDAC sbridge MC3: HANDLING MCE MEMORY ERROR
+ [22715.834759] EDAC sbridge MC3: CPU 0: Machine Check Event: 0 Bank 7: 8c00004000010090
+ [22715.834759] EDAC sbridge MC3: TSC 0
+ [22715.834759] EDAC sbridge MC3: ADDR 12345000 EDAC sbridge MC3: MISC 144780c86
+ [22715.834759] EDAC sbridge MC3: PROCESSOR 0:306e7 TIME 1422553404 SOCKET 0 APIC 0
+ [22716.616173] EDAC MC3: 1 CE memory read error on CPU_SrcID#0_Channel#0_DIMM#0 (channel:0 slot:0 page:0x12345 offset:0x0 grain:32 syndrome:0x0 - area:DRAM err_code:0001:0090 socket:0 channel_mask:1 rank:0)
For more information about EINJ, please refer to ACPI specification
version 4.0, section 17.5 and ACPI 5.0, section 18.6.
diff --git a/Documentation/acpi/index.rst b/Documentation/acpi/index.rst
index 39c647386fe2..bdd82615fef6 100644
--- a/Documentation/acpi/index.rst
+++ b/Documentation/acpi/index.rst
@@ -25,3 +25,4 @@ Linux ACPI (Advanced Configuration and Power Interface)
method-tracing
aml-debugger
apei/output_format
+ apei/einj
--
2.20.1
^ permalink raw reply related [flat|nested] 39+ messages in thread* [PATCH v2 21/24] acpi doc: convert acpi/cppc_sysfs.txt to rst format
2019-03-29 0:11 [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree Changbin Du
` (19 preceding siblings ...)
2019-03-29 0:11 ` [PATCH v2 20/24] acpi doc: convert acpi/apei/einj.txt " Changbin Du
@ 2019-03-29 0:11 ` Changbin Du
2019-03-29 0:11 ` [PATCH v2 22/24] acpi doc: convert acpi/lpit.txt " Changbin Du
` (3 subsequent siblings)
24 siblings, 0 replies; 39+ messages in thread
From: Changbin Du @ 2019-03-29 0:11 UTC (permalink / raw)
To: Jonathan Corbet
Cc: rjw, lenb, linux-acpi, linux-kernel, linux-doc, Changbin Du
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
.../acpi/{cppc_sysfs.txt => cppc_sysfs.rst} | 71 ++++++++++---------
Documentation/acpi/index.rst | 1 +
2 files changed, 40 insertions(+), 32 deletions(-)
rename Documentation/acpi/{cppc_sysfs.txt => cppc_sysfs.rst} (51%)
diff --git a/Documentation/acpi/cppc_sysfs.txt b/Documentation/acpi/cppc_sysfs.rst
similarity index 51%
rename from Documentation/acpi/cppc_sysfs.txt
rename to Documentation/acpi/cppc_sysfs.rst
index f20fb445135d..a4b99afbe331 100644
--- a/Documentation/acpi/cppc_sysfs.txt
+++ b/Documentation/acpi/cppc_sysfs.rst
@@ -1,5 +1,11 @@
+.. SPDX-License-Identifier: GPL-2.0
- Collaborative Processor Performance Control (CPPC)
+==================================================
+Collaborative Processor Performance Control (CPPC)
+==================================================
+
+CPPC
+====
CPPC defined in the ACPI spec describes a mechanism for the OS to manage the
performance of a logical processor on a contigious and abstract performance
@@ -10,31 +16,28 @@ For more details on CPPC please refer to the ACPI specification at:
http://uefi.org/specifications
-Some of the CPPC registers are exposed via sysfs under:
-
-/sys/devices/system/cpu/cpuX/acpi_cppc/
-
-for each cpu X
+Some of the CPPC registers are exposed via sysfs under::
---------------------------------------------------------------------------------
+ /sys/devices/system/cpu/cpuX/acpi_cppc/
-$ ls -lR /sys/devices/system/cpu/cpu0/acpi_cppc/
-/sys/devices/system/cpu/cpu0/acpi_cppc/:
-total 0
--r--r--r-- 1 root root 65536 Mar 5 19:38 feedback_ctrs
--r--r--r-- 1 root root 65536 Mar 5 19:38 highest_perf
--r--r--r-- 1 root root 65536 Mar 5 19:38 lowest_freq
--r--r--r-- 1 root root 65536 Mar 5 19:38 lowest_nonlinear_perf
--r--r--r-- 1 root root 65536 Mar 5 19:38 lowest_perf
--r--r--r-- 1 root root 65536 Mar 5 19:38 nominal_freq
--r--r--r-- 1 root root 65536 Mar 5 19:38 nominal_perf
--r--r--r-- 1 root root 65536 Mar 5 19:38 reference_perf
--r--r--r-- 1 root root 65536 Mar 5 19:38 wraparound_time
+for each cpu X::
---------------------------------------------------------------------------------
+ $ ls -lR /sys/devices/system/cpu/cpu0/acpi_cppc/
+ /sys/devices/system/cpu/cpu0/acpi_cppc/:
+ total 0
+ -r--r--r-- 1 root root 65536 Mar 5 19:38 feedback_ctrs
+ -r--r--r-- 1 root root 65536 Mar 5 19:38 highest_perf
+ -r--r--r-- 1 root root 65536 Mar 5 19:38 lowest_freq
+ -r--r--r-- 1 root root 65536 Mar 5 19:38 lowest_nonlinear_perf
+ -r--r--r-- 1 root root 65536 Mar 5 19:38 lowest_perf
+ -r--r--r-- 1 root root 65536 Mar 5 19:38 nominal_freq
+ -r--r--r-- 1 root root 65536 Mar 5 19:38 nominal_perf
+ -r--r--r-- 1 root root 65536 Mar 5 19:38 reference_perf
+ -r--r--r-- 1 root root 65536 Mar 5 19:38 wraparound_time
* highest_perf : Highest performance of this processor (abstract scale).
-* nominal_perf : Highest sustained performance of this processor (abstract scale).
+* nominal_perf : Highest sustained performance of this processor
+ (abstract scale).
* lowest_nonlinear_perf : Lowest performance of this processor with nonlinear
power savings (abstract scale).
* lowest_perf : Lowest performance of this processor (abstract scale).
@@ -48,22 +51,26 @@ total 0
* feedback_ctrs : Includes both Reference and delivered performance counter.
Reference counter ticks up proportional to processor's reference performance.
Delivered counter ticks up proportional to processor's delivered performance.
-* wraparound_time: Minimum time for the feedback counters to wraparound (seconds).
+* wraparound_time: Minimum time for the feedback counters to wraparound
+ (seconds).
* reference_perf : Performance level at which reference performance counter
accumulates (abstract scale).
---------------------------------------------------------------------------------
- Computing Average Delivered Performance
+Computing Average Delivered Performance
+=======================================
+
+Below describes the steps to compute the average performance delivered by
+taking two different snapshots of feedback counters at time T1 and T2.
+
+ T1: Read feedback_ctrs as fbc_t1
+ Wait or run some workload
-Below describes the steps to compute the average performance delivered by taking
-two different snapshots of feedback counters at time T1 and T2.
+ T2: Read feedback_ctrs as fbc_t2
-T1: Read feedback_ctrs as fbc_t1
- Wait or run some workload
-T2: Read feedback_ctrs as fbc_t2
+::
-delivered_counter_delta = fbc_t2[del] - fbc_t1[del]
-reference_counter_delta = fbc_t2[ref] - fbc_t1[ref]
+ delivered_counter_delta = fbc_t2[del] - fbc_t1[del]
+ reference_counter_delta = fbc_t2[ref] - fbc_t1[ref]
-delivered_perf = (refernce_perf x delivered_counter_delta) / reference_counter_delta
+ delivered_perf = (refernce_perf x delivered_counter_delta) / reference_counter_delta
diff --git a/Documentation/acpi/index.rst b/Documentation/acpi/index.rst
index bdd82615fef6..91aeed814ea9 100644
--- a/Documentation/acpi/index.rst
+++ b/Documentation/acpi/index.rst
@@ -26,3 +26,4 @@ Linux ACPI (Advanced Configuration and Power Interface)
aml-debugger
apei/output_format
apei/einj
+ cppc_sysfs
--
2.20.1
^ permalink raw reply related [flat|nested] 39+ messages in thread* [PATCH v2 22/24] acpi doc: convert acpi/lpit.txt to rst format
2019-03-29 0:11 [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree Changbin Du
` (20 preceding siblings ...)
2019-03-29 0:11 ` [PATCH v2 21/24] acpi doc: convert acpi/cppc_sysfs.txt " Changbin Du
@ 2019-03-29 0:11 ` Changbin Du
2019-03-29 0:11 ` [PATCH v2 23/24] acpi doc: convert acpi/ssdt-overlays.txt " Changbin Du
` (2 subsequent siblings)
24 siblings, 0 replies; 39+ messages in thread
From: Changbin Du @ 2019-03-29 0:11 UTC (permalink / raw)
To: Jonathan Corbet
Cc: rjw, lenb, linux-acpi, linux-kernel, linux-doc, Changbin Du
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
Documentation/acpi/index.rst | 1 +
Documentation/acpi/{lpit.txt => lpit.rst} | 18 +++++++++++++-----
2 files changed, 14 insertions(+), 5 deletions(-)
rename Documentation/acpi/{lpit.txt => lpit.rst} (68%)
diff --git a/Documentation/acpi/index.rst b/Documentation/acpi/index.rst
index 91aeed814ea9..664807949272 100644
--- a/Documentation/acpi/index.rst
+++ b/Documentation/acpi/index.rst
@@ -27,3 +27,4 @@ Linux ACPI (Advanced Configuration and Power Interface)
apei/output_format
apei/einj
cppc_sysfs
+ lpit
diff --git a/Documentation/acpi/lpit.txt b/Documentation/acpi/lpit.rst
similarity index 68%
rename from Documentation/acpi/lpit.txt
rename to Documentation/acpi/lpit.rst
index b426398d2e97..aca928fab027 100644
--- a/Documentation/acpi/lpit.txt
+++ b/Documentation/acpi/lpit.rst
@@ -1,3 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===========================
+Low Power Idle Table (LPIT)
+===========================
+
To enumerate platform Low Power Idle states, Intel platforms are using
“Low Power Idle Table” (LPIT). More details about this table can be
downloaded from:
@@ -8,13 +14,15 @@ Residencies for each low power state can be read via FFH
On platforms supporting S0ix sleep states, there can be two types of
residencies:
-- CPU PKG C10 (Read via FFH interface)
-- Platform Controller Hub (PCH) SLP_S0 (Read via memory mapped interface)
+
+ - CPU PKG C10 (Read via FFH interface)
+ - Platform Controller Hub (PCH) SLP_S0 (Read via memory mapped interface)
The following attributes are added dynamically to the cpuidle
-sysfs attribute group:
- /sys/devices/system/cpu/cpuidle/low_power_idle_cpu_residency_us
- /sys/devices/system/cpu/cpuidle/low_power_idle_system_residency_us
+sysfs attribute group::
+
+ /sys/devices/system/cpu/cpuidle/low_power_idle_cpu_residency_us
+ /sys/devices/system/cpu/cpuidle/low_power_idle_system_residency_us
The "low_power_idle_cpu_residency_us" attribute shows time spent
by the CPU package in PKG C10
--
2.20.1
^ permalink raw reply related [flat|nested] 39+ messages in thread* [PATCH v2 23/24] acpi doc: convert acpi/ssdt-overlays.txt to rst format
2019-03-29 0:11 [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree Changbin Du
` (21 preceding siblings ...)
2019-03-29 0:11 ` [PATCH v2 22/24] acpi doc: convert acpi/lpit.txt " Changbin Du
@ 2019-03-29 0:11 ` Changbin Du
2019-03-29 0:11 ` [PATCH v2 24/24] acpi doc: convert acpi/video_extension.txt " Changbin Du
2019-03-30 9:41 ` [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree Rafael J. Wysocki
24 siblings, 0 replies; 39+ messages in thread
From: Changbin Du @ 2019-03-29 0:11 UTC (permalink / raw)
To: Jonathan Corbet
Cc: rjw, lenb, linux-acpi, linux-kernel, linux-doc, Changbin Du
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
Documentation/acpi/index.rst | 1 +
Documentation/acpi/ssdt-overlays.rst | 180 +++++++++++++++++++++++++++
Documentation/acpi/ssdt-overlays.txt | 172 -------------------------
3 files changed, 181 insertions(+), 172 deletions(-)
create mode 100644 Documentation/acpi/ssdt-overlays.rst
delete mode 100644 Documentation/acpi/ssdt-overlays.txt
diff --git a/Documentation/acpi/index.rst b/Documentation/acpi/index.rst
index 664807949272..d856ba53da4d 100644
--- a/Documentation/acpi/index.rst
+++ b/Documentation/acpi/index.rst
@@ -28,3 +28,4 @@ Linux ACPI (Advanced Configuration and Power Interface)
apei/einj
cppc_sysfs
lpit
+ ssdt-overlays
diff --git a/Documentation/acpi/ssdt-overlays.rst b/Documentation/acpi/ssdt-overlays.rst
new file mode 100644
index 000000000000..da37455f96c9
--- /dev/null
+++ b/Documentation/acpi/ssdt-overlays.rst
@@ -0,0 +1,180 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=============
+SSDT Overlays
+=============
+
+In order to support ACPI open-ended hardware configurations (e.g. development
+boards) we need a way to augment the ACPI configuration provided by the firmware
+image. A common example is connecting sensors on I2C / SPI buses on development
+boards.
+
+Although this can be accomplished by creating a kernel platform driver or
+recompiling the firmware image with updated ACPI tables, neither is practical:
+the former proliferates board specific kernel code while the latter requires
+access to firmware tools which are often not publicly available.
+
+Because ACPI supports external references in AML code a more practical
+way to augment firmware ACPI configuration is by dynamically loading
+user defined SSDT tables that contain the board specific information.
+
+For example, to enumerate a Bosch BMA222E accelerometer on the I2C bus of the
+Minnowboard MAX development board exposed via the LSE connector [1], the
+following ASL code can be used::
+
+ DefinitionBlock ("minnowmax.aml", "SSDT", 1, "Vendor", "Accel", 0x00000003)
+ {
+ External (\_SB.I2C6, DeviceObj)
+
+ Scope (\_SB.I2C6)
+ {
+ Device (STAC)
+ {
+ Name (_ADR, Zero)
+ Name (_HID, "BMA222E")
+
+ Method (_CRS, 0, Serialized)
+ {
+ Name (RBUF, ResourceTemplate ()
+ {
+ I2cSerialBus (0x0018, ControllerInitiated, 0x00061A80,
+ AddressingMode7Bit, "\\_SB.I2C6", 0x00,
+ ResourceConsumer, ,)
+ GpioInt (Edge, ActiveHigh, Exclusive, PullDown, 0x0000,
+ "\\_SB.GPO2", 0x00, ResourceConsumer, , )
+ { // Pin list
+ 0
+ }
+ })
+ Return (RBUF)
+ }
+ }
+ }
+ }
+
+which can then be compiled to AML binary format::
+
+ $ iasl minnowmax.asl
+
+ Intel ACPI Component Architecture
+ ASL Optimizing Compiler version 20140214-64 [Mar 29 2014]
+ Copyright (c) 2000 - 2014 Intel Corporation
+
+ ASL Input: minnomax.asl - 30 lines, 614 bytes, 7 keywords
+ AML Output: minnowmax.aml - 165 bytes, 6 named objects, 1 executable opcodes
+
+[1] http://wiki.minnowboard.org/MinnowBoard_MAX#Low_Speed_Expansion_Connector_.28Top.29
+
+The resulting AML code can then be loaded by the kernel using one of the methods
+below.
+
+Loading ACPI SSDTs from initrd
+==============================
+
+This option allows loading of user defined SSDTs from initrd and it is useful
+when the system does not support EFI or when there is not enough EFI storage.
+
+It works in a similar way with initrd based ACPI tables override/upgrade: SSDT
+aml code must be placed in the first, uncompressed, initrd under the
+"kernel/firmware/acpi" path. Multiple files can be used and this will translate
+in loading multiple tables. Only SSDT and OEM tables are allowed. See
+initrd_table_override.txt for more details.
+
+Here is an example::
+
+ # Add the raw ACPI tables to an uncompressed cpio archive.
+ # They must be put into a /kernel/firmware/acpi directory inside the
+ # cpio archive.
+ # The uncompressed cpio archive must be the first.
+ # Other, typically compressed cpio archives, must be
+ # concatenated on top of the uncompressed one.
+ mkdir -p kernel/firmware/acpi
+ cp ssdt.aml kernel/firmware/acpi
+
+ # Create the uncompressed cpio archive and concatenate the original initrd
+ # on top:
+ find kernel | cpio -H newc --create > /boot/instrumented_initrd
+ cat /boot/initrd >>/boot/instrumented_initrd
+
+Loading ACPI SSDTs from EFI variables
+=====================================
+
+This is the preferred method, when EFI is supported on the platform, because it
+allows a persistent, OS independent way of storing the user defined SSDTs. There
+is also work underway to implement EFI support for loading user defined SSDTs
+and using this method will make it easier to convert to the EFI loading
+mechanism when that will arrive.
+
+In order to load SSDTs from an EFI variable the efivar_ssdt kernel command line
+parameter can be used. The argument for the option is the variable name to
+use. If there are multiple variables with the same name but with different
+vendor GUIDs, all of them will be loaded.
+
+In order to store the AML code in an EFI variable the efivarfs filesystem can be
+used. It is enabled and mounted by default in /sys/firmware/efi/efivars in all
+recent distribution.
+
+Creating a new file in /sys/firmware/efi/efivars will automatically create a new
+EFI variable. Updating a file in /sys/firmware/efi/efivars will update the EFI
+variable. Please note that the file name needs to be specially formatted as
+"Name-GUID" and that the first 4 bytes in the file (little-endian format)
+represent the attributes of the EFI variable (see EFI_VARIABLE_MASK in
+include/linux/efi.h). Writing to the file must also be done with one write
+operation.
+
+For example, you can use the following bash script to create/update an EFI
+variable with the content from a given file::
+
+ #!/bin/sh -e
+
+ while ! [ -z "$1" ]; do
+ case "$1" in
+ "-f") filename="$2"; shift;;
+ "-g") guid="$2"; shift;;
+ *) name="$1";;
+ esac
+ shift
+ done
+
+ usage()
+ {
+ echo "Syntax: ${0##*/} -f filename [ -g guid ] name"
+ exit 1
+ }
+
+ [ -n "$name" -a -f "$filename" ] || usage
+
+ EFIVARFS="/sys/firmware/efi/efivars"
+
+ [ -d "$EFIVARFS" ] || exit 2
+
+ if stat -tf $EFIVARFS | grep -q -v de5e81e4; then
+ mount -t efivarfs none $EFIVARFS
+ fi
+
+ # try to pick up an existing GUID
+ [ -n "$guid" ] || guid=$(find "$EFIVARFS" -name "$name-*" | head -n1 | cut -f2- -d-)
+
+ # use a randomly generated GUID
+ [ -n "$guid" ] || guid="$(cat /proc/sys/kernel/random/uuid)"
+
+ # efivarfs expects all of the data in one write
+ tmp=$(mktemp)
+ /bin/echo -ne "\007\000\000\000" | cat - $filename > $tmp
+ dd if=$tmp of="$EFIVARFS/$name-$guid" bs=$(stat -c %s $tmp)
+ rm $tmp
+
+Loading ACPI SSDTs from configfs
+================================
+
+This option allows loading of user defined SSDTs from userspace via the configfs
+interface. The CONFIG_ACPI_CONFIGFS option must be select and configfs must be
+mounted. In the following examples, we assume that configfs has been mounted in
+/config.
+
+New tables can be loading by creating new directories in /config/acpi/table/ and
+writing the SSDT aml code in the aml attribute::
+
+ cd /config/acpi/table
+ mkdir my_ssdt
+ cat ~/ssdt.aml > my_ssdt/aml
diff --git a/Documentation/acpi/ssdt-overlays.txt b/Documentation/acpi/ssdt-overlays.txt
deleted file mode 100644
index 5ae13f161ea2..000000000000
--- a/Documentation/acpi/ssdt-overlays.txt
+++ /dev/null
@@ -1,172 +0,0 @@
-
-In order to support ACPI open-ended hardware configurations (e.g. development
-boards) we need a way to augment the ACPI configuration provided by the firmware
-image. A common example is connecting sensors on I2C / SPI buses on development
-boards.
-
-Although this can be accomplished by creating a kernel platform driver or
-recompiling the firmware image with updated ACPI tables, neither is practical:
-the former proliferates board specific kernel code while the latter requires
-access to firmware tools which are often not publicly available.
-
-Because ACPI supports external references in AML code a more practical
-way to augment firmware ACPI configuration is by dynamically loading
-user defined SSDT tables that contain the board specific information.
-
-For example, to enumerate a Bosch BMA222E accelerometer on the I2C bus of the
-Minnowboard MAX development board exposed via the LSE connector [1], the
-following ASL code can be used:
-
-DefinitionBlock ("minnowmax.aml", "SSDT", 1, "Vendor", "Accel", 0x00000003)
-{
- External (\_SB.I2C6, DeviceObj)
-
- Scope (\_SB.I2C6)
- {
- Device (STAC)
- {
- Name (_ADR, Zero)
- Name (_HID, "BMA222E")
-
- Method (_CRS, 0, Serialized)
- {
- Name (RBUF, ResourceTemplate ()
- {
- I2cSerialBus (0x0018, ControllerInitiated, 0x00061A80,
- AddressingMode7Bit, "\\_SB.I2C6", 0x00,
- ResourceConsumer, ,)
- GpioInt (Edge, ActiveHigh, Exclusive, PullDown, 0x0000,
- "\\_SB.GPO2", 0x00, ResourceConsumer, , )
- { // Pin list
- 0
- }
- })
- Return (RBUF)
- }
- }
- }
-}
-
-which can then be compiled to AML binary format:
-
-$ iasl minnowmax.asl
-
-Intel ACPI Component Architecture
-ASL Optimizing Compiler version 20140214-64 [Mar 29 2014]
-Copyright (c) 2000 - 2014 Intel Corporation
-
-ASL Input: minnomax.asl - 30 lines, 614 bytes, 7 keywords
-AML Output: minnowmax.aml - 165 bytes, 6 named objects, 1 executable opcodes
-
-[1] http://wiki.minnowboard.org/MinnowBoard_MAX#Low_Speed_Expansion_Connector_.28Top.29
-
-The resulting AML code can then be loaded by the kernel using one of the methods
-below.
-
-== Loading ACPI SSDTs from initrd ==
-
-This option allows loading of user defined SSDTs from initrd and it is useful
-when the system does not support EFI or when there is not enough EFI storage.
-
-It works in a similar way with initrd based ACPI tables override/upgrade: SSDT
-aml code must be placed in the first, uncompressed, initrd under the
-"kernel/firmware/acpi" path. Multiple files can be used and this will translate
-in loading multiple tables. Only SSDT and OEM tables are allowed. See
-initrd_table_override.txt for more details.
-
-Here is an example:
-
-# Add the raw ACPI tables to an uncompressed cpio archive.
-# They must be put into a /kernel/firmware/acpi directory inside the
-# cpio archive.
-# The uncompressed cpio archive must be the first.
-# Other, typically compressed cpio archives, must be
-# concatenated on top of the uncompressed one.
-mkdir -p kernel/firmware/acpi
-cp ssdt.aml kernel/firmware/acpi
-
-# Create the uncompressed cpio archive and concatenate the original initrd
-# on top:
-find kernel | cpio -H newc --create > /boot/instrumented_initrd
-cat /boot/initrd >>/boot/instrumented_initrd
-
-== Loading ACPI SSDTs from EFI variables ==
-
-This is the preferred method, when EFI is supported on the platform, because it
-allows a persistent, OS independent way of storing the user defined SSDTs. There
-is also work underway to implement EFI support for loading user defined SSDTs
-and using this method will make it easier to convert to the EFI loading
-mechanism when that will arrive.
-
-In order to load SSDTs from an EFI variable the efivar_ssdt kernel command line
-parameter can be used. The argument for the option is the variable name to
-use. If there are multiple variables with the same name but with different
-vendor GUIDs, all of them will be loaded.
-
-In order to store the AML code in an EFI variable the efivarfs filesystem can be
-used. It is enabled and mounted by default in /sys/firmware/efi/efivars in all
-recent distribution.
-
-Creating a new file in /sys/firmware/efi/efivars will automatically create a new
-EFI variable. Updating a file in /sys/firmware/efi/efivars will update the EFI
-variable. Please note that the file name needs to be specially formatted as
-"Name-GUID" and that the first 4 bytes in the file (little-endian format)
-represent the attributes of the EFI variable (see EFI_VARIABLE_MASK in
-include/linux/efi.h). Writing to the file must also be done with one write
-operation.
-
-For example, you can use the following bash script to create/update an EFI
-variable with the content from a given file:
-
-#!/bin/sh -e
-
-while ! [ -z "$1" ]; do
- case "$1" in
- "-f") filename="$2"; shift;;
- "-g") guid="$2"; shift;;
- *) name="$1";;
- esac
- shift
-done
-
-usage()
-{
- echo "Syntax: ${0##*/} -f filename [ -g guid ] name"
- exit 1
-}
-
-[ -n "$name" -a -f "$filename" ] || usage
-
-EFIVARFS="/sys/firmware/efi/efivars"
-
-[ -d "$EFIVARFS" ] || exit 2
-
-if stat -tf $EFIVARFS | grep -q -v de5e81e4; then
- mount -t efivarfs none $EFIVARFS
-fi
-
-# try to pick up an existing GUID
-[ -n "$guid" ] || guid=$(find "$EFIVARFS" -name "$name-*" | head -n1 | cut -f2- -d-)
-
-# use a randomly generated GUID
-[ -n "$guid" ] || guid="$(cat /proc/sys/kernel/random/uuid)"
-
-# efivarfs expects all of the data in one write
-tmp=$(mktemp)
-/bin/echo -ne "\007\000\000\000" | cat - $filename > $tmp
-dd if=$tmp of="$EFIVARFS/$name-$guid" bs=$(stat -c %s $tmp)
-rm $tmp
-
-== Loading ACPI SSDTs from configfs ==
-
-This option allows loading of user defined SSDTs from userspace via the configfs
-interface. The CONFIG_ACPI_CONFIGFS option must be select and configfs must be
-mounted. In the following examples, we assume that configfs has been mounted in
-/config.
-
-New tables can be loading by creating new directories in /config/acpi/table/ and
-writing the SSDT aml code in the aml attribute:
-
-cd /config/acpi/table
-mkdir my_ssdt
-cat ~/ssdt.aml > my_ssdt/aml
--
2.20.1
^ permalink raw reply related [flat|nested] 39+ messages in thread* [PATCH v2 24/24] acpi doc: convert acpi/video_extension.txt to rst format
2019-03-29 0:11 [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree Changbin Du
` (22 preceding siblings ...)
2019-03-29 0:11 ` [PATCH v2 23/24] acpi doc: convert acpi/ssdt-overlays.txt " Changbin Du
@ 2019-03-29 0:11 ` Changbin Du
2019-03-30 9:41 ` [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree Rafael J. Wysocki
24 siblings, 0 replies; 39+ messages in thread
From: Changbin Du @ 2019-03-29 0:11 UTC (permalink / raw)
To: Jonathan Corbet
Cc: rjw, lenb, linux-acpi, linux-kernel, linux-doc, Changbin Du
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
Documentation/acpi/index.rst | 1 +
...ideo_extension.txt => video_extension.rst} | 63 ++++++++++---------
2 files changed, 36 insertions(+), 28 deletions(-)
rename Documentation/acpi/{video_extension.txt => video_extension.rst} (79%)
diff --git a/Documentation/acpi/index.rst b/Documentation/acpi/index.rst
index d856ba53da4d..f16d527d1958 100644
--- a/Documentation/acpi/index.rst
+++ b/Documentation/acpi/index.rst
@@ -29,3 +29,4 @@ Linux ACPI (Advanced Configuration and Power Interface)
cppc_sysfs
lpit
ssdt-overlays
+ video_extension
diff --git a/Documentation/acpi/video_extension.txt b/Documentation/acpi/video_extension.rst
similarity index 79%
rename from Documentation/acpi/video_extension.txt
rename to Documentation/acpi/video_extension.rst
index 79bf6a4921be..06f7e3230b6e 100644
--- a/Documentation/acpi/video_extension.txt
+++ b/Documentation/acpi/video_extension.rst
@@ -1,5 +1,8 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=====================
ACPI video extensions
-~~~~~~~~~~~~~~~~~~~~~
+=====================
This driver implement the ACPI Extensions For Display Adapters for
integrated graphics devices on motherboard, as specified in ACPI 2.0
@@ -8,9 +11,10 @@ defining the video POST device, retrieving EDID information or to
setup a video output, etc. Note that this is an ref. implementation
only. It may or may not work for your integrated video device.
-The ACPI video driver does 3 things regarding backlight control:
+The ACPI video driver does 3 things regarding backlight control.
-1 Export a sysfs interface for user space to control backlight level
+1. Export a sysfs interface for user space to control backlight level
+=====================================================================
If the ACPI table has a video device, and acpi_backlight=vendor kernel
command line is not present, the driver will register a backlight device
@@ -32,26 +36,26 @@ type: firmware
Note that ACPI video backlight driver will always use index for
brightness, actual_brightness and max_brightness. So if we have
-the following _BCL package:
+the following _BCL package::
-Method (_BCL, 0, NotSerialized)
-{
- Return (Package (0x0C)
+ Method (_BCL, 0, NotSerialized)
{
- 0x64,
- 0x32,
- 0x0A,
- 0x14,
- 0x1E,
- 0x28,
- 0x32,
- 0x3C,
- 0x46,
- 0x50,
- 0x5A,
- 0x64
- })
-}
+ Return (Package (0x0C)
+ {
+ 0x64,
+ 0x32,
+ 0x0A,
+ 0x14,
+ 0x1E,
+ 0x28,
+ 0x32,
+ 0x3C,
+ 0x46,
+ 0x50,
+ 0x5A,
+ 0x64
+ })
+ }
The first two levels are for when laptop are on AC or on battery and are
not used by Linux currently. The remaining 10 levels are supported levels
@@ -62,13 +66,15 @@ as a "brightness level" indicator. Thus from the user space perspective
the range of available brightness levels is from 0 to 9 (max_brightness)
inclusive.
-2 Notify user space about hotkey event
+2. Notify user space about hotkey event
+=======================================
There are generally two cases for hotkey event reporting:
+
i) For some laptops, when user presses the hotkey, a scancode will be
generated and sent to user space through the input device created by
the keyboard driver as a key type input event, with proper remap, the
- following key code will appear to user space:
+ following key code will appear to user space::
EV_KEY, KEY_BRIGHTNESSUP
EV_KEY, KEY_BRIGHTNESSDOWN
@@ -82,7 +88,7 @@ ii) For some laptops, the press of the hotkey will not generate the
about the event. The event value is defined in the ACPI spec. ACPI
video driver will generate an key type input event according to the
notify value it received and send the event to user space through the
- input device it created:
+ input device it created::
event keycode
0x86 KEY_BRIGHTNESSUP
@@ -94,13 +100,14 @@ so this would lead to the same effect as case i) now.
Once user space tool receives this event, it can modify the backlight
level through the sysfs interface.
-3 Change backlight level in the kernel
+3. Change backlight level in the kernel
+=======================================
This works for machines covered by case ii) in Section 2. Once the driver
received a notification, it will set the backlight level accordingly. This does
not affect the sending of event to user space, they are always sent to user
space regardless of whether or not the video module controls the backlight level
directly. This behaviour can be controlled through the brightness_switch_enabled
-module parameter as documented in admin-guide/kernel-parameters.rst. It is recommended to
-disable this behaviour once a GUI environment starts up and wants to have full
-control of the backlight level.
+module parameter as documented in admin-guide/kernel-parameters.rst. It is
+recommended to disable this behaviour once a GUI environment starts up and
+wants to have full control of the backlight level.
--
2.20.1
^ permalink raw reply related [flat|nested] 39+ messages in thread* Re: [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree
2019-03-29 0:11 [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree Changbin Du
` (23 preceding siblings ...)
2019-03-29 0:11 ` [PATCH v2 24/24] acpi doc: convert acpi/video_extension.txt " Changbin Du
@ 2019-03-30 9:41 ` Rafael J. Wysocki
2019-04-02 8:25 ` Rafael J. Wysocki
24 siblings, 1 reply; 39+ messages in thread
From: Rafael J. Wysocki @ 2019-03-30 9:41 UTC (permalink / raw)
To: Changbin Du
Cc: Jonathan Corbet, Rafael J. Wysocki, Len Brown,
ACPI Devel Maling List, Linux Kernel Mailing List,
open list:DOCUMENTATION
On Fri, Mar 29, 2019 at 1:11 AM Changbin Du <changbin.du@gmail.com> wrote:
>
> Hi Corbet and All,
> The kernel now uses Sphinx to generate intelligent and beautiful documentation
> from reStructuredText files. I converted most of the Linux ACPI docs to rst
> format in this serias.
First, I appreciated the effort, thanks for your work!
> For you to preview, please visit below url:
> http://104.238.181.70:8080/kernel-doc/acpi/index.html
So currently all of this appears under Kernel API documentation, but
the majority of it is not about kernel API.
At least some of it could go under admin-guide IMO.
Thanks,
Rafael
^ permalink raw reply [flat|nested] 39+ messages in thread* Re: [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree
2019-03-30 9:41 ` [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree Rafael J. Wysocki
@ 2019-04-02 8:25 ` Rafael J. Wysocki
2019-04-03 19:36 ` Jonathan Corbet
0 siblings, 1 reply; 39+ messages in thread
From: Rafael J. Wysocki @ 2019-04-02 8:25 UTC (permalink / raw)
To: Jonathan Corbet
Cc: Changbin Du, Rafael J. Wysocki, Len Brown,
ACPI Devel Maling List, Linux Kernel Mailing List,
open list:DOCUMENTATION
On Sat, Mar 30, 2019 at 10:41 AM Rafael J. Wysocki <rafael@kernel.org> wrote:
>
> On Fri, Mar 29, 2019 at 1:11 AM Changbin Du <changbin.du@gmail.com> wrote:
> >
> > Hi Corbet and All,
> > The kernel now uses Sphinx to generate intelligent and beautiful documentation
> > from reStructuredText files. I converted most of the Linux ACPI docs to rst
> > format in this serias.
>
> First, I appreciated the effort, thanks for your work!
>
> > For you to preview, please visit below url:
> > http://104.238.181.70:8080/kernel-doc/acpi/index.html
>
> So currently all of this appears under Kernel API documentation, but
> the majority of it is not about kernel API.
>
> At least some of it could go under admin-guide IMO.
Jon,
There are ACPI-related documents currently in Documentation/acpi/ that
don't clearly fall under either driver-api or admin-guide. For
example, some of them describe various aspects of the ACPI support
subsystem operation and some document expectations with respect to the
ACPI tables provided by the firmware etc.
Where would you recommend to put them after converting to .rst?
Cheers,
Rafael
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree
2019-04-02 8:25 ` Rafael J. Wysocki
@ 2019-04-03 19:36 ` Jonathan Corbet
2019-04-03 20:40 ` Andy Shevchenko
` (2 more replies)
0 siblings, 3 replies; 39+ messages in thread
From: Jonathan Corbet @ 2019-04-03 19:36 UTC (permalink / raw)
To: Rafael J. Wysocki
Cc: Changbin Du, Rafael J. Wysocki, Len Brown,
ACPI Devel Maling List, Linux Kernel Mailing List,
open list:DOCUMENTATION
On Tue, 2 Apr 2019 10:25:23 +0200
"Rafael J. Wysocki" <rafael@kernel.org> wrote:
> There are ACPI-related documents currently in Documentation/acpi/ that
> don't clearly fall under either driver-api or admin-guide. For
> example, some of them describe various aspects of the ACPI support
> subsystem operation and some document expectations with respect to the
> ACPI tables provided by the firmware etc.
>
> Where would you recommend to put them after converting to .rst?
OK, I've done some pondering on this. Maybe what we need is a new
top-level "hardware guide" book meant to hold information on how the
hardware works and what the kernel's expectations are. Architecture
information could maybe go there too. Would this make sense?
If so, I could see a division like this:
Hardware guide
acpi-lid
aml-debugger (or maybe driver api?)
debug (ditto)
DSD-properties-rules
gpio-properties
i2c-muxes
Admin guide
cppc_sysfs
initrd_table_override
Driver-API
enumeration
scan_handlers
other:
dsdt-override: find another home for those five lines
...and so on. I've probably gotten at least one of those wrong, but that's
the idea.
Of course, then it would be nice to better integrate those documents so
that they fit into a single coherent whole...a guy can dream...:)
Thanks,
jon
^ permalink raw reply [flat|nested] 39+ messages in thread* Re: [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree
2019-04-03 19:36 ` Jonathan Corbet
@ 2019-04-03 20:40 ` Andy Shevchenko
2019-04-09 16:35 ` Rafael J. Wysocki
2019-04-05 2:44 ` Changbin Du
2019-04-09 16:42 ` Rafael J. Wysocki
2 siblings, 1 reply; 39+ messages in thread
From: Andy Shevchenko @ 2019-04-03 20:40 UTC (permalink / raw)
To: Jonathan Corbet
Cc: Rafael J. Wysocki, Changbin Du, Rafael J. Wysocki, Len Brown,
ACPI Devel Maling List, Linux Kernel Mailing List,
open list:DOCUMENTATION
On Wed, Apr 3, 2019 at 10:38 PM Jonathan Corbet <corbet@lwn.net> wrote:
> On Tue, 2 Apr 2019 10:25:23 +0200
> Admin guide
> cppc_sysfs
> initrd_table_override
> other:
> dsdt-override: find another home for those five lines
This is similar to initrd_table_override for some particular case, and
sounds like Admin guide, indeed.
--
With Best Regards,
Andy Shevchenko
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree
2019-04-03 20:40 ` Andy Shevchenko
@ 2019-04-09 16:35 ` Rafael J. Wysocki
0 siblings, 0 replies; 39+ messages in thread
From: Rafael J. Wysocki @ 2019-04-09 16:35 UTC (permalink / raw)
To: Andy Shevchenko
Cc: Jonathan Corbet, Rafael J. Wysocki, Changbin Du,
Rafael J. Wysocki, Len Brown, ACPI Devel Maling List,
Linux Kernel Mailing List, open list:DOCUMENTATION
On Wed, Apr 3, 2019 at 10:40 PM Andy Shevchenko
<andy.shevchenko@gmail.com> wrote:
>
> On Wed, Apr 3, 2019 at 10:38 PM Jonathan Corbet <corbet@lwn.net> wrote:
> > On Tue, 2 Apr 2019 10:25:23 +0200
>
>
> > Admin guide
> > cppc_sysfs
>
> > initrd_table_override
>
> > other:
> > dsdt-override: find another home for those five lines
>
> This is similar to initrd_table_override for some particular case, and
> sounds like Admin guide, indeed.
Right, I would put this one into admin-guide.
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree
2019-04-03 19:36 ` Jonathan Corbet
2019-04-03 20:40 ` Andy Shevchenko
@ 2019-04-05 2:44 ` Changbin Du
2019-04-09 16:17 ` Changbin Du
2019-04-09 16:42 ` Rafael J. Wysocki
2 siblings, 1 reply; 39+ messages in thread
From: Changbin Du @ 2019-04-05 2:44 UTC (permalink / raw)
To: Jonathan Corbet
Cc: Rafael J. Wysocki, Changbin Du, Rafael J. Wysocki, Len Brown,
Bjorn Helgaas, ACPI Devel Maling List, Linux Kernel Mailing List,
open list:DOCUMENTATION
+ Bjorn
On Wed, Apr 03, 2019 at 01:36:13PM -0600, Jonathan Corbet wrote:
> On Tue, 2 Apr 2019 10:25:23 +0200
> "Rafael J. Wysocki" <rafael@kernel.org> wrote:
>
> > There are ACPI-related documents currently in Documentation/acpi/ that
> > don't clearly fall under either driver-api or admin-guide. For
> > example, some of them describe various aspects of the ACPI support
> > subsystem operation and some document expectations with respect to the
> > ACPI tables provided by the firmware etc.
> >
> > Where would you recommend to put them after converting to .rst?
>
> OK, I've done some pondering on this. Maybe what we need is a new
> top-level "hardware guide" book meant to hold information on how the
> hardware works and what the kernel's expectations are. Architecture
> information could maybe go there too. Would this make sense?
>
> If so, I could see a division like this:
>
> Hardware guide
> acpi-lid
> aml-debugger (or maybe driver api?)
> debug (ditto)
> DSD-properties-rules
> gpio-properties
> i2c-muxes
>
> Admin guide
> cppc_sysfs
> initrd_table_override
>
> Driver-API
> enumeration
> scan_handlers
>
> other:
> dsdt-override: find another home for those five lines
>
Then, should we create dedicated sub-directories for these new charpters and
move documents to coresspoding one? Now we have 'admin-guide' and all admin-guid
docs are under it, otherwise we will have reference across different folders.
For example, the 'admin-guide/index.rst' will have:
...
../acpi/osi
...
Which seems not good.
> ...and so on. I've probably gotten at least one of those wrong, but that's
> the idea.
>
> Of course, then it would be nice to better integrate those documents so
> that they fit into a single coherent whole...a guy can dream...:)
>
I am not an adminstrator, so I don't know how adminstrators use this kernel
documentation. But as a kernel developer, I prefer all related documents
integrated into one charpter. Because I probably miss some useful sections
if the documents are distributed into several charpters. And this is usually
how a book is written (One charpter focus on one topic and has sub-sections
such as overview, backgroud knowledge, implemenation details..),
but a book mostly target on hypothetical readers...
> Thanks,
>
> jon
--
Cheers,
Changbin Du
^ permalink raw reply [flat|nested] 39+ messages in thread* Re: [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree
@ 2019-04-09 16:17 ` Changbin Du
0 siblings, 0 replies; 39+ messages in thread
From: Changbin Du @ 2019-04-09 16:17 UTC (permalink / raw)
Cc: Changbin Du, Jonathan Corbet, Rafael J. Wysocki,
Rafael J. Wysocki, Len Brown, Bjorn Helgaas,
ACPI Devel Maling List, Linux Kernel Mailing List,
open list:DOCUMENTATION
On Fri, Apr 05, 2019 at 10:44:35AM +0800, Changbin Du wrote:
> + Bjorn
>
> On Wed, Apr 03, 2019 at 01:36:13PM -0600, Jonathan Corbet wrote:
> > On Tue, 2 Apr 2019 10:25:23 +0200
> > "Rafael J. Wysocki" <rafael@kernel.org> wrote:
> >
> > > There are ACPI-related documents currently in Documentation/acpi/ that
> > > don't clearly fall under either driver-api or admin-guide. For
> > > example, some of them describe various aspects of the ACPI support
> > > subsystem operation and some document expectations with respect to the
> > > ACPI tables provided by the firmware etc.
> > >
> > > Where would you recommend to put them after converting to .rst?
> >
> > OK, I've done some pondering on this. Maybe what we need is a new
> > top-level "hardware guide" book meant to hold information on how the
> > hardware works and what the kernel's expectations are. Architecture
> > information could maybe go there too. Would this make sense?
> >
> > If so, I could see a division like this:
> >
> > Hardware guide
> > acpi-lid
> > aml-debugger (or maybe driver api?)
> > debug (ditto)
> > DSD-properties-rules
> > gpio-properties
> > i2c-muxes
> >
> > Admin guide
> > cppc_sysfs
> > initrd_table_override
> >
> > Driver-API
> > enumeration
> > scan_handlers
> >
> > other:
> > dsdt-override: find another home for those five lines
> >
> Then, should we create dedicated sub-directories for these new charpters and
> move documents to coresspoding one? Now we have 'admin-guide' and all admin-guid
> docs are under it, otherwise we will have reference across different folders.
> For example, the 'admin-guide/index.rst' will have:
> ...
> ../acpi/osi
> ...
> Which seems not good.
>
Jonathan, what is your idea about the placement of doc files?
> > ...and so on. I've probably gotten at least one of those wrong, but that's
> > the idea.
> >
> > Of course, then it would be nice to better integrate those documents so
> > that they fit into a single coherent whole...a guy can dream...:)
> >
> I am not an adminstrator, so I don't know how adminstrators use this kernel
> documentation. But as a kernel developer, I prefer all related documents
> integrated into one charpter. Because I probably miss some useful sections
> if the documents are distributed into several charpters. And this is usually
> how a book is written (One charpter focus on one topic and has sub-sections
> such as overview, backgroud knowledge, implemenation details..),
> but a book mostly target on hypothetical readers...
>
After some considerarion, I have a new idea. Since the top charpter named as
*API* so non-API things is not suitable for this charpter. But can we just
rename it? For example, we can rename 'Kernel API documentation' to
'Subsystem-specifc documentation' which is similar to 'Architecture-specific documentation'?
Subsystem-specifc documentation
-------------------------------
.. toctree::
:maxdepth: 2
driver-api/index
core-api/index
media/index
networking/index
input/index
gpu/index
...
Architecture-specific documentation
-----------------------------------
.. toctree::
:maxdepth: 2
sh/index
x86/index
...
> > Thanks,
> >
> > jon
>
> --
> Cheers,
> Changbin Du
--
Cheers,
Changbin Du
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree
@ 2019-04-09 16:17 ` Changbin Du
0 siblings, 0 replies; 39+ messages in thread
From: Changbin Du @ 2019-04-09 16:17 UTC (permalink / raw)
To: Jonathan Corbet
Cc: Changbin Du, Jonathan Corbet, Rafael J. Wysocki,
Rafael J. Wysocki, Len Brown, Bjorn Helgaas,
ACPI Devel Maling List, Linux Kernel Mailing List,
open list:DOCUMENTATION
On Fri, Apr 05, 2019 at 10:44:35AM +0800, Changbin Du wrote:
> + Bjorn
>
> On Wed, Apr 03, 2019 at 01:36:13PM -0600, Jonathan Corbet wrote:
> > On Tue, 2 Apr 2019 10:25:23 +0200
> > "Rafael J. Wysocki" <rafael@kernel.org> wrote:
> >
> > > There are ACPI-related documents currently in Documentation/acpi/ that
> > > don't clearly fall under either driver-api or admin-guide. For
> > > example, some of them describe various aspects of the ACPI support
> > > subsystem operation and some document expectations with respect to the
> > > ACPI tables provided by the firmware etc.
> > >
> > > Where would you recommend to put them after converting to .rst?
> >
> > OK, I've done some pondering on this. Maybe what we need is a new
> > top-level "hardware guide" book meant to hold information on how the
> > hardware works and what the kernel's expectations are. Architecture
> > information could maybe go there too. Would this make sense?
> >
> > If so, I could see a division like this:
> >
> > Hardware guide
> > acpi-lid
> > aml-debugger (or maybe driver api?)
> > debug (ditto)
> > DSD-properties-rules
> > gpio-properties
> > i2c-muxes
> >
> > Admin guide
> > cppc_sysfs
> > initrd_table_override
> >
> > Driver-API
> > enumeration
> > scan_handlers
> >
> > other:
> > dsdt-override: find another home for those five lines
> >
> Then, should we create dedicated sub-directories for these new charpters and
> move documents to coresspoding one? Now we have 'admin-guide' and all admin-guid
> docs are under it, otherwise we will have reference across different folders.
> For example, the 'admin-guide/index.rst' will have:
> ...
> ../acpi/osi
> ...
> Which seems not good.
>
Jonathan, what is your idea about the placement of doc files?
> > ...and so on. I've probably gotten at least one of those wrong, but that's
> > the idea.
> >
> > Of course, then it would be nice to better integrate those documents so
> > that they fit into a single coherent whole...a guy can dream...:)
> >
> I am not an adminstrator, so I don't know how adminstrators use this kernel
> documentation. But as a kernel developer, I prefer all related documents
> integrated into one charpter. Because I probably miss some useful sections
> if the documents are distributed into several charpters. And this is usually
> how a book is written (One charpter focus on one topic and has sub-sections
> such as overview, backgroud knowledge, implemenation details..),
> but a book mostly target on hypothetical readers...
>
After some considerarion, I have a new idea. Since the top charpter named as
*API* so non-API things is not suitable for this charpter. But can we just
rename it? For example, we can rename 'Kernel API documentation' to
'Subsystem-specifc documentation' which is similar to 'Architecture-specific documentation'?
Subsystem-specifc documentation
-------------------------------
.. toctree::
:maxdepth: 2
driver-api/index
core-api/index
media/index
networking/index
input/index
gpu/index
...
Architecture-specific documentation
-----------------------------------
.. toctree::
:maxdepth: 2
sh/index
x86/index
...
> > Thanks,
> >
> > jon
>
> --
> Cheers,
> Changbin Du
--
Cheers,
Changbin Du
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree
2019-04-03 19:36 ` Jonathan Corbet
2019-04-03 20:40 ` Andy Shevchenko
2019-04-05 2:44 ` Changbin Du
@ 2019-04-09 16:42 ` Rafael J. Wysocki
2019-04-09 21:26 ` Jonathan Corbet
2 siblings, 1 reply; 39+ messages in thread
From: Rafael J. Wysocki @ 2019-04-09 16:42 UTC (permalink / raw)
To: Jonathan Corbet
Cc: Rafael J. Wysocki, Changbin Du, Rafael J. Wysocki, Len Brown,
ACPI Devel Maling List, Linux Kernel Mailing List,
open list:DOCUMENTATION
On Wed, Apr 3, 2019 at 9:36 PM Jonathan Corbet <corbet@lwn.net> wrote:
>
> On Tue, 2 Apr 2019 10:25:23 +0200
> "Rafael J. Wysocki" <rafael@kernel.org> wrote:
>
> > There are ACPI-related documents currently in Documentation/acpi/ that
> > don't clearly fall under either driver-api or admin-guide. For
> > example, some of them describe various aspects of the ACPI support
> > subsystem operation and some document expectations with respect to the
> > ACPI tables provided by the firmware etc.
> >
> > Where would you recommend to put them after converting to .rst?
>
> OK, I've done some pondering on this. Maybe what we need is a new
> top-level "hardware guide" book meant to hold information on how the
> hardware works and what the kernel's expectations are. Architecture
> information could maybe go there too. Would this make sense?
>
> If so, I could see a division like this:
>
> Hardware guide
This is more about documenting the expectations regarding the platform
firmware, so what about firmware-guide instead?
> acpi-lid
> aml-debugger (or maybe driver api?)
> debug (ditto)
> DSD-properties-rules
> gpio-properties
> i2c-muxes
>
> Admin guide
> cppc_sysfs
> initrd_table_override
And I would add dsdt-override here.
>
> Driver-API
> enumeration
> scan_handlers
>
So what about this:
- Create a new firmware-guide under Documentation and add an acpi/
directory to it for starters. Put the following files into it:
acpi-lid
aml-debugger
debug (ditto)
DSD-properties-rules
gpio-properties
i2c-muxes
- Add an acpi/ subdirectory to Documentation/admin-guide and put the
following files into it:
cppc_sysfs
initrd_table_override
dsdt-override
- Add an acpi/ subdirectory to Documentation/driver-api and put the
following files into it:
enumeration
scan_handlers
^ permalink raw reply [flat|nested] 39+ messages in thread* Re: [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree
2019-04-09 16:42 ` Rafael J. Wysocki
@ 2019-04-09 21:26 ` Jonathan Corbet
2019-04-09 21:44 ` Rafael J. Wysocki
0 siblings, 1 reply; 39+ messages in thread
From: Jonathan Corbet @ 2019-04-09 21:26 UTC (permalink / raw)
To: Rafael J. Wysocki
Cc: Changbin Du, Rafael J. Wysocki, Len Brown,
ACPI Devel Maling List, Linux Kernel Mailing List,
open list:DOCUMENTATION
On Tue, 9 Apr 2019 18:42:59 +0200
"Rafael J. Wysocki" <rafael@kernel.org> wrote:
> > Hardware guide
>
> This is more about documenting the expectations regarding the platform
> firmware, so what about firmware-guide instead?
I had imagined a slightly wider focus, but this seems OK for now. We can
always rename it later :)
> So what about this:
>
> - Create a new firmware-guide under Documentation and add an acpi/
> directory to it for starters. Put the following files into it:
>
> acpi-lid
> aml-debugger
> debug (ditto)
> DSD-properties-rules
> gpio-properties
> i2c-muxes
>
> - Add an acpi/ subdirectory to Documentation/admin-guide and put the
> following files into it:
>
> cppc_sysfs
> initrd_table_override
> dsdt-override
I do wonder if, rather than creating a new directory, we shouldn't just
make a single acpi.rst and put that information into it?
> - Add an acpi/ subdirectory to Documentation/driver-api and put the
> following files into it:
>
> enumeration
> scan_handlers
...and something similar here? I guess that would be my preference, but I
don't feel all that strongly about it if there's reasons to do otherwise.
In general the plan seems good.
Thanks,
jon
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree
2019-04-09 21:26 ` Jonathan Corbet
@ 2019-04-09 21:44 ` Rafael J. Wysocki
2019-04-11 15:12 ` Changbin Du
0 siblings, 1 reply; 39+ messages in thread
From: Rafael J. Wysocki @ 2019-04-09 21:44 UTC (permalink / raw)
To: Jonathan Corbet
Cc: Rafael J. Wysocki, Changbin Du, Rafael J. Wysocki, Len Brown,
ACPI Devel Maling List, Linux Kernel Mailing List,
open list:DOCUMENTATION
On Tue, Apr 9, 2019 at 11:26 PM Jonathan Corbet <corbet@lwn.net> wrote:
>
> On Tue, 9 Apr 2019 18:42:59 +0200
> "Rafael J. Wysocki" <rafael@kernel.org> wrote:
>
> > > Hardware guide
> >
> > This is more about documenting the expectations regarding the platform
> > firmware, so what about firmware-guide instead?
>
> I had imagined a slightly wider focus, but this seems OK for now. We can
> always rename it later :)
>
> > So what about this:
> >
> > - Create a new firmware-guide under Documentation and add an acpi/
> > directory to it for starters. Put the following files into it:
> >
> > acpi-lid
> > aml-debugger
> > debug (ditto)
> > DSD-properties-rules
> > gpio-properties
> > i2c-muxes
> >
> > - Add an acpi/ subdirectory to Documentation/admin-guide and put the
> > following files into it:
> >
> > cppc_sysfs
> > initrd_table_override
> > dsdt-override
>
> I do wonder if, rather than creating a new directory, we shouldn't just
> make a single acpi.rst and put that information into it?
>
> > - Add an acpi/ subdirectory to Documentation/driver-api and put the
> > following files into it:
> >
> > enumeration
> > scan_handlers
>
> ...and something similar here? I guess that would be my preference, but I
> don't feel all that strongly about it if there's reasons to do otherwise.
The primary reason would be to retain the correspondence between the
old and the new files.
I guess they could be combined, but that would be two sort of
different changes in one go.
> In general the plan seems good.
OK, thanks!
Cheers,
Rafael
^ permalink raw reply [flat|nested] 39+ messages in thread
* Re: [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree
2019-04-09 21:44 ` Rafael J. Wysocki
@ 2019-04-11 15:12 ` Changbin Du
0 siblings, 0 replies; 39+ messages in thread
From: Changbin Du @ 2019-04-11 15:12 UTC (permalink / raw)
To: Rafael J. Wysocki
Cc: Jonathan Corbet, Changbin Du, Rafael J. Wysocki, Len Brown,
ACPI Devel Maling List, Linux Kernel Mailing List,
open list:DOCUMENTATION
On Tue, Apr 09, 2019 at 11:44:11PM +0200, Rafael J. Wysocki wrote:
> On Tue, Apr 9, 2019 at 11:26 PM Jonathan Corbet <corbet@lwn.net> wrote:
> >
> > On Tue, 9 Apr 2019 18:42:59 +0200
> > "Rafael J. Wysocki" <rafael@kernel.org> wrote:
> >
> > > > Hardware guide
> > >
> > > This is more about documenting the expectations regarding the platform
> > > firmware, so what about firmware-guide instead?
> >
> > I had imagined a slightly wider focus, but this seems OK for now. We can
> > always rename it later :)
> >
> > > So what about this:
> > >
> > > - Create a new firmware-guide under Documentation and add an acpi/
> > > directory to it for starters. Put the following files into it:
> > >
> > > acpi-lid
> > > aml-debugger
> > > debug (ditto)
> > > DSD-properties-rules
> > > gpio-properties
> > > i2c-muxes
> > >
> > > - Add an acpi/ subdirectory to Documentation/admin-guide and put the
> > > following files into it:
> > >
> > > cppc_sysfs
> > > initrd_table_override
> > > dsdt-override
> >
> > I do wonder if, rather than creating a new directory, we shouldn't just
> > make a single acpi.rst and put that information into it?
> >
> > > - Add an acpi/ subdirectory to Documentation/driver-api and put the
> > > following files into it:
> > >
> > > enumeration
> > > scan_handlers
> >
> > ...and something similar here? I guess that would be my preference, but I
> > don't feel all that strongly about it if there's reasons to do otherwise.
>
> The primary reason would be to retain the correspondence between the
> old and the new files.
>
> I guess they could be combined, but that would be two sort of
> different changes in one go.
>
> > In general the plan seems good.
>
> OK, thanks!
>
> Cheers,
> Rafael
Ok, if we have reached this greement, I probably do it this weekend. Thanks for your
comments.
--
Cheers,
Changbin Du
^ permalink raw reply [flat|nested] 39+ messages in thread