Connect the debugger to a running target
========================================

Connecting the debugger to a target can help when you want to see the
status of your target after  it has been running for several hours, or even
days; or if you cannot reproduce a crash with the debugger attached. Once
the debugger connected to the target, all the usual functionalities
(break points, step-by-step, variable view, ROV, memory view...) are available.

This step-by-step guide will help you to configure CCS in order to connect to a
running target

1. Modify the GEL file

    In a very simplistic view, the GEL files describe the way the device's
    debugger has to act (more details can be found in the CCS’s help).
    By default, the GEL files ask the device to reset when the debugger is
    started up. Fortunately we can modify this:

    a. Identify the GEL file to modify

        - Start a debug session as always
        - (If needed), display the debug view
        - Right-click on the program being, "Open GEL files View".
        - In the GEL files list, open the corresponding GEL file by
          double-clicking it. Chose cc26x2.gel for CC26x2 and CC13x2 devices.
          Chose cc26x0.gel for CC26x0 and CC13x0 devices.

        .. _locate_gel_file:
        .. figure:: /debugging/resources/locate_gel_file.png
           :align: center

           Locate the GEL file to modify.

        :numref:`locate_gel_file` shows how to find the GEL file to modify.

        .. note::
            Another possibility consists in looking directly in
            ``<CCS directory>\ccs_base\emulation\gel`` for the GEL file.

        .. caution::
            The modifications done in a GEL file affect all the devices using
            the same GEL files. In other words, it affects all the CC26X2 and
            CC13X2 if you modified cc26x2.gel, and all the CC26x0 and CC13x0
            if you modified cc26x0.gel.
            By default, two different CCS versions do *not* use the same
            GEL files.

    #. In the ``StartUp()`` function, comment out the code executing the reset.
       If needed, an explicit comment will help you to identify the code to
       comment out.

        .. _gel_startup:
        .. code-block:: c
            :caption: The StartUp() function after modification.
            :name: StartUp()
            :emphasize-lines: 17-20
            :linenos:

            StartUp(int major, int minor, int patch)
            {
                /* Initialize memory map */
                memorymap_init();

                /* Debugger specific handling */
                if(GEL_MatchesConnection(".*TIXDS.*") == 1)
                {
                    GEL_LoadGel("$(GEL_file_dir)/cc26xx_connect_util.gel");
                    GEL_LoadGel("$(GEL_file_dir)/cc26x2_xds.gel");

                    DefineResets(0);

                    // Issue Board Reset to ensure device is in a known state
                    // Note: If you want to attach to a running target without resetting the
                    //       device, you must comment out the following 4 lines:
                //  if(!GEL_IsConnected())
                //  {
                //      GEL_AdvancedReset("Board Reset");
                //  }
                }
                else if(GEL_MatchesConnection(".*JLink.*") == 1)
                {
                    GEL_LoadGel("$(GEL_file_dir)/cc26xx_jlink.gel");
                }
                else
                {
                    GEL_TextOut("Error: Unknown debugger.\n");
                    return;
                }
            }

    #. Save your modification and close the file. Stop your debugging session

    .. caution::
        The modification of the debug configurations only affects one project.

#. Modify the Debug Configuration of your project

    Once you have clicked CCS's debug button (the green bug), CCS is doing a
    lot of actions for you. For example, CCS loads the program and stops the
    execution of the code on the target. In our case, we don’t want CCS to
    load the program (as we already have a running program...). In addition,
    we don’t necessarily want to stop the execution of the code on the
    target. Fortunately, the way CCS is running a debug session is highly
    configurable. So let's adapt those configurations to our needs.

    a. On the right of the Debug button, there is an arrow.
       Click this arrow and select *Debug Configurations...*.

    #. Select your project

    #. Prevent CCS from loading the program: in the *Program* tab, chose the
       proper *Loading options* (*Load symbols only*)

        .. figure:: /debugging/resources/debug_configuration_1.png
          :align: center

          Open the Debug configurations and modify the loading options.

    #. Prevent CCS from stopping the target: in the *Target* tab, deselect the
       option *Halt the target on a connect*

      .. figure:: /debugging/resources/debug_configuration_2.png
        :align: center

        In the Debug configurations, modify the Connection options.

#. [Optional] Prevent CCS from building the program before load

    As no program will be loaded, it is a bit useless to ask CCS to build an
    image when you start a debug session. As result, you can disable this
    option by using the small arrow at the right of the Flash button. Click
    on *Build Project Before Load* in order to disable the option.

    .. figure:: /debugging/resources/build_project_before_load.png
        :align: center

        Disable "Build Project Before Load" option.

    Now, the debug button does not anymore load code on the device.
    So, how can you load a new image on the device? The easiest way is to use
    the Flash button and select the image to flash. Don’t forget to rebuild
    your image manually (as we have disabled the option before). Another
    solution consists in undoing all the configuration changes we did before.
    A third solution consists in using a different version of CCS.

.. tip:: **You are all set now! Let the code running and, when needed, connect
          to the running target by using the Debug button as you usually do.**
