Merge https://gitlab.denx.de/u-boot/custodians/u-boot-x86

- Rename existing FSP code to fsp1
- Add fsp2 directory in preparation to support FSP 2.0
- Various x86 platform codes update
- Various bug fixes and updates in dm core, sandbox and spl

3 files changed, 76 insertions, 12 deletions

diff --git a/doc/driver-model/debugging.rst b/doc/driver-model/debugging.rst
new file mode 100644
index 0000000000..4f4a8d4805
--- /dev/null
+++ b/doc/driver-model/debugging.rst
@@ -0,0 +1,62 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. sectionauthor:: Simon Glass <sjg@chromium.org>
+
+Debugging driver model
+======================
+
+This document aims to provide help when you cannot work out why driver model is
+not doing what you expect.
+
+
+Useful techniques in general
+----------------------------
+
+Here are some useful debugging features generally.
+
+   - If you are writing a new feature, consider doing it in sandbox instead of
+     on your board. Sandbox has no limits, allows easy debugging (e.g. gdb) and
+     you can write emulators for most common devices.
+   - Put '#define DEBUG' at the top of a file, to activate all the debug() and
+     log_debug() statements in that file.
+   - Where logging is used, change the logging level, e.g. in SPL with
+     CONFIG_SPL_LOG_MAX_LEVEL=7 (which is LOGL_DEBUG) and
+     CONFIG_LOG_DEFAULT_LEVEL=7
+   - Where logging of return values is implemented with log_msg_ret(), set
+     CONFIG_LOG_ERROR_RETURN=y to see exactly where the error is happening
+   - Make sure you have a debug UART enabled - see CONFIG_DEBUG_UART. With this
+     you can get serial output (printf(), etc.) before the serial driver is
+     running.
+   - Use a JTAG emulator to set breakpoints and single-step through code
+
+Not that most of these increase code/data size somewhat when enabled.
+
+
+Failure to locate a device
+--------------------------
+
+Let's say you have uclass_first_device_err() and it is not finding anything.
+
+If it is returning an error, then that gives you a clue. Look up linux/errno.h
+to see errors. Common ones are:
+
+   - -ENOMEM which indicates that memory is short. If it happens in SPL or
+     before relocation in U-Boot, check CONFIG_SPL_SYS_MALLOC_F_LEN and
+     CONFIG_SYS_MALLOC_F_LEN as they may need to be larger. Add '#define DEBUG'
+     at the very top of malloc_simple.c to get an idea of where your memory is
+     going.
+   - -EINVAL which typically indicates that something was missing or wrong in
+     the device tree node. Check that everything is correct and look at the
+     ofdata_to_platdata() method in the driver.
+
+If there is no error, you should check if the device is actually bound. Call
+dm_dump_all() just before you locate the device to make sure it exists.
+
+If it does not exist, check your device tree compatible strings match up with
+what the driver expects (in the struct udevice_id array).
+
+If you are using of-platdata (e.g. CONFIG_SPL_OF_PLATDATA), check that the
+driver name is the same as the first compatible string in the device tree (with
+invalid-variable characters converted to underscore).
+
+If you are really stuck, #define DEBUG at the top of lists.c should show you
+what is going on.
diff --git a/doc/driver-model/index.rst b/doc/driver-model/index.rst
index ea32c36335..6d55774b4c 100644
--- a/doc/driver-model/index.rst
+++ b/doc/driver-model/index.rst
@@ -6,6 +6,7 @@ Driver Model
 .. toctree::
    :maxdepth: 2
 
+   debugging
    design
    fdt-fixup
    fs_firmware_loader
diff --git a/doc/driver-model/pci-info.rst b/doc/driver-model/pci-info.rst
index d93ab8b61d..3c1b1adf07 100644
--- a/doc/driver-model/pci-info.rst
+++ b/doc/driver-model/pci-info.rst
@@ -103,7 +103,7 @@ in each of these nodes.
 
 If PCI devices are not listed in the device tree, U_BOOT_PCI_DEVICE can be used
 to specify the driver to use for the device. The device tree takes precedence
-over U_BOOT_PCI_DEVICE. Plese note with U_BOOT_PCI_DEVICE, only drivers with
+over U_BOOT_PCI_DEVICE. Please note with U_BOOT_PCI_DEVICE, only drivers with
 DM_FLAG_PRE_RELOC will be bound before relocation. If neither device tree nor
 U_BOOT_PCI_DEVICE is provided, the built-in driver (either pci_bridge_drv or
 pci_generic_drv) will be used.
@@ -113,14 +113,17 @@ Sandbox
 -------
 
 With sandbox we need a device emulator for each device on the bus since there
-is no real PCI bus. This works by looking in the device tree node for a
-driver. For example::
-
+is no real PCI bus. This works by looking in the device tree node for an
+emulator driver. For example::
 
 	pci@1f,0 {
 		compatible = "pci-generic";
 		reg = <0xf800 0 0 0 0>;
-		emul@1f,0 {
+		sandbox,emul = <&emul_1f>;
+	};
+	pci-emul {
+		compatible = "sandbox,pci-emul-parent";
+		emul_1f: emul@1f,0 {
 			compatible = "sandbox,swap-case";
 		};
 	};
@@ -130,14 +133,16 @@ Note that the first cell in the 'reg' value is the bus/device/function. See
 PCI_BDF() for the encoding (it is also specified in the IEEE Std 1275-1994
 PCI bus binding document, v2.1)
 
+The pci-emul node should go outside the pci bus node, since otherwise it will
+be scanned as a PCI device, causing confusion.
+
 When this bus is scanned we will end up with something like this::
 
    `- * pci-controller @ 05c660c8, 0
     `-   pci@1f,0 @ 05c661c8, 63488
-     `-   emul@1f,0 @ 05c662c8
+   `-   emul@1f,0 @ 05c662c8
 
-When accesses go to the pci@1f,0 device they are forwarded to its child, the
-emulator.
+When accesses go to the pci@1f,0 device they are forwarded to its emulator.
 
 The sandbox PCI drivers also support dynamic driver binding, allowing device
 driver to declare the driver binding information via U_BOOT_PCI_DEVICE(),
@@ -164,7 +169,3 @@ When this bus is scanned we will end up with something like this::
  pci        [ + ]   pci_sandbo  |-- pci-controller1
  pci_emul   [   ]   sandbox_sw  |   |-- sandbox_swap_case_emul
  pci_emul   [   ]   sandbox_sw  |   `-- sandbox_swap_case_emul
-
-Note the difference from the statically declared device nodes is that the
-device is directly attached to the host controller, instead of via a container
-device like pci@1f,0.