
.. _cc254x-cc23xx-migration-guide:

CC254x to CC23xx Porting Guide
********************************

This section will describe, in general terms, how to port
a project developed for the CC254x device on the 
**SimpleLink CC254x SDK** to a |DEVICE| device running 
the |SDK|.

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

There are some notable software differences between the |DEVICE|
and the CC254x device. It is important to know and understand what
these differences are when porting your project from the CC254x to
the |DEVICE|. The differences between the `SimpleLink CC254x SDK <https://www.ti.com/tool/download/BLE-STACK-1-X>`_ 
and the |SDK| are covered in-depth in this document. Among these changes
are moving to FreeRTOS from OSAL, implementing multi-threading, 
incorporating BLE5 through use of the BLE5-stack, and much more.

.. FreeRTOS is the new operating environment for Bluetooth Low Energy
    projects on CC23xx devices. This software is a multi-threaded
    environment where the protocol stack, application, and its profiles
    exist on different threads. On the CC26xx devices, TI-RTOS has similar features to OSAL but
    different mechanisms for accomplishing them. This section covers the
    main differences between TI-RTOS and OSAL when developing
    applications on top of the Bluetooth Low Energy protocol stack.
    Although the incorporation of TI-RTOS is a major architecture change, Bluetooth
    Low Energy APIs and related procedures are similar to CC254x.
    Following this, discussion into moving from TI-RTOS to FreeRTOS is explained. 

The following sections discuss the major changes between the
CC254x and the |DEVICE| devices.

* :ref:`sec-general-considerations-cc254x-to-cc23xx`

   * :ref:`sec-general-considerations-OSAL`

   * :ref:`sec-general-considerations-ICall`

   * :ref:`sec-general-considerations-event-processing`

   * :ref:`sec-general-considerations-word-alignment`
   
   * :ref:`sec-general-considerations-FreeRTOS`
   
   * :ref:`sec-general-considerations-launchpad-support-cc23xx`
   
   * :ref:`sec-general-considerations-ble5-enabled`

* :ref:`sec-migration-guides-cc254x-to-cc23xx`

   * :ref:`sec-migration-guides-ble5stack-cc254x-to-cc23xx`

   * :ref:`sec-migration-guides-freertos-cc254x-to-cc23xx`

   * :ref:`sec-migration-guides-ti-drivers-cc254x-to-cc23xx`

* :ref:`sec-compatibility-notes-cc254x-to-cc23xx`

...................................................................................................................

.. _sec-general-considerations-cc254x-to-cc23xx:

.. _sec-general-considerations-OSAL:

OSAL
----

A major change in moving to FreeRTOS is the complete removal of the
application from the OSAL environment. While the stack code uses
OSAL within its own thread, the application thread can only use the
APIs of OSAL that are defined in ICallBleAPI.c. Many functions such
as ``osal_memcpy``, ``osal_memcmp``, and
``osal_mem_alloc()`` are unavailable. These functions have been replaced
by FreeRTOS, C runtime, and ICall APIs.

.. _sec-general-considerations-ICall:

Application and Stack With ICall
--------------------------------

In the CC23xx Bluetooth Low Energy protocol stack, the application
and the stack now communicate with one another through the use of messages. 
Messages between the application and stack pass through a framework developed 
called ICall (Indirect Call Framework). This functionality lets the application 
call the same APIs used in OSAL but is parsed by the ICall and sent to the
stack for processing. Many of these stack functions are defined in
``icall_ble_api.h`` for the application to use transparently while ICall
handles the sending and receiving from the stack transparently.

ICall has been optimized for reduced flash usage and increased stack
operational efficiency. 

No ICall/Stack API changes are required to realize these benefits.

For details regarding improved ICall and it's benefits, see :ref:`sec-the-application-icall-lite`.

For additional information on ICall see :ref:`icall`.

.. _sec-general-considerations-threads-semaphores-queues:

Threads, Semaphores, and Queues
-------------------------------

Unlike single-threaded operating systems such as OSAL, FreeRTOS is
multi-threaded with custom priorities for each thread. The FreeRTOS
handles thread synchronization and APIs are provided for the
application threads to use to maintain synchronization between
different threads. Semaphores are the prime source of
synchronization for applications. The semaphores are used to pass
event messages to the event processor of the application.

Profile callbacks that run in the context of the Bluetooth low
energy protocol stack thread are made re-entrant by storing event
data and posting a semaphore of the application to process in the
context of the application. Similarly, key press events and clock
events that run in ISR context also post semaphores to pass events
to the application. Unique to FreeRTOS, queues are how applications
process events in the order the events were called and make callback
functions from profiles and the stack re-entrant. The queues also
provide a FIFO ordering for event processing. An example project may
use a queue to manage internal events from an application profile or
a GAP profile role (for example, Peripheral or Central). ICall uses
a queue and it is accessed through the ICall API. 

For more information on FreeRTOS and its features, see :ref:`sec-freertos-overview`

.. _sec-general-considerations-event-processing:

Event Processing
----------------

Similar to OSAL, each FreeRTOS task has two functions that implement the
fundamental tasks for an application: ``Peripheral_start()`` and
``BLEAppUtil_Task()``.

The `BLEAppUtil framework` framework has a dedicated folder for ICall containing ICall registration routines.
The ``Peripheral_start()`` function has all the initialization functions for the application 
profiles and the GAP and GATT roles. The initialization includes
setting up callbacks that the application should receive from the
profile and stack layers. For more details on callbacks, and other
messaging systems see :ref:`intertask_messages`.

``BLEAppUtil_Task()`` contains an infinite loop in which
events are processed. After entry of the loop and having just
finished initialization, the application task calls ``mq_receive()`` to
block on its semaphore until an event occurs.

Similar to ``osal_set_event()`` in a CC254x application, the
application task can post the semaphore of the application with a
call to ``mq_send()`` after setting an event. An alternative way is to enqueue
a message using ``BLEAppUtil_enqueueMsg()`` which preserves
the order in which the events are processed. 

Events can come from within the same task, the profiles, or the stack.
Events from the stack are handled first with a call to
ICall_fetchMsg() similar to ``osal_msg_receive()`` in a CC254x
application. Internal events and messages from profiles or the
GAP roles, that are received in callback functions, must be treated as
re-entrant and should be handled in the ``BLEAppUtil_Task()`` function
too. In other words, processing should be done within the application context.
In many cases such as in GAP role profile callbacks, you must
place events in a queue to preserve the order in which messages
arrive. For general overview of application architecture see :ref:`the_application`.

.. _sec-general-considerations-word-alignment:

Word alignment boundary support in CCS for split image build configurations
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

In previous versions of Code Composer Studio, the flash-loader driver
was limited to writing/reading/erasing a page at a time.

Utilizing the upgraded word aligned CCS flash-loader driver in CCS 7.0.0 and newer, along
with enhancements in the Frontier tool, limits the worst case to the size of
a word (32 bits). Word alignment allows for additional available Flash to be used
by the application or the stack.

.. _sec-general-considerations-FreeRTOS:

FreeRTOS
--------
The |DEVICE| devices exclusively support FreeRTOS. If a project
needs to be migrated from the **SimpleLink CC254x SDK**, then
it will need to be converted to FreeRTOS during the migration process.

.. _sec-general-considerations-launchpad-support-cc23xx:

LaunchPad support
-----------------
Find support and all the collaterals for the LaunchPad CC2340R5 in the |DEVICE| LaunchPad Development Kit Product Page:
`CC2340R5 LaunchPad`_

.. `CC23xx LaunchPad Development Kit Product Page <http://www.ti.com/tool/LP-EM-CC2340R5>`_'

.. _sec-general-considerations-ble5-enabled:

Bluetooth 5.2 Enabled
---------------------

If your project wasn't already on a BLE5 platform, the |DEVICE| will provide the
ability to support the new features of Bluetooth 5.2. This includes features such
as higher throughput, longer range, advertising extensions, and improved coexistence
with other wireless technology.

.. _sec-migration-guides-cc254x-to-cc23xx:

Migration Guides
----------------

.. _sec-migration-guides-ble5stack-cc254x-to-cc23xx:

Migrate to BLE5 stack
---------------------

If migrating from a **SimpleLink CC254x SDK** based project to a
|SDK| based project, then it is necessary to migrate the **SimpleLink CC254x SDK**
project to the BLE5 stack if it's not already in the BLE5 stack. This initial migration
will greatly ease the porting process further down the line.

If the project has not already been migrated to the BLE5 stack, then the :ref:`blestack_to_ble5stack`
guide should be leveraged to aid in this section of the migration.

.. _sec-migration-guides-freertos-cc254x-to-cc23xx:

Migrate to FreeRTOS
-------------------

An important step that must be taken in order to port an example from the
**SimpleLink CC254x SDK** to the |SDK| is to ensure that
the project is implemented in FreeRTOS. The |SDK| only supports
FreeRTOS, so any projects running on OSAL will not work unless they
are converted to FreeRTOS. This part of the process should be done after the
application code has been transferred to a sample project running on the |SDK|.

.. _sec-migration-guides-ti-drivers-cc254x-to-cc23xx:

Migrate the TI drivers
----------------------

Aside from the change in RTOS and BLE stack, peripheral
drivers represent a significant change from the CC254x architecture.
Any drivers used by the CC254x project must be ported to the
respective |SDK| drivers. 

It is recommended to reference relevant TI drivers examples in the
|SDK| when porting driver code from the **SimpleLink CC254x SDK** to
the |SDK|. The API Guides available for the |SDK| contain function descriptions,
example code, return codes, and parameter descriptions that can be verbosity
helpful during the migration process. 

For example, if SPI was used in the original **SimpleLink CC254x SDK** project then
the ``spicontroller`` and ``spiperipheral`` |SDK| example projects should be referenced. These
projects will showcase how the SPI driver is used and works in the |SDK|.

The changes in the TI Drivers from the **SimpleLink CC254x SDK** to the
|SDK| varies in complexity and amount depending on the specific driver.
To learn about how the TI Drivers work and should be used, the documents referenced
earlier in this section should be leveraged.

It is important to ensure that projects that are being ported to CC23xx are
not using deprecated libraries. A few migration guides for libraries
that should be updated are shown below:

*  :ref:`uart_to_uart2-porting-guide`
*  :ref:`sec-cc23xx-gpio++-porting-guide`
   
.. _sec-compatibility-notes-cc254x-to-cc23xx:

Compatibility Notes
-------------------

Due to a number of improvements and feature additions, the recommended migration
path for customers is to start with a CC23xx based project and migrate any
custom application code and project configuration to the new project.
