iv/linux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Documentation: ACPI: Update references

Browse Source 
Update references for the ACPI _DSD documentation. In particular:

- Substitute _DSD property and hierarchical data extension documents with
  the newer DSD guide that replaces both, and use its HTML form.

- Refer to the latest ACPI spec.

- Add data node reference documentation reference to graph documentation.

Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
Reviewed-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
This commit is contained in:
Sakari Ailus 2021-12-01 14:59:32 +02:00 committed by Rafael J. Wysocki
parent a111749522
commit 59f3f98284
4 changed files with 58 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
Documentation/firmware-guide/acpi/dsd/data-node-references.rst
View File

@ -13,9 +13,9 @@ Hierarchical data extension nodes may not be referred to directly, hence this
document defines a scheme to implement such references. document defines a scheme to implement such references.
A reference consist of the device object name followed by one or more A reference consist of the device object name followed by one or more
hierarchical data extension [1] keys. Specifically, the hierarchical data hierarchical data extension [dsd-guide] keys. Specifically, the hierarchical
extension node which is referred to by the key shall lie directly under the data extension node which is referred to by the key shall lie directly under
parent object i.e. either the device object or another hierarchical data the parent object i.e. either the device object or another hierarchical data
extension node. extension node.
The keys in the hierarchical data nodes shall consist of the name of the node, The keys in the hierarchical data nodes shall consist of the name of the node,
@ -33,7 +33,7 @@ extension key.
Example Example
======= =======
In the ASL snippet below, the "reference" _DSD property [2] contains a In the ASL snippet below, the "reference" _DSD property contains a
device object reference to DEV0 and under that device object, a device object reference to DEV0 and under that device object, a
hierarchical data extension key "node@1" referring to the NOD1 object hierarchical data extension key "node@1" referring to the NOD1 object
and lastly, a hierarchical data extension key "anothernode" referring to and lastly, a hierarchical data extension key "anothernode" referring to
@ -91,10 +91,6 @@ Documentation/firmware-guide/acpi/dsd/graph.rst.
References References
========== ==========
[1] Hierarchical Data Extension UUID For _DSD. [dsd-guide] DSD Guide.
<https://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>, https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc, referenced
referenced 2018-07-17. 2021-11-30.
[2] Device Properties UUID For _DSD.
<https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>,
referenced 2016-10-04.

40
Documentation/firmware-guide/acpi/dsd/graph.rst
View File

@ -7,11 +7,11 @@ Graphs
_DSD _DSD
==== ====
_DSD (Device Specific Data) [7] is a predefined ACPI device _DSD (Device Specific Data) [dsd-guide] is a predefined ACPI device
configuration object that can be used to convey information on configuration object that can be used to convey information on
hardware features which are not specifically covered by the ACPI hardware features which are not specifically covered by the ACPI
specification [1][6]. There are two _DSD extensions that are relevant specification [acpi]. There are two _DSD extensions that are relevant
for graphs: property [4] and hierarchical data extensions [5]. The for graphs: property [dsd-guide] and hierarchical data extensions. The
property extension provides generic key-value pairs whereas the property extension provides generic key-value pairs whereas the
hierarchical data extension supports nodes with references to other hierarchical data extension supports nodes with references to other
nodes, forming a tree. The nodes in the tree may contain properties as nodes, forming a tree. The nodes in the tree may contain properties as
@ -36,8 +36,9 @@ Ports and endpoints
=================== ===================
The port and endpoint concepts are very similar to those in Devicetree The port and endpoint concepts are very similar to those in Devicetree
[3]. A port represents an interface in a device, and an endpoint [devicetree, graph-bindings]. A port represents an interface in a device, and
represents a connection to that interface. an endpoint represents a connection to that interface. Also see [data-node-ref]
for generic data node references.
All port nodes are located under the device's "_DSD" node in the hierarchical 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 data extension tree. The data extension related to each port node must begin
@ -153,25 +154,20 @@ the "ISP" device and vice versa.
References References
========== ==========
[1] _DSD (Device Specific Data) Implementation Guide. [acpi] Advanced Configuration and Power Interface Specification.
https://www.uefi.org/sites/default/files/resources/_DSD-implementation-guide-toplevel-1_1.htm, https://uefi.org/specifications/ACPI/6.4/, referenced 2021-11-30.
referenced 2016-10-03.
[2] Devicetree. https://www.devicetree.org, referenced 2016-10-03. [data-node-ref] Documentation/firmware-guide/acpi/dsd/data-node-references.rst
[3] Documentation/devicetree/bindings/graph.txt [devicetree] Devicetree. https://www.devicetree.org, referenced 2016-10-03.
[4] Device Properties UUID For _DSD. [dsd-guide] DSD Guide.
https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf, https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc, referenced
referenced 2016-10-04. 2021-11-30.
[5] Hierarchical Data Extension UUID For _DSD. [dsd-rules] _DSD Device Properties Usage Rules.
https://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.
https://www.uefi.org/sites/default/files/resources/ACPI_6_1.pdf,
referenced 2016-10-04.
[7] _DSD Device Properties Usage Rules.
Documentation/firmware-guide/acpi/DSD-properties-rules.rst Documentation/firmware-guide/acpi/DSD-properties-rules.rst
[graph-bindings] Common bindings for device graphs (Devicetree).
https://github.com/devicetree-org/dt-schema/blob/main/schemas/graph.yaml,
referenced 2021-11-30.

40
Documentation/firmware-guide/acpi/dsd/leds.rst
View File

@ -5,19 +5,20 @@
Describing and referring to LEDs in ACPI Describing and referring to LEDs in ACPI
======================================== ========================================
Individual LEDs are described by hierarchical data extension [6] nodes under the Individual LEDs are described by hierarchical data extension [5] nodes under the
device node, the LED driver chip. The "reg" property in the LED specific nodes device node, the LED driver chip. The "reg" property in the LED specific nodes
tells the numerical ID of each individual LED output to which the LEDs are tells the numerical ID of each individual LED output to which the LEDs are
connected. [3] The hierarchical data nodes are named "led@X", where X is the connected. [leds] The hierarchical data nodes are named "led@X", where X is the
number of the LED output. number of the LED output.
Referring to LEDs in Device tree is documented in [4], in "flash-leds" property Referring to LEDs in Device tree is documented in [video-interfaces], in
documentation. In short, LEDs are directly referred to by using phandles. "flash-leds" property documentation. In short, LEDs are directly referred to by
using phandles.
While Device tree allows referring to any node in the tree[1], in ACPI While Device tree allows referring to any node in the tree [devicetree], in
references are limited to device nodes only [2]. For this reason using the same ACPI references are limited to device nodes only [acpi]. For this reason using
mechanism on ACPI is not possible. A mechanism to refer to non-device ACPI nodes the same mechanism on ACPI is not possible. A mechanism to refer to non-device
is documented in [7]. ACPI nodes is documented in [data-node-ref].
ACPI allows (as does DT) using integer arguments after the reference. A ACPI allows (as does DT) using integer arguments after the reference. A
combination of the LED driver device reference and an integer argument, combination of the LED driver device reference and an integer argument,
@ -90,22 +91,17 @@ where
References References
========== ==========
[1] Device tree. https://www.devicetree.org, referenced 2019-02-21. [acpi] Advanced Configuration and Power Interface Specification.
https://uefi.org/specifications/ACPI/6.4/, referenced 2021-11-30.
[2] Advanced Configuration and Power Interface Specification. [data-node-ref] Documentation/firmware-guide/acpi/dsd/data-node-references.rst
https://uefi.org/sites/default/files/resources/ACPI_6_3_final_Jan30.pdf,
referenced 2019-02-21.
[3] Documentation/devicetree/bindings/leds/common.txt [devicetree] Devicetree. https://www.devicetree.org, referenced 2019-02-21.
[4] Documentation/devicetree/bindings/media/video-interfaces.txt [dsd-guide] DSD Guide.
https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc, referenced
2021-11-30.
[5] Device Properties UUID For _DSD. [leds] Documentation/devicetree/bindings/leds/common.yaml
https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf,
referenced 2019-02-21.
[6] Hierarchical Data Extension UUID For _DSD. [video-interfaces] Documentation/devicetree/bindings/media/video-interfaces.yaml
https://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf,
referenced 2019-02-21.
[7] Documentation/firmware-guide/acpi/dsd/data-node-references.rst

28
Documentation/firmware-guide/acpi/dsd/phy.rst
View File

@ -4,17 +4,17 @@
MDIO bus and PHYs in ACPI MDIO bus and PHYs in ACPI
========================= =========================
The PHYs on an MDIO bus [1] are probed and registered using The PHYs on an MDIO bus [phy] are probed and registered using
fwnode_mdiobus_register_phy(). fwnode_mdiobus_register_phy().
Later, for connecting these PHYs to their respective MACs, the PHYs registered Later, for connecting these PHYs to their respective MACs, the PHYs registered
on the MDIO bus have to be referenced. on the MDIO bus have to be referenced.
This document introduces two _DSD properties that are to be used This document introduces two _DSD properties that are to be used
for connecting PHYs on the MDIO bus [3] to the MAC layer. for connecting PHYs on the MDIO bus [dsd-properties-rules] to the MAC layer.
These properties are defined in accordance with the "Device These properties are defined in accordance with the "Device
Properties UUID For _DSD" [2] document and the Properties UUID For _DSD" [dsd-guide] document and the
daffd814-6eba-4d8c-8a91-bc9bbf4aa301 UUID must be used in the Device daffd814-6eba-4d8c-8a91-bc9bbf4aa301 UUID must be used in the Device
Data Descriptors containing them. Data Descriptors containing them.
@ -48,22 +48,22 @@ as device object references (e.g. \_SB.MDI0.PHY1).
phy-mode phy-mode
-------- --------
The "phy-mode" _DSD property is used to describe the connection to The "phy-mode" _DSD property is used to describe the connection to
the PHY. The valid values for "phy-mode" are defined in [4]. the PHY. The valid values for "phy-mode" are defined in [ethernet-controller].
managed managed
------- -------
Optional property, which specifies the PHY management type. Optional property, which specifies the PHY management type.
The valid values for "managed" are defined in [4]. The valid values for "managed" are defined in [ethernet-controller].
fixed-link fixed-link
---------- ----------
The "fixed-link" is described by a data-only subnode of the The "fixed-link" is described by a data-only subnode of the
MAC port, which is linked in the _DSD package via MAC port, which is linked in the _DSD package via
hierarchical data extension (UUID dbb8e3e6-5886-4ba6-8795-1319f52a966b hierarchical data extension (UUID dbb8e3e6-5886-4ba6-8795-1319f52a966b
in accordance with [5] "_DSD Implementation Guide" document). in accordance with [dsd-guide] "_DSD Implementation Guide" document).
The subnode should comprise a required property ("speed") and The subnode should comprise a required property ("speed") and
possibly the optional ones - complete list of parameters and possibly the optional ones - complete list of parameters and
their values are specified in [4]. their values are specified in [ethernet-controller].
The following ASL example illustrates the usage of these properties. The following ASL example illustrates the usage of these properties.
@ -188,12 +188,14 @@ MAC node example with a "fixed-link" subnode.
References References
========== ==========
[1] Documentation/networking/phy.rst [phy] Documentation/networking/phy.rst
[2] https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf [dsd-properties-rules]
Documentation/firmware-guide/acpi/DSD-properties-rules.rst
[3] Documentation/firmware-guide/acpi/DSD-properties-rules.rst [ethernet-controller]
Documentation/devicetree/bindings/net/ethernet-controller.yaml
[4] Documentation/devicetree/bindings/net/ethernet-controller.yaml [dsd-guide] DSD Guide.
https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc, referenced
[5] https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.pdf 2021-11-30.