C2000 Getting Started with Code Composer Studio v5

Introduction

Code Composer Studio is TI's integrated development environment (IDE) for TI embedded processors.

This wiki article covers getting started topics for C2000 users who are:

• New and starting with CCS v5.1
• Migrating from CCS v4 to CCSv5.1
• Migrating from CCS v3.3 to CCSv5.1

Changes from CCSv4

If you are migrating from CCSv4, then reading through the CCSv5 Changes Wiki Page is highly recommended.

Other Training Material

For all generic CCSv5 topics which are not C2000-specific, or to better understand CCSv5 in more detail, please visit the Code Composer Studio Wiki:

• Code Composer Studio v5 Wiki

The following workshop material is targeted to other device families. However much of it is still generic CCS v5.1 information and will apply to the C2000 MCUs.

• CCSv5 Fundamentals Workshop: Introductory hands-on training for CCSv5.1 using an MSP430 LaunchPad
• CCSv5 Advanced Workshop: Deeper dive into some of the more advanced functionality of CCSv5.1 using an AM3517 Experimenter Board

Key Eclipse Terminology

Workspaces

In CCSv5 a workspace is:

• Main working folder for CCS
• Contains information to manage all the projects defined to it
• The default location of any new projects created
• User preferences, custom perspectives, cached data for plug-ins, etc are all stored in the workspace
• Multiple workspaces can be maintained
  • Only one can be active within each CCS instance
  • The same workspace cannot be shared by multiple running instances of CCS
  • It is not recommended to share workspaces between users

Note: Workspaces in CCSv5.1 are the same as in CCSv4.x. Workspaces are not portable because they contain data specific to your computer system. You cannot save a workspace, zip it up, and send it to another user. A CCSv5.1 workspace should not be confused with the CCSv3 concept of workspace.

Workbench

Workbench refers to the main CCSv4 GUI window Equivalent to the "Control Window" in CCS 3.x. The Workbench contains all the various views and resources used for development and debug.

CCS 3.x

Each debuggable CPU must have their own instance of the Control Window

• Only one Control Window can be opened for each debuggable CPU
• Information is not shared between each Control Window

CCS v4 and v5

• One Workbench window can have visibility to all debuggable CPUs
• Multiple Workbench windows can be opened ('Window->New Window')
• Each Workbench window can differ visually (arrangement of views, toolbars and such), but refer to the same workspace and the same running instance of CCSv4. A project is opened from one Workbench will appear to be open in all the Workbench windows

The CCSv5 concept of workbench makes working with dual cores such as the C28x and CLA or the Concerto M3 and C28x. You can choose to work with both cores within one workbench, or you can open a workbench for each CPU.

Views

Views are the individual windows which provide a visual representation of information within the workbench. For example the Memory View visually shows a view of memory contents. Another example is the Expression View which shows the results of different expressions. Most Views can be opened through the View menu.

Perspectives

A perspective defines the set and layout of views (i.e. windows) in the Workbench window. Each perspective provides a set of functionality aimed at accomplishing a specific type of task. For example "CCS Edit" for project development, "CCS Debug" for debugging. You can also create custom perspectives.

CCS is likely in the Debug Perspective at this point. This automatically happens when the code is loaded to the MCU.

To switch between perspectives:

• On the upper right you will find a "Open Perspective", "CCS Edit" button, and "CCS Debug" button.
• Click on the "CCS Edit" button to switch back to "CCS Edit" Perspective. The resources now visible are those used for project development.
• Click on the "CCS Deubg" button to switch back to the “CCS Debug” Perspective. The resources now visible are those used for project debug.
• Click on "Open Perspective" to view other defined perspectives.

Perspective Selection

Starting Up CCSv5.1

Select a workspace

When you first open CCSv5.1, a dialog box will prompt you to select a workspace. This is a folder where all of your custom settings will be saved for your specific personal computer. This includes all of your project settings, macros, and views when you shut down CCSv5. For instance, if you have several projects + memory windows + graph window + watch variables that you were working with when you closed CCSv5.1, these same projects and settings will be available when you re-open CCSv5.1.

Note: Workspaces save automatically when you close Code Composer Studio. If you don't want to overwrite the settings you have for a current workspace, you can open / switch to a new workspace by going to: "File-> Switch Workspace".

Select a Workspace

Resource Explorer

Resource Explorer will display the first time CCS is used with a new workspace. The Resource Explorer includes many getting started resources as well as resources advanced users will find helpful. These include:

• Getting Started video introduces you to CCS
• Contains links to documentation, examples, support resources
• Buttons to create a new project or import an existing one into your workspace

To open Resource Explorer at a later time: "Help->Welcome to CCS".

Run Your First C2000 Project in CCSv5.1

Set up the Target Configuration Options

A Target Configuration tells CCS how to connect to the device. It describes the device using gel files and device configuration files.

1. Go to the "View->Target Configurations" menu.
2. Click on the "New Target Configuration File" icon.
   
   
   

   Create a New Target Configuration
   • Type a name for the target configuration file. It will have a “.ccxml” suffix.
   • Leave the "Use shared location" box checked.
3. Select "Finish".
   
   
   

   New Target Configuration
   
   
   
4. In the window that appears, select your emulator via the “Connection” pull-down list.
5. In the “Device” list, select your device.
   • In this example, we have selected the “XDS100v1 Emulator” and the “TMS320F28069” device checkbox.
     
     
     

     Target Configuration
     
     
     
6. Click on the "Save" button or use “File->Save”
7. Go to “View->Target Configurations”
   • Under “User-Defined”, you will see your new target configuration.
8. Right-click the configuration.
9. Select "“Set as Default”" if you want to use this emulator and device GEL file by default for all future projects opened in your workspace that do not have a target configuration assigned to them.
   • Alternatively: Select “Link File to Project ->Example_2806xCpuTimer", to always use this target configuration for this specific project in your workspace.
     
     
     

     Set Default Target Configuration for a Project

Open the CCSv4 cpu_timer project included with controlSUITE (www.ti.com/controlsuite)

This example shows how to load one of the CCSv4 projects from controlSUITE. CCSv4 projects can be imported directly into CCSv5. These instructions are for the CPU Timer example for the F2806x devices. Similar instructions can be followed for any project.

1. For now you can close resource explorer.
2. Go to "Project->Import Existing CCS/CCE Eclipse Project"
   
   
   

   Import Existing CCS4 or CCS5 Project
   
   
   
3. Next to “Select Search Directory”
   • Click on the “Browse” button
   • Browse to the project directory. In this example we will use the "<controlSUITE>/device_support/f2806x/<version>/f2806x_examples/cpu_timer" directory
   • Select “OK”.
   • Make sure “Example_2806xCpuTimer” is selected in the “Projects:” textbox.
   • Important: For example projects supplied by TI, do NOT check the “Copy projects into workspace” checkbox.
4. Click on the “Finish” button.
   
   
   

   Eclipse Import Wizard
   
   
   
   

If the project is CCSv4 based, Code Composer Studio will convert the build option files to the required CCSv5 format.

• Select "Yes" to port the build option files.
• The original CCSv4 files will be saved in .cdtbuild_initial and .project_initial. These files can be used to restore the CCSv4 build options if needed.
• Projects ported to CCSv5.1 can not be loaded directly into CCSv4. The .cdtbuild and .project files must first be restored.
  
  
  

  Converting a CCSv4 Project
  
  
  

You are now in the CCS Edit perspective. The project files appear in the “Project Explorer” view.

Project Explorer

Binaries

After the project is built, the .out file for the project is located here.

Includes

All directories with include referenced by the build options are listed here. Expanding the directories lists all .h and .inc files in these directories which may or may not be used by the project.

Debug

All debug files are located here, including .map and .obj files.

Source Files

All source files are listed. If any source files contain functions, include files, or structures, selecting the “cross” next to the source file lists all the function, include file, and structure names in that file. Double-clicking the function names brings you to where the function, include file, and structures are defined in the source code.

Note: Opening Multiple Projects: As in CCSv4 multiple projects can be imported into CCSv5.1 at one time. One difference is the concept of "active project" is no longer used in CCSv5.1. This is discussed in more detail in the building projects section.

Launch the Debugger

To build the project and launch the debugger:

1. Select the project by clicking on the project's name in the "Project Explorer" view.
2. Click on the green bug ("debug" button) on the toolbar.
   
   
   

   Debug Button
   
   
   
3. Code Composer will do the following:
   • Save any open files in the project selected
   • Build the selected project.
   • Automatically switch to the CCS Debug perspective
4. The "Debug" view will now be visible.
   • This view should always be open (do not close it). If you should close it, you can open it again using the "view->debug" menu item.
   • It allows you to connect to the target device and control it (run, step, etc).
     
     
     

     Debug View - Don't Close This!
     
     
     

The debugger can also be launched by a right click on the target configuration and selecting "Launch Selected Configuration". This will not build the project, however.

Launch Configuration

Connect to the Target

To Connect to the target:

1. In the debug window, select the CPU you wish to connect to.
   • In this example the C28x core is selected.
2. Right click on the core and select "Connect Target"
   • Alternative: Select "Run->Connect Target"
   • Alternative: Use the keyboard shortcut CTRL-ALT-C
     
     
     

     Connect to the Target
     
     
     

Note: You can configure the debug button to also automatically connect to the target after launch: In the CCS Debug perspective: "Tools -> Debugger Options -> Generic Debugger" and slect "Connect to Target on Debugger Setup".

Build the Project

To Build the Project without connecting to the target, or to build it after you have already connected, follow these steps:

1. Make sure the project has been selected by clicking on the name in Project Explorer
   • Note: In CCSv4 you would make the project the "active project" before building. In CCSv5 there is no concept of active project. Instead select the project by clicking on the name.
2. Click on the "build" button which is a small hammer in the toolbar.
   
   
   

   Build the Project
   
   
   

Alternative

You can also build using the "Project->Build Project" menu item.

• This menu is also visible in the debug perspective.

If you have multiple projects that you would like to build one after another:

1. Import all of the projects into Project Explorer
2. "Project->Build All"

Load the Application

At this point the CPU Timer example application is likely already loaded onto the target and you will see the source code for the main function. If this is not the case, then load the application by:

1. In the CCS Debug Perspective
   • If needed refer to Perspectives
2. Select "Run->Load->Load Program"
3. Select "Browse Projects". All projects imported into CCS will be shown along with their .out file if it exists.
4. Select the .out file you want to load into the MCU.
5. Select "Ok".

Load Application

Reset the CPU

Restart and Reset are available on the Debug Toolbar:

Reset and Restart

Alternatively:

• Select "Run->Reset->Reset CPU" to reset the device.
• To restart the program, select "Run->Restart".

Reset

Reset is similar to pulling the device reset pin. Most registers on the device will return to their default state. Some exceptions are PLL configuration, for example.

Restart

This will force the PC to the "entry point" of the application. In most of the C2000 examples this is defined as the symbol "code_start". It should be noted that using "Restart" will bypass executing the boot ROM code. If you are trying to debug issues when an application runs stand-alone, it is recommended to not use restart since it bypasses the boot ROM and the jump to flash.

Note: In the debugger options, you can specify the action to take on a reset, program load or restart. For example "run to main". Disable this option if you want to step through the boot code before main()!

Add Variables to the Expression View

To quickly add variables to the expressions view:

1. Make sure you are in the CCS Debug perspective.
   • If needed refer to Perspectives
2. In “Example_2806xCpuTimer.c”, scroll down in the comments at the top of the file until you reach "“Watch Variables”".
3. Highlight “CpuTimer0.InterruptCount”, right-click, and select Add Watch Expression.
4. A menu will open showing the expression you are adding. Click "ok".
5. Then repeat for “CpuTimer1.InterruptCount” and “CpuTimer2.InterruptCount”.
   • These variables are now in the Expressions View.
   • You can also add expressions directly to the Expression View. Simply click "Add New expression" and type the expression that you want to evaluate. For example, (CpuTimer0.InterruptCount + 5)*3. Then click ok.
     
     ::
     

     Expressions View
     
     
     

Note: The Expression View was called the Watch View in CCS v4 and the Watch Window in CCS v3.3

Enable real-time mode to monitor the watch variables as they are changing

To enable real-time mode:

1. Make sure you are in the CCS Debug perspective.
   • If needed refer to Perspectives
2. Click on the clock at the top of the CCS Debug perspective.
   
   
   

   Enable Realtime Mode
   
   
   
3. CCS will ask you if you would like to change bit 1 of the ST1 status register to 0. This is required to enter real-time mode.
4. Select "Yes".
5. In the upper right-hand corner of the watch window, click on the white down-arrow and select “Continuous Refresh Interval”.
6. Change the Continuous Refresh Interval to “100” (milliseconds) instead of the default “500” (milliseconds).
7. In the upper right-hand corner of the watch window, click on the icon of the yellow arrows rotating to enable continuous refresh mode.
   
   
   

   Configure Refresh Interval and Enable Refresh
   
   
   

Run the program

1. In the CCS Debug Perspective
   • If needed refer to Perspectives
2. Select the green arrow icon on the toolbar or go to "Run->Resume"

Debug Toolbar

Watch the variables in the Watch Window increment once per second as the CPU timers interrupt. Congratulations!! You just finished running your first C2000 project in CCS v5.1!

Portable Projects in CCSv5 or What happened to macro.ini?

You may be familiar with a file called macro.ini that was used to create a portable project in CCSv4 (Refer to: Portable Projects in CCSv4 for C2000). Since that time, Eclipse has implemented the capability to store path-variables in the project's settings and the macro.ini is no longer needed.

You can now define and edit the path-variables at the project scope:

1. Make sure you are in the CCS Edit perspective.
   • If needed refer to Perspectives
2. Right click on the project's name
3. Select "Properties -> Resource -> Linked Resources"
   • You can now view, add or edit the macros for the project.
   • Multiple projects now store their variables at the project scope, not at the global scope.
   • Avoids name collisions between multiple projects.
   • Existing macros.ini files are automatically processed when a CCSv4 project is imported. In the below screenshot, the macros indicated with a blue square were processed from the macro.ini file and automatically added to the project properties when the project was imported.
     
     
     

     Linked Resource Macros in the Project Properties
     
     
     

Note: Knowing the resolved pathname of a macro can be useful when trying to debug issues with a linked resource. If you would like to see the full path that a macro resolves to, then right click on the project name and open the linked resources page ("Properties -> Resource -> Linked Resources"). Now double click on the name of the macro. An edit dialog box will open. Under the macro, you can view the fully resolved path name.

Resolved Macro Path in the Edit Macro Dialog Box

.

Linking New Files to a Project

To link new files into a project do the following:

1. Make sure you are in the CCS Edit perspective.
   • If needed refer to Perspectives
2. In the Project Explorer view, right click on a project name and choose "Add Files"
3. Choose files that you would like to add and click "Open"
4. A dialog that pops up providing options to copy files or link files.
   • If you choose "link file" then you can choose whether to create a link relative to the PROJECT_LOC macro or a macro you created.
   • The PROJECT_LOC macro resolves to the current project's location.
     
     
     

     Linking a New Source File

Note: You can also drag/drop files to a CCSv5 project. Configure the action to be taken on drag/drop in the Window->Preferences->General->Workspace->Linked Resource menu.

Programming Flash

An improvement in CCSv4 and CCS v5.1 over CCSv3.3 is that the flash-programmer plug-in is built in. When you debug a project which has its source code and command linker file configured for flash memory, you no longer need to load the symbols only and then separately use the flash programmer plugin to program the code to flash. Instead, as long as the correct device target configuration is loaded, if CCSv5.1 detects that there is code in flash memory via the command linker file in your project, it will automatically erase the flash and program the relevant code to flash when you load the .out file.

The flash programmer plug-in settings will automatically be configured for your device. To view or change the settings in CCS v5.1:

1. First ensure that your target configuration is set up properly for your device.
2. Launch the debugger.
3. Make sure you are in the CCS Debug perspective.
   • If needed refer to Perspectives
4. Select "Tools->On-chip Flash"
5. Configure the On-Chip Flash Programmer as required
   • You can also erase the flash from the On-Chip Flash Programmer view.
   • For help with the flash plug-in, click on the On-Chop Flash Programmer View and press the F1 key
6. Select "Remember My Settings" if you would like this configuration to remain for future debug sessions.

Note: If your program only uses a few sectors, you can save time by erasing only the sectors you are using. In the Flash plug-in configuration, uncheck the sectors not being used. Now they will not be erased as part of the load process.

On-Chip Flash Programmer Configuration

Project Migration

Migrating C2000 Projects from CCSv4.x to CCSv5.1

CCSv4 and CCSv5 projects are similar. However, the internal storage format of the managed build system changed between CCSv4 and CCSv5 so an internal migration will happen automatically. To import a CCSv4 project, from the Project menu select "Import Existing CCS/CCE Eclipse Project". During import, CCS will ask if you want to convert to the newer format. If you select "No" the project will not be converted and imported into CCSv5.

Note: Projects converted to CCSv5 cannot be directly loaded back into CCSv4, but the conversion process saves a copy of the original .cdtbuild, .project and macros.ini (if one exists) files and names them with a _initial extension. If the project needs to be imported back into CCSv4, these files should first be restored to their original names.

Migrating C2000 Projects from CCSv3.3 to CCSv5.1

Code Composer Studio v5.1 allows users to migrate projects from CCSv3.3. The user has the flexibility of migrating a single project at a time or multiple projects at once. This way, if there are many projects in a single directory which need conversion from CCSv3.x to CCSv5.1, in one run, all the projects can be easily migrated.

CCSv3.3 Projects (.pjt) Compatibility

CCSv5 uses the Eclipse concept of projects, which is different than the projects in CCSv3.3. CCSv5 includes a project import wizard for importing legacy 3.3 projects. To import a CCS 3.3 project, from the Project menu select "Import Legacy CCSv3.3 Project". This will launch a wizard that will guide you through the conversion process. If you don't want to convert your projects at this time one thing you may want to try is to instead create a standard make project that calls timake to build your existing pjt file. A standard make project is really just a wrapper project where you provide the build utility that you want to use and the parameters that should be passed to it for building and cleaning.

If you are importing a project that uses DSP/BIOS the import wizard will ask you which version of DSP/BIOS you want the imported project to use. It is recommended that you select DSP/BIOS 5.41.xx. This version of DSP/BIOS is compatible with previous 5.x versions.

Migrating a Single Project from CCSv3.3 to CCSv5.1

To start the migration process:

1. Make sure you are in the CCS Edit perspective
   • If needed refer to Perspectives
2. Select "Project-> Import Legacy CCSv3.3 Project". The legacy import wizard will open.
3. Choose "Select a project file" radio button
4. Browse to the project (.pjt) you would like to import and select "Open"
   • In the below figure, the "2808_IQsampleC.pjt" file is selected.
   • Note: This is just an example, a CCSv4 version of the project already exists in controlSUITE.
     
     
     

     Importing a Legacy Project
     
     
     
5. Press the "Next" button.
6. Select the Code Generation Tools version desired for building the selected project.
   
   
   

   Codegen Tool Version Selection
   
   
   
7. Press the "Next" button.
8. Specify whether DSP/BIOS support should be enabled or automatically determined.
   • If you do not know, then select "Automatically Determine DSP/BIOS support enablement".
9. Press the "Next" button.
10. De-select "Use common root for all migrated projects" to allow CCS to automatically determine the unique common root for all files referenced by the project.
11. Press the "Finish" button.

Congratulations! You have migrated a CCSv3.x project to CCSv5.1. Code Composer will have created a new folder with the CCSv5.1 files. This includes:

• .ccsproject
• .cproject
• .project

When the project is imported into CCSv5.1, resources in other directories will be linked to the project using a linked resource macro. In this example, the IQmath project contains source that is in another directory so it can be shared with multiple projects. After import, the project properties will have a PROJECT_LOC and SRC_ROOT macro as shown below:

Linked Resources Created During Import

If we take a look in the .project file, we will find the SRC_ROOT macro is used to create a relative path to the source files. This allows the source files to remain in their original location.

Path in the .project File to a Linked Resource

Migrating Multiple Projects at Once from CCSv3.3 to CCSv5.1

To start the migration process:

1. Make sure you are in the CCS Edit perspective
   • If needed, refer to Perspectives
2. Select "Project-> Import Legacy CCSv3.3 Project". The legacy import wizard will open.
3. Select the "Search-Directory" radio button
4. Browse to the directory holding all or some of the CCSv3.3 project files you wish to migrate.
   • In the below screenshot, the directory selected is: "C:\ti\controlSUITE\libs\math\IQmath\v160\examples\C\projects".
   • Note, this is just an example. A CCSv4 version of these projects already exists in [|controlSUITE].
   • The migration wizard will then search for all legacy projects under the selected directory, and these projects will appear in the “Discovered Legacy Projects:” box.
   • Check those projects you wish to migrate.
     
     
     

     Importing Multiple Legacy Projects
     
     
     
5. Press the “Next” button.
6. Select the Code Generation Tools version desired for building the selected project.
   
   
   

   Codegen Tool Version Selection
   
   
   
7. Press the "Next" button.
8. Specify whether DSP/BIOS support should be enabled or automatically determined.
   • If you do not know, then select "Automatically Determine DSP/BIOS support enablement".
9. Press the "Next" button.
10. In the Set Advanced Options window, de-select the "Use a common root for all migrated projects" checkbox. This checkbox is used when multiple projects share a common root directory for files included in those projects.
11. Press the "Finish" button.

The below figure shows the directory file structure for the projects being migrated. All projects to be migrated for this example are located in individual folders in one directory.

Imported Directory Structure

All of these projects include common files under a separate /source directory just as they did before the import.

Target Configurations: Device Target and Emulation Setup

With Code Composer Studio v3.3, in order to configure the device emulation settings for a target, the user must open the Setup CCStudio v3.3 utility, which is independent of the Code Composer Studio IDE to select the correct emulator and device GEL file for CCStudio. This then requires the user to close the CCStudio IDE and run the setup utility every time the target or emulator changes.

Code Composer Studio v5.1 includes emulator target configuration within the IDE itself. The user can specify different target configurations for different emulators and device settings either for general use, or for specific projects.

Please refer to Set up the Target Configuration Options for more information.

C2000 GEL File Migration

CCS v4 to CCS v5.1

GEL files used under CCS v4 are compatible with CCS v5.1.

CCS v3.3 to CCS v5.1

The device gel files from CCSv3.3 still work with CCSv5.1. Calls to manipulate projects (i.e. Build Project) and “WatchAdd()” functions to add variables to the watch window are no longer supported. GEL hotmenu items now appear in the “Scripts” pull-down menu.

More information on GEL files, including how to load GELs and which GEL functions are still supported can be found at the GEL Wiki page here: GEL

Register WatchAdd() in Device GEL Replaced by View->Registers

The C2000 CCS v3.3 device GEL files include “WatchAdd()” functions to all the peripheral registers, allowing the user to quickly add any peripheral’s registers to the watch window in CCSv3.x when not using the TI-provided C/C++ header files. Because the WatchAdd() function no longer works in CCSV5.1, the peripheral registers are now available via the Registers window, which can be accessed from "View->Registers". If using the TI-provided C/C++ header files (downloadable from device product folders on the TI website) while debugging, register structures defined in the header files can also be added to the Watch Window same as before. Expanding these register structures allows access to individual bit fields as well (i.e., adding "AdcRegs" to the Watch Window, will display all the ADC registers and their bit field expansions).

Known Issues

controlSUITE Projects Missing Device Target

Certain controlSUITE projects break after setting a device target in the project properties.

A way to determine if the project is missing a device target is to check the project properties, under "General", and see if the device variant is listed as "Unknown TMS320C28XX Device".

1. Signs of the problem first show up in Step 3 while using the resource explorer. Clicking on "Debugger Configuration" causes the following error.
   
   
   
   
   
2. To fix the problem, open the project properties and select "General" on the left menu.
   
   
   
   
3. Confirm that the device variant is listed as "Unknown TMS320C28XX Device", select the proper device variant. In this example, an F28035 is used. Also select the appropriate connection, in this case, the "Texas Instruments XDS100v1 USB Emulator".
   
   
   
   
4. By changing the device variant, CCSv5 automatically selects the appropriate linker command file to go along with it. This causes a conflict with the command file already included in the example project.
   
   
   
   
5. In order to avoid this conflict, select "<none>" for the linker command file.
   
   
   
   
6. Make sure the compiler version selected is the latest one (or one you have installed.)
   
   
   
   
7. Click on "Apply"

The project should now successfully debug.

Other Resources

To discuss technical questions, the E2E Community is a great resource. Visit e2e.ti.com.

Forums on the E2E site include:

• C2000 Forums
• Development Tools (CCS, Compiler, DSP/BIOS) Forums

and many more...

---

CN C2000 Getting Started with Code Composer Studio v4