3 files changed, 107 insertions, 0 deletions
diff --git a/doc/develop/devicetree/control.rst b/doc/develop/devicetree/control.rst
index 634114af59a..7d6117d5c4b 100644
--- a/doc/develop/devicetree/control.rst
+++ b/doc/develop/devicetree/control.rst
@@ -232,6 +232,64 @@ outside the U-Boot repository. You can use `DEVICE_TREE_INCLUDES` Kconfig
 option to specify a list of .dtsi files that will also be included when
 building .dtb files.
 
+Scripts embedded in control DTB
+-------------------------------
+
+The `DEVICE_TREE_INCLUDES` option can also be used to make the control
+DTB serve double duty as a FIT image. By including a `scripts.dtsi`
+file containing something like::
+
+  / {
+	images {
+		default = "boot";
+		boot {
+			description = "Bootscript";
+			data = /incbin/("boot.sh");
+			type = "script";
+			compression = "none";
+		};
+		factory-reset {
+			description = "Script for performing factory reset";
+			data = /incbin/("factory-reset.sh");
+			type = "script";
+			compression = "none";
+		};
+	};
+  };
+
+one can call those scripts using the `source` command in the U-Boot shell::
+
+  source ${fdtcontroladdr}:boot
+
+or just ``source ${fdtcontroladdr}`` for invoking the default.
+
+Since one does not need to separately build a "real" FIT image
+containing those scripts, this simplifies both the build process and
+the boot logic, as the latter does not need to first load the FIT
+image from storage.
+
+Another advantage is that when the bootloader and boot script must be
+updated together, it is easier to achieve a guaranteed atomic update
+when the boot script is embedded inside the U-Boot binary, instead of
+stored separately.
+
+For the above to work, one must enable the `CONTROL_DTB_AS_FIT` config
+option, which will (when the address passed to the `source` command is
+the address of U-Boot's control DTB) elide certain sanity checks that
+are normally done: With the above `.dtsi` snippet, the control DTB
+does not quite become a "real" FIT image - it lacks `timestamp` and
+`description` properties, but more importantly, FIT images cannot
+contain nodes with `@` in their names (unit addresses) anywhere, and
+the control DTB obviously does have such nodes.
+
+This is not a security problem, as the control DTB is necessarily
+trusted. In any secure boot setup where the bootloader is verified,
+that mechanism must also include verification of the control DTB. So
+in fact, since the scripts embedded this way are then also
+automatically verified, it simplifies implementation of secure
+boot. When using a separate FIT image, one must build it with
+appropriate signatures, just as when building a FIT image containing a
+kernel/dtb/initramfs.
 
 Devicetree bindings schema checks
 ---------------------------------
diff --git a/doc/develop/environment.rst b/doc/develop/environment.rst
index e46cd39d601..a7ed4aab0a5 100644
--- a/doc/develop/environment.rst
+++ b/doc/develop/environment.rst
@@ -49,3 +49,43 @@ The signature of the callback functions is::
   include/search.h
 
 The return value is 0 if the variable change is accepted and 1 otherwise.
+
+Flags for environment variables
+-------------------------------
+
+Environment flags validate the values given to environment variables and
+restrict how environment variables can be changed.
+
+The static list is configured with CONFIG_ENV_FLAGS_LIST_STATIC. The list
+must be in the following format::
+
+    type_attribute = [s|d|x|b|i|m]
+    access_attribute = [a|r|o|c|w]
+    attributes = type_attribute[access_attribute]
+    entry = variable_name[:attributes]
+    list = entry[,list]
+
+The type attributes are:
+
+* s - String (default)
+* d - Decimal
+* x - Hexadecimal
+* b - Boolean ([1yYtT|0nNfF])
+* i - IP address, if networking is enabled
+* m - MAC address, if networking is enabled
+
+The access attributes are:
+
+* a - Any (default)
+* r - Read-only
+* o - Write-once
+* c - Change-default
+* w - Writeable, if CONFIG_ENV_WRITEABLE_LIST is enabled
+
+CONFIG_ENV_FLAGS_LIST_DEFAULT defines the ``.flags`` variable in the
+default or embedded environment. Any association in ``.flags`` overrides
+an association in the static list.
+
+If CONFIG_REGEX is defined, the variable name is evaluated as a regular
+expression. This allows multiple variables to define the same flags without
+explicitly listing them all.
diff --git a/doc/develop/memory.rst b/doc/develop/memory.rst
index 5177229630d..3da39bb6c66 100644
--- a/doc/develop/memory.rst
+++ b/doc/develop/memory.rst
@@ -111,6 +111,15 @@ U-Boot Proper Flow
       This follows the same as in SPL flow. In board_init_f(), a part of memory
       is reserved at the end of RAM (see reserve_* functions in init_sequence_f)
 
+   #. Relocation address
+
+      By default U-Boot will try to relocate below the 4GiB boundary. If
+      RELOC_ADDR_TOP is enabled U-Boot will look into the dram bank config of
+      gd->dram[] and try to relocate to the highest available bank. Use this
+      with caution as devices that can only DMA below 4GiB will misbehave
+      since their buffers may be allocated above the 32-bit boundary.
+      Boards can override thre relocation address via board_get_usable_ram_top().
+
    #. Code Relocation
 
       relocate_code() is called which relocates U-Boot code from the current