Please note as of Wednesday, August 15th, 2018 this wiki has been set to read only. If you are a TI Employee and require Edit ability please contact x0211426 from the company directory.

How to Run GDB on CCSv5

From Texas Instruments Wiki
Jump to: navigation, search

Return to the Sitara Linux Software Developer's Guide

Preliminary Requirements

  1. The Sitara SDK for your hardware platform has been installed on your Ubuntu host machine.
  2. A serial connection between your host machine and the target board with a serial terminal emulator running on the host.  Minicom is recommended.  You could also use a telnet window to the target system.
  3. An Ethernet connection between your host machine and the target board.
  4. This article assumes that the Remote System Explorer plug-in has been setup to provide an SSH connection to the remote file system.  See  How_to_setup_Remote_System_Explorer_plug-in
  5. Boot up the target EVM.
  6. Start CCSv5 and open the project you wish to debug.
  7. The executable to be debugged must reside in the target file system.  It must have been built from the debug build configuration so that it contains the symbol information.

NOTE: For this example, we are going to debug the dhrystone project

Updated Toolchain

Starting with Sitara Linux SDK 6.0 the location of the toolchain has changed and for non ARM 9 devices a new Linaro based toolchain will be used. Details about the change in toolchain location can be found here. Also details about the switch to Linaro can be found here.

AM18x users are not affected by the switch to Linaro. Therefore, any references to the Linaro toolchain prefix "arm-linux-gnueabihf-" should be replaced with "arm-arago-linux-gnueabi-".

Determining the Target Board Ethernet IP Address

    1. Get the target Ethernet IP address:

root@am335x-evm:~# ifconfig   

You should see a response that is similar to this.  The actual target Ethernet IP address will appear where the is shown below.  (This IP address will be used in a later step):

eth0      Link encap:Ethernet  HWaddr 00:50:C2:7E:8F:D4                             
         inet  Bcast:  Mask:              
         UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1                        
         RX packets:24 errors:0 dropped:0 overruns:0 frame:0                       
         TX packets:3 errors:0 dropped:0 overruns:0 carrier:0                      
         collisions:0 txqueuelen:1000                                              
         RX bytes:3174 (3.0 KiB)  TX bytes:1770 (1.7 KiB)                          
lo        Link encap:Local Loopback                                                 
         inet addr:  Mask:                                       
         UP LOOPBACK RUNNING  MTU:16436  Metric:1                                  
         RX packets:0 errors:0 dropped:0 overruns:0 frame:0                        
         TX packets:0 errors:0 dropped:0 overruns:0 carrier:0                      
         collisions:0 txqueuelen:0                                                 
         RX bytes:0 (0.0 B)  TX bytes:0 (0.0 B)

Creating the Debug Configuration for the Project

  1. In CCS, select the project you wish to work with by clicking on it and highlighting it.
  2. Select the Run -> Debug Configurations menu item.  This opens a dialog box as shown below.


    3. Double click C/C++ Remote Application.  You should then see a new debug configuration named "dhrystone Debug" as shown below. 

        Select your target connection from the Connection drop-down box.  In the example the target connection is called My Target EVM.


4. Click the Search Project button to open the Program Selection dialog box below.  Click on the "armle - /dhrystone/Debug/dhrystone" item and click OK.


5. Click the "Browse..." button for "Remote Absolute File Path for C/C++ Application".  Navgate to the executable file on the remote

    file system.  For this example, the executable file is found at "/usr/bin/dhrystone".


   The .gdbinit file is used by GDB to locate source files and library files on the target. The .gdbinit file is created

   when the SDK environment script runs. Here is an example of a .gdbinit file.


6. Click the Debugger tab.  On the Debugger page, the Main tab should be selected.  Click Browse next to "GDB debugger" and browse to the GDB executable.

  • in the SDK, the path is : /home/sitara/ti-sdk-am335x-evm-
  • the GDB init file is located: /home/sitara/ti-sdk-am335x-evm-

   Click browse next to "GDB command file" and browse to the .gdbinit file in the SDK install directory.  When you try to browse to the .gdbinit file, you will need

   to R-Click -> Show Hidden Files to see the file.   Click the Close button and you are now ready to debug the application!


Running the Debug Session

1. Make sure that you are setup for the debug build configuration which contains symbol information.  In the C/C++ perspective, click on the dhrystone project to select it and

   Project -> Build Configurations -> Set Active -> Debug.

2. The executable file and the folder containing the executable file need to be set to Read-Write-Execute permissions for the GDB Automatic Remote Debugging Launcher to work.

    This only needs to be done the first time.  Click the ">>" in the upper right corner of the CCS window and select the Remote System Explorer perspective.  If you are prompted

    to enter a password, the username should be "root" and the password should be left blank.  Open the Sftp Files node in the Remote Systems tree and navigate under the root

    node to the executable file. 




    3.  R-Click on the dhrystone file and select Properties.  Click Permisions and change it so that all permissions are set.  Also set all permissions on the /usr/bin folder.


4.  Click the green "bug" icon to build the executable, transfer the executable to the target, start gdbserver and and start debugging.

    CCS will change to the CCS Debug perspective. The debug tab will show the running threads and their status. The source code window will show 

    the program halted at the first executable source code line in the main() function. The Variables window will show the local variables and their current



5. To toggle a breakpoint, highlight the line of code in the source code window. Then click the Run -> Toggle Breakpoint menu item.

6. Use the debugger "Step Over" and "Step Into" icons to step through the source code.

7. To resume program execution, click the Run -> Resume menu item. 

    NOTE: Do not click the Run -> Debug menu item, as that will attempt to start a new debug session.

    From here, you can make changes to the C source files, save the changes and then just click the green "Bug" icon again and you will be debugging the new executable on the target.

    (Each time you start the debugger the executable is built, automatically transferred to the target board and the gdbserver program is started for you.)

 Stopping the Debug Session

 When finished debugging the dhrystone application, click the Run -> Resume menu item.   To terminate the program,  click the Terminate icon in CCS (this icon is a red square).


NOTE:  If the program being debugged ends abnormally or crashes, the target console running

           gdbserver may no longer respond.  In that case, the target board must be rebooted to start another debug session.

           To avoid having to reboot the target system, the Remote System Explorer Shell Processes feature can be used to terminate the

           gdbserver process.

See How_to_setup_Remote_System_Explorer_plug-in to setup the Remote System Explorer plug-in.

Once setup, you can follow these steps to terminate gdbserver:

1) Change to the Remote System Explorer perspective.  R-Click on Shell Processes in the target connection tree and select Show in Table to open a Remote System Details window.

2) Double-click on "All Processes" in the table to display the list of processes runnning on the target system.

3) Click on "Executable Name" in the table headers to sort the list by executable name.

4) Find the gdbserver process.  R-Click on it and select Kill.  This will open a "Send a Kill Signal" dialog box.  Click the Kill button.