diff options
Diffstat (limited to 'Documentation/firmware-guide/acpi/dsd')
| -rw-r--r-- | Documentation/firmware-guide/acpi/dsd/data-node-references.rst | 41 | ||||
| -rw-r--r-- | Documentation/firmware-guide/acpi/dsd/graph.rst | 51 | ||||
| -rw-r--r-- | Documentation/firmware-guide/acpi/dsd/leds.rst | 39 | ||||
| -rw-r--r-- | Documentation/firmware-guide/acpi/dsd/phy.rst | 201 |
4 files changed, 259 insertions, 73 deletions
diff --git a/Documentation/firmware-guide/acpi/dsd/data-node-references.rst b/Documentation/firmware-guide/acpi/dsd/data-node-references.rst index febccbc5689d..ccb4b153e6f2 100644 --- a/Documentation/firmware-guide/acpi/dsd/data-node-references.rst +++ b/Documentation/firmware-guide/acpi/dsd/data-node-references.rst @@ -5,18 +5,21 @@ Referencing hierarchical data nodes =================================== -:Copyright: |copy| 2018 Intel Corporation +:Copyright: |copy| 2018, 2021 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 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. +A reference to a _DSD hierarchical data node is a string consisting of a +device object reference followed by a dot (".") and a relative path to a data +node object. Do not use non-string references as this will produce a copy of +the hierarchical data node, not a reference! + +The hierarchical data extension node which is referred to shall be located +directly under its parent object i.e. either the device object or another +hierarchical data extension node [dsd-guide]. 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- @@ -33,11 +36,9 @@ 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 contains a string +reference to a hierarchical data extension node ANOD under DEV0 under the parent +of DEV1. ANOD is also the final target node of the reference. :: Device (DEV0) @@ -52,12 +53,14 @@ the ANOD object which is also the final target node of the reference. Name (NOD0, Package() { ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), Package () { + Package () { "reg", 0 }, Package () { "random-property", 3 }, } }) Name (NOD1, Package() { ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), Package () { + Package () { "reg", 1 }, Package () { "anothernode", "ANOD" }, } }) @@ -74,20 +77,18 @@ the ANOD object which is also the final target node of the reference. Name (_DSD, Package () { ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), Package () { - Package () { "reference", ^DEV0, "node@1", "anothernode" }, + Package () { "reference", "^DEV0.ANOD" } + }, } }) } -Please also see a graph example in :doc:`graph`. +Please also see a graph example in +Documentation/firmware-guide/acpi/dsd/graph.rst. References ========== -[1] Hierarchical Data Extension UUID For _DSD. -<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. -<http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>, -referenced 2016-10-04. +[dsd-guide] DSD Guide. + https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc, referenced + 2021-11-30. diff --git a/Documentation/firmware-guide/acpi/dsd/graph.rst b/Documentation/firmware-guide/acpi/dsd/graph.rst index 1a6ce7afba5e..d6ae5ffa748c 100644 --- a/Documentation/firmware-guide/acpi/dsd/graph.rst +++ b/Documentation/firmware-guide/acpi/dsd/graph.rst @@ -7,11 +7,11 @@ Graphs _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 hardware features which are not specifically covered by the ACPI -specification [1][6]. There are two _DSD extensions that are relevant -for graphs: property [4] and hierarchical data extensions [5]. The +specification [acpi]. There are two _DSD extensions that are relevant +for graphs: property [dsd-guide] and hierarchical data extensions. The property extension provides generic key-value pairs whereas the hierarchical data extension supports nodes with references to other 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 -[3]. A port represents an interface in a device, and an endpoint -represents a connection to that interface. +[devicetree, graph-bindings]. A port represents an interface in a device, and +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 data extension tree. The data extension related to each port node must begin @@ -65,12 +66,9 @@ 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 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:: +name followed by a string reference in the same package. [data-node-ref]:: - Package() { device, "port@X", "endpoint@Y" } + "device.datanode" In the above example, "X" is the number of the port and "Y" is the number of the endpoint. @@ -108,7 +106,7 @@ A simple example of this is show below:: ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), Package () { Package () { "reg", 0 }, - Package () { "remote-endpoint", Package() { \_SB.PCI0.ISP, "port@4", "endpoint@0" } }, + Package () { "remote-endpoint", "\\_SB.PCI0.ISP.EP40" }, } }) } @@ -140,7 +138,7 @@ A simple example of this is show below:: ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), Package () { Package () { "reg", 0 }, - Package () { "remote-endpoint", Package () { \_SB.PCI0.I2C2.CAM0, "port@0", "endpoint@0" } }, + Package () { "remote-endpoint", "\\_SB.PCI0.I2C2.CAM0.EP00" }, } }) } @@ -153,25 +151,20 @@ the "ISP" device and vice versa. References ========== -[1] _DSD (Device Specific Data) Implementation Guide. - http://www.uefi.org/sites/default/files/resources/_DSD-implementation-guide-toplevel-1_1.htm, - referenced 2016-10-03. +[acpi] Advanced Configuration and Power Interface Specification. + https://uefi.org/specifications/ACPI/6.4/, referenced 2021-11-30. -[2] Devicetree. http://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. - http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf, - referenced 2016-10-04. +[dsd-guide] DSD Guide. + https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc, referenced + 2021-11-30. -[5] Hierarchical Data Extension UUID For _DSD. - http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf, - referenced 2016-10-04. +[dsd-rules] _DSD Device Properties Usage Rules. + Documentation/firmware-guide/acpi/DSD-properties-rules.rst -[6] Advanced Configuration and Power Interface Specification. - http://www.uefi.org/sites/default/files/resources/ACPI_6_1.pdf, - referenced 2016-10-04. - -[7] _DSD Device Properties Usage Rules. - :doc:`../DSD-properties-rules` +[graph-bindings] Common bindings for device graphs (Devicetree). + https://github.com/devicetree-org/dt-schema/blob/main/schemas/graph.yaml, + referenced 2021-11-30. diff --git a/Documentation/firmware-guide/acpi/dsd/leds.rst b/Documentation/firmware-guide/acpi/dsd/leds.rst index 946efe2b2936..a97cd07d49be 100644 --- a/Documentation/firmware-guide/acpi/dsd/leds.rst +++ b/Documentation/firmware-guide/acpi/dsd/leds.rst @@ -5,19 +5,15 @@ 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 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. -Referring to LEDs in Device tree is documented in [4], in "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 -references are limited to device nodes only [2]. For this reason using the same -mechanism on ACPI is not possible. A mechanism to refer to non-device ACPI nodes -is documented in [7]. +Referring to LEDs in Device tree is documented in [video-interfaces], in +"flash-leds" property documentation. In short, LEDs are directly referred to by +using phandles. ACPI allows (as does DT) using integer arguments after the reference. A combination of the LED driver device reference and an integer argument, @@ -73,7 +69,7 @@ omitted. :: Package () { Package () { "flash-leds", - Package () { ^LED, "led@0", ^LED, "led@1" }, + Package () { "^LED.LED0", "^LED.LED1" }, } } }) @@ -90,22 +86,17 @@ where References ========== -[1] Device tree. <URL:http://www.devicetree.org>, referenced 2019-02-21. - -[2] Advanced Configuration and Power Interface Specification. - <URL:https://uefi.org/sites/default/files/resources/ACPI_6_3_final_Jan30.pdf>, - referenced 2019-02-21. +[acpi] Advanced Configuration and Power Interface Specification. + https://uefi.org/specifications/ACPI/6.4/, referenced 2021-11-30. -[3] Documentation/devicetree/bindings/leds/common.txt +[data-node-ref] Documentation/firmware-guide/acpi/dsd/data-node-references.rst -[4] Documentation/devicetree/bindings/media/video-interfaces.txt +[devicetree] Devicetree. https://www.devicetree.org, referenced 2019-02-21. -[5] Device Properties UUID For _DSD. - <URL:http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>, - referenced 2019-02-21. +[dsd-guide] DSD Guide. + https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc, referenced + 2021-11-30. -[6] Hierarchical Data Extension UUID For _DSD. - <URL:http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>, - referenced 2019-02-21. +[leds] Documentation/devicetree/bindings/leds/common.yaml -[7] Documentation/firmware-guide/acpi/dsd/data-node-references.rst +[video-interfaces] Documentation/devicetree/bindings/media/video-interfaces.yaml diff --git a/Documentation/firmware-guide/acpi/dsd/phy.rst b/Documentation/firmware-guide/acpi/dsd/phy.rst new file mode 100644 index 000000000000..673ac374f92a --- /dev/null +++ b/Documentation/firmware-guide/acpi/dsd/phy.rst @@ -0,0 +1,201 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================= +MDIO bus and PHYs in ACPI +========================= + +The PHYs on an MDIO bus [phy] are probed and registered using +fwnode_mdiobus_register_phy(). + +Later, for connecting these PHYs to their respective MACs, the PHYs registered +on the MDIO bus have to be referenced. + +This document introduces two _DSD properties that are to be used +for connecting PHYs on the MDIO bus [dsd-properties-rules] to the MAC layer. + +These properties are defined in accordance with the "Device +Properties UUID For _DSD" [dsd-guide] document and the +daffd814-6eba-4d8c-8a91-bc9bbf4aa301 UUID must be used in the Device +Data Descriptors containing them. + +phy-handle +---------- +For each MAC node, a device property "phy-handle" is used to reference +the PHY that is registered on an MDIO bus. This is mandatory for +network interfaces that have PHYs connected to MAC via MDIO bus. + +During the MDIO bus driver initialization, PHYs on this bus are probed +using the _ADR object as shown below and are registered on the MDIO bus. + +.. code-block:: none + + Scope(\_SB.MDI0) + { + Device(PHY1) { + Name (_ADR, 0x1) + } // end of PHY1 + + Device(PHY2) { + Name (_ADR, 0x2) + } // end of PHY2 + } + +Later, during the MAC driver initialization, the registered PHY devices +have to be retrieved from the MDIO bus. For this, the MAC driver needs +references to the previously registered PHYs which are provided +as device object references (e.g. \_SB.MDI0.PHY1). + +phy-mode +-------- +The "phy-mode" _DSD property is used to describe the connection to +the PHY. The valid values for "phy-mode" are defined in [ethernet-controller]. + +managed +------- +Optional property, which specifies the PHY management type. +The valid values for "managed" are defined in [ethernet-controller]. + +fixed-link +---------- +The "fixed-link" is described by a data-only subnode of the +MAC port, which is linked in the _DSD package via +hierarchical data extension (UUID dbb8e3e6-5886-4ba6-8795-1319f52a966b +in accordance with [dsd-guide] "_DSD Implementation Guide" document). +The subnode should comprise a required property ("speed") and +possibly the optional ones - complete list of parameters and +their values are specified in [ethernet-controller]. + +The following ASL example illustrates the usage of these properties. + +DSDT entry for MDIO node +------------------------ + +The MDIO bus has an SoC component (MDIO controller) and a platform +component (PHYs on the MDIO bus). + +a) Silicon Component +This node describes the MDIO controller, MDI0 +--------------------------------------------- + +.. code-block:: none + + Scope(_SB) + { + Device(MDI0) { + Name(_HID, "NXP0006") + Name(_CCA, 1) + Name(_UID, 0) + Name(_CRS, ResourceTemplate() { + Memory32Fixed(ReadWrite, MDI0_BASE, MDI_LEN) + Interrupt(ResourceConsumer, Level, ActiveHigh, Shared) + { + MDI0_IT + } + }) // end of _CRS for MDI0 + } // end of MDI0 + } + +b) Platform Component +The PHY1 and PHY2 nodes represent the PHYs connected to MDIO bus MDI0 +--------------------------------------------------------------------- + +.. code-block:: none + + Scope(\_SB.MDI0) + { + Device(PHY1) { + Name (_ADR, 0x1) + } // end of PHY1 + + Device(PHY2) { + Name (_ADR, 0x2) + } // end of PHY2 + } + +DSDT entries representing MAC nodes +----------------------------------- + +Below are the MAC nodes where PHY nodes are referenced. +phy-mode and phy-handle are used as explained earlier. +------------------------------------------------------ + +.. code-block:: none + + Scope(\_SB.MCE0.PR17) + { + Name (_DSD, Package () { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package (2) {"phy-mode", "rgmii-id"}, + Package (2) {"phy-handle", \_SB.MDI0.PHY1} + } + }) + } + + Scope(\_SB.MCE0.PR18) + { + Name (_DSD, Package () { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package (2) {"phy-mode", "rgmii-id"}, + Package (2) {"phy-handle", \_SB.MDI0.PHY2}} + } + }) + } + +MAC node example where "managed" property is specified. +------------------------------------------------------- + +.. code-block:: none + + Scope(\_SB.PP21.ETH0) + { + Name (_DSD, Package () { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package () {"phy-mode", "sgmii"}, + Package () {"managed", "in-band-status"} + } + }) + } + +MAC node example with a "fixed-link" subnode. +--------------------------------------------- + +.. code-block:: none + + Scope(\_SB.PP21.ETH1) + { + Name (_DSD, Package () { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package () {"phy-mode", "sgmii"}, + }, + ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), + Package () { + Package () {"fixed-link", "LNK0"} + } + }) + Name (LNK0, Package(){ // Data-only subnode of port + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package () {"speed", 1000}, + Package () {"full-duplex", 1} + } + }) + } + +References +========== + +[phy] Documentation/networking/phy.rst + +[dsd-properties-rules] + Documentation/firmware-guide/acpi/DSD-properties-rules.rst + +[ethernet-controller] + Documentation/devicetree/bindings/net/ethernet-controller.yaml + +[dsd-guide] DSD Guide. + https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc, referenced + 2021-11-30. |