[RFC PATCH 1/1] of: expand overlay documentation

[frowand . list]

From: Frank Rowand <frank.rowand@xxxxxxxx>

The overlay documentation is incomplete, start adding more content.

Signed-off-by: Frank Rowand <frank.rowand@xxxxxxxx>
---

I have not done a build and have not verified the formatting.

This is a first stab to try to capture some of the content that I
think should be added to the overlay documentation.  I wanted to
give it some exposure instead of letting it languish outside of
public view.

 Documentation/devicetree/overlay-notes.rst | 142 +++++++++++++++++++--
 1 file changed, 128 insertions(+), 14 deletions(-)

diff --git a/Documentation/devicetree/overlay-notes.rst b/Documentation/devicetree/overlay-notes.rst
index e139f22b363e..ac98923bf256 100644
--- a/Documentation/devicetree/overlay-notes.rst
+++ b/Documentation/devicetree/overlay-notes.rst
@@ -4,18 +4,117 @@
 Devicetree Overlay Notes
 ========================
 
-This document describes the implementation of the in-kernel
+This document provides information about device tree overlays.  This includes
+both (1) applying the overlay to the base device tree blob before providing the
+device tree blob to the kernel and (2) applying overlays to the base device
+tree after the kernel has booted.
+
+Impact on both pre-boot and post-boot apply
+-------------------------------------------
+
+The base devicetree is typically compiled by scripts/dtc with the "--symbols"
+or "-@' option if an overlay will be applied to the base devicetree.  This
+results in a larger device tree blob that contains symbolic information that
+can be used when applying an overlay blob.  The size of the symbolic
+information can be modest or very large, depending on the content of the
+base device tree source.
+
+The device tree compiler processing of duplicate or conflicting source items
+is very different than C compilers.  When an item occurs in more than one
+location of the source then the final one encountered replaces any previous
+occurences.  This provides a flexible ability to combine multiple include
+files in various configurations to create device tree blobs that describe
+similar but differing systems.  The downside of this flexibility is that it
+can be difficult to determine exactly which location in which source file
+results in an item in the compiled device tree blob.  The "--annotate", "-T",
+and "-T -T" were added to the scripts/dtc compiler to provide information
+about which particular source location describes each item in the compiled
+output.  These options are only useful when combined with "-O dts" or
+"--out-format dts".  There is no analogous option for scripts/fdtoverlay,
+so the location of the source definition of any specific item after applying
+an overlay to a base device tree blob is not available.
+
+A method of generating the --annotate information for one or more overlays
+applied to a base device tree that might work is:
+::
+   ---- base.dts
+   #include base.dtsi
+
+   ---- base.dtsi
+   /* the actual source of the base dts */
+
+   ---- overlay.dts
+   /plugin/
+   #include overlay.dtsi
+
+   ---- overlay.dtsi
+   /* the actual source of the overlay dts */
+
+   ---- base_and_overlay.dts
+   #include base.dtsi
+   #include overlay.dtsi
+
+   To generate the annotated device tree, use the command:
+      scripts/dtc --annotate -O dts base_and_overlay.dts
+
+The downside of this method is that a unique base_and_overlay.dts is required
+for each combination of a base device tree and the various combinations of
+overlays that may be applied to the base device tree.  This could result
+in a large number of base_and_overlay.dts files in the kernel source tree.
+It is likely that each person who desires to debug the contents of overlays
+applied to a base device tree would create the appropriate base_and_overlay.dts
+file in the own development environment instead of maintaining them in the
+kernel source tree.
+
+There is no guarantee that this method would generate a device tree
+equivalent to a device tree created by scripts/fdtoverlay or a device tree
+created post boot by applying an overlay because the overlay apply process
+may implement different rules or restrictions than scripts/dtc does.
+
+Pre-boot overlay apply
+-------------------------------------------
+
+One or more overlays may be applied to a base device tree by
+scripts/fdtoverlay.  The resulting output DT blob can be provided to the
+kernel for booting.
+
+This method is supported and is strongly encouraged.
+
+
+Post-boot overlay apply
+-------------------------------------------
+
+Run time overlay apply and run time overlay remove from user space are
+not supported in the mainline kernel. There are out of tree patches to
+implement this feature via an overlay manager. The overlay manager is used
+successfully by many users for specific overlays on specific boards with
+specific environments and use cases. However, there are many issues with
+the Linux kernel overlay implementation due to incomplete and incorrect
+code. The overlay manager has not been accepted in mainline due to these
+issues. Once these issues are resolved, it is expected that some method
+of run time overlay apply and overlay removal from user space will be
+supported by the Linux kernel.
+
+For a more detailed description of kernel issues and the progress of
+resolving the issues, see
+::
+   https://elinux.org/Frank%27s_Evolving_Overlay_Thoughts
+
+This method is only partially implemented, is fragile, and is strongly
+discouraged.  The resulting system may or may not function as expected
+and is not supported.  Fixes to issues resulting from this method may
+or may not be accepted in the device tree kernel source code (eg in
+drivers/of/).
+
+This section describes the implementation of the in-kernel
 device tree overlay functionality residing in drivers/of/overlay.c and is a
 companion document to Documentation/devicetree/dynamic-resolution-notes.rst[1]
 
-How overlays work
------------------
-
 A Devicetree's overlay purpose is to modify the kernel's live tree, and
 have the modification affecting the state of the kernel in a way that
 is reflecting the changes.
 Since the kernel mainly deals with devices, any new device node that result
-in an active device should have it created while if the device node is either
+in an active device should have it created.  If the device node is either
 disabled or removed all together, the affected device should be deregistered.
 
 Lets take an example where we have a foo board with the following base tree::
@@ -104,22 +203,20 @@ The above bar.dts example modified to use target path syntax is::
 
 
 Overlay in-kernel API
---------------------------------
-
-The API is quite easy to use.
+-------------------------------------------
 
 1) Call of_overlay_fdt_apply() to create and apply an overlay changeset. The
    return value is an error or a cookie identifying this overlay.
 
 2) Call of_overlay_remove() to remove and cleanup the overlay changeset
-   previously created via the call to of_overlay_fdt_apply(). Removal of an
-   overlay changeset that is stacked by another will not be permitted.
+   previously created via the call to of_overlay_fdt_apply(). Removal of
+   overlay changesets must occur in the opposite order of apply (the
+   most recently applied overlay changeset must be removed first).
 
-Finally, if you need to remove all overlays in one-go, just call
-of_overlay_remove_all() which will remove every single one in the correct
-order.
+If you need to remove all overlays in one-go, just call of_overlay_remove_all()
+which will remove every single overlay changeset in the correct order.
 
-There is the option to register notifiers that get called on
+There is an option to register notifiers that get called on
 overlay operations. See of_overlay_notifier_register/unregister and
 enum of_overlay_notify_action for details.
 
@@ -142,9 +239,26 @@ Any other code that retains a pointer to the overlay nodes or data is
 considered to be a bug because after removing the overlay the pointer
 will refer to freed memory.
 
+All overlay related notifiers are subject to especially cautious review.
+
 Users of overlays must be especially aware of the overall operations that
 occur on the system to ensure that other kernel code does not retain any
 pointers to the overlay nodes or data.  Any example of an inadvertent use
 of such pointers is if a driver or subsystem module is loaded after an
 overlay has been applied, and the driver or subsystem scans the entire
 devicetree or a large portion of it, including the overlay nodes.
+
+Post-boot overlay apply constraints
+-------------------------------------------
+
+The post-boot overlay apply code constrains what a valid overlay may contain.
+
+This is a very incomplete list of such constraints.
+
+::
+   - An overlay may not replace an existing node or property.  A special
+     exception is that the value of the "status" property can be changed
+     to "ok".  Whether this change will be properly detected and processed
+     depends upon the relevant subsystem(s) and driver(s).
+
+   - An overlay may not add a property to an existing node.
-- 
Frank Rowand <frank.rowand@xxxxxxxx>