From: Simon Glass <sjg@chromium.org>
Date: Wed, 7 Sep 2022 02:27:01 +0000 (-0600)
Subject: dm: core: Document the livetree structures properly
X-Git-Tag: v2025.01-rc5-pxa1908~1263^2^2~32
X-Git-Url: http://git.dujemihanovic.xyz/html/index.html?a=commitdiff_plain;h=5ecba3ba40cebd5e4340f6fd422683bde773689c;p=u-boot.git

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 <sjg@chromium.org>
---

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 "<NULL>" 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