.. _developer_notes_bootloaders:

Understanding bootloaders in Processor SDK |dev_platform| (RTOS/Linux/QNX)
==========================================================================

Introduction
------------

There are two bootloaders in Processor SDK |dev_platform| (RTOS/Linux/QNX). They are:

    #. RTOS SDK Bootloader
    #. Linux SDK Bootloader

This developer note describes about these two bootloaders.

RTOS SDK Bootloader
-------------------

RTOS Bootloader is referred to as SBL (Secondary bootloader).

.. ifconfig:: REMOTE_FIRMWARE_REPO in ('pdk')

    This is included in Processor SDK RTOS at

        pdk_<device>_<version>/packages/ti/boot

.. ifconfig:: REMOTE_FIRMWARE_REPO in ('mcu_plus_sdk')

    This is included in Processor SDK RTOS at

        mcu_plus_sdk_<device>_<version>/examples/drivers/boot/



This is used when all cores on the SoC run FreeRTOS. Following are the details regarding boot files in the SD card:

#. **tiboot3.bin** - this is the SBL which the ROM bootloader will boot on MCU R5F Core0
#. **tiboot3.bin** will boot |sysfw_bin| - this is the DMSC firmware binary
#. **tiboot3.bin** will boot a file called **"app"**. 

  - If **"app"** is **"combined boot image"**, it contains binaries of all other CPUs like A72, 
    Main |rtos_cores|.  **"combined boot image"** is created by running an offline tool which covert
    elf **.out** files to **.rprc** format and then combines these to something called "multi-core image"
  - If **"app"** is **"BootAPP"**, please refer below table.

.. seealso::

    See PDK's bootloader page for more info on this .rprc file and offline boot tools 

The table below provides more information about the features and differences between the SBL bootloader and the “Boot App”:

+------------------------------------------+---------------------------------------------+------------------------------------------------------------------+------------------------------------------------------------------+
| Feature area                             | SBL Description                             | “Boot App”                                                       | Key Diffs / Comments                                             |
+==========================================+=============================================+==================================================================+==================================================================+
| Initial Bootloader                       | YES                                         | NO                                                               |       Boot app is a “tertiary” bootloader                        |
+------------------------------------------+---------------------------------------------+------------------------------------------------------------------+------------------------------------------------------------------+
| SoC's Supported                          | J7200/J721E/J721S2/J784S4/J722S/J742S2      | J7200/J721E/J721S2/J784S4/J742S2                                 |                                                                  |
+------------------------------------------+---------------------------------------------+------------------------------------------------------------------+------------------------------------------------------------------+
| Device types supported                   | GP, HS                                      | GP, HS                                                           | NOTE: most, but not all, features are supported for each device  |
|                                          |                                             |                                                                  | type.  Check specific feature support listed in each release.    |
+------------------------------------------+---------------------------------------------+------------------------------------------------------------------+------------------------------------------------------------------+
| Runs on MCU R5F                          | YES                                         | YES                                                              | NOTE: the SBL is used to boot the Boot App                       |
+------------------------------------------+---------------------------------------------+------------------------------------------------------------------+------------------------------------------------------------------+
| Can support startup with MCU domain only | YES                                         | YES                                                              |                                                                  |
+------------------------------------------+---------------------------------------------+------------------------------------------------------------------+------------------------------------------------------------------+
| Boot media supported                     | UART, MMCSD, OSPI                           | MMCSD, OSPI                                                      | UART boot supported with SBL only                                |
+------------------------------------------+---------------------------------------------+------------------------------------------------------------------+------------------------------------------------------------------+
| Supports booting HLOS + RTOS images      | YES                                         | YES                                                              | SBL uses “combined appimage” build to put all RTOS & HLOS images |
|                                          |                                             |                                                                  | into a single .appimage, whereas a specific format of combined   |
|                                          |                                             |                                                                  | images is used with the boot app.                                |
+------------------------------------------+---------------------------------------------+------------------------------------------------------------------+------------------------------------------------------------------+
| Boots another app to MCU R5F             | YES                                         |                                                                  | Boot app doesn’t support booting an app to the MCU R5F (since it |
|                                          |                                             |                                                                  | is the app already running on that processor)                    |
+------------------------------------------+---------------------------------------------+------------------------------------------------------------------+------------------------------------------------------------------+
| Image Layout                             |  single appimage                            | 3-5 different appimages                                          | SBL: all images for the remote cores to be booted must all be    |
|                                          |                                             |                                                                  | combined in to a single .appimage file that is either placed     |
|                                          |                                             |                                                                  | on the SD card (for MMCSD boot) or is flashed to a single flash  |
|                                          |                                             |                                                                  | addr location (for xSPI / OSPI boot). This includes all HLOS &   |
|                                          |                                             |                                                                  | RTOS images that must be booted.                                 |
|                                          |                                             |                                                                  |                                                                  |
|                                          |                                             |                                                                  | "Boot App": images for remote cores to be booted are             |
|                                          |                                             |                                                                  | split up into 3-5 different appimage files for either SD card    |
|                                          |                                             |                                                                  | booting or flashed into 3-5 different flash addresses for        |
|                                          |                                             |                                                                  | xSPI / OSPI booting (see details in the MCUSW CAN Boot App       |
|                                          |                                             |                                                                  | documentation).                                                  |
+------------------------------------------+---------------------------------------------+------------------------------------------------------------------+------------------------------------------------------------------+


Linux SDK Bootloader
--------------------

TI Linux SDK utilizes ti-u-boot as a bootloader option for our SoCs which is available at (https://git.ti.com/cgit/ti-u-boot/ti-u-boot/) and also included in Processor SDK Linux at below path ::

    board-support/u-boot-<version and git tag>

In addition to **qnx-ifs**, the following files are loaded to the boot partition of the SD card when using this boot method.

1. **tiboot3.bin** contains the R5 U-Boot SPL, TIFS (system firmware), and the cut down device tree for the R5 u-boot SPL. This is what public ROM code will load to SRAM and run on MCU/WKUP domain R5_core0.
2. **tispl.bin** contains DM firmware and the following components for the Coretex-A cores:

    * Arm Trusted Firmware
    * OPTEE (empty if not used)
    * U-Boot SPL
    * Device Tree for Cortex-A U-Boot SPL

3. **u-boot.img** is started by the U-Boot SPL.
4. Any variables set in the **uEnv.txt** file will override U-Boot defaults. The `run envboot` command (which runs automatically if U-Boot prompt is not interrupted) will perform the tasks inside the `uenvcmd` variable. This is typically to load any remote core binaries (like R5F, C7x), test conditions, and run U-Boot commands. The last thing `uenvcmd` calls for is to load qnx-ifs (and dtb depending on QNX SDP version) to DDR and start QNX.
5. If using QNX SDP version 8.0+ (used by Processor SDK QNX 10.0+), a device tree file **(.dtb)** will be present and required by QNX as well.

.. ifconfig:: CONFIG_part_variant in ('J721E')
    
    6. J721E uses a split binary, split firmware boot flow and will contain an additional file **sysfw.itb**, that is not common among other K3 SoCs.


.. Hint::

  U-Boot knows where to find remote core binaries in `<rootfs>/lib/firmware`. If using eMMC as boot media, remote core binaries will be in a different location as specified by :ref:`developer_notes_eMMC_filesystem` and our **uEnv.txt** file helps U-Boot find the correct eMMC partition


.. warning::

  U-Boot does not always take QNX into consideration when making design decisions. New versions of U-Boot may change things QNX relies on and while we test our SDK releases for proper behavior, future or past versions of U-Boot may require patching to either U-Boot or QNX.

.. seealso::

  Refer to PSDK LINUX documentation for more information on u-boot
  https://software-dl.ti.com/jacinto7/esd/processor-sdk-linux-j722s/latest/exports/docs/linux/Foundational_Components_U-Boot.html#u-boot-user-s-guide

  For a bootflow overview of K3 devices, see https://docs.u-boot.org/en/latest/board/ti/k3.html
