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, memory view...) are available.

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

#. While the |DEVICE| is running the desired project, open CCS Theia.

#. Go to the Debug view by clicking on the Debug icon on the left side bar.

#. Click on the gear icon to open the launch.json file.

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

#. In the configurations array, add a new configuration object as shown below.

    .. figure:: /debugging/resources/load_symbols_only_theia.png
        :align: center
#. [Optional] If you would like to prevent CCS from halting the program, Right-click
   on the project and select Properties. In the Properties window, select
   Debugger | Connection options and uncheck Halt the target on a connect.

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

#. At this point, you are all set. To connect to the running target, select
   the newly created configuration in the Debug view and click on the green
   play button.

If using CCS Eclipse, connecting to a running target will be slightly different

#. While the |DEVICE| is running the desired project, open CCS Eclipse.

#. Open the Target Configurations window by click on View |rarr| Target Configurations.

#. In the Target Configurations window, expand the Projects folder.

#. Expand your project within the Projects folder inside the Target Configurations window.

#. Expand the targetConfigs folder.

#. Right click on CC2340R5.ccxml and click on Launch Selected Configuration

    .. figure:: /debugging/resources/cc23xx_target_configuration_launch.jpg
        :align: center

#. After a few seconds, CCS will connect to the target and the core will be visible
   in the Debug window.

#. Right click on the core and select Connect Target

    .. figure:: /debugging/resources/cc23xx_core_connect_target.jpg
        :align: center

#. Click on Run |rarr| Load |rarr| Load Symbols...

#. Click on Browse Project.

#. Select your project's out file and press OK.

#. Press OK on Load Symbols window.

#. At this point you are connected to the target and should see where in the project
   the target is currently located.


..
    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.**

