From b10134a3643dced57976f9346764144203cfb302 Mon Sep 17 00:00:00 2001 From: Sakari Ailus Date: Tue, 17 Jul 2018 17:19:13 +0300 Subject: ACPI: property: Document hierarchical data extension references Add documentation on how to refer to hierarchical data nodes in a generic way. This brings ACPI to feature parity with Device Tree in terms of being able to refer to any node in the tree. Signed-off-by: Sakari Ailus Signed-off-by: Rafael J. Wysocki --- Documentation/acpi/dsd/data-node-references.txt | 69 +++++++++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 Documentation/acpi/dsd/data-node-references.txt (limited to 'Documentation') diff --git a/Documentation/acpi/dsd/data-node-references.txt b/Documentation/acpi/dsd/data-node-references.txt new file mode 100644 index 000000000000..00c3b5fe1f2e --- /dev/null +++ b/Documentation/acpi/dsd/data-node-references.txt @@ -0,0 +1,69 @@ +Copyright (C) 2018 Intel Corporation +Author: Sakari Ailus + + +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. + +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" referring to the NODE object and + lastly, a hierarchical data extension key "anothernode" referring to the + ANOD object which is also the final target of the reference. + + Device (DEV0) + { + Name (_DSD, Package () { + ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), + Package () { + Package () { "node", NODE }, + } + }) + Name (NODE, 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", "anothernode" }, + } + }) + } + + +References +---------- + +[1] Hierarchical Data Extension UUID For _DSD. + , + referenced 2018-07-17. + +[2] Device Properties UUID For _DSD. + , + referenced 2016-10-04. -- cgit v1.2.3 From 2285e6d9f68912c786cfc46f798be42ef9800ae8 Mon Sep 17 00:00:00 2001 From: Sakari Ailus Date: Tue, 17 Jul 2018 17:19:17 +0300 Subject: ACPI: property: Document key numbering for hierarchical data extension refs As part of the hierarchical data extension key naming, introduce numbering scheme for the nodes that may be referred to using hierarchical data extension references. This allows iterating over particular kind of nodes recognised by the node name whilst allowing numbering the nodes, bringing ACPI to feature parity with DT in this respect. Signed-off-by: Sakari Ailus Signed-off-by: Rafael J. Wysocki --- Documentation/acpi/dsd/data-node-references.txt | 31 ++++++++++++++++++++----- 1 file changed, 25 insertions(+), 6 deletions(-) (limited to 'Documentation') diff --git a/Documentation/acpi/dsd/data-node-references.txt b/Documentation/acpi/dsd/data-node-references.txt index 00c3b5fe1f2e..6e9a5f925edd 100644 --- a/Documentation/acpi/dsd/data-node-references.txt +++ b/Documentation/acpi/dsd/data-node-references.txt @@ -15,24 +15,43 @@ 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" referring to the NODE object and - lastly, a hierarchical data extension key "anothernode" referring to the - ANOD object which is also the final target of the reference. + 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", NODE }, + Package () { "node@0", NOD0 }, + Package () { "node@1", NOD1 }, + } + }) + Name (NOD0, Package() { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package () { "random-property", 3 }, } }) - Name (NODE, Package() { + Name (NOD1, Package() { ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), Package () { Package () { "anothernode", ANOD }, @@ -51,7 +70,7 @@ Example Name (_DSD, Package () { ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), Package () { - Package () { "reference", ^DEV0, "node", "anothernode" }, + Package () { "reference", ^DEV0, "node@1", "anothernode" }, } }) } -- cgit v1.2.3 From e4702b2ca7b4aa81cc067c1b8e7aaa1350239fa2 Mon Sep 17 00:00:00 2001 From: Sakari Ailus Date: Tue, 17 Jul 2018 17:19:18 +0300 Subject: ACPI: property: Update documentation for hierarchical data extension 1.1 Hierarchical data extension 1.1 allows using references as the second entries of the hierearchical data extension packages. Update the references and the examples. The quotes are left in documentation for clarity. Signed-off-by: Sakari Ailus Signed-off-by: Rafael J. Wysocki --- Documentation/acpi/dsd/graph.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'Documentation') diff --git a/Documentation/acpi/dsd/graph.txt b/Documentation/acpi/dsd/graph.txt index ac09e3138b79..591c47509c63 100644 --- a/Documentation/acpi/dsd/graph.txt +++ b/Documentation/acpi/dsd/graph.txt @@ -76,7 +76,7 @@ A simple example of this is show below: }, ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), Package () { - Package () { "port0", "PRT0" }, + Package () { "port0", PRT0 }, } }) Name (PRT0, Package() { @@ -86,7 +86,7 @@ A simple example of this is show below: }, ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), Package () { - Package () { "endpoint0", "EP00" }, + Package () { "endpoint0", EP00 }, } }) Name (EP00, Package() { @@ -106,7 +106,7 @@ A simple example of this is show below: Name (_DSD, Package () { ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), Package () { - Package () { "port4", "PRT4" }, + Package () { "port4", PRT4 }, } }) @@ -117,7 +117,7 @@ A simple example of this is show below: }, ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), Package () { - Package () { "endpoint0", "EP40" }, + Package () { "endpoint0", EP40 }, } }) @@ -151,7 +151,7 @@ References referenced 2016-10-04. [5] Hierarchical Data Extension UUID For _DSD. - , + , referenced 2016-10-04. [6] Advanced Configuration and Power Interface Specification. -- cgit v1.2.3 From e58b1c6a9422b97b30838e77b7d1d2bbed121e96 Mon Sep 17 00:00:00 2001 From: Sakari Ailus Date: Tue, 17 Jul 2018 17:19:19 +0300 Subject: ACPI: property: graph: Fix graph documentation Address a few issues in the ACPI _DSD properties graph documentation: - the extension for port nodes is a data extension (and not property extension), - clean up language in port hierarchical data extension definition, - add examples of port and endpoint packages, - port property value is the number of the "port" and not the number of the "port node", - remove word "individual" from endpoint data node description, it was redundant, - remove the extra "The" in the endpoint property description, - refer to hierarchical data extension keys and targets instead of first and second package list entries. Signed-off-by: Sakari Ailus Signed-off-by: Rafael J. Wysocki --- Documentation/acpi/dsd/graph.txt | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-) (limited to 'Documentation') diff --git a/Documentation/acpi/dsd/graph.txt b/Documentation/acpi/dsd/graph.txt index 591c47509c63..0b007fceda0e 100644 --- a/Documentation/acpi/dsd/graph.txt +++ b/Documentation/acpi/dsd/graph.txt @@ -36,20 +36,24 @@ 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. +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 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() { "port4", 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 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() { "endpoint0", EP40 } 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 +which is the number of the port. 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. -- cgit v1.2.3 From e49363e96fd2ee3fd5259fd2a6f9050cb4af82c8 Mon Sep 17 00:00:00 2001 From: Sakari Ailus Date: Tue, 17 Jul 2018 17:19:20 +0300 Subject: ACPI: property: graph: Improve graph documentation for port/ep numbering Document that if a port has a single endpoint only, its value shall be zero. Similarly, if a device object only has a single port, its value shlla be zero. Signed-off-by: Sakari Ailus Signed-off-by: Rafael J. Wysocki --- Documentation/acpi/dsd/graph.txt | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/acpi/dsd/graph.txt b/Documentation/acpi/dsd/graph.txt index 0b007fceda0e..3131f457882b 100644 --- a/Documentation/acpi/dsd/graph.txt +++ b/Documentation/acpi/dsd/graph.txt @@ -55,7 +55,10 @@ endpoint. An example of such a package would be: 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 "endpoint". Port numbers must be unique within a -device and endpoint numbers must be unique within a port. +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 -- cgit v1.2.3 From a4138e7c12287268348cc2dcad414a62c515d77a Mon Sep 17 00:00:00 2001 From: Sakari Ailus Date: Tue, 17 Jul 2018 17:19:21 +0300 Subject: ACPI: property: graph: Update graph documentation to use generic references Instead of port and endpoint properties for representing ports and endpoints, use the keys of the hierarchical data extension references when referring to the port and endpoint nodes. Additionally, use "reg" properties as in Device Tree to specify the number of the port or the endpoint. The keys of the port nodes begin with "port" and the keys of the endpoint nodes begin with "endpoint", both followed by "@" character and the number of the port or the endpoint. These changes have the advantage that no ACPI specific properties need to be added to refer to non-device nodes. Additionally, using the name of the node instead of an integer property inside the node is easier to parse in code and easier for humans to understand. Signed-off-by: Sakari Ailus Signed-off-by: Rafael J. Wysocki --- Documentation/acpi/dsd/data-node-references.txt | 1 + Documentation/acpi/dsd/graph.txt | 65 +++++++++++++------------ 2 files changed, 36 insertions(+), 30 deletions(-) (limited to 'Documentation') diff --git a/Documentation/acpi/dsd/data-node-references.txt b/Documentation/acpi/dsd/data-node-references.txt index 6e9a5f925edd..c3871565c8cf 100644 --- a/Documentation/acpi/dsd/data-node-references.txt +++ b/Documentation/acpi/dsd/data-node-references.txt @@ -75,6 +75,7 @@ Example }) } +Please also see a graph example in graph.txt . References ---------- diff --git a/Documentation/acpi/dsd/graph.txt b/Documentation/acpi/dsd/graph.txt index 3131f457882b..b9ce910781dc 100644 --- a/Documentation/acpi/dsd/graph.txt +++ b/Documentation/acpi/dsd/graph.txt @@ -38,34 +38,39 @@ 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 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() { "port4", PRT4 } + 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 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: +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() { "endpoint0", EP40 } + 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 "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. +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. @@ -83,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" } }, } }) } @@ -113,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" } }, } }) } -- cgit v1.2.3