On Tue, Jul 17, 2018 at 12:07 PM, Sakari Ailus <sakari.ailus@xxxxxxxxxxxxxxx> wrote: > 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? I think so. > 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? That would be better, yes. In any case, the exact meaning of all the terms used should be clear. >> >> > + >> > +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. I'm not sure how this is related to the example thing? Thanks, Rafael -- 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
