New to the C2000

Efrain,

Welcome to the world of embedded programming! Since this is a class project I'm guessing you're short on time, but if you get a chance, brush up pointers in C. A deeper knowledge of pointers is *very* helpful for MCU programming.

Not sure how much you know already, so let's start with the basics. In embedded programming we're much more concerned about CPU-specific details than in normal C application programming. Often we care about the actual size of data types, since that's what we get from hardware. (Registers are 16 or 32 bits, not "short int" or "unsigned long int" bits.) Usually we'll use typedefs to define specific data sizes. Section 6.4 of the compiler manual (SPRU514F) lists the sizes of the C data types:

char = 16 bits <-- Very unusual! Most CPUs have 8-bit chars, but the C28x CPU is really a 16-bit DSP.
int = 16 bits
long = 32 bits
long long = 64 bits
pointer = 22 bits <-- In the large memory model. Also unusual. 32 bits is more common.

So we could define specific types like this:

typedef int signed_16bit_int;
typedef unsigned int unsigned_16bit_int;
typedef long int signed_32bit_int;
typedef unsigned long int unsigned_32bit_int;

and then declare variables like this:

signed_16bit_int s1, s2, s3;
unsigned_32bit_int u1, u2;

This is so common that C now does it for us. If you #include <stdint.h>, you get types like int16_t (signed 16-bit integer) and uint32_t (unsigned 32-bit integer). Uint32s are very common since many registers are 32 bits.

(So where's #include <stdint.h> in the example code? It gets #included in F2802x_Device.h, which is #included in DSP28x_Project.h, which is #included in the main C file for the example. Both of those headers are in the controlSUITE\development_kits\C2000_Launchpad directory. The header files system is complicated, but #including DSP28x_Project.h should get you almost everything you need.)

Okay, on to registers. I'm not familiar with the launchpad library specifically, but I can tell you a few things. The goal here is to read and write values (integers) to and from hardware registers. The registers are memory-mapped. (Let me know if you need an explanation for that.) So to access them, we need to make the CPU access specific memory addresses. There are two standard ways to do this:

1. Make a pointer to the memory address.
2. Tell the linker to put a variable at that memory address.

Let's talk about the first method. We could use hardcoded numerical addresses everywhere:

*(uint16_t *)0x701C |= CLK_PCLKCR0_ADCENCLK_BITS; //Enable ADC clock via the PCLKCR0 register

but that's error prone and hard to read. We could #define names for every register:

#define CLK_PCLKCR0 (*(uint16_t *)0x701C)
CLK_PCLKCR0 |= CLK_PCLKCR0_ADCENCLK_BITS;     //Atmel does this in their 8-bit MCU libraries

but that gets clunky, especially if you have several copies of a module. Three ADCs would mean three sets of constants used in three sets of functions, for instance. So in big MCUs, it's not ideal. A better option is to define the structure of the register group itself, without the absolute address. That's what the Launchpad software is doing:

typedef struct _CLK_Obj_
{
    volatile uint16_t   XCLK;         //!< XCLKOUT/XCLKIN Control
    volatile uint16_t   rsvd_1;       //!< Reserved
    volatile uint16_t   CLKCTL;       //!< Clock Control Register
    volatile uint16_t   rsvd_2[8];    //!< Reserved
    volatile uint16_t   LOSPCP;       //!< Low-Speed Peripheral Clock Pre-Scaler Register
    volatile uint16_t   PCLKCR0;      //!< Peripheral Clock Control Register 0
    volatile uint16_t   PCLKCR1;      //!< Peripheral Clock Control Register 1
    volatile uint16_t   rsvd_3[2];    //!< Reserved
    volatile uint16_t   PCLKCR3;      //!< Peripheral Clock Control Register 3
} CLK_Obj;

Now we've told the compiler where the clock registers are relative to each other. To get the right addresses, we make a pointer to the register frame:

CLK_Obj *clk = (CLK_Obj *)CLK_BASE_ADDR;     //Pointer to address 0x7010

This lets us access the registers as through they were part of a normal C data structure in memory:

clk->PCLKCR0 |= CLK_PCLKCR0_ADCENCLK_BITS;     //OR the register at address 0x7010 with 1<<3 (0x0008)

which is precisely what CLK_enableAdcClock() does. They just use a typedef for the CLK_Obj pointer in the function calls. (Typedefs are a running theme here, as you can tell.)

The Launchpad code refers to these register structure pointers as "handles". A handle is a reference to some software or hardware resource. For example, standard C uses file handles:

FILE *fileHandle;
fileHandle = fopen("somefile.txt", "w");
fputs("Text to be written", fileHandle);
fclose(fileHandle);

The purpose of a handle is to let you access a specific resource (e.g. one file out of many) without needing a low-level description of where/what it is. This lets you mostly ignore hardware details when you use higher-level functions. In the Launchpad software, a handle is just a pointer to the register frame. The XXX_init() functions assign the address (first parameter) to the pointer (return value) with some error checking based on the structure size, probably to make sure you copied and pasted correctly. :-)

I know this all seems like black magic when you first work on it (it sure did to me!), but I promise it all makes sense and there's not all that much to it once you get going. If there's anything else you'd like me to explain, please feel free to ask.

Good luck!