[PATCH v4 0/6] Better smartphone support (Qualcomm)

[PATCH v4 0/6] Better smartphone support (Qualcomm)

[Caleb Connolly]

Improve support for running U-Boot on [Qualcomm] smartphones, with:

* A boot menu which can be entered by holding volume down during boot
* Hang on panic (so errors can be read on the display)
* Serial gadget which can be enabled by holding volume down or via
  boot menu

In its current form, U-Boot's boot menu is perfectly adequate, however
once an option is picked U-Boot will never return to the menu, always to
the CLI.

On a phone (with no keyboard), dropping to the CLI effectively makes the
device unusable until manually rebooted, since there is no way to run
any commands...

To rectify this, let's revive CONFIG_BOOT_RETRY for the hush parser and
add an option CONFIG_RETRY_BOOTCMD to run the contents of "bootcmd".
This provides for a flexible menu system which we can enter and exit.
See qcom-phone.env in patch 1 for more details.

Finally, provide some rough-ish documentation to describe how Qualcomm
phone support works and outline some debugging steps for when UART and
the framebuffer are unavailable.

---
Changes in v4
- Enable console recording and "fastboot oem console" support
- Clean up boot menu
- Simplify button_cmds usage, and use Volume Down instead of power
- Make button_get_by_label() case insensitive
- Use better button labels in the qcom-pmic button driver
- Enable the MMC fastboot backend by default since it can be used on
  older devices, or those with an sdcard slot.
- Document fastboot mode and log retrieval
- Link to v3: https://lore.kernel.org/u-boot/20250311-qcom-phones-v2-0-83dcd88a6a87@linaro.org
[v3 was accidentally sent as "v2" a second time]

Changes in v3:
- Minor wording/clarification improvements in docs
- Introduce CONFIG_RETRY_BOOTCMD rather than changing the default
  behaviour.
- Enable some more gadgets in the phone config fragment.
- Link to v2: https://lore.kernel.org/u-boot/20241004-qcom-phones-v2-0-c7ab67ac3043@linaro.org

Changes in v2:
- Fix CONFIG_BUTTON_REMAP_PHONE_KEYS name in qcom-phone.config
- Add Tom and Simon to CC
- Link to v1: https://lore.kernel.org/r/20240831-qcom-phones-v1-0-08614edd8e35@linaro.org

---
Caleb Connolly (6):
      board/qualcomm: introduce phone config
      cli_hush: support running bootcmd on boot retry
      bootretry: check for bootretry variable changes
      doc: board/qualcomm: describe phone support and bringup
      button: qcom-pmic: prettify and standardise button labels
      button: make button_get_by_label() case insensitive

 board/qualcomm/dragonboard410c/dragonboard410c.c |   2 +-
 board/qualcomm/dragonboard820c/dragonboard820c.c |   2 +-
 board/qualcomm/qcom-phone.config                 |  29 +++++
 board/qualcomm/qcom-phone.env                    |  47 ++++++++
 boot/Kconfig                                     |   7 ++
 boot/bootretry.c                                 |   2 +
 common/cli_hush.c                                |   6 +-
 common/cli_hush_upstream.c                       |   6 +-
 doc/board/qualcomm/board.rst                     |   5 +
 doc/board/qualcomm/index.rst                     |   1 +
 doc/board/qualcomm/phones.rst                    | 144 +++++++++++++++++++++++
 drivers/button/button-qcom-pmic.c                |   8 +-
 drivers/button/button-uclass.c                   |   2 +-
 13 files changed, 250 insertions(+), 11 deletions(-)
---
base-commit: 96f6ab64e1bc897d26649d15365f6d9970ccb1c0

Caleb Connolly <caleb.connolly@linaro.org>

[PATCH v4 1/6] board/qualcomm: introduce phone config

[Caleb Connolly]

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.

Reviewed-by: Simon Glass <sjg@chromium.org>
Tested-by: Danila Tikhonov <danila@jiaxyga.com> # google-sunfish
Tested-by: Jens Reidel <adrian@mainlining.org> # xiaomi-davinci
Signed-off-by: Caleb Connolly <caleb.connolly@linaro.org>
---
 board/qualcomm/qcom-phone.config | 29 +++++++++++++++++++++++++
 board/qualcomm/qcom-phone.env    | 47 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 76 insertions(+)

diff --git a/board/qualcomm/qcom-phone.config b/board/qualcomm/qcom-phone.config
new file mode 100644
index 0000000000000000000000000000000000000000..913c91757c1d77b79b5997597917f9ac002049fb
--- /dev/null
+++ b/board/qualcomm/qcom-phone.config
@@ -0,0 +1,29 @@
+# Settings for phones
+CONFIG_DEFAULT_ENV_FILE="board/qualcomm/qcom-phone.env"
+# Hang on panic so the error message can be read
+CONFIG_PANIC_HANG=y
+# We use pause in various places to allow text to be read
+# before it scrolls off the screen
+CONFIG_CMD_PAUSE=y
+CONFIG_BOOT_RETRY=y
+CONFIG_BOOT_RETRY_TIME=1
+CONFIG_BUTTON_REMAP_PHONE_KEYS=y
+CONFIG_RETRY_BOOTCMD=y
+CONFIG_FASTBOOT_BUF_ADDR=0x1A000000
+CONFIG_USB_FUNCTION_FASTBOOT=y
+CONFIG_USB_FUNCTION_ACM=y
+CONFIG_CMD_UMS_ABORT_KEYED=y
+
+# Record all console output and let it be dumped via fastboot
+CONFIG_CONSOLE_RECORD=y
+CONFIG_CONSOLE_RECORD_INIT_F=y
+CONFIG_CONSOLE_RECORD_OUT_SIZE=0x6000
+CONFIG_FASTBOOT_CMD_OEM_CONSOLE=y
+
+# Only MMC is supported by fastboot currently, but this is still useful.
+CONFIG_FASTBOOT_FLASH=y
+CONFIG_FASTBOOT_FLASH_MMC_DEV=0
+CONFIG_FASTBOOT_OEM_RUN=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 0000000000000000000000000000000000000000..6750b6daaed8695faa2fbe1546c1582713f7d56f
--- /dev/null
+++ b/board/qualcomm/qcom-phone.env
@@ -0,0 +1,47 @@
+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
+
+# Always probe for UFS storage, though it should be done by board code.
+preboot=scsi scan
+
+# 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=echo "Press any key to exit UMS mode"; ums 0 scsi 0
+bootmenu_3=Enable fastboot mode=run fastboot
+# Disabling bootretry means we'll just drop the shell
+bootmenu_4=Drop to shell=setenv bootretry -1
+bootmenu_5=Reset device=reset
+bootmenu_6=Dump clocks=clk dump; pause
+bootmenu_7=Dump environment=printenv; pause
+bootmenu_8=Board info=bdinfo; pause
+bootmenu_9=Dump bootargs=fdt print /chosen bootargs; pause
+
+# Allow holding the power button while U-Boot loads to enter
+# the boot menu
+button_cmd_0_name=Volume Down
+button_cmd_0=run menucmd

-- 
2.49.0

Re: [PATCH v4 1/6] board/qualcomm: introduce phone config

[Sam Day]

G'day Caleb,

On Mon Mar 31, 2025 at 2:23 PM CEST, Caleb Connolly wrote:
> 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.
>
> Reviewed-by: Simon Glass <sjg@chromium.org>
> Tested-by: Danila Tikhonov <danila@jiaxyga.com> # google-sunfish
> Tested-by: Jens Reidel <adrian@mainlining.org> # xiaomi-davinci
> Signed-off-by: Caleb Connolly <caleb.connolly@linaro.org>
> ---
>  board/qualcomm/qcom-phone.config | 29 +++++++++++++++++++++++++
>  board/qualcomm/qcom-phone.env    | 47 ++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 76 insertions(+)
>
> diff --git a/board/qualcomm/qcom-phone.config b/board/qualcomm/qcom-phone.config
> new file mode 100644
> index 0000000000000000000000000000000000000000..913c91757c1d77b79b5997597917f9ac002049fb
> --- /dev/null
> +++ b/board/qualcomm/qcom-phone.config
> @@ -0,0 +1,29 @@
> +# Settings for phones
> +CONFIG_DEFAULT_ENV_FILE="board/qualcomm/qcom-phone.env"
> +# Hang on panic so the error message can be read
> +CONFIG_PANIC_HANG=y
> +# We use pause in various places to allow text to be read
> +# before it scrolls off the screen
> +CONFIG_CMD_PAUSE=y
> +CONFIG_BOOT_RETRY=y
> +CONFIG_BOOT_RETRY_TIME=1
> +CONFIG_BUTTON_REMAP_PHONE_KEYS=y
> +CONFIG_RETRY_BOOTCMD=y
> +CONFIG_FASTBOOT_BUF_ADDR=0x1A000000
> +CONFIG_USB_FUNCTION_FASTBOOT=y
> +CONFIG_USB_FUNCTION_ACM=y
> +CONFIG_CMD_UMS_ABORT_KEYED=y
> +
> +# Record all console output and let it be dumped via fastboot
> +CONFIG_CONSOLE_RECORD=y
> +CONFIG_CONSOLE_RECORD_INIT_F=y
> +CONFIG_CONSOLE_RECORD_OUT_SIZE=0x6000
> +CONFIG_FASTBOOT_CMD_OEM_CONSOLE=y
> +
> +# Only MMC is supported by fastboot currently, but this is still useful.
> +CONFIG_FASTBOOT_FLASH=y
> +CONFIG_FASTBOOT_FLASH_MMC_DEV=0
> +CONFIG_FASTBOOT_OEM_RUN=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 0000000000000000000000000000000000000000..6750b6daaed8695faa2fbe1546c1582713f7d56f
> --- /dev/null
> +++ b/board/qualcomm/qcom-phone.env
> @@ -0,0 +1,47 @@
> +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
> +
> +# Always probe for UFS storage, though it should be done by board code.
> +preboot=scsi scan
> +
> +# 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=echo "Press any key to exit UMS mode"; ums 0 scsi 0
> +bootmenu_3=Enable fastboot mode=run fastboot
> +# Disabling bootretry means we'll just drop the shell
> +bootmenu_4=Drop to shell=setenv bootretry -1
> +bootmenu_5=Reset device=reset
> +bootmenu_6=Dump clocks=clk dump; pause
> +bootmenu_7=Dump environment=printenv; pause
> +bootmenu_8=Board info=bdinfo; pause
> +bootmenu_9=Dump bootargs=fdt print /chosen bootargs; pause
> +
> +# Allow holding the power button while U-Boot loads to enter

Comment should mention vol-down rather than pwrkey. I also noticed that
the cover letter still mentions the vol-down serial gadget path which is
dropped now.

Cheers,
-Sam

> +# the boot menu
> +button_cmd_0_name=Volume Down
> +button_cmd_0=run menucmd

[PATCH v4 2/6] cli_hush: support running bootcmd on boot retry

[Caleb Connolly]

Introduce a new config option: RETRY_BOOTCMD. When enabled this causes
hush shell to re-run "bootcmd" when the auto-boot counter times out.

Tested-by: Danila Tikhonov <danila@jiaxyga.com> # google-sunfish
Tested-by: Jens Reidel <adrian@mainlining.org> # xiaomi-davinci
Signed-off-by: Caleb Connolly <caleb.connolly@linaro.org>
---
 boot/Kconfig               | 7 +++++++
 common/cli_hush.c          | 6 ++++--
 common/cli_hush_upstream.c | 6 ++++--
 3 files changed, 15 insertions(+), 4 deletions(-)

diff --git a/boot/Kconfig b/boot/Kconfig
index c09a98c3233ceb1c68024a193d7dafdce6b83903..4db13dcb9a51940c358f754d9ff91e88bebd96b1 100644
--- a/boot/Kconfig
+++ b/boot/Kconfig
@@ -1711,8 +1711,15 @@ config RESET_TO_RETRY
 	help
 	  After the countdown timed out, the board will be reset to restart
 	  again.
 
+config RETRY_BOOTCMD
+	bool "Run bootcmd on retry"
+	depends on BOOT_RETRY && HUSH_PARSER && !RESET_TO_RETRY
+	help
+	  If this option is enabled, the "bootcmd" will be run after the
+	  countdown times out.
+
 endmenu
 
 menu "Image support"
 
diff --git a/common/cli_hush.c b/common/cli_hush.c
index 9f437ae5f475e2f33041485e88d72c9bb71ab309..7bd6943d3ed65bb24c709af0b195825a26d65f39 100644
--- a/common/cli_hush.c
+++ b/common/cli_hush.c
@@ -1027,10 +1027,12 @@ static void get_user_input(struct in_str *i)
 	if (n == -2) {
 	  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"
+#  elif IS_ENABLED(CONFIG_RETRY_BOOTCMD)
+	strcpy(console_buffer, "run bootcmd\n");
+# else
+#	error "This only works with CONFIG_RESET_TO_RETRY or CONFIG_BOOT_RETRY_COMMAND enabled"
 #  endif
 	}
 #endif
 	if (n == -1 ) {
diff --git a/common/cli_hush_upstream.c b/common/cli_hush_upstream.c
index ab5aa5f9b36a91e09f8fcfcbb8b31afa0892e6bc..748ef60ac90b8af8052631c7ad3a6aed2629140b 100644
--- a/common/cli_hush_upstream.c
+++ b/common/cli_hush_upstream.c
@@ -2906,10 +2906,12 @@ static void get_user_input(struct in_str *i)
 	if (n == -2) {
 		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"
+#  elif IS_ENABLED(CONFIG_RETRY_BOOTCMD)
+	strcpy(console_buffer, "run bootcmd\n");
+# else
+#	error "This only works with CONFIG_RESET_TO_RETRY or CONFIG_BOOT_RETRY_COMMAND enabled"
 #  endif
 	}
 # endif
 	if (n == -1 ) {

-- 
2.49.0

[PATCH v4 3/6] bootretry: check for bootretry variable changes

[Caleb Connolly]

To enable more complex sequencing of the bootmenu, autoboot, and
bootretry, handle changes to the bootretry variable between tries. This
makes it possible to turn bootretry off (e.g. to drop to a shell) and
then back on again.

This makes it possible to have a persistent bootmenu (the only way to
navigate U-Boot on devices like smartphones which lack a physical
keyboard) by having bootcmd be defined to launch the bootmenu. This
allows for menu options like enabling USB mass storage gadget to return
back to the boot menu once the gadget is shut down.

Reviewed-by: Tom Rini <trini@konsulko.com>
Tested-by: Danila Tikhonov <danila@jiaxyga.com> # google-sunfish
Tested-by: Jens Reidel <adrian@mainlining.org> # xiaomi-davinci
Signed-off-by: Caleb Connolly <caleb.connolly@linaro.org>
---
 boot/bootretry.c | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/boot/bootretry.c b/boot/bootretry.c
index 587b2de7d6b08db07e1dea512a834cb5590c2d12..a60767eaa2ee51970e4695e487ce5651575079ba 100644
--- a/boot/bootretry.c
+++ b/boot/bootretry.c
@@ -36,8 +36,10 @@ void bootretry_init_cmd_timeout(void)
  * reset command line timeout to retry_time seconds
  */
 void bootretry_reset_cmd_timeout(void)
 {
+	/* Parse changes to bootretry */
+	bootretry_init_cmd_timeout();
 	endtime = endtick(retry_time);
 }
 
 int bootretry_tstc_timeout(void)

-- 
2.49.0

[PATCH v4 4/6] doc: board/qualcomm: describe phone support and bringup

[Caleb Connolly]

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.

Reviewed-by: Simon Glass <sjg@chromium.org>
Tested-by: Danila Tikhonov <danila@jiaxyga.com> # google-sunfish
Tested-by: Jens Reidel <adrian@mainlining.org> # xiaomi-davinci
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 | 144 ++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 150 insertions(+)

diff --git a/doc/board/qualcomm/board.rst b/doc/board/qualcomm/board.rst
index 4d793209f9e31e6447c696ccd07af206dba99645..003d59a18ebd3f19db568fa59e9fd06906e209f2 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 66bc922033a2e30a472db5b5c7dc6c8511f50ed8..e2fcbfa19c2fff36c8551823ca4a53a5fdc7fa9a 100644
--- a/doc/board/qualcomm/index.rst
+++ b/doc/board/qualcomm/index.rst
@@ -8,6 +8,7 @@ Qualcomm
 
    dragonboard410c
    rb3gen2
    board
+   phones
    debugging
    rdp
diff --git a/doc/board/qualcomm/phones.rst b/doc/board/qualcomm/phones.rst
new file mode 100644
index 0000000000000000000000000000000000000000..1d27196cf54018b393f3cbc914d0cd26e7f0d8dd
--- /dev/null
+++ b/doc/board/qualcomm/phones.rst
@@ -0,0 +1,144 @@
+.. 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 tricky 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
+
+Fastboot mode
+-------------
+
+U-Boot's fastboot implementation is much more limited than Qualcomm's, and currently does not have a
+backend for UFS storage. If your device uses eMMC or has an sdcard slot, fastboot will use that by
+default.
+
+You may need to run the fastboot command on your PC as root since the USB product/vendor ID may not
+match the android udev rules.
+
+You can also use fastboot to run arbitrary U-Boot commands with ``fastboot oem run``
+
+Retrieving early logs
+^^^^^^^^^^^^^^^^^^^^^
+
+U-Boot is configured to save it's internal log to a buffer, this can help with debugging some driver
+bind/probe issues. If your device can boot and has working USB, you can enable fastboot mode (either
+via the U-Boot menu or by adding ``run fastboot`` to the end of the ``preboot=`` config in
+``board/qualcomm/qcom-phone.env``).
+
+You can then retrieve U-Boot's log buffer with the ``fastboot oem log`` command on your PC.
+
+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``. If it stays connected, 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?
+^^^^^^^^^^^^^^^^^^^^^
+
+If it stays on a black screen and does nothing, then that's a 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()`` (with CONFIG_PANIC_HANG enabled). Then if the device resets you
+know it executed the ``reset_cpu()`` call.
+
+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.
+
+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 (usb, ufs)
+- 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

-- 
2.49.0

[PATCH v4 5/6] button: qcom-pmic: prettify and standardise button labels

[Caleb Connolly]

Boards using gpio-keys for volume buttons label them "Volume Down",
let's match that here, and make the power button nicer too.

This simplifies configuring button_cmds in a board-agnostic way.

Tested-by: Danila Tikhonov <danila@jiaxyga.com> # google-sunfish
Tested-by: Jens Reidel <adrian@mainlining.org> # xiaomi-davinci
Signed-off-by: Caleb Connolly <caleb.connolly@linaro.org>
---
 board/qualcomm/dragonboard410c/dragonboard410c.c | 2 +-
 board/qualcomm/dragonboard820c/dragonboard820c.c | 2 +-
 drivers/button/button-qcom-pmic.c                | 8 ++++----
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/board/qualcomm/dragonboard410c/dragonboard410c.c b/board/qualcomm/dragonboard410c/dragonboard410c.c
index fcbf2c3fe60f21bae1c6d64b542a4d9867c33826..d0d82489f53c4f31b7b08bcf6e4269730027874a 100644
--- a/board/qualcomm/dragonboard410c/dragonboard410c.c
+++ b/board/qualcomm/dragonboard410c/dragonboard410c.c
@@ -71,9 +71,9 @@ int misc_init_r(void)
 	struct udevice *btn;
 	int ret;
 	enum button_state_t state;
 
-	ret = button_get_by_label("vol_down", &btn);
+	ret = button_get_by_label("Volume Down", &btn);
 	if (ret < 0) {
 		printf("Couldn't find power button!\n");
 		return ret;
 	}
diff --git a/board/qualcomm/dragonboard820c/dragonboard820c.c b/board/qualcomm/dragonboard820c/dragonboard820c.c
index d3333a59db01caa940224a99df6b43a3375cacf8..12a9273ec4b9d240bc2eaed2834d5265290153ec 100644
--- a/board/qualcomm/dragonboard820c/dragonboard820c.c
+++ b/board/qualcomm/dragonboard820c/dragonboard820c.c
@@ -105,9 +105,9 @@ int misc_init_r(void)
 	struct udevice *btn;
 	int ret;
 	enum button_state_t state;
 
-	ret = button_get_by_label("pwrkey", &btn);
+	ret = button_get_by_label("Power Button", &btn);
 	if (ret < 0) {
 		printf("Couldn't find power button!\n");
 		return ret;
 	}
diff --git a/drivers/button/button-qcom-pmic.c b/drivers/button/button-qcom-pmic.c
index f9f0948ae095f433e35ecfc0f98741ab1a850742..e3bb9bd758aca819b3a10aac84787e703c55d36a 100644
--- a/drivers/button/button-qcom-pmic.c
+++ b/drivers/button/button-qcom-pmic.c
@@ -72,27 +72,27 @@ static const struct qcom_pmic_btn_data qcom_pmic_btn_data_table[] = {
 	{
 		.compatible = "qcom,pm8941-pwrkey",
 		.status_bit = PON_KPDPWR_N_SET,
 		.code = KEY_ENTER,
-		.label = "pwrkey",
+		.label = "Power Button",
 	},
 	{
 		.compatible = "qcom,pm8941-resin",
 		.status_bit = PON_RESIN_N_SET,
 		.code = KEY_DOWN,
-		.label = "vol_down",
+		.label = "Volume Down",
 	},
 	{
 		.compatible = "qcom,pmk8350-pwrkey",
 		.status_bit = PON_GEN3_KPDPWR_N_SET,
 		.code = KEY_ENTER,
-		.label = "pwrkey",
+		.label = "Power Button",
 	},
 	{
 		.compatible = "qcom,pmk8350-resin",
 		.status_bit = PON_GEN3_RESIN_N_SET,
 		.code = KEY_DOWN,
-		.label = "vol_down",
+		.label = "Volume Down",
 	},
 };
 
 static const struct qcom_pmic_btn_data *button_qcom_pmic_match(ofnode node)

-- 
2.49.0

Re: [PATCH v4 5/6] button: qcom-pmic: prettify and standardise button labels

[Neil Armstrong]

On 31/03/2025 14:23, Caleb Connolly wrote:
> Boards using gpio-keys for volume buttons label them "Volume Down",
> let's match that here, and make the power button nicer too.
> 
> This simplifies configuring button_cmds in a board-agnostic way.
> 
> Tested-by: Danila Tikhonov <danila@jiaxyga.com> # google-sunfish
> Tested-by: Jens Reidel <adrian@mainlining.org> # xiaomi-davinci
> Signed-off-by: Caleb Connolly <caleb.connolly@linaro.org>
> ---
>   board/qualcomm/dragonboard410c/dragonboard410c.c | 2 +-
>   board/qualcomm/dragonboard820c/dragonboard820c.c | 2 +-
>   drivers/button/button-qcom-pmic.c                | 8 ++++----
>   3 files changed, 6 insertions(+), 6 deletions(-)
> 
> diff --git a/board/qualcomm/dragonboard410c/dragonboard410c.c b/board/qualcomm/dragonboard410c/dragonboard410c.c
> index fcbf2c3fe60f21bae1c6d64b542a4d9867c33826..d0d82489f53c4f31b7b08bcf6e4269730027874a 100644
> --- a/board/qualcomm/dragonboard410c/dragonboard410c.c
> +++ b/board/qualcomm/dragonboard410c/dragonboard410c.c
> @@ -71,9 +71,9 @@ int misc_init_r(void)
>   	struct udevice *btn;
>   	int ret;
>   	enum button_state_t state;
>   
> -	ret = button_get_by_label("vol_down", &btn);
> +	ret = button_get_by_label("Volume Down", &btn);
>   	if (ret < 0) {
>   		printf("Couldn't find power button!\n");
>   		return ret;
>   	}
> diff --git a/board/qualcomm/dragonboard820c/dragonboard820c.c b/board/qualcomm/dragonboard820c/dragonboard820c.c
> index d3333a59db01caa940224a99df6b43a3375cacf8..12a9273ec4b9d240bc2eaed2834d5265290153ec 100644
> --- a/board/qualcomm/dragonboard820c/dragonboard820c.c
> +++ b/board/qualcomm/dragonboard820c/dragonboard820c.c
> @@ -105,9 +105,9 @@ int misc_init_r(void)
>   	struct udevice *btn;
>   	int ret;
>   	enum button_state_t state;
>   
> -	ret = button_get_by_label("pwrkey", &btn);
> +	ret = button_get_by_label("Power Button", &btn);
>   	if (ret < 0) {
>   		printf("Couldn't find power button!\n");
>   		return ret;
>   	}
> diff --git a/drivers/button/button-qcom-pmic.c b/drivers/button/button-qcom-pmic.c
> index f9f0948ae095f433e35ecfc0f98741ab1a850742..e3bb9bd758aca819b3a10aac84787e703c55d36a 100644
> --- a/drivers/button/button-qcom-pmic.c
> +++ b/drivers/button/button-qcom-pmic.c
> @@ -72,27 +72,27 @@ static const struct qcom_pmic_btn_data qcom_pmic_btn_data_table[] = {
>   	{
>   		.compatible = "qcom,pm8941-pwrkey",
>   		.status_bit = PON_KPDPWR_N_SET,
>   		.code = KEY_ENTER,
> -		.label = "pwrkey",
> +		.label = "Power Button",
>   	},
>   	{
>   		.compatible = "qcom,pm8941-resin",
>   		.status_bit = PON_RESIN_N_SET,
>   		.code = KEY_DOWN,
> -		.label = "vol_down",
> +		.label = "Volume Down",
>   	},
>   	{
>   		.compatible = "qcom,pmk8350-pwrkey",
>   		.status_bit = PON_GEN3_KPDPWR_N_SET,
>   		.code = KEY_ENTER,
> -		.label = "pwrkey",
> +		.label = "Power Button",
>   	},
>   	{
>   		.compatible = "qcom,pmk8350-resin",
>   		.status_bit = PON_GEN3_RESIN_N_SET,
>   		.code = KEY_DOWN,
> -		.label = "vol_down",
> +		.label = "Volume Down",
>   	},
>   };
>   
>   static const struct qcom_pmic_btn_data *button_qcom_pmic_match(ofnode node)
> 

Reviewed-by: Neil Armstrong <neil.armstrong@linaro.org>

[PATCH v4 6/6] button: make button_get_by_label() case insensitive

[Caleb Connolly]

This function is already doing a fuzzy match, since there are no
guarantees that a given label is unique.

Ignoring case makes it much easier to catch "Volume down" or "Volume
Down" in board-agnostic code.

Tested-by: Danila Tikhonov <danila@jiaxyga.com> # google-sunfish
Tested-by: Jens Reidel <adrian@mainlining.org> # xiaomi-davinci
Signed-off-by: Caleb Connolly <caleb.connolly@linaro.org>
---
 drivers/button/button-uclass.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/button/button-uclass.c b/drivers/button/button-uclass.c
index 729983d58701867f7ea18e9b5f87e7404bca3dce..025917887e80f2fe9cbd3777e04035d20fa34713 100644
--- a/drivers/button/button-uclass.c
+++ b/drivers/button/button-uclass.c
@@ -20,9 +20,9 @@ int button_get_by_label(const char *label, struct udevice **devp)
 	uclass_id_foreach_dev(UCLASS_BUTTON, dev, uc) {
 		struct button_uc_plat *uc_plat = dev_get_uclass_plat(dev);
 
 		/* Ignore the top-level button node */
-		if (uc_plat->label && !strcmp(label, uc_plat->label))
+		if (uc_plat->label && !strcasecmp(label, uc_plat->label))
 			return uclass_get_device_tail(dev, 0, devp);
 	}
 
 	return -ENODEV;

-- 
2.49.0

Re: [PATCH v4 6/6] button: make button_get_by_label() case insensitive

[Neil Armstrong]

On 31/03/2025 14:23, Caleb Connolly wrote:
> This function is already doing a fuzzy match, since there are no
> guarantees that a given label is unique.
> 
> Ignoring case makes it much easier to catch "Volume down" or "Volume
> Down" in board-agnostic code.
> 
> Tested-by: Danila Tikhonov <danila@jiaxyga.com> # google-sunfish
> Tested-by: Jens Reidel <adrian@mainlining.org> # xiaomi-davinci
> Signed-off-by: Caleb Connolly <caleb.connolly@linaro.org>
> ---
>   drivers/button/button-uclass.c | 2 +-
>   1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/drivers/button/button-uclass.c b/drivers/button/button-uclass.c
> index 729983d58701867f7ea18e9b5f87e7404bca3dce..025917887e80f2fe9cbd3777e04035d20fa34713 100644
> --- a/drivers/button/button-uclass.c
> +++ b/drivers/button/button-uclass.c
> @@ -20,9 +20,9 @@ int button_get_by_label(const char *label, struct udevice **devp)
>   	uclass_id_foreach_dev(UCLASS_BUTTON, dev, uc) {
>   		struct button_uc_plat *uc_plat = dev_get_uclass_plat(dev);
>   
>   		/* Ignore the top-level button node */
> -		if (uc_plat->label && !strcmp(label, uc_plat->label))
> +		if (uc_plat->label && !strcasecmp(label, uc_plat->label))
>   			return uclass_get_device_tail(dev, 0, devp);
>   	}
>   
>   	return -ENODEV;
> 

Reviewed-by: Neil Armstrong <neil.armstrong@linaro.org>

Re: [PATCH v4 0/6] Better smartphone support (Qualcomm)

[Caleb Connolly]

On Mon, 31 Mar 2025 14:23:17 +0200, Caleb Connolly wrote:
> Improve support for running U-Boot on [Qualcomm] smartphones, with:
> 
> * A boot menu which can be entered by holding volume down during boot
> * Hang on panic (so errors can be read on the display)
> * Serial gadget which can be enabled by holding volume down or via
>   boot menu
> 
> [...]

Applied, thanks!

[1/6] board/qualcomm: introduce phone config
      https://source.denx.de/u-boot/custodians/u-boot-snapdragon/-/commit/fd775fb7aff8
[2/6] cli_hush: support running bootcmd on boot retry
      https://source.denx.de/u-boot/custodians/u-boot-snapdragon/-/commit/657e19f8f2dd
[3/6] bootretry: check for bootretry variable changes
      https://source.denx.de/u-boot/custodians/u-boot-snapdragon/-/commit/aa5ef3c0a752
[4/6] doc: board/qualcomm: describe phone support and bringup
      https://source.denx.de/u-boot/custodians/u-boot-snapdragon/-/commit/4509f8183970
[5/6] button: qcom-pmic: prettify and standardise button labels
      https://source.denx.de/u-boot/custodians/u-boot-snapdragon/-/commit/8f5685d5d32f
[6/6] button: make button_get_by_label() case insensitive
      https://source.denx.de/u-boot/custodians/u-boot-snapdragon/-/commit/9c607005c519

Best regards,
-- 
Caleb Connolly <caleb.connolly@linaro.org>