diff mbox series

[v2,13/45] dm: core: Document the livetree structures properly

Message ID 20220907022733.66423-14-sjg@chromium.org
State Accepted
Commit 5ecba3ba40cebd5e4340f6fd422683bde773689c
Delegated to: Tom Rini
Headers show
Series dm: core: Support multiple device trees in ofnode | expand

Commit Message

Simon Glass Sept. 7, 2022, 2:27 a.m. UTC
Clarify the data structure so it is easier for people to understand,
particularly the corner cases.

Signed-off-by: Simon Glass <sjg@chromium.org>
---

(no changes since v1)

 include/dm/of.h | 15 +++++++++++++--
 1 file changed, 13 insertions(+), 2 deletions(-)
diff mbox series

Patch

diff --git a/include/dm/of.h b/include/dm/of.h
index 9c9065b7932..fce7cef0ff6 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