Overview
==================================
This module will explain how to use
Code Composer Studio (CCS) integrated development environment (IDE) tools to
develop a program. It will also cover how to create a project, set build
options, and use of linker command files. For a deeper look at all of the
components involved in getting started with C2000 refer to [Getting Started
with C2000 Real-Time Control Microcontrollers (MCUs)](https://ti.com/lit/SPRUIV6)
Embedded Application Binary Interface (EABI)
============================================
EABI defines the low-level interface between programs, program components, and
the execution environment, including the operating system if one is
present. Components of the EABI include: calling conventions, data layout and
addressing conventions, and object file formats. The purpose of the
specification is to enable tool providers, software providers, and users of the
C28x to build tools and programs that can interoperate with each other. For more
details on C28x EABI, refer to the following resources:
* [ C28x Embedded Application Binary Interface ](https://ti.com/lit/SPRAC71)
* [ TMS320C28x Optimizing C/C++ Compiler User's Guide ](https://ti.com/lit/SPRU514) - Version R or later
* [ TMS320C28x x Assembly Language Tools User's Guide ](https://ti.com/lit/SPRU513) - Version R or later
Prior to release 18.12.0.LTS of TI's C28x Compiler Tools, the one and only ABI
for C28x was the original Common Object File Format (COFF-based ABI). It was strictly a bare-metal ABI; there was no execution-level component. For a look into the migration details of COFF to EABI refer to [C2000 Migration from COFF to EABI](https://software-dl.ti.com/ccs/esd/documents/C2000_c28x_migration_from_coff_to_eabi.html)
Software Structure
============================================================
Each file of code, called a module, may be written independently, including the
specification of all resources necessary for the proper operation of the module.
Modules can be written using Code Composer Studio (CCS) or any text editor
capable of providing a simple ASCII file output. The expected extension of a
source file is .ASM for assembly and .C for C programs.
Numerous modules are joined to form a complete program by using the linker. The
linker efficiently allocates the resources available on the device to each
module in the system. The linker uses a command (.cmd) file to identify the
memory resources and placement of where the various sections within each module
are to go. Outputs of the linking process includes the linked object file
(.out), which runs on the device, and can include a .map file which identifies
where each linked section is located.
Code Composer Studio
==================================
Code Composer Studio™ (CCS) is an integrated development environment (IDE) for
Texas Instruments (TI) embedded processor families. CCS comprises a suite of
tools used to develop and debug embedded applications. It includes compilers for
each of TI's device families, source code editor, project build environment,
debugger, profiler, simulators, real-time operating system and many other
features. Additionally, tools to connect file input and output, as well as built-in
graph displays for output are available. Other features can be added using the
plug-ins capability.
The intuitive IDE provides a single user interface taking you through
each step of the application development flow. Familiar tools and interfaces
allow users to get started faster than ever before and add functionality to
their application thanks to sophisticated productivity tools. CCS supports
running on both Windows and Linux PCs. Note that not all features or devices are
supported on Linux
To install Code Composer Studio (CCS) please refer to: https://www.ti.com/tool/CCSTUDIO
Refer to [this link](https://software-dl.ti.com/ccs/esd/training/workshop/ccsv7/c2000/sdto_ccsv7_c2000-fundamentals-workshop.html) for in-depth training material on how to use Code Composer Studio
Edit and Debug Perspective
-------------------------------------------------
A perspective defines the initial layout views of the workbench windows, toolbars,
and menus that are appropriate for a specific type of task, such as code
development or debugging. This minimizes clutter to the user interface.
Code Composer Studio has “Edit” and “Debug” perspectives. Each perspective
provides a set of functionality aimed at accomplishing a specific task. To
change perspectives go to `Window > Perspective > Open Perspective`
Perspective | Description
------------|----------------------------
Edit | Displays views used during code development (C/C++ project, editor, etc.)
Debug | Displays views used for debugging (menus and toolbars used for debugging, watch and memory windows, graphs, etc.)
Target Configuration
-------------------------------------------------
A Target Configuration defines how CCS connects to the device. It describes the device
using GEL files and device configuration files. The configuration files are XML
files and have a `*.ccxml` file extension.
To create a new Target Configuration go to `File > New > Target Configuration
File`
- Under `General Setup` select a connection type, device, and then save the configuration.
CCS Project
-------------------------------------------------
Code Composer works with a project paradigm. Essentially, within CCS you create a project for
each executable program you wish to create. Projects store all the information
required to build the executable. For example, it includes components such as the source
files, the header files, the target system’s memory-map, and program build
options. The following table describes the included components within a project.
**Project Files Contain:**
Content | Content Types
-----------------|----------------------------
Files | Source (C, assembly), Libraries, Linker command files,
TI-RTOS configuration file Project Settings | Build options (compiler, assembler, linker, and TI-RTOS), Build configurations
Along with the main project menu, you can also manage open projects using the
right-click popup menu. Either of these menus allows you to modify a project,
such as add files to a project, or open the properties of a project to set the
build options.
Creating a new CCS Project
-------------------------------------------------
To create a new project, you need to select the following menu items: `File > New CCS Project`
A graphical user interface (GUI) is used to assist in creating a new project.
Within this GUI select the desired target (C2000 device). Under `Tool Chain` the
Linker Command File can be specified, and under `Project Templates and examples`
an `Empty Project` can be selected.
After a project is created, the build options are configured.
CCS: Build Options – Compiler/Linker
-------------------------------------------------
Project options direct the code generation tools (i.e. compiler, assembler,
linker) to create code according to your system’s needs. When you create a new
project, CCS creates two sets of build options ("configurations"): one
called Debug, the other Release (you might think of as optimized).
To make it easier to choose build options, CCS provides a graphical user
interface (GUI) for the various compiler and linker options.
**Compiler:**
- 22 categories for code generation tools
- Controls many aspects of the build process, such as: Optimization level,
Target device, Compiler/assembly/link options
**Linker:**
- 9 categories for linking (Specify various link options)
- `${PROJECT_ROOT}` specifies the current project directory
There is a one-to-one relationship between the items in the text box on the main
page and the GUI checkboxes, sliders, and drop-down selections. If desired, users
can also edit the compiler and linker configuration in a CLI-like format using the
"Edit Flags" menu in the CCS GUI.
There are many linker options but these four handle all of the basic needs:
- `-o ` specifies the output (executable) filename.
- `-m ` creates a map file. This file reports the linker’s results.
- `-c` tells the compiler to auto initialize your global and static variables.
- `-x` tells the compiler to exhaustively read the libraries. Without this
option libraries are searched only once, and therefore backwards references
may not be resolved.
To help make sense of the many compiler options, TI provides two default sets of
configurationss in each new project you create. The Debug configuration
is used for standard development and debugging of the project. Thus, the compiler
in this build is configured to streamline the debugging process. The Release (optimized)
configuration invokes the optimizer with `–o3` and disables source-level,
symbolic debugging by omitting `–g` (which disables some optimizations used for
debugging).
CCS Debug Environment
-------------------------------------------------
The basic buttons that control the debug environment are located in the top of CCS as seen in
For the name of the icon simply hover over the icon itself within CCS. Use the table below
for a description of the operation.
[[+g Common debugging and program execution descriptions
Name | Description
-------------------------|----------------------------
New Target Configuration | Creates a new target configuration file.
Debug | Opens a dialog to modify existing debug configurations. Its drop down can be used to access other launching options.
Connect Target | Connect to hardware targets.
Terminate All | Terminates all active debug sessions.
Halt | Halts the selected target. The rest of the debug views will update automatically with most recent target data.
Run | Resumes the execution of the currently loaded program from the current PC location. Execution continues until a break-point is encountered.
Run to Line | Resumes the execution of the currently loaded program from the current PC location. Execution continues until the specific source/assembly line is reached.
Go to Main | Runs the programs until the beginning of function main in reached.
Step Into | Steps into the highlighted statement.
Step Over | Steps over the highlighted statement. Execution will continue at the next line either in the same method or (if you are at the end of a method) it will continue in the method from which the current method was called. The cursor jumps to the declaration of the method and selects this line.
Step Return | Steps out of the current method.
Reset | Resets the selected target. The drop-down menu has various advanced reset options, depending on the selected device.
Restart | Restores the PC to the entry point for the currently loaded program. If the debugger option "Run to main on target load or restart" is set the target will run to the specified symbol, otherwise the execution state of the target is not changed.
Assembly | The debugger executes the next assembly instruction, whether source is available or not.
Assembly Step Over | The debugger steps over a single assembly instruction. If the instruction is an assembly subroutine, the debugger executes the assembly subroutine and then halts after the assembly function returns. +]]
Linker Command File
=========================================================
The examples within [C2000Ware](https://www.ti.com/tool/C2000WARE) already contain a
linker command file. The following information is to learn how to modify/create your
own linker command file.
Sections
-------------------------------------------------
Looking at a C program, you'll notice it contains both code and different kinds of data
(global, local, etc.). All code consists of different parts called sections. All
default section names begin with a dot and are typically lower case. The
compiler has default section names for initialized and uninitialized sections.
For example, x and y are global variables, and they are placed in the section
.ebss. Whereas 2 and 7 are initialized values, and they are placed in the
section called .cinit. The local variables are in a section .stack, and the code
is placed in a section called .txt.
In the TI code-generation tools, these various parts of a program are called Sections.
Breaking the program code and data into various sections provides flexibility
since it allows you to place code sections in ROM and variables in RAM. The list below
defines the components within a C program:
* Global Variables
* Initial Values for global variables
* Local Variables (i.e. the stack)
* Code (the actual instructions)
The following is a list of the initialized and uninitialized sections that are created by
the compiler. Along with their description, we provide the Section Name defined by the
compiler. This is a small list of compiler default section names. The top group is
initialized sections, and they are linked to flash. The .txt section was used for
code, and .cinit is for initialized values. The bottom group is uninitialized
sections, and they are linked to RAM. The .ebss section is used for global
variables and .stack for local variables.
**Initialized Sections:**
Name | Description | Link Location
----------|-------------------------------------------------------|--------------
.text | Code | FLASH
.cinit | Initialization values for global and static variables | FLASH
.econst | Constants (e.g. cnst int k=3;) |
.switch | Tables for switch statements | FLASH
.pinit | Tables for global constructors (C++) | FLASH
**Uninitialized Sections:**
Name | Description | Link Location
----------|-------------------------------------------------------|--------------
.ebss | Global and static variables | RAM
.stack | Stack Space | low 64Kw RAM
.esysmem | Memory for malloc functions | RAM
[[b Note:
During development initialized sections could be linked to RAM since
the emulator can be used to load the RAM ]]
Sections of a C program must be located in different memories in your target
system. This is the big advantage of creating the separate sections for code,
constants, and variables. In this way, they can all be linked (located) into
their proper memory locations in your target embedded system. Generally, they’re
located as follows:
**Program Code (.text)**
Program code consists of the sequence of instructions used to manipulate data,
initialize system settings, etc. Program code must be defined upon system reset
(power turn-on). Due to this basic system constraint it is usually necessary to
place program code into non-volatile memory, such as FLASH or EPROM.
**Constants (.cinit – initialized data)**
Initialized data are those data memory locations defined at reset. It contains
constants or initial values for variables. Similar to program code, constant
data is expected to be valid upon reset of the system. It is often found in
FLASH or EPROM (non-volatile memory).
**Variables (.ebss – uninitialized data)**
Uninitialized data memory locations can be changed and manipulated by the
program code during runtime execution. Unlike program code or constants,
uninitialized data or variables must reside in volatile memory, such as RAM.
These memories can be modified and updated, supporting the way variables are
used in math formulas, high-level languages, etc. Each variable must be
declared with a directive to reserve memory to contain its value. By their
nature, no value is assigned, instead they are loaded at runtime by the program.
Next, we need to place the sections that were created by the compiler into the
appropriate memory spaces. The uninitialized sections, .ebss and .stack, need to
be placed into RAM; while the initialized sections, .cinit, and .txt, need to be
placed into flash.
Linking code is a three step process:
1. Defining the various regions of memory (on-chip RAM vs. FLASH vs. External Memory)
* Describing what sections go into which memory regions
* Running the linker with “build” or “rebuild”
Linker Command Files(.cmd)
-------------------------------------------------
The linker concatenates each section from all input files, allocating memory to each
section based on its length and location as specified by the MEMORY and SECTIONS
commands in the linker command file. The linker command file describes the
physical hardware memory and specifies where the sections are placed in the
memory. The file created during the link process is a .out file. This is the
file that will be loaded into the microcontroller. As an option, we can generate
a map file. This map file will provide a summary of the link process, such as
the absolute address and size of each section.
**Linking:**
Memory-Map Description
-------------------------------------------------
The MEMORY section describes the memory configuration of the target system to the
linker. The format is:
```c
Name: origin = 0x????, length = 0x????
```
For example, if you placed a 256 kiloword FLASH starting at memory location 0x080000, it
would read:
```c
MEMORY { FLASH: origin = 0x080000 , length = 0x040000 }
```
Each memory segment is defined using the above format. If you added RAMM0 and RAMM1, it
would look like:
```c
MEMORY { RAMM0: origin = 0x000000 , length = 0x0400 RAMM1:
origin = 0x000400 , length = 0x0400
```
Remember that the MCU has two memory maps: Program, and Data. Therefore, the
MEMORY description must describe each of these separately. The loader uses the
following syntax to delineate each of these:
Linker Page | TI Definition
-------------|--------------
Page 0 | Program
Page 1 | Data
A linker command file consists of two sections, a memory section and a sections
section. In the memory section, page 0 defines the program memory space, and
page 1 defines the data memory space. Each memory block is given a unique name,
along with its origin and length. In the sections section, the section is
directed to the appropriate memory block.
**Linker Command File:**
```c
MEMORY {
PAGE 0: /* Program Memory */
FLASH: origin = 0x080000, length = 0x40000
PAGE 1: /* Data Memory */
RAMM0: origin =0x000000, length = 0x400
RAMM1: origin = 0x000400, length = 0x400
}
SECTIONS {
.text:> FLASH PAGE = 0
.ebss:> RAMM0 PAGE = 1
.cinit:> FLASH PAGE = 0
.stack:>RAMM1 PAGE = 1
}
```
**Section Placement**
The `SECTIONS` portion will specify how you want the sections to be distributed through memory.
The linker will gather all the code sections from all the files being linked
together. Similarly, it will combine all ‘like’ sections.
Beginning with the first section listed, the linker will place it into the
specified memory segment
Summary: Linker Command File
-------------------------------------------------
The linker command file (.cmd) contains the input commands for the linker. This
information is summarized below:
1. Memory Map Description (Name, Location, Size)
* Sections Description
• Directs software sections into named memory regions
• Allows per-file discrimination
• Allows separate load/run locations
C2000Ware SDK
========================================================
[C2000Ware](https://www.ti.com/tool/C2000WARE) is a software development kit (SDK) that provides all of the basic software to get
started with programming C2000 MCU - drivers, libraries, tools, and examples. C2000Ware is the
core SDK for C2000 MCUs and is application agnostic.
To learn more about C2000Ware refer to the [C2000Ware section of the C2000 Software Guide](https://software-dl.ti.com/C2000/docs/software_guide/c2000ware/index.html) or watch a video overview: [Introduction to C2000Ware](https://training.ti.com/introduction-c2000ware?context=1137766-1139644-1137338).
Examples for devices can be found in the following default directory:
`C:\ti\c2000\C2000Ware_X_0X_00_00\driverlib\device\examples`
Evaluation Boards
========================================================
C2000 has two types of development boards, a LaunchPad and a controlCARD.
C2000 LaunchPad
--------------------------------------------------------
[LaunchPads](https://www.ti.com/microcontrollers-mcus-processors/microcontrollers/c2000-real-time-control-mcus/design-development.html#launchpads) are low-cost, powerful evaluation platforms which are used to develop real-time control systems based on C2000 microcontrollers. Various LaunchPads are available and developers can find a LaunchPad with the required performance and feature mix for any application.
The [C2000 BoosterPacks](https://dev.ti.com/bpchecker/#/) expand the power of the LaunchPads with application specific plug-in boards, allowing developers to design full solutions using a LaunchPad and BoosterPack combination.
**Features:**
* Low-cost evaluation kit
* Various BoosterPacks available
* On-board JTAG debug probe: JTAG debug probe not required
* Access to LaunchPad signals
* C2000 applications software with example code and full hardware details in available in C2000Ware
C2000 ControlCard
--------------------------------------------------------
[ControlCARDs](https://www.ti.com/microcontrollers-mcus-processors/microcontrollers/c2000-real-time-control-mcus/design-development.html#controlcards) allow for device exploration and initial prototyping. These kits are complete, open source, evaluation and development tools where the user can modify both the hardware and software to best fit their needs.
Experimenter’s Kits include a specific controlCARD and Docking Station. The docking station provides access to all of the controlCARD signals with two prototyping breadboard areas and header pins, allowing for development of custom solutions.
**Experimenter Kit Includes:**
* controlCARD
* USB docking station
* C2000 applications software with example code and full hardware details available in C2000Ware
* Code Composer Studio (download)
**Experimenter Kit Features:**
* Access to controlCARD signals through the docking station
* Breadboard areas on the docking station
* On-board USB JTAG debug probe through the controlCARD
References
==================================
[Code Composer Studio](https://www.ti.com/tool/CCSTUDIO)
----------------------------------------------------------------
[[d! Feedback
Please provide any feedback you may have about the content within C2000 Academy to:
]]