Debugging TFM-examples
======================

The |TFM| examples can be debugged using code composer studio. There are a few details
that need to be taken care of which are covered in this section.


Building and Running
--------------------

These examples need the secure image provided in the SDK to be flashed along with the
application executable themselves.

The secure image(``tfm_s.axf`` or ``tfm_s.hex``) is found in the path
``SDK_ROOT\tfm_s\build\cc26x4\production_full\Release\outputs``.
This secure image and the generated application ``.out`` file can be flashed in any order
using UniFlash_. They can be flashed in any order.


Debugging
---------
To debug the |TFM| examples, symbols from both the non secure application and the secure
image must be loaded. You can do the following in |CCS|.

1. Launch the |CCS| debug session.
2. Select Tools -> Debugger Options -> Auto Run and Launch Options. Disable Auto Run Option "On a program load or restart".
   Set "Remember My Settings" to allow this setting to persist for subsequent debug sessions.

.. figure:: /debugging/resources/autorun_options.png
 :width: 800
 :align: center

 Autorun and Launch Options

3. Exit and relaunch the debug session. Execution should be paused at _c_int00(). Steps 2 & 3 can be skipped for subsequent debug sessions.

.. figure:: /debugging/resources/execution_paused.png
 :width: 600
 :align: center

 Execution paused at _c_int00()

4. Select Run -> Load -> Load Program. Select ``tfm_s.axf``. This will overwrite the non secure application symbols.

.. figure:: /debugging/resources/load_secure_image_menu.png
 :width: 800
 :align: center

.. figure:: /debugging/resources/load_secure_image.png
 :width: 600
 :align: center

 Load Secure Image

5. Add the non secure application symbols.

.. figure:: /debugging/resources/add_symbols.png
 :width: 800
 :align: center

.. figure:: /debugging/resources/add_non_secure_symbols.png
 :width: 600
 :align: center

 Add Non-Secure Image Symbols

6. Set breakpoints if desired and resume execution to run the example.

.. warning::
 Due to a known issue in the symbol management of |CCS|, you may be disallowed from placing a breakpoint in the
 application. In this case, load the non secure application symbols first, then add the secure image symbols.
 This sequence of loading non secure symbols and adding secure image symbols, forces |CCS| to use the correct symbol manager.

Debug single-step over non-secure PSA API
-----------------------------------------

When using the |CCS| Debugger to single-step in your non-secure program,
special care must be taken when stepping over the following PSA API
functions:

  * psa_connect()
  * psa_call()
  * psa_close()

These functions must be executed with interrupts enabled. They depend
on the Secure Partition Environment's PendSV interrupt handler being invoked.
The PendSV interrupt is used by the secure library to context switch into the
Secure Partition.

By default, the |CCS| debugger is configured to:

   * Disable interrupts while single-stepping at the *assembly* level, causing PSA
     functions to misbehave if you step over them at the *assembly* level
   * Not disable interrupts when single-stepping at the *C source code* level,
     safely permitting the user to step over PSA functions at the *C source level*

The single-step behavior of the debugger can be modified by the following steps.

   1. Tools > Debugger Options > Program/Memory Load Options
   2. Disable interrupts
   3. When assembly stepping > Select
   4. When source stepping > Unselect
   5. When running > Unselect

.. figure:: /debugging/resources/tfm_program_load_options.png
 :width: 800
 :align: center

 Disable interrupts when assembly stepping

In many cases, it is simplest to set a breakpoint after the PSA API and then
run to the breakpoint.


Runtime Object View (ROV)
-------------------------

Runtime Object View can be used with the |TFM| examples just like you would use with
any other non-secure examples.
It must be noted that the ROV session opens up with the latest symbols or program that is loaded.
Adding the symbols does not affect the ROV context.
For example, loading  the secure image symbols after starting the debug session will result in ROV starting up in the secure image context.

.. figure:: /debugging/resources/secure_image_ROV.png
 :width: 800
 :align: center

 ROV when secure image symbols are loaded last

To open the ROV in the context of the non-secure application. Load the non-secure application symbols.

.. figure:: /debugging/resources/non_secure_app_ROV.png
 :width: 800
 :align: center

 ROV when non-secure application symbols are loaded last
