A number of fairly straightforward grammatical fixes and minor updates to the devicetree docs. Signed-off-by: Robert P. J. Day <rpjday@xxxxxxxxxxxxxx> --- there's certainly a lot more that can be tidied up in that directory, but i'll start with the easy stuff if that's all right. diff --git a/Documentation/devicetree/00-INDEX b/Documentation/devicetree/00-INDEX index 8c4102c..141c43a31 100644 --- a/Documentation/devicetree/00-INDEX +++ b/Documentation/devicetree/00-INDEX @@ -7,6 +7,14 @@ https://lists.ozlabs.org/listinfo/devicetree-discuss 00-INDEX - this file booting-without-of.txt - - Booting Linux without Open Firmware, describes history and format of device trees. + - Booting Linux without Open Firmware, describes history and format of device trees +changesets.txt + - How to apply DT changesets to the live tree atomically +dynamic-resolution-notes.txt + - The implementation of the in-kernel DT dynamic resolver +of_unittest.txt + - How test data is attached to the live tree dynamically +overlay-notes.txt + - Implementation of the in-kernel DT overlay functionality usage-model.txt - - How Linux uses DT and what DT aims to solve. \ No newline at end of file + - How Linux uses DT and what DT aims to solve diff --git a/Documentation/devicetree/changesets.txt b/Documentation/devicetree/changesets.txt index 935ba5a..e200e7a 100644 --- a/Documentation/devicetree/changesets.txt +++ b/Documentation/devicetree/changesets.txt @@ -1,37 +1,41 @@ -A DT changeset is a method which allows one to apply changes -in the live tree in such a way that either the full set of changes -will be applied, or none of them will be. If an error occurs partway -through applying the changeset, then the tree will be rolled back to the -previous state. A changeset can also be removed after it has been -applied. +A DT changeset is a method which allows one to apply changes in the +live tree in such a way that either the full set of changes will be +applied, or none of them will be. If an error occurs partway through +applying the changeset, the tree will be rolled back to the previous +state. A changeset can also be removed after it has been applied. When a changeset is applied, all of the changes get applied to the tree -at once before emitting OF_RECONFIG notifiers. This is so that the -receiver sees a complete and consistent state of the tree when it -receives the notifier. +at once before emitting OF_RECONFIG_* notifiers. This is so the receiver +sees a complete and consistent state of the tree when it receives the +notifier. -The sequence of a changeset is as follows. +The sequence of applying a changeset is as follows: 1. of_changeset_init() - initializes a changeset -2. A number of DT tree change calls, of_changeset_attach_node(), -of_changeset_detach_node(), of_changeset_add_property(), -of_changeset_remove_property, of_changeset_update_property() to prepare -a set of changes. No changes to the active tree are made at this point. -All the change operations are recorded in the of_changeset 'entries' -list. +2. A number of DT tree change calls: + + * of_changeset_attach_node() + * of_changeset_detach_node() + * of_changeset_add_property() + * of_changeset_remove_property() + * of_changeset_update_property() + +to prepare a set of changes. No changes to the active tree are made at +this point. All the change operations are recorded in the of_changeset +'entries' list. 3. mutex_lock(of_mutex) - starts a changeset; The global of_mutex ensures there can only be one editor at a time. 4. of_changeset_apply() - Apply the changes to the tree. Either the -entire changeset will get applied, or if there is an error the tree will -be restored to the previous state +entire changeset will get applied or, if there is an error, the tree will +be restored to the previous state. -5. mutex_unlock(of_mutex) - All operations complete, release the mutex +5. mutex_unlock(of_mutex) - All operations complete, release the mutex. If a successfully applied changeset needs to be removed, it can be done -with the following sequence. +with the following sequence: 1. mutex_lock(of_mutex) diff --git a/Documentation/devicetree/dynamic-resolution-notes.txt b/Documentation/devicetree/dynamic-resolution-notes.txt index 083d232..8294ff0 100644 --- a/Documentation/devicetree/dynamic-resolution-notes.txt +++ b/Documentation/devicetree/dynamic-resolution-notes.txt @@ -2,17 +2,16 @@ Device Tree Dynamic Resolver Notes ---------------------------------- This document describes the implementation of the in-kernel -Device Tree resolver, residing in drivers/of/resolver.c and is a -companion document to Documentation/devicetree/dt-object-internal.txt[1] +Device Tree resolver, residing in drivers/of/resolver.c. How the resolver works ---------------------- -The resolver is given as an input an arbitrary tree compiled with the +The resolver is given, as input, an arbitrary tree compiled with the proper dtc option and having a /plugin/ tag. This generates the -appropriate __fixups__ & __local_fixups__ nodes as described in [1]. +appropriate __fixups__ & __local_fixups__ nodes. -In sequence the resolver works by the following steps: +In sequence, the resolver runs the following steps: 1. Get the maximum device tree phandle value from the live tree + 1. 2. Adjust all the local phandles of the tree to resolve by that amount. diff --git a/Documentation/devicetree/overlay-notes.txt b/Documentation/devicetree/overlay-notes.txt index d418a6c..0eb830d 100644 --- a/Documentation/devicetree/overlay-notes.txt +++ b/Documentation/devicetree/overlay-notes.txt @@ -1,23 +1,21 @@ 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/dt-object-internal.txt[1] & -Documentation/devicetree/dynamic-resolution-notes.txt[2] +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.txt[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 +A Device Tree's overlay purpose is to modify the kernel's live tree, +so that the new state of the kernel reflects those changes. + +Since the kernel mainly deals with devices, any new device node that results 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 -which is taken from [1]. +Lets take an example where we have a foo board with the following base tree: ---- foo.dts ----------------------------------------------------------------- /* FOO platform */ @@ -85,7 +83,7 @@ so a bar platform device will be registered and if a matching device driver is loaded the device will be created as expected. Overlay in-kernel API --------------------------------- +--------------------- The API is quite easy to use. @@ -96,9 +94,8 @@ is a cookie identifying this overlay. created via the call to of_overlay_create(). Removal of an overlay that is stacked by another will not be permitted. -Finally, if you need to remove all overlays in one-go, just call -of_overlay_destroy_all() which will remove every single one in the correct -order. +Finally, if you need to remove all overlays in one go, just call +of_overlay_destroy_all() which removes all overlays in the correct order. Overlay DTS Format ------------------ rday -- ======================================================================== Robert P. J. Day Ottawa, Ontario, CANADA http://crashcourse.ca Twitter: http://twitter.com/rpjday LinkedIn: http://ca.linkedin.com/in/rpjday ======================================================================== -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
