From fdd72be486144f154fdfac91e7bfc2d503fea9fb Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Wed, 25 Sep 2019 08:55:48 -0600 Subject: dm: core: Add documentation on how to debug driver model Sometimes devices don't appear and it can be confusing. Add a few notes to help with this situation. Signed-off-by: Simon Glass Reviewed-by: Bin Meng Tested-by: Bin Meng [bmeng: fix 2 issues in the doc and include the doc in the index.rst] Signed-off-by: Bin Meng --- doc/driver-model/debugging.rst | 62 ++++++++++++++++++++++++++++++++++++++++++ doc/driver-model/index.rst | 1 + 2 files changed, 63 insertions(+) create mode 100644 doc/driver-model/debugging.rst (limited to 'doc') diff --git a/doc/driver-model/debugging.rst b/doc/driver-model/debugging.rst new file mode 100644 index 00000000000..4f4a8d4805f --- /dev/null +++ b/doc/driver-model/debugging.rst @@ -0,0 +1,62 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. sectionauthor:: Simon Glass + +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 ea32c36335f..6d55774b4c2 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 -- cgit v1.3.1 From 189882c9337bd4fa0a6b2c5de3031cd6f4b8e262 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Wed, 25 Sep 2019 08:56:07 -0600 Subject: sandbox: Add a -T flag to use the test device tree U-Boot already supports using -D to indicate that it should use the normal device tree. It is sometimes useful to run with the test device tree, e.g. when running a test. Add a -T option for this along with some documentation. It can be used like this: /tmp/b/sandbox/u-boot -T -c "ut dm pci_busdev" (this will use /tmp/b/sandbox/arch/sandbox/dts/test.dtb as the DT) Signed-off-by: Simon Glass Reviewed-by: Bin Meng Tested-by: Bin Meng --- arch/sandbox/cpu/start.c | 25 +++++++++++++++++++++++++ doc/arch/sandbox.rst | 9 +++++++++ 2 files changed, 34 insertions(+) (limited to 'doc') diff --git a/arch/sandbox/cpu/start.c b/arch/sandbox/cpu/start.c index 82828f0c1d4..cfc542c8066 100644 --- a/arch/sandbox/cpu/start.c +++ b/arch/sandbox/cpu/start.c @@ -147,6 +147,31 @@ static int sandbox_cmdline_cb_default_fdt(struct sandbox_state *state, SANDBOX_CMDLINE_OPT_SHORT(default_fdt, 'D', 0, "Use the default u-boot.dtb control FDT in U-Boot directory"); +static int sandbox_cmdline_cb_test_fdt(struct sandbox_state *state, + const char *arg) +{ + const char *fmt = "/arch/sandbox/dts/test.dtb"; + char *p; + char *fname; + int len; + + len = strlen(state->argv[0]) + strlen(fmt) + 1; + fname = os_malloc(len); + if (!fname) + return -ENOMEM; + strcpy(fname, state->argv[0]); + p = strrchr(fname, '/'); + if (!p) + p = fname + strlen(fname); + len -= p - fname; + snprintf(p, len, fmt, p); + state->fdt_fname = fname; + + return 0; +} +SANDBOX_CMDLINE_OPT_SHORT(test_fdt, 'T', 0, + "Use the test.dtb control FDT in U-Boot directory"); + static int sandbox_cmdline_cb_interactive(struct sandbox_state *state, const char *arg) { diff --git a/doc/arch/sandbox.rst b/doc/arch/sandbox.rst index 5c0caebcbf0..54933b56759 100644 --- a/doc/arch/sandbox.rst +++ b/doc/arch/sandbox.rst @@ -103,6 +103,8 @@ A device tree binary file can be provided with -d. If you edit the source (it is stored at arch/sandbox/dts/sandbox.dts) you must rebuild U-Boot to recreate the binary file. +To use the default device tree, use -D. To use the test device tree, use -T. + To execute commands directly, use the -c option. You can specify a single command, or multiple commands separated by a semicolon, as is normal in U-Boot. Be careful with quoting as the shell will normally process and @@ -499,6 +501,13 @@ run natively on your board if desired (and enabled). To run all tests use "make check". +To run a single test in an existing sandbox build, you can use -T to use the +test device tree, and -c to select the test: + + /tmp/b/sandbox/u-boot -T -c "ut dm pci_busdev" + +This runs dm_test_pci_busdev() which is in test/dm/pci.c + Memory Map ---------- -- cgit v1.3.1 From 9b69ba4a787209da59e69fd4e411ab6561b0447f Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Wed, 25 Sep 2019 08:56:10 -0600 Subject: pci: sandbox: Move the emulators into their own node Sandbox pci works using emulation drivers which are currently children of the pci device: pci-controller { pci@1f,0 { compatible = "pci-generic"; reg = <0xf800 0 0 0 0>; emul@1f,0 { compatible = "sandbox,swap-case"; }; }; }; In this case the emulation device is attached to pci device on address f800 (device 1f, function 0) and provides the swap-case functionality. However this is not ideal, since every device on a PCI bus has a child device. This is only really the case for sandbox, but we want to avoid special-case code for sandbox. Worse, child devices cannot be probed before their parents. This forces us to use 'find' rather than 'get' to obtain the emulator device. In fact the emulator devices are never probed. There is code in sandbox_pci_emul_post_probe() which tries to track when emulators are active, but at present this does not work. A better approach seems to be to add a separate node elsewhere in the device tree, an 'emulation parent'. This could be given a bogus address (such as -1) to hide the emulators away from the 'pci' command, but it seems better to keep it at the root node to avoid such hacks. Then we can use a phandle to point from the device to the correct emulator, and only on sandbox. The code to find an emulator does not interfere with normal pci operation. Add a new UCLASS_PCI_EMUL_PARENT uclass which allows finding an emulator given a bus, and finding a bus given an emulator. Update the existing device trees and the code for finding an emulator. This brings PCI emulators more into line with I2C. Signed-off-by: Simon Glass Reviewed-by: Bin Meng Tested-by: Bin Meng [bmeng: fix 3 typos in the commit message; encode bus number in the labels of swap_case_emul nodes; mention commit 4345998ae9df in sandbox_pci_get_emul()] Signed-off-by: Bin Meng --- arch/sandbox/dts/sandbox.dtsi | 11 ++++++++--- arch/sandbox/dts/test.dts | 38 +++++++++++++++++++++++++------------- doc/driver-model/pci-info.rst | 23 ++++++++++++----------- drivers/pci/pci-emul-uclass.c | 36 ++++++++++++++++++++++++++++++------ include/dm/uclass-id.h | 1 + 5 files changed, 76 insertions(+), 33 deletions(-) (limited to 'doc') diff --git a/arch/sandbox/dts/sandbox.dtsi b/arch/sandbox/dts/sandbox.dtsi index c6d5650c20b..f09bc70b0da 100644 --- a/arch/sandbox/dts/sandbox.dtsi +++ b/arch/sandbox/dts/sandbox.dtsi @@ -103,9 +103,14 @@ pci@1f,0 { compatible = "pci-generic"; reg = <0xf800 0 0 0 0>; - emul@1f,0 { - compatible = "sandbox,swap-case"; - }; + sandbox,emul = <&swap_case_emul>; + }; + }; + + emul { + compatible = "sandbox,pci-emul-parent"; + swap_case_emul: emul@1f,0 { + compatible = "sandbox,swap-case"; }; }; diff --git a/arch/sandbox/dts/test.dts b/arch/sandbox/dts/test.dts index 5e859ba11d9..b6d09600976 100644 --- a/arch/sandbox/dts/test.dts +++ b/arch/sandbox/dts/test.dts @@ -452,24 +452,31 @@ pci@0,0 { compatible = "pci-generic"; reg = <0x0000 0 0 0 0>; - emul@0,0 { - compatible = "sandbox,swap-case"; - }; + sandbox,emul = <&swap_case_emul0_0>; }; pci@1,0 { compatible = "pci-generic"; reg = <0x0800 0 0 0 0>; - emul@0,0 { - compatible = "sandbox,swap-case"; - use-ea; - }; + sandbox,emul = <&swap_case_emul0_1>; }; pci@1f,0 { compatible = "pci-generic"; reg = <0xf800 0 0 0 0>; - emul@1f,0 { - compatible = "sandbox,swap-case"; - }; + sandbox,emul = <&swap_case_emul0_1f>; + }; + }; + + pci-emul0 { + compatible = "sandbox,pci-emul-parent"; + swap_case_emul0_0: emul0@0,0 { + compatible = "sandbox,swap-case"; + }; + swap_case_emul0_1: emul0@1,0 { + compatible = "sandbox,swap-case"; + use-ea; + }; + swap_case_emul0_1f: emul0@1f,0 { + compatible = "sandbox,swap-case"; }; }; @@ -499,9 +506,14 @@ pci@1f,0 { compatible = "pci-generic"; reg = <0xf800 0 0 0 0>; - emul@1f,0 { - compatible = "sandbox,swap-case"; - }; + sandbox,emul = <&swap_case_emul2_1f>; + }; + }; + + pci-emul2 { + compatible = "sandbox,pci-emul-parent"; + swap_case_emul2_1f: emul2@1f,0 { + compatible = "sandbox,swap-case"; }; }; diff --git a/doc/driver-model/pci-info.rst b/doc/driver-model/pci-info.rst index d93ab8b61d5..f39ff990a67 100644 --- a/doc/driver-model/pci-info.rst +++ b/doc/driver-model/pci-info.rst @@ -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. diff --git a/drivers/pci/pci-emul-uclass.c b/drivers/pci/pci-emul-uclass.c index 38227583547..6b4efcea37d 100644 --- a/drivers/pci/pci-emul-uclass.c +++ b/drivers/pci/pci-emul-uclass.c @@ -10,6 +10,7 @@ #include #include #include +#include struct sandbox_pci_emul_priv { int dev_count; @@ -30,13 +31,14 @@ int sandbox_pci_get_emul(struct udevice *bus, pci_dev_t find_devfn, } *containerp = dev; - if (device_get_uclass_id(dev) == UCLASS_PCI_GENERIC) { - ret = device_find_first_child(dev, emulp); - if (ret) - return ret; - } else { + /* + * See commit 4345998ae9df, + * "pci: sandbox: Support dynamically binding device driver" + */ + ret = uclass_find_device_by_phandle(UCLASS_PCI_EMUL, dev, + "sandbox,emul", emulp); + if (ret && device_get_uclass_id(dev) != UCLASS_PCI_GENERIC) *emulp = dev; - } return *emulp ? 0 : -ENODEV; } @@ -68,3 +70,25 @@ UCLASS_DRIVER(pci_emul) = { .pre_remove = sandbox_pci_emul_pre_remove, .priv_auto_alloc_size = sizeof(struct sandbox_pci_emul_priv), }; + +/* + * This uclass is a child of the pci bus. Its platdata is not defined here so + * is defined by its parent, UCLASS_PCI, which uses struct pci_child_platdata. + * See per_child_platdata_auto_alloc_size in UCLASS_DRIVER(pci). + */ +UCLASS_DRIVER(pci_emul_parent) = { + .id = UCLASS_PCI_EMUL_PARENT, + .name = "pci_emul_parent", + .post_bind = dm_scan_fdt_dev, +}; + +static const struct udevice_id pci_emul_parent_ids[] = { + { .compatible = "sandbox,pci-emul-parent" }, + { } +}; + +U_BOOT_DRIVER(pci_emul_parent_drv) = { + .name = "pci_emul_parent_drv", + .id = UCLASS_PCI_EMUL_PARENT, + .of_match = pci_emul_parent_ids, +}; diff --git a/include/dm/uclass-id.h b/include/dm/uclass-id.h index d4d96106b37..f431f3bf294 100644 --- a/include/dm/uclass-id.h +++ b/include/dm/uclass-id.h @@ -23,6 +23,7 @@ enum uclass_id { UCLASS_I2C_EMUL, /* sandbox I2C device emulator */ UCLASS_I2C_EMUL_PARENT, /* parent for I2C device emulators */ UCLASS_PCI_EMUL, /* sandbox PCI device emulator */ + UCLASS_PCI_EMUL_PARENT, /* parent for PCI device emulators */ UCLASS_USB_EMUL, /* sandbox USB bus device emulator */ UCLASS_AXI_EMUL, /* sandbox AXI bus device emulator */ -- cgit v1.3.1 From bdaa976153b29c88822e6c196e48f6ad2f881846 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Wed, 25 Sep 2019 08:56:14 -0600 Subject: pci: Correct 'specifified' and 'Plese' typos Fix these spelling errors the header file and documentation. Fix a small typo in the PCI documentation. Signed-off-by: Simon Glass Reviewed-by: Bin Meng --- doc/driver-model/pci-info.rst | 2 +- include/pci.h | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/driver-model/pci-info.rst b/doc/driver-model/pci-info.rst index f39ff990a67..3c1b1adf077 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. diff --git a/include/pci.h b/include/pci.h index 2b82b2c5a3e..8aa6636cfbf 100644 --- a/include/pci.h +++ b/include/pci.h @@ -1595,7 +1595,7 @@ int sandbox_pci_get_emul(struct udevice *bus, pci_dev_t find_devfn, /** * pci_get_devfn() - Extract the devfn from fdt_pci_addr of the device * - * Get devfn from fdt_pci_addr of the specifified device + * Get devfn from fdt_pci_addr of the specified device * * @dev: PCI device * @return devfn in bits 15...8 if found, -ENODEV if not found -- cgit v1.3.1