* [PATCH v6 13/24] Documentation: ACPI: move acpi-lid.txt to firmware-guide/acpi and convert to reST
From: Changbin Du @ 2019-04-25 15:31 UTC (permalink / raw)
To: rjw, Jonathan Corbet
Cc: fenghua.yu, mchehab+samsung, linux-doc, linux-gpio, linux-kernel,
linux-acpi, Bjorn Helgaas, linuxppc-dev, Changbin Du
In-Reply-To: <20190425153117.16057-1-changbin.du@gmail.com>
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../acpi/acpi-lid.rst} | 40 ++++++++++++++-----
Documentation/firmware-guide/acpi/index.rst | 1 +
2 files changed, 30 insertions(+), 11 deletions(-)
rename Documentation/{acpi/acpi-lid.txt => firmware-guide/acpi/acpi-lid.rst} (86%)
diff --git a/Documentation/acpi/acpi-lid.txt b/Documentation/firmware-guide/acpi/acpi-lid.rst
similarity index 86%
rename from Documentation/acpi/acpi-lid.txt
rename to Documentation/firmware-guide/acpi/acpi-lid.rst
index effe7af3a5af..874ce0ed340d 100644
--- a/Documentation/acpi/acpi-lid.txt
+++ b/Documentation/firmware-guide/acpi/acpi-lid.rst
@@ -1,13 +1,18 @@
-Special Usage Model of the ACPI Control Method Lid Device
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
-Copyright (C) 2016, Intel Corporation
-Author: Lv Zheng <lv.zheng@intel.com>
+=========================================================
+Special Usage Model of the ACPI Control Method Lid Device
+=========================================================
+:Copyright: |copy| 2016, Intel Corporation
-Abstract:
+:Author: Lv Zheng <lv.zheng@intel.com>
-Platforms containing lids convey lid state (open/close) to OSPMs using a
-control method lid device. To implement this, the AML tables issue
+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".
@@ -19,7 +24,8 @@ 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
+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
@@ -30,7 +36,8 @@ initial returning value. When the AML tables implement this control method
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
+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
@@ -39,18 +46,22 @@ state is changed to "closed". The "closed" notification is normally used to
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
+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 +70,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 +96,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 +106,7 @@ C. button.lid_init_state=ignore:
notifications can be delivered to the userspace when the lid is actually
opens given that some AML tables do not send "opened" notifications
reliably.
+
In this mode, if everything is correctly implemented by the platform
firmware, the old userspace programs should still work. Otherwise, the
new userspace programs are required to work with the ACPI button driver.
diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst
index 1c89888f6ee8..bedcb0b242a2 100644
--- a/Documentation/firmware-guide/acpi/index.rst
+++ b/Documentation/firmware-guide/acpi/index.rst
@@ -14,3 +14,4 @@ ACPI Support
DSD-properties-rules
gpio-properties
i2c-muxes
+ acpi-lid
\ No newline at end of file
--
2.20.1
^ permalink raw reply related
* [PATCH v6 14/24] Documentation: ACPI: move dsd/graph.txt to firmware-guide/acpi and convert to reST
From: Changbin Du @ 2019-04-25 15:31 UTC (permalink / raw)
To: rjw, Jonathan Corbet
Cc: fenghua.yu, mchehab+samsung, linux-doc, linux-gpio, linux-kernel,
linux-acpi, Bjorn Helgaas, linuxppc-dev, Changbin Du
In-Reply-To: <20190425153117.16057-1-changbin.du@gmail.com>
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../acpi/dsd/graph.rst} | 157 +++++++++---------
Documentation/firmware-guide/acpi/index.rst | 1 +
2 files changed, 81 insertions(+), 77 deletions(-)
rename Documentation/{acpi/dsd/graph.txt => firmware-guide/acpi/dsd/graph.rst} (56%)
diff --git a/Documentation/acpi/dsd/graph.txt b/Documentation/firmware-guide/acpi/dsd/graph.rst
similarity index 56%
rename from Documentation/acpi/dsd/graph.txt
rename to Documentation/firmware-guide/acpi/dsd/graph.rst
index b9ce910781dc..e0baed35b037 100644
--- a/Documentation/acpi/dsd/graph.txt
+++ b/Documentation/firmware-guide/acpi/dsd/graph.rst
@@ -1,8 +1,11 @@
-Graphs
+.. SPDX-License-Identifier: GPL-2.0
+======
+Graphs
+======
_DSD
-----
+====
_DSD (Device Specific Data) [7] is a predefined ACPI device
configuration object that can be used to convey information on
@@ -30,7 +33,7 @@ hierarchical data extension array on each depth.
Ports and endpoints
--------------------
+===================
The port and endpoint concepts are very similar to those in Devicetree
[3]. A port represents an interface in a device, and an endpoint
@@ -38,9 +41,9 @@ represents a connection to that interface.
All port nodes are located under the device's "_DSD" node in the hierarchical
data extension tree. The data extension related to each port node must begin
-with "port" and must be followed by the "@" character and the number of the port
-as its key. The target object it refers to should be called "PRTX", where "X" is
-the number of the port. An example of such a package would be:
+with "port" and must be followed by the "@" character and the number of the
+port as its key. The target object it refers to should be called "PRTX", where
+"X" is the number of the port. An example of such a package would be::
Package() { "port@4", PRT4 }
@@ -49,7 +52,7 @@ data extension key of the endpoint nodes must begin with
"endpoint" and must be followed by the "@" character and the number of the
endpoint. The object it refers to should be called "EPXY", where "X" is the
number of the port and "Y" is the number of the endpoint. An example of such a
-package would be:
+package would be::
Package() { "endpoint@0", EP40 }
@@ -62,85 +65,85 @@ of that port shall be zero. Similarly, if a port may only have a single
endpoint, the number of that endpoint shall be zero.
The endpoint reference uses property extension with "remote-endpoint" property
-name followed by a reference in the same package. Such references consist of the
+name followed by a reference in the same package. Such references consist of
the remote device reference, the first package entry of the port data extension
reference under the device and finally the first package entry of the endpoint
-data extension reference under the port. Individual references thus appear as:
+data extension reference under the port. Individual references thus appear as::
Package() { device, "port@X", "endpoint@Y" }
-In the above example, "X" is the number of the port and "Y" is the number of the
-endpoint.
+In the above example, "X" is the number of the port and "Y" is the number of
+the endpoint.
The references to endpoints must be always done both ways, to the
remote endpoint and back from the referred remote endpoint node.
-A simple example of this is show below:
+A simple example of this is show below::
Scope (\_SB.PCI0.I2C2)
{
- Device (CAM0)
- {
- Name (_DSD, Package () {
- ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
- Package () {
- Package () { "compatible", Package () { "nokia,smia" } },
- },
- ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
- Package () {
- Package () { "port@0", PRT0 },
- }
- })
- Name (PRT0, Package() {
- ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
- Package () {
- Package () { "reg", 0 },
- },
- ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
- Package () {
- Package () { "endpoint@0", EP00 },
- }
- })
- Name (EP00, Package() {
- ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
- Package () {
- Package () { "reg", 0 },
- Package () { "remote-endpoint", Package() { \_SB.PCI0.ISP, "port@4", "endpoint@0" } },
- }
- })
- }
+ Device (CAM0)
+ {
+ Name (_DSD, Package () {
+ ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+ Package () {
+ Package () { "compatible", Package () { "nokia,smia" } },
+ },
+ ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
+ Package () {
+ Package () { "port@0", PRT0 },
+ }
+ })
+ Name (PRT0, Package() {
+ ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+ Package () {
+ Package () { "reg", 0 },
+ },
+ ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
+ Package () {
+ Package () { "endpoint@0", EP00 },
+ }
+ })
+ Name (EP00, Package() {
+ ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+ Package () {
+ Package () { "reg", 0 },
+ Package () { "remote-endpoint", Package() { \_SB.PCI0.ISP, "port@4", "endpoint@0" } },
+ }
+ })
+ }
}
Scope (\_SB.PCI0)
{
- Device (ISP)
- {
- Name (_DSD, Package () {
- ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
- Package () {
- Package () { "port@4", PRT4 },
- }
- })
-
- Name (PRT4, Package() {
- ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
- Package () {
- Package () { "reg", 4 }, /* CSI-2 port number */
- },
- ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
- Package () {
- Package () { "endpoint@0", EP40 },
- }
- })
-
- Name (EP40, Package() {
- ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
- Package () {
- Package () { "reg", 0 },
- Package () { "remote-endpoint", Package () { \_SB.PCI0.I2C2.CAM0, "port@0", "endpoint@0" } },
- }
- })
- }
+ Device (ISP)
+ {
+ Name (_DSD, Package () {
+ ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
+ Package () {
+ Package () { "port@4", PRT4 },
+ }
+ })
+
+ Name (PRT4, Package() {
+ ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+ Package () {
+ Package () { "reg", 4 }, /* CSI-2 port number */
+ },
+ ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
+ Package () {
+ Package () { "endpoint@0", EP40 },
+ }
+ })
+
+ Name (EP40, Package() {
+ ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+ Package () {
+ Package () { "reg", 0 },
+ Package () { "remote-endpoint", Package () { \_SB.PCI0.I2C2.CAM0, "port@0", "endpoint@0" } },
+ }
+ })
+ }
}
Here, the port 0 of the "CAM0" device is connected to the port 4 of
@@ -148,27 +151,27 @@ the "ISP" device and vice versa.
References
-----------
+==========
[1] _DSD (Device Specific Data) Implementation Guide.
- <URL:http://www.uefi.org/sites/default/files/resources/_DSD-implementation-guide-toplevel-1_1.htm>,
+ http://www.uefi.org/sites/default/files/resources/_DSD-implementation-guide-toplevel-1_1.htm,
referenced 2016-10-03.
-[2] Devicetree. <URL:http://www.devicetree.org>, referenced 2016-10-03.
+[2] Devicetree. http://www.devicetree.org, referenced 2016-10-03.
[3] Documentation/devicetree/bindings/graph.txt
[4] Device Properties UUID For _DSD.
- <URL:http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>,
+ http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf,
referenced 2016-10-04.
[5] Hierarchical Data Extension UUID For _DSD.
- <URL:http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>,
+ http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf,
referenced 2016-10-04.
[6] Advanced Configuration and Power Interface Specification.
- <URL:http://www.uefi.org/sites/default/files/resources/ACPI_6_1.pdf>,
+ http://www.uefi.org/sites/default/files/resources/ACPI_6_1.pdf,
referenced 2016-10-04.
[7] _DSD Device Properties Usage Rules.
- Documentation/acpi/DSD-properties-rules.txt
+ :doc:`../DSD-properties-rules`
diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst
index bedcb0b242a2..f81cfbcb6878 100644
--- a/Documentation/firmware-guide/acpi/index.rst
+++ b/Documentation/firmware-guide/acpi/index.rst
@@ -8,6 +8,7 @@ ACPI Support
:maxdepth: 1
namespace
+ dsd/graph
enumeration
osi
method-customizing
--
2.20.1
^ permalink raw reply related
* [PATCH v6 15/24] Documentation: ACPI: move dsd/data-node-references.txt to firmware-guide/acpi and convert to reST
From: Changbin Du @ 2019-04-25 15:31 UTC (permalink / raw)
To: rjw, Jonathan Corbet
Cc: fenghua.yu, mchehab+samsung, linux-doc, linux-gpio, linux-kernel,
linux-acpi, Bjorn Helgaas, linuxppc-dev, Changbin Du
In-Reply-To: <20190425153117.16057-1-changbin.du@gmail.com>
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../acpi/dsd/data-node-references.rst} | 36 ++++++++++---------
Documentation/firmware-guide/acpi/index.rst | 1 +
2 files changed, 21 insertions(+), 16 deletions(-)
rename Documentation/{acpi/dsd/data-node-references.txt => firmware-guide/acpi/dsd/data-node-references.rst} (71%)
diff --git a/Documentation/acpi/dsd/data-node-references.txt b/Documentation/firmware-guide/acpi/dsd/data-node-references.rst
similarity index 71%
rename from Documentation/acpi/dsd/data-node-references.txt
rename to Documentation/firmware-guide/acpi/dsd/data-node-references.rst
index c3871565c8cf..1351984e767c 100644
--- a/Documentation/acpi/dsd/data-node-references.txt
+++ b/Documentation/firmware-guide/acpi/dsd/data-node-references.rst
@@ -1,9 +1,12 @@
-Copyright (C) 2018 Intel Corporation
-Author: Sakari Ailus <sakari.ailus@linux.intel.com>
-
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
+===================================
Referencing hierarchical data nodes
------------------------------------
+===================================
+
+:Copyright: |copy| 2018 Intel Corporation
+:Author: Sakari Ailus <sakari.ailus@linux.intel.com>
ACPI in general allows referring to device objects in the tree only.
Hierarchical data extension nodes may not be referred to directly, hence this
@@ -28,13 +31,14 @@ extension key.
Example
--------
+=======
- In the ASL snippet below, the "reference" _DSD property [2] contains a
- device object reference to DEV0 and under that device object, a
- hierarchical data extension key "node@1" referring to the NOD1 object
- and lastly, a hierarchical data extension key "anothernode" referring to
- the ANOD object which is also the final target node of the reference.
+In the ASL snippet below, the "reference" _DSD property [2] contains a
+device object reference to DEV0 and under that device object, a
+hierarchical data extension key "node@1" referring to the NOD1 object
+and lastly, a hierarchical data extension key "anothernode" referring to
+the ANOD object which is also the final target node of the reference.
+::
Device (DEV0)
{
@@ -75,15 +79,15 @@ 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>,
- referenced 2018-07-17.
+<http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>,
+referenced 2018-07-17.
[2] Device Properties UUID For _DSD.
- <URL:http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>,
- referenced 2016-10-04.
+<http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>,
+referenced 2016-10-04.
diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst
index f81cfbcb6878..6d4e0df4f063 100644
--- a/Documentation/firmware-guide/acpi/index.rst
+++ b/Documentation/firmware-guide/acpi/index.rst
@@ -9,6 +9,7 @@ ACPI Support
namespace
dsd/graph
+ dsd/data-node-references
enumeration
osi
method-customizing
--
2.20.1
^ permalink raw reply related
* [PATCH v6 16/24] Documentation: ACPI: move debug.txt to firmware-guide/acpi and convert to reST
From: Changbin Du @ 2019-04-25 15:31 UTC (permalink / raw)
To: rjw, Jonathan Corbet
Cc: fenghua.yu, mchehab+samsung, linux-doc, linux-gpio, linux-kernel,
linux-acpi, Bjorn Helgaas, linuxppc-dev, Changbin Du
In-Reply-To: <20190425153117.16057-1-changbin.du@gmail.com>
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../acpi/debug.rst} | 31 ++++++++++---------
Documentation/firmware-guide/acpi/index.rst | 3 +-
2 files changed, 19 insertions(+), 15 deletions(-)
rename Documentation/{acpi/debug.txt => firmware-guide/acpi/debug.rst} (91%)
diff --git a/Documentation/acpi/debug.txt b/Documentation/firmware-guide/acpi/debug.rst
similarity index 91%
rename from Documentation/acpi/debug.txt
rename to Documentation/firmware-guide/acpi/debug.rst
index 65bf47c46b6d..1a152dd1d765 100644
--- a/Documentation/acpi/debug.txt
+++ b/Documentation/firmware-guide/acpi/debug.rst
@@ -1,18 +1,21 @@
- ACPI Debug Output
+.. SPDX-License-Identifier: GPL-2.0
+=================
+ACPI Debug Output
+=================
The ACPI CA, the Linux ACPI core, and some ACPI drivers can generate debug
output. This document describes how to use this facility.
Compile-time configuration
---------------------------
+==========================
ACPI debug output is globally enabled by CONFIG_ACPI_DEBUG. If this config
option is turned off, the debug messages are not even built into the
kernel.
Boot- and run-time configuration
---------------------------------
+================================
When CONFIG_ACPI_DEBUG=y, you can select the component and level of messages
you're interested in. At boot-time, use the acpi.debug_layer and
@@ -21,7 +24,7 @@ debug_layer and debug_level files in /sys/module/acpi/parameters/ to control
the debug messages.
debug_layer (component)
------------------------
+=======================
The "debug_layer" is a mask that selects components of interest, e.g., a
specific driver or part of the ACPI interpreter. To build the debug_layer
@@ -33,7 +36,7 @@ to /sys/module/acpi/parameters/debug_layer.
The possible components are defined in include/acpi/acoutput.h and
include/acpi/acpi_drivers.h. Reading /sys/module/acpi/parameters/debug_layer
-shows the supported mask values, currently these:
+shows the supported mask values, currently these::
ACPI_UTILITIES 0x00000001
ACPI_HARDWARE 0x00000002
@@ -65,7 +68,7 @@ shows the supported mask values, currently these:
ACPI_PROCESSOR_COMPONENT 0x20000000
debug_level
------------
+===========
The "debug_level" is a mask that selects different types of messages, e.g.,
those related to initialization, method execution, informational messages, etc.
@@ -81,7 +84,7 @@ to /sys/module/acpi/parameters/debug_level.
The possible levels are defined in include/acpi/acoutput.h. Reading
/sys/module/acpi/parameters/debug_level shows the supported mask values,
-currently these:
+currently these::
ACPI_LV_INIT 0x00000001
ACPI_LV_DEBUG_OBJECT 0x00000002
@@ -113,9 +116,9 @@ currently these:
ACPI_LV_EVENTS 0x80000000
Examples
---------
+========
-For example, drivers/acpi/bus.c contains this:
+For example, drivers/acpi/bus.c contains this::
#define _COMPONENT ACPI_BUS_COMPONENT
...
@@ -127,22 +130,22 @@ statement uses ACPI_DB_INFO, which is macro based on the ACPI_LV_INFO
definition.)
Enable all AML "Debug" output (stores to the Debug object while interpreting
-AML) during boot:
+AML) during boot::
acpi.debug_layer=0xffffffff acpi.debug_level=0x2
-Enable PCI and PCI interrupt routing debug messages:
+Enable PCI and PCI interrupt routing debug messages::
acpi.debug_layer=0x400000 acpi.debug_level=0x4
-Enable all ACPI hardware-related messages:
+Enable all ACPI hardware-related messages::
acpi.debug_layer=0x2 acpi.debug_level=0xffffffff
-Enable all ACPI_DB_INFO messages after boot:
+Enable all ACPI_DB_INFO messages after boot::
# echo 0x4 > /sys/module/acpi/parameters/debug_level
-Show all valid component values:
+Show all valid component values::
# cat /sys/module/acpi/parameters/debug_layer
diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst
index 6d4e0df4f063..a45fea11f998 100644
--- a/Documentation/firmware-guide/acpi/index.rst
+++ b/Documentation/firmware-guide/acpi/index.rst
@@ -14,6 +14,7 @@ ACPI Support
osi
method-customizing
DSD-properties-rules
+ debug
gpio-properties
i2c-muxes
- acpi-lid
\ No newline at end of file
+ acpi-lid
--
2.20.1
^ permalink raw reply related
* [PATCH v6 17/24] Documentation: ACPI: move method-tracing.txt to firmware-guide/acpi and convert to rsST
From: Changbin Du @ 2019-04-25 15:31 UTC (permalink / raw)
To: rjw, Jonathan Corbet
Cc: fenghua.yu, mchehab+samsung, linux-doc, linux-gpio, linux-kernel,
linux-acpi, Bjorn Helgaas, linuxppc-dev, Changbin Du
In-Reply-To: <20190425153117.16057-1-changbin.du@gmail.com>
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/acpi/method-tracing.txt | 192 --------------
Documentation/firmware-guide/acpi/index.rst | 1 +
.../firmware-guide/acpi/method-tracing.rst | 238 ++++++++++++++++++
3 files changed, 239 insertions(+), 192 deletions(-)
delete mode 100644 Documentation/acpi/method-tracing.txt
create mode 100644 Documentation/firmware-guide/acpi/method-tracing.rst
diff --git a/Documentation/acpi/method-tracing.txt b/Documentation/acpi/method-tracing.txt
deleted file mode 100644
index 0aba14c8f459..000000000000
--- a/Documentation/acpi/method-tracing.txt
+++ /dev/null
@@ -1,192 +0,0 @@
-ACPICA Trace Facility
-
-Copyright (C) 2015, Intel Corporation
-Author: Lv Zheng <lv.zheng@intel.com>
-
-
-Abstract:
-
-This document describes the functions and the interfaces of the method
-tracing facility.
-
-1. Functionalities and usage examples:
-
- ACPICA provides method tracing capability. And two functions are
- currently implemented using this capability.
-
- A. Log reducer
- ACPICA subsystem provides debugging outputs when CONFIG_ACPI_DEBUG is
- enabled. The debugging messages which are deployed via
- ACPI_DEBUG_PRINT() macro can be reduced at 2 levels - per-component
- level (known as debug layer, configured via
- /sys/module/acpi/parameters/debug_layer) and per-type level (known as
- debug level, configured via /sys/module/acpi/parameters/debug_level).
-
- But when the particular layer/level is applied to the control method
- evaluations, the quantity of the debugging outputs may still be too
- large to be put into the kernel log buffer. The idea thus is worked out
- to only enable the particular debug layer/level (normally more detailed)
- logs when the control method evaluation is started, and disable the
- detailed logging when the control method evaluation is stopped.
-
- The following command examples illustrate the usage of the "log reducer"
- functionality:
- a. Filter out the debug layer/level matched logs when control methods
- are being evaluated:
- # cd /sys/module/acpi/parameters
- # echo "0xXXXXXXXX" > trace_debug_layer
- # echo "0xYYYYYYYY" > trace_debug_level
- # echo "enable" > trace_state
- b. Filter out the debug layer/level matched logs when the specified
- control method is being evaluated:
- # cd /sys/module/acpi/parameters
- # echo "0xXXXXXXXX" > trace_debug_layer
- # echo "0xYYYYYYYY" > trace_debug_level
- # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
- # echo "method" > /sys/module/acpi/parameters/trace_state
- c. Filter out the debug layer/level matched logs when the specified
- control method is being evaluated for the first time:
- # cd /sys/module/acpi/parameters
- # echo "0xXXXXXXXX" > trace_debug_layer
- # echo "0xYYYYYYYY" > trace_debug_level
- # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
- # echo "method-once" > /sys/module/acpi/parameters/trace_state
- Where:
- 0xXXXXXXXX/0xYYYYYYYY: Refer to Documentation/acpi/debug.txt for
- possible debug layer/level masking values.
- \PPPP.AAAA.TTTT.HHHH: Full path of a control method that can be found
- in the ACPI namespace. It needn't be an entry
- of a control method evaluation.
-
- B. AML tracer
-
- There are special log entries added by the method tracing facility at
- the "trace points" the AML interpreter starts/stops to execute a control
- method, or an AML opcode. Note that the format of the log entries are
- subject to change:
- [ 0.186427] exdebug-0398 ex_trace_point : Method Begin [0xf58394d8:\_SB.PCI0.LPCB.ECOK] execution.
- [ 0.186630] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905c88:If] execution.
- [ 0.186820] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905cc0:LEqual] execution.
- [ 0.187010] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905a20:-NamePath-] execution.
- [ 0.187214] exdebug-0398 ex_trace_point : Opcode End [0xf5905a20:-NamePath-] execution.
- [ 0.187407] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905f60:One] execution.
- [ 0.187594] exdebug-0398 ex_trace_point : Opcode End [0xf5905f60:One] execution.
- [ 0.187789] exdebug-0398 ex_trace_point : Opcode End [0xf5905cc0:LEqual] execution.
- [ 0.187980] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905cc0:Return] execution.
- [ 0.188146] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905f60:One] execution.
- [ 0.188334] exdebug-0398 ex_trace_point : Opcode End [0xf5905f60:One] execution.
- [ 0.188524] exdebug-0398 ex_trace_point : Opcode End [0xf5905cc0:Return] execution.
- [ 0.188712] exdebug-0398 ex_trace_point : Opcode End [0xf5905c88:If] execution.
- [ 0.188903] exdebug-0398 ex_trace_point : Method End [0xf58394d8:\_SB.PCI0.LPCB.ECOK] execution.
-
- Developers can utilize these special log entries to track the AML
- interpretion, thus can aid issue debugging and performance tuning. Note
- that, as the "AML tracer" logs are implemented via ACPI_DEBUG_PRINT()
- macro, CONFIG_ACPI_DEBUG is also required to be enabled for enabling
- "AML tracer" logs.
-
- The following command examples illustrate the usage of the "AML tracer"
- functionality:
- a. Filter out the method start/stop "AML tracer" logs when control
- methods are being evaluated:
- # cd /sys/module/acpi/parameters
- # echo "0x80" > trace_debug_layer
- # echo "0x10" > trace_debug_level
- # echo "enable" > trace_state
- b. Filter out the method start/stop "AML tracer" when the specified
- control method is being evaluated:
- # cd /sys/module/acpi/parameters
- # echo "0x80" > trace_debug_layer
- # echo "0x10" > trace_debug_level
- # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
- # echo "method" > trace_state
- c. Filter out the method start/stop "AML tracer" logs when the specified
- control method is being evaluated for the first time:
- # cd /sys/module/acpi/parameters
- # echo "0x80" > trace_debug_layer
- # echo "0x10" > trace_debug_level
- # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
- # echo "method-once" > trace_state
- d. Filter out the method/opcode start/stop "AML tracer" when the
- specified control method is being evaluated:
- # cd /sys/module/acpi/parameters
- # echo "0x80" > trace_debug_layer
- # echo "0x10" > trace_debug_level
- # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
- # echo "opcode" > trace_state
- e. Filter out the method/opcode start/stop "AML tracer" when the
- specified control method is being evaluated for the first time:
- # cd /sys/module/acpi/parameters
- # echo "0x80" > trace_debug_layer
- # echo "0x10" > trace_debug_level
- # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
- # echo "opcode-opcode" > trace_state
-
- Note that all above method tracing facility related module parameters can
- be used as the boot parameters, for example:
- acpi.trace_debug_layer=0x80 acpi.trace_debug_level=0x10 \
- acpi.trace_method_name=\_SB.LID0._LID acpi.trace_state=opcode-once
-
-2. Interface descriptions:
-
- All method tracing functions can be configured via ACPI module
- parameters that are accessible at /sys/module/acpi/parameters/:
-
- trace_method_name
- The full path of the AML method that the user wants to trace.
- Note that the full path shouldn't contain the trailing "_"s in its
- name segments but may contain "\" to form an absolute path.
-
- trace_debug_layer
- The temporary debug_layer used when the tracing feature is enabled.
- Using ACPI_EXECUTER (0x80) by default, which is the debug_layer
- used to match all "AML tracer" logs.
-
- trace_debug_level
- The temporary debug_level used when the tracing feature is enabled.
- Using ACPI_LV_TRACE_POINT (0x10) by default, which is the
- debug_level used to match all "AML tracer" logs.
-
- trace_state
- The status of the tracing feature.
- Users can enable/disable this debug tracing feature by executing
- the following command:
- # echo string > /sys/module/acpi/parameters/trace_state
- Where "string" should be one of the following:
- "disable"
- Disable the method tracing feature.
- "enable"
- Enable the method tracing feature.
- ACPICA debugging messages matching
- "trace_debug_layer/trace_debug_level" during any method
- execution will be logged.
- "method"
- Enable the method tracing feature.
- ACPICA debugging messages matching
- "trace_debug_layer/trace_debug_level" during method execution
- of "trace_method_name" will be logged.
- "method-once"
- Enable the method tracing feature.
- ACPICA debugging messages matching
- "trace_debug_layer/trace_debug_level" during method execution
- of "trace_method_name" will be logged only once.
- "opcode"
- Enable the method tracing feature.
- ACPICA debugging messages matching
- "trace_debug_layer/trace_debug_level" during method/opcode
- execution of "trace_method_name" will be logged.
- "opcode-once"
- Enable the method tracing feature.
- ACPICA debugging messages matching
- "trace_debug_layer/trace_debug_level" during method/opcode
- execution of "trace_method_name" will be logged only once.
- Note that, the difference between the "enable" and other feature
- enabling options are:
- 1. When "enable" is specified, since
- "trace_debug_layer/trace_debug_level" shall apply to all control
- method evaluations, after configuring "trace_state" to "enable",
- "trace_method_name" will be reset to NULL.
- 2. When "method/opcode" is specified, if
- "trace_method_name" is NULL when "trace_state" is configured to
- these options, the "trace_debug_layer/trace_debug_level" will
- apply to all control method evaluations.
diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst
index a45fea11f998..287a7cbd82ac 100644
--- a/Documentation/firmware-guide/acpi/index.rst
+++ b/Documentation/firmware-guide/acpi/index.rst
@@ -13,6 +13,7 @@ ACPI Support
enumeration
osi
method-customizing
+ method-tracing
DSD-properties-rules
debug
gpio-properties
diff --git a/Documentation/firmware-guide/acpi/method-tracing.rst b/Documentation/firmware-guide/acpi/method-tracing.rst
new file mode 100644
index 000000000000..d0b077b73f5f
--- /dev/null
+++ b/Documentation/firmware-guide/acpi/method-tracing.rst
@@ -0,0 +1,238 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
+
+=====================
+ACPICA Trace Facility
+=====================
+
+:Copyright: |copy| 2015, Intel Corporation
+:Author: Lv Zheng <lv.zheng@intel.com>
+
+
+Abstract
+========
+This document describes the functions and the interfaces of the
+method tracing facility.
+
+Functionalities and usage examples
+==================================
+
+ACPICA provides method tracing capability. And two functions are
+currently implemented using this capability.
+
+Log reducer
+-----------
+
+ACPICA subsystem provides debugging outputs when CONFIG_ACPI_DEBUG is
+enabled. The debugging messages which are deployed via
+ACPI_DEBUG_PRINT() macro can be reduced at 2 levels - per-component
+level (known as debug layer, configured via
+/sys/module/acpi/parameters/debug_layer) and per-type level (known as
+debug level, configured via /sys/module/acpi/parameters/debug_level).
+
+But when the particular layer/level is applied to the control method
+evaluations, the quantity of the debugging outputs may still be too
+large to be put into the kernel log buffer. The idea thus is worked out
+to only enable the particular debug layer/level (normally more detailed)
+logs when the control method evaluation is started, and disable the
+detailed logging when the control method evaluation is stopped.
+
+The following command examples illustrate the usage of the "log reducer"
+functionality:
+
+a. Filter out the debug layer/level matched logs when control methods
+ are being evaluated::
+
+ # cd /sys/module/acpi/parameters
+ # echo "0xXXXXXXXX" > trace_debug_layer
+ # echo "0xYYYYYYYY" > trace_debug_level
+ # echo "enable" > trace_state
+
+b. Filter out the debug layer/level matched logs when the specified
+ control method is being evaluated::
+
+ # cd /sys/module/acpi/parameters
+ # echo "0xXXXXXXXX" > trace_debug_layer
+ # echo "0xYYYYYYYY" > trace_debug_level
+ # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
+ # echo "method" > /sys/module/acpi/parameters/trace_state
+
+c. Filter out the debug layer/level matched logs when the specified
+ control method is being evaluated for the first time::
+
+ # cd /sys/module/acpi/parameters
+ # echo "0xXXXXXXXX" > trace_debug_layer
+ # echo "0xYYYYYYYY" > trace_debug_level
+ # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
+ # echo "method-once" > /sys/module/acpi/parameters/trace_state
+
+Where:
+ 0xXXXXXXXX/0xYYYYYYYY
+ Refer to Documentation/acpi/debug.txt for possible debug layer/level
+ masking values.
+ \PPPP.AAAA.TTTT.HHHH
+ Full path of a control method that can be found in the ACPI namespace.
+ It needn't be an entry of a control method evaluation.
+
+AML tracer
+----------
+
+There are special log entries added by the method tracing facility at
+the "trace points" the AML interpreter starts/stops to execute a control
+method, or an AML opcode. Note that the format of the log entries are
+subject to change::
+
+ [ 0.186427] exdebug-0398 ex_trace_point : Method Begin [0xf58394d8:\_SB.PCI0.LPCB.ECOK] execution.
+ [ 0.186630] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905c88:If] execution.
+ [ 0.186820] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905cc0:LEqual] execution.
+ [ 0.187010] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905a20:-NamePath-] execution.
+ [ 0.187214] exdebug-0398 ex_trace_point : Opcode End [0xf5905a20:-NamePath-] execution.
+ [ 0.187407] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905f60:One] execution.
+ [ 0.187594] exdebug-0398 ex_trace_point : Opcode End [0xf5905f60:One] execution.
+ [ 0.187789] exdebug-0398 ex_trace_point : Opcode End [0xf5905cc0:LEqual] execution.
+ [ 0.187980] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905cc0:Return] execution.
+ [ 0.188146] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905f60:One] execution.
+ [ 0.188334] exdebug-0398 ex_trace_point : Opcode End [0xf5905f60:One] execution.
+ [ 0.188524] exdebug-0398 ex_trace_point : Opcode End [0xf5905cc0:Return] execution.
+ [ 0.188712] exdebug-0398 ex_trace_point : Opcode End [0xf5905c88:If] execution.
+ [ 0.188903] exdebug-0398 ex_trace_point : Method End [0xf58394d8:\_SB.PCI0.LPCB.ECOK] execution.
+
+Developers can utilize these special log entries to track the AML
+interpretion, thus can aid issue debugging and performance tuning. Note
+that, as the "AML tracer" logs are implemented via ACPI_DEBUG_PRINT()
+macro, CONFIG_ACPI_DEBUG is also required to be enabled for enabling
+"AML tracer" logs.
+
+The following command examples illustrate the usage of the "AML tracer"
+functionality:
+
+a. Filter out the method start/stop "AML tracer" logs when control
+ methods are being evaluated::
+
+ # cd /sys/module/acpi/parameters
+ # echo "0x80" > trace_debug_layer
+ # echo "0x10" > trace_debug_level
+ # echo "enable" > trace_state
+
+b. Filter out the method start/stop "AML tracer" when the specified
+ control method is being evaluated::
+
+ # cd /sys/module/acpi/parameters
+ # echo "0x80" > trace_debug_layer
+ # echo "0x10" > trace_debug_level
+ # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
+ # echo "method" > trace_state
+
+c. Filter out the method start/stop "AML tracer" logs when the specified
+ control method is being evaluated for the first time::
+
+ # cd /sys/module/acpi/parameters
+ # echo "0x80" > trace_debug_layer
+ # echo "0x10" > trace_debug_level
+ # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
+ # echo "method-once" > trace_state
+
+d. Filter out the method/opcode start/stop "AML tracer" when the
+ specified control method is being evaluated::
+
+ # cd /sys/module/acpi/parameters
+ # echo "0x80" > trace_debug_layer
+ # echo "0x10" > trace_debug_level
+ # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
+ # echo "opcode" > trace_state
+
+e. Filter out the method/opcode start/stop "AML tracer" when the
+ specified control method is being evaluated for the first time::
+
+ # cd /sys/module/acpi/parameters
+ # echo "0x80" > trace_debug_layer
+ # echo "0x10" > trace_debug_level
+ # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
+ # echo "opcode-opcode" > trace_state
+
+Note that all above method tracing facility related module parameters can
+be used as the boot parameters, for example::
+
+ acpi.trace_debug_layer=0x80 acpi.trace_debug_level=0x10 \
+ acpi.trace_method_name=\_SB.LID0._LID acpi.trace_state=opcode-once
+
+
+Interface descriptions
+======================
+
+All method tracing functions can be configured via ACPI module
+parameters that are accessible at /sys/module/acpi/parameters/:
+
+trace_method_name
+ The full path of the AML method that the user wants to trace.
+
+ Note that the full path shouldn't contain the trailing "_"s in its
+ name segments but may contain "\" to form an absolute path.
+
+trace_debug_layer
+ The temporary debug_layer used when the tracing feature is enabled.
+
+ Using ACPI_EXECUTER (0x80) by default, which is the debug_layer
+ used to match all "AML tracer" logs.
+
+trace_debug_level
+ The temporary debug_level used when the tracing feature is enabled.
+
+ Using ACPI_LV_TRACE_POINT (0x10) by default, which is the
+ debug_level used to match all "AML tracer" logs.
+
+trace_state
+ The status of the tracing feature.
+
+ Users can enable/disable this debug tracing feature by executing
+ the following command::
+
+ # echo string > /sys/module/acpi/parameters/trace_state
+
+Where "string" should be one of the following:
+
+"disable"
+ Disable the method tracing feature.
+
+"enable"
+ Enable the method tracing feature.
+
+ ACPICA debugging messages matching "trace_debug_layer/trace_debug_level"
+ during any method execution will be logged.
+
+"method"
+ Enable the method tracing feature.
+
+ ACPICA debugging messages matching "trace_debug_layer/trace_debug_level"
+ during method execution of "trace_method_name" will be logged.
+
+"method-once"
+ Enable the method tracing feature.
+
+ ACPICA debugging messages matching "trace_debug_layer/trace_debug_level"
+ during method execution of "trace_method_name" will be logged only once.
+
+"opcode"
+ Enable the method tracing feature.
+
+ ACPICA debugging messages matching "trace_debug_layer/trace_debug_level"
+ during method/opcode execution of "trace_method_name" will be logged.
+
+"opcode-once"
+ Enable the method tracing feature.
+
+ ACPICA debugging messages matching "trace_debug_layer/trace_debug_level"
+ during method/opcode execution of "trace_method_name" will be logged only
+ once.
+
+Note that, the difference between the "enable" and other feature
+enabling options are:
+
+1. When "enable" is specified, since
+ "trace_debug_layer/trace_debug_level" shall apply to all control
+ method evaluations, after configuring "trace_state" to "enable",
+ "trace_method_name" will be reset to NULL.
+2. When "method/opcode" is specified, if
+ "trace_method_name" is NULL when "trace_state" is configured to
+ these options, the "trace_debug_layer/trace_debug_level" will
+ apply to all control method evaluations.
--
2.20.1
^ permalink raw reply related
* [PATCH v6 18/24] Documentation: ACPI: move aml-debugger.txt to firmware-guide/acpi and convert to reST
From: Changbin Du @ 2019-04-25 15:31 UTC (permalink / raw)
To: rjw, Jonathan Corbet
Cc: fenghua.yu, mchehab+samsung, linux-doc, linux-gpio, linux-kernel,
linux-acpi, Bjorn Helgaas, linuxppc-dev, Changbin Du
In-Reply-To: <20190425153117.16057-1-changbin.du@gmail.com>
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/acpi/aml-debugger.txt | 66 ----------------
.../firmware-guide/acpi/aml-debugger.rst | 75 +++++++++++++++++++
Documentation/firmware-guide/acpi/index.rst | 1 +
3 files changed, 76 insertions(+), 66 deletions(-)
delete mode 100644 Documentation/acpi/aml-debugger.txt
create mode 100644 Documentation/firmware-guide/acpi/aml-debugger.rst
diff --git a/Documentation/acpi/aml-debugger.txt b/Documentation/acpi/aml-debugger.txt
deleted file mode 100644
index 75ebeb64ab29..000000000000
--- a/Documentation/acpi/aml-debugger.txt
+++ /dev/null
@@ -1,66 +0,0 @@
-The AML Debugger
-
-Copyright (C) 2016, Intel Corporation
-Author: Lv Zheng <lv.zheng@intel.com>
-
-
-This document describes the usage of the AML debugger embedded in the Linux
-kernel.
-
-1. Build the debugger
-
- The following kernel configuration items are required to enable the AML
- debugger interface from the Linux kernel:
-
- CONFIG_ACPI_DEBUGGER=y
- CONFIG_ACPI_DEBUGGER_USER=m
-
- The userspace utilities can be built from the kernel source tree using
- the following commands:
-
- $ cd tools
- $ make acpi
-
- The resultant userspace tool binary is then located at:
-
- tools/power/acpi/acpidbg
-
- It can be installed to system directories by running "make install" (as a
- sufficiently privileged user).
-
-2. Start the userspace debugger interface
-
- After booting the kernel with the debugger built-in, the debugger can be
- started by using the following commands:
-
- # mount -t debugfs none /sys/kernel/debug
- # modprobe acpi_dbg
- # tools/power/acpi/acpidbg
-
- That spawns the interactive AML debugger environment where you can execute
- debugger commands.
-
- The commands are documented in the "ACPICA Overview and Programmer Reference"
- that can be downloaded from
-
- https://acpica.org/documentation
-
- The detailed debugger commands reference is located in Chapter 12 "ACPICA
- Debugger Reference". The "help" command can be used for a quick reference.
-
-3. Stop the userspace debugger interface
-
- The interactive debugger interface can be closed by pressing Ctrl+C or using
- the "quit" or "exit" commands. When finished, unload the module with:
-
- # rmmod acpi_dbg
-
- The module unloading may fail if there is an acpidbg instance running.
-
-4. Run the debugger in a script
-
- It may be useful to run the AML debugger in a test script. "acpidbg" supports
- this in a special "batch" mode. For example, the following command outputs
- the entire ACPI namespace:
-
- # acpidbg -b "namespace"
diff --git a/Documentation/firmware-guide/acpi/aml-debugger.rst b/Documentation/firmware-guide/acpi/aml-debugger.rst
new file mode 100644
index 000000000000..a889d43bc6c5
--- /dev/null
+++ b/Documentation/firmware-guide/acpi/aml-debugger.rst
@@ -0,0 +1,75 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
+
+================
+The AML Debugger
+================
+
+:Copyright: |copy| 2016, Intel Corporation
+:Author: Lv Zheng <lv.zheng@intel.com>
+
+
+This document describes the usage of the AML debugger embedded in the Linux
+kernel.
+
+1. Build the debugger
+=====================
+
+The following kernel configuration items are required to enable the AML
+debugger interface from the Linux kernel::
+
+ CONFIG_ACPI_DEBUGGER=y
+ CONFIG_ACPI_DEBUGGER_USER=m
+
+The userspace utilities can be built from the kernel source tree using
+the following commands::
+
+ $ cd tools
+ $ make acpi
+
+The resultant userspace tool binary is then located at::
+
+ tools/power/acpi/acpidbg
+
+It can be installed to system directories by running "make install" (as a
+sufficiently privileged user).
+
+2. Start the userspace debugger interface
+=========================================
+
+After booting the kernel with the debugger built-in, the debugger can be
+started by using the following commands::
+
+ # mount -t debugfs none /sys/kernel/debug
+ # modprobe acpi_dbg
+ # tools/power/acpi/acpidbg
+
+That spawns the interactive AML debugger environment where you can execute
+debugger commands.
+
+The commands are documented in the "ACPICA Overview and Programmer Reference"
+that can be downloaded from
+
+https://acpica.org/documentation
+
+The detailed debugger commands reference is located in Chapter 12 "ACPICA
+Debugger Reference". The "help" command can be used for a quick reference.
+
+3. Stop the userspace debugger interface
+========================================
+
+The interactive debugger interface can be closed by pressing Ctrl+C or using
+the "quit" or "exit" commands. When finished, unload the module with::
+
+ # rmmod acpi_dbg
+
+The module unloading may fail if there is an acpidbg instance running.
+
+4. Run the debugger in a script
+===============================
+
+It may be useful to run the AML debugger in a test script. "acpidbg" supports
+this in a special "batch" mode. For example, the following command outputs
+the entire ACPI namespace::
+
+ # acpidbg -b "namespace"
diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst
index 287a7cbd82ac..e9f253d54897 100644
--- a/Documentation/firmware-guide/acpi/index.rst
+++ b/Documentation/firmware-guide/acpi/index.rst
@@ -16,6 +16,7 @@ ACPI Support
method-tracing
DSD-properties-rules
debug
+ aml-debugger
gpio-properties
i2c-muxes
acpi-lid
--
2.20.1
^ permalink raw reply related
* [PATCH v6 19/24] Documentation: ACPI: move apei/output_format.txt to firmware-guide/acpi and convert to reST
From: Changbin Du @ 2019-04-25 15:31 UTC (permalink / raw)
To: rjw, Jonathan Corbet
Cc: fenghua.yu, mchehab+samsung, linux-doc, linux-gpio, linux-kernel,
linux-acpi, Bjorn Helgaas, linuxppc-dev, Changbin Du
In-Reply-To: <20190425153117.16057-1-changbin.du@gmail.com>
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/acpi/apei/output_format.txt | 147 -----------------
.../acpi/apei/output_format.rst | 150 ++++++++++++++++++
Documentation/firmware-guide/acpi/index.rst | 1 +
3 files changed, 151 insertions(+), 147 deletions(-)
delete mode 100644 Documentation/acpi/apei/output_format.txt
create mode 100644 Documentation/firmware-guide/acpi/apei/output_format.rst
diff --git a/Documentation/acpi/apei/output_format.txt b/Documentation/acpi/apei/output_format.txt
deleted file mode 100644
index 0c49c197c47a..000000000000
--- a/Documentation/acpi/apei/output_format.txt
+++ /dev/null
@@ -1,147 +0,0 @@
- APEI output format
- ~~~~~~~~~~~~~~~~~~
-
-APEI uses printk as hardware error reporting interface, the output
-format is as follow.
-
-<error record> :=
-APEI generic hardware error status
-severity: <integer>, <severity string>
-section: <integer>, severity: <integer>, <severity string>
-flags: <integer>
-<section flags strings>
-fru_id: <uuid string>
-fru_text: <string>
-section_type: <section type string>
-<section data>
-
-<severity string>* := recoverable | fatal | corrected | info
-
-<section flags strings># :=
-[primary][, containment warning][, reset][, threshold exceeded]\
-[, resource not accessible][, latent error]
-
-<section type string> := generic processor error | memory error | \
-PCIe error | unknown, <uuid string>
-
-<section data> :=
-<generic processor section data> | <memory section data> | \
-<pcie section data> | <null>
-
-<generic processor section data> :=
-[processor_type: <integer>, <proc type string>]
-[processor_isa: <integer>, <proc isa string>]
-[error_type: <integer>
-<proc error type strings>]
-[operation: <integer>, <proc operation string>]
-[flags: <integer>
-<proc flags strings>]
-[level: <integer>]
-[version_info: <integer>]
-[processor_id: <integer>]
-[target_address: <integer>]
-[requestor_id: <integer>]
-[responder_id: <integer>]
-[IP: <integer>]
-
-<proc type string>* := IA32/X64 | IA64
-
-<proc isa string>* := IA32 | IA64 | X64
-
-<processor error type strings># :=
-[cache error][, TLB error][, bus error][, micro-architectural error]
-
-<proc operation string>* := unknown or generic | data read | data write | \
-instruction execution
-
-<proc flags strings># :=
-[restartable][, precise IP][, overflow][, corrected]
-
-<memory section data> :=
-[error_status: <integer>]
-[physical_address: <integer>]
-[physical_address_mask: <integer>]
-[node: <integer>]
-[card: <integer>]
-[module: <integer>]
-[bank: <integer>]
-[device: <integer>]
-[row: <integer>]
-[column: <integer>]
-[bit_position: <integer>]
-[requestor_id: <integer>]
-[responder_id: <integer>]
-[target_id: <integer>]
-[error_type: <integer>, <mem error type string>]
-
-<mem error type string>* :=
-unknown | no error | single-bit ECC | multi-bit ECC | \
-single-symbol chipkill ECC | multi-symbol chipkill ECC | master abort | \
-target abort | parity error | watchdog timeout | invalid address | \
-mirror Broken | memory sparing | scrub corrected error | \
-scrub uncorrected error
-
-<pcie section data> :=
-[port_type: <integer>, <pcie port type string>]
-[version: <integer>.<integer>]
-[command: <integer>, status: <integer>]
-[device_id: <integer>:<integer>:<integer>.<integer>
-slot: <integer>
-secondary_bus: <integer>
-vendor_id: <integer>, device_id: <integer>
-class_code: <integer>]
-[serial number: <integer>, <integer>]
-[bridge: secondary_status: <integer>, control: <integer>]
-[aer_status: <integer>, aer_mask: <integer>
-<aer status string>
-[aer_uncor_severity: <integer>]
-aer_layer=<aer layer string>, aer_agent=<aer agent string>
-aer_tlp_header: <integer> <integer> <integer> <integer>]
-
-<pcie port type string>* := PCIe end point | legacy PCI end point | \
-unknown | unknown | root port | upstream switch port | \
-downstream switch port | PCIe to PCI/PCI-X bridge | \
-PCI/PCI-X to PCIe bridge | root complex integrated endpoint device | \
-root complex event collector
-
-if section severity is fatal or recoverable
-<aer status string># :=
-unknown | unknown | unknown | unknown | Data Link Protocol | \
-unknown | unknown | unknown | unknown | unknown | unknown | unknown | \
-Poisoned TLP | Flow Control Protocol | Completion Timeout | \
-Completer Abort | Unexpected Completion | Receiver Overflow | \
-Malformed TLP | ECRC | Unsupported Request
-else
-<aer status string># :=
-Receiver Error | unknown | unknown | unknown | unknown | unknown | \
-Bad TLP | Bad DLLP | RELAY_NUM Rollover | unknown | unknown | unknown | \
-Replay Timer Timeout | Advisory Non-Fatal
-fi
-
-<aer layer string> :=
-Physical Layer | Data Link Layer | Transaction Layer
-
-<aer agent string> :=
-Receiver ID | Requester ID | Completer ID | Transmitter ID
-
-Where, [] designate corresponding content is optional
-
-All <field string> description with * has the following format:
-
-field: <integer>, <field string>
-
-Where value of <integer> should be the position of "string" in <field
-string> description. Otherwise, <field string> will be "unknown".
-
-All <field strings> description with # has the following format:
-
-field: <integer>
-<field strings>
-
-Where each string in <fields strings> corresponding to one set bit of
-<integer>. The bit position is the position of "string" in <field
-strings> description.
-
-For more detailed explanation of every field, please refer to UEFI
-specification version 2.3 or later, section Appendix N: Common
-Platform Error Record.
diff --git a/Documentation/firmware-guide/acpi/apei/output_format.rst b/Documentation/firmware-guide/acpi/apei/output_format.rst
new file mode 100644
index 000000000000..c2e7ebddb529
--- /dev/null
+++ b/Documentation/firmware-guide/acpi/apei/output_format.rst
@@ -0,0 +1,150 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==================
+APEI output format
+==================
+
+APEI uses printk as hardware error reporting interface, the output
+format is as follow::
+
+ <error record> :=
+ APEI generic hardware error status
+ severity: <integer>, <severity string>
+ section: <integer>, severity: <integer>, <severity string>
+ flags: <integer>
+ <section flags strings>
+ fru_id: <uuid string>
+ fru_text: <string>
+ section_type: <section type string>
+ <section data>
+
+ <severity string>* := recoverable | fatal | corrected | info
+
+ <section flags strings># :=
+ [primary][, containment warning][, reset][, threshold exceeded]\
+ [, resource not accessible][, latent error]
+
+ <section type string> := generic processor error | memory error | \
+ PCIe error | unknown, <uuid string>
+
+ <section data> :=
+ <generic processor section data> | <memory section data> | \
+ <pcie section data> | <null>
+
+ <generic processor section data> :=
+ [processor_type: <integer>, <proc type string>]
+ [processor_isa: <integer>, <proc isa string>]
+ [error_type: <integer>
+ <proc error type strings>]
+ [operation: <integer>, <proc operation string>]
+ [flags: <integer>
+ <proc flags strings>]
+ [level: <integer>]
+ [version_info: <integer>]
+ [processor_id: <integer>]
+ [target_address: <integer>]
+ [requestor_id: <integer>]
+ [responder_id: <integer>]
+ [IP: <integer>]
+
+ <proc type string>* := IA32/X64 | IA64
+
+ <proc isa string>* := IA32 | IA64 | X64
+
+ <processor error type strings># :=
+ [cache error][, TLB error][, bus error][, micro-architectural error]
+
+ <proc operation string>* := unknown or generic | data read | data write | \
+ instruction execution
+
+ <proc flags strings># :=
+ [restartable][, precise IP][, overflow][, corrected]
+
+ <memory section data> :=
+ [error_status: <integer>]
+ [physical_address: <integer>]
+ [physical_address_mask: <integer>]
+ [node: <integer>]
+ [card: <integer>]
+ [module: <integer>]
+ [bank: <integer>]
+ [device: <integer>]
+ [row: <integer>]
+ [column: <integer>]
+ [bit_position: <integer>]
+ [requestor_id: <integer>]
+ [responder_id: <integer>]
+ [target_id: <integer>]
+ [error_type: <integer>, <mem error type string>]
+
+ <mem error type string>* :=
+ unknown | no error | single-bit ECC | multi-bit ECC | \
+ single-symbol chipkill ECC | multi-symbol chipkill ECC | master abort | \
+ target abort | parity error | watchdog timeout | invalid address | \
+ mirror Broken | memory sparing | scrub corrected error | \
+ scrub uncorrected error
+
+ <pcie section data> :=
+ [port_type: <integer>, <pcie port type string>]
+ [version: <integer>.<integer>]
+ [command: <integer>, status: <integer>]
+ [device_id: <integer>:<integer>:<integer>.<integer>
+ slot: <integer>
+ secondary_bus: <integer>
+ vendor_id: <integer>, device_id: <integer>
+ class_code: <integer>]
+ [serial number: <integer>, <integer>]
+ [bridge: secondary_status: <integer>, control: <integer>]
+ [aer_status: <integer>, aer_mask: <integer>
+ <aer status string>
+ [aer_uncor_severity: <integer>]
+ aer_layer=<aer layer string>, aer_agent=<aer agent string>
+ aer_tlp_header: <integer> <integer> <integer> <integer>]
+
+ <pcie port type string>* := PCIe end point | legacy PCI end point | \
+ unknown | unknown | root port | upstream switch port | \
+ downstream switch port | PCIe to PCI/PCI-X bridge | \
+ PCI/PCI-X to PCIe bridge | root complex integrated endpoint device | \
+ root complex event collector
+
+ if section severity is fatal or recoverable
+ <aer status string># :=
+ unknown | unknown | unknown | unknown | Data Link Protocol | \
+ unknown | unknown | unknown | unknown | unknown | unknown | unknown | \
+ Poisoned TLP | Flow Control Protocol | Completion Timeout | \
+ Completer Abort | Unexpected Completion | Receiver Overflow | \
+ Malformed TLP | ECRC | Unsupported Request
+ else
+ <aer status string># :=
+ Receiver Error | unknown | unknown | unknown | unknown | unknown | \
+ Bad TLP | Bad DLLP | RELAY_NUM Rollover | unknown | unknown | unknown | \
+ Replay Timer Timeout | Advisory Non-Fatal
+ fi
+
+ <aer layer string> :=
+ Physical Layer | Data Link Layer | Transaction Layer
+
+ <aer agent string> :=
+ Receiver ID | Requester ID | Completer ID | Transmitter ID
+
+Where, [] designate corresponding content is optional
+
+All <field string> description with * has the following format::
+
+ field: <integer>, <field string>
+
+Where value of <integer> should be the position of "string" in <field
+string> description. Otherwise, <field string> will be "unknown".
+
+All <field strings> description with # has the following format::
+
+ field: <integer>
+ <field strings>
+
+Where each string in <fields strings> corresponding to one set bit of
+<integer>. The bit position is the position of "string" in <field
+strings> description.
+
+For more detailed explanation of every field, please refer to UEFI
+specification version 2.3 or later, section Appendix N: Common
+Platform Error Record.
diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst
index e9f253d54897..869badba6d7a 100644
--- a/Documentation/firmware-guide/acpi/index.rst
+++ b/Documentation/firmware-guide/acpi/index.rst
@@ -17,6 +17,7 @@ ACPI Support
DSD-properties-rules
debug
aml-debugger
+ apei/output_format
gpio-properties
i2c-muxes
acpi-lid
--
2.20.1
^ permalink raw reply related
* [PATCH v6 20/24] Documentation: ACPI: move apei/einj.txt to firmware-guide/acpi and convert to reST
From: Changbin Du @ 2019-04-25 15:31 UTC (permalink / raw)
To: rjw, Jonathan Corbet
Cc: fenghua.yu, mchehab+samsung, linux-doc, linux-gpio, linux-kernel,
linux-acpi, Bjorn Helgaas, linuxppc-dev, Changbin Du
In-Reply-To: <20190425153117.16057-1-changbin.du@gmail.com>
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../acpi/apei/einj.rst} | 94 ++++++++++---------
Documentation/firmware-guide/acpi/index.rst | 1 +
2 files changed, 52 insertions(+), 43 deletions(-)
rename Documentation/{acpi/apei/einj.txt => firmware-guide/acpi/apei/einj.rst} (67%)
diff --git a/Documentation/acpi/apei/einj.txt b/Documentation/firmware-guide/acpi/apei/einj.rst
similarity index 67%
rename from Documentation/acpi/apei/einj.txt
rename to Documentation/firmware-guide/acpi/apei/einj.rst
index e550c8b98139..e588bccf5158 100644
--- a/Documentation/acpi/apei/einj.txt
+++ b/Documentation/firmware-guide/acpi/apei/einj.rst
@@ -1,13 +1,16 @@
- APEI Error INJection
- ~~~~~~~~~~~~~~~~~~~~
+.. SPDX-License-Identifier: GPL-2.0
+
+====================
+APEI Error INJection
+====================
EINJ provides a hardware error injection mechanism. It is very useful
for debugging and testing APEI and RAS features in general.
You need to check whether your BIOS supports EINJ first. For that, look
-for early boot messages similar to this one:
+for early boot messages similar to this one::
-ACPI: EINJ 0x000000007370A000 000150 (v01 INTEL 00000001 INTL 00000001)
+ ACPI: EINJ 0x000000007370A000 000150 (v01 INTEL 00000001 INTL 00000001)
which shows that the BIOS is exposing an EINJ table - it is the
mechanism through which the injection is done.
@@ -23,11 +26,11 @@ order to see the APEI,EINJ,... functionality supported and exposed by
the BIOS menu.
To use EINJ, make sure the following are options enabled in your kernel
-configuration:
+configuration::
-CONFIG_DEBUG_FS
-CONFIG_ACPI_APEI
-CONFIG_ACPI_APEI_EINJ
+ CONFIG_DEBUG_FS
+ CONFIG_ACPI_APEI
+ CONFIG_ACPI_APEI_EINJ
The EINJ user interface is in <debugfs mount point>/apei/einj.
@@ -37,20 +40,22 @@ The following files belong to it:
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
+ ================ ===================================
+ 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 +78,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 +129,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 +139,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 +160,26 @@ documentation for details (and expect changes to this API if vendors
creativity in using this feature expands beyond our expectations).
-An error injection example:
+An error injection example::
-# cd /sys/kernel/debug/apei/einj
-# cat available_error_type # See which errors can be injected
-0x00000002 Processor Uncorrectable non-fatal
-0x00000008 Memory Correctable
-0x00000010 Memory Uncorrectable non-fatal
-# echo 0x12345000 > param1 # Set memory address for injection
-# echo $((-1 << 12)) > param2 # Mask 0xfffffffffffff000 - anywhere in this page
-# echo 0x8 > error_type # Choose correctable memory error
-# echo 1 > error_inject # Inject now
+ # cd /sys/kernel/debug/apei/einj
+ # cat available_error_type # See which errors can be injected
+ 0x00000002 Processor Uncorrectable non-fatal
+ 0x00000008 Memory Correctable
+ 0x00000010 Memory Uncorrectable non-fatal
+ # echo 0x12345000 > param1 # Set memory address for injection
+ # echo $((-1 << 12)) > param2 # Mask 0xfffffffffffff000 - anywhere in this page
+ # echo 0x8 > error_type # Choose correctable memory error
+ # echo 1 > error_inject # Inject now
-You should see something like this in dmesg:
+You should see something like this in dmesg::
-[22715.830801] EDAC sbridge MC3: HANDLING MCE MEMORY ERROR
-[22715.834759] EDAC sbridge MC3: CPU 0: Machine Check Event: 0 Bank 7: 8c00004000010090
-[22715.834759] EDAC sbridge MC3: TSC 0
-[22715.834759] EDAC sbridge MC3: ADDR 12345000 EDAC sbridge MC3: MISC 144780c86
-[22715.834759] EDAC sbridge MC3: PROCESSOR 0:306e7 TIME 1422553404 SOCKET 0 APIC 0
-[22716.616173] EDAC MC3: 1 CE memory read error on CPU_SrcID#0_Channel#0_DIMM#0 (channel:0 slot:0 page:0x12345 offset:0x0 grain:32 syndrome:0x0 - area:DRAM err_code:0001:0090 socket:0 channel_mask:1 rank:0)
+ [22715.830801] EDAC sbridge MC3: HANDLING MCE MEMORY ERROR
+ [22715.834759] EDAC sbridge MC3: CPU 0: Machine Check Event: 0 Bank 7: 8c00004000010090
+ [22715.834759] EDAC sbridge MC3: TSC 0
+ [22715.834759] EDAC sbridge MC3: ADDR 12345000 EDAC sbridge MC3: MISC 144780c86
+ [22715.834759] EDAC sbridge MC3: PROCESSOR 0:306e7 TIME 1422553404 SOCKET 0 APIC 0
+ [22716.616173] EDAC MC3: 1 CE memory read error on CPU_SrcID#0_Channel#0_DIMM#0 (channel:0 slot:0 page:0x12345 offset:0x0 grain:32 syndrome:0x0 - area:DRAM err_code:0001:0090 socket:0 channel_mask:1 rank:0)
For more information about EINJ, please refer to ACPI specification
version 4.0, section 17.5 and ACPI 5.0, section 18.6.
diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst
index 869badba6d7a..fca854f017d8 100644
--- a/Documentation/firmware-guide/acpi/index.rst
+++ b/Documentation/firmware-guide/acpi/index.rst
@@ -18,6 +18,7 @@ ACPI Support
debug
aml-debugger
apei/output_format
+ apei/einj
gpio-properties
i2c-muxes
acpi-lid
--
2.20.1
^ permalink raw reply related
* [PATCH v6 21/24] Documentation: ACPI: move cppc_sysfs.txt to admin-guide/acpi and convert to reST
From: Changbin Du @ 2019-04-25 15:31 UTC (permalink / raw)
To: rjw, Jonathan Corbet
Cc: fenghua.yu, mchehab+samsung, linux-doc, linux-gpio, linux-kernel,
linux-acpi, Bjorn Helgaas, linuxppc-dev, Changbin Du
In-Reply-To: <20190425153117.16057-1-changbin.du@gmail.com>
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
.../acpi/cppc_sysfs.rst} | 71 ++++++++++---------
Documentation/admin-guide/acpi/index.rst | 1 +
2 files changed, 40 insertions(+), 32 deletions(-)
rename Documentation/{acpi/cppc_sysfs.txt => admin-guide/acpi/cppc_sysfs.rst} (51%)
diff --git a/Documentation/acpi/cppc_sysfs.txt b/Documentation/admin-guide/acpi/cppc_sysfs.rst
similarity index 51%
rename from Documentation/acpi/cppc_sysfs.txt
rename to Documentation/admin-guide/acpi/cppc_sysfs.rst
index f20fb445135d..a4b99afbe331 100644
--- a/Documentation/acpi/cppc_sysfs.txt
+++ b/Documentation/admin-guide/acpi/cppc_sysfs.rst
@@ -1,5 +1,11 @@
+.. SPDX-License-Identifier: GPL-2.0
- Collaborative Processor Performance Control (CPPC)
+==================================================
+Collaborative Processor Performance Control (CPPC)
+==================================================
+
+CPPC
+====
CPPC defined in the ACPI spec describes a mechanism for the OS to manage the
performance of a logical processor on a contigious and abstract performance
@@ -10,31 +16,28 @@ For more details on CPPC please refer to the ACPI specification at:
http://uefi.org/specifications
-Some of the CPPC registers are exposed via sysfs under:
-
-/sys/devices/system/cpu/cpuX/acpi_cppc/
-
-for each cpu X
+Some of the CPPC registers are exposed via sysfs under::
---------------------------------------------------------------------------------
+ /sys/devices/system/cpu/cpuX/acpi_cppc/
-$ ls -lR /sys/devices/system/cpu/cpu0/acpi_cppc/
-/sys/devices/system/cpu/cpu0/acpi_cppc/:
-total 0
--r--r--r-- 1 root root 65536 Mar 5 19:38 feedback_ctrs
--r--r--r-- 1 root root 65536 Mar 5 19:38 highest_perf
--r--r--r-- 1 root root 65536 Mar 5 19:38 lowest_freq
--r--r--r-- 1 root root 65536 Mar 5 19:38 lowest_nonlinear_perf
--r--r--r-- 1 root root 65536 Mar 5 19:38 lowest_perf
--r--r--r-- 1 root root 65536 Mar 5 19:38 nominal_freq
--r--r--r-- 1 root root 65536 Mar 5 19:38 nominal_perf
--r--r--r-- 1 root root 65536 Mar 5 19:38 reference_perf
--r--r--r-- 1 root root 65536 Mar 5 19:38 wraparound_time
+for each cpu X::
---------------------------------------------------------------------------------
+ $ ls -lR /sys/devices/system/cpu/cpu0/acpi_cppc/
+ /sys/devices/system/cpu/cpu0/acpi_cppc/:
+ total 0
+ -r--r--r-- 1 root root 65536 Mar 5 19:38 feedback_ctrs
+ -r--r--r-- 1 root root 65536 Mar 5 19:38 highest_perf
+ -r--r--r-- 1 root root 65536 Mar 5 19:38 lowest_freq
+ -r--r--r-- 1 root root 65536 Mar 5 19:38 lowest_nonlinear_perf
+ -r--r--r-- 1 root root 65536 Mar 5 19:38 lowest_perf
+ -r--r--r-- 1 root root 65536 Mar 5 19:38 nominal_freq
+ -r--r--r-- 1 root root 65536 Mar 5 19:38 nominal_perf
+ -r--r--r-- 1 root root 65536 Mar 5 19:38 reference_perf
+ -r--r--r-- 1 root root 65536 Mar 5 19:38 wraparound_time
* highest_perf : Highest performance of this processor (abstract scale).
-* nominal_perf : Highest sustained performance of this processor (abstract scale).
+* nominal_perf : Highest sustained performance of this processor
+ (abstract scale).
* lowest_nonlinear_perf : Lowest performance of this processor with nonlinear
power savings (abstract scale).
* lowest_perf : Lowest performance of this processor (abstract scale).
@@ -48,22 +51,26 @@ total 0
* feedback_ctrs : Includes both Reference and delivered performance counter.
Reference counter ticks up proportional to processor's reference performance.
Delivered counter ticks up proportional to processor's delivered performance.
-* wraparound_time: Minimum time for the feedback counters to wraparound (seconds).
+* wraparound_time: Minimum time for the feedback counters to wraparound
+ (seconds).
* reference_perf : Performance level at which reference performance counter
accumulates (abstract scale).
---------------------------------------------------------------------------------
- Computing Average Delivered Performance
+Computing Average Delivered Performance
+=======================================
+
+Below describes the steps to compute the average performance delivered by
+taking two different snapshots of feedback counters at time T1 and T2.
+
+ T1: Read feedback_ctrs as fbc_t1
+ Wait or run some workload
-Below describes the steps to compute the average performance delivered by taking
-two different snapshots of feedback counters at time T1 and T2.
+ T2: Read feedback_ctrs as fbc_t2
-T1: Read feedback_ctrs as fbc_t1
- Wait or run some workload
-T2: Read feedback_ctrs as fbc_t2
+::
-delivered_counter_delta = fbc_t2[del] - fbc_t1[del]
-reference_counter_delta = fbc_t2[ref] - fbc_t1[ref]
+ delivered_counter_delta = fbc_t2[del] - fbc_t1[del]
+ reference_counter_delta = fbc_t2[ref] - fbc_t1[ref]
-delivered_perf = (refernce_perf x delivered_counter_delta) / reference_counter_delta
+ delivered_perf = (refernce_perf x delivered_counter_delta) / reference_counter_delta
diff --git a/Documentation/admin-guide/acpi/index.rst b/Documentation/admin-guide/acpi/index.rst
index d68e9914c5ff..9049a7b9f065 100644
--- a/Documentation/admin-guide/acpi/index.rst
+++ b/Documentation/admin-guide/acpi/index.rst
@@ -10,3 +10,4 @@ the Linux ACPI support.
initrd_table_override
dsdt-override
+ cppc_sysfs
--
2.20.1
^ permalink raw reply related
* [PATCH v6 22/24] Documentation: ACPI: move lpit.txt to firmware-guide/acpi and convert to reST
From: Changbin Du @ 2019-04-25 15:31 UTC (permalink / raw)
To: rjw, Jonathan Corbet
Cc: fenghua.yu, mchehab+samsung, linux-doc, linux-gpio, linux-kernel,
linux-acpi, Bjorn Helgaas, linuxppc-dev, Changbin Du
In-Reply-To: <20190425153117.16057-1-changbin.du@gmail.com>
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/firmware-guide/acpi/index.rst | 1 +
.../lpit.txt => firmware-guide/acpi/lpit.rst} | 18 +++++++++++++-----
2 files changed, 14 insertions(+), 5 deletions(-)
rename Documentation/{acpi/lpit.txt => firmware-guide/acpi/lpit.rst} (68%)
diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst
index fca854f017d8..0e60f4b7129a 100644
--- a/Documentation/firmware-guide/acpi/index.rst
+++ b/Documentation/firmware-guide/acpi/index.rst
@@ -22,3 +22,4 @@ ACPI Support
gpio-properties
i2c-muxes
acpi-lid
+ lpit
diff --git a/Documentation/acpi/lpit.txt b/Documentation/firmware-guide/acpi/lpit.rst
similarity index 68%
rename from Documentation/acpi/lpit.txt
rename to Documentation/firmware-guide/acpi/lpit.rst
index b426398d2e97..aca928fab027 100644
--- a/Documentation/acpi/lpit.txt
+++ b/Documentation/firmware-guide/acpi/lpit.rst
@@ -1,3 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===========================
+Low Power Idle Table (LPIT)
+===========================
+
To enumerate platform Low Power Idle states, Intel platforms are using
“Low Power Idle Table” (LPIT). More details about this table can be
downloaded from:
@@ -8,13 +14,15 @@ Residencies for each low power state can be read via FFH
On platforms supporting S0ix sleep states, there can be two types of
residencies:
-- CPU PKG C10 (Read via FFH interface)
-- Platform Controller Hub (PCH) SLP_S0 (Read via memory mapped interface)
+
+ - CPU PKG C10 (Read via FFH interface)
+ - Platform Controller Hub (PCH) SLP_S0 (Read via memory mapped interface)
The following attributes are added dynamically to the cpuidle
-sysfs attribute group:
- /sys/devices/system/cpu/cpuidle/low_power_idle_cpu_residency_us
- /sys/devices/system/cpu/cpuidle/low_power_idle_system_residency_us
+sysfs attribute group::
+
+ /sys/devices/system/cpu/cpuidle/low_power_idle_cpu_residency_us
+ /sys/devices/system/cpu/cpuidle/low_power_idle_system_residency_us
The "low_power_idle_cpu_residency_us" attribute shows time spent
by the CPU package in PKG C10
--
2.20.1
^ permalink raw reply related
* [PATCH v6 23/24] Documentation: ACPI: move ssdt-overlays.txt to admin-guide/acpi and convert to reST
From: Changbin Du @ 2019-04-25 15:31 UTC (permalink / raw)
To: rjw, Jonathan Corbet
Cc: fenghua.yu, mchehab+samsung, linux-doc, linux-gpio, linux-kernel,
linux-acpi, Bjorn Helgaas, linuxppc-dev, Changbin Du
In-Reply-To: <20190425153117.16057-1-changbin.du@gmail.com>
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/acpi/ssdt-overlays.txt | 172 -----------------
Documentation/admin-guide/acpi/index.rst | 1 +
.../admin-guide/acpi/ssdt-overlays.rst | 180 ++++++++++++++++++
3 files changed, 181 insertions(+), 172 deletions(-)
delete mode 100644 Documentation/acpi/ssdt-overlays.txt
create mode 100644 Documentation/admin-guide/acpi/ssdt-overlays.rst
diff --git a/Documentation/acpi/ssdt-overlays.txt b/Documentation/acpi/ssdt-overlays.txt
deleted file mode 100644
index 5ae13f161ea2..000000000000
--- a/Documentation/acpi/ssdt-overlays.txt
+++ /dev/null
@@ -1,172 +0,0 @@
-
-In order to support ACPI open-ended hardware configurations (e.g. development
-boards) we need a way to augment the ACPI configuration provided by the firmware
-image. A common example is connecting sensors on I2C / SPI buses on development
-boards.
-
-Although this can be accomplished by creating a kernel platform driver or
-recompiling the firmware image with updated ACPI tables, neither is practical:
-the former proliferates board specific kernel code while the latter requires
-access to firmware tools which are often not publicly available.
-
-Because ACPI supports external references in AML code a more practical
-way to augment firmware ACPI configuration is by dynamically loading
-user defined SSDT tables that contain the board specific information.
-
-For example, to enumerate a Bosch BMA222E accelerometer on the I2C bus of the
-Minnowboard MAX development board exposed via the LSE connector [1], the
-following ASL code can be used:
-
-DefinitionBlock ("minnowmax.aml", "SSDT", 1, "Vendor", "Accel", 0x00000003)
-{
- External (\_SB.I2C6, DeviceObj)
-
- Scope (\_SB.I2C6)
- {
- Device (STAC)
- {
- Name (_ADR, Zero)
- Name (_HID, "BMA222E")
-
- Method (_CRS, 0, Serialized)
- {
- Name (RBUF, ResourceTemplate ()
- {
- I2cSerialBus (0x0018, ControllerInitiated, 0x00061A80,
- AddressingMode7Bit, "\\_SB.I2C6", 0x00,
- ResourceConsumer, ,)
- GpioInt (Edge, ActiveHigh, Exclusive, PullDown, 0x0000,
- "\\_SB.GPO2", 0x00, ResourceConsumer, , )
- { // Pin list
- 0
- }
- })
- Return (RBUF)
- }
- }
- }
-}
-
-which can then be compiled to AML binary format:
-
-$ iasl minnowmax.asl
-
-Intel ACPI Component Architecture
-ASL Optimizing Compiler version 20140214-64 [Mar 29 2014]
-Copyright (c) 2000 - 2014 Intel Corporation
-
-ASL Input: minnomax.asl - 30 lines, 614 bytes, 7 keywords
-AML Output: minnowmax.aml - 165 bytes, 6 named objects, 1 executable opcodes
-
-[1] http://wiki.minnowboard.org/MinnowBoard_MAX#Low_Speed_Expansion_Connector_.28Top.29
-
-The resulting AML code can then be loaded by the kernel using one of the methods
-below.
-
-== Loading ACPI SSDTs from initrd ==
-
-This option allows loading of user defined SSDTs from initrd and it is useful
-when the system does not support EFI or when there is not enough EFI storage.
-
-It works in a similar way with initrd based ACPI tables override/upgrade: SSDT
-aml code must be placed in the first, uncompressed, initrd under the
-"kernel/firmware/acpi" path. Multiple files can be used and this will translate
-in loading multiple tables. Only SSDT and OEM tables are allowed. See
-initrd_table_override.txt for more details.
-
-Here is an example:
-
-# Add the raw ACPI tables to an uncompressed cpio archive.
-# They must be put into a /kernel/firmware/acpi directory inside the
-# cpio archive.
-# The uncompressed cpio archive must be the first.
-# Other, typically compressed cpio archives, must be
-# concatenated on top of the uncompressed one.
-mkdir -p kernel/firmware/acpi
-cp ssdt.aml kernel/firmware/acpi
-
-# Create the uncompressed cpio archive and concatenate the original initrd
-# on top:
-find kernel | cpio -H newc --create > /boot/instrumented_initrd
-cat /boot/initrd >>/boot/instrumented_initrd
-
-== Loading ACPI SSDTs from EFI variables ==
-
-This is the preferred method, when EFI is supported on the platform, because it
-allows a persistent, OS independent way of storing the user defined SSDTs. There
-is also work underway to implement EFI support for loading user defined SSDTs
-and using this method will make it easier to convert to the EFI loading
-mechanism when that will arrive.
-
-In order to load SSDTs from an EFI variable the efivar_ssdt kernel command line
-parameter can be used. The argument for the option is the variable name to
-use. If there are multiple variables with the same name but with different
-vendor GUIDs, all of them will be loaded.
-
-In order to store the AML code in an EFI variable the efivarfs filesystem can be
-used. It is enabled and mounted by default in /sys/firmware/efi/efivars in all
-recent distribution.
-
-Creating a new file in /sys/firmware/efi/efivars will automatically create a new
-EFI variable. Updating a file in /sys/firmware/efi/efivars will update the EFI
-variable. Please note that the file name needs to be specially formatted as
-"Name-GUID" and that the first 4 bytes in the file (little-endian format)
-represent the attributes of the EFI variable (see EFI_VARIABLE_MASK in
-include/linux/efi.h). Writing to the file must also be done with one write
-operation.
-
-For example, you can use the following bash script to create/update an EFI
-variable with the content from a given file:
-
-#!/bin/sh -e
-
-while ! [ -z "$1" ]; do
- case "$1" in
- "-f") filename="$2"; shift;;
- "-g") guid="$2"; shift;;
- *) name="$1";;
- esac
- shift
-done
-
-usage()
-{
- echo "Syntax: ${0##*/} -f filename [ -g guid ] name"
- exit 1
-}
-
-[ -n "$name" -a -f "$filename" ] || usage
-
-EFIVARFS="/sys/firmware/efi/efivars"
-
-[ -d "$EFIVARFS" ] || exit 2
-
-if stat -tf $EFIVARFS | grep -q -v de5e81e4; then
- mount -t efivarfs none $EFIVARFS
-fi
-
-# try to pick up an existing GUID
-[ -n "$guid" ] || guid=$(find "$EFIVARFS" -name "$name-*" | head -n1 | cut -f2- -d-)
-
-# use a randomly generated GUID
-[ -n "$guid" ] || guid="$(cat /proc/sys/kernel/random/uuid)"
-
-# efivarfs expects all of the data in one write
-tmp=$(mktemp)
-/bin/echo -ne "\007\000\000\000" | cat - $filename > $tmp
-dd if=$tmp of="$EFIVARFS/$name-$guid" bs=$(stat -c %s $tmp)
-rm $tmp
-
-== Loading ACPI SSDTs from configfs ==
-
-This option allows loading of user defined SSDTs from userspace via the configfs
-interface. The CONFIG_ACPI_CONFIGFS option must be select and configfs must be
-mounted. In the following examples, we assume that configfs has been mounted in
-/config.
-
-New tables can be loading by creating new directories in /config/acpi/table/ and
-writing the SSDT aml code in the aml attribute:
-
-cd /config/acpi/table
-mkdir my_ssdt
-cat ~/ssdt.aml > my_ssdt/aml
diff --git a/Documentation/admin-guide/acpi/index.rst b/Documentation/admin-guide/acpi/index.rst
index 9049a7b9f065..4d13eeea1eca 100644
--- a/Documentation/admin-guide/acpi/index.rst
+++ b/Documentation/admin-guide/acpi/index.rst
@@ -10,4 +10,5 @@ the Linux ACPI support.
initrd_table_override
dsdt-override
+ ssdt-overlays
cppc_sysfs
diff --git a/Documentation/admin-guide/acpi/ssdt-overlays.rst b/Documentation/admin-guide/acpi/ssdt-overlays.rst
new file mode 100644
index 000000000000..da37455f96c9
--- /dev/null
+++ b/Documentation/admin-guide/acpi/ssdt-overlays.rst
@@ -0,0 +1,180 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=============
+SSDT Overlays
+=============
+
+In order to support ACPI open-ended hardware configurations (e.g. development
+boards) we need a way to augment the ACPI configuration provided by the firmware
+image. A common example is connecting sensors on I2C / SPI buses on development
+boards.
+
+Although this can be accomplished by creating a kernel platform driver or
+recompiling the firmware image with updated ACPI tables, neither is practical:
+the former proliferates board specific kernel code while the latter requires
+access to firmware tools which are often not publicly available.
+
+Because ACPI supports external references in AML code a more practical
+way to augment firmware ACPI configuration is by dynamically loading
+user defined SSDT tables that contain the board specific information.
+
+For example, to enumerate a Bosch BMA222E accelerometer on the I2C bus of the
+Minnowboard MAX development board exposed via the LSE connector [1], the
+following ASL code can be used::
+
+ DefinitionBlock ("minnowmax.aml", "SSDT", 1, "Vendor", "Accel", 0x00000003)
+ {
+ External (\_SB.I2C6, DeviceObj)
+
+ Scope (\_SB.I2C6)
+ {
+ Device (STAC)
+ {
+ Name (_ADR, Zero)
+ Name (_HID, "BMA222E")
+
+ Method (_CRS, 0, Serialized)
+ {
+ Name (RBUF, ResourceTemplate ()
+ {
+ I2cSerialBus (0x0018, ControllerInitiated, 0x00061A80,
+ AddressingMode7Bit, "\\_SB.I2C6", 0x00,
+ ResourceConsumer, ,)
+ GpioInt (Edge, ActiveHigh, Exclusive, PullDown, 0x0000,
+ "\\_SB.GPO2", 0x00, ResourceConsumer, , )
+ { // Pin list
+ 0
+ }
+ })
+ Return (RBUF)
+ }
+ }
+ }
+ }
+
+which can then be compiled to AML binary format::
+
+ $ iasl minnowmax.asl
+
+ Intel ACPI Component Architecture
+ ASL Optimizing Compiler version 20140214-64 [Mar 29 2014]
+ Copyright (c) 2000 - 2014 Intel Corporation
+
+ ASL Input: minnomax.asl - 30 lines, 614 bytes, 7 keywords
+ AML Output: minnowmax.aml - 165 bytes, 6 named objects, 1 executable opcodes
+
+[1] http://wiki.minnowboard.org/MinnowBoard_MAX#Low_Speed_Expansion_Connector_.28Top.29
+
+The resulting AML code can then be loaded by the kernel using one of the methods
+below.
+
+Loading ACPI SSDTs from initrd
+==============================
+
+This option allows loading of user defined SSDTs from initrd and it is useful
+when the system does not support EFI or when there is not enough EFI storage.
+
+It works in a similar way with initrd based ACPI tables override/upgrade: SSDT
+aml code must be placed in the first, uncompressed, initrd under the
+"kernel/firmware/acpi" path. Multiple files can be used and this will translate
+in loading multiple tables. Only SSDT and OEM tables are allowed. See
+initrd_table_override.txt for more details.
+
+Here is an example::
+
+ # Add the raw ACPI tables to an uncompressed cpio archive.
+ # They must be put into a /kernel/firmware/acpi directory inside the
+ # cpio archive.
+ # The uncompressed cpio archive must be the first.
+ # Other, typically compressed cpio archives, must be
+ # concatenated on top of the uncompressed one.
+ mkdir -p kernel/firmware/acpi
+ cp ssdt.aml kernel/firmware/acpi
+
+ # Create the uncompressed cpio archive and concatenate the original initrd
+ # on top:
+ find kernel | cpio -H newc --create > /boot/instrumented_initrd
+ cat /boot/initrd >>/boot/instrumented_initrd
+
+Loading ACPI SSDTs from EFI variables
+=====================================
+
+This is the preferred method, when EFI is supported on the platform, because it
+allows a persistent, OS independent way of storing the user defined SSDTs. There
+is also work underway to implement EFI support for loading user defined SSDTs
+and using this method will make it easier to convert to the EFI loading
+mechanism when that will arrive.
+
+In order to load SSDTs from an EFI variable the efivar_ssdt kernel command line
+parameter can be used. The argument for the option is the variable name to
+use. If there are multiple variables with the same name but with different
+vendor GUIDs, all of them will be loaded.
+
+In order to store the AML code in an EFI variable the efivarfs filesystem can be
+used. It is enabled and mounted by default in /sys/firmware/efi/efivars in all
+recent distribution.
+
+Creating a new file in /sys/firmware/efi/efivars will automatically create a new
+EFI variable. Updating a file in /sys/firmware/efi/efivars will update the EFI
+variable. Please note that the file name needs to be specially formatted as
+"Name-GUID" and that the first 4 bytes in the file (little-endian format)
+represent the attributes of the EFI variable (see EFI_VARIABLE_MASK in
+include/linux/efi.h). Writing to the file must also be done with one write
+operation.
+
+For example, you can use the following bash script to create/update an EFI
+variable with the content from a given file::
+
+ #!/bin/sh -e
+
+ while ! [ -z "$1" ]; do
+ case "$1" in
+ "-f") filename="$2"; shift;;
+ "-g") guid="$2"; shift;;
+ *) name="$1";;
+ esac
+ shift
+ done
+
+ usage()
+ {
+ echo "Syntax: ${0##*/} -f filename [ -g guid ] name"
+ exit 1
+ }
+
+ [ -n "$name" -a -f "$filename" ] || usage
+
+ EFIVARFS="/sys/firmware/efi/efivars"
+
+ [ -d "$EFIVARFS" ] || exit 2
+
+ if stat -tf $EFIVARFS | grep -q -v de5e81e4; then
+ mount -t efivarfs none $EFIVARFS
+ fi
+
+ # try to pick up an existing GUID
+ [ -n "$guid" ] || guid=$(find "$EFIVARFS" -name "$name-*" | head -n1 | cut -f2- -d-)
+
+ # use a randomly generated GUID
+ [ -n "$guid" ] || guid="$(cat /proc/sys/kernel/random/uuid)"
+
+ # efivarfs expects all of the data in one write
+ tmp=$(mktemp)
+ /bin/echo -ne "\007\000\000\000" | cat - $filename > $tmp
+ dd if=$tmp of="$EFIVARFS/$name-$guid" bs=$(stat -c %s $tmp)
+ rm $tmp
+
+Loading ACPI SSDTs from configfs
+================================
+
+This option allows loading of user defined SSDTs from userspace via the configfs
+interface. The CONFIG_ACPI_CONFIGFS option must be select and configfs must be
+mounted. In the following examples, we assume that configfs has been mounted in
+/config.
+
+New tables can be loading by creating new directories in /config/acpi/table/ and
+writing the SSDT aml code in the aml attribute::
+
+ cd /config/acpi/table
+ mkdir my_ssdt
+ cat ~/ssdt.aml > my_ssdt/aml
--
2.20.1
^ permalink raw reply related
* [PATCH v6 24/24] Documentation: ACPI: move video_extension.txt to firmware-guide/acpi and convert to reST
From: Changbin Du @ 2019-04-25 15:31 UTC (permalink / raw)
To: rjw, Jonathan Corbet
Cc: fenghua.yu, mchehab+samsung, linux-doc, linux-gpio, linux-kernel,
linux-acpi, Bjorn Helgaas, linuxppc-dev, Changbin Du
In-Reply-To: <20190425153117.16057-1-changbin.du@gmail.com>
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: Changbin Du <changbin.du@gmail.com>
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/firmware-guide/acpi/index.rst | 1 +
.../acpi/video_extension.rst} | 85 +++++++++++--------
2 files changed, 52 insertions(+), 34 deletions(-)
rename Documentation/{acpi/video_extension.txt => firmware-guide/acpi/video_extension.rst} (68%)
diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst
index 0e60f4b7129a..ae609eec4679 100644
--- a/Documentation/firmware-guide/acpi/index.rst
+++ b/Documentation/firmware-guide/acpi/index.rst
@@ -23,3 +23,4 @@ ACPI Support
i2c-muxes
acpi-lid
lpit
+ video_extension
diff --git a/Documentation/acpi/video_extension.txt b/Documentation/firmware-guide/acpi/video_extension.rst
similarity index 68%
rename from Documentation/acpi/video_extension.txt
rename to Documentation/firmware-guide/acpi/video_extension.rst
index 79bf6a4921be..932fb47342a7 100644
--- a/Documentation/acpi/video_extension.txt
+++ b/Documentation/firmware-guide/acpi/video_extension.rst
@@ -1,5 +1,8 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=====================
ACPI video extensions
-~~~~~~~~~~~~~~~~~~~~~
+=====================
This driver implement the ACPI Extensions For Display Adapters for
integrated graphics devices on motherboard, as specified in ACPI 2.0
@@ -8,9 +11,12 @@ defining the video POST device, retrieving EDID information or to
setup a video output, etc. Note that this is an ref. implementation
only. It may or may not work for your integrated video device.
-The ACPI video driver does 3 things regarding backlight control:
+The ACPI video driver exports the backlight control via a sysfs interface,
+notifies userspace with events and changes the backlight level via ACPI
+firmware, as detailed at the following chapters:
-1 Export a sysfs interface for user space to control backlight level
+Export a sysfs interface for user space to control backlight level
+==================================================================
If the ACPI table has a video device, and acpi_backlight=vendor kernel
command line is not present, the driver will register a backlight device
@@ -22,36 +28,41 @@ The backlight sysfs interface has a standard definition here:
Documentation/ABI/stable/sysfs-class-backlight.
And what ACPI video driver does is:
-actual_brightness: on read, control method _BQC will be evaluated to
-get the brightness level the firmware thinks it is at;
-bl_power: not implemented, will set the current brightness instead;
-brightness: on write, control method _BCM will run to set the requested
-brightness level;
-max_brightness: Derived from the _BCL package(see below);
-type: firmware
+
+actual_brightness:
+ on read, control method _BQC will be evaluated to
+ get the brightness level the firmware thinks it is at;
+bl_power:
+ not implemented, will set the current brightness instead;
+brightness:
+ on write, control method _BCM will run to set the requested brightness level;
+max_brightness:
+ Derived from the _BCL package(see below);
+type:
+ firmware
Note that ACPI video backlight driver will always use index for
brightness, actual_brightness and max_brightness. So if we have
-the following _BCL package:
+the following _BCL package::
-Method (_BCL, 0, NotSerialized)
-{
- Return (Package (0x0C)
+ Method (_BCL, 0, NotSerialized)
{
- 0x64,
- 0x32,
- 0x0A,
- 0x14,
- 0x1E,
- 0x28,
- 0x32,
- 0x3C,
- 0x46,
- 0x50,
- 0x5A,
- 0x64
- })
-}
+ Return (Package (0x0C)
+ {
+ 0x64,
+ 0x32,
+ 0x0A,
+ 0x14,
+ 0x1E,
+ 0x28,
+ 0x32,
+ 0x3C,
+ 0x46,
+ 0x50,
+ 0x5A,
+ 0x64
+ })
+ }
The first two levels are for when laptop are on AC or on battery and are
not used by Linux currently. The remaining 10 levels are supported levels
@@ -62,13 +73,15 @@ as a "brightness level" indicator. Thus from the user space perspective
the range of available brightness levels is from 0 to 9 (max_brightness)
inclusive.
-2 Notify user space about hotkey event
+Notify user space about hotkey event
+====================================
There are generally two cases for hotkey event reporting:
+
i) For some laptops, when user presses the hotkey, a scancode will be
generated and sent to user space through the input device created by
the keyboard driver as a key type input event, with proper remap, the
- following key code will appear to user space:
+ following key code will appear to user space::
EV_KEY, KEY_BRIGHTNESSUP
EV_KEY, KEY_BRIGHTNESSDOWN
@@ -84,23 +97,27 @@ ii) For some laptops, the press of the hotkey will not generate the
notify value it received and send the event to user space through the
input device it created:
+ ===== ==================
event keycode
+ ===== ==================
0x86 KEY_BRIGHTNESSUP
0x87 KEY_BRIGHTNESSDOWN
etc.
+ ===== ==================
so this would lead to the same effect as case i) now.
Once user space tool receives this event, it can modify the backlight
level through the sysfs interface.
-3 Change backlight level in the kernel
+Change backlight level in the kernel
+====================================
This works for machines covered by case ii) in Section 2. Once the driver
received a notification, it will set the backlight level accordingly. This does
not affect the sending of event to user space, they are always sent to user
space regardless of whether or not the video module controls the backlight level
directly. This behaviour can be controlled through the brightness_switch_enabled
-module parameter as documented in admin-guide/kernel-parameters.rst. It is recommended to
-disable this behaviour once a GUI environment starts up and wants to have full
-control of the backlight level.
+module parameter as documented in admin-guide/kernel-parameters.rst. It is
+recommended to disable this behaviour once a GUI environment starts up and
+wants to have full control of the backlight level.
--
2.20.1
^ permalink raw reply related
* Re: [PATCH v4 25/63] Documentation: add Linux PCI to Sphinx TOC tree
From: Changbin Du @ 2019-04-25 15:42 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: fenghua.yu, x86, Jonathan Corbet, linux-pci, linux-gpio,
linux-doc, rjw, linux-kernel, linux-acpi, mingo, Bjorn Helgaas,
tglx, linuxppc-dev, Changbin Du
In-Reply-To: <20190424120336.4f66cbb8@coco.lan>
On Wed, Apr 24, 2019 at 12:03:43PM -0300, Mauro Carvalho Chehab wrote:
> Em Wed, 24 Apr 2019 00:28:54 +0800
> Changbin Du <changbin.du@gmail.com> escreveu:
>
> > Add a index.rst for PCI subsystem. More docs will be added later.
> >
> > Signed-off-by: Changbin Du <changbin.du@gmail.com>
> > Acked-by: Bjorn Helgaas <bhelgaas@google.com>
> > ---
> > Documentation/PCI/index.rst | 9 +++++++++
>
> On a past discussion at docs ML, we've agreed to use lowercase for new
> stuff. My suggestion here would be to use lowercase for "pci".
>
> Also, there's already a pci directory under driver-api, added on this
> commit:
>
> commit fcc78f9c22474d60c65d522e50ea07006ec1b9fc
> Author: Logan Gunthorpe <logang@deltatee.com>
> Date: Thu Oct 4 15:27:39 2018 -0600
>
> docs-rst: Add a new directory for PCI documentation
>
> I would just add a new section at Documentation/driver-api/pci/index.rst
> with something like:
>
> Legacy PCI documentation
> ========================
>
> .. note::
>
> The files here were written a long time ago and need some serious
> work. Use their contents with caution.
>
> .. toctree::
> :maxdepth: 1
>
> <files converted from Documentation/PCI>
>
> And add those documents from Documentation/PCI into it.
>
Bjorn, Jonathan,
Do you agree with this? By this all Documentation/PCI/* will be moved to
Documentation/driver-api/pci.
>
> Thanks,
> Mauro
--
Cheers,
Changbin Du
^ permalink raw reply
* Re: [PATCH v2 3/4] powerpc/boot: Add bzip2 support for uImage
From: Christophe Leroy @ 2019-04-25 17:03 UTC (permalink / raw)
To: Adam Borowski; +Cc: linuxppc-dev, Paul Mackerras, linux-kernel
In-Reply-To: <20190425143706.GA28476@angband.pl>
On 04/25/2019 02:37 PM, Adam Borowski wrote:
> On Tue, Apr 23, 2019 at 02:20:43PM +0000, Christophe Leroy wrote:
>> This patch allows to generate bzip2 compressed uImage
>
> Please don't add bzip2 support, that's a waste of your time as we're trying
> to remove it kernel-wide. There's a patchset to retire compressors beaten
> by alternatives on the whole speed-to-size curve; reposting it is overdue.
>
> It does:
> * add ZSTD (fast and strong)
> * remove BZIP2 (obsolete, only user in kernel)
> * remove LZMA (redundant with XZ, uses a private copy of its library)
> * makes Kconfig prose talk badly about LZO (used elsewhere in the kernel)
>
> I believe only three compressors are worth using here: XZ, ZSTD, LZ4.
> GZIP must stay because of ubiquitous support, the rest should go.
Ok. Initially the purpose was to add lzma, then I took the opportunity
to add all compressors supported by u-boot uImage files which are 'none,
bzip2, gzip, lzma, lzo':
[root@po16846vm linux-powerpc]# mkimage -C -h
Invalid Compression Type - valid names are: none, bzip2, gzip, lzma, lzo
Usage: mkimage -l image
-l ==> list image header information
mkimage [-x] -A arch -O os -T type -C comp -a addr -e ep -n name
-d data_file[:data_file...] image
So I can leave bzip2 aside.
xz, zstd and lz4 are not supported by the uImage format as far as I know
so we have to keep lzma which gives a far better compression ratio than
gzip (gzipped uImage don't fit in my board's NOR Flash while lzmaed
uImage does).
Christophe
>
>> --- a/arch/powerpc/Kconfig
>> +++ b/arch/powerpc/Kconfig
>> @@ -199,6 +199,7 @@ config PPC
>> + select HAVE_KERNEL_BZIP2 if DEFAULT_UIMAGE
>> --- a/arch/powerpc/boot/Makefile
>> +++ b/arch/powerpc/boot/Makefile
>> @@ -23,6 +23,7 @@ all: $(obj)/zImage
>> +compress-$(CONFIG_KERNEL_BZIP2) := CONFIG_KERNEL_BZIP2
>> @@ -259,6 +260,7 @@ endif
>> +compressor-$(CONFIG_KERNEL_BZIP2) := bz2
>> --- a/arch/powerpc/boot/wrapper
>> +++ b/arch/powerpc/boot/wrapper
>> @@ -137,7 +137,7 @@ while [ "$#" -gt 0 ]; do
>> - [ "$1" != "gz" -o "$1" != "xz" -o "$1" != "lzma" -o "$1" != "none" ] || usage
>> + [ "$1" != "gz" -o "$1" != "xz" -o "$1" != "lzma" -o "$1" != "bz2" -o "$1" != "none" ] || usage
>> @@ -149,6 +149,9 @@ while [ "$#" -gt 0 ]; do
>> + if [ $uboot_comp = "bz2" ]; then
>> + uboot_comp=bzip2
>> + fi
>> @@ -377,6 +380,9 @@ if [ -z "$cacheit" -o ! -f "$vmz$compression" -o "$vmz$compression" -ot "$kernel
>> + .bz2)
>> + bzip2 -f "$vmz.$$"
>> + ;;
>
>
> Meow!
>
^ permalink raw reply
* Re: [PATCH v4 38/63] Documentation: x86: convert boot.txt to reST
From: Changbin Du @ 2019-04-25 17:07 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: fenghua.yu, x86, Jonathan Corbet, linux-pci, linux-gpio,
linux-doc, rjw, linux-kernel, linux-acpi, mingo, Bjorn Helgaas,
tglx, linuxppc-dev, Changbin Du
In-Reply-To: <20190424143644.2e1ffa20@coco.lan>
On Wed, Apr 24, 2019 at 02:36:44PM -0300, Mauro Carvalho Chehab wrote:
> Em Wed, 24 Apr 2019 00:29:07 +0800
> Changbin Du <changbin.du@gmail.com> escreveu:
>
> > This converts the plain text documentation to reStructuredText format and
> > add it to Sphinx TOC tree. No essential content change.
> >
> > Signed-off-by: Changbin Du <changbin.du@gmail.com>
> > ---
> > Documentation/x86/boot.rst | 1205 +++++++++++++++++++++++++++++++++++
> > Documentation/x86/boot.txt | 1130 --------------------------------
> > Documentation/x86/index.rst | 2 +
> > 3 files changed, 1207 insertions(+), 1130 deletions(-)
> > create mode 100644 Documentation/x86/boot.rst
> > delete mode 100644 Documentation/x86/boot.txt
> >
> > diff --git a/Documentation/x86/boot.rst b/Documentation/x86/boot.rst
> > new file mode 100644
> > index 000000000000..9f55e832bc47
> > --- /dev/null
> > +++ b/Documentation/x86/boot.rst
> > @@ -0,0 +1,1205 @@
> > +.. SPDX-License-Identifier: GPL-2.0
> > +
> > +===========================
> > +The Linux/x86 Boot Protocol
> > +===========================
> > +
> > +On the x86 platform, the Linux kernel uses a rather complicated boot
> > +convention. This has evolved partially due to historical aspects, as
> > +well as the desire in the early days to have the kernel itself be a
> > +bootable image, the complicated PC memory model and due to changed
> > +expectations in the PC industry caused by the effective demise of
> > +real-mode DOS as a mainstream operating system.
> > +
> > +Currently, the following versions of the Linux/x86 boot protocol exist.
> > +
> > +Old kernels:
> > + zImage/Image support only. Some very early kernels
> > + may not even support a command line.
> > +
> > +Protocol 2.00:
> > + (Kernel 1.3.73) Added bzImage and initrd support, as
> > + well as a formalized way to communicate between the
> > + boot loader and the kernel. setup.S made relocatable,
> > + although the traditional setup area still assumed writable.
> > +
> > +Protocol 2.01:
> > + (Kernel 1.3.76) Added a heap overrun warning.
> > +
> > +Protocol 2.02:
> > + (Kernel 2.4.0-test3-pre3) New command line protocol.
> > + Lower the conventional memory ceiling. No overwrite
> > + of the traditional setup area, thus making booting
> > + safe for systems which use the EBDA from SMM or 32-bit
> > + BIOS entry points. zImage deprecated but still supported.
> > +
> > +Protocol 2.03:
> > + (Kernel 2.4.18-pre1) Explicitly makes the highest possible
> > + initrd address available to the bootloader.
> > +
> > +Protocol 2.04:
> > + (Kernel 2.6.14) Extend the syssize field to four bytes.
> > +
> > +Protocol 2.05:
> > + (Kernel 2.6.20) Make protected mode kernel relocatable.
> > + Introduce relocatable_kernel and kernel_alignment fields.
> > +
> > +Protocol 2.06:
> > + (Kernel 2.6.22) Added a field that contains the size of
> > + the boot command line.
> > +
> > +Protocol 2.07:
> > + (Kernel 2.6.24) Added paravirtualised boot protocol.
> > + Introduced hardware_subarch and hardware_subarch_data
> > + and KEEP_SEGMENTS flag in load_flags.
> > +
> > +Protocol 2.08:
> > + (Kernel 2.6.26) Added crc32 checksum and ELF format
> > + payload. Introduced payload_offset and payload_length
> > + fields to aid in locating the payload.
> > +
> > +Protocol 2.09:
> > + (Kernel 2.6.26) Added a field of 64-bit physical
> > + pointer to single linked list of struct setup_data.
> > +
> > +Protocol 2.10:
> > + (Kernel 2.6.31) Added a protocol for relaxed alignment
> > + beyond the kernel_alignment added, new init_size and
> > + pref_address fields. Added extended boot loader IDs.
> > +
> > +Protocol 2.11:
> > + (Kernel 3.6) Added a field for offset of EFI handover
> > + protocol entry point.
> > +
> > +Protocol 2.12:
> > + (Kernel 3.8) Added the xloadflags field and extension fields
> > + to struct boot_params for loading bzImage and ramdisk
> > + above 4G in 64bit.
>
> This is a side node, but you should really try to avoid replacing too
> many lines, as it makes a lot harder for reviewers for no good reason.
>
> For example, this is the way I would convert this changelog table:
>
>
> @@ -10,6 +11,7 @@ real-mode DOS as a mainstream operating system.
>
> Currently, the following versions of the Linux/x86 boot protocol exist.
>
> +=============== ===============================================================
> Old kernels: zImage/Image support only. Some very early kernels
> may not even support a command line.
>
> @@ -64,33 +66,35 @@ Protocol 2.12: (Kernel 3.8) Added the xloadflags field and extension fields
> Protocol 2.13: (Kernel 3.14) Support 32- and 64-bit flags being set in
> xloadflags to support booting a 64-bit kernel from 32-bit
> EFI
> +=============== ===============================================================
>
>
> This is simple enough, preserves the original author's intent and
> makes a lot easier for reviewers to check what you changed.
>
much better. thanks.
> > +
> > +MEMORY LAYOUT
> > +=============
> > +
> > +The traditional memory map for the kernel loader, used for Image or
> > +zImage kernels, typically looks like::
> > +
> > + | |
> > + 0A0000 +------------------------+
> > + | Reserved for BIOS | Do not use. Reserved for BIOS EBDA.
> > + 09A000 +------------------------+
> > + | Command line |
> > + | Stack/heap | For use by the kernel real-mode code.
> > + 098000 +------------------------+
> > + | Kernel setup | The kernel real-mode code.
> > + 090200 +------------------------+
> > + | Kernel boot sector | The kernel legacy boot sector.
> > + 090000 +------------------------+
> > + | Protected-mode kernel | The bulk of the kernel image.
> > + 010000 +------------------------+
> > + | Boot loader | <- Boot sector entry point 0000:7C00
> > + 001000 +------------------------+
> > + | Reserved for MBR/BIOS |
> > + 000800 +------------------------+
> > + | Typically used by MBR |
> > + 000600 +------------------------+
> > + | BIOS use only |
> > + 000000 +------------------------+
> > +
> > +
>
> I might be wrong, but it seems that you broke the above ascii
> artwork.
>
You r right and fixed.
> > +When using bzImage, the protected-mode kernel was relocated to
> > +0x100000 ("high memory"), and the kernel real-mode block (boot sector,
> > +setup, and stack/heap) was made relocatable to any address between
> > +0x10000 and end of low memory. Unfortunately, in protocols 2.00 and
> > +2.01 the 0x90000+ memory range is still used internally by the kernel;
> > +the 2.02 protocol resolves that problem.
> > +
> > +It is desirable to keep the "memory ceiling" -- the highest point in
> > +low memory touched by the boot loader -- as low as possible, since
> > +some newer BIOSes have begun to allocate some rather large amounts of
> > +memory, called the Extended BIOS Data Area, near the top of low
> > +memory. The boot loader should use the "INT 12h" BIOS call to verify
> > +how much low memory is available.
> > +
> > +Unfortunately, if INT 12h reports that the amount of memory is too
> > +low, there is usually nothing the boot loader can do but to report an
> > +error to the user. The boot loader should therefore be designed to
> > +take up as little space in low memory as it reasonably can. For
> > +zImage or old bzImage kernels, which need data written into the
> > +0x90000 segment, the boot loader should make sure not to use memory
> > +above the 0x9A000 point; too many BIOSes will break above that point.
> > +
> > +For a modern bzImage kernel with boot protocol version >= 2.02, a
> > +memory layout like the following is suggested::
> > +
> > + ~ ~
> > + | Protected-mode kernel |
> > + 100000 +------------------------+
> > + | I/O memory hole |
> > + 0A0000 +------------------------+
> > + | Reserved for BIOS | Leave as much as possible unused
> > + ~ ~
> > + | Command line | (Can also be below the X+10000 mark)
> > + X+10000 +------------------------+
> > + | Stack/heap | For use by the kernel real-mode code.
> > + X+08000 +------------------------+
> > + | Kernel setup | The kernel real-mode code.
> > + | Kernel boot sector | The kernel legacy boot sector.
> > + X +------------------------+
> > + | Boot loader | <- Boot sector entry point 0000:7C00
> > + 001000 +------------------------+
> > + | Reserved for MBR/BIOS |
> > + 000800 +------------------------+
> > + | Typically used by MBR |
> > + 000600 +------------------------+
> > + | BIOS use only |
> > + 000000 +------------------------+
>
>
> Same here: it sounds to me that you mistakenly replaced some tabs
> by spaces.
>
> > +
> > +... where the address X is as low as the design of the boot loader
> > +permits.
>
> That seems to be the legend of the artwork. I would indent it, in
> order to be shown inside the artwork.
>
agree.
> > +
> > +
> > +THE REAL-MODE KERNEL HEADER
> > +===========================
> > +
> > +In the following text, and anywhere in the kernel boot sequence, "a
> > +sector" refers to 512 bytes. It is independent of the actual sector
> > +size of the underlying medium.
> > +
> > +The first step in loading a Linux kernel should be to load the
> > +real-mode code (boot sector and setup code) and then examine the
> > +following header at offset 0x01f1. The real-mode code can total up to
> > +32K, although the boot loader may choose to load only the first two
> > +sectors (1K) and then examine the bootup sector size.
> > +
> > +The header looks like::
> > +
> > + Offset Proto Name Meaning
> > + /Size
> > +
> > + 01F1/1 ALL(1 setup_sects The size of the setup in sectors
> > + 01F2/2 ALL root_flags If set, the root is mounted readonly
> > + 01F4/4 2.04+(2 syssize The size of the 32-bit code in 16-byte paras
> > + 01F8/2 ALL ram_size DO NOT USE - for bootsect.S use only
> > + 01FA/2 ALL vid_mode Video mode control
> > + 01FC/2 ALL root_dev Default root device number
> > + 01FE/2 ALL boot_flag 0xAA55 magic number
> > + 0200/2 2.00+ jump Jump instruction
> > + 0202/4 2.00+ header Magic signature "HdrS"
> > + 0206/2 2.00+ version Boot protocol version supported
> > + 0208/4 2.00+ realmode_swtch Boot loader hook (see below)
> > + 020C/2 2.00+ start_sys_seg The load-low segment (0x1000) (obsolete)
> > + 020E/2 2.00+ kernel_version Pointer to kernel version string
> > + 0210/1 2.00+ type_of_loader Boot loader identifier
> > + 0211/1 2.00+ loadflags Boot protocol option flags
> > + 0212/2 2.00+ setup_move_size Move to high memory size (used with hooks)
> > + 0214/4 2.00+ code32_start Boot loader hook (see below)
> > + 0218/4 2.00+ ramdisk_image initrd load address (set by boot loader)
> > + 021C/4 2.00+ ramdisk_size initrd size (set by boot loader)
> > + 0220/4 2.00+ bootsect_kludge DO NOT USE - for bootsect.S use only
> > + 0224/2 2.01+ heap_end_ptr Free memory after setup end
> > + 0226/1 2.02+(3 ext_loader_ver Extended boot loader version
> > + 0227/1 2.02+(3 ext_loader_type Extended boot loader ID
> > + 0228/4 2.02+ cmd_line_ptr 32-bit pointer to the kernel command line
> > + 022C/4 2.03+ initrd_addr_max Highest legal initrd address
> > + 0230/4 2.05+ kernel_alignment Physical addr alignment required for kernel
> > + 0234/1 2.05+ relocatable_kernel Whether kernel is relocatable or not
> > + 0235/1 2.10+ min_alignment Minimum alignment, as a power of two
> > + 0236/2 2.12+ xloadflags Boot protocol option flags
> > + 0238/4 2.06+ cmdline_size Maximum size of the kernel command line
> > + 023C/4 2.07+ hardware_subarch Hardware subarchitecture
> > + 0240/8 2.07+ hardware_subarch_data Subarchitecture-specific data
> > + 0248/4 2.08+ payload_offset Offset of kernel payload
> > + 024C/4 2.08+ payload_length Length of kernel payload
> > + 0250/8 2.09+ setup_data 64-bit physical pointer to linked list
> > + of struct setup_data
> > + 0258/8 2.10+ pref_address Preferred loading address
> > + 0260/4 2.10+ init_size Linear memory required during initialization
> > + 0264/4 2.11+ handover_offset Offset of handover entry point
>
> This is a table. Please use table markups and fix some wrong indentation
> there, as it makes a lot easier to read it on html, e-pub and pdf formats.
>
> E. g. something like:
>
> ====== ======== ===================== ========================================
> Offset Proto Name Meaning
> /Size
>
> 01F1/1 ALL(1) setup_sects The size of the setup in sectors
> 01F2/2 ALL root_flags If set, the root is mounted readonly
> 01F4/4 2.04+(2) syssize The size of the 32-bit code in 16-byte
> paras
> 01F8/2 ALL ram_size DO NOT USE - for bootsect.S use only
> 01FA/2 ALL vid_mode Video mode control
> 01FC/2 ALL root_dev Default root device number
> 01FE/2 ALL boot_flag 0xAA55 magic number
> 0200/2 2.00+ jump Jump instruction
> 0202/4 2.00+ header Magic signature "HdrS"
> 0206/2 2.00+ version Boot protocol version supported
> 0208/4 2.00+ realmode_swtch Boot loader hook (see below)
> 020C/2 2.00+ start_sys_seg The load-low segment (0x1000) (obsolete)
> 020E/2 2.00+ kernel_version Pointer to kernel version string
> 0210/1 2.00+ type_of_loader Boot loader identifier
> 0211/1 2.00+ loadflags Boot protocol option flags
> 0212/2 2.00+ setup_move_size Move to high memory size
> (used with hooks)
> 0214/4 2.00+ code32_start Boot loader hook (see below)
> 0218/4 2.00+ ramdisk_image initrd load address (set by boot loader)
> 021C/4 2.00+ ramdisk_size initrd size (set by boot loader)
> 0220/4 2.00+ bootsect_kludge DO NOT USE - for bootsect.S use only
> 0224/2 2.01+ heap_end_ptr Free memory after setup end
> 0226/1 2.02+(3) ext_loader_ver Extended boot loader version
> 0227/1 2.02+(3) ext_loader_type Extended boot loader ID
> 0228/4 2.02+ cmd_line_ptr 32-bit pointer to the kernel command line
> 022C/4 2.03+ initrd_addr_max Highest legal initrd address
> 0230/4 2.05+ kernel_alignment Physical addr alignment required for
> kernel
> 0234/1 2.05+ relocatable_kernel Whether kernel is relocatable or not
> 0235/1 2.10+ min_alignment Minimum alignment, as a power of two
> 0236/2 2.12+ xloadflags Boot protocol option flags
> 0238/4 2.06+ cmdline_size Maximum size of the kernel command line
> 023C/4 2.07+ hardware_subarch Hardware subarchitecture
> 0240/8 2.07+ hardware_subarch_data Subarchitecture-specific data
> 0248/4 2.08+ payload_offset Offset of kernel payload
> 024C/4 2.08+ payload_length Length of kernel payload
> 0250/8 2.09+ setup_data 64-bit physical pointer to linked list
> of struct setup_data
> 0258/8 2.10+ pref_address Preferred loading address
> 0260/4 2.10+ init_size Linear memory required during
> initialization
> 0264/4 2.11+ handover_offset Offset of handover entry point
> ====== ======== ===================== ========================================
>
>
done as table.
> > +
> > +(1) For backwards compatibility, if the setup_sects field contains 0, the
> > + real value is 4.
> > +
> > +(2) For boot protocol prior to 2.04, the upper two bytes of the syssize
> > + field are unusable, which means the size of a bzImage kernel
> > + cannot be determined.
> > +
> > +(3) Ignored, but safe to set, for boot protocols 2.02-2.09.
>
> Btw, (1), (2) and (3) here sounds to be footnotes. Perhaps you could use
> ReST footnote markups, if ok for the X86 maintainers.
>
Turned into footnote.
> > +
> > +If the "HdrS" (0x53726448) magic number is not found at offset 0x202,
> > +the boot protocol version is "old". Loading an old kernel, the
> > +following parameters should be assumed::
> > +
> > + Image type = zImage
> > + initrd not supported
> > + Real-mode kernel must be located at 0x90000.
> > +
> > +Otherwise, the "version" field contains the protocol version,
> > +e.g. protocol version 2.01 will contain 0x0201 in this field. When
> > +setting fields in the header, you must make sure only to set fields
> > +supported by the protocol version in use.
> > +
> > +
> > +DETAILS OF HEADER FIELDS
> > +========================
> > +
> > +For each field, some are information from the kernel to the bootloader
> > +("read"), some are expected to be filled out by the bootloader
> > +("write"), and some are expected to be read and modified by the
> > +bootloader ("modify").
> > +
> > +All general purpose boot loaders should write the fields marked
> > +(obligatory). Boot loaders who want to load the kernel at a
> > +nonstandard address should fill in the fields marked (reloc); other
> > +boot loaders can ignore those fields.
> > +
> > +The byte order of all fields is littleendian (this is x86, after all.)
> > +::
> > +
> > + Field name: setup_sects
> > + Type: read
> > + Offset/size: 0x1f1/1
> > + Protocol: ALL
>
> Marking this as a literal block sounds plain wrong to me. I suspect that
> you could use this syntax instead:
>
> :Field name: setup_sects
> :Type: read
> :Offset/size: 0x1f1/1
> :Protocol: ALL
>
> Or:
>
> Field name: setup_sects
> -----------------------
>
> Type:
> read
> Offset/size:
> 0x1f1/1
> Protocol:
> ALL
>
> Or (my favorite):
>
> Field name: setup_sects
> -----------------------
>
> :Type: read
> :Offset/size: 0x1f1/1
> :Protocol: ALL
>
> As it is more compact in text, and will provide a much better
> html/pdf output. It will also make (IMHO) a lot easier for
> people to read in text and seek for an specific field.
>
> Of course, whatever we do here should be applied to all similar
> structs inside this file.
>
I convert them to tables. The output looks good. Thanks.
> > +
> > +The size of the setup code in 512-byte sectors. If this field is
> > +0, the real value is 4. The real-mode code consists of the boot
> > +sector (always one 512-byte sector) plus the setup code.
> > +::
> > +
> > + Field name: root_flags
> > + Type: modify (optional)
> > + Offset/size: 0x1f2/2
> > + Protocol: ALL
> > +
> > +If this field is nonzero, the root defaults to readonly. The use of
> > +this field is deprecated; use the "ro" or "rw" options on the
> > +command line instead.
> > +::
> > +
> > + Field name: syssize
> > + Type: read
> > + Offset/size: 0x1f4/4 (protocol 2.04+) 0x1f4/2 (protocol ALL)
> > + Protocol: 2.04+
> > +
> > +The size of the protected-mode code in units of 16-byte paragraphs.
> > +For protocol versions older than 2.04 this field is only two bytes
> > +wide, and therefore cannot be trusted for the size of a kernel if
> > +the LOAD_HIGH flag is set.
> > +::
> > +
> > + Field name: ram_size
> > + Type: kernel internal
> > + Offset/size: 0x1f8/2
> > + Protocol: ALL
> > +
> > +This field is obsolete.
> > +::
> > +
> > + Field name: vid_mode
> > + Type: modify (obligatory)
> > + Offset/size: 0x1fa/2
> > +
> > +Please see the section on SPECIAL COMMAND LINE OPTIONS.
> > +::
> > +
> > + Field name: root_dev
> > + Type: modify (optional)
> > + Offset/size: 0x1fc/2
> > + Protocol: ALL
> > +
> > +The default root device device number. The use of this field is
> > +deprecated, use the "root=" option on the command line instead.
> > +::
> > +
> > + Field name: boot_flag
> > + Type: read
> > + Offset/size: 0x1fe/2
> > + Protocol: ALL
> > +
> > +Contains 0xAA55. This is the closest thing old Linux kernels have
> > +to a magic number.
> > +::
> > +
> > + Field name: jump
> > + Type: read
> > + Offset/size: 0x200/2
> > + Protocol: 2.00+
> > +
> > +Contains an x86 jump instruction, 0xEB followed by a signed offset
> > +relative to byte 0x202. This can be used to determine the size of
> > +the header.
> > +::
> > +
> > + Field name: header
> > + Type: read
> > + Offset/size: 0x202/4
> > + Protocol: 2.00+
> > +
> > +Contains the magic number "HdrS" (0x53726448).
> > +::
> > +
> > + Field name: version
> > + Type: read
> > + Offset/size: 0x206/2
> > + Protocol: 2.00+
> > +
> > +Contains the boot protocol version, in (major << 8)+minor format,
> > +e.g. 0x0204 for version 2.04, and 0x0a11 for a hypothetical version
> > +10.17.
> > +::
> > +
> > + Field name: realmode_swtch
> > + Type: modify (optional)
> > + Offset/size: 0x208/4
> > + Protocol: 2.00+
> > +
> > +Boot loader hook (see ADVANCED BOOT LOADER HOOKS below.)
> > +::
> > +
> > + Field name: start_sys_seg
> > + Type: read
> > + Offset/size: 0x20c/2
> > + Protocol: 2.00+
> > +
> > +The load low segment (0x1000). Obsolete.
> > +::
> > +
> > + Field name: kernel_version
> > + Type: read
> > + Offset/size: 0x20e/2
> > + Protocol: 2.00+
> > +
> > +If set to a nonzero value, contains a pointer to a NUL-terminated
> > +human-readable kernel version number string, less 0x200. This can
> > +be used to display the kernel version to the user. This value
> > +should be less than (0x200*setup_sects).
> > +
> > +For example, if this value is set to 0x1c00, the kernel version
> > +number string can be found at offset 0x1e00 in the kernel file.
> > +This is a valid value if and only if the "setup_sects" field
> > +contains the value 15 or higher, as::
> > +
> > + 0x1c00 < 15*0x200 (= 0x1e00) but
> > + 0x1c00 >= 14*0x200 (= 0x1c00)
> > +
> > + 0x1c00 >> 9 = 14, so the minimum value for setup_secs is 15.
> > +
> > +::
> > +
> > + Field name: type_of_loader
> > + Type: write (obligatory)
> > + Offset/size: 0x210/1
> > + Protocol: 2.00+
> > +
> > +If your boot loader has an assigned id (see table below), enter
> > +0xTV here, where T is an identifier for the boot loader and V is
> > +a version number. Otherwise, enter 0xFF here.
> > +
> > +For boot loader IDs above T = 0xD, write T = 0xE to this field and
> > +write the extended ID minus 0x10 to the ext_loader_type field.
> > +Similarly, the ext_loader_ver field can be used to provide more than
> > +four bits for the bootloader version.
> > +
> > +For example, for T = 0x15, V = 0x234, write::
> > +
> > + type_of_loader <- 0xE4
> > + ext_loader_type <- 0x05
> > + ext_loader_ver <- 0x23
> > +
> > +Assigned boot loader ids (hexadecimal)::
> > +
> > + 0 LILO (0x00 reserved for pre-2.00 bootloader)
> > + 1 Loadlin
> > + 2 bootsect-loader (0x20, all other values reserved)
> > + 3 Syslinux
> > + 4 Etherboot/gPXE/iPXE
> > + 5 ELILO
> > + 7 GRUB
> > + 8 U-Boot
> > + 9 Xen
> > + A Gujin
> > + B Qemu
> > + C Arcturus Networks uCbootloader
> > + D kexec-tools
> > + E Extended (see ext_loader_type)
> > + F Special (0xFF = undefined)
> > + 10 Reserved
> > + 11 Minimal Linux Bootloader <http://sebastian-plotz.blogspot.de>
> > + 12 OVMF UEFI virtualization stack
>
> Clearly there's something wrong with the last 3 lines, as they aren't
> following the expected indentation.
>
> Anyway, IMO the best would be to use a table, instead:
>
> == =======================================
> 0 LILO
> (0x00 reserved for pre-2.00 bootloader)
> 1 Loadlin
> 2 bootsect-loader
> (0x20, all other values reserved)
> 3 Syslinux
> 4 Etherboot/gPXE/iPXE
> 5 ELILO
> 7 GRUB
> 8 U-Boot
> 9 Xen
> A Gujin
> B Qemu
> C Arcturus Networks uCbootloader
> D kexec-tools
> E Extended
> (see ext_loader_type)
> F Special
> (0xFF = undefined)
> 10 Reserved
> 11 Minimal Linux Bootloader
> <http://sebastian-plotz.blogspot.de>
> 12 OVMF UEFI virtualization stack
> == =======================================
>
done.
>
>
> > +
> > +Please contact <hpa@zytor.com> if you need a bootloader ID value assigned.
> > +::
> > +
> > + Field name: loadflags
> > + Type: modify (obligatory)
> > + Offset/size: 0x211/1
> > + Protocol: 2.00+
> > +
> > +This field is a bitmask.
> > +::
> > +
> > + Bit 0 (read): LOADED_HIGH
> > + - If 0, the protected-mode code is loaded at 0x10000.
> > + - If 1, the protected-mode code is loaded at 0x100000.
> > +
> > + Bit 1 (kernel internal): KASLR_FLAG
> > + - Used internally by the compressed kernel to communicate
> > + KASLR status to kernel proper.
> > + If 1, KASLR enabled.
> > + If 0, KASLR disabled.
>
> You need to either add blank lines or add a "- " before the
> two if's above.
>
done.
> > +
> > + Bit 5 (write): QUIET_FLAG
> > + - If 0, print early messages.
> > + - If 1, suppress early messages.
> > + This requests to the kernel (decompressor and early
> > + kernel) to not write early messages that require
> > + accessing the display hardware directly.
> > +
> > + Bit 6 (write): KEEP_SEGMENTS
> > + Protocol: 2.07+
> > + - If 0, reload the segment registers in the 32bit entry point.
> > + - If 1, do not reload the segment registers in the 32bit entry point.
> > + Assume that %cs %ds %ss %es are all set to flat segments with
> > + a base of 0 (or the equivalent for their environment).
> > +
> > + Bit 7 (write): CAN_USE_HEAP
> > + Set this bit to 1 to indicate that the value entered in the
> > + heap_end_ptr is valid. If this field is clear, some setup code
> > + functionality will be disabled.
> > +
> > +::
> > +
> > + Field name: setup_move_size
> > + Type: modify (obligatory)
> > + Offset/size: 0x212/2
> > + Protocol: 2.00-2.01
> > +
> > +When using protocol 2.00 or 2.01, if the real mode kernel is not
> > +loaded at 0x90000, it gets moved there later in the loading
> > +sequence. Fill in this field if you want additional data (such as
> > +the kernel command line) moved in addition to the real-mode kernel
> > +itself.
> > +
> > +The unit is bytes starting with the beginning of the boot sector.
> > +
> > +This field is can be ignored when the protocol is 2.02 or higher, or
> > +if the real-mode code is loaded at 0x90000.
> > +::
> > +
> > + Field name: code32_start
> > + Type: modify (optional, reloc)
> > + Offset/size: 0x214/4
> > + Protocol: 2.00+
> > +
> > +The address to jump to in protected mode. This defaults to the load
> > +address of the kernel, and can be used by the boot loader to
> > +determine the proper load address.
> > +
> > +This field can be modified for two purposes:
> > +
> > + 1. as a boot loader hook (see ADVANCED BOOT LOADER HOOKS below.)
> > +
> > + 2. if a bootloader which does not install a hook loads a
> > + relocatable kernel at a nonstandard address it will have to modify
> > + this field to point to the load address.
> > +
> > +::
> > +
> > + Field name: ramdisk_image
> > + Type: write (obligatory)
> > + Offset/size: 0x218/4
> > + Protocol: 2.00+
> > +
> > +The 32-bit linear address of the initial ramdisk or ramfs. Leave at
> > +zero if there is no initial ramdisk/ramfs.
> > +::
> > +
> > + Field name: ramdisk_size
> > + Type: write (obligatory)
> > + Offset/size: 0x21c/4
> > + Protocol: 2.00+
> > +
> > +Size of the initial ramdisk or ramfs. Leave at zero if there is no
> > +initial ramdisk/ramfs.
> > +::
> > +
> > + Field name: bootsect_kludge
> > + Type: kernel internal
> > + Offset/size: 0x220/4
> > + Protocol: 2.00+
> > +
> > +This field is obsolete.
> > +::
> > +
> > + Field name: heap_end_ptr
> > + Type: write (obligatory)
> > + Offset/size: 0x224/2
> > + Protocol: 2.01+
> > +
> > +Set this field to the offset (from the beginning of the real-mode
> > +code) of the end of the setup stack/heap, minus 0x0200.
> > +::
> > +
> > + Field name: ext_loader_ver
> > + Type: write (optional)
> > + Offset/size: 0x226/1
> > + Protocol: 2.02+
> > +
> > +This field is used as an extension of the version number in the
> > +type_of_loader field. The total version number is considered to be
> > +(type_of_loader & 0x0f) + (ext_loader_ver << 4).
> > +
> > +The use of this field is boot loader specific. If not written, it
> > +is zero.
> > +
> > +Kernels prior to 2.6.31 did not recognize this field, but it is safe
> > +to write for protocol version 2.02 or higher.
> > +::
> > +
> > + Field name: ext_loader_type
> > + Type: write (obligatory if (type_of_loader & 0xf0) == 0xe0)
> > + Offset/size: 0x227/1
> > + Protocol: 2.02+
> > +
> > +This field is used as an extension of the type number in
> > +type_of_loader field. If the type in type_of_loader is 0xE, then
> > +the actual type is (ext_loader_type + 0x10).
> > +
> > +This field is ignored if the type in type_of_loader is not 0xE.
> > +
> > +Kernels prior to 2.6.31 did not recognize this field, but it is safe
> > +to write for protocol version 2.02 or higher.
> > +::
> > +
> > + Field name: cmd_line_ptr
> > + Type: write (obligatory)
> > + Offset/size: 0x228/4
> > + Protocol: 2.02+
> > +
> > +Set this field to the linear address of the kernel command line.
> > +The kernel command line can be located anywhere between the end of
> > +the setup heap and 0xA0000; it does not have to be located in the
> > +same 64K segment as the real-mode code itself.
> > +
> > +Fill in this field even if your boot loader does not support a
> > +command line, in which case you can point this to an empty string
> > +(or better yet, to the string "auto".) If this field is left at
> > +zero, the kernel will assume that your boot loader does not support
> > +the 2.02+ protocol.
> > +::
> > +
> > + Field name: initrd_addr_max
> > + Type: read
> > + Offset/size: 0x22c/4
> > + Protocol: 2.03+
> > +
> > +The maximum address that may be occupied by the initial
> > +ramdisk/ramfs contents. For boot protocols 2.02 or earlier, this
> > +field is not present, and the maximum address is 0x37FFFFFF. (This
> > +address is defined as the address of the highest safe byte, so if
> > +your ramdisk is exactly 131072 bytes long and this field is
> > +0x37FFFFFF, you can start your ramdisk at 0x37FE0000.)
> > +::
> > +
> > + Field name: kernel_alignment
> > + Type: read/modify (reloc)
> > + Offset/size: 0x230/4
> > + Protocol: 2.05+ (read), 2.10+ (modify)
> > +
> > +Alignment unit required by the kernel (if relocatable_kernel is
> > +true.) A relocatable kernel that is loaded at an alignment
> > +incompatible with the value in this field will be realigned during
> > +kernel initialization.
> > +
> > +Starting with protocol version 2.10, this reflects the kernel
> > +alignment preferred for optimal performance; it is possible for the
> > +loader to modify this field to permit a lesser alignment. See the
> > +min_alignment and pref_address field below.
> > +::
> > +
> > + Field name: relocatable_kernel
> > + Type: read (reloc)
> > + Offset/size: 0x234/1
> > + Protocol: 2.05+
> > +
> > +If this field is nonzero, the protected-mode part of the kernel can
> > +be loaded at any address that satisfies the kernel_alignment field.
> > +After loading, the boot loader must set the code32_start field to
> > +point to the loaded code, or to a boot loader hook.
> > +::
> > +
> > + Field name: min_alignment
> > + Type: read (reloc)
> > + Offset/size: 0x235/1
> > + Protocol: 2.10+
> > +
> > +This field, if nonzero, indicates as a power of two the minimum
> > +alignment required, as opposed to preferred, by the kernel to boot.
> > +If a boot loader makes use of this field, it should update the
> > +kernel_alignment field with the alignment unit desired; typically::
> > +
> > + kernel_alignment = 1 << min_alignment
> > +
> > +There may be a considerable performance cost with an excessively
> > +misaligned kernel. Therefore, a loader should typically try each
> > +power-of-two alignment from kernel_alignment down to this alignment.
> > +::
> > +
> > + Field name: xloadflags
> > + Type: read
> > + Offset/size: 0x236/2
> > + Protocol: 2.12+
> > +
> > +This field is a bitmask.
> > +::
> > +
> > + Bit 0 (read): XLF_KERNEL_64
> > + - If 1, this kernel has the legacy 64-bit entry point at 0x200.
> > +
> > + Bit 1 (read): XLF_CAN_BE_LOADED_ABOVE_4G
> > + - If 1, kernel/boot_params/cmdline/ramdisk can be above 4G.
>
> Please indent it the same way as Bit 0.
>
done.
> > +
> > + Bit 2 (read): XLF_EFI_HANDOVER_32
> > + - If 1, the kernel supports the 32-bit EFI handoff entry point
> > + given at handover_offset.
> > +
> > + Bit 3 (read): XLF_EFI_HANDOVER_64
> > + - If 1, the kernel supports the 64-bit EFI handoff entry point
> > + given at handover_offset + 0x200.
> > +
> > + Bit 4 (read): XLF_EFI_KEXEC
> > + - If 1, the kernel supports kexec EFI boot with EFI runtime support.
> > +
> > +::
> > +
> > + Field name: cmdline_size
> > + Type: read
> > + Offset/size: 0x238/4
> > + Protocol: 2.06+
> > +
> > +The maximum size of the command line without the terminating
> > +zero. This means that the command line can contain at most
> > +cmdline_size characters. With protocol version 2.05 and earlier, the
> > +maximum size was 255.
> > +::
> > +
> > + Field name: hardware_subarch
> > + Type: write (optional, defaults to x86/PC)
> > + Offset/size: 0x23c/4
> > + Protocol: 2.07+
> > +
> > +In a paravirtualized environment the hardware low level architectural
> > +pieces such as interrupt handling, page table handling, and
> > +accessing process control registers needs to be done differently.
> > +
> > +This field allows the bootloader to inform the kernel we are in one
> > +one of those environments.
> > +::
> > +
> > + 0x00000000 The default x86/PC environment
> > + 0x00000001 lguest
> > + 0x00000002 Xen
> > + 0x00000003 Moorestown MID
> > + 0x00000004 CE4100 TV Platform
>
> This is already a table. Just add the markups for it, instead of using '::'
>
> e. g.:
>
> + ========== ==============================
> 0x00000000 The default x86/PC environment
> 0x00000001 lguest
> 0x00000002 Xen
> 0x00000003 Moorestown MID
> 0x00000004 CE4100 TV Platform
> + ========== ==============================
>
done.
>
> > +
> > +::
> > +
> > + Field name: hardware_subarch_data
> > + Type: write (subarch-dependent)
> > + Offset/size: 0x240/8
> > + Protocol: 2.07+
> > +
> > +A pointer to data that is specific to hardware subarch
> > +This field is currently unused for the default x86/PC environment,
> > +do not modify.
> > +::
> > +
> > + Field name: payload_offset
> > + Type: read
> > + Offset/size: 0x248/4
> > + Protocol: 2.08+
> > +
> > +If non-zero then this field contains the offset from the beginning
> > +of the protected-mode code to the payload.
> > +
> > +The payload may be compressed. The format of both the compressed and
> > +uncompressed data should be determined using the standard magic
> > +numbers. The currently supported compression formats are gzip
> > +(magic numbers 1F 8B or 1F 9E), bzip2 (magic number 42 5A), LZMA
> > +(magic number 5D 00), XZ (magic number FD 37), and LZ4 (magic number
> > +02 21). The uncompressed payload is currently always ELF (magic
> > +number 7F 45 4C 46).
> > +::
> > +
> > + Field name: payload_length
> > + Type: read
> > + Offset/size: 0x24c/4
> > + Protocol: 2.08+
> > +
> > +The length of the payload.
> > +::
> > +
> > + Field name: setup_data
> > + Type: write (special)
> > + Offset/size: 0x250/8
> > + Protocol: 2.09+
> > +
> > +The 64-bit physical pointer to NULL terminated single linked list of
> > +struct setup_data. This is used to define a more extensible boot
> > +parameters passing mechanism. The definition of struct setup_data is
> > +as follow::
> > +
> > + struct setup_data {
> > + u64 next;
> > + u32 type;
> > + u32 len;
> > + u8 data[0];
> > + };
> > +
> > +Where, the next is a 64-bit physical pointer to the next node of
> > +linked list, the next field of the last node is 0; the type is used
> > +to identify the contents of data; the len is the length of data
> > +field; the data holds the real payload.
> > +
> > +This list may be modified at a number of points during the bootup
> > +process. Therefore, when modifying this list one should always make
> > +sure to consider the case where the linked list already contains
> > +entries.
> > +::
> > +
> > + Field name: pref_address
> > + Type: read (reloc)
> > + Offset/size: 0x258/8
> > + Protocol: 2.10+
> > +
> > +This field, if nonzero, represents a preferred load address for the
> > +kernel. A relocating bootloader should attempt to load at this
> > +address if possible.
> > +
> > +A non-relocatable kernel will unconditionally move itself and to run
> > +at this address.
> > +::
> > +
> > + Field name: init_size
> > + Type: read
> > + Offset/size: 0x260/4
> > +
> > +This field indicates the amount of linear contiguous memory starting
> > +at the kernel runtime start address that the kernel needs before it
> > +is capable of examining its memory map. This is not the same thing
> > +as the total amount of memory the kernel needs to boot, but it can
> > +be used by a relocating boot loader to help select a safe load
> > +address for the kernel.
> > +
> > +The kernel runtime start address is determined by the following algorithm::
> > +
> > + if (relocatable_kernel)
> > + runtime_start = align_up(load_address, kernel_alignment)
> > + else
> > + runtime_start = pref_address
> > +
> > +::
> > +
> > + Field name: handover_offset
> > + Type: read
> > + Offset/size: 0x264/4
> > +
> > +This field is the offset from the beginning of the kernel image to
> > +the EFI handover protocol entry point. Boot loaders using the EFI
> > +handover protocol to boot the kernel should jump to this offset.
> > +
> > +See EFI HANDOVER PROTOCOL below for more details.
> > +
> > +
> > +THE IMAGE CHECKSUM
> > +==================
> > +
> > +From boot protocol version 2.08 onwards the CRC-32 is calculated over
> > +the entire file using the characteristic polynomial 0x04C11DB7 and an
> > +initial remainder of 0xffffffff. The checksum is appended to the
> > +file; therefore the CRC of the file up to the limit specified in the
> > +syssize field of the header is always 0.
> > +
> > +
> > +THE KERNEL COMMAND LINE
> > +=======================
> > +
> > +The kernel command line has become an important way for the boot
> > +loader to communicate with the kernel. Some of its options are also
> > +relevant to the boot loader itself, see "special command line options"
> > +below.
> > +
> > +The kernel command line is a null-terminated string. The maximum
> > +length can be retrieved from the field cmdline_size. Before protocol
> > +version 2.06, the maximum was 255 characters. A string that is too
> > +long will be automatically truncated by the kernel.
> > +
> > +If the boot protocol version is 2.02 or later, the address of the
> > +kernel command line is given by the header field cmd_line_ptr (see
> > +above.) This address can be anywhere between the end of the setup
> > +heap and 0xA0000.
> > +
> > +If the protocol version is *not* 2.02 or higher, the kernel
> > +command line is entered using the following protocol:
> > +
> > + - At offset 0x0020 (word), "cmd_line_magic", enter the magic
> > + number 0xA33F.
> > +
> > + - At offset 0x0022 (word), "cmd_line_offset", enter the offset
> > + of the kernel command line (relative to the start of the
> > + real-mode kernel).
> > +
> > + - The kernel command line *must* be within the memory region
> > + covered by setup_move_size, so you may need to adjust this
> > + field.
> > +
> > +
> > +MEMORY LAYOUT OF THE REAL-MODE CODE
> > +===================================
> > +
> > +The real-mode code requires a stack/heap to be set up, as well as
> > +memory allocated for the kernel command line. This needs to be done
> > +in the real-mode accessible memory in bottom megabyte.
> > +
> > +It should be noted that modern machines often have a sizable Extended
> > +BIOS Data Area (EBDA). As a result, it is advisable to use as little
> > +of the low megabyte as possible.
> > +
> > +Unfortunately, under the following circumstances the 0x90000 memory
> > +segment has to be used:
> > +
> > + - When loading a zImage kernel ((loadflags & 0x01) == 0).
> > + - When loading a 2.01 or earlier boot protocol kernel.
> > +
> > + For the 2.00 and 2.01 boot protocols, the real-mode code
> > + can be loaded at another address, but it is internally
> > + relocated to 0x90000. For the "old" protocol, the
> > + real-mode code must be loaded at 0x90000.
> > +
> > +When loading at 0x90000, avoid using memory above 0x9a000.
> > +
> > +For boot protocol 2.02 or higher, the command line does not have to be
> > +located in the same 64K segment as the real-mode setup code; it is
> > +thus permitted to give the stack/heap the full 64K segment and locate
> > +the command line above it.
> > +
> > +The kernel command line should not be located below the real-mode
> > +code, nor should it be located in high memory.
> > +
> > +
> > +SAMPLE BOOT CONFIGURATION
> > +=========================
> > +
> > +As a sample configuration, assume the following layout of the real
> > +mode segment.
> > +
>
>
> > +When loading below 0x90000, use the entire segment::
> > +
> > + 0x0000-0x7fff Real mode kernel
> > + 0x8000-0xdfff Stack and heap
> > + 0xe000-0xffff Kernel command line
> > +
> > +When loading at 0x90000 OR the protocol version is 2.01 or earlier::
> > +
> > + 0x0000-0x7fff Real mode kernel
> > + 0x8000-0x97ff Stack and heap
> > + 0x9800-0x9fff Kernel command line
>
> Again, tables. Just do:
>
> When loading below 0x90000, use the entire segment:
>
> + ============= ===================
> 0x0000-0x7fff Real mode kernel
> 0x8000-0xdfff Stack and heap
> 0xe000-0xffff Kernel command line
> + ============= ===================
>
> When loading at 0x90000 OR the protocol version is 2.01 or earlier:
>
> + ============= ===================
> 0x0000-0x7fff Real mode kernel
> 0x8000-0x97ff Stack and heap
> 0x9800-0x9fff Kernel command line
> + ============= ===================
>
done.
>
>
> > +
> > +Such a boot loader should enter the following fields in the header::
> > +
> > + unsigned long base_ptr; /* base address for real-mode segment */
> > +
> > + if ( setup_sects == 0 ) {
> > + setup_sects = 4;
> > + }
> > +
> > + if ( protocol >= 0x0200 ) {
> > + type_of_loader = <type code>;
> > + if ( loading_initrd ) {
> > + ramdisk_image = <initrd_address>;
> > + ramdisk_size = <initrd_size>;
> > + }
> > +
> > + if ( protocol >= 0x0202 && loadflags & 0x01 )
> > + heap_end = 0xe000;
> > + else
> > + heap_end = 0x9800;
> > +
> > + if ( protocol >= 0x0201 ) {
> > + heap_end_ptr = heap_end - 0x200;
> > + loadflags |= 0x80; /* CAN_USE_HEAP */
> > + }
> > +
> > + if ( protocol >= 0x0202 ) {
> > + cmd_line_ptr = base_ptr + heap_end;
> > + strcpy(cmd_line_ptr, cmdline);
> > + } else {
> > + cmd_line_magic = 0xA33F;
> > + cmd_line_offset = heap_end;
> > + setup_move_size = heap_end + strlen(cmdline)+1;
> > + strcpy(base_ptr+cmd_line_offset, cmdline);
> > + }
> > + } else {
> > + /* Very old kernel */
> > +
> > + heap_end = 0x9800;
> > +
> > + cmd_line_magic = 0xA33F;
> > + cmd_line_offset = heap_end;
> > +
> > + /* A very old kernel MUST have its real-mode code
> > + loaded at 0x90000 */
> > +
> > + if ( base_ptr != 0x90000 ) {
> > + /* Copy the real-mode kernel */
> > + memcpy(0x90000, base_ptr, (setup_sects+1)*512);
> > + base_ptr = 0x90000; /* Relocated */
> > + }
> > +
> > + strcpy(0x90000+cmd_line_offset, cmdline);
> > +
> > + /* It is recommended to clear memory up to the 32K mark */
> > + memset(0x90000 + (setup_sects+1)*512, 0,
> > + (64-(setup_sects+1))*512);
> > + }
> > +
> > +
> > +LOADING THE REST OF THE KERNEL
> > +==============================
> > +
> > +The 32-bit (non-real-mode) kernel starts at offset (setup_sects+1)*512
> > +in the kernel file (again, if setup_sects == 0 the real value is 4.)
> > +It should be loaded at address 0x10000 for Image/zImage kernels and
> > +0x100000 for bzImage kernels.
> > +
> > +The kernel is a bzImage kernel if the protocol >= 2.00 and the 0x01
> > +bit (LOAD_HIGH) in the loadflags field is set::
> > +
> > + is_bzImage = (protocol >= 0x0200) && (loadflags & 0x01);
> > + load_address = is_bzImage ? 0x100000 : 0x10000;
> > +
> > +Note that Image/zImage kernels can be up to 512K in size, and thus use
> > +the entire 0x10000-0x90000 range of memory. This means it is pretty
> > +much a requirement for these kernels to load the real-mode part at
> > +0x90000. bzImage kernels allow much more flexibility.
> > +
> > +
> > +SPECIAL COMMAND LINE OPTIONS
> > +============================
> > +
> > +If the command line provided by the boot loader is entered by the
> > +user, the user may expect the following command line options to work.
> > +They should normally not be deleted from the kernel command line even
> > +though not all of them are actually meaningful to the kernel. Boot
> > +loader authors who need additional command line options for the boot
> > +loader itself should get them registered in
> > +Documentation/admin-guide/kernel-parameters.rst to make sure they will not
> > +conflict with actual kernel options now or in the future.
> > +
> > + vga=<mode>
> > + <mode> here is either an integer (in C notation, either
> > + decimal, octal, or hexadecimal) or one of the strings
> > + "normal" (meaning 0xFFFF), "ext" (meaning 0xFFFE) or "ask"
> > + (meaning 0xFFFD). This value should be entered into the
> > + vid_mode field, as it is used by the kernel before the command
> > + line is parsed.
> > +
> > + mem=<size>
> > + <size> is an integer in C notation optionally followed by
> > + (case insensitive) K, M, G, T, P or E (meaning << 10, << 20,
> > + << 30, << 40, << 50 or << 60). This specifies the end of
> > + memory to the kernel. This affects the possible placement of
> > + an initrd, since an initrd should be placed near end of
> > + memory. Note that this is an option to *both* the kernel and
> > + the bootloader!
> > +
> > + initrd=<file>
> > + An initrd should be loaded. The meaning of <file> is
> > + obviously bootloader-dependent, and some boot loaders
> > + (e.g. LILO) do not have such a command.
> > +
> > +In addition, some boot loaders add the following options to the
> > +user-specified command line:
> > +
> > + BOOT_IMAGE=<file>
> > + The boot image which was loaded. Again, the meaning of <file>
> > + is obviously bootloader-dependent.
> > +
> > + auto
> > + The kernel was booted without explicit user intervention.
> > +
> > +If these options are added by the boot loader, it is highly
> > +recommended that they are located *first*, before the user-specified
> > +or configuration-specified command line. Otherwise, "init=/bin/sh"
> > +gets confused by the "auto" option.
> > +
> > +
> > +RUNNING THE KERNEL
> > +==================
> > +
> > +The kernel is started by jumping to the kernel entry point, which is
> > +located at *segment* offset 0x20 from the start of the real mode
> > +kernel. This means that if you loaded your real-mode kernel code at
> > +0x90000, the kernel entry point is 9020:0000.
> > +
> > +At entry, ds = es = ss should point to the start of the real-mode
> > +kernel code (0x9000 if the code is loaded at 0x90000), sp should be
> > +set up properly, normally pointing to the top of the heap, and
> > +interrupts should be disabled. Furthermore, to guard against bugs in
> > +the kernel, it is recommended that the boot loader sets fs = gs = ds =
> > +es = ss.
> > +
> > +In our example from above, we would do::
> > +
> > + /* Note: in the case of the "old" kernel protocol, base_ptr must
> > + be == 0x90000 at this point; see the previous sample code */
> > +
> > + seg = base_ptr >> 4;
> > +
> > + cli(); /* Enter with interrupts disabled! */
> > +
> > + /* Set up the real-mode kernel stack */
> > + _SS = seg;
> > + _SP = heap_end;
> > +
> > + _DS = _ES = _FS = _GS = seg;
> > + jmp_far(seg+0x20, 0); /* Run the kernel */
> > +
> > +If your boot sector accesses a floppy drive, it is recommended to
> > +switch off the floppy motor before running the kernel, since the
> > +kernel boot leaves interrupts off and thus the motor will not be
> > +switched off, especially if the loaded kernel has the floppy driver as
> > +a demand-loaded module!
> > +
> > +
> > +ADVANCED BOOT LOADER HOOKS
> > +==========================
> > +
> > +If the boot loader runs in a particularly hostile environment (such as
> > +LOADLIN, which runs under DOS) it may be impossible to follow the
> > +standard memory location requirements. Such a boot loader may use the
> > +following hooks that, if set, are invoked by the kernel at the
> > +appropriate time. The use of these hooks should probably be
> > +considered an absolutely last resort!
> > +
> > +IMPORTANT: All the hooks are required to preserve %esp, %ebp, %esi and
> > +%edi across invocation.
> > +
> > + realmode_swtch:
> > + A 16-bit real mode far subroutine invoked immediately before
> > + entering protected mode. The default routine disables NMI, so
> > + your routine should probably do so, too.
> > +
> > + code32_start:
> > + A 32-bit flat-mode routine *jumped* to immediately after the
> > + transition to protected mode, but before the kernel is
> > + uncompressed. No segments, except CS, are guaranteed to be
> > + set up (current kernels do, but older ones do not); you should
> > + set them up to BOOT_DS (0x18) yourself.
> > +
> > + After completing your hook, you should jump to the address
> > + that was in this field before your boot loader overwrote it
> > + (relocated, if appropriate.)
> > +
> > +
> > +32-bit BOOT PROTOCOL
> > +====================
> > +
> > +For machine with some new BIOS other than legacy BIOS, such as EFI,
> > +LinuxBIOS, etc, and kexec, the 16-bit real mode setup code in kernel
> > +based on legacy BIOS can not be used, so a 32-bit boot protocol needs
> > +to be defined.
> > +
> > +In 32-bit boot protocol, the first step in loading a Linux kernel
> > +should be to setup the boot parameters (struct boot_params,
> > +traditionally known as "zero page"). The memory for struct boot_params
> > +should be allocated and initialized to all zero. Then the setup header
> > +from offset 0x01f1 of kernel image on should be loaded into struct
> > +boot_params and examined. The end of setup header can be calculated as
> > +follow::
> > +
> > + 0x0202 + byte value at offset 0x0201
> > +
> > +In addition to read/modify/write the setup header of the struct
> > +boot_params as that of 16-bit boot protocol, the boot loader should
> > +also fill the additional fields of the struct boot_params as that
> > +described in zero-page.txt.
> > +
> > +After setting up the struct boot_params, the boot loader can load the
> > +32/64-bit kernel in the same way as that of 16-bit boot protocol.
> > +
> > +In 32-bit boot protocol, the kernel is started by jumping to the
> > +32-bit kernel entry point, which is the start address of loaded
> > +32/64-bit kernel.
> > +
> > +At entry, the CPU must be in 32-bit protected mode with paging
> > +disabled; a GDT must be loaded with the descriptors for selectors
> > +__BOOT_CS(0x10) and __BOOT_DS(0x18); both descriptors must be 4G flat
> > +segment; __BOOT_CS must have execute/read permission, and __BOOT_DS
> > +must have read/write permission; CS must be __BOOT_CS and DS, ES, SS
> > +must be __BOOT_DS; interrupt must be disabled; %esi must hold the base
> > +address of the struct boot_params; %ebp, %edi and %ebx must be zero.
> > +
> > +64-bit BOOT PROTOCOL
> > +====================
> > +
> > +For machine with 64bit cpus and 64bit kernel, we could use 64bit bootloader
> > +and we need a 64-bit boot protocol.
> > +
> > +In 64-bit boot protocol, the first step in loading a Linux kernel
> > +should be to setup the boot parameters (struct boot_params,
> > +traditionally known as "zero page"). The memory for struct boot_params
> > +could be allocated anywhere (even above 4G) and initialized to all zero.
> > +Then, the setup header at offset 0x01f1 of kernel image on should be
> > +loaded into struct boot_params and examined. The end of setup header
> > +can be calculated as follows::
> > +
> > + 0x0202 + byte value at offset 0x0201
> > +
> > +In addition to read/modify/write the setup header of the struct
> > +boot_params as that of 16-bit boot protocol, the boot loader should
> > +also fill the additional fields of the struct boot_params as described
> > +in zero-page.txt.
> > +
> > +After setting up the struct boot_params, the boot loader can load
> > +64-bit kernel in the same way as that of 16-bit boot protocol, but
> > +kernel could be loaded above 4G.
> > +
> > +In 64-bit boot protocol, the kernel is started by jumping to the
> > +64-bit kernel entry point, which is the start address of loaded
> > +64-bit kernel plus 0x200.
> > +
> > +At entry, the CPU must be in 64-bit mode with paging enabled.
> > +The range with setup_header.init_size from start address of loaded
> > +kernel and zero page and command line buffer get ident mapping;
> > +a GDT must be loaded with the descriptors for selectors
> > +__BOOT_CS(0x10) and __BOOT_DS(0x18); both descriptors must be 4G flat
> > +segment; __BOOT_CS must have execute/read permission, and __BOOT_DS
> > +must have read/write permission; CS must be __BOOT_CS and DS, ES, SS
> > +must be __BOOT_DS; interrupt must be disabled; %rsi must hold the base
> > +address of the struct boot_params.
> > +
> > +EFI HANDOVER PROTOCOL
> > +=====================
> > +
> > +This protocol allows boot loaders to defer initialisation to the EFI
> > +boot stub. The boot loader is required to load the kernel/initrd(s)
> > +from the boot media and jump to the EFI handover protocol entry point
> > +which is hdr->handover_offset bytes from the beginning of
> > +startup_{32,64}.
> > +
> > +The function prototype for the handover entry point looks like this::
> > +
> > + efi_main(void *handle, efi_system_table_t *table, struct boot_params *bp)
> > +
> > +'handle' is the EFI image handle passed to the boot loader by the EFI
> > +firmware, 'table' is the EFI system table - these are the first two
> > +arguments of the "handoff state" as described in section 2.3 of the
> > +UEFI specification. 'bp' is the boot loader-allocated boot params.
> > +
> > +The boot loader *must* fill out the following fields in bp::
> > +
> > + - hdr.code32_start
> > + - hdr.cmd_line_ptr
> > + - hdr.ramdisk_image (if applicable)
> > + - hdr.ramdisk_size (if applicable)
> > +
> > +All other fields should be zero.
> > diff --git a/Documentation/x86/boot.txt b/Documentation/x86/boot.txt
> > deleted file mode 100644
> > index f4c2a97bfdbd..000000000000
> > --- a/Documentation/x86/boot.txt
> > +++ /dev/null
> > @@ -1,1130 +0,0 @@
> > - THE LINUX/x86 BOOT PROTOCOL
> > - ---------------------------
> > -
> > -On the x86 platform, the Linux kernel uses a rather complicated boot
> > -convention. This has evolved partially due to historical aspects, as
> > -well as the desire in the early days to have the kernel itself be a
> > -bootable image, the complicated PC memory model and due to changed
> > -expectations in the PC industry caused by the effective demise of
> > -real-mode DOS as a mainstream operating system.
> > -
> > -Currently, the following versions of the Linux/x86 boot protocol exist.
> > -
> > -Old kernels: zImage/Image support only. Some very early kernels
> > - may not even support a command line.
> > -
> > -Protocol 2.00: (Kernel 1.3.73) Added bzImage and initrd support, as
> > - well as a formalized way to communicate between the
> > - boot loader and the kernel. setup.S made relocatable,
> > - although the traditional setup area still assumed
> > - writable.
> > -
> > -Protocol 2.01: (Kernel 1.3.76) Added a heap overrun warning.
> > -
> > -Protocol 2.02: (Kernel 2.4.0-test3-pre3) New command line protocol.
> > - Lower the conventional memory ceiling. No overwrite
> > - of the traditional setup area, thus making booting
> > - safe for systems which use the EBDA from SMM or 32-bit
> > - BIOS entry points. zImage deprecated but still
> > - supported.
> > -
> > -Protocol 2.03: (Kernel 2.4.18-pre1) Explicitly makes the highest possible
> > - initrd address available to the bootloader.
> > -
> > -Protocol 2.04: (Kernel 2.6.14) Extend the syssize field to four bytes.
> > -
> > -Protocol 2.05: (Kernel 2.6.20) Make protected mode kernel relocatable.
> > - Introduce relocatable_kernel and kernel_alignment fields.
> > -
> > -Protocol 2.06: (Kernel 2.6.22) Added a field that contains the size of
> > - the boot command line.
> > -
> > -Protocol 2.07: (Kernel 2.6.24) Added paravirtualised boot protocol.
> > - Introduced hardware_subarch and hardware_subarch_data
> > - and KEEP_SEGMENTS flag in load_flags.
> > -
> > -Protocol 2.08: (Kernel 2.6.26) Added crc32 checksum and ELF format
> > - payload. Introduced payload_offset and payload_length
> > - fields to aid in locating the payload.
> > -
> > -Protocol 2.09: (Kernel 2.6.26) Added a field of 64-bit physical
> > - pointer to single linked list of struct setup_data.
> > -
> > -Protocol 2.10: (Kernel 2.6.31) Added a protocol for relaxed alignment
> > - beyond the kernel_alignment added, new init_size and
> > - pref_address fields. Added extended boot loader IDs.
> > -
> > -Protocol 2.11: (Kernel 3.6) Added a field for offset of EFI handover
> > - protocol entry point.
> > -
> > -Protocol 2.12: (Kernel 3.8) Added the xloadflags field and extension fields
> > - to struct boot_params for loading bzImage and ramdisk
> > - above 4G in 64bit.
> > -
> > -**** MEMORY LAYOUT
> > -
> > -The traditional memory map for the kernel loader, used for Image or
> > -zImage kernels, typically looks like:
> > -
> > - | |
> > -0A0000 +------------------------+
> > - | Reserved for BIOS | Do not use. Reserved for BIOS EBDA.
> > -09A000 +------------------------+
> > - | Command line |
> > - | Stack/heap | For use by the kernel real-mode code.
> > -098000 +------------------------+
> > - | Kernel setup | The kernel real-mode code.
> > -090200 +------------------------+
> > - | Kernel boot sector | The kernel legacy boot sector.
> > -090000 +------------------------+
> > - | Protected-mode kernel | The bulk of the kernel image.
> > -010000 +------------------------+
> > - | Boot loader | <- Boot sector entry point 0000:7C00
> > -001000 +------------------------+
> > - | Reserved for MBR/BIOS |
> > -000800 +------------------------+
> > - | Typically used by MBR |
> > -000600 +------------------------+
> > - | BIOS use only |
> > -000000 +------------------------+
> > -
> > -
> > -When using bzImage, the protected-mode kernel was relocated to
> > -0x100000 ("high memory"), and the kernel real-mode block (boot sector,
> > -setup, and stack/heap) was made relocatable to any address between
> > -0x10000 and end of low memory. Unfortunately, in protocols 2.00 and
> > -2.01 the 0x90000+ memory range is still used internally by the kernel;
> > -the 2.02 protocol resolves that problem.
> > -
> > -It is desirable to keep the "memory ceiling" -- the highest point in
> > -low memory touched by the boot loader -- as low as possible, since
> > -some newer BIOSes have begun to allocate some rather large amounts of
> > -memory, called the Extended BIOS Data Area, near the top of low
> > -memory. The boot loader should use the "INT 12h" BIOS call to verify
> > -how much low memory is available.
> > -
> > -Unfortunately, if INT 12h reports that the amount of memory is too
> > -low, there is usually nothing the boot loader can do but to report an
> > -error to the user. The boot loader should therefore be designed to
> > -take up as little space in low memory as it reasonably can. For
> > -zImage or old bzImage kernels, which need data written into the
> > -0x90000 segment, the boot loader should make sure not to use memory
> > -above the 0x9A000 point; too many BIOSes will break above that point.
> > -
> > -For a modern bzImage kernel with boot protocol version >= 2.02, a
> > -memory layout like the following is suggested:
> > -
> > - ~ ~
> > - | Protected-mode kernel |
> > -100000 +------------------------+
> > - | I/O memory hole |
> > -0A0000 +------------------------+
> > - | Reserved for BIOS | Leave as much as possible unused
> > - ~ ~
> > - | Command line | (Can also be below the X+10000 mark)
> > -X+10000 +------------------------+
> > - | Stack/heap | For use by the kernel real-mode code.
> > -X+08000 +------------------------+
> > - | Kernel setup | The kernel real-mode code.
> > - | Kernel boot sector | The kernel legacy boot sector.
> > -X +------------------------+
> > - | Boot loader | <- Boot sector entry point 0000:7C00
> > -001000 +------------------------+
> > - | Reserved for MBR/BIOS |
> > -000800 +------------------------+
> > - | Typically used by MBR |
> > -000600 +------------------------+
> > - | BIOS use only |
> > -000000 +------------------------+
> > -
> > -... where the address X is as low as the design of the boot loader
> > -permits.
> > -
> > -
> > -**** THE REAL-MODE KERNEL HEADER
> > -
> > -In the following text, and anywhere in the kernel boot sequence, "a
> > -sector" refers to 512 bytes. It is independent of the actual sector
> > -size of the underlying medium.
> > -
> > -The first step in loading a Linux kernel should be to load the
> > -real-mode code (boot sector and setup code) and then examine the
> > -following header at offset 0x01f1. The real-mode code can total up to
> > -32K, although the boot loader may choose to load only the first two
> > -sectors (1K) and then examine the bootup sector size.
> > -
> > -The header looks like:
> > -
> > -Offset Proto Name Meaning
> > -/Size
> > -
> > -01F1/1 ALL(1 setup_sects The size of the setup in sectors
> > -01F2/2 ALL root_flags If set, the root is mounted readonly
> > -01F4/4 2.04+(2 syssize The size of the 32-bit code in 16-byte paras
> > -01F8/2 ALL ram_size DO NOT USE - for bootsect.S use only
> > -01FA/2 ALL vid_mode Video mode control
> > -01FC/2 ALL root_dev Default root device number
> > -01FE/2 ALL boot_flag 0xAA55 magic number
> > -0200/2 2.00+ jump Jump instruction
> > -0202/4 2.00+ header Magic signature "HdrS"
> > -0206/2 2.00+ version Boot protocol version supported
> > -0208/4 2.00+ realmode_swtch Boot loader hook (see below)
> > -020C/2 2.00+ start_sys_seg The load-low segment (0x1000) (obsolete)
> > -020E/2 2.00+ kernel_version Pointer to kernel version string
> > -0210/1 2.00+ type_of_loader Boot loader identifier
> > -0211/1 2.00+ loadflags Boot protocol option flags
> > -0212/2 2.00+ setup_move_size Move to high memory size (used with hooks)
> > -0214/4 2.00+ code32_start Boot loader hook (see below)
> > -0218/4 2.00+ ramdisk_image initrd load address (set by boot loader)
> > -021C/4 2.00+ ramdisk_size initrd size (set by boot loader)
> > -0220/4 2.00+ bootsect_kludge DO NOT USE - for bootsect.S use only
> > -0224/2 2.01+ heap_end_ptr Free memory after setup end
> > -0226/1 2.02+(3 ext_loader_ver Extended boot loader version
> > -0227/1 2.02+(3 ext_loader_type Extended boot loader ID
> > -0228/4 2.02+ cmd_line_ptr 32-bit pointer to the kernel command line
> > -022C/4 2.03+ initrd_addr_max Highest legal initrd address
> > -0230/4 2.05+ kernel_alignment Physical addr alignment required for kernel
> > -0234/1 2.05+ relocatable_kernel Whether kernel is relocatable or not
> > -0235/1 2.10+ min_alignment Minimum alignment, as a power of two
> > -0236/2 2.12+ xloadflags Boot protocol option flags
> > -0238/4 2.06+ cmdline_size Maximum size of the kernel command line
> > -023C/4 2.07+ hardware_subarch Hardware subarchitecture
> > -0240/8 2.07+ hardware_subarch_data Subarchitecture-specific data
> > -0248/4 2.08+ payload_offset Offset of kernel payload
> > -024C/4 2.08+ payload_length Length of kernel payload
> > -0250/8 2.09+ setup_data 64-bit physical pointer to linked list
> > - of struct setup_data
> > -0258/8 2.10+ pref_address Preferred loading address
> > -0260/4 2.10+ init_size Linear memory required during initialization
> > -0264/4 2.11+ handover_offset Offset of handover entry point
> > -
> > -(1) For backwards compatibility, if the setup_sects field contains 0, the
> > - real value is 4.
> > -
> > -(2) For boot protocol prior to 2.04, the upper two bytes of the syssize
> > - field are unusable, which means the size of a bzImage kernel
> > - cannot be determined.
> > -
> > -(3) Ignored, but safe to set, for boot protocols 2.02-2.09.
> > -
> > -If the "HdrS" (0x53726448) magic number is not found at offset 0x202,
> > -the boot protocol version is "old". Loading an old kernel, the
> > -following parameters should be assumed:
> > -
> > - Image type = zImage
> > - initrd not supported
> > - Real-mode kernel must be located at 0x90000.
> > -
> > -Otherwise, the "version" field contains the protocol version,
> > -e.g. protocol version 2.01 will contain 0x0201 in this field. When
> > -setting fields in the header, you must make sure only to set fields
> > -supported by the protocol version in use.
> > -
> > -
> > -**** DETAILS OF HEADER FIELDS
> > -
> > -For each field, some are information from the kernel to the bootloader
> > -("read"), some are expected to be filled out by the bootloader
> > -("write"), and some are expected to be read and modified by the
> > -bootloader ("modify").
> > -
> > -All general purpose boot loaders should write the fields marked
> > -(obligatory). Boot loaders who want to load the kernel at a
> > -nonstandard address should fill in the fields marked (reloc); other
> > -boot loaders can ignore those fields.
> > -
> > -The byte order of all fields is littleendian (this is x86, after all.)
> > -
> > -Field name: setup_sects
> > -Type: read
> > -Offset/size: 0x1f1/1
> > -Protocol: ALL
> > -
> > - The size of the setup code in 512-byte sectors. If this field is
> > - 0, the real value is 4. The real-mode code consists of the boot
> > - sector (always one 512-byte sector) plus the setup code.
> > -
> > -Field name: root_flags
> > -Type: modify (optional)
> > -Offset/size: 0x1f2/2
> > -Protocol: ALL
> > -
> > - If this field is nonzero, the root defaults to readonly. The use of
> > - this field is deprecated; use the "ro" or "rw" options on the
> > - command line instead.
> > -
> > -Field name: syssize
> > -Type: read
> > -Offset/size: 0x1f4/4 (protocol 2.04+) 0x1f4/2 (protocol ALL)
> > -Protocol: 2.04+
> > -
> > - The size of the protected-mode code in units of 16-byte paragraphs.
> > - For protocol versions older than 2.04 this field is only two bytes
> > - wide, and therefore cannot be trusted for the size of a kernel if
> > - the LOAD_HIGH flag is set.
> > -
> > -Field name: ram_size
> > -Type: kernel internal
> > -Offset/size: 0x1f8/2
> > -Protocol: ALL
> > -
> > - This field is obsolete.
> > -
> > -Field name: vid_mode
> > -Type: modify (obligatory)
> > -Offset/size: 0x1fa/2
> > -
> > - Please see the section on SPECIAL COMMAND LINE OPTIONS.
> > -
> > -Field name: root_dev
> > -Type: modify (optional)
> > -Offset/size: 0x1fc/2
> > -Protocol: ALL
> > -
> > - The default root device device number. The use of this field is
> > - deprecated, use the "root=" option on the command line instead.
> > -
> > -Field name: boot_flag
> > -Type: read
> > -Offset/size: 0x1fe/2
> > -Protocol: ALL
> > -
> > - Contains 0xAA55. This is the closest thing old Linux kernels have
> > - to a magic number.
> > -
> > -Field name: jump
> > -Type: read
> > -Offset/size: 0x200/2
> > -Protocol: 2.00+
> > -
> > - Contains an x86 jump instruction, 0xEB followed by a signed offset
> > - relative to byte 0x202. This can be used to determine the size of
> > - the header.
> > -
> > -Field name: header
> > -Type: read
> > -Offset/size: 0x202/4
> > -Protocol: 2.00+
> > -
> > - Contains the magic number "HdrS" (0x53726448).
> > -
> > -Field name: version
> > -Type: read
> > -Offset/size: 0x206/2
> > -Protocol: 2.00+
> > -
> > - Contains the boot protocol version, in (major << 8)+minor format,
> > - e.g. 0x0204 for version 2.04, and 0x0a11 for a hypothetical version
> > - 10.17.
> > -
> > -Field name: realmode_swtch
> > -Type: modify (optional)
> > -Offset/size: 0x208/4
> > -Protocol: 2.00+
> > -
> > - Boot loader hook (see ADVANCED BOOT LOADER HOOKS below.)
> > -
> > -Field name: start_sys_seg
> > -Type: read
> > -Offset/size: 0x20c/2
> > -Protocol: 2.00+
> > -
> > - The load low segment (0x1000). Obsolete.
> > -
> > -Field name: kernel_version
> > -Type: read
> > -Offset/size: 0x20e/2
> > -Protocol: 2.00+
> > -
> > - If set to a nonzero value, contains a pointer to a NUL-terminated
> > - human-readable kernel version number string, less 0x200. This can
> > - be used to display the kernel version to the user. This value
> > - should be less than (0x200*setup_sects).
> > -
> > - For example, if this value is set to 0x1c00, the kernel version
> > - number string can be found at offset 0x1e00 in the kernel file.
> > - This is a valid value if and only if the "setup_sects" field
> > - contains the value 15 or higher, as:
> > -
> > - 0x1c00 < 15*0x200 (= 0x1e00) but
> > - 0x1c00 >= 14*0x200 (= 0x1c00)
> > -
> > - 0x1c00 >> 9 = 14, so the minimum value for setup_secs is 15.
> > -
> > -Field name: type_of_loader
> > -Type: write (obligatory)
> > -Offset/size: 0x210/1
> > -Protocol: 2.00+
> > -
> > - If your boot loader has an assigned id (see table below), enter
> > - 0xTV here, where T is an identifier for the boot loader and V is
> > - a version number. Otherwise, enter 0xFF here.
> > -
> > - For boot loader IDs above T = 0xD, write T = 0xE to this field and
> > - write the extended ID minus 0x10 to the ext_loader_type field.
> > - Similarly, the ext_loader_ver field can be used to provide more than
> > - four bits for the bootloader version.
> > -
> > - For example, for T = 0x15, V = 0x234, write:
> > -
> > - type_of_loader <- 0xE4
> > - ext_loader_type <- 0x05
> > - ext_loader_ver <- 0x23
> > -
> > - Assigned boot loader ids (hexadecimal):
> > -
> > - 0 LILO (0x00 reserved for pre-2.00 bootloader)
> > - 1 Loadlin
> > - 2 bootsect-loader (0x20, all other values reserved)
> > - 3 Syslinux
> > - 4 Etherboot/gPXE/iPXE
> > - 5 ELILO
> > - 7 GRUB
> > - 8 U-Boot
> > - 9 Xen
> > - A Gujin
> > - B Qemu
> > - C Arcturus Networks uCbootloader
> > - D kexec-tools
> > - E Extended (see ext_loader_type)
> > - F Special (0xFF = undefined)
> > - 10 Reserved
> > - 11 Minimal Linux Bootloader <http://sebastian-plotz.blogspot.de>
> > - 12 OVMF UEFI virtualization stack
> > -
> > - Please contact <hpa@zytor.com> if you need a bootloader ID
> > - value assigned.
> > -
> > -Field name: loadflags
> > -Type: modify (obligatory)
> > -Offset/size: 0x211/1
> > -Protocol: 2.00+
> > -
> > - This field is a bitmask.
> > -
> > - Bit 0 (read): LOADED_HIGH
> > - - If 0, the protected-mode code is loaded at 0x10000.
> > - - If 1, the protected-mode code is loaded at 0x100000.
> > -
> > - Bit 1 (kernel internal): KASLR_FLAG
> > - - Used internally by the compressed kernel to communicate
> > - KASLR status to kernel proper.
> > - If 1, KASLR enabled.
> > - If 0, KASLR disabled.
> > -
> > - Bit 5 (write): QUIET_FLAG
> > - - If 0, print early messages.
> > - - If 1, suppress early messages.
> > - This requests to the kernel (decompressor and early
> > - kernel) to not write early messages that require
> > - accessing the display hardware directly.
> > -
> > - Bit 6 (write): KEEP_SEGMENTS
> > - Protocol: 2.07+
> > - - If 0, reload the segment registers in the 32bit entry point.
> > - - If 1, do not reload the segment registers in the 32bit entry point.
> > - Assume that %cs %ds %ss %es are all set to flat segments with
> > - a base of 0 (or the equivalent for their environment).
> > -
> > - Bit 7 (write): CAN_USE_HEAP
> > - Set this bit to 1 to indicate that the value entered in the
> > - heap_end_ptr is valid. If this field is clear, some setup code
> > - functionality will be disabled.
> > -
> > -Field name: setup_move_size
> > -Type: modify (obligatory)
> > -Offset/size: 0x212/2
> > -Protocol: 2.00-2.01
> > -
> > - When using protocol 2.00 or 2.01, if the real mode kernel is not
> > - loaded at 0x90000, it gets moved there later in the loading
> > - sequence. Fill in this field if you want additional data (such as
> > - the kernel command line) moved in addition to the real-mode kernel
> > - itself.
> > -
> > - The unit is bytes starting with the beginning of the boot sector.
> > -
> > - This field is can be ignored when the protocol is 2.02 or higher, or
> > - if the real-mode code is loaded at 0x90000.
> > -
> > -Field name: code32_start
> > -Type: modify (optional, reloc)
> > -Offset/size: 0x214/4
> > -Protocol: 2.00+
> > -
> > - The address to jump to in protected mode. This defaults to the load
> > - address of the kernel, and can be used by the boot loader to
> > - determine the proper load address.
> > -
> > - This field can be modified for two purposes:
> > -
> > - 1. as a boot loader hook (see ADVANCED BOOT LOADER HOOKS below.)
> > -
> > - 2. if a bootloader which does not install a hook loads a
> > - relocatable kernel at a nonstandard address it will have to modify
> > - this field to point to the load address.
> > -
> > -Field name: ramdisk_image
> > -Type: write (obligatory)
> > -Offset/size: 0x218/4
> > -Protocol: 2.00+
> > -
> > - The 32-bit linear address of the initial ramdisk or ramfs. Leave at
> > - zero if there is no initial ramdisk/ramfs.
> > -
> > -Field name: ramdisk_size
> > -Type: write (obligatory)
> > -Offset/size: 0x21c/4
> > -Protocol: 2.00+
> > -
> > - Size of the initial ramdisk or ramfs. Leave at zero if there is no
> > - initial ramdisk/ramfs.
> > -
> > -Field name: bootsect_kludge
> > -Type: kernel internal
> > -Offset/size: 0x220/4
> > -Protocol: 2.00+
> > -
> > - This field is obsolete.
> > -
> > -Field name: heap_end_ptr
> > -Type: write (obligatory)
> > -Offset/size: 0x224/2
> > -Protocol: 2.01+
> > -
> > - Set this field to the offset (from the beginning of the real-mode
> > - code) of the end of the setup stack/heap, minus 0x0200.
> > -
> > -Field name: ext_loader_ver
> > -Type: write (optional)
> > -Offset/size: 0x226/1
> > -Protocol: 2.02+
> > -
> > - This field is used as an extension of the version number in the
> > - type_of_loader field. The total version number is considered to be
> > - (type_of_loader & 0x0f) + (ext_loader_ver << 4).
> > -
> > - The use of this field is boot loader specific. If not written, it
> > - is zero.
> > -
> > - Kernels prior to 2.6.31 did not recognize this field, but it is safe
> > - to write for protocol version 2.02 or higher.
> > -
> > -Field name: ext_loader_type
> > -Type: write (obligatory if (type_of_loader & 0xf0) == 0xe0)
> > -Offset/size: 0x227/1
> > -Protocol: 2.02+
> > -
> > - This field is used as an extension of the type number in
> > - type_of_loader field. If the type in type_of_loader is 0xE, then
> > - the actual type is (ext_loader_type + 0x10).
> > -
> > - This field is ignored if the type in type_of_loader is not 0xE.
> > -
> > - Kernels prior to 2.6.31 did not recognize this field, but it is safe
> > - to write for protocol version 2.02 or higher.
> > -
> > -Field name: cmd_line_ptr
> > -Type: write (obligatory)
> > -Offset/size: 0x228/4
> > -Protocol: 2.02+
> > -
> > - Set this field to the linear address of the kernel command line.
> > - The kernel command line can be located anywhere between the end of
> > - the setup heap and 0xA0000; it does not have to be located in the
> > - same 64K segment as the real-mode code itself.
> > -
> > - Fill in this field even if your boot loader does not support a
> > - command line, in which case you can point this to an empty string
> > - (or better yet, to the string "auto".) If this field is left at
> > - zero, the kernel will assume that your boot loader does not support
> > - the 2.02+ protocol.
> > -
> > -Field name: initrd_addr_max
> > -Type: read
> > -Offset/size: 0x22c/4
> > -Protocol: 2.03+
> > -
> > - The maximum address that may be occupied by the initial
> > - ramdisk/ramfs contents. For boot protocols 2.02 or earlier, this
> > - field is not present, and the maximum address is 0x37FFFFFF. (This
> > - address is defined as the address of the highest safe byte, so if
> > - your ramdisk is exactly 131072 bytes long and this field is
> > - 0x37FFFFFF, you can start your ramdisk at 0x37FE0000.)
> > -
> > -Field name: kernel_alignment
> > -Type: read/modify (reloc)
> > -Offset/size: 0x230/4
> > -Protocol: 2.05+ (read), 2.10+ (modify)
> > -
> > - Alignment unit required by the kernel (if relocatable_kernel is
> > - true.) A relocatable kernel that is loaded at an alignment
> > - incompatible with the value in this field will be realigned during
> > - kernel initialization.
> > -
> > - Starting with protocol version 2.10, this reflects the kernel
> > - alignment preferred for optimal performance; it is possible for the
> > - loader to modify this field to permit a lesser alignment. See the
> > - min_alignment and pref_address field below.
> > -
> > -Field name: relocatable_kernel
> > -Type: read (reloc)
> > -Offset/size: 0x234/1
> > -Protocol: 2.05+
> > -
> > - If this field is nonzero, the protected-mode part of the kernel can
> > - be loaded at any address that satisfies the kernel_alignment field.
> > - After loading, the boot loader must set the code32_start field to
> > - point to the loaded code, or to a boot loader hook.
> > -
> > -Field name: min_alignment
> > -Type: read (reloc)
> > -Offset/size: 0x235/1
> > -Protocol: 2.10+
> > -
> > - This field, if nonzero, indicates as a power of two the minimum
> > - alignment required, as opposed to preferred, by the kernel to boot.
> > - If a boot loader makes use of this field, it should update the
> > - kernel_alignment field with the alignment unit desired; typically:
> > -
> > - kernel_alignment = 1 << min_alignment
> > -
> > - There may be a considerable performance cost with an excessively
> > - misaligned kernel. Therefore, a loader should typically try each
> > - power-of-two alignment from kernel_alignment down to this alignment.
> > -
> > -Field name: xloadflags
> > -Type: read
> > -Offset/size: 0x236/2
> > -Protocol: 2.12+
> > -
> > - This field is a bitmask.
> > -
> > - Bit 0 (read): XLF_KERNEL_64
> > - - If 1, this kernel has the legacy 64-bit entry point at 0x200.
> > -
> > - Bit 1 (read): XLF_CAN_BE_LOADED_ABOVE_4G
> > - - If 1, kernel/boot_params/cmdline/ramdisk can be above 4G.
> > -
> > - Bit 2 (read): XLF_EFI_HANDOVER_32
> > - - If 1, the kernel supports the 32-bit EFI handoff entry point
> > - given at handover_offset.
> > -
> > - Bit 3 (read): XLF_EFI_HANDOVER_64
> > - - If 1, the kernel supports the 64-bit EFI handoff entry point
> > - given at handover_offset + 0x200.
> > -
> > - Bit 4 (read): XLF_EFI_KEXEC
> > - - If 1, the kernel supports kexec EFI boot with EFI runtime support.
> > -
> > -Field name: cmdline_size
> > -Type: read
> > -Offset/size: 0x238/4
> > -Protocol: 2.06+
> > -
> > - The maximum size of the command line without the terminating
> > - zero. This means that the command line can contain at most
> > - cmdline_size characters. With protocol version 2.05 and earlier, the
> > - maximum size was 255.
> > -
> > -Field name: hardware_subarch
> > -Type: write (optional, defaults to x86/PC)
> > -Offset/size: 0x23c/4
> > -Protocol: 2.07+
> > -
> > - In a paravirtualized environment the hardware low level architectural
> > - pieces such as interrupt handling, page table handling, and
> > - accessing process control registers needs to be done differently.
> > -
> > - This field allows the bootloader to inform the kernel we are in one
> > - one of those environments.
> > -
> > - 0x00000000 The default x86/PC environment
> > - 0x00000001 lguest
> > - 0x00000002 Xen
> > - 0x00000003 Moorestown MID
> > - 0x00000004 CE4100 TV Platform
> > -
> > -Field name: hardware_subarch_data
> > -Type: write (subarch-dependent)
> > -Offset/size: 0x240/8
> > -Protocol: 2.07+
> > -
> > - A pointer to data that is specific to hardware subarch
> > - This field is currently unused for the default x86/PC environment,
> > - do not modify.
> > -
> > -Field name: payload_offset
> > -Type: read
> > -Offset/size: 0x248/4
> > -Protocol: 2.08+
> > -
> > - If non-zero then this field contains the offset from the beginning
> > - of the protected-mode code to the payload.
> > -
> > - The payload may be compressed. The format of both the compressed and
> > - uncompressed data should be determined using the standard magic
> > - numbers. The currently supported compression formats are gzip
> > - (magic numbers 1F 8B or 1F 9E), bzip2 (magic number 42 5A), LZMA
> > - (magic number 5D 00), XZ (magic number FD 37), and LZ4 (magic number
> > - 02 21). The uncompressed payload is currently always ELF (magic
> > - number 7F 45 4C 46).
> > -
> > -Field name: payload_length
> > -Type: read
> > -Offset/size: 0x24c/4
> > -Protocol: 2.08+
> > -
> > - The length of the payload.
> > -
> > -Field name: setup_data
> > -Type: write (special)
> > -Offset/size: 0x250/8
> > -Protocol: 2.09+
> > -
> > - The 64-bit physical pointer to NULL terminated single linked list of
> > - struct setup_data. This is used to define a more extensible boot
> > - parameters passing mechanism. The definition of struct setup_data is
> > - as follow:
> > -
> > - struct setup_data {
> > - u64 next;
> > - u32 type;
> > - u32 len;
> > - u8 data[0];
> > - };
> > -
> > - Where, the next is a 64-bit physical pointer to the next node of
> > - linked list, the next field of the last node is 0; the type is used
> > - to identify the contents of data; the len is the length of data
> > - field; the data holds the real payload.
> > -
> > - This list may be modified at a number of points during the bootup
> > - process. Therefore, when modifying this list one should always make
> > - sure to consider the case where the linked list already contains
> > - entries.
> > -
> > -Field name: pref_address
> > -Type: read (reloc)
> > -Offset/size: 0x258/8
> > -Protocol: 2.10+
> > -
> > - This field, if nonzero, represents a preferred load address for the
> > - kernel. A relocating bootloader should attempt to load at this
> > - address if possible.
> > -
> > - A non-relocatable kernel will unconditionally move itself and to run
> > - at this address.
> > -
> > -Field name: init_size
> > -Type: read
> > -Offset/size: 0x260/4
> > -
> > - This field indicates the amount of linear contiguous memory starting
> > - at the kernel runtime start address that the kernel needs before it
> > - is capable of examining its memory map. This is not the same thing
> > - as the total amount of memory the kernel needs to boot, but it can
> > - be used by a relocating boot loader to help select a safe load
> > - address for the kernel.
> > -
> > - The kernel runtime start address is determined by the following algorithm:
> > -
> > - if (relocatable_kernel)
> > - runtime_start = align_up(load_address, kernel_alignment)
> > - else
> > - runtime_start = pref_address
> > -
> > -Field name: handover_offset
> > -Type: read
> > -Offset/size: 0x264/4
> > -
> > - This field is the offset from the beginning of the kernel image to
> > - the EFI handover protocol entry point. Boot loaders using the EFI
> > - handover protocol to boot the kernel should jump to this offset.
> > -
> > - See EFI HANDOVER PROTOCOL below for more details.
> > -
> > -
> > -**** THE IMAGE CHECKSUM
> > -
> > -From boot protocol version 2.08 onwards the CRC-32 is calculated over
> > -the entire file using the characteristic polynomial 0x04C11DB7 and an
> > -initial remainder of 0xffffffff. The checksum is appended to the
> > -file; therefore the CRC of the file up to the limit specified in the
> > -syssize field of the header is always 0.
> > -
> > -
> > -**** THE KERNEL COMMAND LINE
> > -
> > -The kernel command line has become an important way for the boot
> > -loader to communicate with the kernel. Some of its options are also
> > -relevant to the boot loader itself, see "special command line options"
> > -below.
> > -
> > -The kernel command line is a null-terminated string. The maximum
> > -length can be retrieved from the field cmdline_size. Before protocol
> > -version 2.06, the maximum was 255 characters. A string that is too
> > -long will be automatically truncated by the kernel.
> > -
> > -If the boot protocol version is 2.02 or later, the address of the
> > -kernel command line is given by the header field cmd_line_ptr (see
> > -above.) This address can be anywhere between the end of the setup
> > -heap and 0xA0000.
> > -
> > -If the protocol version is *not* 2.02 or higher, the kernel
> > -command line is entered using the following protocol:
> > -
> > - At offset 0x0020 (word), "cmd_line_magic", enter the magic
> > - number 0xA33F.
> > -
> > - At offset 0x0022 (word), "cmd_line_offset", enter the offset
> > - of the kernel command line (relative to the start of the
> > - real-mode kernel).
> > -
> > - The kernel command line *must* be within the memory region
> > - covered by setup_move_size, so you may need to adjust this
> > - field.
> > -
> > -
> > -**** MEMORY LAYOUT OF THE REAL-MODE CODE
> > -
> > -The real-mode code requires a stack/heap to be set up, as well as
> > -memory allocated for the kernel command line. This needs to be done
> > -in the real-mode accessible memory in bottom megabyte.
> > -
> > -It should be noted that modern machines often have a sizable Extended
> > -BIOS Data Area (EBDA). As a result, it is advisable to use as little
> > -of the low megabyte as possible.
> > -
> > -Unfortunately, under the following circumstances the 0x90000 memory
> > -segment has to be used:
> > -
> > - - When loading a zImage kernel ((loadflags & 0x01) == 0).
> > - - When loading a 2.01 or earlier boot protocol kernel.
> > -
> > - -> For the 2.00 and 2.01 boot protocols, the real-mode code
> > - can be loaded at another address, but it is internally
> > - relocated to 0x90000. For the "old" protocol, the
> > - real-mode code must be loaded at 0x90000.
> > -
> > -When loading at 0x90000, avoid using memory above 0x9a000.
> > -
> > -For boot protocol 2.02 or higher, the command line does not have to be
> > -located in the same 64K segment as the real-mode setup code; it is
> > -thus permitted to give the stack/heap the full 64K segment and locate
> > -the command line above it.
> > -
> > -The kernel command line should not be located below the real-mode
> > -code, nor should it be located in high memory.
> > -
> > -
> > -**** SAMPLE BOOT CONFIGURATION
> > -
> > -As a sample configuration, assume the following layout of the real
> > -mode segment:
> > -
> > - When loading below 0x90000, use the entire segment:
> > -
> > - 0x0000-0x7fff Real mode kernel
> > - 0x8000-0xdfff Stack and heap
> > - 0xe000-0xffff Kernel command line
> > -
> > - When loading at 0x90000 OR the protocol version is 2.01 or earlier:
> > -
> > - 0x0000-0x7fff Real mode kernel
> > - 0x8000-0x97ff Stack and heap
> > - 0x9800-0x9fff Kernel command line
> > -
> > -Such a boot loader should enter the following fields in the header:
> > -
> > - unsigned long base_ptr; /* base address for real-mode segment */
> > -
> > - if ( setup_sects == 0 ) {
> > - setup_sects = 4;
> > - }
> > -
> > - if ( protocol >= 0x0200 ) {
> > - type_of_loader = <type code>;
> > - if ( loading_initrd ) {
> > - ramdisk_image = <initrd_address>;
> > - ramdisk_size = <initrd_size>;
> > - }
> > -
> > - if ( protocol >= 0x0202 && loadflags & 0x01 )
> > - heap_end = 0xe000;
> > - else
> > - heap_end = 0x9800;
> > -
> > - if ( protocol >= 0x0201 ) {
> > - heap_end_ptr = heap_end - 0x200;
> > - loadflags |= 0x80; /* CAN_USE_HEAP */
> > - }
> > -
> > - if ( protocol >= 0x0202 ) {
> > - cmd_line_ptr = base_ptr + heap_end;
> > - strcpy(cmd_line_ptr, cmdline);
> > - } else {
> > - cmd_line_magic = 0xA33F;
> > - cmd_line_offset = heap_end;
> > - setup_move_size = heap_end + strlen(cmdline)+1;
> > - strcpy(base_ptr+cmd_line_offset, cmdline);
> > - }
> > - } else {
> > - /* Very old kernel */
> > -
> > - heap_end = 0x9800;
> > -
> > - cmd_line_magic = 0xA33F;
> > - cmd_line_offset = heap_end;
> > -
> > - /* A very old kernel MUST have its real-mode code
> > - loaded at 0x90000 */
> > -
> > - if ( base_ptr != 0x90000 ) {
> > - /* Copy the real-mode kernel */
> > - memcpy(0x90000, base_ptr, (setup_sects+1)*512);
> > - base_ptr = 0x90000; /* Relocated */
> > - }
> > -
> > - strcpy(0x90000+cmd_line_offset, cmdline);
> > -
> > - /* It is recommended to clear memory up to the 32K mark */
> > - memset(0x90000 + (setup_sects+1)*512, 0,
> > - (64-(setup_sects+1))*512);
> > - }
> > -
> > -
> > -**** LOADING THE REST OF THE KERNEL
> > -
> > -The 32-bit (non-real-mode) kernel starts at offset (setup_sects+1)*512
> > -in the kernel file (again, if setup_sects == 0 the real value is 4.)
> > -It should be loaded at address 0x10000 for Image/zImage kernels and
> > -0x100000 for bzImage kernels.
> > -
> > -The kernel is a bzImage kernel if the protocol >= 2.00 and the 0x01
> > -bit (LOAD_HIGH) in the loadflags field is set:
> > -
> > - is_bzImage = (protocol >= 0x0200) && (loadflags & 0x01);
> > - load_address = is_bzImage ? 0x100000 : 0x10000;
> > -
> > -Note that Image/zImage kernels can be up to 512K in size, and thus use
> > -the entire 0x10000-0x90000 range of memory. This means it is pretty
> > -much a requirement for these kernels to load the real-mode part at
> > -0x90000. bzImage kernels allow much more flexibility.
> > -
> > -
> > -**** SPECIAL COMMAND LINE OPTIONS
> > -
> > -If the command line provided by the boot loader is entered by the
> > -user, the user may expect the following command line options to work.
> > -They should normally not be deleted from the kernel command line even
> > -though not all of them are actually meaningful to the kernel. Boot
> > -loader authors who need additional command line options for the boot
> > -loader itself should get them registered in
> > -Documentation/admin-guide/kernel-parameters.rst to make sure they will not
> > -conflict with actual kernel options now or in the future.
> > -
> > - vga=<mode>
> > - <mode> here is either an integer (in C notation, either
> > - decimal, octal, or hexadecimal) or one of the strings
> > - "normal" (meaning 0xFFFF), "ext" (meaning 0xFFFE) or "ask"
> > - (meaning 0xFFFD). This value should be entered into the
> > - vid_mode field, as it is used by the kernel before the command
> > - line is parsed.
> > -
> > - mem=<size>
> > - <size> is an integer in C notation optionally followed by
> > - (case insensitive) K, M, G, T, P or E (meaning << 10, << 20,
> > - << 30, << 40, << 50 or << 60). This specifies the end of
> > - memory to the kernel. This affects the possible placement of
> > - an initrd, since an initrd should be placed near end of
> > - memory. Note that this is an option to *both* the kernel and
> > - the bootloader!
> > -
> > - initrd=<file>
> > - An initrd should be loaded. The meaning of <file> is
> > - obviously bootloader-dependent, and some boot loaders
> > - (e.g. LILO) do not have such a command.
> > -
> > -In addition, some boot loaders add the following options to the
> > -user-specified command line:
> > -
> > - BOOT_IMAGE=<file>
> > - The boot image which was loaded. Again, the meaning of <file>
> > - is obviously bootloader-dependent.
> > -
> > - auto
> > - The kernel was booted without explicit user intervention.
> > -
> > -If these options are added by the boot loader, it is highly
> > -recommended that they are located *first*, before the user-specified
> > -or configuration-specified command line. Otherwise, "init=/bin/sh"
> > -gets confused by the "auto" option.
> > -
> > -
> > -**** RUNNING THE KERNEL
> > -
> > -The kernel is started by jumping to the kernel entry point, which is
> > -located at *segment* offset 0x20 from the start of the real mode
> > -kernel. This means that if you loaded your real-mode kernel code at
> > -0x90000, the kernel entry point is 9020:0000.
> > -
> > -At entry, ds = es = ss should point to the start of the real-mode
> > -kernel code (0x9000 if the code is loaded at 0x90000), sp should be
> > -set up properly, normally pointing to the top of the heap, and
> > -interrupts should be disabled. Furthermore, to guard against bugs in
> > -the kernel, it is recommended that the boot loader sets fs = gs = ds =
> > -es = ss.
> > -
> > -In our example from above, we would do:
> > -
> > - /* Note: in the case of the "old" kernel protocol, base_ptr must
> > - be == 0x90000 at this point; see the previous sample code */
> > -
> > - seg = base_ptr >> 4;
> > -
> > - cli(); /* Enter with interrupts disabled! */
> > -
> > - /* Set up the real-mode kernel stack */
> > - _SS = seg;
> > - _SP = heap_end;
> > -
> > - _DS = _ES = _FS = _GS = seg;
> > - jmp_far(seg+0x20, 0); /* Run the kernel */
> > -
> > -If your boot sector accesses a floppy drive, it is recommended to
> > -switch off the floppy motor before running the kernel, since the
> > -kernel boot leaves interrupts off and thus the motor will not be
> > -switched off, especially if the loaded kernel has the floppy driver as
> > -a demand-loaded module!
> > -
> > -
> > -**** ADVANCED BOOT LOADER HOOKS
> > -
> > -If the boot loader runs in a particularly hostile environment (such as
> > -LOADLIN, which runs under DOS) it may be impossible to follow the
> > -standard memory location requirements. Such a boot loader may use the
> > -following hooks that, if set, are invoked by the kernel at the
> > -appropriate time. The use of these hooks should probably be
> > -considered an absolutely last resort!
> > -
> > -IMPORTANT: All the hooks are required to preserve %esp, %ebp, %esi and
> > -%edi across invocation.
> > -
> > - realmode_swtch:
> > - A 16-bit real mode far subroutine invoked immediately before
> > - entering protected mode. The default routine disables NMI, so
> > - your routine should probably do so, too.
> > -
> > - code32_start:
> > - A 32-bit flat-mode routine *jumped* to immediately after the
> > - transition to protected mode, but before the kernel is
> > - uncompressed. No segments, except CS, are guaranteed to be
> > - set up (current kernels do, but older ones do not); you should
> > - set them up to BOOT_DS (0x18) yourself.
> > -
> > - After completing your hook, you should jump to the address
> > - that was in this field before your boot loader overwrote it
> > - (relocated, if appropriate.)
> > -
> > -
> > -**** 32-bit BOOT PROTOCOL
> > -
> > -For machine with some new BIOS other than legacy BIOS, such as EFI,
> > -LinuxBIOS, etc, and kexec, the 16-bit real mode setup code in kernel
> > -based on legacy BIOS can not be used, so a 32-bit boot protocol needs
> > -to be defined.
> > -
> > -In 32-bit boot protocol, the first step in loading a Linux kernel
> > -should be to setup the boot parameters (struct boot_params,
> > -traditionally known as "zero page"). The memory for struct boot_params
> > -should be allocated and initialized to all zero. Then the setup header
> > -from offset 0x01f1 of kernel image on should be loaded into struct
> > -boot_params and examined. The end of setup header can be calculated as
> > -follow:
> > -
> > - 0x0202 + byte value at offset 0x0201
> > -
> > -In addition to read/modify/write the setup header of the struct
> > -boot_params as that of 16-bit boot protocol, the boot loader should
> > -also fill the additional fields of the struct boot_params as that
> > -described in zero-page.txt.
> > -
> > -After setting up the struct boot_params, the boot loader can load the
> > -32/64-bit kernel in the same way as that of 16-bit boot protocol.
> > -
> > -In 32-bit boot protocol, the kernel is started by jumping to the
> > -32-bit kernel entry point, which is the start address of loaded
> > -32/64-bit kernel.
> > -
> > -At entry, the CPU must be in 32-bit protected mode with paging
> > -disabled; a GDT must be loaded with the descriptors for selectors
> > -__BOOT_CS(0x10) and __BOOT_DS(0x18); both descriptors must be 4G flat
> > -segment; __BOOT_CS must have execute/read permission, and __BOOT_DS
> > -must have read/write permission; CS must be __BOOT_CS and DS, ES, SS
> > -must be __BOOT_DS; interrupt must be disabled; %esi must hold the base
> > -address of the struct boot_params; %ebp, %edi and %ebx must be zero.
> > -
> > -**** 64-bit BOOT PROTOCOL
> > -
> > -For machine with 64bit cpus and 64bit kernel, we could use 64bit bootloader
> > -and we need a 64-bit boot protocol.
> > -
> > -In 64-bit boot protocol, the first step in loading a Linux kernel
> > -should be to setup the boot parameters (struct boot_params,
> > -traditionally known as "zero page"). The memory for struct boot_params
> > -could be allocated anywhere (even above 4G) and initialized to all zero.
> > -Then, the setup header at offset 0x01f1 of kernel image on should be
> > -loaded into struct boot_params and examined. The end of setup header
> > -can be calculated as follows:
> > -
> > - 0x0202 + byte value at offset 0x0201
> > -
> > -In addition to read/modify/write the setup header of the struct
> > -boot_params as that of 16-bit boot protocol, the boot loader should
> > -also fill the additional fields of the struct boot_params as described
> > -in zero-page.txt.
> > -
> > -After setting up the struct boot_params, the boot loader can load
> > -64-bit kernel in the same way as that of 16-bit boot protocol, but
> > -kernel could be loaded above 4G.
> > -
> > -In 64-bit boot protocol, the kernel is started by jumping to the
> > -64-bit kernel entry point, which is the start address of loaded
> > -64-bit kernel plus 0x200.
> > -
> > -At entry, the CPU must be in 64-bit mode with paging enabled.
> > -The range with setup_header.init_size from start address of loaded
> > -kernel and zero page and command line buffer get ident mapping;
> > -a GDT must be loaded with the descriptors for selectors
> > -__BOOT_CS(0x10) and __BOOT_DS(0x18); both descriptors must be 4G flat
> > -segment; __BOOT_CS must have execute/read permission, and __BOOT_DS
> > -must have read/write permission; CS must be __BOOT_CS and DS, ES, SS
> > -must be __BOOT_DS; interrupt must be disabled; %rsi must hold the base
> > -address of the struct boot_params.
> > -
> > -**** EFI HANDOVER PROTOCOL
> > -
> > -This protocol allows boot loaders to defer initialisation to the EFI
> > -boot stub. The boot loader is required to load the kernel/initrd(s)
> > -from the boot media and jump to the EFI handover protocol entry point
> > -which is hdr->handover_offset bytes from the beginning of
> > -startup_{32,64}.
> > -
> > -The function prototype for the handover entry point looks like this,
> > -
> > - efi_main(void *handle, efi_system_table_t *table, struct boot_params *bp)
> > -
> > -'handle' is the EFI image handle passed to the boot loader by the EFI
> > -firmware, 'table' is the EFI system table - these are the first two
> > -arguments of the "handoff state" as described in section 2.3 of the
> > -UEFI specification. 'bp' is the boot loader-allocated boot params.
> > -
> > -The boot loader *must* fill out the following fields in bp,
> > -
> > - o hdr.code32_start
> > - o hdr.cmd_line_ptr
> > - o hdr.ramdisk_image (if applicable)
> > - o hdr.ramdisk_size (if applicable)
> > -
> > -All other fields should be zero.
> > diff --git a/Documentation/x86/index.rst b/Documentation/x86/index.rst
> > index 7612d3142b2a..8f08caf4fbbb 100644
> > --- a/Documentation/x86/index.rst
> > +++ b/Documentation/x86/index.rst
> > @@ -7,3 +7,5 @@ Linux x86 Support
> > .. toctree::
> > :maxdepth: 2
> > :numbered:
> > +
> > + boot
>
>
>
> Thanks,
> Mauro
--
Cheers,
Changbin Du
^ permalink raw reply
* Applied "ASoC: fsl_sai: Update is_slave_mode with correct value" to the asoc tree
From: Mark Brown @ 2019-04-25 19:24 UTC (permalink / raw)
To: Daniel Baluta
Cc: alsa-devel, timur, Xiubo.Lee, linuxppc-dev, S.j. Wang, tiwai,
linux-kernel, lgirdwood, Nicolin Chen, Mark Brown, dl-linux-imx,
perex, festevam
In-Reply-To: <20190421193853.10188-2-daniel.baluta@nxp.com>
The patch
ASoC: fsl_sai: Update is_slave_mode with correct value
has been applied to the asoc tree at
https://git.kernel.org/pub/scm/linux/kernel/git/broonie/sound.git for-5.2
All being well this means that it will be integrated into the linux-next
tree (usually sometime in the next 24 hours) and sent to Linus during
the next merge window (or sooner if it is a bug fix), however if
problems are discovered then the patch may be dropped or reverted.
You may get further e-mails resulting from automated or manual testing
and review of the tree, please engage with people reporting problems and
send followup patches addressing any issues that are reported if needed.
If any updates are required or you are submitting further changes they
should be sent as incremental updates against current git, existing
patches will not be replaced.
Please add any relevant lists and maintainers to the CCs when replying
to this mail.
Thanks,
Mark
From ddb351145a967ee791a0fb0156852ec2fcb746ba Mon Sep 17 00:00:00 2001
From: Daniel Baluta <daniel.baluta@nxp.com>
Date: Sun, 21 Apr 2019 19:39:08 +0000
Subject: [PATCH] ASoC: fsl_sai: Update is_slave_mode with correct value
is_slave_mode defaults to false because sai structure
that contains it is kzalloc'ed.
Anyhow, if we decide to set the following configuration
SAI slave -> SAI master, is_slave_mode will remain set on true
although SAI being master it should be set to false.
Fix this by updating is_slave_mode for each call of
fsl_sai_set_dai_fmt.
Signed-off-by: Daniel Baluta <daniel.baluta@nxp.com>
Acked-by: Nicolin Chen <nicoleotsuka@gmail.com>
Signed-off-by: Mark Brown <broonie@kernel.org>
---
sound/soc/fsl/fsl_sai.c | 2 ++
1 file changed, 2 insertions(+)
diff --git a/sound/soc/fsl/fsl_sai.c b/sound/soc/fsl/fsl_sai.c
index db9e0872f73d..7549b74e464e 100644
--- a/sound/soc/fsl/fsl_sai.c
+++ b/sound/soc/fsl/fsl_sai.c
@@ -268,12 +268,14 @@ static int fsl_sai_set_dai_fmt_tr(struct snd_soc_dai *cpu_dai,
case SND_SOC_DAIFMT_CBS_CFS:
val_cr2 |= FSL_SAI_CR2_BCD_MSTR;
val_cr4 |= FSL_SAI_CR4_FSD_MSTR;
+ sai->is_slave_mode = false;
break;
case SND_SOC_DAIFMT_CBM_CFM:
sai->is_slave_mode = true;
break;
case SND_SOC_DAIFMT_CBS_CFM:
val_cr2 |= FSL_SAI_CR2_BCD_MSTR;
+ sai->is_slave_mode = false;
break;
case SND_SOC_DAIFMT_CBM_CFS:
val_cr4 |= FSL_SAI_CR4_FSD_MSTR;
--
2.20.1
^ permalink raw reply related
* Applied "ASoC: fsl_sai: Update is_slave_mode with correct value" to the asoc tree
From: Mark Brown @ 2019-04-25 19:26 UTC (permalink / raw)
To: Daniel Baluta
Cc: alsa-devel, timur, Xiubo.Lee, linuxppc-dev, S.j. Wang, tiwai,
linux-kernel, lgirdwood, Nicolin Chen, Mark Brown, dl-linux-imx,
perex, festevam
In-Reply-To: <20190421193853.10188-2-daniel.baluta@nxp.com>
The patch
ASoC: fsl_sai: Update is_slave_mode with correct value
has been applied to the asoc tree at
https://git.kernel.org/pub/scm/linux/kernel/git/broonie/sound.git for-5.2
All being well this means that it will be integrated into the linux-next
tree (usually sometime in the next 24 hours) and sent to Linus during
the next merge window (or sooner if it is a bug fix), however if
problems are discovered then the patch may be dropped or reverted.
You may get further e-mails resulting from automated or manual testing
and review of the tree, please engage with people reporting problems and
send followup patches addressing any issues that are reported if needed.
If any updates are required or you are submitting further changes they
should be sent as incremental updates against current git, existing
patches will not be replaced.
Please add any relevant lists and maintainers to the CCs when replying
to this mail.
Thanks,
Mark
From ddb351145a967ee791a0fb0156852ec2fcb746ba Mon Sep 17 00:00:00 2001
From: Daniel Baluta <daniel.baluta@nxp.com>
Date: Sun, 21 Apr 2019 19:39:08 +0000
Subject: [PATCH] ASoC: fsl_sai: Update is_slave_mode with correct value
is_slave_mode defaults to false because sai structure
that contains it is kzalloc'ed.
Anyhow, if we decide to set the following configuration
SAI slave -> SAI master, is_slave_mode will remain set on true
although SAI being master it should be set to false.
Fix this by updating is_slave_mode for each call of
fsl_sai_set_dai_fmt.
Signed-off-by: Daniel Baluta <daniel.baluta@nxp.com>
Acked-by: Nicolin Chen <nicoleotsuka@gmail.com>
Signed-off-by: Mark Brown <broonie@kernel.org>
---
sound/soc/fsl/fsl_sai.c | 2 ++
1 file changed, 2 insertions(+)
diff --git a/sound/soc/fsl/fsl_sai.c b/sound/soc/fsl/fsl_sai.c
index db9e0872f73d..7549b74e464e 100644
--- a/sound/soc/fsl/fsl_sai.c
+++ b/sound/soc/fsl/fsl_sai.c
@@ -268,12 +268,14 @@ static int fsl_sai_set_dai_fmt_tr(struct snd_soc_dai *cpu_dai,
case SND_SOC_DAIFMT_CBS_CFS:
val_cr2 |= FSL_SAI_CR2_BCD_MSTR;
val_cr4 |= FSL_SAI_CR4_FSD_MSTR;
+ sai->is_slave_mode = false;
break;
case SND_SOC_DAIFMT_CBM_CFM:
sai->is_slave_mode = true;
break;
case SND_SOC_DAIFMT_CBS_CFM:
val_cr2 |= FSL_SAI_CR2_BCD_MSTR;
+ sai->is_slave_mode = false;
break;
case SND_SOC_DAIFMT_CBM_CFS:
val_cr4 |= FSL_SAI_CR4_FSD_MSTR;
--
2.20.1
^ permalink raw reply related
* Re: [PATCH v10 00/18] Introduce the Counter subsystem
From: Greg KH @ 2019-04-25 19:36 UTC (permalink / raw)
To: Jonathan Cameron
Cc: mark.rutland, benjamin.gaignard, linux-pwm, linux-iio,
patrick.havelange, thierry.reding, pmeerw, linux-api, lars,
daniel.lezcano, linux-arm-kernel, devicetree, david,
William Breathitt Gray, robh+dt, tglx, fabrice.gasnier, esben,
shawnguo, linux-kernel, leoyang.li, knaack.h, akpm, linuxppc-dev
In-Reply-To: <20190407152550.451a7f63@archlinux>
On Sun, Apr 07, 2019 at 03:25:50PM +0100, Jonathan Cameron wrote:
> On Tue, 2 Apr 2019 15:30:35 +0900
> William Breathitt Gray <vilhelm.gray@gmail.com> wrote:
>
> > Changes in v10:
> > - Fix minor typographical errors in documentation
> > - Merge the FlexTimer Module Quadrature decoder counter driver patches
> >
> > This revision is functionally identical to the last; changes in this
> > version were made to fix minor typos in the documentation files and also
> > to pull in the new FTM quadrature decoder counter driver.
> >
> > The Generic Counter API has been and is still in a feature freeze until
> > it is merged into the mainline. The following features will be
> > investigated after the merge: interrupt support for counter devices, and
> > a character device interface for low-latency applications.
>
> Hi William / al,
>
> So the question is how to move this forwards? I'm happy with how it turned
> out and the existing drivers we had in IIO are a lot cleaner under
> the counter subsystem (other than the backwards compatibility for those that
> ever existed in IIO). For those not following closely the situation is:
I've now sucked this into my staging-testing branch and if 0-day is fine
with it, I'll merge it to staging-next in a day or so. This way you can
build on it for any iio drivers that might be coming.
I do have reservations about that one sysfs file that is multi-line, and
I think it will come to bite you in the end over time, so I reserve the
right to say "I told you so" when that happens...
But, I don't have a better answer for it now, so don't really worry
about it :)
thanks,
greg k-h
^ permalink raw reply
* [PATCH] KVM: PPC: Book3S HV: smb->smp comment fixup
From: Palmer Dabbelt @ 2019-04-25 19:53 UTC (permalink / raw)
To: paulus; +Cc: Palmer Dabbelt, linux-kernel, kvm-ppc, linuxppc-dev
I made the same typo when trying to grep for uses of smp_wmb and figured
I might as well fix it.
Signed-off-by: Palmer Dabbelt <palmer@sifive.com>
---
arch/powerpc/kvm/book3s_hv.c | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/arch/powerpc/kvm/book3s_hv.c b/arch/powerpc/kvm/book3s_hv.c
index 06964350b97a..842ab9511b54 100644
--- a/arch/powerpc/kvm/book3s_hv.c
+++ b/arch/powerpc/kvm/book3s_hv.c
@@ -749,7 +749,7 @@ static bool kvmppc_doorbell_pending(struct kvm_vcpu *vcpu)
/*
* Ensure that the read of vcore->dpdes comes after the read
* of vcpu->doorbell_request. This barrier matches the
- * smb_wmb() in kvmppc_guest_entry_inject().
+ * smp_wmb() in kvmppc_guest_entry_inject().
*/
smp_rmb();
vc = vcpu->arch.vcore;
--
2.21.0
^ permalink raw reply related
* Re: [PATCH v10 14/18] drivers/clocksource: timer-fsl-ftm: use common header for FlexTimer #defines
From: Daniel Lezcano @ 2019-04-25 21:41 UTC (permalink / raw)
To: William Breathitt Gray, gregkh
Cc: mark.rutland, benjamin.gaignard, linux-pwm, linux-iio,
patrick.havelange, thierry.reding, pmeerw, lars, linux-arm-kernel,
devicetree, david, robh+dt, tglx, fabrice.gasnier, esben,
shawnguo, linux-kernel, leoyang.li, knaack.h, akpm, linuxppc-dev,
jic23
In-Reply-To: <c82ce954006d9a228c7a6ebb0eabade48bd2c149.1554184734.git.vilhelm.gray@gmail.com>
On 02/04/2019 08:30, William Breathitt Gray wrote:
> From: Patrick Havelange <patrick.havelange@essensium.com>
>
> Common #defines have been moved to "linux/fsl/ftm.h". Thus making use of
> this file.
> Also FTM_SC_CLK_SHIFT has been renamed to FTM_SC_CLK_MASK_SHIFT.
>
> Reviewed-by: Esben Haabendal <esben@haabendal.dk>
> Signed-off-by: Patrick Havelange <patrick.havelange@essensium.com>
> Signed-off-by: William Breathitt Gray <vilhelm.gray@gmail.com>
Please, do pick my Acked-by from V2.
> ---
> drivers/clocksource/timer-fsl-ftm.c | 15 ++-------------
> 1 file changed, 2 insertions(+), 13 deletions(-)
>
> diff --git a/drivers/clocksource/timer-fsl-ftm.c b/drivers/clocksource/timer-fsl-ftm.c
> index 846d18daf893..e1c34b2f53a5 100644
> --- a/drivers/clocksource/timer-fsl-ftm.c
> +++ b/drivers/clocksource/timer-fsl-ftm.c
> @@ -19,20 +19,9 @@
> #include <linux/of_irq.h>
> #include <linux/sched_clock.h>
> #include <linux/slab.h>
> +#include <linux/fsl/ftm.h>
>
> -#define FTM_SC 0x00
> -#define FTM_SC_CLK_SHIFT 3
> -#define FTM_SC_CLK_MASK (0x3 << FTM_SC_CLK_SHIFT)
> -#define FTM_SC_CLK(c) ((c) << FTM_SC_CLK_SHIFT)
> -#define FTM_SC_PS_MASK 0x7
> -#define FTM_SC_TOIE BIT(6)
> -#define FTM_SC_TOF BIT(7)
> -
> -#define FTM_CNT 0x04
> -#define FTM_MOD 0x08
> -#define FTM_CNTIN 0x4C
> -
> -#define FTM_PS_MAX 7
> +#define FTM_SC_CLK(c) ((c) << FTM_SC_CLK_MASK_SHIFT)
>
> struct ftm_clock_device {
> void __iomem *clksrc_base;
>
--
<http://www.linaro.org/> Linaro.org │ Open source software for ARM SoCs
Follow Linaro: <http://www.facebook.com/pages/Linaro> Facebook |
<http://twitter.com/#!/linaroorg> Twitter |
<http://www.linaro.org/linaro-blog/> Blog
^ permalink raw reply
* Re: [PATCH v2] powerpc/pseries: Use correct event modifier in rtas_parse_epow_errlog()
From: Tyrel Datwyler @ 2019-04-25 22:17 UTC (permalink / raw)
To: Yue Haibing, benh, paulus, mpe, mahesh, npiggin, ganeshgr, anton,
ruscur
Cc: linuxppc-dev, linux-kernel
In-Reply-To: <20190424021739.20916-1-yuehaibing@huawei.com>
On 04/23/2019 07:17 PM, Yue Haibing wrote:
> From: YueHaibing <yuehaibing@huawei.com>
>
> rtas_parse_epow_errlog() should pass 'modifier' to
> handle_system_shutdown, because event modifier only use
> bottom 4 bits.
>
> Fixes: 55fc0c561742 ("powerpc/pseries: Parse and handle EPOW interrupts")
> Signed-off-by: YueHaibing <yuehaibing@huawei.com>
> ---
Reviewed-by: Tyrel Datwyler <tyreld@linux.ibm.com>
> v2: fix compile issue by 'event_modifier'-->'modifier'
> ---
> arch/powerpc/platforms/pseries/ras.c | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/arch/powerpc/platforms/pseries/ras.c b/arch/powerpc/platforms/pseries/ras.c
> index c97d153..744604d 100644
> --- a/arch/powerpc/platforms/pseries/ras.c
> +++ b/arch/powerpc/platforms/pseries/ras.c
> @@ -285,7 +285,7 @@ static void rtas_parse_epow_errlog(struct rtas_error_log *log)
> break;
>
> case EPOW_SYSTEM_SHUTDOWN:
> - handle_system_shutdown(epow_log->event_modifier);
> + handle_system_shutdown(modifier);
> break;
>
> case EPOW_SYSTEM_HALT:
>
^ permalink raw reply
* Re: [PATCH v2] mm: Fix modifying of page protection by insert_pfn_pmd()
From: Dan Williams @ 2019-04-26 0:33 UTC (permalink / raw)
To: Jan Kara
Cc: linux-nvdimm, Aneesh Kumar K.V, Matthew Wilcox, Linux MM,
Chandan Rajendra, stable, Andrew Morton, linuxppc-dev
In-Reply-To: <20190425073149.GA21215@quack2.suse.cz>
On Thu, Apr 25, 2019 at 12:32 AM Jan Kara <jack@suse.cz> wrote:
>
> On Wed 24-04-19 11:13:48, Dan Williams wrote:
> > On Wed, Apr 24, 2019 at 10:38 AM Matthew Wilcox <willy@infradead.org> wrote:
> > >
> > > On Wed, Apr 24, 2019 at 10:13:15AM -0700, Dan Williams wrote:
> > > > I think unaligned addresses have always been passed to
> > > > vmf_insert_pfn_pmd(), but nothing cared until this patch. I *think*
> > > > the only change needed is the following, thoughts?
> > > >
> > > > diff --git a/fs/dax.c b/fs/dax.c
> > > > index ca0671d55aa6..82aee9a87efa 100644
> > > > --- a/fs/dax.c
> > > > +++ b/fs/dax.c
> > > > @@ -1560,7 +1560,7 @@ static vm_fault_t dax_iomap_pmd_fault(struct
> > > > vm_fault *vmf, pfn_t *pfnp,
> > > > }
> > > >
> > > > trace_dax_pmd_insert_mapping(inode, vmf, PMD_SIZE, pfn, entry);
> > > > - result = vmf_insert_pfn_pmd(vma, vmf->address, vmf->pmd, pfn,
> > > > + result = vmf_insert_pfn_pmd(vma, pmd_addr, vmf->pmd, pfn,
> > > > write);
> > >
> > > We also call vmf_insert_pfn_pmd() in dax_insert_pfn_mkwrite() -- does
> > > that need to change too?
> >
> > It wasn't clear to me that it was a problem. I think that one already
> > happens to be pmd-aligned.
>
> Why would it need to be? The address is taken from vmf->address and that's
> set up in __handle_mm_fault() like .address = address & PAGE_MASK. So I
> don't see anything forcing PMD alignment of the virtual address...
True. So now I'm wondering if the masking should be done internal to
the routine. Given it's prefixed vmf_ it seems to imply the api is
prepared to take raw 'struct vm_fault' parameters. I think I'll go
that route unless someone sees a reason to require the caller to
handle this responsibility.
^ permalink raw reply
* Re: [PATCH v2] mm: Fix modifying of page protection by insert_pfn_pmd()
From: Matthew Wilcox @ 2019-04-26 0:51 UTC (permalink / raw)
To: Dan Williams
Cc: Jan Kara, linux-nvdimm, Aneesh Kumar K.V, stable, Linux MM,
Chandan Rajendra, Andrew Morton, linuxppc-dev
In-Reply-To: <CAPcyv4iYMP4NWxa08zTdRxtc4UcbFFOCwbMZijB0bc2WcawggQ@mail.gmail.com>
On Thu, Apr 25, 2019 at 05:33:04PM -0700, Dan Williams wrote:
> On Thu, Apr 25, 2019 at 12:32 AM Jan Kara <jack@suse.cz> wrote:
> > > > We also call vmf_insert_pfn_pmd() in dax_insert_pfn_mkwrite() -- does
> > > > that need to change too?
> > >
> > > It wasn't clear to me that it was a problem. I think that one already
> > > happens to be pmd-aligned.
> >
> > Why would it need to be? The address is taken from vmf->address and that's
> > set up in __handle_mm_fault() like .address = address & PAGE_MASK. So I
> > don't see anything forcing PMD alignment of the virtual address...
>
> True. So now I'm wondering if the masking should be done internal to
> the routine. Given it's prefixed vmf_ it seems to imply the api is
> prepared to take raw 'struct vm_fault' parameters. I think I'll go
> that route unless someone sees a reason to require the caller to
> handle this responsibility.
The vmf_ prefix was originally used to indicate 'returns a vm_fault_t'
instead of 'returns an errno'. That said, I like the interpretation
you're coming up with here, and it makes me wonder if we shouldn't
change vmf_insert_pfn_pmd() to take (vmf, pfn, write) as arguments
instead of separate vma, address & pmd arguments.
^ permalink raw reply
* Re: powerpc hugepage leak caused by 576ed913 "block: use bio_add_page in bio_iov_iter_get_pages"
From: David Gibson @ 2019-04-26 1:05 UTC (permalink / raw)
To: Christoph Hellwig
Cc: Jens Axboe, linux-kernel, Nick Piggin, Michael Ellerman,
Paul Mackerras, linuxppc-dev
In-Reply-To: <20190425061958.GA7881@lst.de>
[-- Attachment #1: Type: text/plain, Size: 4404 bytes --]
On Thu, Apr 25, 2019 at 08:19:58AM +0200, Christoph Hellwig wrote:
> Just curious: What exact trees do you see this with? This area
> changed a lot with the multipage bvec support, and subsequent fixes.
So, I tried it with 576ed913 itself and with 576ed913^ to verify that
it didn't happen there. The problem also occurred with Linus' tree as
of when I started bisecting, which appears to have been 444fe991.
Actually, come to that, here's the whole bisect log in case it's
helpful:
# git bisect log
git bisect start
# good: [bebc6082da0a9f5d47a1ea2edc099bf671058bd4] Linux 4.14
git bisect good bebc6082da0a9f5d47a1ea2edc099bf671058bd4
# bad: [444fe991353987c1c9bc5ab1f903d01f1b4ad415] Merge tag 'riscv-for-linus-5.1-rc6' of git://git.kernel.org/pub/scm/linux/kernel/git/palmer/riscv-linux
git bisect bad 444fe991353987c1c9bc5ab1f903d01f1b4ad415
# good: [399c4129eba6145924ab90363352b7bdcd554751] Merge tag 'pxa-for-4.19-dma_slave_map' of https://github.com/rjarzmik/linux
git bisect good 399c4129eba6145924ab90363352b7bdcd554751
# bad: [73b6f96cbc0162787bcbdac5f538167084c8d605] Merge branch 'drm-fixes-4.20' of git://people.freedesktop.org/~agd5f/linux into drm-fixes
git bisect bad 73b6f96cbc0162787bcbdac5f538167084c8d605
# good: [85a585918fb4122ad26b6febaec5c3c90bf2535c] Merge tag 'loadpin-security-next' of https://git.kernel.org/pub/scm/linux/kernel/git/kees/linux into next-loadpin
git bisect good 85a585918fb4122ad26b6febaec5c3c90bf2535c
# bad: [3acbd2de6bc3af215c6ed7732dfc097d1e238503] Merge tag 'sound-4.20-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/tiwai/sound
git bisect bad 3acbd2de6bc3af215c6ed7732dfc097d1e238503
# good: [8f18da47211554f1ef674fef627c05f23b75a8e0] Merge branch 'master' of git://git.kernel.org/pub/scm/linux/kernel/git/klassert/ipsec-next
git bisect good 8f18da47211554f1ef674fef627c05f23b75a8e0
# bad: [0d1b82cd8ac2e8856ae9045c97782ac1c359929c] Merge branch 'ras-core-for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip
git bisect bad 0d1b82cd8ac2e8856ae9045c97782ac1c359929c
# bad: [1650ac53066577a5e83fe3e9d992c9311597ff8c] Merge tag 'mmc-v4.20' of git://git.kernel.org/pub/scm/linux/kernel/git/ulfh/mmc
git bisect bad 1650ac53066577a5e83fe3e9d992c9311597ff8c
# bad: [6ab9e09238fdfd742fe23b81e2d385a1cab49d9b] Merge tag 'for-4.20/block-20181021' of git://git.kernel.dk/linux-block
git bisect bad 6ab9e09238fdfd742fe23b81e2d385a1cab49d9b
# good: [528985117126f11beea339cf39120ee99da04cd2] Merge tag 'arm64-upstream' of git://git.kernel.org/pub/scm/linux/kernel/git/arm64/linux
git bisect good 528985117126f11beea339cf39120ee99da04cd2
# bad: [2cf99bbd106f89fc72f778e8ad9d5538f1ef939b] lightnvm: pblk: add helpers for chunk addresses
git bisect bad 2cf99bbd106f89fc72f778e8ad9d5538f1ef939b
# bad: [33b14f67a4e1eabd219fd6543da8f15ed86b641c] nvme: register ns_id attributes as default sysfs groups
git bisect bad 33b14f67a4e1eabd219fd6543da8f15ed86b641c
# bad: [27ca1d4ed04ea29dc77b47190a3cc82697023e76] block: move req_gap_back_merge to blk.h
git bisect bad 27ca1d4ed04ea29dc77b47190a3cc82697023e76
# bad: [07b05bcc3213ac9f8c28c9d835b4bf3d5798cc60] blkcg: convert blkg_lookup_create to find closest blkg
git bisect bad 07b05bcc3213ac9f8c28c9d835b4bf3d5798cc60
# good: [cbeb869a3d1110450186b738199963c5e68c2a71] block, bfq: correctly charge and reset entity service in all cases
git bisect good cbeb869a3d1110450186b738199963c5e68c2a71
# bad: [576ed9135489c723fb39b97c4e2c73428d06dd78] block: use bio_add_page in bio_iov_iter_get_pages
git bisect bad 576ed9135489c723fb39b97c4e2c73428d06dd78
# good: [c8765de0adfcaaf4ffb2d951e07444f00ffa9453] blok, bfq: do not plug I/O if all queues are weight-raised
git bisect good c8765de0adfcaaf4ffb2d951e07444f00ffa9453
# first bad commit: [576ed9135489c723fb39b97c4e2c73428d06dd78] block: use bio_add_page in bio_iov_iter_get_pages
The problem also occurred with the RHEL8 downstream kernel tree.
That's based on 4.18, but has 576ed913 backported.
> So I'd be really curious if it can be reproduced with Jens' latest
> block for-5.2 tree (which should be in latest linux-next).
I'll see if I can try that when I next get access to the machine.
--
David Gibson | I'll have my music baroque, and my code
david AT gibson.dropbear.id.au | minimalist, thank you. NOT _the_ _other_
| _way_ _around_!
http://www.ozlabs.org/~dgibson
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply
* [PATCH] ASoC: fsl_sai: Add missing return 0 in remove()
From: Nicolin Chen @ 2019-04-26 3:20 UTC (permalink / raw)
To: broonie
Cc: daniel.baluta, sfr, alsa-devel, timur, lgirdwood, linuxppc-dev,
Xiubo.Lee, tiwai, perex, festevam, linux-kernel
Build warning being reported:
sound/soc/fsl/fsl_sai.c: In function 'fsl_sai_remove':
sound/soc/fsl/fsl_sai.c:921:1: warning: no return statement in
function returning non-void [-Wreturn-type]
So this patch just adds a "return 0" to fix it.
Fixes: 812ad463e089 ("ASoC: fsl_sai: Add support for runtime pm")
Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
Signed-off-by: Nicolin Chen <nicoleotsuka@gmail.com>
---
sound/soc/fsl/fsl_sai.c | 2 ++
1 file changed, 2 insertions(+)
diff --git a/sound/soc/fsl/fsl_sai.c b/sound/soc/fsl/fsl_sai.c
index 26c27dc..8593269 100644
--- a/sound/soc/fsl/fsl_sai.c
+++ b/sound/soc/fsl/fsl_sai.c
@@ -918,6 +918,8 @@ static int fsl_sai_probe(struct platform_device *pdev)
static int fsl_sai_remove(struct platform_device *pdev)
{
pm_runtime_disable(&pdev->dev);
+
+ return 0;
}
static const struct of_device_id fsl_sai_ids[] = {
--
2.7.4
^ permalink raw reply related
page: next (older) | prev (newer) | latest
- recent:[subjects (threaded)|topics (new)|topics (active)]
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox