diff options
Diffstat (limited to 'Documentation/firmware-guide/acpi/dsd')
| -rw-r--r-- | Documentation/firmware-guide/acpi/dsd/data-node-references.rst | 31 | ||||
| -rw-r--r-- | Documentation/firmware-guide/acpi/dsd/graph.rst | 40 | ||||
| -rw-r--r-- | Documentation/firmware-guide/acpi/dsd/leds.rst | 107 | ||||
| -rw-r--r-- | Documentation/firmware-guide/acpi/dsd/phy.rst | 201 |
4 files changed, 343 insertions, 36 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..8d8b53e96bcf 100644 --- a/Documentation/firmware-guide/acpi/dsd/data-node-references.rst +++ b/Documentation/firmware-guide/acpi/dsd/data-node-references.rst @@ -5,7 +5,7 @@ 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. @@ -13,9 +13,9 @@ 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 +hierarchical data extension [dsd-guide] 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, @@ -33,7 +33,7 @@ extension key. 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 hierarchical data extension key "node@1" referring to the NOD1 object and lastly, a hierarchical data extension key "anothernode" referring to @@ -52,12 +52,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 +76,21 @@ 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", Package () { + ^DEV0, "node@1", "anothernode" + } + }, } }) } -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..b9dbfc73ed25 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 @@ -153,25 +154,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 new file mode 100644 index 000000000000..93db592c93c7 --- /dev/null +++ b/Documentation/firmware-guide/acpi/dsd/leds.rst @@ -0,0 +1,107 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> + +======================================== +Describing and referring to LEDs in ACPI +======================================== + +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. [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 [video-interfaces], 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 [devicetree], in +ACPI references are limited to device nodes only [acpi]. For this reason using +the same mechanism on ACPI is not possible. A mechanism to refer to non-device +ACPI nodes is documented in [data-node-ref]. + +ACPI allows (as does DT) using integer arguments after the reference. A +combination of the LED driver device reference and an integer argument, +referring to the "reg" property of the relevant LED, is used to identify +individual LEDs. The value of the "reg" property is a contract between the +firmware and software, it uniquely identifies the LED driver outputs. + +Under the LED driver device, The first hierarchical data extension package list +entry shall contain the string "led@" followed by the number of the LED, +followed by the referred object name. That object shall be named "LED" followed +by the number of the LED. + +Example +======= + +An ASL example of a camera sensor device and a LED driver device for two LEDs is +show below. Objects not relevant for LEDs or the references to them have been +omitted. :: + + Device (LED) + { + Name (_DSD, Package () { + ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), + Package () { + Package () { "led@0", LED0 }, + Package () { "led@1", LED1 }, + } + }) + Name (LED0, Package () { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package () { "reg", 0 }, + Package () { "flash-max-microamp", 1000000 }, + Package () { "flash-timeout-us", 200000 }, + Package () { "led-max-microamp", 100000 }, + Package () { "label", "white:flash" }, + } + }) + Name (LED1, Package () { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package () { "reg", 1 }, + Package () { "led-max-microamp", 10000 }, + Package () { "label", "red:indicator" }, + } + }) + } + + Device (SEN) + { + Name (_DSD, Package () { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package () { + "flash-leds", + Package () { ^LED, "led@0", ^LED, "led@1" }, + } + } + }) + } + +where +:: + + LED LED driver device + LED0 First LED + LED1 Second LED + SEN Camera sensor device (or another device the LED is related to) + +References +========== + +[acpi] Advanced Configuration and Power Interface Specification. + https://uefi.org/specifications/ACPI/6.4/, referenced 2021-11-30. + +[data-node-ref] Documentation/firmware-guide/acpi/dsd/data-node-references.rst + +[devicetree] Devicetree. https://www.devicetree.org, referenced 2019-02-21. + +[dsd-guide] DSD Guide. + https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc, referenced + 2021-11-30. + +[leds] Documentation/devicetree/bindings/leds/common.yaml + +[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. |