.. _developer_notes_new_host_id:

Alternate TISCI Host ID & User-Mode Privilege UDMA RM
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

Prior to the PSDK QNX 11.02.00 release, the UDMA resource manager utilized elevated privileges for IO access. PSDK QNX 11.02.00 introduces an opt-in feature that enables user-mode privilege access for UDMA IO operations, eliminating the need for elevated privileges.

This feature is implemented through a new host_id configuration that allows UDMA operations to run with user-mode privileges instead of elevated privileges. This change enhances the security picture of the system while maintaining full UDMA functionality.

The new user-mode privilege access for UDMA relies on three key changes:

1. Modifying the compiler option ``PSDK_QNX_USE_LEGACY_HOST_CONFIG`` to opt out of the legacy host configuration.

2. **New Host ID Configuration**: The new host_id is used in the resource manager configuration that has user-mode IO access rights. Refer to the `TISCI Documentation <https://software-dl.ti.com/tisci/esd/latest/5_soc_doc/index.html>`_ for more details on host ID descriptions.

3. **Reduced IO Privilege Level**: The BSP ``.build`` file is updated to use IO privilege level 1 (user-mode) instead of level 2 (elevated privileges) for io-sock (if applicable).


.. IMPORTANT::

    This feature is **opt-in** and requires a few steps to enable. Applications using the legacy host configuration will continue to function as before by default.

.. NOTE::

    - This feature is **only available for SBL boot flow** and is not supported with SPL/U-Boot boot flow.
    - Vision Apps User Guide build steps have not been verified with the new host ID


Prerequisites
-------------

This feature is available on the following SoCs with their respective **new** host IDs:

- **J721E** using new host ID **A72_5**
- **J721S2** using new host ID **A72_5**
- **J784S4** using new host ID **A72_8**

Additionally, the following conditions must be met:

- Processor SDK QNX version supporting this feature (11.02.00 or later)
- Processor SDK RTOS version supporting this feature (11.02.00 or later)
- SBL bootloader is the only supported bootflow (**not** SPL/U-Boot)

    - Refer to step 2b of the :ref:`build_steps_|dev_platform|` documentation for building SBL bootloader.

- Access to sysconfig tool (version >= 1.25.0) for generating board configuration files

    - This tool is optional and only required if building custom board configuration files. PSDK QNX reference configuration files for TI |dev_platform| EVMs are provided with this release and do not require this tool


Enabling User-Mode UDMA Privilege Access
-----------------------------------------

To enable this feature, please follow these steps. Keep in mind there are two methods to build PSDK QNX with the new host ID configuration: using the provided reference RM configuration files or generating custom files using the sysconfig tool.


Build PSDK QNX Reference RM Cfg for New Host ID
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The compiler option ``PSDK_QNX_USE_LEGACY_HOST_CONFIG`` must be set to 0 in your build configuration.

In **${PSDK_QNX_PATH}/qnx**:

Locate your build configuration file (e.g., `psdk_qnx_build.mk`) and ensure ``PSDK_QNX_USE_LEGACY_HOST_CONFIG`` is set to 0 or export the new value in your terminal.

.. code:: bash

    # Set the following flag to 0 to disable legacy host configuration:
    export PSDK_QNX_USE_LEGACY_HOST_CONFIG=0


Build and Test
~~~~~~~~~~~~~~~

Rebuild the bootloader, BSP, and resource managers.


You can verify the status of tisci-mgr and udma-mgr by checking the slog2info output:

.. code:: bash

    slog2info -d | grep -E 'tisci-mgr|udma-mgr'


For both host ID configurations, you will see messages indicating the current implementation for each resource managers startup sequence.

.. code:: bash

    Jan 01 00:00:03.830               tisci_mgr.241679                 slog    130  Using legacy host id with priv IO access configuration
    Jan 01 00:00:03.936              tiudma_mgr.262162                 slog    131  Using legacy host id with priv IO access configuration

    # OR

    Jan 01 00:00:03.830               tisci_mgr.241679                 slog    130  Using new host id with non-priv IO access configuration
    Jan 01 00:00:03.936              tiudma_mgr.262162                 slog    131  Using new host id with non-priv IO access configuration


Reverting to Legacy Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To revert to the legacy configuration with elevated privileges:

1. Re-enable ``PSDK_QNX_USE_LEGACY_HOST_CONFIG`` compiler option
2. Rebuild all components


(Optional): Build with User Generated RM Cfg for New Host ID
-------------------------------------------------------------

.. IMPORTANT::

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

        The sysconfig-generated files must be configured to use the new **A72_5** host_id on |dev_platform|. Ensure your sysconfig configuration includes the appropriate host_id for your target SoC.


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

        The sysconfig-generated files must be configured to use the new **A72_8** host_id on |dev_platform|. Ensure your sysconfig configuration includes the appropriate host_id for your target SoC.


Generate compatible board configuration files using the `sysconfig tool <https://software-dl.ti.com/jacinto7/esd/processor-sdk-linux-j784s4/11_01_00_03/exports/docs/linux/Foundational_Components/Tools/SysConfig_Tools.html>`_, and then update the **${USER_MODE_RM_CFG_PATH}** to point to where the sysconfig generated files are saved. Inside this directory there should be the following files:

- ``sciclient_defaultBoardcfg_tifs_rm.c``
- ``sciclient_defaultBoardcfg_rm.c``

Update the following variables to point to the appropriate directory and filenames (these values are assigned default values in `soc_configs.mk` for building with reference rm cfg):

.. code:: bash

    # example
    export USER_MODE_RM_CFG_PATH=<path_to_sysconfig_generated_files_directory>
    export USER_MODE_RM_C=sciclient_defaultBoardcfg_rm.c
    export USER_MODE_TIFS_RM_C=sciclient_defaultBoardcfg_tifs_rm.c


The build process will automatically overwrite the default rm cfg with the user generated files that are pointed to by the above assigned variables. When ``PSDK_QNX_USE_LEGACY_HOST_CONFIG`` is set back to 1, the files will be reverted back to the original defaults.

Files that will be replaced **${PDK_PATH}**:

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

    .. code:: bash

        pdk_<version>/packages/ti/drv/sciclient/soc/V1/sciclient_defaultBoardcfg_tifs_rm.c
        pdk_<version>/packages/ti/drv/sciclient/soc/V1/sciclient_defaultBoardcfg_rm.c

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

    .. code:: bash

        pdk_<version>/packages/ti/drv/sciclient/soc/V4/sciclient_defaultBoardcfg_tifs_rm.c
        pdk_<version>/packages/ti/drv/sciclient/soc/V4/sciclient_defaultBoardcfg_rm.c

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

    .. code:: bash

        pdk_<version>/packages/ti/drv/sciclient/soc/V6/sciclient_defaultBoardcfg_tifs_rm.c
        pdk_<version>/packages/ti/drv/sciclient/soc/V6/sciclient_defaultBoardcfg_rm.c


Update io-sock startup in BSP .build File
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If not using the |dev_platform|-evm-ti.build file, your custom ``.build`` file must be updated to change the "iolevel" parameter from 2 (elevated) to 1 (user-mode) for io-sock (if applicable).

For example, In **${PSDK_QNX_PATH}/qnx/bsp/images**:

In the ``.build`` file, locate the ``io-sock`` startup line and change ``iolevel=2`` to ``iolevel=1``:

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

    .. code:: bash

        # Before (with elevated privileges):
        io-sock -odtb=/usr/lib/psdk_linux_9.2_k3-j784s4-evm.dtb,iolevel=2 -d cpsw-j784s4

        # After (with user-mode privileges):
        io-sock -odtb=/usr/lib/psdk_linux_9.2_k3-j784s4-evm.dtb,iolevel=1 -d cpsw-j784s4


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

    .. code:: bash

        # Before (with elevated privileges):
        /etc/iosock-cpsw.conf={
        qnx.iolevel="2"

        # After (with user-mode privileges):
        /etc/iosock-cpsw.conf={
        qnx.iolevel="1"


Build and Test
~~~~~~~~~~~~~~~

After making all changes, rebuild the bootloader, BSP, and resource managers.


FAQ and Additional Notes
-------------------------

.. NOTE::

    There has been no change to the BSP startup to use the new host IDs by default. As there are no privilege level concerns with the TISCI calls the BSP makes, it will continue to use the legacy host IDs. There is no difference in functionality for the BSP startup when using either new or legacy host IDs. If user modified BSPs require user mode privileges for TISCI calls, the BSP must be modified to use the new host IDs accordingly.

.. NOTE::

    A living FAQ for this feature is maintained on the TI E2E forums at: `[FAQ] Support for user-mode host-id <https://e2e.ti.com/support/processors-group/processors/f/processors-forum/1598467/faq-tda4-support-for-user-mode-host-id-for-a72-a53-hlos-running-user-mode-drivers>`_. Please vist the link for the latest updates and common questions regarding this feature.