
.. _getting_started_|dev_platform|:

Getting Started
^^^^^^^^^^^^^^^

.. IMPORTANT::

    **Processor SDK RTOS (PSDK RTOS)**  for |dev_platform| needs to be downloaded separately.

Downloading and installing the PSDK QNX
=======================================

Step 1: Install QNX Packages
----------------------------

- In order to build for a QNX environment, there are multiple packages from QNX Software Center that
  must be installed. This includes the QNX SDP and related packages.  Please refer to the Software
  Dependencies section of the :ref:`release_notes`, for a list of those packages, and ensure they are
  installed on the host build machine.

- Processor SDK QNX (PSDK QNX) for |dev_platform| supports & has been validated with QNX SDP |qnx_sdp_version|. While installing the
  QNX SDP |qnx_sdp_version|, the default install location is:

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

  .. code:: bash

      /home/$USER/qnx800

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

    .. code:: bash

      /home/$USER/qnx710


- The QNX SDP |qnx_sdp_version| can be installed to any directory location, but please update the version and paths
  accordingly in:

   - ${PSDK_RTOS_PATH}/sdk_builder/tools_path.mak
   - ${PSDK_RTOS_PATH}/psdkqa/qnx/qnx_tools_path.mak

Step 2: Download & Install the PSDK RTOS
----------------------------------------

.. IMPORTANT::

    In order to download and compile some components from next step, it is required that your
    PC network proxy is setup properly in case it is not directly connected to internet.

- The PSDK RTOS release can be downloaded from ti.com. [|psdk_rtos_release|]. The version of PSDK RTOS and PSDK QNX should have
  the same major & minor revision number (ex: 11_00_xx_xx). The PSDK RTOS package needs to be installed in your build machine. Here
  after we'll refer to this installation directory as ${PSDK_RTOS_PATH}

- The PSDK RTOS release requires certain packages which are NOT included in PSDK RTOS installer and need
  to be downloaded separately. The script **setup_psdk_rtos.sh** downloads these packages and needs to be run after
  the PSDK RTOS is installed. Refer vision apps user guide [|vision_apps_ug_env_setup|] for more details.

.. NOTE::

    - To run below script, 'sudo' permission is required for installing some components using apt-get. In case you
      don't want to install packages with sudo permission pass below argument to this script: **\--skip_sudo**

    - In case you are only using QNX SBL in your development, you can skip any SPL-related installations
      by passing the below flag when running the setup_psdk_rtos script: **\--qnx_sbl**

    - Make sure to call the script from ${PSDK_RTOS_PATH} as shown above. DO NOT "cd" into sdk_builder/scripts and call the script

.. code:: bash

    cd ${PSDK_RTOS_PATH}
    ./sdk_builder/scripts/setup_psdk_rtos.sh


Step 3: Download & Install the PSDK QNX
---------------------------------------

- Download the psdk qnx package (ti-processor-sdk-qnx\_\ |dev_plat_lower|\ _xx_xx_xx_xx.tar.gz) and extract this to the ${PSDK_RTOS_PATH}

.. ifconfig:: CONFIG_part_variant in ('J721E')

  .. code:: bash

      cd ${PSDK_RTOS_PATH}
      tar -xvf ti-processor-sdk-qnx_j721e_xx_xx_xx_xx.tar.gz -C ${PSDK_RTOS_PATH}

.. NOTE::

    The above step would create the directory by name **psdkqa**.  Please note that from now on ${PSDK_RTOS_PATH}/psdkqa will be referred to as PSDK_QNX_PATH

- Once the PSDK QNX package has been extracted, the ${PSDK_QNX_PATH}/psdk_qnx_setup.sh has to
  be run from the $PSDK_QNX_PATH folder to complete installation. Please check following variables is set correctly in the ${PSDK_QNX_PATH}/psdk_qnx_setup.sh for the script to function correctly.
- Please note: if you are using a newer BSP than this release was generated for **you must do this for the setup script to work correctly**.

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

  .. code:: bash

        QNX_BSP_PATH=${QNX_BASE}/bsp/                                              (The location of the extracted bsp that was downloaded from QNX Software Center)
        QNX_BSP_NAME=BSP_ti-j721e-am752x-evm_br-hw-rel_be-800_SVNxxxxxx_JBNyyy.zip (The QNX BSP zip file)
        QNX_BSP_VERSION=800_SVNxxxxxx_JBNyyy                                       (The QNX BSP version)

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

    .. code:: bash

        QNX_BSP_PATH=${QNX_BASE}/bsp/                                          (The location of the extracted bsp that was downloaded from QNX Software Center)
        QNX_BSP_NAME=BSP_ti-j721e-am752x-evm_br-710_be-710_SVNxxxxxx_JBNyy.zip (The QNX BSP zip file)
        QNX_BSP_VERSION=710_SVNxxxxxx_JBNyy                                    (The QNX BSP version)


- The ${QNX_BASE} referenced is the location in which QNX SDP was installed. The script assumes the default location,
  if QNX SDP was installed elsewhere the path must be updated accordingly.

.. NOTE::

  .. NOTE::

      QNX Software Center would download the BSP archive by default to /home/$USER/qnx800/bsp, however the user can modify this path.

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

  .. NOTE::

      QNX Software Center would download the BSP archive by default to /home/$USER/qnx710/bsp, however the user can modify this path.

.. NOTE::

    Please refer to the Software Dependencies section of the :ref:`release_notes` supported QNX BSP releases.

- The BSP archive must be downloaded using QNX Software Center prior to running the psdk_qnx_setup.sh script.

- After modifying the ${PSDK_QNX_PATH}/psdk_qnx_setup.sh script, launch it with the following command
  from the PSDK_QNX_PATH directory path.

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

  .. code:: bash

      cd ${PSDK_QNX_PATH}
      QNX_SDP_VERSION=800 ./psdk_qnx_setup.sh

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

  .. code:: bash

      cd ${PSDK_QNX_PATH}
      QNX_SDP_VERSION=710 ./psdk_qnx_setup.sh

.. NOTE::

    Make sure to call the script from ${PSDK_QNX_PATH} as shown above.

- The psdk_qnx_setup.sh creates

    #. A QNX specific copy of the PDK in psdkqa/pdk
    #. A TI modified copy of the QNX BSP in psdkqa/bsp


PSDK QNX Build Options
======================

The PSDK QNX provides a build environment to generate QNX binaries and libraries required for the |dev_platform| EVM to run in an QNX environment.
The QNX binaries and libraries must be aligned with the firmware on the other cores of the |dev_platform| device.   By default the PSDK QNX supports
three different variants of firmware images, as described in the following sections.   Each of the build options is exclusive and offers
different features.  The generated PSDK QNX binaries and libraries for each option will only function correctly provided that they are
aligned with the firmware running on the remote cores, for that build option.   When switching between the supported build options,
a full scrub must be done.

PSDK QNX And Vision Apps Demos
------------------------------

- The Vision Apps build environment is used as a centralized build location for both PSDK RTOS and PSDK QNX.
  To build and run the PSDK QNX and vision apps demos, detailed instructions from vision_apps user guide should be followed.
  Refer to the *Build and Run* section of vision apps user-guide. The vision apps user guide is available at the latest
  online documentation [|vision_apps_user_guide|] or in the local installation documentation at
  ${PSDK_RTOS_PATH}/vision_apps/docs/user_guide/index.html

- For details regarding setting the EVM, boot modes etc., please refer :ref:`evm_setup_|dev_platform|`

- Refer to section :ref:`ccs_setup_|dev_platform|` for steps to debug RTOS or QNX cores.

.. NOTE::

    :ref:`build_steps_|dev_platform|` must not be referred when building for vision app demos. For vision apps demos you must refer to the vision apps user guide [|vision_apps_user_guide|].

PSDK QNX And Ethernet Firmware Images
-------------------------------------

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

  .. NOTE::

    The DEVNP driver is specific to io-pkt based QNX SDP 7.1 based releases only.
    This driver is deprecated and no longer provided in the SDK by default.
    If using SDP 7.1 and support for the DEVNP driver is required for your application, please contact your Texas Instruments representative for further assistance. For more information refer to the developer note :ref:`devnp_710_developer_note`.

  This build option provides a QNX setup on the A72 along with support of the CPSW9G, and includes support of the required ethernet
  firmware image running on MCU2_0.

  Please refer :ref:`build_steps_|dev_platform|` for the detailed build instructions.

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

  .. NOTE::

    The section is specific to io-pkt based QNX SDP 7.1 based releases only.
    If using SDP 7.1 and support for the DEVNP driver is required for your application, please contact your Texas Instruments representative for further assistance.
    For more information refer to the developer note :ref:`devnp_710_developer_note`.

PSDK QNX And IPC Echo Test Firmware Images
------------------------------------------

This build option provides a QNX setup on the A72 with firmware images capable of support and IPC test setup.

Please refer :ref:`build_steps_|dev_platform|` for the detailed build instructions.

Resource Managers
=================

The PSDK QNX package provides A72 resource managers as described in PSDK QNX Components, for:

- SCI
- UDMA
- IPC
- Shared Memory Allocator
- IMG Codec

These resource managers must be launched during system initialization.  Examples of this can be seen
in ${PSDK_QNX_PATH}/qnx/scripts/user.sh.  This script file is used during initialization, and is
included in the SD card image generated by following:

-  The *Build and Run* section of vision apps user-guide [|vision_apps_user_guide|].
-  The :ref:`build_steps_|dev_platform|`

PSDK QNX Boot Modes
===================

.. IMPORTANT::

    Refer to PSDK RTOS documentation for detailed information on boot modes and boot flow.


The PSDK QNX package supports 3 different boot modes

    * SPL+Uboot(SD Boot)
    * SBL+BootApp(SD Boot)
    * SBL+BootApp(OSPI Boot)

The steps to get each of these boot modes running is covered in:

-  The *Build and Run* section of vision apps user-guide [|vision_apps_user_guide|].
-  The :ref:`build_steps_|dev_platform|`

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

    .. IMPORTANT::

        In QNX SDP 800, Device Tree Blobs (DTBs) are required to be loaded during the boot process in order to use io-sock based networking. For further details on loading DTBs in U-boot and SBL via the PSDK QNX build flow, please see the associated developer note: :ref:`developer_notes_device_tree_support`.

SPL+Uboot Boot
-----------------

For the SPL/Uboot option, the following binaries are required, which are available as part of the PSDK Linux package:

    * R5 bootloader (tiboot3.bin)
    * A72 bootloader (tispl.bin)
    * U-boot (u-boot.img)
    * DMSC System firmware binary (sysfw.itb).

SBL Boot
---------

For the SBL boot option, we use the SBL bootloader include as part of the PSDK RTOS package. Reference PSDK RTOS |dev_platform| package documentation (|psdk_rtos_user_guide|) for details.

When using the SBL / BootApp boot flow, be aware that the following set of resources are already configured prior to QNX starting.  The settings are mostly done through usage of “Board_init()” calls in SBL or Boot App, which in turn call init functions in the Board library:

**PLLs**:  Refer to the list PLLs that are initialized for both MCU & MAIN domains in the “gBoardPllClkCfgMcu[]” and “gBoardPllClkCfgMain[]” struct arrays, shown in the board_pll.c file here:

    * https://git.ti.com/cgit/processor-sdk/pdk/tree/packages/ti/board/src/j721e_evm/board_pll.c

**Clocks**: Refer to the list of Clocks that are initialized for both MCU & MAIN domains in the “gBoardClkModuleMcuID[]” and “gBoardClkModuleMainID[]” arrays, shown in the board_clock.c file here:

    * https://git.ti.com/cgit/processor-sdk/pdk/tree/packages/ti/board/src/j721e_evm/board_clock.c

**Pinmux**: on the J721E EVM, the main boards and daughter boards are detected and basic pinmux setup is done for the primary functionality used with these boards.  Any other functionality must be customized (for customer boards, etc.).  The pinmux configuration is called using the function “Board_pinmuxConfig” in the file here:

    * https://git.ti.com/cgit/processor-sdk/pdk/tree/packages/ti/board/src/j721e_evm/board_pinmux.c

Related MCU & MAIN domain pinmux selections are possible (depending on which daughter boards are connected to the main EVM), where configurations are shown in these files:

    * https://git.ti.com/cgit/processor-sdk/pdk/tree/packages/ti/board/src/j721e_evm/include/board_pinmux.h
    * https://git.ti.com/cgit/processor-sdk/pdk/tree/packages/ti/board/src/j721e_evm/J721E_pinmux.h
    * https://git.ti.com/cgit/processor-sdk/pdk/tree/packages/ti/board/src/j721e_evm/J721E_pinmux_data.c

There are other files there for different EVM daughter boards, etc.

**DDR**: LPDDR4 memory is configured through the “Board_DDRInit()” function in file:

    * https://git.ti.com/cgit/processor-sdk/pdk/tree/packages/ti/board/src/j721e_evm/board_ddr.c

**Boot media**:  The Boot App will leave the boot media (either OSPI flash or SD card) as previously used, but with handles closed and left in a state to allow the software on the A72 to take over control:

    * MMCSD boot: SD card has been released and is ready for HLOS to take control
    * OSPI flash: Flash is closed & re-initialized in SPI mode, so that the HLOS can reset the flash as needed and re-initialize with its own OSPI



=======
