Phones don't have keyboards! Introduce a phone-specific config fragment and associated environment file to make U-Boot more useful on these devices. This allows for navigating via the buttons and enabling various USB gadget modes or displaying info about U-Boot.

Signed-off-by: Caleb Connolly caleb.connolly@linaro.org --- board/qualcomm/qcom-phone.config | 12 ++++++++++ board/qualcomm/qcom-phone.env | 49 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 61 insertions(+)

diff --git a/board/qualcomm/qcom-phone.config b/board/qualcomm/qcom-phone.config new file mode 100644 index 000000000000..4639e19a3df2 --- /dev/null +++ b/board/qualcomm/qcom-phone.config @@ -0,0 +1,12 @@ +# Settings for phones +CONFIG_USE_DEFAULT_ENV_FILE=y +CONFIG_DEFAULT_ENV_FILE="board/qualcomm/qcom-phone.env" +CONFIG_PANIC_HANG=y +CONFIG_CMD_PAUSE=y +CONFIG_BOOTSTD=y +CONFIG_BOOT_RETRY=y +CONFIG_BOOT_RETRY_TIME=1 +CONFIG_REMAP_PHONE_KEYS=y + +# Many phones don't actually define a serial port in their DTS +# CONFIG_REQUIRE_SERIAL_CONSOLE is not set diff --git a/board/qualcomm/qcom-phone.env b/board/qualcomm/qcom-phone.env new file mode 100644 index 000000000000..2a0791c888c6 --- /dev/null +++ b/board/qualcomm/qcom-phone.env @@ -0,0 +1,49 @@ +bootdelay=0 +bootretry=1 +stdin=serial,button-kbd +stdout=serial,vidconsole +stderr=serial,vidconsole + +# Fastboot is keen to use the address from kconfig, but we +# allocate its buffer at runtime. +fastboot=fastboot -l $fastboot_addr_r usb 0 + +# Shortcut to enable USB serial gadget and disable bootretry +serial_gadget=setenv stdin serial,button-kbd,usbacm; \ + setenv stdout serial,vidconsole,usbacm; \ + setenv stderr serial,vidconsole,usbacm; \ + setenv bootretry -1; \ + echo Enabled U-Boot console serial gadget + +# bootretry will run this command over and over, if we fail once +# then bail out to the boot menu instead (with a pause to read +# the error message) +bootcmd=bootefi bootmgr; pause; run menucmd + +# When entering the menu (either from button press or failed boot) +# remap bootcmd so it will re-open the menu and we won't get stuck +# at the console with no way to type +menucmd=setenv bootcmd run menucmd; bootmenu -1 + +# Pause is used so the output can be read on the display +bootmenu_0=Boot=bootefi bootmgr; pause +bootmenu_1=Enable serial console gadget=run serial_gadget +bootmenu_2=Enable USB mass storage=ums 0 scsi 0 +bootmenu_3=Reset device=reset +bootmenu_4=Dump clocks=clk dump; pause +bootmenu_5=Dump environment=printenv; pause +bootmenu_6=Board info=bdinfo; pause +bootmenu_7=Dump bootargs=fdt print /chosen bootargs; pause +bootmenu_8=Enable fastboot mode=run fastboot +# Disabling bootretry means we'll just drop the shell +bootmenu_9=Drop to shell=setenv bootretry -1 + +# Allow holding the power button while U-Boot loads to enter +# the boot menu +button_cmd_0_name=pwrkey +button_cmd_0=run menucmd + +# Hold volume down to drop to a shell with the USB serial gadget +# enabled for debugging +button_cmd_1_name=Volume down +button_cmd_1=run serial_gadget

When CONFIG_BOOT_RETRY is enabled, make hush shell always run the bootcmd. This is an improvement over failing to build.

Signed-off-by: Caleb Connolly caleb.connolly@linaro.org --- common/cli_hush.c | 2 +- common/cli_hush_upstream.c | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/common/cli_hush.c b/common/cli_hush.c index a6a8edce1f43..3c6fd6f00a1d 100644 --- a/common/cli_hush.c +++ b/common/cli_hush.c @@ -1028,9 +1028,9 @@ static void get_user_input(struct in_str *i) puts("\nTimeout waiting for command\n"); # ifdef CONFIG_RESET_TO_RETRY do_reset(NULL, 0, 0, NULL); # else -# error "This currently only works with CONFIG_RESET_TO_RETRY enabled" + strcpy(console_buffer, "run bootcmd\n"); # endif } #endif if (n == -1 ) { diff --git a/common/cli_hush_upstream.c b/common/cli_hush_upstream.c index 7874b399d141..c28f4a92123d 100644 --- a/common/cli_hush_upstream.c +++ b/common/cli_hush_upstream.c @@ -2897,9 +2897,9 @@ static void get_user_input(struct in_str *i) puts("\nTimeout waiting for command\n"); # ifdef CONFIG_RESET_TO_RETRY do_reset(NULL, 0, 0, NULL); # else -# error "This currently only works with CONFIG_RESET_TO_RETRY enabled" + strcpy(console_buffer, "run bootcmd\n"); # endif } # endif if (n == -1 ) {

Add some documentation which attempts to describe Qualcomm smartphone support with the qcom-phone.config fragment, as well as a high level debugging guide for diagnosing U-Boot issues when UART and framebuffer are unavailable.

Signed-off-by: Caleb Connolly caleb.connolly@linaro.org --- doc/board/qualcomm/board.rst | 5 ++ doc/board/qualcomm/index.rst | 1 + doc/board/qualcomm/phones.rst | 122 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 128 insertions(+)

diff --git a/doc/board/qualcomm/board.rst b/doc/board/qualcomm/board.rst index 4d793209f9e3..003d59a18ebd 100644 --- a/doc/board/qualcomm/board.rst +++ b/doc/board/qualcomm/board.rst @@ -89,8 +89,13 @@ Or for db410c (and other boards not supported by the generic target)::

make CROSS_COMPILE=aarch64-linux-gnu- O=.output dragonboard410c_defconfig make O=.output -j$(nproc)

+Or for smartphones:: + + make CROSS_COMPILE=aarch64-linux-gnu- O=.output qcom_defconfig qcom-phone.config + make O=.output -j$(nproc) + - gzip u-boot::

gzip u-boot-nodtb.bin

diff --git a/doc/board/qualcomm/index.rst b/doc/board/qualcomm/index.rst index 4955274a39bc..690d80c4ab1b 100644 --- a/doc/board/qualcomm/index.rst +++ b/doc/board/qualcomm/index.rst @@ -8,4 +8,5 @@ Qualcomm

dragonboard410c board debugging + phones diff --git a/doc/board/qualcomm/phones.rst b/doc/board/qualcomm/phones.rst new file mode 100644 index 000000000000..0726f782b675 --- /dev/null +++ b/doc/board/qualcomm/phones.rst @@ -0,0 +1,122 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. sectionauthor:: Caleb Connolly caleb.connolly@linaro.org + +====================================== +Booting U-Boot on Qualcomm smartphones +====================================== + +About this +---------- + +This page attempts to the describe U-Boot support for Qualcomm phones, as a user guide but also a +technical introduction to How Stuff Works to help new porters. + +In broad strokes, U-Boot should boot if the SoC is supported, and the device is already capable of +booting an upstream Linux kernel. + +The list of supported Qualcomm SoCs changes often, for now it is best to look in +``drivers/clk/qcom/`` to get a rough idea. + +For building instructions, see :doc:`board`. + +Phone bringup +------------- + +It is usually easier to get Linux booting first, there are many good resources for this such as the +`postmarketOS wiki`_. Once the device can boot Linux with logs on the display and ideally USB gadget +support, it is highly likely that U-Boot will boot as well. + +For logs on display, you should have a simple framebuffer node defined in your DT, newer devices +require that this follow the downstream naming scheme (that the DTB is compiled with labels enabled +and the framebuffer reserved-memory region is labelled ``cont_splash``). Once this is working in +Linux it should also work in U-Boot. + +In practise, U-Boot still has many more papercuts than Linux, which can be sticking points when +porting a new device. In particular, drivers failing to bind/probe (especially pre-relocation) can +be near-impossible to debug without UART since U-Boot will simply panic with no way to inform you of +the error. As a result, bringing up a new device can be quite frustrating, but there are quite a few +things you can try. + +The phone config +^^^^^^^^^^^^^^^^ + +Since most phones lack a physical keyboard or serial port, a special config fragment and environment +file can be used to provide a more seamless experience. This can be enabled by generating the config +with:: + + make CROSS_COMPILE=aarch64-linux-gnu- O=.output qcom_defconfig qcom-phone.config + +The config and associated environment file can be found in board/qualcomm/. The main changes are: + +- Panic on hang (so the panic message can be read on the display) +- Boot retry (to automatically open and re-open the bootmenu) +- A boot menu with helpful shortcuts (including USB console gadget) +- Launch the boot menu if power is held during boot or on boot failure + +Hang/crash bisection +-------------------- + +Without a way to get logs, we can still get quite far with only a few bits of information: what +happens when you ``fastboot boot u-boot.img``? + +Does the device disconnect? +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This can be verified by watching ``dmesg -w``. It likely means the boot image doesn't match what the +bootloader expected, use ``unpack_bootimg`` to compare it with a known-good boot image (ideally one +with an upstream kernel). + +Does the device hang? +^^^^^^^^^^^^^^^^^^^^^ + +Since ``qcom-phone.config`` enables CONFIG_PANIC_HANG, this likely means that you're successfully +executing U-Boot code (yay!), but something is causing a panic. + +It could also be due to a bad memory or register access triggering a secure interrupt, it's worth +waiting for around a minute to see if the device eventually reboots or goes to crashdump mode. You +can also disable CONFIG_PANIC_HANG and see if that causes the device to reboot instead, if so then +it is definitely a U-Boot panic. + +With enough time and patience, it should be possible to narrow down the cause of the panic by +inserting calls to ``reset_cpu()``. You can then determine where execution stops by seeing if the +device hangs or resets. + +A good place to start is ``board_fdt_blob_setup()`` in ``arch/arm/mach-snapdragon/board.c``, this +function is called extremely early so adding a reset call is a good way to validate that U-Boot is +definitely running. + +You can then do a binary search starting from the end of ``board_init_f()`` / start of +``board_init_r()`` and work from there using the init sequences for reference. + +The Qualcomm RAM parsing code is a likely culprit, as ABL is known to sometimes give bogus entries +in the memory node which can trip U-Boot up. We should eventually handle all of these correctly +upstream. + +To rule out crashes that might be caused by specific drivers, it's a good idea to disable them and +re-enable them one by one. Here is a non-exhaustive list of drivers to disable: + +- pinctrl +- mmc +- scsi/ufs +- usb (dwc3) +- phy +- clk (remove clock references from your framebuffer node in DT) + +Ideally, it would be possible to use the framebuffer as an early console / debug output, at the time +of writing there are out of tree patches for this but they haven't been submitted upstream yet. + +Does the device reboot or go to crashdump mode? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +On many devices crashdump mode is disabled, so they will reboot instead (maybe after some delay). +The same approach as suggested above can be used to figure out where the crash occurs. + +If the device is rebooting, you can insert calls to ``hang()`` instead of ``reset_cpu()`` when +following the instructions above. + +The most likely cause of a crashdump is the pinctrl/gpio driver or the SMMU driver, ensure that the +``apps_smmu`` node in your SoCs devicetree file has one of its compatible strings referenced in +``drivers/iommu/qcom-hyp-smmu.c``, you can also try disabling the pinctrl driver for your SoC (or +``CONFIG_PINCTRL`` altogether). + +.. _`postmarketOS wiki`: https://wiki.postmarketos.org/wiki/Mainlining