Table of Contents
Setting up Eclipse with hardware debugging
For this guide we will assume that you are using the Linux JTAG toolchain for an LM3S based board (Such as Cygni, Eridani, or Procyon.) If you are not using that toolchain you may still apply this contents of this document with some suitable changes.
Eclipse is complex software and this guide is just a starting point, you should customize the environment to suit your needs and wishes.
The purpose of the using Eclipse is to mainly to provide a convenient means of using GDB to debug the target board over JTAG that is well integrated.
This will allow us to inspect register and memory contents of the MCU as we run code and set breakpoints with ease.
Some sections of this document may not be needed by all. We have tried to be complete, some settings may not be needed but the following configuration should work with our provided examples.
If you search around the net, most guides suggest using the Zylin plugin but that information seems to be dated as hardware GDB support is now part of the CDT project.
Below is what the Eclipse Environment looks like in the Debug view following this guide:
Installing Eclipse, CDT, and Embedded Systems Register View
We assume you are using an Ubuntu flavor for this guide.
We will use Eclipse Indigo. This is the default package under Ubuntu 11.10 so we will install with:
sudo apt-get install eclipse
You can also get Eclipse directly, Indigo is release 3.7. (If you are using another Linux flavor or OS for instance).
After Eclipse installs launch it, you will be prompted to make a workspace. If you have been using the regular toolchain paths, the recommended location for this is somewhere inside the Development directory, such as Development/Eclipse/BoardName.
Once Eclipse is open we will need to install some software.
This is located under Help → Install New Software
Click Add to bring up the dialog to add a software source, we need two sources
Embedded Systems Register View http://embsysregview.sourceforge.net/update
The former is the popular C/C++ IDE for Eclipse and the later is a plugin that allows the inspection of registers of some MCUs in a easier to use fashion than the standard memory viewer in Eclipse (IE you don't need to look at the memory map).
From CDT install:
- C/C++ Development Tools
- C/C++ Development Tools SDK
- C/C++ GCC Cross Compiler Support
- C/C++ GDB Hardware Debugging
- C/C++ Memory View Enhancements
From Embedded System Register View install the only package 0.19 at the time of writing.
Restart Eclipse as prompted during the install of these components.
Setup the Eclipse Project
For this walk through we will just make a copy of the “Basic” example that is provided with every board release. Call the copy EclipseBasic and leave it in whatever board directory basic was in so that all the makefile paths remain happy. (IE: “Development/Cygni/EclipseBasic”).
Select File → New → Project
Expand C/C++, and select Makefile Project with External Code, click next
Project Name: EclipseBasic
Browse to the folder you just copied that contains the files
Select Cross GCC in Toolchain for Indexer Settings
Now the Project is imported and setup.
Make sure you are in the C/C++ perspective if the project creation didn't switch you automatically to it.
Next we want to tell Eclipse about some targets in the makefile, this is under:
Project → Make Target - > Create
You can leave everything default but create targets for the 3 important targets in the makefile:
Building and flashing the project
Open the basic.c file
There are a bunch of errors. If you clean the project and tell Eclipse to build it Eclipse will read the include statements in the makefile and many of these errors will disappear.
However, if Eclipse still shows many unknown symbols in the file do the following:
Change some character in the file and save basic.c (it will look dirty and Eclipse will reread the file when you build the project again).
Clean the project and then build the project, all the errors should be gone.
Now use a terminal and run OpenOCD in the directory the project files are in. Make sure the JTAG attaches as normal.
Now we will build and flash the project like we would on the command line using Eclipse as the frontend.
Project → Make Target → Build… (Shift-F9) (Remembering it is Shift-F9 is helpful).
Select the flash target and click build
You should see in OpenOCD the normal steps and the program should run.
We have just gotten Eclipse to where we were with a text editor and a terminal.
Setting up hardware debugging
The point of using Eclipse is largely to have hardware GDB support so that we can easily debug the target board using a JTAG, so this is the critical section.
Setting up a debug configuration in Eclipse:
Run → Debug Configurations
In the left pane there are many options. One of them is: GDB Hardware Debugging, select it and click the new button.
Change the configuration name to OpenOCD GDB
You may wish to turn on Enable auto build
Change Command to arm-none-eabi-gdb, you may also browse to the location
Host name or IP address should read localhost
Change Port number to 3333
Click the Select other… link following “GDB (DSF) Hardware Debugging Launcher” at the bottom of the window
Click change workspace settings link
Under GDB Hardware Debugging click [Debug]
Check Standard GDB Hardware Debugging Launcher from the list of choices
If it already said Standard GDB Hardware Debugging Launcher you don't need to do this. You also don't have to change the setting for the whole workspace if you don't want to.
The Embedded System Register View software needs the standard interface to communicate at this time, rather than DSF.
Add “monitor soft_reset_halt” to the box below the halt check box
You should be able to leave the rest of the settings unchanged, they use the project binary to load the symbols and image.
Under Display in favorites menu check Debug
Click Apply then close
Using JTAG GDB in Eclipse
We could now use the debug configuration we just made, however OpenOCD would complain about attaching GDB to the board while the board is not halted if we did (probably).
The simplest fix to this is to add the following two lines to the end of the OpenOCD file in the project source file directory.
#Switch to passing commands and halt the MCU init reset halt
To the end of the OpenOCD file in the correct directory. The init command basically lets you use the telnet interface from inside the OpenOCD file so all this does is issues a reset halt right after the JTAG attaches the first time. This should prevent OpenOCD from complaining when we attach GDB.
Close OpenOCD and run it again from the correct directory once you have made the changes.
We could setup OpenOCD as an external tool in Eclipse but we prefer to use it from a terminal at this time.
Now we are ready to use the hardware debugging!
There is a nice “bug” button, click the arrow and select the debug configuration you made from the drop down.
It will ask you to swtich to the debug perspective. Do so.
Next it will probably complain you don't have source for “g_pfnVectors()”, this is the startup code for whatever reason Eclipse doesn't see the symbol in the code files, you can ignore the error.
Put a breakpoint somewhere in the code and click the resume button or hit F8
The JTAG should halt the execution when it gets there!
You can now look at registers, variables and memory using the tools built into Eclipse!
Next we will add the useful Embedded Systems Register View tool
Adding Embedded Systems Register View
Click on Window → Preferences
Expand Debug, and select EmbSys Register View
Set Architecture → cortex-m3
Set Vendor → LuminaryMicro
Set Chip → Whatever is used on your board.
Sadly at least in 0.19 this last menu is a jumble, but almost all LM3S chips are there just look carefully down the list till you see the right one!
Click Window → Show View → Other… (Shift-Alt-Q Q)
Click on EmbSys Registers
You can drag the view to wherever you want in the Debug perspective.
You can expand the folders and select the register you want to inspect. Double click on the register name and it should turn green and report its current value.
This saves you the trouble of looking up the register memory locations for chips that EmbSys Register View has files for.