Files in CCS Projects
A CCS project for embedded programs takes in source files or resources and generates an output executable file. A typical project consists of source files (C/C++/assembly), linker command file and a runtime support library, at a minimum. A SYS/BIOS project will additionally contain a BIOS configuration file. After the build process, an output executable file is created. In most cases a linker map file is also generated by default. Depending on the project settings and options, other output files may be optionally generated. This page describes some of these files and their significance.
For more information on the build flow itself, please refer to this page.
Default files in new CCS Projects
When a new CCS project is created using the project wizard (File->New->CCS Project) some default files are typically added to the project. These files vary based on the type of project (BIOS or non-BIOS), the template chosen, and whether or not a Connection is specified. This is done merely to simplify the process for the user by adding some of the basic files required for building a program and loading it to the TI device.
One file that remains common no matter the type of project is the target configuration file(.ccxml). In CCS 5.3 and later, if a Connection is selected when creating the CCS project, a target configuration file (.ccxml) is added inside a folder named “targetConfigs”. The target configuration file defines the emulator connection and type of device it is connecting to. The creation of this file enables you to quickly start your debug session by the simple click of a button once you have built your project. This file is not required for the build process but comes into play when the program is ready to be loaded on to the target.
Linker command files
When a new non-RTSC project is created usually a linker command file (.cmd) and source file(s) (depending on the template chosen) is added to the project. You may choose to keep the source file or delete it and add your own source files.
The linker command file is a default file chosen based on the device selected for the project. The setting that allows this default linker command file to be added is under Advanced Settings in the New Project wizard. If the Linker command file field is set to <automatic> then the default file will be chosen. If you do not want a default linker command file chosen for you and would rather add a file of your own choice to the project, you can set the Linker command file field to <none>. Alternately, you can click on Browse and select a linker command file of your choice.
The linker command file is used during the linking stage of your application build where the linker combines object files and allocates sections into the target system's configured memory. The linker command file is an ASCII file that uses two linker directives, MEMORY and SECTIONS, to allocate sections into specific areas of memory. The MEMORY directive defines target memory configuration. The SECTIONS directive controls how sections are built and allocated. In addition, the linker command file can also include input filenames and linker options.
The Linker Command File Primer page covers the basics of linker command files, focusing on the MEMORY and SECTIONS directives.
Full details on linker command files can be found in the "Linker" chapter of the Assembly Language Tools Users Guides.
Linker command files play an important role in an embedded program as they specify where code and data sections get allocated into target memory. Without this file, the linker will not know the target memory configuration and how to properly allocate the sections. It will use default properties when allocating the sections of code. This may result in "data verification" errors or "Trouble Writing Memory Block" types of errors when loading code to the target. In some cases, it may still load without errors (for example, if loading to certain simulators) but it is never good practice, and more than often will cause the program to not work as expected when run on a target device. Hence it is very important to use a correct linker command file for your target.
To minimize load time and runtime errors that may arise due to missing linker command files, in CCS 5.2 and higher, the New Project wizard adds a default linker command file for most devices/boards. If a default linker command file is not added for your device, you may try one of the example files available at the linker command file repository.
The default file should work for many simple applications, however as application requirements get more stringent, the linker command file can be customized as needed. Also, if you already have a custom linker command file to use in your application, the default one added by CCS can simply be deleted.
SYS/BIOS Configuration files
When a new SYS/BIOS CCS project is created, usually a configuration file(.cfg) and source files(s)(depending on the template chosen) is added to the project. In this case, the target memory definition and section allocation is generally performed by a RTSC platform file that is selected by the user during project creation.
Note: An exception is for MCU devices (Stellaris, C2000, MSP430), where although a platform file is selected, the memory definition and section allocation come exclusively from a linker command file(.cmd) instead of the platform file.
The configuration file (.cfg) sets up BIOS objects and features required for the application.
When a SYS/BIOS project is built, the XDCtools take in the platform and configuration files and auto-generates these files (see this figure for build flow):
- compiler.opt: that contains a set of options (typically include options and preprocessor defines) to be passed to the compiler when compiling user source files
- linker.cmd: linker command file to be passed to the linker when linking the application
These files can be found in the \configPkg directory within the active build configuration directory, for example, <project_root>\Debug\configPkg directory.
In spite of the fact that a linker command file is auto-generated by SYS/BIOS, it is still possible for a user to additionally supply their own custom linker command file, if they have additional custom sections to allocate or if they wish to allocate one of the standard sections to a different memory region than the default. For more details and examples please refer to the following page: Memory Mangement
For more details on the build flow of a typical SYS/BIOS application, please refer to the following page: How is SYS/BIOS related to XDCtools and RTSC
If you wish to change the default target memory definition (say when moving from a TI evaluation board to a custom board) you have to create a new RTSC platform since it is the platform that defines the target memory and section allocation. See the page Demo of the RTSC Platform Wizard in CCSv4 for steps to create a custom RTSC platform using the RTSC platform wizard in CCS.
Linker map file
The linker map file (.map) is an output from the linker that provides a summary of the memory configuration, section allocation, addresses of external symbols after they have been relocated, and more. This is the file where you can check the size of code and data sections in your program and where the sections and symbols are allocated in memory. To understand the different sections generated by the compiler (.text, .bss, .const etc) and differentiate between which ones are code and which ones are data, please see the Compiler Users Guide for the target processor you are working with.
A common misconception is that the size of the executable (.out) generated by a CCS build is an indication of the size of the program being loaded to the target. This is not true as the executable contains symbolic debug information that is not actually loaded to the target. To determine the actual size of code and data in the program, it is best to look at the link map file.
CCSv5 and CCSv6 projects generate a link map file by default in the active build configuration directory (\Debug by default).
To change the name or location of the link map file, go to Project Properties->Build->Linker->Basic Options, and change the --map_file option.
For more details on the linker map file, please see the "Linker" chapter in the Assembly Language Tools Users Guides.
NEW IN CCSv6: Starting with CCSv6, there is a view called Memory Allocation view which you can also use to see a visual representation of how much memory is consumed by your application. Please see the quick video below.
The executable file (.out) that is output from the build process is the file that can be loaded and executed on a target device. It can be directly loaded and debugged using CCS or can be converted to a different format, such as a hex format and programmed to the target using a hex programmer.
CCSv5 projects generate the executable file by default in the active build configuration directory (\Debug by default).
To change the name or location of the executable file, go to Project Properties->Build->Linker->Basic Options, and change the --output_file option.
The format of the executable is either COFF or ELF. A brief history of the two formats is in this page:
As of CCS 5.3, new projects default to ELF format for C66x, MSP430 and ARM (Cortex and ARM9)devices. C2000 and C5500 default to COFF. There is currently no ELF support for C2000 and C5500.
To check whether your project is set to create a ELF or COFF executable, right-click on the project and go to Properties->General->Advanced Settings. The Output format field will show the format. For devices that support both ELF and COFF it is possible to change the "Output format" setting if you wish. Keep in mind though that all object files and libraries being linked together should be of the same format. So if you are working with ELF you need to ensure that any libraries that you are linking into the project are also in ELF format. If not there will be an error at link time and an executable will not be created.
You may hear the terms ELF and EABI used interchangeably. While ELF is the file format, EABI (which stands for Embedded Application Binary Interface) is the set of rules followed by the compiler to create a cohesive executable. These references elaborate more on EABI and migration details for moving from COFF to EABI:
Runtime support library
The runtime support is a ANSI C/C++ standard library that takes care of system startup, provides support functions for things like string handling, input/output processing, and memory allocation among other things. Since these things are handled by the runtime support library, CCS projects should link in this library.
The compiler toolset comes with a set of prebuilt runtime support libraries. Since the library can be built with an explicit set of options (to denote device, endianness, abi mode etc) that can lead to a large number of combinations, hence we only include the more commonly-used libraries in the compiler release. You can take a look in the compiler release's \lib directory to see which libraries are pre-built for that particular release.
During CCS project build, if the linker requires a library that is not provided by default, it will automatically build the library as part of the project build, and place it in the \lib directory within the compiler tools installation. The library will then become available for subsequent compilations without requiring another rebuild.
Note that this library build step will cause a one-time delay when it is built for the first time. Build times of 1-5 minutes have been observed. This will depend on the power of the host (number of CPUs, etc).
The runtime library can also be built manually outside of CCS using the executable mklib, which is included with the compiler tools (starting with CCS 5.1). For more details on mklib, see the Mklib wiki page.
When you create a new project in CCSv5, the appropriate runtime library for your device/settings will be automatically chosen. You can check this by right-clicking on the project and going to Properties->CCS General->Advanced Settings and verify that the Runtime support library field is set to <automatic>. It is best to leave this setting to <automatic> and let the linker choose the library that best matches your project options. If you still want to set it to use a specific runtime library, you may do so by selecting the appropriate one from the drop-down list in the Runtime support library field.