Linux Debug in CCSv5 0
Note: For CCS 5.1 and higher please see this page.
Linux Debug Overview
CCSv5 supports run mode debug (a.k.a. remote GDB debug, agent-based debug), stop mode debug (a.k.a. JTAG debug, OCD) and Linux aware debug (an extension of the stop mode debug).
- In run mode debug, the user can debug one or more Linux processes. On the host side, CCSv5 launches a cross platform GDB debugger to control the target side agent (a GDB server process). The GDB server launches or attaches to the process to be debugged and accepts instructions from the host side over a serial or TCP/IP connection. The Linux kernel remains active during the debug session. The user can only examine the state of the processes being debugged.
- In the stop mode debug, CCSv5 halts the target using a JTAG emulator. The Linux kernel and all processes are suspended completely. The user can examine the state of the target and the execution state of the current process.
- The Linux aware debug is an extension of the stop-mode debug. While the target is halted, CCSv5 reads the Linux kernel data via the JTAG link and allows the user to examine the states of the Linux kernel and all processes and threads.
Run Mode Debug
The following dependencies apply to Run Mode Debug:
- CCS versions: CCS 5.0 or greater
- Devices: Cortex A8 (tested OMAP3430/3530 EVMs and beagleboard, AM3517), should for ARM9 and Cortex A9 as well
- Host requirement: a cross platform GDB debugger
- Target requirement: a GDB server that is compatible with the host GDB debugger
The run mode debug requires two connections to the target system.
- One connection, typically, via a serial port, to the target console is used to execute Linux commands.
- The other connection, typically, via an ethernet port, is used by the gdb debugger to communicate with the gdb server running on the target.
The host system needs to have an installation of a cross platform gdb debugger and the target system needs to have a compatible version of gdb server.
We are going to show how to use CCSv5 to set up the debug in a "hello world" project.
Here are the steps:
- Bring up the Debug Configurations dialog by selecting Run -> Debug Configurations
- Select "C/C++ Application"
- Create a new configuration.
- Set the project to the "hello world" project
- We disable the auto-build option as we are only interested in debugging the hello application only
- It is possible to set up CCSv5 to build the application and deploy to the target automatically.
- Click the link "Select other..." to select a different launcher
- Select the "GDB (DSF) Remote System Process Launcher"
- Click OK
- On the Debugger Main tab, specify the GDB debugger.
- We are using the GDB debugger from CodeSourcery.
- On the Debugger Connection tab,
- specify the IP address and port of the GDB server running on the target.
- You can determine the IP address of the target by executing
the command ifconfig on the target console.
- On the target console , start the GDB server.
- Make sure the port number matches with the one specified in the Debugger Connection tab.
- Launch the debug configuration by clicking the Debug button.
- CCSv5 will launch the GDB debugger to connect to the GDB server.
- After the connection is established, you can step, set breakpoints and view the memory,
registers and variables of the "hello world" process running on the target.
Stop Mode Debug
The following dependencies apply to Stop Mode Debug:
- CCS versions: CCS 5.0 or greater. This facilitates working on either a Windows host, or a Linux host.
- CCSv5.1. A short video clip that shows the procedure below is located here.
- Devices: ARM 926, Cortex A8 (tested on Davinci, OMAPL1x, OMAP 3430/3530 EVMs, beagleboard and devkit8000)
- Target Linux version: 2.6
IMPORTANT! The linux kernel must be built with debugging information. Check the details below in the menuconfig step of the linux kernel build procedures.
- Enable Kernel hacking --> Compile the kernel with debug info
- Also, if the kernel is in experimental mode, you should enable the option below:
- Kernel hacking ---> Enable stack unwinding support
- To check if the kernel is in this mode, check if the option below is enabled.
- General Setup ---> Prompt for development and/or incomplete code/drivers
We are going to show how to use CCSv5 to debug the Linux kernel running on the target.
In this example, the host system needs to have access to the Linux kernel source tree used to build the kernel image and the ELF symbol file (vmlinux) that is generated from the same kernel build.
We are going to do this in two parts:
- First, we show how to create a project that contains all the kernel source code. This will allow us to navigate and search the code much faster.
- Second, we show how to set up a debug configuration to launch the debug.
Creating A Source-code Project for the Kernel
Here are the steps to create a Linux kernel project:
- Create a new C/C++ project by selecting File -> New -> Project.
- Select "Makefile Project with Existing Code"
- Click Next
- Enter the project name
- Specify the root folder of the Linux kernel source tree
- Select no toolchain as we are not going to build the kernel within CCSv5.
- Click Finish
- From the Project view, select the new project
- Right click to display the Properties dialog
- Select the C/C++ Build tab
- Under Workbench build behaviour, uncheck all the boxes.
- Click OK
Associating the Kernel Project with the Target
At this point, you need to have created a Target Configuration, already. That defines what your target board and JTAG emulator are. Having done so, you can proceed to associate the above Project with your Target, as follows:
- Select Run -> Debug Configurations to bring up the dialog
- Select "Code Composer Studio - Device Debugging"
- On the Main tab
- Specify the Target Configuration file, which you had already created.
- You can use the Target Configurations to create the file to match with the target to be debugged.
- In this example, the target is an OMAP 3530 EVM.
- The panes in the screenshot may be disabled depending on what version of CCS you are using. You do not need to change the checkboxes in the disabled pane.
- When creating a target configuration in the configuration editor, it is best to bypass all unused targets. You would also remove the GEL file for the ARM you are going to debug. The GEL file will not work when an OS is present on the target.
- On the Program tab
- Select the device on which the Linux kernel is running.
- In this example, the device is the Cortex A8
- Set the project to the Linux kernel project created above.
- Set the program to the vmlinux file.
- Check "Load Symbol Only"
- Click Apply, to complete the association of your Project with your Target.
We are ready to launch the debugging session. At this point, you ought to have powered up, and paused, the target, similar to these Beagle Board instructions. Now click the Debug button:
- CCSv5 will launch the device debug
- Connect to the Cortex A8
- Load the Linux kernel symbol
- After the symbols are loaded and the call stack is refreshed.
- You are ready to start the kernel debug.
Mixed Mode Debug
The stop mode debug can be used concurrently with the run mode debug.
The user can set breakpoints in the user process using the run mode debug and breakpoints in the kernel using the stop mode debug.
Using the Hello World and the Linux kernel projects, we can launch both debug one after the other.
- From the stop mode debug,
- we set a breakpoint at the function sys_nanosleep
- From the run mode debug,
- we are stepping the main program and
- the debugger is at the source line where the program is going to make a sleep call.
- we are going to step into the call.
- As soon as we step into the sleep call.
- The stop mode debug kicks in as it hits the breakpoint.
- At this point, you are in stop mode debug.
Linux Aware Debug
The following dependencies apply to Linux Aware Debug:
- CCS versions: CCS 5.0 or greater
- Devices: ARM 926, Cortex A8 (tested on Davinci, OMAP 3430/3530 EVMs and beagleboard)
- Target Linux version: Open Source 2.6.19 or later
Linux Aware Debug extends Stop Mode Kernel Debug to provide the capabilities of the process or thread level debug and module debug similar to the Linux Aware Debug feature available in CCSv4.
This feature will not be available in the initial CCSv5 beta release.
Limitations and Known Issues
1. When performing Run Mode debug, by default Eclipse looks in the host PC root directory for runtime shared libraries, thus failing to load these when debugging the application in the target hardware. The error messages are something like:
- warning: .dynamic section for "/usr/lib/libstdc++.so.6" is not at the expected address (wrong library or version mismatch?)
- warning: .dynamic section for "/lib/libm.so.6" is not at the expected address (wrong library or version mismatch?)
- warning: .dynamic section for "/lib/libgcc_s.so.1" is not at the expected address (wrong library or version mismatch?)
- warning: .dynamic section for "/lib/libc.so.6" is not at the expected address (wrong library or version mismatch?)
- [New Thread 1701]
To correct this you must create a gdb command file (.gdbinit) in a text editor (gedit, vim, etc.) and add the following line to it:
- set solib-absolute-prefix /home/user/targetfs (or wherever the target filesystem is located)
Close any GDB debugging sessions. Open the Debug Configurations as shown in the Run Time debugging and then browse to this file in the Debugger tab --> box GDB command file.