From: Mauro Carvalho Chehab Date: Wed, 15 Apr 2020 14:45:22 +0000 (+0200) Subject: docs: dt: convert overlay-notes.txt to ReST format X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=642e6e5ce03e5b02d658e87d6c21d881b1ce8f62;p=linux.git docs: dt: convert overlay-notes.txt to ReST format - Add a SPDX header; - Adjust document title; - Some whitespace fixes and new line breaks; - Mark literal blocks as such; - Add it to devicetree/index.rst. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Rob Herring --- diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst index 8b78e2c25e5a0..1c36bc19969b0 100644 --- a/Documentation/devicetree/index.rst +++ b/Documentation/devicetree/index.rst @@ -12,3 +12,4 @@ Open Firmware and Device Tree changesets dynamic-resolution-notes of_unittest + overlay-notes diff --git a/Documentation/devicetree/overlay-notes.rst b/Documentation/devicetree/overlay-notes.rst new file mode 100644 index 0000000000000..c67cc676bbd2d --- /dev/null +++ b/Documentation/devicetree/overlay-notes.rst @@ -0,0 +1,128 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================= +Device Tree Overlay Notes +========================= + +This document 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 Device Tree'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 +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:: + + ---- foo.dts --------------------------------------------------------------- + /* FOO platform */ + /dts-v1/; + / { + compatible = "corp,foo"; + + /* shared resources */ + res: res { + }; + + /* On chip peripherals */ + ocp: ocp { + /* peripherals that are always instantiated */ + peripheral1 { ... }; + }; + }; + ---- foo.dts --------------------------------------------------------------- + +The overlay bar.dts, +:: + + ---- bar.dts - overlay target location by label ---------------------------- + /dts-v1/; + /plugin/; + &ocp { + /* bar peripheral */ + bar { + compatible = "corp,bar"; + ... /* various properties and child nodes */ + }; + }; + ---- bar.dts --------------------------------------------------------------- + +when loaded (and resolved as described in [1]) should result in foo+bar.dts:: + + ---- foo+bar.dts ----------------------------------------------------------- + /* FOO platform + bar peripheral */ + / { + compatible = "corp,foo"; + + /* shared resources */ + res: res { + }; + + /* On chip peripherals */ + ocp: ocp { + /* peripherals that are always instantiated */ + peripheral1 { ... }; + + /* bar peripheral */ + bar { + compatible = "corp,bar"; + ... /* various properties and child nodes */ + }; + }; + }; + ---- foo+bar.dts ----------------------------------------------------------- + +As a result of the overlay, a new device node (bar) has been created +so a bar platform device will be registered and if a matching device driver +is loaded the device will be created as expected. + +If the base DT was not compiled with the -@ option then the "&ocp" label +will not be available to resolve the overlay node(s) to the proper location +in the base DT. In this case, the target path can be provided. The target +location by label syntax is preferred because the overlay can be applied to +any base DT containing the label, no matter where the label occurs in the DT. + +The above bar.dts example modified to use target path syntax is:: + + ---- bar.dts - overlay target location by explicit path -------------------- + /dts-v1/; + /plugin/; + &{/ocp} { + /* bar peripheral */ + bar { + compatible = "corp,bar"; + ... /* various properties and child nodes */ + } + }; + ---- bar.dts --------------------------------------------------------------- + + +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. + +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. + +In addition, there is the option to register notifiers that get called on +overlay operations. See of_overlay_notifier_register/unregister and +enum of_overlay_notify_action for details. + +Note that a notifier callback is not supposed to store pointers to a device +tree node or its content beyond OF_OVERLAY_POST_REMOVE corresponding to the +respective node it received. diff --git a/Documentation/devicetree/overlay-notes.txt b/Documentation/devicetree/overlay-notes.txt deleted file mode 100644 index b06ffcb8f0f8e..0000000000000 --- a/Documentation/devicetree/overlay-notes.txt +++ /dev/null @@ -1,124 +0,0 @@ -Device Tree Overlay Notes -------------------------- - -This document 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 Device Tree'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 -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: - ----- foo.dts ----------------------------------------------------------------- - /* FOO platform */ - /dts-v1/; - / { - compatible = "corp,foo"; - - /* shared resources */ - res: res { - }; - - /* On chip peripherals */ - ocp: ocp { - /* peripherals that are always instantiated */ - peripheral1 { ... }; - }; - }; ----- foo.dts ----------------------------------------------------------------- - -The overlay bar.dts, - ----- bar.dts - overlay target location by label ------------------------------ - /dts-v1/; - /plugin/; - &ocp { - /* bar peripheral */ - bar { - compatible = "corp,bar"; - ... /* various properties and child nodes */ - }; - }; ----- bar.dts ----------------------------------------------------------------- - -when loaded (and resolved as described in [1]) should result in foo+bar.dts - ----- foo+bar.dts ------------------------------------------------------------- - /* FOO platform + bar peripheral */ - / { - compatible = "corp,foo"; - - /* shared resources */ - res: res { - }; - - /* On chip peripherals */ - ocp: ocp { - /* peripherals that are always instantiated */ - peripheral1 { ... }; - - /* bar peripheral */ - bar { - compatible = "corp,bar"; - ... /* various properties and child nodes */ - }; - }; - }; ----- foo+bar.dts ------------------------------------------------------------- - -As a result of the overlay, a new device node (bar) has been created -so a bar platform device will be registered and if a matching device driver -is loaded the device will be created as expected. - -If the base DT was not compiled with the -@ option then the "&ocp" label -will not be available to resolve the overlay node(s) to the proper location -in the base DT. In this case, the target path can be provided. The target -location by label syntax is preferred because the overlay can be applied to -any base DT containing the label, no matter where the label occurs in the DT. - -The above bar.dts example modified to use target path syntax is: - ----- bar.dts - overlay target location by explicit path ---------------------- - /dts-v1/; - /plugin/; - &{/ocp} { - /* bar peripheral */ - bar { - compatible = "corp,bar"; - ... /* various properties and child nodes */ - } - }; ----- bar.dts ----------------------------------------------------------------- - - -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. - -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. - -In addition, there is the option to register notifiers that get called on -overlay operations. See of_overlay_notifier_register/unregister and -enum of_overlay_notify_action for details. - -Note that a notifier callback is not supposed to store pointers to a device -tree node or its content beyond OF_OVERLAY_POST_REMOVE corresponding to the -respective node it received. diff --git a/MAINTAINERS b/MAINTAINERS index 03a1abf0d6e95..ecf2082d592b7 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -12536,7 +12536,7 @@ M: Frank Rowand L: devicetree@vger.kernel.org S: Maintained F: Documentation/devicetree/dynamic-resolution-notes.rst -F: Documentation/devicetree/overlay-notes.txt +F: Documentation/devicetree/overlay-notes.rst F: drivers/of/overlay.c F: drivers/of/resolver.c K: of_overlay_notifier_