Merge branch '2022-09-29-dm-core-support-multiple-device-trees-in-ofnode' into next

To quote the author:
At present the ofnode interface is somewhat limited, in that it cannot
access the device tree provided by the OS, only the one used by U-Boot
itself (assuming these are separate). This prevents using ofnode functions
to handle device tree fixups, i.e. ft_board_setup() and the like.

The ofnode interface was introduced to allow a consistent API to access
the device tree, whether a flat tree or a live tree (OF_LIVE) is in use.

With the flat tree, adding nodes and properties at the start of the tree
(as often happens when writing to the /chosen node) requires copying a
lot of data for each operation. With live tree, such operations are
quite a bit faster, since there is no memory copying required. This has to
be weighed against the required memory allocation with OF_LIVE, as well
as the cost of unflattening and flattening the device tree which U-Boot
is running.

This series enables support for access to multiple device trees with the
ofnode interface. This is already available to some extent with OF_LIVE,
but some of the ofnode functions need changes to allow the tree to be
specified.

The mechanism works by using the top 1-4 bits of the device tree offset.
The sign bit is not affected, since negative values must be supported.

With this implemented, it becomes possible to use the ofnode interface
to do device tree fixups. The only current user is the EVT_FT_FIXUP
event.

This has two main benefits:

- ofnode can now be used everywhere, in preference to the libfdt calls
- live tree can eventually be used everywhere, with potential speed
  improvements when larger number of fixups are used

This series is only a step along the way. Firstly, while it is possible
to access the 'fix-up' tree using OF_LIVE, most of the fixup functions use
flat tree directly, rather than the ofnode interface. These need to be
updated. Also the tree must be flattened again before it is passed to the
OS. This is not currently implemented.

With OFNODE_MULTI_TREE disabled this has almost no effect on code size:
around 4 bytes if EVENT is enabled, 0 if not. With the feature enabled,
the increase is around 700 bytes, e.g. on venice2:

$ buildman -b ofn2a venice2 -sS --step 0
Summary of 2 commits for 1 boards (1 thread, 64 jobs per thread)
01: image: Drop some other #ifdefs in image-board.c
       arm:  w+   venice2
48: wip
       arm: (for 1/1 boards) all +668.0 text +668.0

This size increase is not too bad, considering the extra functionality,
but is too large to enable everywhere. So for now this features needs to
be opt-in only, based on EVENT.

1 files changed, 14 insertions, 23 deletions

diff --git a/doc/develop/driver-model/livetree.rst b/doc/develop/driver-model/livetree.rst
index faf3eb5b5f..55aa3eac92 100644
--- a/doc/develop/driver-model/livetree.rst
+++ b/doc/develop/driver-model/livetree.rst
@@ -235,20 +235,9 @@ tree either present or absent. This is to make sure that the flat tree functions
 work correctly even with OF_LIVE is enabled. But if a test modifies the flat
 device tree, then the live tree can become invalid. Any live tree tests that run
 after that point will use a corrupted tree, e.g. with an incorrect property name
-or worse. To deal with this we use a flag UT_TESTF_LIVE_OR_FLAT then ensures
-that tests which write to the flat tree are not run if OF_LIVE is enabled. Only
-the live tree version of the test is run, when OF_LIVE is enabled, with
-sandbox_flattree running the flat tree version.
-
-This is of course a work-around, even if a reasonable one. One solution to this
-problem would be to make a copy of the flat tree before the test and restore it
-afterwards, in the same memory location, so that the live tree pointers work
-again. Another would be to regenerate the live tree if a test modified the flat
-tree.
-
-Neither of these solutions is currently implemented, since the situation that
-causes the problem can only occur in sandbox tests, is somewhat esoteric and
-the UT_TESTF_LIVE_OR_FLAT flag deals with it in a reasonable way.
+or worse. To deal with this we take a copy of the device tree and restore it
+after any test that modifies it. Note that this copy is not made on other
+boards, only sandbox.
 
 
 Multiple livetrees
@@ -261,11 +250,14 @@ a flat tree.
 It would be helpful to use livetree for fixups, since adding a lot of nodes and
 properties would involve less memory copying and be more efficient. As a step
 towards this, an `oftree` type has been introduced. It is normally set to
-oftree_default() but can be set to other values. Eventually this should allow
-the use of FDT fixups using the ofnode interface, instead of the low-level
-libfdt one.
+oftree_default() but can be set to other values using oftree_from_fdt().
+So long as OF_LIVE is disabled, it is possible to do fixups using the ofnode
+interface. The OF_LIVE support required addition of the flattening step at the
+end.
 
-See dm_test_ofnode_root() for some examples.
+See dm_test_ofnode_root() for some examples. The ofnode_path_root() function
+causes a flat device tree to be 'registered' such that it can be used by the
+ofnode interface.
 
 
 Internal implementation
@@ -329,10 +321,9 @@ Adding a new function for device-tree access involves the following steps:
 Future work
 -----------
 
-Live tree support was introduced in U-Boot 2017.07. There is still quite a bit
-of work to do to flesh this out:
+Live tree support was introduced in U-Boot 2017.07. Some possible enhancements
+are:
 
-- tests for all access functions
-- more support for livetree modification
-- addition of more access functions as needed
 - support for livetree in SPL and before relocation (if desired)
+- freeing leaked memory caused by writing new nodes / property values to the
+  livetree (ofnode_write_prop())