Hi Rafael, Thanks for the review. On Mon, Jul 09, 2018 at 11:52:39AM +0200, Rafael J. Wysocki wrote: > On Wednesday, June 27, 2018 11:37:20 AM CEST Sakari Ailus wrote: > > Add generic documentation on how to refer to hierarchical data nodes. 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 <sakari.ailus@xxxxxxxxxxxxxxx> > > --- > > Documentation/acpi/dsd/data-node-references.txt | 18 ++++++++++++++++++ > > 1 file changed, 18 insertions(+) > > create mode 100644 Documentation/acpi/dsd/data-node-references.txt > > > > diff --git a/Documentation/acpi/dsd/data-node-references.txt b/Documentation/acpi/dsd/data-node-references.txt > > new file mode 100644 > > index 0000000000000..2f60eda811163 > > --- /dev/null > > +++ b/Documentation/acpi/dsd/data-node-references.txt > > @@ -0,0 +1,18 @@ > > It would be good to have some authorship/copyright info here. Added. > > > +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. > > + > > +The references consist of the device node followed by the first package entries > > +of the hierarchical data node extensions from the first child node of the device > > +node until the referred data extension node. > > The above is not particularly clear IMO. > > First off, it is not clear what "device node" means in there. I guess you mean > a pathname or similar. Also the "first package entries" phrase is not clear at > all. What package do you mean in the first place? Right. The device node here means the ACPI node that corresponds to struct device in Linux. Perhaps "device object" would be more appropriate in ACPI context? Reading the hierarchical data extension spec, it would seem these would better be referred to as "key" and "target" than first or second package list entries. How about that? > > > + > > +The first package list entry in the hierarchical data node shall consist of the > > +name of the node, "@" character and the number of the node. If the node has no > > +numerical value, then the number shall be omitted. The first package list > > +entries of the hierarchical data nodes shall be unique directly under the parent > > +of the node, i.e. there may not be two hierarchical data extensions that have > > +the same first package entry under any node (device or hierarchical data > > +extension). > > > > It would be good to give an example here. The graph data structure documentation is added in later patches and a reference is added to this file in the last patch of the set. -- Kind regards, Sakari Ailus sakari.ailus@xxxxxxxxxxxxxxx -- To unsubscribe from this list: send the line "unsubscribe linux-acpi" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
