.. _cc2340r5-cc2340r22-migration-guide:

CC2340R5 to CC2340R22 Porting Guide
***********************************

This section will describe, in general terms, how to migrate
a project developed for the |DEVICE_LOW_PLUS| device to a
|DEVICE_LOW_PLUS_FLASH_DOWN| device running the |SDK|. However,
it is important to first assess the differences between both
devices to make sure that the project migration is possible

Evaluate the |DEVICE_LOW_PLUS_FLASH_DOWN| device when only having |DEVICE_LOW_PLUS| devices
===========================================================================================

To evaluate the |DEVICE_LOW_PLUS_FLASH_DOWN| when only having a |DEVICE_LOW_PLUS|, you can
modify the Flash size as described bellow:

 * Open the Linker command file ``.cmd`` and modify the Flash size
   to |FLASH_SIZE_LOW|.

    .. code-block:: c
        :caption: lpf3_app_freertos.cmd - Replace ``FLASH_SIZE`` value.
        :linenos:

        #define FLASH_SIZE   0x40000

.. note::
    The two devices are API compatible, a project for |DEVICE_LOW_PLUS_FLASH_DOWN| developed on
    |DEVICE_LOW_PLUS| can be migrated (via the migration guide below) 
    with very few modifications to be built and flashed on |DEVICE_LOW_PLUS_FLASH_DOWN|.

Migration Guide
===============

The recommended migration path is to start with a |DEVICE_LOW_PLUS| 
based example project from the |SDK| and follow the next steps:

1. Import the project into Code Composer Studio or you IDE of preference.

2. Open SysConfig, go to ``Device View`` and click on ``SWITCH``.

.. _deviceview_switch_configurationR2_1:
.. figure:: resources/DeviceView_Switch.png
    :align: center

    SysConfig - Switch Device.

3. Once the ``Switch Board or Device`` window is opened, select the
   |DEVICE_LOW_PLUS_FLASH_DOWN| board, or |DEVICE_LOW_PLUS_FLASH_DOWN|
   device and click on ``CONFIRM``. Make sure to save the project changes
   so that the migration takes place.

.. _deviceview_switch_configurationR2_2:
.. figure:: resources/Select_R22device.png
    :align: center

    SysConfig - Select |DEVICE_LOW_PLUS_FLASH_DOWN| device.

.. warning:: If a new linker command file is generated after migration (named ``cc23x0r2.cmd`` in the project files)
             please make sure to exclude it from build (or eliminated it from the project files) so that the original
             ``lpf3_app_freertos.cmd`` file is used during build time.
             
4. Open SysConfig and reduce the internal NVS size, under NVS |rarr| ``Internal Flash``.
   For an out-of-the-box implementation of the examples, consider using 0x3C000 as the
   region base value.

.. _deviceview_switch_configuration_5:
.. figure:: resources/change_NVS_basic_ble.png
    :align: center

    SysConfig - Modify NVS base region.

5. Build the project.

.. TODO once Zigbee OAD is available
    Additional Steps for Off-Chip OAD and MCUBoot examples
    ======================================================

    .. note::
    The |DEVICE_LOW_PLUS_FLASH_DOWN| device does not support On-Chip and Dual Image OAD due
    to reduced Flash size.

    1. Right click on the project file and select Properties.
    Modify the post build steps so that the slot sizes match the ones of the
    |DEVICE_LOW_PLUS_FLASH_DOWN| device.

    .. _deviceview_switch_configurationR2_9:
    .. figure:: resources/modify_post_build_offchip.png
        :align: center

        Project Properties - Modify post build steps.

    2. Import MCUBoot project, modify the ``flash_map_backend.h`` adding the
    following lines of code. In addition, add ``DeviceFamily_CC23X0R22`` as part
    of the ``Predefined Symbols`` of the project (right click on Properties |rarr|
    Predefined Symbols).

        .. code-block:: c
            :caption: flash_map_backend.h - Replace ``BOOT_PRIMARY_1_SIZE`` and ``BOOT_SECONDARY_1_SIZE`` values.
            :linenos:
            :emphasize-lines: 6,9

                #elif defined DeviceFamily_CC23X0R22
                    #define BOOTLOADER_BASE_ADDRESS                 0x00000000
                    #define BOOT_BOOTLOADER_SIZE                    0x00006000

                    #define BOOT_PRIMARY_1_BASE_ADDRESS             0x00006000
                    #define BOOT_PRIMARY_1_SIZE                     0x00036000

                    #define BOOT_SECONDARY_1_BASE_ADDRESS           0x00023000
                    #define BOOT_SECONDARY_1_SIZE                   0x00036000

    3. To finish with the MCUBoot project, go inside ``mcuboot_config`` and do the following:

        - Uncomment the following two lines: 
            .. code-block:: c
                :caption: mcuboot_config.h - Uncomment to enable external flash configuration and enable 
                        the overwrite-only code path.
                :linenos:

                    #define TI_BOOT_USE_EXTERNAL_FLASH
                    #define MCUBOOT_OVERWRITE_ONLY

        - Comment out the following line: 
            .. code-block:: c
                :caption: mcuboot_config.h - Comment to disable the direct-xip code path.
                :linenos:

                    //#define MCUBOOT_DIRECT_XIP
        
    4. Build both projects.