From 5ecba3ba40cebd5e4340f6fd422683bde773689c Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Tue, 6 Sep 2022 20:27:01 -0600 Subject: [PATCH] dm: core: Document the livetree structures properly Clarify the data structure so it is easier for people to understand, particularly the corner cases. Signed-off-by: Simon Glass --- include/dm/of.h | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/include/dm/of.h b/include/dm/of.h index 9c9065b793..fce7cef0ff 100644 --- a/include/dm/of.h +++ b/include/dm/of.h @@ -31,10 +31,21 @@ struct property { /** * struct device_node: Device tree node * - * @name: Node name + * The top of this tree is typically gd->of_root which points to the root node. + * + * The head of the list of children for the root node (and any other node) is + * in @child, with @sibling providing a link to the next child. + * + * Each child has a pointer to its parent in @parent. + * + * A node may have properties in which case the head of the list of properties + * @properties pointers to the first one, with struct property->@next pointing + * to the next one. + * + * @name: Node name, "" for the root node * @type: Node type (value of device_type property) or "" if none * @phandle: Phandle value of this none, or 0 if none - * @full_name: Full path to node, e.g. "/bus@1/spi@1100" + * @full_name: Full path to node, e.g. "/bus@1/spi@1100" ("/" for the root node) * @properties: Pointer to head of list of properties, or NULL if none * @parent: Pointer to parent node, or NULL if this is the root node * @child: Pointer to head of child node list, or NULL if no children -- 2.39.5