.. |OLD_STACK_VER| replace:: |DEVICE| SDK 8.40
.. |NEW_STACK_VER| replace:: |DEVICE| SDK 9.10

|OLD_STACK_VER| to |NEW_STACK_VER|
==================================

This section will describe how to port a project from |OLD_STACK_VER| to
a |NEW_STACK_VER| project.

.. note:: Vulnerability reports and mitigations can be found on `Report potential product security vulnerabilities <https://www.ti.com/PSIRT>`_.

.. _ble-porting-sdk-9-10:

Porting Bluetooth LE Projects
-----------------------------

The recommended method for porting an existing project from |OLD_STACK_VER|
to |NEW_STACK_VER| is to modify the project using only the Code Composer Studio interface.
The following steps will detail the changes needed when porting an out of the box
example from the SDK such as ``basic_ble``:

1. Import the project into Code Composer Studio.

2. In order to modify the SDK version, corresponding SysConfig version, as well as the compiler version, 
right-click on the imported project folder inside the Project Explorer and select ``Properties``.

3. In ``General``, select ``Compiler`` and choose the correct version. Refer to the Dependencies section
in the SDK release notes

  .. figure:: ./resources/8.40_to_9.10_compiler.png
      :align: center

      Code Composer Studio - Change Compiler Version.

4. Go to ``Dependencies`` and double-click on ``SimpleLink Low Power F3 SDK`` and choose the correct version.
Then double-click on ``SysConfig`` and do the same. Refer to the Dependencies Section in the SDK release notes
for the correct versions.

  .. figure:: ./resources/8.40_to_9.10_sdk.png
      :align: center

      Code Composer Studio - Change SDK and SysConfig Version.

If the newest SDK is not available, it will need to be actualized. To do this, go to ``File`` => ``Preferences`` 
=> ``Code Composer Studio Settings``, and select ``Products``. Inside the ``Products`` tab, press the refresh
button, which should discover the latest version of the SDK that was installed.

5. Go to ``Arm Compiler`` and select ``Include Options``. In there, remove the following include paths:

    1. All paths that include ``ble5stack_flash``

    2. ${COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR}/source/ti/bleapp/profiles/health_thermometer

    3. ${COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR}/source/ti/bleapp/services/health_thermometer

6. Go to ``Advanced Options`` and select ``Command files``. In there, remove the two file paths and add:

    1. ${COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR}/source/ti/ble/stack_util/config/build_components.opt

    2. ${COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR}/source/ti/ble/stack_util/config/factory_config.opt

7. Exit the ``Properties`` menu. Right-click the ``SysConfig`` file in the project and select "Open With", then 
select "Text Editor". Then, inside the ``SysConfig`` file, change all instances of ``ble5stack`` to ``ble``.

8. Due to a change in the naming conventions, the following changes are needed for each instance of the
following paths:

.. list-table:: File Renaming
   :widths: 50 50
   :header-rows: 1

   * - Change from
     - Change to
   * - source/ti/ble5stack_flash
     - source/ti/ble
   * - source/ti/ble5stack_flash/lib_projects
     - source/ti/ble/lib     
   * - source/ti/bleapp/services
     - source/ti/ble/services
   * - source/ti/bleapp/profiles
     - source/ti/ble/profiles
   * - source/ti/bleapp
     - source/ti/ble/app_util     
   * - tools/ble5stack
     - tools/ble
   * - source/ti/ble/app_util/util/sw_update
     - source/ti/ble/app_util/sw_update
   * - source/ti/bleapp/ble_app_util
     - source/ti/ble/app_util/framework    
   * - source/ti/bleapp/ble_app_util/inc
     - source/ti/ble/app_util/framework
   * - source/ti/bleapp/menu_module
     - source/ti/ble/app_util/menu
   * - source/ti/ble5stack/.meta
     - source/ti/ble/.meta
   * - source/ti/ble5stack_flash
     - source/t/ble/host
   * - source/ti/ble5stack_flash/npi 
     - source/ti/ble/app_util/npi
   * - source/ti/ble5stack_flash/npi/unified
     - source/ti/ble/app_util/unpi
   * - source/ti/ble5stack_flash/health_toolkit
     - source/ti/ble/stack_util
   * - source/ti/ble5stack_flash/osal
     - source/ti/ble/stack_util/osal
   * - source/ti/ble5stack_flash/icall
     - source/ti/ble/stack_util/icall
   * - source/ti/ble5stack_flash/rom 
     - source/ti/ble/stack_util/lib_opt
   * - source/ti/ble5stack_flash/config
     - source/ti/ble/stack_util/config
            
9. Go to ``common`` => ``Startup`` and click on ``ocal_icall_ble.c`` and edit the following:

    1. Since the previous include paths were taken out in the properties section of the project, the following include paths will need to be changed:
    
    .. list-table:: Include path changes in osal_icall_ble.c
      :widths: 50 50
      :header-rows: 1

      * - Change from
        - Change to
      * - #include “osal_snv.h”
        - #include “ti/ble/stack_util/osal/osal_snv.h”
      * - #include “osal.h”
        - #include “ti/ble/stack_util/osal/osal.h”
      * - #include <icall.h>
        - #include “ti/ble/stack_util/icall/app/icall.h”
      * - #include “hal_types.h” and #include “hal_mcu.h”
        - #include “ti/ble/stack_util/comdef.h”
      * - #include “osal_tasks.h”
        - #include “ti/ble/stack_util/osal/osal_tasks.h”
      * - #include “ll.h”
        - #include “ti/ble/controller/ll/ll.h”
      * - #include “osal_cbtimer.h”
        - #include “ti/ble/stack_util/osal/osal_cbtimer.h”
      * - #include “l2cap.h”
        - #include “ti/ble/host/l2cap/l2cap.h”
      * - #include “gap.h”
        - #include “ti/ble/host/gap/gap.h”
      * - #include “gapbondmgr_internal.h”
        - #include “ti/ble/host/gapbondmgr/gapbondmgr_internal.h”
      * - #include “gatt.h”
        - #include “ti/ble/host/gatt/gatt.h”
      * - #include “hci_tl.h”
        - #include “ti/ble/controller/hci/hci_tl.h”
      * - #include “gattservapp.h”
        - #include “ti/ble/host/gatt/gattservapp.h”
      * - #include “gapbondmgr.h”
        - #include “ti/ble/host/gapbondmgr/gapbondmgr.h”
      * - #include “ble_user_config.h”
        - #include “ti/ble/app_util/config/ble_user_config.h”
      * - #include “ble_dispatch.h”
        - #include “ti/ble/stack_util/icall/stack/ble_dispatch_lite.h”
    
    2. Inside tasksArr::
   
          #ifdef ICALL_LITE
            ble_dispatch_liteProcess,                                         // task 9
          #else
            bleDispatch_ProcessEvent                                          // task 9
          #endif /* ICALL_LITE */
      
      Would become::
          
          ble_dispatch_liteProcess

    3. Inside osalInitTasks::
   
          #ifdef ICALL_LITE
            ble_dispatch_liteInit(taskID++);
          #else
            /* ICall BLE Dispatcher Task */
            bleDispatch_Init( taskID );

          #endif /* ICALL_LITE */
       
       Would become::
          
          ble_dispatch_liteInit(taskID++);

    4. Inside osalInitTasks, remove::
   
          #ifndef ICALL_LITE
            /* Enroll the obtained dispatcher entity and OSAL task ID of HCI Ext App
            * to OSAL so that OSAL can route the dispatcher message into
            * the appropriate OSAL task.
            */
            osal_enroll_dispatchid(taskID, entity);
          #endif /* ICALL_LITE */

    5. Inside stack_main::
   
          #ifdef ICALL_JT
            setBleUserConfig( (icall_userCfg_t *)arg );
          #else /* !(ICALL_JT) */
            setBleUserConfig( (bleUserCfg_t *)arg );
          #endif /* ICALL_JT *

       Would become::
          
          setBleUserConfig( (icall_userCfg_t *)arg );

    6. Inside stack_main::
   
          #if defined(ICALL_LITE) && (!defined(STACK_LIBRARY))
            {
              icall_liteTranslationInit((uint32_t*)bleAPItable);
            }
          #endif  /* ICALL_LITE */

          #ifdef ICALL_LITE
            {
              osal_set_icall_hook(icall_liteMsgParser);
            }
          #endif  /* ICALL_LITE */
       
       Would become::
          
          osal_set_icall_hook(icall_liteMsgParser);
    7. Inside stack_main, remove the following lines::
   
          #ifdef CC23X0
          #ifndef USE_HSM
            if (LL_initRNGNoise() != LL_STATUS_SUCCESS)
            {
            /* abort */
              ICall_abort();
            }
          #endif
          #endif

10. Go to main_freertos.c and edit the following:

  1. Remove the following includes: #include <ti/common/cc26xx/uartlog/UartLog.h> and #include "ble_stack_api.h"

  2. Change the following includes:

      .. list-table:: Include path changes in main_freertos.c
        :widths: 50 50
        :header-rows: 1

        * - Change from
          - Change to
        * - #include <icall.h>
          - #include "ti/ble/stack_util/icall/app/icall.h"
        * - #include "hal_assert.h"
          - #include "ti/ble/stack_util/health_toolkit/assert.h"
        * - #include "bcomdef.h"
          - #include "ti/ble/stack_util/bcomdef.h"
        * - #include "ble_user_config.h"
          - #include "ti/ble/app_util/config/ble_user_config.h"

  3. Turn all log_error0 instances into HAL_ASSERT_SPINLOCK, and remove the log_error2 instance.

11. Delete the following files from the project:
  
  1. ble_stack_api.c inside of iCallBLE folder
  2. ble_stack_api.h inside of iCallBLE folder
  3. icall_api_lite.c inside of iCallBLE folder
  4. ble_user_config_stack.c inside of Startup folder


12. Import basic_ble from the |NEW_STACK_VER| SDK, copy the "lib_opt" folder and paste it in the example you are attempting to migrate.

13. Some files inside the project will still be unresolved, due to the location change. To fix this:
  
  1. Copy the path of the file. Each file's correct path is included in the table below
  2. Right-click on the unresolved file
  3. Select "Edit Linked File"
  4. Replace the current path with the one copied from the table below

  .. list-table:: Linked File Paths
    :widths: 50 50
    :header-rows: 1

    * - File
      - Path
    * - bleapputil_api.h
      - ${COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR}/source/ti/ble/app_util/framework/bleapputil_api.h
    * - bleaputil_init.c
      - ${COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR}/source/ti/ble/app_util/framework/src/bleapputil_init.c
    * - bleapputil_process.c
      - ${COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR}/source/ti/ble/app_util/framework/src/bleapputil_process.c
    * - bleapputil_stack_callbacks.c
      - ${COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR}/source/ti/ble/app_util/framework/src/bleapputil_stack_callbacks.c
    * - bleapputil_task.c
      - ${COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR}/source/ti/ble/app_util/framework/src/bleapputil_task.c
    * - icall_addrs.h
      - ${COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR}/source/ti/ble/stack_util/icall/app/icall_addrs.h
    * - icall_cc23x0.c
      - ${COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR}/source/ti/ble/stack_util/icall/app/src/icall_cc23x0.c
    * - icall_platform.h
      - ${COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR}/source/ti/ble/stack_util/icall/app/icall_platform.h
    * - icall_POSIX.c
      - ${COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR}/source/ti/ble/stack_util/icall/app/src/icall_POSIX.c
    * - icall_user_config.c
      - ${COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR}/source/ti/ble/stack_util/icall/app/src/icall_user_config.c
    * - icall_user_config.h
      - ${COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR}/source/ti/ble/stack_util/icall/app/icall_user_config.h
    * - icall.h 
      - ${COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR}/source/ti/ble/stack_util/icall/app/icall.h
    * - ble_user_config.c
      - ${COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR}/source/ti/ble/app_util/config/src/ble_user_config.c
    * - ble_user_config.h 
      - ${COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR}/source/ti/ble/app_util/config/ble_user_config.h
    * - icall_ble_apimsg.h
      - ${COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR}/source/ti/ble/stack_util/icall/app/icall_ble_apimsg.h
    * - menu_module.c
      - ${COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR}/source/ti/ble/app_util/menu/src/menu_module.c
    * - menu_module.h
      - ${COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR}/source/ti/ble/app_util/menu/menu_module.h
    * - simple_gatt_profile.c 
      - ${COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR}/source/ti/ble/app_util/menu/src/menu_module.c
    * - simple_gatt_profile.h
      - ${COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR}/source/ti/ble/profiles/simple_gatt/simple_gatt_profile.h
    * - dev_info_service.c
      - ${COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR}/source/ti/ble/services/dev_info/src/dev_info_service.c
    * - dev_info_service.h
      - ${COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR}/source/ti/ble/services/dev_info/dev_info_service.h
    * - rom_init.c
      - ${COM_TI_SIMPLELINK_LOWPOWER_F3_SDK_INSTALL_DIR}/source/ti/ble/stack_util/lib_opt/rom_init.c

.. note:: These edits pertain to the basic_ble project. Other projects may require similar edits to other files as well!

Legacy Porting
--------------

.. warning::
   The following section covers a legacy porting method. Current SDK porting
   does not require this process and should instead see
   :ref:`ble-porting-sdk-9-10`.

For this guide, a peripheral project from |OLD_STACK_VER| will be
ported over to |NEW_STACK_VER|. The recommended approach is to start with the
Basic BLE project on |NEW_STACK_VER| and modify the base configuration to
match the peripheral configuration used in the |OLD_STACK_VER| project.
Afterwards, the custom application code should be transferred to the new
project.

#. Import a |NEW_STACK_VER| Basic BLE project.

#. Change the default Basic BLE project configuration options in the BLE Module
   present in SysConfig to match the configuration used in the |OLD_STACK_VER| project.

#. Transfer all custom application logic from the |OLD_STACK_VER| into the
   |NEW_STACK_VER| Basic BLE project.

#. Move any profiles and services that the application is using to the
   |NEW_STACK_VER| project.

#. Transfer the SysConfig settings either visually through the GUI or open both
   the old and the new project ``.syscfg`` files and copy-paste the desired
   settings.

#. If necessary, update the project to use the newer TI drivers that are
   supplied with the |SDK|. Additional details are provided
   in :ref:`noteworthy-ble-migration-sdk-9-10`.

#. Refer to the Core SDK release notes for additional information and the
   FreeRTOS examples included with |SDK|. The Core SDK release notes may be
   found in
   ``{SDK_INSTALL_DIR}/docs/simplelink_mcu_sdk/release_notes_coresdk_lpf3_x_xx_xx_xx.html``

   For additional information on how |NEW_STACK_VER| uses FreeRTOS see
   :ref:`sec-freertos-overview`.

   For any utilized TI Drivers, review |TI_DRIVERS_API|.

.. _noteworthy-ble-migration-sdk-9-10:

A Few Noteworthy Changes from |OLD_STACK_VER| to |NEW_STACK_VER|
----------------------------------------------------------------

You can follow the guide above without addressing these updates; they are listed
for your information only. All fine grained details might not be mentioned. However,
please keep in mind that the file name changes need to be addressed regardless
of the project being migrated. 

Also, due to the crypto drivers being removed from the drivers library and moved into 
a seperate secure drivers library, the  lib folder will need to be added 
(source/ti/drivers/secure/lib). Please refer to the specific example you need to port 
and do a compare between the old and new project files. 

Please refer to the |STACK| Release Notes for all the details.