Documentation/devicetree/overlay-notes.rst

1 .. SPDX-License-Identifier: GPL-2.0
7 This document describes the implementation of the in-kernel
9 companion document to Documentation/devicetree/dynamic-resolution-notes.rst[1]
12 -----------------
14 A Devicetree's overlay purpose is to modify the kernel's live tree, and
23     ---- foo.dts ---------------------------------------------------------------
25 	/dts-v1/;
39     ---- foo.dts ---------------------------------------------------------------
44     ---- bar.dts - overlay target location by label ----------------------------
45 	/dts-v1/;
48 		/* bar peripheral */
54     ---- bar.dts ---------------------------------------------------------------
58     ---- foo+bar.dts -----------------------------------------------------------
59 	/* FOO platform + bar peripheral */
72 			/* bar peripheral */
79     ---- foo+bar.dts -----------------------------------------------------------
85 If the base DT was not compiled with the -@ option then the "&ocp" label
86 will not be available to resolve the overlay node(s) to the proper location
88 location by label syntax is preferred because the overlay can be applied to
91 The above bar.dts example modified to use target path syntax is::
93     ---- bar.dts - overlay target location by explicit path --------------------
94 	/dts-v1/;
97 		/* bar peripheral */
103     ---- bar.dts ---------------------------------------------------------------
106 Overlay in-kernel API
107 --------------------------------
109 The API is quite easy to use.
111 1) Call of_overlay_fdt_apply() to create and apply an overlay changeset. The
114 2) Call of_overlay_remove() to remove and cleanup the overlay changeset
115    previously created via the call to of_overlay_fdt_apply(). Removal of an
118 Finally, if you need to remove all overlays in one-go, just call
122 There is the option to register notifiers that get called on
127 OF_OVERLAY_PRE_REMOVE may store pointers to a device tree node in the overlay
129 for OF_OVERLAY_POST_REMOVE.  The memory containing the overlay will be
131 memory will be kfree()ed even if the notifier for OF_OVERLAY_POST_REMOVE
136 are not allowed to store pointers to a device tree node in the overlay
138 remaining active when the memory containing the overlay is freed as a result
141 Any other code that retains a pointer to the overlay nodes or data is
142 considered to be a bug because after removing the overlay the pointer
143 will refer to freed memory.
146 occur on the system to ensure that other kernel code does not retain any
147 pointers to the overlay nodes or data.  Any example of an inadvertent use