.. _device-configuration:

Device Configuration (CCFG)
===========================

After importing a SysConfig enabled |STACK| project into CCS, by double clicking 
on the ``*.syscfg`` file, a GUI will appear where the project can be configured 
more easily. In the *TI DEVICES* |rarr| *Device Configuration* view, you can
modify the CCFG area of dedicated flash which is used by boot ROM and TI drivers 
to configure the device through the ``ti_radio_config.c/h`` files generated by
:term:`SysConfig`.

.. figure:: resources/device_configuration_cc23xx.png
    :align: center

This section will cover the most utilized features of the *Device Configuration* 
module.

.. note::
    The |DEVICE| device must be re-programmed using the existing configuration 
    for the new settings to take effect.

* Low Frequency Clock Source: LF RCOSC can be selected instead of LF XOSC, but 
  should only be done if the |STACK| configuration allows the additional 
  LF clock inaccuracy which will be introduced

.. _bootloader-configuration:

Bootloader Configuration
------------------------

*Default FCFG bootloader* is the standard selection.  This incorporates the
following settings:

* Serial Bootloader enabled
* Serial IO Configuration Index 2 for UART RX/TX to DIO pins 22/20, respectively 
* Pin Trigger enabled for DIO 21, active low on reset

.. figure:: resources/bootloader_configuration_cc23xx.png
    :align: center

The Serial IO Configuration Index and Pin Trigger DIO for blank devices or FCFG 
default values are fully described in the ROM Serial Bootloader Interfaces
section of the |TRM|.  By using *Default FCFG bootloader, with CCFG settings* 
instead, users can select custom values for each of the above settings.  
Alternatively, *Any bootloader forbidden* will fully disable the bootloader.

.. _device-permission-settings:

Device Permission Settings
--------------------------

This is where device permissions are controlled. Some of the most relevant CCFG permissions are explained below.

#.  **Allow SWD Debug Port:** controls the SWD Debug Port to allow debugging. If enabled, debug access is still dependent on the *Debug Configuration* |rarr| *Debug Authorization Configuration* setting.

#.  **Allow Flash Verify:** checks the integrity of the flash content against a CRC32 value, and it does not return any flash contents.

#.  **Allow Flash Program:** allows to make changes to flash through SACI commands after initial programming.

#.  **Allow Chip Erase:** allows the device to be reprogrammed through SACI or ROM serial Bootloader.

#.  **Allow Return To Factory:** provides only to Texas Instruments a way to unlock the device and do full failure analysis (including flash).

For more information on these CCFG permissions, and instructions for entering 
the SACI mode, please consult their respective sections within the |TRM|.

Flash Configurations for Debug and Production
---------------------------------------------

In this section we will suggest two ways of locking the |DEVICE| devices Flash to avoid unwanted read operations while in production.

.. note::
    Make sure to enable CCFG Sector protection by setting the ``Write/Erase Protection, CCFG Sector`` flag in SysConfig as seen below.

    .. figure:: resources/enable_CCFG_sector_protection.png
        :align: center

.. _lock-flash:

1. **Lock the debug access and make it available only after a chip erase:**

    #. Go to SysConfig |rarr| TI Devices |rarr| Device Configuration |rarr| “Device Permission Settings”
       and disable the ``Allow SWD Debug Port``. You can additionally disable ``Allow Flash program`` and ``Allow Flash Verify``
       if that helps meet your security goals. **Make sure to keep** ``Allow Chip Erase`` **enabled.**

        .. figure:: resources/ccfg_permissions.png
            :scale: 45 %
            :align: center

    #. Go to SysConfig |rarr| TI Devices |rarr| Device Configuration |rarr| “Debug Configuration” and select ``Debug not allowed`` inside the
       ``Debug Authorization Configuration`` field.

        .. figure:: resources/disable_debug_ccfg.png
            :align: center

    #. Save the modifications, build and flash the device.
    
    #. Now the debug access is completely blocked and the debug access point is no longer available. 
       The only access to the device is through SACI which does not provide any method for readback
       of the device contents.

    #. To enter SACI again your tools will need to allow a sequence where the device is held in reset via
       the hardware pin reset and the SWD enable procedure is done. This is the state noted in the |TRM| section 8.3.

    #. From SACI you can perform a full erase of the device, including CCFG which contains the debug and SWD access control fields. 
       Once the full erase is complete then the device is back to state it was when you received it from TI. This erase procedure
       using SACI can be accomplished with `UNIFLASH <http://www.ti.com/tool/UNIFLASH>`_ by enabling the ``Apply pin reset when waking up from the dormant state`` option
       inside the ``New Configuration`` window. Once connected you can perform an erase but cannot read back any memory contents. 

        .. figure:: resources/chiperase_UniFlash.png
            :scale: 60 %
            :align: center

.. _debug-configuration:

2. **Enable debug access with authentication:**

    #. Go to SysConfig |rarr| TI Devices |rarr| Device Configuration |rarr| “Device Permission Settings”
       and enable ``Allow SWD Debug Port``. You can however disable ``Allow Flash program`` and ``Allow Flash Verify``
       if that helps meet your security goals. **Make sure to keep** ``Allow Chip Erase`` **enabled.**

        .. figure:: resources/ccfg_permissions_enableSWD.png
            :scale: 45 %
            :align: center

    #. Go to SysConfig |rarr| TI Devices |rarr| Device Configuration |rarr| “Debug Configuration” and select
       ``Require debug authentication`` inside the ``Debug Authorization Configuration`` field.

        .. figure:: resources/authenticate_debug_ccfg.png
            :align: center

    #. Choose a password between 12 to 64 characters in multiples of four (i.e. 
       32-bit word length). Characters can be letters, numbers or special
       characters.

    #. Use an online `SHA256 tool <https://emn178.github.io/online-tools/sha256.html>`_
       to calculate the hash.

        .. figure:: resources/sha256_tool.png
            :scale: 75 %
            :align: center

        .. note::
            The default password is "Open Sesame!" to produce the default hash in 
            SysConfig.

    #. Select a 32-bit password-ID. This ID typically helps in case you want to have
       different passwords (e.g. if you want to update the password daily on the 
       production line). That way, you can check the password-ID loaded on the 
       device and look-up the password. 

    #. Populate SysConfig with the values found from the above steps.

        .. figure:: resources/require_debug_authentication.png
            :align: center

    #. Save the SysConfig file, re-build the project, and flash the |DEVICE| device.

    #. Afterwards, starting a debug session in the chosen IDE (e.g. IAR or CCS) will
       produce the following error since the debugger has not been provided the 
       chosen password.  
        
        .. figure:: resources/debug_error.png
            :align: center
        
       To resolve this, right-click on the *Project* |rarr| 
       *Debug As* |rarr| *Debug Configurations*.  Then select your active project, 
       enter *Target* |rarr| *Flash Settings* tab, and set the debug password 
       according to the Device Configuration (CCFG) settings.

        .. figure:: resources/debug_flash_settings_password.png
            :align: center

    #. Click on *Apply* and *Debug* to proceed with a typical debug session.