diff mbox series

[v4,25/39] doc: board/qualcomm: document generic targets

Message ID 20240215-b4-qcom-common-target-v4-25-ed06355c634a@linaro.org
State Superseded
Headers show
Series Qualcomm generic board support | expand

Commit Message

Caleb Connolly Feb. 15, 2024, 8:52 p.m. UTC
Replace the board specific docs with a generic board.rst file which
documents the build/boot process for the sdm845 and qcs404 boards now
that the only differences are the DTB in use.

At the same time, create a debugging page to document some useful
snippets and tips for working with Qualcomm platforms.

Reviewed-by: Neil Armstrong <neil.armstrong@linaro.org>
Signed-off-by: Caleb Connolly <caleb.connolly@linaro.org>
---
 doc/board/qualcomm/board.rst     | 125 +++++++++++++++++++++++++++++
 doc/board/qualcomm/debugging.rst |  61 ++++++++++++++
 doc/board/qualcomm/index.rst     |   4 +-
 doc/board/qualcomm/qcs404.rst    |  79 ------------------
 doc/board/qualcomm/sdm845.rst    | 167 ---------------------------------------
 5 files changed, 188 insertions(+), 248 deletions(-)

Comments

Sumit Garg Feb. 20, 2024, 1:55 p.m. UTC | #1
On Fri, 16 Feb 2024 at 02:22, Caleb Connolly <caleb.connolly@linaro.org> wrote:
>
> Replace the board specific docs with a generic board.rst file which
> documents the build/boot process for the sdm845 and qcs404 boards now
> that the only differences are the DTB in use.
>
> At the same time, create a debugging page to document some useful
> snippets and tips for working with Qualcomm platforms.
>
> Reviewed-by: Neil Armstrong <neil.armstrong@linaro.org>
> Signed-off-by: Caleb Connolly <caleb.connolly@linaro.org>
> ---
>  doc/board/qualcomm/board.rst     | 125 +++++++++++++++++++++++++++++
>  doc/board/qualcomm/debugging.rst |  61 ++++++++++++++
>  doc/board/qualcomm/index.rst     |   4 +-
>  doc/board/qualcomm/qcs404.rst    |  79 ------------------
>  doc/board/qualcomm/sdm845.rst    | 167 ---------------------------------------
>  5 files changed, 188 insertions(+), 248 deletions(-)
>

Apart from minor nits below, feel free to add:

Reviewed-by: Sumit Garg <sumit.garg@linaro.org>

-Sumit

> diff --git a/doc/board/qualcomm/board.rst b/doc/board/qualcomm/board.rst
> new file mode 100644
> index 000000000000..4d793209f9e3
> --- /dev/null
> +++ b/doc/board/qualcomm/board.rst
> @@ -0,0 +1,125 @@
> +.. SPDX-License-Identifier: GPL-2.0+
> +.. sectionauthor:: Dzmitry Sankouski <dsankouski@gmail.com>
> +
> +Qualcomm generic boards
> +=======================
> +
> +About this
> +----------
> +This document describes how to build and run U-Boot for Qualcomm generic
> +boards. Right now the generic target supports the Snapdragon 845 SoC, however
> +it's expected to support more SoCs going forward.
> +
> +SDM845 - high-end qualcomm chip, introduced in late 2017.
> +Mostly used in flagship phones and tablets of 2018.
> +
> +The current boot flow support loading u-boot as an Android boot image via

s/support/supports/

> +Qualcomm's UEFI-based ABL (Android) Bootloader. The DTB used by U-Boot will
> +be appended to the U-Boot image the same way as when booting Linux. U-Boot
> +will then retrieve the DTB during init. This way the memory layout and KASLR
> +offset will be populated by ABL.
> +
> +Installation
> +------------
> +Build
> +^^^^^
> +
> +       $ ./tools/buildman/buildman -o .output qcom
> +
> +This will build ``.output/u-boot-nodtb.bin`` using the ``qcom_defconfig``.
> +
> +Generate FIT image (optional)
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +See doc/uImage.FIT for more details
> +
> +Pack android boot image
> +^^^^^^^^^^^^^^^^^^^^^^^
> +We'll assemble android boot image with ``u-boot-nodtb.bin`` instead of linux kernel,
> +and FIT image instead of ``initramfs``. Android bootloader expect gzipped kernel

s/expect/expects/

> +with appended dtb, so let's mimic linux to satisfy stock bootloader.
> +
> +Boards
> +------
> +
> +starqlte
> +^^^^^^^^
> +
> +The starqltechn is a production board for Samsung S9 (SM-G9600) phone,
> +based on the Qualcomm SDM845 SoC.
> +
> +This device is supported by the common qcom_defconfig.
> +
> +The DTB is called "sdm845-samsung-starqltechn.dtb"
> +
> +More information can be found on the `Samsung S9 page`_.
> +
> +dragonboard845c
> +^^^^^^^^^^^^^^^
> +
> +The dragonboard845c is a Qualcomm Robotics RB3 Development Platform, based on
> +the Qualcomm SDM845 SoC.
> +
> +This device is supported by the common qcom_defconfig
> +
> +The DTB is called "sdm845-db845c.dtb"
> +
> +More information can be found on the `DragonBoard 845c page`_.
> +
> +qcs404-evb
> +^^^^^^^^^^
> +
> +The QCS404 EvB is a Qualcomm Development Platform, based on the Qualcomm QCS404 SoC.
> +
> +This device is supported by the common qcom_defconfig
> +
> +The DTB is called "qcs404-evb-4000.dtb"
> +
> +Building steps
> +--------------
> +
> +Steps:
> +
> +- Build u-boot
> +
> +As above::
> +
> +       ./tools/buildman/buildman -o .output qcom
> +
> +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)
> +
> +- gzip u-boot::
> +
> +       gzip u-boot-nodtb.bin
> +
> +- Append dtb to gzipped u-boot::
> +
> +       cat u-boot-nodtb.bin.gz arch/arm/dts/your-board.dtb > u-boot-nodtb.bin.gz-dtb
> +
> +- If you chose to build a FIT image, A ``qcom.its`` file can be found in ``board/qualcomm/generic/``

s/chose/choose/


> +  directory. It expects a folder as ``qcom_imgs/`` in the main directory containing pre-built kernel,
> +  dts and ramdisk images. See ``qcom.its`` for full path to images::
> +
> +       mkimage -f qcom.its qcom.itb
> +
> +- Now we've got everything to build android boot image::
> +
> +       mkbootimg --kernel u-boot-nodtb.bin.gz-dtb --ramdisk db845c.itb \
> +       --output boot.img --pagesize 4096 --base 0x80000000
> +
> +Or with no FIT image::
> +
> +       mkbootimg --kernel u-boot-nodtb.bin.gz-dtb \
> +       --output boot.img --pagesize 4096 --base 0x80000000
> +
> +- Flash boot.img using fastboot and erase dtbo to avoid conflicts with our DTB:
> +
> +  .. code-block:: bash
> +
> +       fastboot flash boot boot.img
> +       fastboot erase dtbo
> +
> +.. _Samsung S9 page: https://en.wikipedia.org/wiki/Samsung_Galaxy_S9
> +.. _DragonBoard 845c page: https://www.96boards.org/product/rb3-platform/
> diff --git a/doc/board/qualcomm/debugging.rst b/doc/board/qualcomm/debugging.rst
> new file mode 100644
> index 000000000000..1c35d1909d12
> --- /dev/null
> +++ b/doc/board/qualcomm/debugging.rst
> @@ -0,0 +1,61 @@
> +.. SPDX-License-Identifier: GPL-2.0+
> +.. sectionauthor:: Caleb Connolly <caleb.connolly@linaro.org>
> +
> +Qualcomm debugging
> +==================
> +
> +About this
> +----------
> +
> +This page describes how to enable early UART and other debugging techniques
> +for Qualcomm boards.
> +
> +Enable debug UART
> +-----------------
> +
> +Newer boards (SDM845 and newer, those with GENI SE UART)
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +Open ``configs/qcom_defconfig`` and add the following snippet to the bottom:
> +
> +       CONFIG_BAUDRATE=115200
> +
> +       # Uncomment to enable UART pre-relocation
> +       CONFIG_DEBUG_UART=y
> +       CONFIG_DEBUG_UART_ANNOUNCE=y
> +       # This is the address of the debug-uart peripheral
> +       # The value here is for SDM845, other platforms will vary
> +       CONFIG_DEBUG_UART_BASE=0xa84000
> +       # Boards older than ~2018 pre-date the GENI driver and unfortunately
> +       # aren't supported here
> +       CONFIG_DEBUG_UART_MSM_GENI=y
> +       # For sdm845 this is the UART clock rate
> +       CONFIG_DEBUG_UART_CLOCK=7372800
> +       # Most newer boards have an oversampling value of 16 instead
> +       # of 32, they need the clock rate to be doubled
> +       #CONFIG_DEBUG_UART_CLOCK=14745600
> +
> +Then build as normal (don't forget to ``make qcom_defconfig``` again).
> +
> +Older boards (db410c and db820c)
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +Open ``configs/dragonboard<BOARD>_defconfig``
> +

In case you don't plan to enable debug UART when U-Boot is the first
stage bootloader then it should atleast be documented here that only
chainloaded configuration supports it.

-Sumit

> +       CONFIG_BAUDRATE=115200
> +       CONFIG_DEBUG_UART=y
> +       CONFIG_DEBUG_UART_ANNOUNCE=y
> +       # db410c - 0x78b0000
> +       # db820c - 0x75b0000
> +       CONFIG_DEBUG_UART_BASE=0x75b0000
> +       CONFIG_DEBUG_UART_MSM=y
> +       CONFIG_DEBUG_UART_CLOCK=7372800
> +       #CONFIG_DEBUG_UART_SKIP_INIT=y
> +
> +       CONFIG_LOG=y
> +       CONFIG_HEXDUMP=y
> +       CONFIG_CMD_LOG=y
> +       CONFIG_LOG_MAX_LEVEL=9
> +       CONFIG_LOG_DEFAULT_LEVEL=9
> +       CONFIG_LOGLEVEL=9
> +
> diff --git a/doc/board/qualcomm/index.rst b/doc/board/qualcomm/index.rst
> index 0f9c4299569a..4955274a39bc 100644
> --- a/doc/board/qualcomm/index.rst
> +++ b/doc/board/qualcomm/index.rst
> @@ -7,5 +7,5 @@ Qualcomm
>     :maxdepth: 2
>
>     dragonboard410c
> -   sdm845
> -   qcs404
> +   board
> +   debugging
> diff --git a/doc/board/qualcomm/qcs404.rst b/doc/board/qualcomm/qcs404.rst
> deleted file mode 100644
> index 0cb71d97c987..000000000000
> --- a/doc/board/qualcomm/qcs404.rst
> +++ /dev/null
> @@ -1,79 +0,0 @@
> -.. SPDX-License-Identifier: GPL-2.0+
> -.. sectionauthor:: Sumit Garg <sumit.garg@linaro.org>
> -
> -QCS404 EVB
> -==========
> -
> -About this
> -----------
> -This document describes the information about Qualcomm QCS404 evaluation board
> -and it's usage steps.
> -
> -The current boot flow support loading u-boot as an Android boot image via
> -Qualcomm's UEFI-based ABL (Android) Bootloader.
> -
> -Installation
> -------------
> -Build
> -^^^^^
> -Setup ``CROSS_COMPILE`` for aarch64 and build U-Boot for your board::
> -
> -       $ export CROSS_COMPILE=<aarch64 toolchain prefix>
> -       $ make qcs404evb_defconfig
> -       $ make
> -
> -This will build ``u-boot.bin`` in the configured output directory.
> -
> -Generate FIT image
> -^^^^^^^^^^^^^^^^^^
> -A ``qcs404.its`` file can be found in ``board/qualcomm/qcs404-evb/`` directory.
> -It expects a folder as ``qcs404_imgs/`` in the main directory containing
> -pre-built kernel, dts and ramdisk images. See ``qcs404.its`` for full path to
> -images.
> -
> -- Build FIT image::
> -
> -       mkimage -f qcs404-evb.its qcs404-evb.itb
> -
> -Pack android boot image
> -^^^^^^^^^^^^^^^^^^^^^^^
> -We'll assemble android boot image with ``u-boot.bin`` instead of linux kernel,
> -and FIT image instead of ``initramfs``. Android bootloader expect gzipped kernel
> -with appended dtb, so let's mimic linux to satisfy stock bootloader:
> -
> -- create dump dtb::
> -
> -       workdir=/tmp/prepare_payload
> -       mkdir -p "$workdir"
> -       cd "$workdir"
> -       mock_dtb="$workdir"/payload_mock.dtb
> -
> -       dtc -I dts -O dtb -o "$mock_dtb" << EOF
> -       /dts-v1/;
> -       / {
> -               model = "Qualcomm Technologies, Inc. QCS404 EVB 4000";
> -               compatible = "qcom,qcs404-evb-4000", "qcom,qcs404-evb", "qcom,qcs404";
> -
> -               #address-cells = <2>;
> -               #size-cells = <2>;
> -
> -               memory@80000000 {
> -                       device_type = "memory";
> -                       /* We expect the bootloader to fill in the size */
> -                       reg = <0 0x80000000 0 0>;
> -               };
> -
> -               chosen { };
> -       };
> -       EOF
> -
> -- gzip u-boot ``gzip u-boot.bin``
> -- append dtb to gzipped u-boot: ``cat u-boot.bin.gz "$mock_dtb" > u-boot.bin.gz-dtb``
> -
> -Now we've got everything to build android boot image:::
> -
> -       mkbootimg --kernel u-boot.bin.gz-dtb \
> -       --ramdisk qcs404-evb.itb --pagesize 4096 \
> -       --base 0x80000000 --output boot.img
> -
> -Flash image on qcs404-evb using fastboot method.
> diff --git a/doc/board/qualcomm/sdm845.rst b/doc/board/qualcomm/sdm845.rst
> deleted file mode 100644
> index a65f00df39f5..000000000000
> --- a/doc/board/qualcomm/sdm845.rst
> +++ /dev/null
> @@ -1,167 +0,0 @@
> -.. SPDX-License-Identifier: GPL-2.0+
> -.. sectionauthor:: Dzmitry Sankouski <dsankouski@gmail.com>
> -
> -Snapdragon 845
> -==============
> -
> -About this
> -----------
> -
> -This document describes the information about Qualcomm Snapdragon 845
> -supported boards and it's usage steps.
> -
> -SDM845 - hi-end qualcomm chip, introduced in late 2017.
> -Mostly used in flagship phones and tablets of 2018.
> -
> -The current boot flow support loading u-boot as an Android boot image via
> -Qualcomm's UEFI-based ABL (Android) Bootloader.
> -
> -Installation
> -------------
> -
> -Build
> -^^^^^
> -
> -Setup ``CROSS_COMPILE`` for aarch64 and build U-Boot for your board::
> -
> -       $ export CROSS_COMPILE=<aarch64 toolchain prefix>
> -       $ make <your board name here, see Boards section>_defconfig
> -       $ make
> -
> -This will build ``u-boot.bin`` in the configured output directory.
> -
> -Generate FIT image
> -^^^^^^^^^^^^^^^^^^
> -
> -See doc/uImage.FIT for more details
> -
> -Pack android boot image
> -^^^^^^^^^^^^^^^^^^^^^^^
> -
> -We'll assemble android boot image with ``u-boot.bin`` instead of linux kernel,
> -and FIT image instead of ``initramfs``. Android bootloader expect gzipped kernel
> -with appended dtb, so let's mimic linux to satisfy stock bootloader.
> -
> -Boards
> -------
> -
> -starqlte
> -^^^^^^^^
> -
> -The starqltechn is a production board for Samsung S9 (SM-G9600) phone,
> -based on the Qualcomm SDM845 SoC.
> -
> -Steps:
> -
> -- Build u-boot::
> -
> -       $ export CROSS_COMPILE=<aarch64 toolchain prefix>
> -       $ make starqltechn_defconfig
> -       $ make
> -
> -- Create dump dtb::
> -
> -       workdir=/tmp/prepare_payload
> -       mkdir -p "$workdir"
> -       cd "$workdir"
> -       mock_dtb="$workdir"/payload_mock.dtb
> -
> -       dtc -I dts -O dtb -o "$mock_dtb" << EOF
> -       /dts-v1/;
> -       / {
> -               memory {
> -                       /* We expect the bootloader to fill in the size */
> -                       reg = <0 0 0 0>;
> -               };
> -
> -               chosen { };
> -       };
> -       EOF
> -
> -- gzip u-boot::
> -
> -       gzip u-boot.bin
> -
> -- Append dtb to gzipped u-boot::
> -
> -       cat u-boot.bin.gz "$mock_dtb" > u-boot.bin.gz-dtb
> -
> -- Now we've got everything to build android boot image::
> -
> -       mkbootimg --base 0x0 --kernel_offset 0x00008000 \
> -       --ramdisk_offset 0x02000000 --tags_offset 0x01e00000 \
> -       --pagesize 4096 --second_offset 0x00f00000 \
> -       --ramdisk "$fit_image" \
> -       --kernel u-boot.bin.gz-dtb \
> -       -o boot.img
> -
> -- Flash image with your phone's flashing method.
> -
> -More information can be found on the `Samsung S9 page`_.
> -
> -dragonboard845c
> -^^^^^^^^^^^^^^^
> -
> -The dragonboard845c is a Qualcomm Robotics RB3 Development Platform, based on
> -the Qualcomm SDM845 SoC.
> -
> -Steps:
> -
> -- Build u-boot::
> -
> -       $ export CROSS_COMPILE=<aarch64 toolchain prefix>
> -       $ make dragonboard845c_defconfig
> -       $ make
> -
> -- Create dummy dtb::
> -
> -       workdir=/tmp/prepare_payload
> -       mkdir -p "$workdir"
> -       mock_dtb="$workdir"/payload_mock.dtb
> -
> -       dtc -I dts -O dtb -o "$mock_dtb" << EOF
> -       /dts-v1/;
> -       / {
> -               #address-cells = <2>;
> -               #size-cells = <2>;
> -
> -               memory@80000000 {
> -                       device_type = "memory";
> -                       /* We expect the bootloader to fill in the size */
> -                       reg = <0 0x80000000 0 0>;
> -               };
> -
> -               chosen { };
> -       };
> -       EOF
> -
> -- gzip u-boot::
> -
> -       gzip u-boot.bin
> -
> -- Append dtb to gzipped u-boot::
> -
> -        cat u-boot.bin.gz "$mock_dtb" > u-boot.bin.gz-dtb
> -
> -- A ``db845c.its`` file can be found in ``board/qualcomm/dragonboard845c/``
> -  directory. It expects a folder as ``db845c_imgs/`` in the main directory
> -  containing pre-built kernel, dts and ramdisk images. See ``db845c.its``
> -  for full path to images::
> -
> -       mkimage -f db845c.its db845c.itb
> -
> -- Now we've got everything to build android boot image::
> -
> -       mkbootimg --kernel u-boot.bin.gz-dtb --ramdisk db845c.itb \
> -       --output boot.img --pagesize 4096 --base 0x80000000
> -
> -- Flash boot.img using db845c fastboot method:
> -
> -  .. code-block:: bash
> -
> -      sudo fastboot flash boot boot.img
> -
> -More information can be found on the `DragonBoard 845c page`_.
> -
> -.. _Samsung S9 page: https://en.wikipedia.org/wiki/Samsung_Galaxy_S9
> -.. _DragonBoard 845c page: https://www.96boards.org/product/rb3-platform/
>
> --
> 2.43.1
>
diff mbox series

Patch

diff --git a/doc/board/qualcomm/board.rst b/doc/board/qualcomm/board.rst
new file mode 100644
index 000000000000..4d793209f9e3
--- /dev/null
+++ b/doc/board/qualcomm/board.rst
@@ -0,0 +1,125 @@ 
+.. SPDX-License-Identifier: GPL-2.0+
+.. sectionauthor:: Dzmitry Sankouski <dsankouski@gmail.com>
+
+Qualcomm generic boards
+=======================
+
+About this
+----------
+This document describes how to build and run U-Boot for Qualcomm generic
+boards. Right now the generic target supports the Snapdragon 845 SoC, however
+it's expected to support more SoCs going forward.
+
+SDM845 - high-end qualcomm chip, introduced in late 2017.
+Mostly used in flagship phones and tablets of 2018.
+
+The current boot flow support loading u-boot as an Android boot image via
+Qualcomm's UEFI-based ABL (Android) Bootloader. The DTB used by U-Boot will
+be appended to the U-Boot image the same way as when booting Linux. U-Boot
+will then retrieve the DTB during init. This way the memory layout and KASLR
+offset will be populated by ABL.
+
+Installation
+------------
+Build
+^^^^^
+
+	$ ./tools/buildman/buildman -o .output qcom
+
+This will build ``.output/u-boot-nodtb.bin`` using the ``qcom_defconfig``.
+
+Generate FIT image (optional)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+See doc/uImage.FIT for more details
+
+Pack android boot image
+^^^^^^^^^^^^^^^^^^^^^^^
+We'll assemble android boot image with ``u-boot-nodtb.bin`` instead of linux kernel,
+and FIT image instead of ``initramfs``. Android bootloader expect gzipped kernel
+with appended dtb, so let's mimic linux to satisfy stock bootloader.
+
+Boards
+------
+
+starqlte
+^^^^^^^^
+
+The starqltechn is a production board for Samsung S9 (SM-G9600) phone,
+based on the Qualcomm SDM845 SoC.
+
+This device is supported by the common qcom_defconfig.
+
+The DTB is called "sdm845-samsung-starqltechn.dtb"
+
+More information can be found on the `Samsung S9 page`_.
+
+dragonboard845c
+^^^^^^^^^^^^^^^
+
+The dragonboard845c is a Qualcomm Robotics RB3 Development Platform, based on
+the Qualcomm SDM845 SoC.
+
+This device is supported by the common qcom_defconfig
+
+The DTB is called "sdm845-db845c.dtb"
+
+More information can be found on the `DragonBoard 845c page`_.
+
+qcs404-evb
+^^^^^^^^^^
+
+The QCS404 EvB is a Qualcomm Development Platform, based on the Qualcomm QCS404 SoC.
+
+This device is supported by the common qcom_defconfig
+
+The DTB is called "qcs404-evb-4000.dtb"
+
+Building steps
+--------------
+
+Steps:
+
+- Build u-boot
+
+As above::
+
+	./tools/buildman/buildman -o .output qcom
+
+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)
+
+- gzip u-boot::
+
+	gzip u-boot-nodtb.bin
+
+- Append dtb to gzipped u-boot::
+
+	cat u-boot-nodtb.bin.gz arch/arm/dts/your-board.dtb > u-boot-nodtb.bin.gz-dtb
+
+- If you chose to build a FIT image, A ``qcom.its`` file can be found in ``board/qualcomm/generic/``
+  directory. It expects a folder as ``qcom_imgs/`` in the main directory containing pre-built kernel,
+  dts and ramdisk images. See ``qcom.its`` for full path to images::
+
+	mkimage -f qcom.its qcom.itb
+
+- Now we've got everything to build android boot image::
+
+	mkbootimg --kernel u-boot-nodtb.bin.gz-dtb --ramdisk db845c.itb \
+	--output boot.img --pagesize 4096 --base 0x80000000
+
+Or with no FIT image::
+
+	mkbootimg --kernel u-boot-nodtb.bin.gz-dtb \
+	--output boot.img --pagesize 4096 --base 0x80000000
+
+- Flash boot.img using fastboot and erase dtbo to avoid conflicts with our DTB:
+
+  .. code-block:: bash
+
+	fastboot flash boot boot.img
+	fastboot erase dtbo
+
+.. _Samsung S9 page: https://en.wikipedia.org/wiki/Samsung_Galaxy_S9
+.. _DragonBoard 845c page: https://www.96boards.org/product/rb3-platform/
diff --git a/doc/board/qualcomm/debugging.rst b/doc/board/qualcomm/debugging.rst
new file mode 100644
index 000000000000..1c35d1909d12
--- /dev/null
+++ b/doc/board/qualcomm/debugging.rst
@@ -0,0 +1,61 @@ 
+.. SPDX-License-Identifier: GPL-2.0+
+.. sectionauthor:: Caleb Connolly <caleb.connolly@linaro.org>
+
+Qualcomm debugging
+==================
+
+About this
+----------
+
+This page describes how to enable early UART and other debugging techniques
+for Qualcomm boards.
+
+Enable debug UART
+-----------------
+
+Newer boards (SDM845 and newer, those with GENI SE UART)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Open ``configs/qcom_defconfig`` and add the following snippet to the bottom:
+
+	CONFIG_BAUDRATE=115200
+
+	# Uncomment to enable UART pre-relocation
+	CONFIG_DEBUG_UART=y
+	CONFIG_DEBUG_UART_ANNOUNCE=y
+	# This is the address of the debug-uart peripheral
+	# The value here is for SDM845, other platforms will vary
+	CONFIG_DEBUG_UART_BASE=0xa84000
+	# Boards older than ~2018 pre-date the GENI driver and unfortunately
+	# aren't supported here
+	CONFIG_DEBUG_UART_MSM_GENI=y
+	# For sdm845 this is the UART clock rate
+	CONFIG_DEBUG_UART_CLOCK=7372800
+	# Most newer boards have an oversampling value of 16 instead
+	# of 32, they need the clock rate to be doubled
+	#CONFIG_DEBUG_UART_CLOCK=14745600
+
+Then build as normal (don't forget to ``make qcom_defconfig``` again).
+
+Older boards (db410c and db820c)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Open ``configs/dragonboard<BOARD>_defconfig``
+
+	CONFIG_BAUDRATE=115200
+	CONFIG_DEBUG_UART=y
+	CONFIG_DEBUG_UART_ANNOUNCE=y
+	# db410c - 0x78b0000
+	# db820c - 0x75b0000
+	CONFIG_DEBUG_UART_BASE=0x75b0000
+	CONFIG_DEBUG_UART_MSM=y
+	CONFIG_DEBUG_UART_CLOCK=7372800
+	#CONFIG_DEBUG_UART_SKIP_INIT=y
+
+	CONFIG_LOG=y
+	CONFIG_HEXDUMP=y
+	CONFIG_CMD_LOG=y
+	CONFIG_LOG_MAX_LEVEL=9
+	CONFIG_LOG_DEFAULT_LEVEL=9
+	CONFIG_LOGLEVEL=9
+
diff --git a/doc/board/qualcomm/index.rst b/doc/board/qualcomm/index.rst
index 0f9c4299569a..4955274a39bc 100644
--- a/doc/board/qualcomm/index.rst
+++ b/doc/board/qualcomm/index.rst
@@ -7,5 +7,5 @@  Qualcomm
    :maxdepth: 2
 
    dragonboard410c
-   sdm845
-   qcs404
+   board
+   debugging
diff --git a/doc/board/qualcomm/qcs404.rst b/doc/board/qualcomm/qcs404.rst
deleted file mode 100644
index 0cb71d97c987..000000000000
--- a/doc/board/qualcomm/qcs404.rst
+++ /dev/null
@@ -1,79 +0,0 @@ 
-.. SPDX-License-Identifier: GPL-2.0+
-.. sectionauthor:: Sumit Garg <sumit.garg@linaro.org>
-
-QCS404 EVB
-==========
-
-About this
-----------
-This document describes the information about Qualcomm QCS404 evaluation board
-and it's usage steps.
-
-The current boot flow support loading u-boot as an Android boot image via
-Qualcomm's UEFI-based ABL (Android) Bootloader.
-
-Installation
-------------
-Build
-^^^^^
-Setup ``CROSS_COMPILE`` for aarch64 and build U-Boot for your board::
-
-	$ export CROSS_COMPILE=<aarch64 toolchain prefix>
-	$ make qcs404evb_defconfig
-	$ make
-
-This will build ``u-boot.bin`` in the configured output directory.
-
-Generate FIT image
-^^^^^^^^^^^^^^^^^^
-A ``qcs404.its`` file can be found in ``board/qualcomm/qcs404-evb/`` directory.
-It expects a folder as ``qcs404_imgs/`` in the main directory containing
-pre-built kernel, dts and ramdisk images. See ``qcs404.its`` for full path to
-images.
-
-- Build FIT image::
-
-	mkimage -f qcs404-evb.its qcs404-evb.itb
-
-Pack android boot image
-^^^^^^^^^^^^^^^^^^^^^^^
-We'll assemble android boot image with ``u-boot.bin`` instead of linux kernel,
-and FIT image instead of ``initramfs``. Android bootloader expect gzipped kernel
-with appended dtb, so let's mimic linux to satisfy stock bootloader:
-
-- create dump dtb::
-
-	workdir=/tmp/prepare_payload
-	mkdir -p "$workdir"
-	cd "$workdir"
-	mock_dtb="$workdir"/payload_mock.dtb
-
-	dtc -I dts -O dtb -o "$mock_dtb" << EOF
-	/dts-v1/;
-	/ {
-		model = "Qualcomm Technologies, Inc. QCS404 EVB 4000";
-		compatible = "qcom,qcs404-evb-4000", "qcom,qcs404-evb", "qcom,qcs404";
-
-		#address-cells = <2>;
-		#size-cells = <2>;
-
-		memory@80000000 {
-			device_type = "memory";
-			/* We expect the bootloader to fill in the size */
-			reg = <0 0x80000000 0 0>;
-		};
-
-		chosen { };
-	};
-	EOF
-
-- gzip u-boot ``gzip u-boot.bin``
-- append dtb to gzipped u-boot: ``cat u-boot.bin.gz "$mock_dtb" > u-boot.bin.gz-dtb``
-
-Now we've got everything to build android boot image:::
-
-	mkbootimg --kernel u-boot.bin.gz-dtb \
-	--ramdisk qcs404-evb.itb --pagesize 4096 \
-	--base 0x80000000 --output boot.img
-
-Flash image on qcs404-evb using fastboot method.
diff --git a/doc/board/qualcomm/sdm845.rst b/doc/board/qualcomm/sdm845.rst
deleted file mode 100644
index a65f00df39f5..000000000000
--- a/doc/board/qualcomm/sdm845.rst
+++ /dev/null
@@ -1,167 +0,0 @@ 
-.. SPDX-License-Identifier: GPL-2.0+
-.. sectionauthor:: Dzmitry Sankouski <dsankouski@gmail.com>
-
-Snapdragon 845
-==============
-
-About this
-----------
-
-This document describes the information about Qualcomm Snapdragon 845
-supported boards and it's usage steps.
-
-SDM845 - hi-end qualcomm chip, introduced in late 2017.
-Mostly used in flagship phones and tablets of 2018.
-
-The current boot flow support loading u-boot as an Android boot image via
-Qualcomm's UEFI-based ABL (Android) Bootloader.
-
-Installation
-------------
-
-Build
-^^^^^
-
-Setup ``CROSS_COMPILE`` for aarch64 and build U-Boot for your board::
-
-	$ export CROSS_COMPILE=<aarch64 toolchain prefix>
-	$ make <your board name here, see Boards section>_defconfig
-	$ make
-
-This will build ``u-boot.bin`` in the configured output directory.
-
-Generate FIT image
-^^^^^^^^^^^^^^^^^^
-
-See doc/uImage.FIT for more details
-
-Pack android boot image
-^^^^^^^^^^^^^^^^^^^^^^^
-
-We'll assemble android boot image with ``u-boot.bin`` instead of linux kernel,
-and FIT image instead of ``initramfs``. Android bootloader expect gzipped kernel
-with appended dtb, so let's mimic linux to satisfy stock bootloader.
-
-Boards
-------
-
-starqlte
-^^^^^^^^
-
-The starqltechn is a production board for Samsung S9 (SM-G9600) phone,
-based on the Qualcomm SDM845 SoC.
-
-Steps:
-
-- Build u-boot::
-
-	$ export CROSS_COMPILE=<aarch64 toolchain prefix>
-	$ make starqltechn_defconfig
-	$ make
-
-- Create dump dtb::
-
-	workdir=/tmp/prepare_payload
-	mkdir -p "$workdir"
-	cd "$workdir"
-	mock_dtb="$workdir"/payload_mock.dtb
-
-	dtc -I dts -O dtb -o "$mock_dtb" << EOF
-	/dts-v1/;
-	/ {
-		memory {
-			/* We expect the bootloader to fill in the size */
-			reg = <0 0 0 0>;
-		};
-
-		chosen { };
-	};
-	EOF
-
-- gzip u-boot::
-
-	gzip u-boot.bin
-
-- Append dtb to gzipped u-boot::
-
-	cat u-boot.bin.gz "$mock_dtb" > u-boot.bin.gz-dtb
-
-- Now we've got everything to build android boot image::
-
-	mkbootimg --base 0x0 --kernel_offset 0x00008000 \
-	--ramdisk_offset 0x02000000 --tags_offset 0x01e00000 \
-	--pagesize 4096 --second_offset 0x00f00000 \
-	--ramdisk "$fit_image" \
-	--kernel u-boot.bin.gz-dtb \
-	-o boot.img
-
-- Flash image with your phone's flashing method.
-
-More information can be found on the `Samsung S9 page`_.
-
-dragonboard845c
-^^^^^^^^^^^^^^^
-
-The dragonboard845c is a Qualcomm Robotics RB3 Development Platform, based on
-the Qualcomm SDM845 SoC.
-
-Steps:
-
-- Build u-boot::
-
-	$ export CROSS_COMPILE=<aarch64 toolchain prefix>
-	$ make dragonboard845c_defconfig
-	$ make
-
-- Create dummy dtb::
-
-	workdir=/tmp/prepare_payload
-	mkdir -p "$workdir"
-	mock_dtb="$workdir"/payload_mock.dtb
-
-	dtc -I dts -O dtb -o "$mock_dtb" << EOF
-	/dts-v1/;
-	/ {
-		#address-cells = <2>;
-		#size-cells = <2>;
-
-		memory@80000000 {
-			device_type = "memory";
-			/* We expect the bootloader to fill in the size */
-			reg = <0 0x80000000 0 0>;
-		};
-
-		chosen { };
-	};
-	EOF
-
-- gzip u-boot::
-
-	gzip u-boot.bin
-
-- Append dtb to gzipped u-boot::
-
-	 cat u-boot.bin.gz "$mock_dtb" > u-boot.bin.gz-dtb
-
-- A ``db845c.its`` file can be found in ``board/qualcomm/dragonboard845c/``
-  directory. It expects a folder as ``db845c_imgs/`` in the main directory
-  containing pre-built kernel, dts and ramdisk images. See ``db845c.its``
-  for full path to images::
-
-	mkimage -f db845c.its db845c.itb
-
-- Now we've got everything to build android boot image::
-
-	mkbootimg --kernel u-boot.bin.gz-dtb --ramdisk db845c.itb \
-	--output boot.img --pagesize 4096 --base 0x80000000
-
-- Flash boot.img using db845c fastboot method:
-
-  .. code-block:: bash
-
-      sudo fastboot flash boot boot.img
-
-More information can be found on the `DragonBoard 845c page`_.
-
-.. _Samsung S9 page: https://en.wikipedia.org/wiki/Samsung_Galaxy_S9
-.. _DragonBoard 845c page: https://www.96boards.org/product/rb3-platform/