Skip to content

Toolkit overview

Jump to bottom Edit New page
Georgia Tech Solar Racing edited this page May 18, 2015 · 1 revision

Welcome to the TI-C2000-dev-suite wiki! Good projects are easy to understand. The C2000 is, however, complicated to get started with. This toolkit aims to make working with it much easier and the resulting code much more readable.

Table of Contents

Preamble: The Anatomy of a Microcontroller

A typical microcontroller program is meant to sense the state of the outside world at some regular interval, perform some computation based on that information, and use the results to effect some desirable change to the outside world (which it then senses again and affects again ad infinitum).

To accomplish this requires the interaction and cooperation of numerous systems. This document is intended to communicate the complexity of this process and get you started at understanding the system elements and how they fit together.

Systems on a the C2000 include

  • Clocks
  • General Purpose Input/Output (GPIO)
  • Interrupts (subroutines triggered by hardware events, like clock-edges or ADC conversions)
  • Analog-to-Digital Converters (ADC)
  • Serial Communications Interface (SCI)
  • I2C
Introducing these microcontrollers is difficult because even creating a project that blinks an LED, the HelloWorld of hardware/software systems programming, requires understanding of
  1. What the watchdog is and how to either disable or periodically reset it
  2. What system clocks exist and which clock various subsystems
  3. How to set these clocks to certain frequencies
  4. How to set the system to recieve interrupts from a clock
  5. How to initialize GPIO
  6. How to write and read from GPIO registers
  7. How to acknowledge an interrupt after it has occurred (so later interrupts can be recieved)
And if you want to do anything fancier, like talk to an analog device such as a thermocouple or to a high-frequency digital device like the xtend, then you may additionally need to know
  1. How to initialize the ADC module
  2. How to enable interrupts from an ADC event
  3. How to initialize the SPI module
  4. How to use the SPI module
The approach to understanding these systems should not be to read the technical documentation right away. It is too dense and too detailed to be helpful at a high-level. Instead, I recommend starting with the Systems Tutorials below, which explain systems more abstractly before delving into the specifics of how they work. After you have a basic understanding of the microcontroller, begin looking at some of our libraries. These take care of some of the lower-level detail involved with programming C2000s and make your life easier.

The Common Architecture of C2000 Projects

A project has

  • A .h file in which all functions are declared
  • A .c file including a main() function
  • Includes
  • Extra files specifying whether it loads to RAM or Flash
Let's go down the list.

.h files hold function headers so that the compiler can know what the signatures of various methods should look like. That is, it can decide whether you are using a method correctly based upon the definition you provide. If you plan to define a function that might be reused anywhere outside a particular file, you should put its header in the project's .h file so it might be simply #included to additional .c files. Likewise, it is useful to define enums in .h files so multiple .c files can easily see and use them. Note that you may not need to define a new .h file for your project at all, in which case you should place method headers at the top of your .c code under the #includes.

project.h commonly looks something like

/** 

 * @author you 
 * comments describing project purpose, oddities,
 * typedefs, et cetera
 */

typedef enum {//example of how to define an enum 

    ONE,    TWO,    THREE,
    FOUR,   FIVE,   SIX

} THING;

void method(THING, THING);//Andrey wants Doxygen comments here void othermethod(char, Uint16);//I [Pavel] prefer them only in the .c //et cetera

The .c file is the central piece of your project. The main() function is executed when the program starts, and any additional methods are defined here.

The project.c commonly looks like

/** 

 * @author you
 * @brief short description
 * @version 1.0, 2.0, whatever
 *
 * More descriptive comments outlining the project
 */
  1. include "F2806x_Device.h"
  2. include "string.h"
  3. include "library1.h"
  4. include "library2.h"
//et cetera

//global variable declarations and function declarations if not in .h file interrupt void WhateverISR(void);

void main(void) { 

    EALLOW;//an assembly language thing required to allow access to system
    SysCtrlRegs.WDCR = 0x68;//disable watchdog            control registers

    SysCtrlRegs.WDCR = 0x28;//reenable the watchdog
    EDIS;//disallow access to system control registers

    while (1) {
        EALLOW;
        SysCtrlRegs.WDKEY = 0x55;
        SysCtrlRegs.WDKEY = 0xAA;//Service WATCHDOG TIMER
        EDIS;
    }

}

interrupt void WhateverISR() { 

    //do thing
    PieCtrlRegs.PIEACK.all = PIEACK_GROUPx;//x = the group to which the hardware 
                                           //device belongs. timer0 is in group1,

} //for example.

The .c and .h alone are contextless islands of code, largely meaningless to the compiler. Without telling CCS where to look for F2806x_Device.h or libraryx.h, the compiler will have no concept of what things like SysCtrlRegs or various init() functions are. The solution is to include and link libraries and make the resulting dependencies explicit.

Lastly, your project should be set up to run from RAM by default, but this does not always work, nor is it always your intent. If CCS complains that your "program will not fit in available memory" or if you want your project to run on the MCU without having to connect it to a computer running a CCS debug session, you will need to start messing with the .cmd files.

Resources

Systems Tutorials

F28069 Technical Documentation

Target Hardware Documentation

To Create an Executable Project

  1. 'File' -> 'New CCS Project'
  2. The Target (upper right) should be set to 'TMS320F28069' (or what is appropriate for you).
  3. 'Connection' is 'Texas Instruments XDS100v2 USB Debug Probe' (or what is appropriate for you).
  4. Make sure the 'Output type' under 'Advanced settings' is set to 'Executable'.
  5. You probably want to make a new empty project with a main.c

To Create a Library Project

  1. 'File' -> 'New CCS Project'
  2. The Target (upper right) should be set to 'TMS320F28069' (or what is appropriate for you).
  3. 'Connection' is 'Texas Instruments XDS100v2 USB Debug Probe' (or what is appropriate for you).
  4. Make sure the 'Output type' under 'Advanced settings' is set to 'Library'.

Choosing .cmd Files

.cmd files define how the hardware executes the project. For our purposes it is important only to distinguish between running a project from RAM and running from Flash memory. RAM allows one to reload and rerun programs quickly, so it is good for debugging. But if your project is too large to fit into RAM, or in the case you want to create a project that can run on the MCU independently from a PC immediately after power-up, you will need to put it in Flash, which is a bit more involved.

If you want to run from RAM:

  • You can either use the default built in F28069_RAM_lnk.cmd, or a modified version that addresses a problem with using 'puts'. For using the default file, just select it under 'Linker Command File' in the 'General' tab of the project properties. To use the modified version of this file that resolves a problem with 'puts', select <none></none> as the 'Linker command file'. Then go to Build -> C2000 Linker-> File Search Path, and click the top green + image, then 'Workspace', and add 28069RAM.cmd from 28069Common/cmd.
  • Also to Build -> C2000 Linker-> File Search Path, and click the top green + image, then 'Workspace', and add F2806x_Headers_nonBIOS.cmd from 28069Common/cmd.
I [Pavel] have tried to make the process of running from Flash as painless as possible, but it is still complicated. The problem is Flash is slow, too slow to keep up with the pace of things like SCI. So the goal becomes to store your project in Flash, but to copy it over to and run from working memory at boot. The steps are:
  • Go to Build -> C2000 Linker-> File Search Path, and click the top green + image, then 'Workspace', and add F28069_FLASH.cmd from 28069Common/cmd.
  • Also to Build -> C2000 Linker-> File Search Path, and click the top green + image, then 'Workspace', and add F2806x_Headers_nonBIOS.cmd from 28069Common/cmd.
  • Copy F2806x_CodeStartBranch.asm from 28069Common/asm in the root folder of your project.
  • Include the FastFlash project via the process under 'Add dir to #include search path' in the next section.
  • Link to the FastFlab .lib file as described under 'Include library file or command file as input' in the next section.
  • (Best practise, but not strictly necessary) Make your project explicitly dependent upon FastFlash as laid out in the next section.
  • At the top of the project C-file containing main(), #include fastflash.h
  • Near the top of your main (Right after EALLOWing and disabling the Watchdog is a good spot.), add a call to InitFlash()

Configuring Includes and Linking

  1. Right-click the project in the 'Project Explorer' pane and select 'Properties'.
  2. 'Add dir to #include search path' by
    1. navigating to 'Build' - >'C2000 Compiler' -> 'Include Options' in the left pane of the window that appears,
    2. clicking the icon with the green plus (alt text reads 'Add...') by the --include_path tag box,
    3. clicking the 'Workspace...' button,
    4. selecting the /h directory under the 28069Common library,
    5. and clicking 'OK'.
    6. Repeat this process for all other libraries to be included in your project, but include the root directory instead of a /h directory. (/h for the Common lib was just something odd I [Pavel] did. For all other libraries, the .h files are in the root.)
  3. 'Include a library file or command file as an input'. This must be done for 28069Common.lib which contains all the C code for the respective .h files. Do this by:
    1. navigating to 'Build' -> 'C2000 Linker' -> 'File Search Path',
    2. clicking the icon with the green plus next to "Include library or command file as input (--library, -l)" (alt text reads 'Add...')
    3. clicking the 'Workspace...' button,
    4. navigating to the /Debug folder inside a library to be included,
    5. selecting the <library></library>.lib file (Ex: "28069Common.lib"; see footnote),
    6. and clicking 'OK'.
    7. Repeat this process for other libraries.
  4. Make your project explicitly dependent upon whatever libraries you just included by
    1. clicking 'Build' in the left pand,
    2. selecting the 'Dependencies' tab,
    3. clicking the 'Add' button,
    4. checking boxes next to relevant libraries,
    5. and clicking 'OK'.
Footnote: If a .lib file does not exist, it can be generated by building the library.
Add a custom footer
Add a custom sidebar
Clone this wiki locally