
.. _developer_notes_device_tree_support:

Device Tree Support
===================

.. ifconfig:: QNX_SDP_VERSION in ('710')

  .. IMPORTANT::

    **Device Tree loading at boot time support is only valid in QNX SDP 8.0!!!**

    When using SDP 7.1 based io-sock, the device tree is not loaded at boot time and is instead
    read from the filesystem at driver startup. This rest of this section is not relevant for
    those using io-pkt based networking in SDP 7.1.

    For more information on the differences between io-sock and io-pkt, please refer to
    the developer note :ref:`devnp_710_developer_note`

.. IMPORTANT::

  For any information about Device Trees refer to the QNX |dev_platform| BSP user guide
  accessible via QNX Software Center for further details. If there are still questions
  **contact QNX for any questions about Device Tree**.

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

Device Trees (DTs) are required for io-sock based networking.
In QNX SDP 8.0, the Device Tree Blobs (DTBs) must be loaded into memory by the
bootloader prior to the QNX image taking over. This is not required for QNX SDP 7.1 based
io-sock networking as the DTB is read from the filesystem at driver startup.

Support for loading DTBs has been added to Processor SDK |dev_platform| QNX for the following boot modes:

  #. U-boot
  #. SBL+BootApp
  #. SBL Combined Boot

.. NOTE::

  The configurations for each SOC have been updated with defaults based on the BSP revision
  they were validated with. If running on a TI EVM with the same BSP revision, then no modifications
  should be required. **If using a custom board contact QNX for DTB related support.
  PSDK QNX does not own the DTB being used and is distributed via the QNX BSP!!!**

- In U-boot, the DTB is stored in the bootfs partition of the SD card. The U-boot boot script
  (uEnv.txt) then loads the specified DTB to the specified memory address before jumping
  to the QNX image.
- In SBL with BootApp, the DTB is linked into the QNX appimage. This is different than Linux
  whose DTB is stored as another appimage along side the Linux appimage.
- In SBL Combined Boot, the DTB is built into the combined appimage via the standard SBL
  build flow.

Follow the below instructions for adding/customizing the loading of DTBs.

Instructions for Loading Customer Device Trees in PSDK QNX
----------------------------------------------------------

Modifications Required for Both U-boot and SBL
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

These configurations are required for both U-boot and SBL. The majority of the DTB
configuration happens in ${PSDK_QNX_PATH}/soc_config.mk. An excerpt of this file is
shown below:

.. code:: make

  ############################
  ## Device Tree Configuration
  ############################
  # Define FDT_PATH, FDT_BIN_NAME, and FDT_LOAD_ADDR for each given SOC.
  # If not defined then no FDT will be copied/built into Uboot or SBL.
  ifeq ($(SOC), j721e)

    ifeq ($(QNX_SDP_VERSION), 800)
      FDT_PATH=$(PSDK_QNX_PATH)/qnx/bsp/prebuilt/usr/lib/
      FDT_BIN_NAME=psdk_linux_9.2_k3-j721e-common-proc-board-quad-port-eth-exp.dtb
      FDT_LOAD_ADDR=0x88000000
    endif

  else ifeq ($(SOC), j721s2)

    ifeq ($(QNX_SDP_VERSION), 800)
      FDT_PATH=$(PSDK_QNX_PATH)/qnx/bsp/prebuilt/usr/lib
      FDT_BIN_NAME=psdk_linux_9.2_k3-j721s2-common-proc-board.dtb
      FDT_LOAD_ADDR=0x88000000
    endif

  else ifeq ($(SOC), j784s4)

    ifeq ($(QNX_SDP_VERSION), 800)
      FDT_PATH=$(PSDK_QNX_PATH)/qnx/bsp/prebuilt/usr/lib
      #FDT_BIN_NAME=psdk_linux_9.2_k3-j784s4-evm.dtb
      FDT_BIN_NAME=psdk_linux_9.2_k3-j784s4-evm-quad-port-eth-exp1.dtb
      FDT_LOAD_ADDR=0x88000000
    endif

  else ifeq ($(SOC), j722s)

    ifeq ($(QNX_SDP_VERSION), 800)
      FDT_PATH=$(PSDK_QNX_PATH)/qnx/bsp/prebuilt/usr/lib
      FDT_BIN_NAME=psdk_linux_9.2_k3-j722s-evm.dtb
      FDT_LOAD_ADDR=0x88000000
    endif

  endif

The purpose of this code section is to define the 3 make flags FDT_PATH, FDT_BIN_NAME,
and FDT_LOAD_ADDR when a Device Tree is desired to be loaded. At the time of writing
DTBs are only required when running on a SDP 8.0 platform with io-sock base networking
so these make flags are only defined under SDP 8.0. Consequently, in the PSDK QNX
default soc_config.mk, these flags are only active under SDP 8.0.

To modify which DTB is loaded by the PSDK QNX make system, update the above flags accordingly.

FDT_BIN_NAME is the flag that is checked before modifying the build process. This means
that **if FDT_BIN_NAME is defined, then the other two flags must be defined or build
errors will occur.**


Modifications Required for U-boot Only
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The U-boot uEnv.txt boot script needs to be updated with the load address and name of
the dtb file. An excerpt of default U-boot script, at the time of writing, is shown below:

.. code:: text

  # This uEnv.txt file can contain additional environment settings that you
  # want to set in U-Boot at boot time.  This can be simple variables such
  # as the serverip or custom variables.  The format of this file is:
  #    variable=value
  # NOTE: This file will be evaluated after the bootcmd is run and the
  #       bootcmd must be set to load this file if it exists (this is the
  #       default on all newer U-Boot images.  This also means that some
  #       variables such as bootdelay cannot be changed by this file since
  #       it is not evaluated until the bootcmd is run.

  dtb_name=psdk_linux_9.2_k3-j784s4-evm-quad-port-eth-exp1.dtb
  ifs_load_addr=0x80080000
  dtb_load_addr=0x88000000
  dorprocboot=1

In the uEnv.txt file the variables ``dtb_name`` and ``dtb_load_addr`` must be populated.
In the case of |dev_platform|, the U-boot script to update is
${PSDK_QNX_PATH}/qnx/scripts/u-boot/uEnv\_ |dev_plat_lower|.txt.

Modifications Required for SBL with Bootapp Only
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

As mentioned earlier, the DTB is built into the QNX appimage in the case of SBL with
bootapp. If you need to use a DTB address that is different than the default, then
the QNX appimage linker script needs to be updated:
``${PSDK_QNX_PATH}/qnx/scripts/sbl/ifs_qnx_dtb.lds``. An excerpt of the linker script
is shown below for reference:

.. code::

  /*
   * ifs_qnx.lds - simple linker file for stand-alone QNX IFS booting
   *
   * Copyright (C) 2020 Texas Instruments Incorporated - http://www.ti.com/
   *
   * Use of this source code is governed by a BSD-style license that can be
   * found in the LICENSE.txt file.
   */
  OUTPUT_FORMAT("elf64-littleaarch64")
  OUTPUT_ARCH(aarch64)
  TARGET(binary)
  INPUT(qnx-ifs)
  INPUT(dtb.bin)
  SECTIONS
  {
   . = 0x0000000080080000;
   qnx = .;
   .qnx : { qnx-ifs }
   . = 0x0000000088000000;
   dtb = .;
   .dtb : { dtb.bin }
  }

In this case the address 0x0000000088000000 should be updated to the newly desired DTB
load address.


DTB Address Passing: SBL vs U-boot
----------------------------------

.. IMPORTANT::

  The default QNX IFS (|dev_plat_lower|-evm-ti.build) uses the argument method for getting
  the DTB address. This means that the default QNX IFS is made for U-boot only (at least
  on SDP 800). The PSDK QNX make system will copy this build file and change ``-u arg`` to
  ``-u reg`` automatically for SBL (and name it |dev_plat_lower|-evm-ti-sbl.build). **If using
  a custom build file, make sure that the -u argument is set accordingly.**


There is a important difference in the mechanism in which U-boot vs. SBL pass the
address of the DTB to the QNX image.


- With the QNX provided U-boot instructions, the DTB address is passed by argument to
  the QNX image (via the register ``x1``). For passing the DTB address by argument, the ``-u arg``
  argument must be provided to the QNX IFS startup command. For example, from the J784S4
  build file: ``[+keeplinked] startup-j784s4-evm -u arg -v -s1:1:1:2 -r0xA0000000,0x60000000,1...``.
- In SBL, the DTB load address is passed to QNX from Arm Trusted Firmware (ATF) by value in
  the register ``x0``. For passing the DTB address by argument, the ``-u reg`` argument must
  be provided to the QNX IFS startup command. For example,
  ``[+keeplinked] startup-j784s4-evm -u reg -v -s1:1:1:2 -r0xA0000000,0x60000000,1,1...``.

  - If using a custom ATF image for SBL that has been built outside of the PSDK QNX make
    system, make sure that the build flag ``K3_HW_CONFIG_BASE=$(FDT_LOAD_ADDR)`` is used.
