8 files changed, 129 insertions, 11 deletions
diff --git a/doc/develop/bloblist.rst b/doc/develop/bloblist.rst
index 317ebc4919..47274cf8e2 100644
--- a/doc/develop/bloblist.rst
+++ b/doc/develop/bloblist.rst
@@ -59,6 +59,22 @@ Bloblist provides a fairly simple API which allows blobs to be created and
 found. All access is via the blob's tag. Blob records are zeroed when added.
 
 
+Placing the bloblist
+--------------------
+
+The bloblist is typically positioned at a fixed address by TPL, or SPL. This
+is controlled by `CONFIG_BLOBLIST_ADDR`. But in some cases it is preferable to
+allocate the bloblist in the malloc() space. Use the `CONFIG_BLOBLIST_ALLOC`
+option to enable this.
+
+The bloblist is automatically relocated as part of U-Boot relocation. Sometimes
+it is useful to expand the bloblist in U-Boot proper, since it may want to add
+information for use by Linux. Note that this does not mean that Linux needs to
+know anything about the bloblist format, just that it is convenient to use
+bloblist to place things contiguously in memory. Set
+`CONFIG_BLOBLIST_SIZE_RELOC` to define the expanded size, if needed.
+
+
 Finishing the bloblist
 ----------------------
 
diff --git a/doc/develop/devicetree/dt_qemu.rst b/doc/develop/devicetree/dt_qemu.rst
new file mode 100644
index 0000000000..c25c4fb053
--- /dev/null
+++ b/doc/develop/devicetree/dt_qemu.rst
@@ -0,0 +1,48 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Devicetree in QEMU
+==================
+
+For QEMU on ARM, RISC-V and one PPC target, the devicetree is created on-the-fly
+by QEMU. It is intended for use in Linux but can be used by U-Boot also, so long
+as any nodes/properties needed by U-Boot are merged in.
+
+When `CONFIG_OF_BOARD` is enabled
+
+
+Obtaining the QEMU devicetree
+-----------------------------
+
+Where QEMU generates its own devicetree to pass to U-Boot tou can use
+`-dtb u-boot.dtb` to force QEMU to use U-Boot's in-tree version.
+
+To obtain the devicetree that qemu generates, add `-machine dumpdtb=qemu.dtb`,
+e.g.::
+
+    qemu-system-arm -machine virt -machine dumpdtb=qemu.dtb
+
+    qemu-system-aarch64 -machine virt -machine dumpdtb=qemu.dtb
+
+    qemu-system-riscv64 -machine virt -machine dumpdtb=qemu.dtb
+
+
+Merging in U-Boot nodes/properties
+----------------------------------
+
+Various U-Boot features require nodes and properties in the U-Boot devicetree
+and at present QEMU is unaware of these. To use these you must manually merge
+in the appropriate pieces.
+
+One way to do this is with dtc. This command runs dtc on each .dtb file in turn,
+to produce a text file. It drops the duplicate header on the qemu one. Then it
+joins them up and runs them through dtc to compile the output::
+
+    qemu-system-arm -machine virt -machine dumpdtb=qemu.dtb
+    cat  <(dtc -I dtb qemu.dtb) <(dtc -I dtb  u-boot.dtb |grep -v /dts-v1/) |dtc - -o merged.dtb
+
+You can then run qemu with the merged devicetree, e.g.::
+
+    qemu-system-arm -machine virt -nographic -bios u-boot.bin -dtb merged.dtb
+
+Note that there seems to be a bug in some versions of qemu where the output of
+dumpdtb does not quite match what is provided to U-Boot.
diff --git a/doc/develop/devicetree/index.rst b/doc/develop/devicetree/index.rst
index fa5db3eb76..2edb69572d 100644
--- a/doc/develop/devicetree/index.rst
+++ b/doc/develop/devicetree/index.rst
@@ -11,3 +11,4 @@ build-time and runtime configuration.
 
    intro
    control
+   dt_qemu
diff --git a/doc/develop/driver-model/migration.rst b/doc/develop/driver-model/migration.rst
index 8bb8601c58..3dbeea6537 100644
--- a/doc/develop/driver-model/migration.rst
+++ b/doc/develop/driver-model/migration.rst
@@ -98,3 +98,11 @@ Deadline: 2021.10
 The I2C subsystem has supported the driver model since early 2015.
 Maintainers should submit patches switching over to using CONFIG_DM_I2C and
 other base driver model options in time for inclusion in the 2021.10 release.
+
+CONFIG_KEYBOARD
+---------------
+Deadline: 2022.10
+
+This is a legacy option which has been replaced by driver model.
+Maintainers should submit patches switching over to using CONFIG_DM_KEYBOARD and
+other base driver model options in time for inclusion in the 2022.10 release.
diff --git a/doc/develop/environment.rst b/doc/develop/environment.rst
new file mode 100644
index 0000000000..0b86fafbff
--- /dev/null
+++ b/doc/develop/environment.rst
@@ -0,0 +1,51 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Environment implementation
+==========================
+
+See :doc:`../usage/environment` for usage information.
+
+Callback functions for environment variables
+--------------------------------------------
+
+For some environment variables, the behavior of u-boot needs to change
+when their values are changed.  This functionality allows functions to
+be associated with arbitrary variables.  On creation, overwrite, or
+deletion, the callback will provide the opportunity for some side
+effect to happen or for the change to be rejected.
+
+The callbacks are named and associated with a function using the
+U_BOOT_ENV_CALLBACK macro in your board or driver code.
+
+These callbacks are associated with variables in one of two ways.  The
+static list can be added to by defining CONFIG_ENV_CALLBACK_LIST_STATIC
+in the board configuration to a string that defines a list of
+associations.  The list must be in the following format::
+
+    entry = variable_name[:callback_name]
+    list = entry[,list]
+
+If the callback name is not specified, then the callback is deleted.
+Spaces are also allowed anywhere in the list.
+
+Callbacks can also be associated by defining the ".callbacks" variable
+with the same list format above.  Any association in ".callbacks" will
+override any association in the static list. You can define
+CONFIG_ENV_CALLBACK_LIST_DEFAULT to a list (string) to define the
+".callbacks" environment variable in the default or embedded environment.
+
+If CONFIG_REGEX is defined, the variable_name above is evaluated as a
+regular expression. This allows multiple variables to be connected to
+the same callback without explicitly listing them all out.
+
+The signature of the callback functions is::
+
+    int callback(const char *name, const char *value, enum env_op op, int flags)
+
+* name - changed environment variable
+* value - new value of the environment variable
+* op - operation (create, overwrite, or delete)
+* flags - attributes of the environment variable change, see flags H_* in
+  include/search.h
+
+The return value is 0 if the variable change is accepted and 1 otherwise.
diff --git a/doc/develop/index.rst b/doc/develop/index.rst
index b3871b16f3..9592d193fc 100644
--- a/doc/develop/index.rst
+++ b/doc/develop/index.rst
@@ -16,6 +16,7 @@ Implementation
    devicetree/index
    distro
    driver-model/index
+   environment
    global_data
    logging
    makefiles
diff --git a/doc/develop/trace.rst b/doc/develop/trace.rst
index 09f5745a90..b22e068ef9 100644
--- a/doc/develop/trace.rst
+++ b/doc/develop/trace.rst
@@ -30,16 +30,11 @@ Sandbox is a build of U-Boot that can run under Linux so it is a convenient
 way of trying out tracing before you use it on your actual board. To do
 this, follow these steps:
 
-Add the following to include/configs/sandbox.h (if not already there)
+Add the following to config/sandbox_defconfig
 
 .. code-block:: c
 
-    #define CONFIG_TRACE
-    #define CONFIG_CMD_TRACE
-    #define CONFIG_TRACE_BUFFER_SIZE    (16 << 20)
-    #define CONFIG_TRACE_EARLY_SIZE     (8 << 20)
-    #define CONFIG_TRACE_EARLY
-    #define CONFIG_TRACE_EARLY_ADDR     0x00100000
+    CONFIG_TRACE=y
 
 Build sandbox U-Boot with tracing enabled:
 
diff --git a/doc/develop/uefi/u-boot_on_efi.rst b/doc/develop/uefi/u-boot_on_efi.rst
index 5f2f850f07..acad6397e8 100644
--- a/doc/develop/uefi/u-boot_on_efi.rst
+++ b/doc/develop/uefi/u-boot_on_efi.rst
@@ -265,13 +265,11 @@ This work could be extended in a number of ways:
 
 - Figure out how to solve the interrupt problem
 
-- Add more drivers to the application side (e.g. block devices, USB,
-  environment access). This would mostly be an academic exercise as a strong
-  use case is not readily apparent, but it might be fun.
+- Add more drivers to the application side (e.g.USB, environment access).
 
 - Avoid turning off boot services in the stub. Instead allow U-Boot to make
   use of boot services in case it wants to. It is unclear what it might want
-  though.
+  though. It is better to use the app.
 
 Where is the code?
 ------------------