fdt: Add a Kconfig for boards with a prior stage

When U-Boot is started from another firmware program, not just a prior
phase of U-Boot, special behaviour is typically used. In particular, the
device tree may come from that prior stage.

At present this is sort-of indicated by OF_BOARD, although the
correlation is not 1:1, since that option simply means that the board has
a custom mechanism for obtaining the device tree. For example, sandbox
defines OF_BOARD. Also the board_fdt_blob_setup() function can in fact
make use of the devicetree in U-Boot if it wishes, as used by
dragonboard410c until very recently.

Add an explicit Kconfig for this situation. Update the OF_BOARD option to
more-accurately reflect what it is doing, e.g. for sandbox.

Drop the docs in the README as it is out of date.

Signed-off-by: Simon Glass <sjg@chromium.org>

3 files changed, 29 insertions, 34 deletions

diff --git a/README b/README
index 056b717557b..3496bef7774 100644
--- a/README
+++ b/README
@@ -646,35 +646,6 @@ The following options need to be configured:
 		which adds regex support to some commands, as for
 		example "env grep" and "setexpr".
 
-- Device tree:
-		CONFIG_OF_CONTROL
-		If this variable is defined, U-Boot will use a device tree
-		to configure its devices, instead of relying on statically
-		compiled #defines in the board file. This option is
-		experimental and only available on a few boards. The device
-		tree is available in the global data as gd->fdt_blob.
-
-		U-Boot needs to get its device tree from somewhere. This can
-		be done using one of the three options below:
-
-		CONFIG_OF_SEPARATE
-		If this variable is defined, U-Boot will build a device tree
-		binary. It will be called u-boot.dtb. Architecture-specific
-		code will locate it at run-time. Generally this works by:
-
-			cat u-boot.bin u-boot.dtb >image.bin
-
-		and in fact, U-Boot does this for you, creating a file called
-		u-boot-dtb.bin which is useful in the common case. You can
-		still use the individual files if you need something more
-		exotic.
-
-		CONFIG_OF_BOARD
-		If this variable is defined, U-Boot will use the device tree
-		provided by the board at runtime instead of embedding one with
-		the image. Only boards defining board_fdt_blob_setup() support
-		this option (see include/fdtdec.h file).
-
 - Watchdog:
 		CONFIG_WATCHDOG
 		If this variable is defined, it enables watchdog
diff --git a/dts/Kconfig b/dts/Kconfig
index 5dcc79d5192..e57ce84b98d 100644
--- a/dts/Kconfig
+++ b/dts/Kconfig
@@ -98,13 +98,36 @@ endchoice
 
 config OF_BOARD
 	bool "Provided by the board (e.g a previous loader) at runtime"
-	default y if SANDBOX
+	default y if SANDBOX || OF_HAS_PRIOR_STAGE
 	help
-	  If this option is enabled, the device tree will be provided by
-	  the board at runtime if the board supports it. The device tree bundled
-	  with the image (if any) will be overridden / ignored.
+	  If this option is enabled, the device tree is provided at runtime by
+	  a custom function called board_fdt_blob_setup(). The board must
+	  implement this function if it wishes to provide special behaviour.
 
-	  A device tree file must be provided in the tree.
+	  With this option, the device tree build by U-Boot may be overridden or
+	  ignored. See OF_HAS_PRIOR_STAGE.
+
+	  Note: Boards which use this to handle a device tree passed from an
+	  earlier stage should enable OF_HAS_PRIOR_STAGE.
+
+config OF_HAS_PRIOR_STAGE
+	bool
+	help
+	  Indicates that a prior stage of the firmware (before U-Boot proper)
+	  makes use of device tree and this board normally boots with that prior
+	  stage, that provides a devicetree to U-Boot.
+
+	  This means that the device tree built in U-Boot should not be packaged
+	  in the firmware image. Instead, the prior stage's device tree should
+	  be so packaged. At runtime, the prior stage reads this, does any
+	  necessary fix-ups, then passes it to U-Boot. See OF_BOARD.
+
+	  This option does not preclude using the U-Boot device tree, e.g. for
+	  development purposes, but it is not recommended, and likely will not
+	  even work, for production systems.
+
+	  Note: This option must be set in Kconfig and cannot be enabled or
+	  disabled in the board's defconfig file.
 
 config DEFAULT_DEVICE_TREE
 	string "Default Device Tree for DT control"
diff --git a/lib/fdtdec.c b/lib/fdtdec.c
index 118c100b389..280cda61a72 100644
--- a/lib/fdtdec.c
+++ b/lib/fdtdec.c
@@ -1595,6 +1595,7 @@ int fdtdec_set_carveout(void *blob, const char *node, const char *prop_name,
 	return 0;
 }
 
+/* TODO(sjg@chromium.org): This function should not be weak */
 __weak int fdtdec_board_setup(const void *fdt_blob)
 {
 	return 0;