GSG:Debugging projects

Debugging projects

---

Introduction

This section describes the general steps required to create a target configuration and debug the project in CCSv4. 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.

• 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 CCSv4 this is done inside the IDE allowing not only create system-wide configurations 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

CCSv4 provides a very handy graphical target configuration editor that has several pre-configured devices and boards and also allows adapting it to a custom hardware.

Each project can have one or multiple target configurations but only one active.

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

1. 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 CCSv4 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.

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

Fig. 2: Target configuration editor

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. Please check the section GSG:Common_target_configurations for instructions on how to configure common targets.
• The Device section contains all devices compatible with the connection selected. The upper box is a filter that helps selecting the correct device in the lower browse table.

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.

A project can have multiple target configurations but only one active that 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 debugger can be launched by going to menu Target --> Debug Active Project. This will open the Debug Perspective, a different set of windows and menus tailored for debugging.

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

Note: the debugger can also be launched by right-clicking on the newly created target configuration file and selecting Debug As... --> Debug Session. This method does not load the code automatically to the target but is useful if you don't have a project or need to debug SoC devices as in GSG:Connecting_to_slave_cores_in_SoC_devices.

Loading the code

Once the debugger completes the target initialization, the project's output file .OUT will be automatically loaded to the active target and by default the code will be halted at the main() function.

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 or Tools --> MSP430 Debugger Options.

Note: if the debugger was launched by right clicking on the target configuration file as mentioned in the previous section, it is necessary to first connect to the target (right click on the core and select Connect Target) and then load the code to it (menu Target --> Load Program...).

Fig. 3: 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().
• Basic debugging functionality (Run, halt, step in/out, reset) is located in the bar at the top of the Debug view. The menu Target has several additional debug functions.

Tutorial: start the debugger by going to menu Target --> Debug Active Project.

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. 4: The GEL output

Tutorial: in simulator no GEL files are used.

Watching variables and registers

The Local and Watch views are also opened at program load and show local and global variables:

Fig. 5: Viewing variables

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

Register view is not opened by default but can be viewed by going to menu View --> Registers

Fig. 6: Viewing registers

Tutorial: the screenshot above shows all the peripheral registers of a typical C674x device, however in this example the simulator chosen does not simulate the peripherals.

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.

A particularly useful feature of the disassembly window is the mixed source and assembly code viewer shown in the screen below. To use it, simply right-click in the Disassembly view and select View Source

Fig. 7: 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.

Several useful features are available from this screen: the memory can be viewed in several formats, filled with an arbitrary value, saved to/loaded from a binary file in the host PC, all the variables and functions can be viewed, and every memory position has a context-sensitive information box.

Fig. 8: Viewing memory

Tutorial: the screenshot shows the variable volatile short output[16] allocated in memory. All the other variables are local and therefore allocated in stack.

Managing breakpoints

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

• 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. 9: Breakpoint options

To set a breakpoint, simply double-click on the left of the line number in source view or on the left of the address in 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.

Fig. 10: Breakpoint viewer

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

• Action allows to set the behaviour 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 allows to set a 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 at the next section.

Advanced Data Visualization Tools

An advanced graph and image visualization tool is available in CCSv4. 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 as update rate (freeze, continuous, at target halt or manual), zoom in and out, configuration properties, etc.

Fig. 11: The graph toolbar

By default graph windows are updated whenever the target is halted, use 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 Target --> Run. The graph should update in batches of 16 samples.

6. To see the actual values of the output array, click on the tab Watch (should be at the upper right portion of the screen) and click on new. Type output and 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 on the Watch window, right-click and select Q-values --> Q-value(15).

Fig. 12: Sinewave example

Displaying images

To display an image, simply go to menu Tools --> Image Analyzer.

Two views will be opened at the bottom of the screen: Image and Properties.

The images loaded to CCSv4 need to be uncompressed and without header. The byte ordering, format and other properties can be set after it is loaded.

CCSv4 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. Open a memory view by going to menu View --> Memory

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.

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

Fig. 13: Image properties

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

Fig. 14: 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 v4, you can continue to the Advanced Topics section of the CCSv4 Getting Started Guide.

---

CN GSG:Debugging projects