GSG:Debugging projects v5

Debugging projects

---

Introduction

This section describes the general steps required to create a target configuration and debug the project in CCSv5. The sentences marked as Tutorial: show specific steps to debug the example program created in the previous section.

Before starting the debugger

Before the debugger can be started it is necessary to select and configure the target to where the code will execute. The target can be a software simulator or an emulator connected to a board. Note: if the project uses a non-generic device, the target configuration was already configured in the project wizard. Unless it is desired to configure additional target configurations, this section can be skipped.

• Software simulators do not require external hardware and are very useful to perform benchmark and algorithm validation. Additional information about simulation technologies can be found at the link below:

http://processors.wiki.ti.com/index.php/Category:Simulation

• Emulators are hardware devices used to debug directly into hardware and can be either included in a development board (DSK, eZdsp, EVM, etc.) or standalone (XDS100v2, XDS510 USB, XDS560, etc.). Additional information about emulation technologies can be found at the link below:

http://processors.wiki.ti.com/index.php/Category:Emulation

Note: If you are familiar with CCSv3.3 the configuration of the targets was done with the external program CCSetup. In CCSv5 this is done inside the IDE allowing not only a system-wide configuration, but also individual configurations per project. This also has the benefit of completely eliminating the need to restart CCS after each target configuration changes.
Tutorial: in this example a simulator will be used.

Creating a Target Configuration File

CCSv5 provides a handy graphical target configuration editor that has several pre-configured devices and boards, and allows adapting it to a custom hardware.
Each project can have one or multiple target configurations but only one active.

Optional. CCSv5 also allows creating a system-wide target configuration that can be shared among projects.

Important! Additional device support for newer devices and boards is located at the page Device support files.

1. Create the target configuration file. Right-click on the project name and select New --> Target Configuration File

Fig. 1: Creating a new target

2. Give a name to the configuration file - the extension .ccxml will be added. A good idea is to give a meaningful name depending on the target and the emulator used, for example F28335_XDS510USB if you are using an F28335 device and an XDS510USB emulator.

Optional. If the option Use shared location is selected the new target configuration will be shared among all projects and stored in the default CCSv5 directory. This is recommended if you intend to connect to the target without a project or need to debug a SoC device as described in GSG:Connecting to slave cores in SoC devices.

Tutorial: Since the simulator will be used, name the new configuration as C6748_sim.

Fig. 2: Target configuration filename

3. Click Finish. The target configuration editor will open.

4. Two elements of the target must be configured:

• The Connection drop-down menu allows selecting either a software simulator or several types of built-in or standalone emulators. Refer to the GSG:Common target configurations section for instructions on how to configure common targets.
• The Device section contains all devices compatible with the connection selected. (See this Beagle Board set-up for an example) The upper box is a filter that helps selecting the correct device in the lower browse table.

Fig. 3: Target configuration editor

Tutorial: Select Texas Instruments Simulator for the connection and C674x CPU Cycle Accurate Simulator, Little Endian for the device.

5. After selecting the device, click on the Save button. The configuration will be automatically set to Active/Default.

Fig. 4: Project tree with the target configuration

Note: A project can have multiple target configurations but only the active one will be launched automatically.

Note: To see all existing Target Configurations on your system, simply go to menu View --> Target Configurations.

Launching the debugger

Once a configuration is created the debugging process can be started. The debugger opens the CCS Debug Perspective, a different set of windows and menus tailored for debugging.
The debugger can be launched in many different ways:

1. Highlight the project in the Project Explorer view and go to menu Run --> Debug (or the F11 key).
2. Click on the green bug button .
3. Right-click on the newly created target configuration file and select Debug As... --> Code Composer Debug Session.

This will launch the debugger, load the project's output file .OUT automatically to the target and (if configured) run to the function main().

Note: The code will be automatically written to the flash memory of the MSP430, F28x and Stellaris devices. To configure the flash loader properties, launch the debugger and go to menu Tools --> On-chip Flash.

Note: Launching the debugger may cause CCSv5 to build the active project if any modifications to the source code or the build options are made.

Optional: the debugger can also be launched manually. Open the menu View --> Target Configurations. Then expand the tree to point to the desired configuration (either a project-exclusive or a shared configuration), right-click and select Launch Selected Configuration.

This method does not load the code automatically to the target but is mandatory if you do not have a project or need to debug SoC devices as in GSG:Connecting_to_slave_cores_in_SoC_devices.

Tutorial: Start the debugger using one of the first three methods above. After launching, the screen below should be shown.

Fig. 5: Device connection, call stack and source

• The Debug view contains the target configuration and the call stack for each core.
• The source code view shows the program halted at main().
• For convenience, the Variables, Expressions and Registers views are also opened by default.
• Basic debugging functionality (Run, halt, terminate, step in/over/out, reset, restart) is located in the bar at the top of the Debug view. The menu Target has several additional debug functions.

Fig. 6: Debugging toolbar

Note: If the target configuration requires a script to run before the code is loaded, the Console view will open. The scripts are written in GEL (General Extension Language) and are particularly needed to configure devices with complex external memory timings and power configurations.

Fig. 7: The GEL output

The same Console view will also display the build output when the project is built, as well as any Console I/O output such as printf statements in the code. You can toggle between the different Console views using the "Display Selected Console" icon.

Tutorial: in simulator no GEL files are used.

Watching variables, expressions and registers

The Variables and Expressions views are also opened at program load and show local and global variables.

Fig. 8: Viewing local variables

Tutorial: the screenshot above shows the variables in the main() function of <sinewave_int.c>.

The Expressions view is a typical watch window where variables, expressions and even registers can be monitored. To add an expression, simply click on Add new expression and type the variable name, expression, etc.

Fig. 9: Viewing expressions

Tutorial: the screenshot above shows the expression on the right-side of the equals sign ( = ) in line 12. It also shows the global array output.

The Registers view allows looking at the contents of core and peripheral registers of the device.

Fig. 10: Viewing registers

Tutorial: The screenshot above shows the core registers in the simulator. Since in this example the simulator chosen does not simulate the peripherals, their registers are only shown in a hardware target.

Disassembly and mixed source and assembly mode

The disassembly view is not opened by default but can be viewed by going to menu View --> Disassembly.

• It features the mixed source and assembly code viewer (enabled by default), as well as complete correlation with the source line numbers.
• Additional capabilities include assembly step buttons and a jump-to address box that accepts physical address numbers, function and variable names.

Fig. 11: Mixed source/assembly view

Tutorial: The screenshot shows the beginning of function main() of <sinewave_int.c>.

Memory viewer

The memory view is not opened by default but can be viewed by going to menu View --> Memory Browser.

• It features multiple viewing formats and types: char, integer (signed/unsigned), float and multiple Hexadecimal data sizes (8 through 64-bits)
• Additional capabilities include: memory fill with predefined values, save to/load from files in the host PC, all the variables and functions can be viewed, and every memory position has a context-sensitive information box.

Fig. 12: Viewing memory

Tutorial: The screenshot shows the variable volatile short output[16] allocated in memory.

Managing breakpoints

Being the most basic feature in any debugger, breakpoints in CCSv5 add a range of options to help add flexibility to the debugging process.

• Software and Hardware breakpoints can be set directly from the IDE.
• Software breakpoints are limited only by the memory available on the device.
• Software breakpoints can be set to halt inconditionally or conditionally.
• Software breakpoints can perform additional functions other than halt the target: file I/O transfers, screen updating, etc.

Fig. 13: Breakpoint options

To set a breakpoint, simply double-click on the left side of either the line number in the source code view or the address in the disassembly view. The icon for either hardware or software breakpoint will indicate its status and placement.

Note: In optimized code sometimes the breakpoint cannot be set to the exact line in the C source code. This is because the optimizer may condense code and impact the correlation between the assembly instruction and the C source.

All breakpoints (software, hardware, enabled, disabled) can be seen in the breakpoint viewer. To open it, go to menu View --> Breakpoints.

Fig. 14: Breakpoint viewer

To configure the breakpoint, simply right-click on the blue dot or in the breakpoint view, and select Breakpoint Properties....

• Action sets the behavior of the breakpoint to simply remain halted, update one or all debugger views, read or write data to files, activate or deactivate groups of breakpoints, etc.
• Skip Count sets the number of passes before the breakpoint action is executed.
• Group allows grouping breakpoints for advanced control.

Tutorial: Place a breakpoint at line 18. Its properties will be set in the next section.

Advanced Data Visualization Tools

An advanced graph and image visualization tool is available in CCSv5. It can display arrays of data in a graphical form and with several formats.

Displaying graphs

To add a graph, simply go to menu Tools --> Graph and select among one of the various display options.

• Time-based graphs: Single Time and Dual Time
• Frequency-based graphs: all FFT options

The top toolbar in the graph window controls several features such as update rate (freeze, continuous, at target halt or manual), zoom in and out, configuration properties, etc.

Fig. 15: The graph toolbar

By default, graph windows are updated whenever the target is halted, using autoscale and display X axis in number of samples and Y axis in integer values. All these options can be set.

Note: Keep in mind the amount of data transferred for graph updates may impact the real-time operation of the target hardware.

Tutorial: the procedure below displays a graph with the output of the sinewave generator.

1. In the source code window, right-click on the breakpoint blue dot (set at the previous section) and select Breakpoint Properties....

2. At the property Action, click on its value and select Refresh All Windows. This will refresh all windows instead of completely halting the program at this point.

3. The variable output[] contains 16 samples of the sinewave generator output, therefore the entire buffer must be displayed at once in the graph window. Click on Tools -> Graph -> Single Time and configure the options as below:

Property	Value
Acquisition Buffer Size	16
Dsp Data Type	16 bit signed integer
Q_value	15
Start Address	output

4. A graph window should appear at the bottom of the screen. If needed, the graph properties can be changed by clicking on the button .

5. Click on Run --> Resume. The graph should update in batches of 16 samples.

6. To see the actual values of the output array, add it to the Expressions view as mentioned previously. Expand the array to show all its values. These values are printed as 16-bit signed integers, therefore you can normalize them by adjusting the Q value: select all values of the array, right-click and select Q-values --> Select Q-value... and type the value 15.

Fig. 16: Sinewave example

Displaying images

To display an image, simply go to menu Tools --> Image Analyzer.
Two views will be opened: Image and Properties.

• CCSv5 can display information from both a file from the host PC or an image loaded in the target board. In the properties page, simply set the option Image source to either File or Connected Device.
• Similarly to the Graph viewer, it is necessary to set all the other properties before having a meaningful display. Several options like color masks, line sizes and data widths are relevant to properly display the image.

Tutorial: to display an image loaded to the target:

1. Download the file <sample_24bpp.zip> from the link below:

http://processors.wiki.ti.com/index.php/File:Sample_24bpp.zip

2. If you haven't done so, open a memory view by going to menu View --> Memory Browser.

3. In the address box type a valid target address: 0xC0000000.

4. Load the image file <sample_24bpp.rgb> to 0xC0000000: Click on the triangle next to the memory operations icon and then Load. Browse to the directory where you downloaded the image and click Next

5. Type the same start address as in the memory window and the Type-size as 32-bits. Click Finish to load the data.

6. In the Properties view of the Image analyzer, select RGB in the Image Format parameter. All the properties below will be opened. Set them accordingly.

Property	Value
Number of pixels per line	320
Number of lines	240
Data format	Packed
Pixel stride (bytes)	3
Red mask	0xFF0000
Green mask	0x00FF00
Blue mask	0x0000FF
Alpha mask (if any)	0x000000
Line stride (bytes)	960
Image source	Connected Device
Start Address	0xC0000000
Read data as	8 bit data

7. Select tab Image, right-click and select Refresh. The image below should be shown.

Fig. 17: Image display

Several additional debugger functions and views are available. It is strongly suggested to explore these options thoroughly to uncover all functionality of the debugger.

What's next?

Now that you have learned about basic debugging using Code Composer Studio v5, you can continue to the Advanced Topics section of the CCSv5 Getting Started Guide.

---