On Tue, Jul 17, 2018 at 12:21:44PM +0200, Rafael J. Wysocki wrote: > 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? It demonstrates the use of the referencing mechanism as an example would do. Anyway, reading the documentation again, I agree a more simple example would be beneficial here. I'll add that for v2. -- 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
