viktorvaczi90 / tm4c-launchpad-cmsis

An Eclipse project using ARM CMSIS to create and debug code for the TI TM4C123XL Cortex-M4 LaunchPad.

Introduction

This is an Eclipse project for the TM4C123XL LaunchPad from Texas Instruments (TI). It uses the ARM Cortex-M Software Interface Standard (CMSIS) project style and structure and supports Open On-Chip Debug (OpenOCD) for debugging. The C compiler, assembler, and loader are from the GNU Compiler Collection (gcc). All of the software used is open-source and free.

Note that this project definition is not intended to be compatible with the TivaWare package supplied by TI, and that the TM4C-specific files supplied for CMSIS compatibility are not provided, maintained, or endorsed by Texas Instruments or ARM.

Files that support CMSIS projects:

• Processor peripheral memory map definition header file (TM4C123GH6PM.h)
• System clock configuration and initialization (system_TM4C.c)
• C run-time startup (startup_TM4C.s)

Files that support debugging with OpenOCD:

• Eclipse launcher for the OpenOCD gdb server
• Eclipse launcher for gdb

CMSIS

The part of the CMSIS that is most specific to the TM4C123 processor is the "core peripheral access layer header file", which defines the memory map for all of the on-chip peripheral devices as well as their interrupt vectors. The header file supplied with this project is specifically written for the TM4C123GH6PM processor and is therefore named TM4C123GH6PM.h This header file was adapted from similar header files generated for similar processors. To the best of my knowledge, this header file is consistent with the peripheral register definitions provided in the TI data sheet for the TM4C123GH6PM processor. However, I have not made an explicit attempt to verify every definition.

The system_TM4C.c and system_TM4C.h files provides one global variable and two functions that are required by the ARM CMSIS. The variable, SystemCoreClock, is a global variable whose value is equal to the processor core clock in hertz. This variable can be updated by calling the SystemCoreClockUpdate function. The most important function, SystemInit, configures and initializes the processor. This consists mainly in configuring the system clock source and the phase-locked loop. There are many options for the clocks in a TM4C processor, and the user should review the compile-time constants defined in system_TM4C.c before using this file with any system other than the TM4C123XL LaunchPad.

The startup_TM4C.s file defines all of the interrupt service routines and provides the C runtime initialization. The steps in initializing the processor are:

• Enable the Usage, Bus, and Memory Management Fault exceptions to make debugging a little easier
• Clear the bss segment. This is the part of RAM that holds static variables that lack an explicit, non-zero initial value.
• Copy the data segment from flash to RAM. This is the part of RAM that holds static variables with explicit, non-zero initial values.
• Call the CMSIS SystemInit function to setup the clocks.
• Call the user's main function.

Note that the main function should never end or execute a return statement. If it does, the processor will sit in an infinite loop that is the last instruction in the C runtime initialization. Here's an example of a main program using the CMSIS style of peripheral access:

#include "TM4C123GH6PM.h"

#define BIT4 (1 << 4)
#define PORTE (1 << 4)

int main()
{
  uint32_t Increment = 0;

  // Enable clock to GPIO E, wait for port to be ready
  SYSCTL->RCGCGPIO |= PORTE;
  while ((SYSCTL->PRGPIO & PORTE) == 0) {
  }

  // Configure PE4 as an output pin
  GPIOE->DIR |= BIT4;
  // Configure PE4 for 8mA output
  GPIOE->DR8R |= BIT4;
  // Enable digital function for PE4
  GPIOE->DEN |= BIT4;
  
  // Loop forever, blinking the LED
  for (;;) {
    Increment++;
    if (Increment >= (SystemCoreClock >> 4)) {
      Increment = 0;
      GPIOE->DATA ^= BIT4;
    }
  }
  return 0;
}

OpenOCD

There are two Eclipse launchers that are used to debug code running on a LaunchPad. The first, OOCDWinSrvrTM4C123GH6PM.launch, simply starts the OpenOCD executable as a gdb server. A command line switch is used to specify that the target board is a TM4C123GXL LaunchPad. If the project is imported correctly you should see an entry for this launcher under the "external tools" menu item in the debug perspective.

The second launcher, OOCDgdbWin.launch, starts gdb itself. (If the project is imported correctly you should see an entry for this launcher under the "debug" menu item in the debug perspective.) A sequence of commands is then sent from gdb to the gdb server in order to wake up the target TM4C processor, program its flash, and start execution of the user code. This launcher expects the compiled target code to be in a file named main.elf within a project named MyProject. Once you have imported the project you can use the Eclipse menus to rename it and this change will automatically be made to the launcher as well. However, if your executable code is in a file other than main.elf then you will need to manually edit the launcher.

Dependencies

This project has been configured for use under Windows, where all of the important software has been installed in a directory named C:\armtools

However, the project may be used under Linux (and probably OSX) by changing the search path definition in the project preferences and by changing the hard-coded paths in the two debug launchers.

GNU tools and utilities

The Eclipse project preferences add these two values to the search path for executable software:

• C:\armtools\gnutools\bin
• C:\armtools\yagarto-tools\bin

The launcher for gdb (OOCDgdbWin.launch) contains a hard-coded path for the GNU debugger. It expects to find the gdb executable file at

• C:\armtools\gnutools\bin\arm-none-eabi-gdb.exe

gcc

The gnutools directory must contain the executable files and libraries needed by gcc and related tools. Pre-built versions of gcc for ARM Cortex-M processors are maintained and provided by ARM employees here. Note that when you download and install the software it will be in a directory that has a version-dependent name, such as gcc-arm-none-eabi-4_7-2013q1. This directory has simply been renamed gnutools so that upgrading the gcc version does not break the pointers and hard-coded paths in the Eclipse settings and launchers.

Utilities

The yagarto-tools directory contains a few utility programs including make and rm. The Eclipse project includes a manually-written make file, so there must be an executable version of make available somewhere in the executable search path. The make file executes rm when you clean the project so this program must also be available.

This version of the Eclipse project uses the versions of these utilities that were provided by Michael Fischer as part of yagarto-tools, but this package is no longer being developed. It appears that they have been archived as http://www.emb4fun.de/archive/gabmt/download/emb4fun-tools-20140920-setup.exe but I have not verified this. It is not necessary to use special versions of these utilities when developing ARM software, so if your system already has them then you simply need to make sure that they can be found along the search path used by Eclipse.

The make file provided with the project expects that the top-level main function will be provided in a C source file named main.c. All C and assembly source files should be kept in the project's src directory and all C header files should be in the inc directory. The only source file suffixes recognized by the make file are .c, .s, and .h.

OpenOCD

The launcher for the OpenOCD gdb server (OOCDWinSrvrTM4C123GH6PM.launch) defines the path to the OpenOCD executable to be

• C:\armtools\openocd\bin-x64\openocd-x64-0.8.0.exe

If you have OpenOCD install along a different path then you must manually modify the launcher.

The documentation and source code for OpenOCD is available at sourceforge. Linux and OSX users can probably obtain a recent version from the software repositories for their distribution, and Freddie Chopin makes pre-compiled Windows versions of OpenOCD available at his web page. Make sure you have a version that supports the TI ICDI interface (version 0.7.0 or higher), and that the file ek-tm4c123gxl.cfg exists in the board scripts directory.

USB drivers

Under Windows it will probably be necessary to manually install the drivers for the USB debugging interface to the LaunchPad. There are two drivers that must be installed to accommodate debugging via ICDI and a third that enables the virtual COM port from the LaunchPad. The required drivers and installation information can be obtained from TI on this page.