summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2018-08-14 23:39:52 +0300
committerLinus Torvalds <torvalds@linux-foundation.org>2018-08-14 23:39:52 +0300
commit2c20443ec221dcb76484b30933593e8ecd836bbd (patch)
tree870ba518b23cfe2f190e52688440e2e4d72f0545 /Documentation
parentb018fc9800557bd14a40d69501e19c340eb2c521 (diff)
parent76f7d6c07acd7a694ccc97355d37637f6677de51 (diff)
downloadlinux-2c20443ec221dcb76484b30933593e8ecd836bbd.tar.xz
Merge tag 'acpi-4.19-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/rafael/linux-pm
Pull ACPI updates from Rafael Wysocki: "These revert two ACPICA commits that are not needed any more, rework the property graphs support in ACPI to be more aligned with the analogous DT code, add some new quirks and remove one that isn't needed any more, add a special platform driver to enumerate multiple I2C devices hooked up to the same device object in the ACPI tables and update the battery and button drivers. Specifics: - Revert two ACPICA commits that are not needed any more (Erik Schmauss). - Rework property graph support in the ACPI device properties framework to make it behave more like the analogous DT code and update the documentation of it (Sakari Ailus). - Change the default ACPI device status after initialization to ACPI_STA_DEFAULT instead of 0 (Hans de Goede). - Add a special platform driver for enumerating multiple I2C devices hooked up to the same object in the ACPI tables (Hans de Goede). - Fix the ACPI battery driver to avoid reporting full capacity on systems without support for that and clean it up (Hans de Goede, Dmitry Rozhkov, Lucas Rangit Magasweran). - Add two system wakeup quirks to the ACPI EC driver (Aaron Ma, Mika Westerberg). - Add the touchscreen on Dell Venue Pro 7139 to the list of "always present" devices to make it work (Tristian Celestin). - Revert a special tables handling quirk for Dell XPS 9570 and Precision M5530 which is not needed any more (Kai Heng Feng). - Add support for a new OEM _OSI string to allow system vendors to work around issues with NVidia HDMI audio (Alex Hung). - Prevent the ACPI button driver from reporting excessive system wakeup events and clean it up (Ravi Chandra Sadineni, Randy Dunlap). - Clean up two minor code style issues in the ACPI core and GHES handling on ARM64 (Dongjiu Geng, John Garry, Tom Todd)" * tag 'acpi-4.19-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/rafael/linux-pm: (34 commits) platform/x86: Add ACPI i2c-multi-instantiate pseudo driver ACPI / x86: utils: Remove status workaround from acpi_device_always_present() ACPI / scan: Create platform device for fwnodes with multiple i2c devices ACPI / scan: Initialize status to ACPI_STA_DEFAULT ACPI / EC: Add another entry for Thinkpad X1 Carbon 6th ACPI: bus: Fix a pointer coding style issue arm64 / ACPI: clean the additional checks before calling ghes_notify_sea() ACPI / scan: Add static attribute to indirect_io_hosts[] ACPI / battery: Do not export energy_full[_design] on devices without full_charge_capacity ACPI / EC: Use ec_no_wakeup on ThinkPad X1 Yoga 3rd ACPI / battery: get rid of negations in conditions ACPI / battery: use specialized print macros ACPI / battery: reorder headers alphabetically ACPI / battery: drop inclusion of init.h ACPI: battery: remove redundant old_present check on insertion ACPI: property: graph: Update graph documentation to use generic references ACPI: property: graph: Improve graph documentation for port/ep numbering ACPI: property: graph: Fix graph documentation ACPI: property: Update documentation for hierarchical data extension 1.1 ACPI: property: Document key numbering for hierarchical data extension refs ...
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/acpi/dsd/data-node-references.txt89
-rw-r--r--Documentation/acpi/dsd/graph.txt72
2 files changed, 131 insertions, 30 deletions
diff --git a/Documentation/acpi/dsd/data-node-references.txt b/Documentation/acpi/dsd/data-node-references.txt
new file mode 100644
index 000000000000..c3871565c8cf
--- /dev/null
+++ b/Documentation/acpi/dsd/data-node-references.txt
@@ -0,0 +1,89 @@
+Copyright (C) 2018 Intel Corporation
+Author: Sakari Ailus <sakari.ailus@linux.intel.com>
+
+
+Referencing hierarchical data nodes
+-----------------------------------
+
+ACPI in general allows referring to device objects in the tree only.
+Hierarchical data extension nodes may not be referred to directly, hence this
+document defines a scheme to implement such references.
+
+A reference consist of the device object name followed by one or more
+hierarchical data extension [1] keys. Specifically, the hierarchical data
+extension node which is referred to by the key shall lie directly under the
+parent object i.e. either the device object or another hierarchical data
+extension node.
+
+The keys in the hierarchical data nodes shall consist of the name of the node,
+"@" character and the number of the node in hexadecimal notation (without pre-
+or postfixes). The same ACPI object shall include the _DSD property extension
+with a property "reg" that shall have the same numerical value as the number of
+the node.
+
+In case a hierarchical data extensions node has no numerical value, then the
+"reg" property shall be omitted from the ACPI object's _DSD properties and the
+"@" character and the number shall be omitted from the hierarchical data
+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.
+
+ Device (DEV0)
+ {
+ Name (_DSD, Package () {
+ ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
+ Package () {
+ Package () { "node@0", NOD0 },
+ Package () { "node@1", NOD1 },
+ }
+ })
+ Name (NOD0, Package() {
+ ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+ Package () {
+ Package () { "random-property", 3 },
+ }
+ })
+ Name (NOD1, Package() {
+ ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
+ Package () {
+ Package () { "anothernode", ANOD },
+ }
+ })
+ Name (ANOD, Package() {
+ ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+ Package () {
+ Package () { "random-property", 0 },
+ }
+ })
+ }
+
+ Device (DEV1)
+ {
+ Name (_DSD, Package () {
+ ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+ Package () {
+ Package () { "reference", ^DEV0, "node@1", "anothernode" },
+ }
+ })
+ }
+
+Please also see a graph example in graph.txt .
+
+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.
+
+[2] Device Properties UUID For _DSD.
+ <URL:http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>,
+ referenced 2016-10-04.
diff --git a/Documentation/acpi/dsd/graph.txt b/Documentation/acpi/dsd/graph.txt
index ac09e3138b79..b9ce910781dc 100644
--- a/Documentation/acpi/dsd/graph.txt
+++ b/Documentation/acpi/dsd/graph.txt
@@ -36,29 +36,41 @@ The port and endpoint concepts are very similar to those in Devicetree
[3]. A port represents an interface in a device, and an endpoint
represents a connection to that interface.
-All port nodes are located under the device's "_DSD" node in the
-hierarchical data extension tree. The property extension related to
-each port node must contain the key "port" and an integer value which
-is the number of the port. The object it refers to should be called "PRTX",
-where "X" is the number of the port.
-
-Further on, endpoints are located under the individual port nodes. The
-first hierarchical data extension package list entry of the endpoint
-nodes must begin with "endpoint" and must be followed by 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.
-
-Each port node contains a property extension key "port", the value of
-which is the number of the port node. The each endpoint is similarly numbered
-with a property extension key "endpoint". Port numbers must be unique within a
-device and endpoint numbers must be unique within a port.
+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:
+
+ Package() { "port@4", PRT4 }
+
+Further on, endpoints are located under the port nodes. The hierarchical
+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() { "endpoint@0", EP40 }
+
+Each port node contains a property extension key "port", the value of which is
+the number of the port. Each endpoint is similarly numbered with a property
+extension key "reg", the value of which is the number of the endpoint. Port
+numbers must be unique within a device and endpoint numbers must be unique
+within a port. If a device object may only has a single port, then the number
+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
-the remote device reference, number of the port in the device and finally the
-number of the endpoint in that port. Individual references thus appear as:
+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:
- Package() { device, port_number, endpoint_number }
+ 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.
The references to endpoints must be always done both ways, to the
remote endpoint and back from the referred remote endpoint node.
@@ -76,24 +88,24 @@ A simple example of this is show below:
},
ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
Package () {
- Package () { "port0", "PRT0" },
+ Package () { "port@0", PRT0 },
}
})
Name (PRT0, Package() {
ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
Package () {
- Package () { "port", 0 },
+ Package () { "reg", 0 },
},
ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
Package () {
- Package () { "endpoint0", "EP00" },
+ Package () { "endpoint@0", EP00 },
}
})
Name (EP00, Package() {
ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
Package () {
- Package () { "endpoint", 0 },
- Package () { "remote-endpoint", Package() { \_SB.PCI0.ISP, 4, 0 } },
+ Package () { "reg", 0 },
+ Package () { "remote-endpoint", Package() { \_SB.PCI0.ISP, "port@4", "endpoint@0" } },
}
})
}
@@ -106,26 +118,26 @@ A simple example of this is show below:
Name (_DSD, Package () {
ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
Package () {
- Package () { "port4", "PRT4" },
+ Package () { "port@4", PRT4 },
}
})
Name (PRT4, Package() {
ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
Package () {
- Package () { "port", 4 }, /* CSI-2 port number */
+ Package () { "reg", 4 }, /* CSI-2 port number */
},
ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
Package () {
- Package () { "endpoint0", "EP40" },
+ Package () { "endpoint@0", EP40 },
}
})
Name (EP40, Package() {
ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
Package () {
- Package () { "endpoint", 0 },
- Package () { "remote-endpoint", Package () { \_SB.PCI0.I2C2.CAM0, 0, 0 } },
+ Package () { "reg", 0 },
+ Package () { "remote-endpoint", Package () { \_SB.PCI0.I2C2.CAM0, "port@0", "endpoint@0" } },
}
})
}
@@ -151,7 +163,7 @@ References
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.pdf>,
+ <URL: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.