Include linux ACPI docs into Sphinx TOC tree
Subsystems (2)
v2 cover Include linux ACPI docs into Sphinx TOC tree
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.
For you to preview, please visit below url:
http://104.238.181.70:8080/kernel-doc/acpi/index.html
Thank you!
v2:
o Update MAINTAINERS.
o Add SPDX tags for all docs.
Changbin Du (24):
Documentation: add Linux ACPI to Sphinx TOC tree
acpi doc: convert acpi/namespace.txt to rst format acpi doc: convert acpi/enumeration.txt to rst format acpi doc: convert acpi/osi.txt to rst format
acpi doc: convert acpi/linuxized-acpica.txt to rst format acpi doc: convert acpi/scan_handlers.txt to rst format acpi doc: convert acpi/DSD-properties-rules.txt to rst format acpi doc: convert acpi/gpio-properties.txt to rst format acpi doc: convert acpi/method-customizing.txt to rst format acpi doc: convert acpi/initrd_table_override.txt to rst format acpi doc: convert acpi/dsdt-override.txt to rst format acpi doc: convert acpi/i2c-muxes.txt to rst format acpi doc: convert acpi/acpi-lid.txt to rst format
acpi doc: convert acpi/dsd/graph.txt to rst format acpi doc: convert acpi/dsd/data-node-references.txt to rst format acpi doc: convert acpi/debug.txt to rst format
acpi doc: convert acpi/method-tracing.txt to rst format acpi doc: convert acpi/aml-debugger.txt to rst format acpi doc: convert acpi/apei/output_format.txt to rst format acpi doc: convert acpi/apei/einj.txt to rst format acpi doc: convert acpi/cppc_sysfs.txt to rst format acpi doc: convert acpi/lpit.txt to rst format
acpi doc: convert acpi/ssdt-overlays.txt to rst format acpi doc: convert acpi/video_extension.txt to rst format
...ies-rules.txt => DSD-properties-rules.rst} | 21 +-
.../acpi/{acpi-lid.txt => acpi-lid.rst} | 48 ++-
Documentation/acpi/aml-debugger.rst | 75 +++++
Documentation/acpi/aml-debugger.txt | 66 ----
.../acpi/apei/{einj.txt => einj.rst} | 98 +++---
Documentation/acpi/apei/output_format.rst | 150 +++++++++
Documentation/acpi/apei/output_format.txt | 147 ---------
.../acpi/{cppc_sysfs.txt => cppc_sysfs.rst} | 71 ++--
Documentation/acpi/{debug.txt => debug.rst} | 31 +-
...eferences.txt => data-node-references.rst} | 28 +-
.../acpi/dsd/{graph.txt => graph.rst} | 157 ++++-----
.../{dsdt-override.txt => dsdt-override.rst} | 8 +-
.../acpi/{enumeration.txt => enumeration.rst} | 135 ++++----
...pio-properties.txt => gpio-properties.rst} | 78 +++--
Documentation/acpi/i2c-muxes.rst | 61 ++++
Documentation/acpi/i2c-muxes.txt | 58 ----
Documentation/acpi/index.rst | 32 ++
Documentation/acpi/initrd_table_override.rst | 120 +++++++
Documentation/acpi/initrd_table_override.txt | 111 -------
...uxized-acpica.txt => linuxized-acpica.rst} | 115 ++++---
Documentation/acpi/{lpit.txt => lpit.rst} | 18 +-
Documentation/acpi/method-customizing.rst | 82 +++++
Documentation/acpi/method-customizing.txt | 73 -----
Documentation/acpi/method-tracing.rst | 225 +++++++++++++
Documentation/acpi/method-tracing.txt | 192 -----------
.../acpi/{namespace.txt => namespace.rst} | 310 +++++++++---------
Documentation/acpi/{osi.txt => osi.rst} | 15 +-
.../{scan_handlers.txt => scan_handlers.rst} | 24 +-
Documentation/acpi/ssdt-overlays.rst | 180 ++++++++++
Documentation/acpi/ssdt-overlays.txt | 172 ----------
...ideo_extension.txt => video_extension.rst} | 63 ++--
Documentation/index.rst | 1 +
MAINTAINERS | 2 +-
33 files changed, 1596 insertions(+), 1371 deletions(-)
rename Documentation/acpi/{DSD-properties-rules.txt => DSD-properties-rules.rst} (88%)
rename Documentation/acpi/{acpi-lid.txt => acpi-lid.rst} (77%)
create mode 100644 Documentation/acpi/aml-debugger.rst
delete mode 100644 Documentation/acpi/aml-debugger.txt
rename Documentation/acpi/apei/{einj.txt => einj.rst} (67%)
create mode 100644 Documentation/acpi/apei/output_format.rst
delete mode 100644 Documentation/acpi/apei/output_format.txt
rename Documentation/acpi/{cppc_sysfs.txt => cppc_sysfs.rst} (51%)
rename Documentation/acpi/{debug.txt => debug.rst} (91%)
rename Documentation/acpi/dsd/{data-node-references.txt => data-node-references.rst} (79%)
rename Documentation/acpi/dsd/{graph.txt => graph.rst} (56%)
rename Documentation/acpi/{dsdt-override.txt => dsdt-override.rst} (56%)
rename Documentation/acpi/{enumeration.txt => enumeration.rst} (87%)
rename Documentation/acpi/{gpio-properties.txt => gpio-properties.rst} (81%)
create mode 100644 Documentation/acpi/i2c-muxes.rst
delete mode 100644 Documentation/acpi/i2c-muxes.txt
create mode 100644 Documentation/acpi/index.rst
create mode 100644 Documentation/acpi/initrd_table_override.rst
delete mode 100644 Documentation/acpi/initrd_table_override.txt
rename Documentation/acpi/{linuxized-acpica.txt => linuxized-acpica.rst} (78%)
rename Documentation/acpi/{lpit.txt => lpit.rst} (68%)
create mode 100644 Documentation/acpi/method-customizing.rst
delete mode 100644 Documentation/acpi/method-customizing.txt
create mode 100644 Documentation/acpi/method-tracing.rst
delete mode 100644 Documentation/acpi/method-tracing.txt
rename Documentation/acpi/{namespace.txt => namespace.rst} (54%)
rename Documentation/acpi/{osi.txt => osi.rst} (97%)
rename Documentation/acpi/{scan_handlers.txt => scan_handlers.rst} (90%)
create mode 100644 Documentation/acpi/ssdt-overlays.rst
delete mode 100644 Documentation/acpi/ssdt-overlays.txt
rename Documentation/acpi/{video_extension.txt => video_extension.rst} (79%)Signature · 1 line
2.20.1
PATCH v2 1/24 Documentation: add Linux ACPI to Sphinx TOC tree
Add a index.rst for trace subsystem. More docs will be added later.
--- Documentation/acpi/index.rst | 8 ++++++++ Documentation/index.rst | 1 + 2 files changed, 9 insertions(+) create mode 100644 Documentation/acpi/index.rst
Documentation/acpi/index.rst new file +8 -0
@@ -0,0 +1,8 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================================================= +Linux ACPI (Advanced Configuration and Power Interface) +======================================================= + +.. toctree:: + :maxdepth: 2
Documentation/index.rst +1 -0
@@ -90,6 +90,7 @@ needed). filesystems/index vm/index bpf/index + acpi/index misc-devices/index Architecture-specific documentation
Signature · 1 line
2.20.1
Rafael J. Wysocki
maintainerRe: [PATCH v2 01/24] Documentation: add Linux ACPI to Sphinx TOC tree
Quoted 16 lines · Changbin Du
Add a
index.rstfor trace subsystem. More docs will be added later.Signed-off-by Changbin Du <[email protected]>--- Documentation/acpi/index.rst | 8 ++++++++ Documentation/index.rst | 1 + 2 files changed, 9 insertions(+) create mode 100644 Documentation/acpi/index.rstDocumentation/acpi/index.rst new file +0
-0
Documentation/acpi/index.rst line 4
Quoted 4 lines
Documentation/acpi/index.rst new file +4
-0@@ -0,0 +1,8 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================================================= +Linux ACPI (Advanced Configuration and Power Interface)
"Linux ACPI Support", please.
Quoted 19 lines
Documentation/acpi/index.rst new file +4
-0+======================================================= + +.. toctree:: + :maxdepth: 2Documentation/index.rst +1
-1@@ -90,6 +90,7 @@ needed). filesystems/index vm/index bpf/index + acpi/index misc-devices/index Architecture-specific documentation --2.20.1
Re: [PATCH v2 01/24] Documentation: add Linux ACPI to Sphinx TOC tree
Quoted 11 lines · Rafael J. Wysocki
Quoted 10 lines · Changbin Du
Add a
index.rstfor trace subsystem. More docs will be added later.Signed-off-by Changbin Du <[email protected]>--- Documentation/acpi/index.rst | 8 ++++++++ Documentation/index.rst | 1 + 2 files changed, 9 insertions(+) create mode 100644 Documentation/acpi/index.rst
Quoted 13 lines
Documentation/acpi/index.rst line 4
Quoted 10 lines
Documentation/acpi/index.rst new file +4
-0@@ -0,0 +1,8 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================================================= +Linux ACPI (Advanced Configuration and Power Interface)"Linux ACPI Support", please.
sure.
Quoted 19 lines
Quoted 19 lines
Documentation/acpi/index.rst new file +4
-0+======================================================= + +.. toctree:: + :maxdepth: 2Documentation/index.rst +1
-1@@ -90,6 +90,7 @@ needed). filesystems/index vm/index bpf/index + acpi/index misc-devices/index Architecture-specific documentation --2.20.1
Signature · 2 lines
Cheers, Changbin Du
PATCH v2 2/24 acpi doc: convert acpi/namespace.txt to rst format
In reply to Changbin DuThis converts the plain text documentation to reStructuredText format and add it to Sphinx TOC tree. No essential content change.
---
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%)Documentation/acpi/index.rst +3 -1
@@ -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
Documentation/acpi/namespace.rst renamed from Documentation/acpi/namespace.txt +160 -150
351 lines not on this page · raw message
Signature · 1 line
2.20.1
PATCH v2 3/24 acpi doc: convert acpi/enumeration.txt to rst format
In reply to Changbin DuThis converts the plain text documentation to reStructuredText format and add it to Sphinx TOC tree. No essential content change.
---
.../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%)Documentation/acpi/enumeration.rst renamed from Documentation/acpi/enumeration.txt +73 -62
@@ -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.
Documentation/acpi/index.rst +1 -0
@@ -8,3 +8,4 @@ Linux ACPI (Advanced Configuration and Power Interface) :maxdepth: 2 namespace + enumeration
Signature · 1 line
2.20.1
PATCH v2 4/24 acpi doc: convert acpi/osi.txt to rst format
In reply to Changbin DuThis converts the plain text documentation to reStructuredText format and add it to Sphinx TOC tree. No essential content change.
---
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%)Documentation/acpi/index.rst +1 -0
@@ -9,3 +9,4 @@ Linux ACPI (Advanced Configuration and Power Interface) namespace enumeration + osi
Documentation/acpi/osi.rst renamed from Documentation/acpi/osi.txt +9 -6
@@ -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.
Signature · 1 line
2.20.1
PATCH v2 5/24 acpi doc: convert acpi/linuxized-acpica.txt to rst format
In reply to Changbin DuThis converts the plain text documentation to reStructuredText format and add it to Sphinx TOC tree. No essential content change.
---
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%)Documentation/acpi/index.rst +1 -0
@@ -7,6 +7,7 @@ Linux ACPI (Advanced Configuration and Power Interface) .. toctree:: :maxdepth: 2 + linuxized-acpica namespace enumeration osi
Documentation/acpi/linuxized-acpica.rst renamed from Documentation/acpi/linuxized-acpica.txt +65 -50
199 lines not on this page · raw message
Signature · 1 line
2.20.1
PATCH v2 6/24 acpi doc: convert acpi/scan_handlers.txt to rst format
In reply to Changbin DuThis converts the plain text documentation to reStructuredText format and add it to Sphinx TOC tree. No essential content change.
---
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%)Documentation/acpi/index.rst +1 -0
@@ -11,3 +11,4 @@ Linux ACPI (Advanced Configuration and Power Interface) namespace enumeration osi + scan_handlers
Documentation/acpi/scan_handlers.rst renamed from Documentation/acpi/scan_handlers.txt +15 -9
@@ -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 <[email protected]> +:Author: Rafael J. Wysocki <[email protected]> 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
Signature · 1 line
2.20.1
PATCH v2 7/24 acpi doc: convert acpi/DSD-properties-rules.txt to rst format
In reply to Changbin DuThis converts the plain text documentation to reStructuredText format and add it to Sphinx TOC tree. No essential content change.
---
...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%)Documentation/acpi/DSD-properties-rules.rst renamed from Documentation/acpi/DSD-properties-rules.txt +12 -9
@@ -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
Documentation/acpi/index.rst +1 -0
@@ -11,4 +11,5 @@ Linux ACPI (Advanced Configuration and Power Interface) namespace enumeration osi + DSD-properties-rules scan_handlers
Signature · 1 line
2.20.1
PATCH v2 8/24 acpi doc: convert acpi/gpio-properties.txt to rst format
In reply to Changbin DuThis converts the plain text documentation to reStructuredText format and add it to Sphinx TOC tree. No essential content change.
---
...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%)Documentation/acpi/gpio-properties.rst renamed from Documentation/acpi/gpio-properties.txt +44 -34
@@ -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
Documentation/acpi/index.rst +1 -0
@@ -12,4 +12,5 @@ Linux ACPI (Advanced Configuration and Power Interface) enumeration osi DSD-properties-rules + gpio-properties scan_handlers
MAINTAINERS +1 -1
@@ -6593,7 +6593,7 @@ M: Andy Shevchenko <[email protected]> L: [email protected] L: [email protected] S: Maintained -F: Documentation/acpi/gpio-properties.txt +F: Documentation/acpi/gpio-properties.rst F: drivers/gpio/gpiolib-acpi.c GPIO IR Transmitter
Signature · 1 line
2.20.1
PATCH v2 9/24 acpi doc: convert acpi/method-customizing.txt to rst format
In reply to Changbin DuThis converts the plain text documentation to reStructuredText format and add it to Sphinx TOC tree. No essential content change.
--- 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
Documentation/acpi/index.rst +1 -0
@@ -14,3 +14,4 @@ Linux ACPI (Advanced Configuration and Power Interface) DSD-properties-rules gpio-properties scan_handlers + method-customizing
Documentation/acpi/method-customizing.rst new file +82 -0
82 lines not on this page · raw message
Documentation/acpi/method-customizing.txt deleted +0 -73
73 lines not on this page · raw message
Signature · 1 line
2.20.1
PATCH v2 10/24 acpi doc: convert acpi/initrd_table_override.txt to rst format
In reply to Changbin DuThis converts the plain text documentation to reStructuredText format and add it to Sphinx TOC tree. No essential content change.
--- 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
Documentation/acpi/index.rst +1 -0
@@ -15,3 +15,4 @@ Linux ACPI (Advanced Configuration and Power Interface) gpio-properties scan_handlers method-customizing + initrd_table_override
Documentation/acpi/initrd_table_override.rst new file +120 -0
120 lines not on this page · raw message
Documentation/acpi/initrd_table_override.txt deleted +0 -111
111 lines not on this page · raw message
Signature · 1 line
2.20.1
PATCH v2 11/24 acpi doc: convert acpi/dsdt-override.txt to rst format
In reply to Changbin DuThis converts the plain text documentation to reStructuredText format and add it to Sphinx TOC tree. No essential content change.
---
.../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%)Documentation/acpi/dsdt-override.rst renamed from Documentation/acpi/dsdt-override.txt +7 -1
@@ -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:
Documentation/acpi/index.rst +1 -0
@@ -16,3 +16,4 @@ Linux ACPI (Advanced Configuration and Power Interface) scan_handlers method-customizing initrd_table_override + dsdt-override
Signature · 1 line
2.20.1
PATCH v2 12/24 acpi doc: convert acpi/i2c-muxes.txt to rst format
In reply to Changbin DuThis converts the plain text documentation to reStructuredText format and add it to Sphinx TOC tree. No essential content change.
--- 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
Documentation/acpi/i2c-muxes.rst new file +61 -0
@@ -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,,) + } + } + } + } + }
Documentation/acpi/i2c-muxes.txt deleted +0 -58
58 lines not on this page · raw message
Documentation/acpi/index.rst +1 -0
@@ -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
Signature · 1 line
2.20.1
PATCH v2 13/24 acpi doc: convert acpi/acpi-lid.txt to rst format
In reply to Changbin DuThis converts the plain text documentation to reStructuredText format and add it to Sphinx TOC tree. No essential content change.
---
.../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%)Documentation/acpi/acpi-lid.rst renamed from Documentation/acpi/acpi-lid.txt +32 -16
@@ -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 <[email protected]> +========================================================= +Special Usage Model of the ACPI Control Method Lid Device +========================================================= +:Copyright: |copy| 2016, Intel Corporation -Abstract: +:Author: Lv Zheng <[email protected]> -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.
Documentation/acpi/index.rst +1 -0
@@ -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
Signature · 1 line
2.20.1
PATCH v2 14/24 acpi doc: convert acpi/dsd/graph.txt to rst format
In reply to Changbin DuThis converts the plain text documentation to reStructuredText format and add it to Sphinx TOC tree. No essential content change.
---
.../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%)Documentation/acpi/dsd/graph.rst renamed from Documentation/acpi/dsd/graph.txt +80 -77
@@ -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`
Documentation/acpi/index.rst +1 -0
@@ -9,6 +9,7 @@ Linux ACPI (Advanced Configuration and Power Interface) linuxized-acpica namespace + dsd/graph enumeration osi DSD-properties-rules
Signature · 1 line
2.20.1
PATCH v2 15/24 acpi doc: convert acpi/dsd/data-node-references.txt to rst format
In reply to Changbin DuThis converts the plain text documentation to reStructuredText format and add it to Sphinx TOC tree. No essential content change.
---
...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%)Documentation/acpi/dsd/data-node-references.rst renamed from Documentation/acpi/dsd/data-node-references.txt +16 -12
@@ -1,9 +1,12 @@ -Copyright (C) 2018 Intel Corporation -Author: Sakari Ailus <[email protected]> - +.. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> +=================================== Referencing hierarchical data nodes ------------------------------------ +=================================== + +:Copyright: |copy| 2018 Intel Corporation +:Author: Sakari Ailus <[email protected]> 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>,
Documentation/acpi/index.rst +1 -0
@@ -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
Signature · 1 line
2.20.1
PATCH v2 16/24 acpi doc: convert acpi/debug.txt to rst format
In reply to Changbin DuThis converts the plain text documentation to reStructuredText format and add it to Sphinx TOC tree. No essential content change.
---
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%)Documentation/acpi/debug.rst renamed from Documentation/acpi/debug.txt +17 -14
@@ -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
Documentation/acpi/index.rst +1 -0
@@ -21,3 +21,4 @@ Linux ACPI (Advanced Configuration and Power Interface) method-customizing initrd_table_override dsdt-override + debug
Signature · 1 line
2.20.1
PATCH v2 17/24 acpi doc: convert acpi/method-tracing.txt to rst format
In reply to Changbin DuThis converts the plain text documentation to reStructuredText format and add it to Sphinx TOC tree. No essential content change.
--- 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
Documentation/acpi/index.rst +1 -0
@@ -22,3 +22,4 @@ Linux ACPI (Advanced Configuration and Power Interface) initrd_table_override dsdt-override debug + method-tracing
Documentation/acpi/method-tracing.rst new file +225 -0
225 lines not on this page · raw message
Documentation/acpi/method-tracing.txt deleted +0 -192
192 lines not on this page · raw message
Signature · 1 line
2.20.1
PATCH v2 18/24 acpi doc: convert acpi/aml-debugger.txt to rst format
In reply to Changbin DuThis converts the plain text documentation to reStructuredText format and add it to Sphinx TOC tree. No essential content change.
--- 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
Documentation/acpi/aml-debugger.rst new file +75 -0
@@ -0,0 +1,75 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> + +================ +The AML Debugger +================ + +:Copyright: |copy| 2016, Intel Corporation +:Author: Lv Zheng <[email protected]> + + +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"
Documentation/acpi/aml-debugger.txt deleted +0 -66
66 lines not on this page · raw message
Documentation/acpi/index.rst +1 -0
@@ -23,3 +23,4 @@ Linux ACPI (Advanced Configuration and Power Interface) dsdt-override debug method-tracing + aml-debugger
Signature · 1 line
2.20.1
PATCH v2 19/24 acpi doc: convert acpi/apei/output_format.txt to rst format
In reply to Changbin DuThis converts the plain text documentation to reStructuredText format and add it to Sphinx TOC tree. No essential content change.
--- 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
Documentation/acpi/apei/output_format.rst new file +150 -0
@@ -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.
Documentation/acpi/apei/output_format.txt deleted +0 -147
147 lines not on this page · raw message
Documentation/acpi/index.rst +1 -0
@@ -24,3 +24,4 @@ Linux ACPI (Advanced Configuration and Power Interface) debug method-tracing aml-debugger + apei/output_format
Signature · 1 line
2.20.1
PATCH v2 20/24 acpi doc: convert acpi/apei/einj.txt to rst format
In reply to Changbin DuThis converts the plain text documentation to reStructuredText format and add it to Sphinx TOC tree. No essential content change.
---
.../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%)Documentation/acpi/apei/einj.rst renamed from Documentation/acpi/apei/einj.txt +52 -46
@@ -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.
Documentation/acpi/index.rst +1 -0
@@ -25,3 +25,4 @@ Linux ACPI (Advanced Configuration and Power Interface) method-tracing aml-debugger apei/output_format + apei/einj
Signature · 1 line
2.20.1
PATCH v2 21/24 acpi doc: convert acpi/cppc_sysfs.txt to rst format
In reply to Changbin DuThis converts the plain text documentation to reStructuredText format and add it to Sphinx TOC tree. No essential content change.
---
.../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%)Documentation/acpi/cppc_sysfs.rst renamed from Documentation/acpi/cppc_sysfs.txt +39 -32
@@ -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
Documentation/acpi/index.rst +1 -0
@@ -26,3 +26,4 @@ Linux ACPI (Advanced Configuration and Power Interface) aml-debugger apei/output_format apei/einj + cppc_sysfs
Signature · 1 line
2.20.1
PATCH v2 22/24 acpi doc: convert acpi/lpit.txt to rst format
In reply to Changbin DuThis converts the plain text documentation to reStructuredText format and add it to Sphinx TOC tree. No essential content change.
---
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%)Documentation/acpi/index.rst +1 -0
@@ -27,3 +27,4 @@ Linux ACPI (Advanced Configuration and Power Interface) apei/output_format apei/einj cppc_sysfs + lpit
Documentation/acpi/lpit.rst renamed from Documentation/acpi/lpit.txt +13 -5
@@ -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
Signature · 1 line
2.20.1
PATCH v2 23/24 acpi doc: convert acpi/ssdt-overlays.txt to rst format
In reply to Changbin DuThis converts the plain text documentation to reStructuredText format and add it to Sphinx TOC tree. No essential content change.
--- 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
Documentation/acpi/index.rst +1 -0
@@ -28,3 +28,4 @@ Linux ACPI (Advanced Configuration and Power Interface) apei/einj cppc_sysfs lpit + ssdt-overlays
Documentation/acpi/ssdt-overlays.rst new file +180 -0
180 lines not on this page · raw message
Documentation/acpi/ssdt-overlays.txt deleted +0 -172
172 lines not on this page · raw message
Signature · 1 line
2.20.1
PATCH v2 24/24 acpi doc: convert acpi/video_extension.txt to rst format
In reply to Changbin DuThis converts the plain text documentation to reStructuredText format and add it to Sphinx TOC tree. No essential content change.
---
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%)Documentation/acpi/index.rst +1 -0
@@ -29,3 +29,4 @@ Linux ACPI (Advanced Configuration and Power Interface) cppc_sysfs lpit ssdt-overlays + video_extension
Documentation/acpi/video_extension.rst renamed from Documentation/acpi/video_extension.txt +35 -28
108 lines not on this page · raw message
Signature · 1 line
2.20.1
Rafael J. Wysocki
maintainerQuoted 5 lines · Changbin Du
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!
Quoted 2 lines
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
Rafael J. Wysocki
maintainerQuoted 10 lines · Rafael J. Wysocki
Quoted 5 lines · Changbin Du
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!
Quoted 7 lines
Quoted 2 lines
For you to preview, please visit below url:
http://104.238.181.70:8080/kernel-doc/acpi/index.htmlSo 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
Jonathan Corbet
maintainerQuoted 7 lines · On Tue, 2 Apr 2019 10:25:23 +0200 "Rafael J. Wysocki" <[email protected]> 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
Quoted 10 lines · Jonathan Corbet
On Tue, 2 Apr 2019 10:25:23 +0200
Admin guide
cppc_sysfs
initrd_table_overrideother:
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.
Signature · 2 lines
With Best Regards, Andy Shevchenko
Rafael J. Wysocki
maintainerQuoted 8 lines · Andy Shevchenko
Quoted 5 lines · Jonathan Corbet
On Tue, 2 Apr 2019 10:25:23 +0200
Admin guide
cppc_sysfs
Quoted 7 lines
Quoted 4 lines
initrd_table_overrideother:
dsdt-override: find another home for those five linesThis is similar to
initrd_table_overridefor some particular case, and sounds like Admin guide, indeed.
Right, I would put this one into admin-guide.
+ Bjorn
Quoted 30 lines · Jonathan Corbet
Quoted 7 lines · On Tue, 2 Apr 2019 10:25:23 +0200 "Rafael J. Wysocki" <[email protected]> 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-muxesAdmin guide
cppc_sysfs
initrd_table_override
Quoted 7 lines
Driver-API
enumeration
scan_handlersother:
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.
Quoted 6 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...:)
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...
Quoted 3 lines
Thanks,
jon
Signature · 2 lines
Cheers, Changbin Du
Quoted 40 lines · Changbin Du
+ Bjorn
Quoted 30 lines · Jonathan Corbet
Quoted 7 lines · On Tue, 2 Apr 2019 10:25:23 +0200 "Rafael J. Wysocki" <[email protected]> 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-muxesAdmin guide
cppc_sysfs
initrd_table_overrideQuoted 7 lines
Driver-API
enumeration
scan_handlersother:
dsdt-override: find another home for those five lines
Quoted 9 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?
Quoted 6 lines
Quoted 6 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...:)
Quoted 8 lines
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
...
Quoted 7 lines
Quoted 3 lines
Thanks,
jon
Signature · 2 lines
Cheers, Changbin Du
Signature · 2 lines
Cheers, Changbin Du
Rafael J. Wysocki
maintainerQuoted 12 lines · Jonathan Corbet
Quoted 7 lines · On Tue, 2 Apr 2019 10:25:23 +0200 "Rafael J. Wysocki" <[email protected]> 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?
Quoted 8 lines
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?
Quoted 10 lines
acpi-lid
aml-debugger (or maybe driver api?)
debug (ditto)
DSD-properties-rules
gpio-properties
i2c-muxesAdmin guide
cppc_sysfs
initrd_table_override
And I would add dsdt-override here.
Quoted 5 lines
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
Jonathan Corbet
maintainerQuoted 4 lines · On Tue, 9 Apr 2019 18:42:59 +0200 "Rafael J. Wysocki" <[email protected]> wrote:
Quoted 1 line
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 :)
Quoted 12 lines
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
Quoted 6 lines
- Add an acpi/ subdirectory to
Documentation/admin-guideand 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?
Quoted 5 lines
- Add an acpi/ subdirectory to
Documentation/driver-apiand 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
Rafael J. Wysocki
maintainerQuoted 34 lines · Jonathan Corbet
Quoted 4 lines · On Tue, 9 Apr 2019 18:42:59 +0200 "Rafael J. Wysocki" <[email protected]> wrote:
Quoted 1 line
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 :)
Quoted 12 lines
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-muxesQuoted 6 lines
- Add an acpi/ subdirectory to
Documentation/admin-guideand put the following files into it:
cppc_sysfs
initrd_table_override
dsdt-overrideI do wonder if, rather than creating a new directory, we shouldn't just make a single
acpi.rstand put that information into it?
Quoted 8 lines
Quoted 5 lines
- Add an acpi/ subdirectory to
Documentation/driver-apiand 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.
Quoted 1 line
In general the plan seems good.
OK, thanks!
Cheers,
Rafael
Quoted 50 lines · Rafael J. Wysocki
Quoted 34 lines · Jonathan Corbet
Quoted 4 lines · On Tue, 9 Apr 2019 18:42:59 +0200 "Rafael J. Wysocki" <[email protected]> wrote:
Quoted 1 line
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 :)
Quoted 12 lines
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-muxesQuoted 6 lines
- Add an acpi/ subdirectory to
Documentation/admin-guideand put the following files into it:
cppc_sysfs
initrd_table_override
dsdt-overrideI do wonder if, rather than creating a new directory, we shouldn't just make a single
acpi.rstand put that information into it?Quoted 8 lines
Quoted 5 lines
- Add an acpi/ subdirectory to
Documentation/driver-apiand 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.
Quoted 6 lines
Quoted 1 line
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.
Signature · 2 lines
Cheers, Changbin Du