index.rst: - Include 'spl-qclib.rst' rdp.rst: - Add details about the SPL & U-Boot proper build steps, converting to flashable images, source URLs for the needed binaries and scripts. - Update author e-mail id.
spl-qclib.rst: - Describe the SPL - Qualcomm Library (QCLib) interface used to exchange information between U-Boot SPL and QCLib for initializing the DDR. Reviewed-by: Simon Glass <[email protected]> Reviewed-by: Balaji Selvanathan <[email protected]> Signed-off-by: Varadarajan Narayanan <[email protected]> --- doc/board/qualcomm/index.rst | 1 + doc/board/qualcomm/rdp.rst | 79 +++++++++++++++++++++++++++++++++------- doc/board/qualcomm/spl-qclib.rst | 76 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 143 insertions(+), 13 deletions(-) diff --git a/doc/board/qualcomm/index.rst b/doc/board/qualcomm/index.rst index 56b8d894c2a..ddb75c49bcc 100644 --- a/doc/board/qualcomm/index.rst +++ b/doc/board/qualcomm/index.rst @@ -17,3 +17,4 @@ Qualcomm rdp signing spl + spl-qclib diff --git a/doc/board/qualcomm/rdp.rst b/doc/board/qualcomm/rdp.rst index 4e63fe624b8..8aab9b606d0 100644 --- a/doc/board/qualcomm/rdp.rst +++ b/doc/board/qualcomm/rdp.rst @@ -1,5 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0 -.. sectionauthor:: Varadarajan Narayanan <[email protected]> +.. sectionauthor:: Varadarajan Narayanan <[email protected]> Qualcomm Reference Design Platform (RDP) ======================================== @@ -22,17 +22,6 @@ First, setup ``CROSS_COMPILE`` for aarch64. Then, build U-Boot for ``IPQ9574``:: This will build the signed ``u-boot.mbn`` in the configured output directory. More information about image signing can be found in :doc:`signing`. -The firmware expects the ELF images to be in MBN format. The `elftombn.py` tool -can be used to convert the ELF images to MBN format. - - IPQ9574: (MBN version 6) - - $ python elftombn.py -f u-boot.elf -o u-boot.mbn -v6 - - IPQ5424: (MBN version 7) - - $ python elftombn.py -f u-boot.elf -o u-boot.mbn -v7 - Then install the resulting ``u-boot.mbn`` to the ``0:APPSBL`` partition on your device with:: @@ -43,6 +32,63 @@ on your device with:: U-Boot should be running after a reboot (``reset``). +Build steps for IPQ5210 based Qualcomm Dragonwing F8 & N8 Platforms: +-------------------------------------------------------------------- + +Please refer to the following URLs for more details about the platforms. + + F8: https://www.qualcomm.com/networking-infrastructure/products/f-series/f8-platform + + N8: https://www.qualcomm.com/networking-infrastructure/products/n-series/n8-platform + +Since U-Boot SPL is enabled on these platforms, the build command generates both +the U-Boot SPL and U-Boot proper images. + +Download `tmel-ipq52xx-patch.elf` and update CONFIG_QCOM_TMEL_ELF in the config +file (i.e. configs/qcom_ipq5210_mmc_defconfig) as appropriate. + +Assuming ${uboot_dir} is the top of the U-Boot sources and ${out_dir} as the +output directory, + +.. code-block:: bash + + cd ${uboot_dir} + export CROSS_COMPILE=<aarch64 toolchain prefix> + make -j8 O=${out_dir} qcom_ipq5210_mmc_defconfig + make -j8 O=${out_dir} + +U-Boot SPL image: ${out_dir}/spl/u-boot-spl.melf +U-Boot image: ${out_dir}/u-boot.mbn + +TFA: + +.. code-block:: bash + + make PLAT=ipq52xx QTISECLIB_PATH=path/to/`libqtisec_dbg.a` SPD=opteed + +OPTEE: + +.. code-block:: bash + + make PLATFORM=qcom-ipq52xx -j16 + +These binaries can be combined into a flashable image using `gen_its.py`. + +.. code-block:: bash + + python gen_its.py --arch ipq5210 \ + --qclib_path `QCLib.elf` \ + --qcconfig_path `qc_config.elf` \ + --tfa_bl31_path bl31.mbn \ + --uboot_path u-boot.mbn \ + --optee_path tee-raw.mbn \ + -p qcconfig qclib \ + -P tfa_bl31 uboot optee \ + -o output/hm_503_test_uboot.img \ + --template `template.its` + +This should be flashed into 0:BOOTLDR partition. + .. WARNING Boards with newer software versions would automatically go the emergency download (EDL) mode if U-Boot is not functioning as expected. If its a @@ -55,5 +101,12 @@ U-Boot should be running after a reboot (``reset``). Note that the support added is very basic. Restoring the original U-Boot on boards with older version of the software requires a debugger. -.. _elftombn.py: https://git.codelinaro.org/clo/qsdk/oss/system/tools/meta/-/tree/NHSS.QSDK.13.0.5.r2/scripts?ref_type=heads .. _edl: https://github.com/bkerler/edl +.. _gen_its.py: https://git.codelinaro.org/clo/qsdk/oss/system/tools/meta/-/tree/win.platform_tools.1.0.r34/scripts?ref_type=heads +.. _libqtisec_dbg.a: https://softwarecenter.qualcomm.com/nexus/generic/product/chip/software-product/IPQ5210.NLQ.14.0/ipq5210.nlq.14.0-qca-oem-qartifact/r00036.1/WIN.TFA.1.0.R4/apss_proc/out/proprietary/qtiseclib/output/ipq52xx/release/libqtisec_dbg.a +.. _OPTEE: https://git.codelinaro.org/clo/trusted-firmware/optee_os/optee_os/-/tree/win.optee.1.0?ref_type=heads +.. _qc_config.elf: https://softwarecenter.qualcomm.com/nexus/generic/product/chip/software-product/IPQ5210.NLQ.14.0/ipq5210.nlq.14.0-qca-oem-qartifact/r00036.1/BOOT.MXF.2.3.1.1/boot_images/boot/QcomPkg/SocPkg/Hermosa/Bin/LC/RELEASE/qc_config.elf +.. _QCLib.elf: https://softwarecenter.qualcomm.com/nexus/generic/product/chip/software-product/IPQ5210.NLQ.14.0/ipq5210.nlq.14.0-qca-oem-qartifact/r00036.1/BOOT.MXF.2.3.1.1/boot_images/boot/QcomPkg/SocPkg/Hermosa/Bin/LC/RELEASE/QCLib.elf +.. _template.its: https://git.codelinaro.org/clo/qsdk/oss/system/tools/meta/-/tree/win.platform_tools.1.0.r34/scripts?ref_type=heads +.. _TFA: https://git.codelinaro.org/clo/trusted-firmware/tf-a/trusted-firmware-a/-/tree/win.tfa.1.0.r4?ref_type=heads +.. _tmel-ipq52xx-patch.elf: https://softwarecenter.qualcomm.com/nexus/generic/product/chip/software-product/IPQ5210.NLQ.14.0/ipq5210.nlq.14.0-qca-oem-qartifact/r00036.1/TMEL.WNS.2.4/tmel-ipq52xx-patch.elf diff --git a/doc/board/qualcomm/spl-qclib.rst b/doc/board/qualcomm/spl-qclib.rst new file mode 100644 index 00000000000..b430f10dc68 --- /dev/null +++ b/doc/board/qualcomm/spl-qclib.rst @@ -0,0 +1,76 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. sectionauthor:: Varadarajan Narayanan <[email protected]> + +QCLib Interface Table +===================== + +Overview +-------- + +QCLib (Qualcomm Library) is a Qualcomm proprietary firmware binary that +performs DDR initialization and other pre-DDR hardware bring-up on Snapdragon +SoCs. U-Boot SPL communicates with QCLib through a shared in-memory structure +called the **interface table** (``struct interface_table``). The table is +populated by SPL before jumping to QCLib, and QCLib updates selected entries +before returning. + +Interface Table Header +---------------------- + +The table header occupies the first 0x20 bytes of the structure: + +.. code-block:: none + + Offset Size Field Description + ------ ---- ------------------ ---------------------------------------- + 0x00 8 magic_key ASCII magic: "QCLIB_CB" (no NUL) + 0x08 4 version Interface version; currently 0x00000001 + 0x0C 4 num_entries Number of valid entries in the table + 0x10 4 max_entries Maximum entries the table can hold (16) + 0x14 4 global_attributes Bitmask of global control flags + 0x18 4 reserved1 Reserved; must be zero + 0x1C 4 reserved2 Reserved; must be zero + 0x20 - entries[] Array of up to 16 table entries + +The magic key ``"QCLIB_CB"`` is validated by QCLib on entry. If the magic does +not match, QCLib will not proceed. + +Table Entry Format +------------------ + +Each entry is 0x28 bytes: + +.. code-block:: none + + Offset Size Field Description + ------ ---- ------------------ ---------------------------------------- + 0x00 24 entry_name NUL-padded ASCII name (see entries below) + 0x18 8 address Physical address of the blob in SRAM + 0x20 4 size Size of the blob in bytes + 0x24 4 attributes Bitmask of per-entry flags + +The ``global_attributes`` and per-entry ``attributes`` fields are bitmasks +defined by the QCLib interface specification. SPL initializes both to zero +unless a SoC-specific override sets them. + +Interface Table Entries +----------------------- + +.. list-table:: + :header-rows: 1 + :widths: 22 12 66 + + * - Entry name + - Direction + - Description + * - ``qc_config`` + - Input + - Entry point / load address of the pre-DDR configuration image + (``qcom-config-1`` in the FIT). Contains platform configuration + data consumed by QCLib. + * - ``qcsdi`` + - Bidirectional + - QCSDI (Qualcomm Crash Dump Interface) entry. SPL initializes the + address to zero; QCLib writes the QCSDI physical address here before + returning. SPL reads it back and passes it to downstream firmware + (e.g. TF-A BL31 via ``arg0``) for crash-dump support. -- 2.34.1
