docs(msm8916): new port for Qualcomm Snapdragon 410
The Qualcomm Snapdragon 410 is Qualcomm's first 64-bit SoC, released
in 2014 with four ARM Cortex-A53 cores. There are differents variants
(MSM8916, APQ8016(E), ...) that are all very similar. A popular device
based on APQ8016E is the DragonBoard 410c single-board computer,
but the SoC is also used in various mid-range smartphones/tablets.
This commit adds documentation for a minimal, community-maintained port
of TF-A/BL31 for MSM8916. The actual platform port is added in the
following four separate small commits to simplify the review process.
The code is primarily based on the information from the public
Snapdragon 410E Technical Reference Manual [1], combined with a lot of
trial and error to actually make it work.
Note that this port is a pure community effort without any
commercial interests and is not related to Qualcomm in any way.
The main motivation for this port is to have a minimal, updatable
firmware since this old chip does not receive many updates anymore from
Qualcomm. It works quite well for many use cases so I am willing to
maintain it as a "code owner". I have also added Nikita Travkin as
second code owner to help with reviews.
The main limitation so far is the lack of memory protection for TF-A.
This is similar to the ports for the Raspberry Pi but in this case not
a lack of hardware support but rather a lack of documentation. However,
this does not limit the usefulness of the port when used as a minimal
PSCI implementation.
[1]: https://developer.qualcomm.com/download/sd410/snapdragon-410e-technical-reference-manual.pdf
Change-Id: I676adf86061638cfc2f3ae8615470d145e84f172
Signed-off-by: Stephan Gerhold <stephan@gerhold.net>
diff --git a/docs/about/maintainers.rst b/docs/about/maintainers.rst
index e0a7587..94c63f4 100644
--- a/docs/about/maintainers.rst
+++ b/docs/about/maintainers.rst
@@ -580,6 +580,15 @@
:|F|: docs/plat/qti.rst
:|F|: plat/qti/
+QTI MSM8916 platform port
+^^^^^^^^^^^^^^^^^^^^^^^^^
+:|M|: Stephan Gerhold <stephan@gerhold.net>
+:|G|: `stephan-gh`_
+:|M|: Nikita Travkin <nikita@trvn.ru>
+:|G|: `TravMurav`_
+:|F|: docs/plat/qti-msm8916.rst
+:|F|: plat/qti/msm8916/
+
Raspberry Pi 3 platform port
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
:|M|: Ying-Chun Liu (PaulLiu) <paul.liu@linaro.org>
@@ -797,9 +806,11 @@
.. _smaeul: https://github.com/smaeul
.. _soby-mathew: https://github.com/soby-mathew
.. _sreekare: https://github.com/sreekare
+.. _stephan-gh: https://github.com/stephan-gh
.. _thloh85-intel: https://github.com/thloh85-intel
.. _thomas-arm: https://github.com/thomas-arm
.. _TonyXie06: https://github.com/TonyXie06
+.. _TravMurav: https://github.com/TravMurav
.. _vwadekar: https://github.com/vwadekar
.. _venkatesh: https://github.com/vabbarap
.. _Yann-lms: https://github.com/Yann-lms
diff --git a/docs/plat/index.rst b/docs/plat/index.rst
index 57cc488..0cef16a 100644
--- a/docs/plat/index.rst
+++ b/docs/plat/index.rst
@@ -32,6 +32,7 @@
qemu
qemu-sbsa
qti
+ qti-msm8916
rpi3
rpi4
rcar-gen3
diff --git a/docs/plat/qti-msm8916.rst b/docs/plat/qti-msm8916.rst
new file mode 100644
index 0000000..09a79b7
--- /dev/null
+++ b/docs/plat/qti-msm8916.rst
@@ -0,0 +1,116 @@
+Qualcomm Snapdragon 410 (MSM8916/APQ8016)
+=========================================
+
+The `Qualcomm Snapdragon 410`_ is Qualcomm's first 64-bit SoC, released in 2014
+with four ARM Cortex-A53 cores. There are differents variants (MSM8916,
+APQ8016(E), ...) that are all very similar. A popular device based on APQ8016E
+is the `DragonBoard 410c`_ single-board computer, but the SoC is also used in
+various mid-range smartphones/tablets.
+
+The TF-A/BL31 port for MSM8916 provides a minimal, community-maintained
+EL3 firmware. It is primarily based on information from the public
+`Snapdragon 410E Technical Reference Manual`_ combined with a lot of
+trial and error to actually make it work.
+
+.. note::
+ Unlike the :doc:`QTI SC7180/SC7280 <qti>` ports, this port does **not**
+ make use of a proprietary binary components (QTISECLIB). It is fully
+ open-source but therefore limited to publicly documented hardware
+ components.
+
+Functionality
+-------------
+
+The BL31 port is much more minimal compared to the original firmware and
+therefore expects the non-secure world (e.g. Linux) to manage more hardware,
+such as the SMMUs and all remote processors (RPM, WCNSS, Venus, Modem).
+Everything except modem is currently functional with a slightly modified version
+of mainline Linux.
+
+.. warning::
+ This port is **not secure**. There is no special secure memory and the
+ used DRAM is available from both the non-secure and secure worlds.
+ Unfortunately, the hardware used for memory protection is not described
+ in the APQ8016E documentation.
+
+The port is primarily intended as a minimal PSCI implementation (without a
+separate secure world) where this limitation is not a big problem. Booting
+secondary CPU cores (PSCI ``CPU_ON``) is supported. Basic CPU core power
+management (``CPU_SUSPEND``) is functional but still work-in-progress and
+will be added later once ready.
+
+Boot Flow
+---------
+BL31 replaces the original ``tz`` firmware in the boot flow::
+
+ Boot ROM (PBL) -> SBL -> BL31 (EL3) -> U-Boot (EL2) -> Linux (EL2)
+
+By default, BL31 enters the non-secure world in EL2 AArch64 state at address
+``0x8f600000``. The original hypervisor firmware (``hyp``) is not used, you can
+use KVM or another hypervisor. The entry address is fixed in the BL31 binary
+but can be changed using the ``PRELOADED_BL33_BASE`` make file parameter.
+
+Using an AArch64 bootloader (such as `U-Boot for DragonBoard 410c`_) is
+recommended. AArch32 bootloaders (such as the original Little Kernel bootloader
+from Qualcomm) are not directly supported, although it is possible to use an EL2
+shim loader to temporarily switch to AArch32 state.
+
+Installation
+------------
+First, setup the cross compiler for AArch64 and build TF-A for ``msm8916``::
+
+ $ make CROSS_COMPILE=aarch64-linux-gnu- PLAT=msm8916
+
+The BL31 ELF image is generated in ``build/msm8916/release/bl31/bl31.elf``.
+This image must be "signed" before flashing it, even if the board has secure
+boot disabled. In this case the signature does not provide any security,
+but it provides the firmware with required metadata.
+
+The `DragonBoard 410c`_ does not have secure boot enabled by default. In this
+case you can simply sign the ELF image using a randomly generated key. You can
+use e.g. `qtestsign`_::
+
+ $ ./qtestsign.py tz build/msm8916/release/bl31/bl31.elf
+
+Then install the resulting ``build/msm8916/release/bl31/bl31-test-signed.mbn``
+to the ``tz`` partition on the device. BL31 should be running after a reboot.
+
+.. warning::
+ Do not flash incorrectly signed firmware on devices that have secure
+ boot enabled! Make sure that you have a way to recover the board in case
+ of problems (e.g. using EDL).
+
+Boot Trace
+----------
+BL31 prints some lines on the debug console UART2, which will usually look like
+this (with ``DEBUG=1``, otherwise only the ``NOTICE`` lines are shown)::
+
+ ...
+ S - DDR Frequency, 400 MHz
+ NOTICE: BL31: v2.6(debug):v2.6
+ NOTICE: BL31: Built : 20:00:00, Dec 01 2021
+ INFO: BL31: Platform setup start
+ INFO: ARM GICv2 driver initialized
+ INFO: BL31: Platform setup done
+ INFO: BL31: Initializing runtime services
+ INFO: BL31: cortex_a53: CPU workaround for 819472 was applied
+ INFO: BL31: cortex_a53: CPU workaround for 824069 was applied
+ INFO: BL31: cortex_a53: CPU workaround for 826319 was applied
+ INFO: BL31: cortex_a53: CPU workaround for 827319 was applied
+ INFO: BL31: cortex_a53: CPU workaround for 835769 was applied
+ INFO: BL31: cortex_a53: CPU workaround for disable_non_temporal_hint was applied
+ INFO: BL31: cortex_a53: CPU workaround for 843419 was applied
+ INFO: BL31: cortex_a53: CPU workaround for 1530924 was applied
+ INFO: BL31: Preparing for EL3 exit to normal world
+ INFO: Entry point address = 0x8f600000
+ INFO: SPSR = 0x3c9
+
+ U-Boot 2021.10 (Dec 01 2021 - 20:00:00 +0000)
+ Qualcomm-DragonBoard 410C
+ ...
+
+.. _Qualcomm Snapdragon 410: https://www.qualcomm.com/products/snapdragon-processors-410
+.. _DragonBoard 410c: https://www.96boards.org/product/dragonboard410c/
+.. _Snapdragon 410E Technical Reference Manual: https://developer.qualcomm.com/download/sd410/snapdragon-410e-technical-reference-manual.pdf
+.. _U-Boot for DragonBoard 410c: https://u-boot.readthedocs.io/en/latest/board/qualcomm/dragonboard410c.html
+.. _qtestsign: https://github.com/msm8916-mainline/qtestsign