Documentation/devicetree/changesets.rst

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