Documentation/devicetree/changesets.txt

   1 A DT changeset is a method which allows one to apply changes
   2 in the live tree in such a way that either the full set of changes
   3 will be applied, or none of them will be. If an error occurs partway
   4 through applying the changeset, then the tree will be rolled back to the
   5 previous state. A changeset can also be removed after it has been
   6 applied.
   7
   8 When a changeset is applied, all of the changes get applied to the tree
   9 at once before emitting OF_RECONFIG notifiers. This is so that the
  10 receiver sees a complete and consistent state of the tree when it
  11 receives the notifier.
  12
  13 The sequence of a changeset is as follows.
  14
  15 1. of_changeset_init() - initializes a changeset
  16
  17 2. A number of DT tree change calls, of_changeset_attach_node(),
  18 of_changeset_detach_node(), of_changeset_add_property(),
  19 of_changeset_remove_property, of_changeset_update_property() to prepare
  20 a set of changes. No changes to the active tree are made at this point.
  21 All the change operations are recorded in the of_changeset 'entries'
  22 list.
  23
  24 3. mutex_lock(of_mutex) - starts a changeset; The global of_mutex
  25 ensures there can only be one editor at a time.
  26
  27 4. of_changeset_apply() - Apply the changes to the tree. Either the
  28 entire changeset will get applied, or if there is an error the tree will
  29 be restored to the previous state
  30
  31 5. mutex_unlock(of_mutex) - All operations complete, release the mutex
  32
  33 If a successfully applied changeset needs to be removed, it can be done
  34 with the following sequence.
  35
  36 1. mutex_lock(of_mutex)
  37
  38 2. of_changeset_revert()
  39
  40 3. mutex_unlock(of_mutex)