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.2.3