Creating an Eclipse Project

Once you have your tools installed (see http://www.makingthings.com/wiki/eclipse-openocd-gnu-arm-toolchain), it's time to create a project.

The first thing you will need is the source code for the Make Controller.  Go to http://www.makingthings.com/resources/downloads and download the latest version to your hard drive.  Unzip it and make a note of where you put it.  Then ...

Crank up Eclipse and begin. 

(The first time you start Eclipse, you will need to select the Workbench icon on the far right and tell Eclipse where you want the workbench's files to reside on your hard drive.)

Right-click in the Project Explorer (far left side) and select New C Project.  You can also use the menu bar at the top - File/New/C Project.

Give your project a name.

You can change the project location, but the default is in your workbench location.

Select Empty Project and make sure MinGW GCC is highlighted.  (Select the Empty Project item under Makefile project not the one under Executable).

Click Next (not Finish).

Click Advanced settings. We need to set up for the Yagarto toolchain ...

In the "C/C++/Build/Discovery Options" section, click the Browse button beside the Compile Invocation command textbox. 

Navigate to where you installed Yagarto, find the /bin directory and choose arm-elf-gcc-exe.

Click on the "C/C++/Build/Environment" category. 

Click on Path, then click the Edit button.  Enter the full path to the Yagarto /bin directory, followed by a semi-colon, then the full path to the MSYS /bin directory. 

Click OK.

Click on the "C/C++/Build/Settings" category.

Click in the checkbox for GNU Elf Parser and uncheck all others.

Click on GNU Elf Parser to highlight it.  Use the Browse buttons to select (from the Yagarto /bin directory) arm-elf-addr2line.exe for the addr2line textbox, and arm-elf-c++filt.exe for the C++filt textbox.

Click on the "C/C++/General/Paths and symbols" category.

Click on "GNU C" to highlight it.

Click the Add button. 

Enter the full path to the \arm-elf\include directory in the Yagarto install directory.

Click OK.

Click Finish.

Congrats ... you now have the shell for a Make Controller project.

Your screen should now show an Eclipse project with whatever name you gave it.  There is an Includes (virtual) folder which has the paths to the various include directories.

Now add a new, empty folder to hold our output (*.bin, *.elf, *.map, etc.)

Right-click in the Project Explorer area and select New/Folder.  Name the folder "Output".

Your project screen should now look something like this:

Now we need to add the Output folder we just created into the Project Properties.

Right-click the project name and select Properties (down at the very bottom), or click Project on the menu bar and select Properties.

Select C/C++ General and Paths and Symbols.  Click on the "Output location" tab.

 Select Add Folder and select the Output folder.

Click Apply and then click OK.

Now add a new, empty folder to hold our openOCD configuration files.

Right-click in the Project Explorer area and select New/Folder.  Name the folder "openOCD".

Now that we have the project pretty well defined, we need to add our source code files.

Right-click the project name in Project Explorer and select Import.

(Note: We are going to deviate somewhat from the file hierarchy in the source code download.  We will do this in order to get Makefile and main.c into the root directory of the project.  Trust me, this makes building the project a whole lot easier.)

Select General/File System and click Next.

Navigate to the downloaded source files folder, and then to the projects\tiny folder. 

Select config.h, main.c, and Makefile (right side).

Make certain the "Create selected folders only" radio button is checked.

Click Finish.

Your project should now look something like this:

Now repeat the Import steps above and navigate to the root directory of your downloaded source code.

This time select folders only (left side).  Select "core" and "libraries".

Again, make sure the "Create selected folders only" is checked, then click Finish.

Now - just for fun - let's attempt to build the project.

On the menu bar, click Project and Build All.

Result:

Oh well, it was a nice try.  As you see in the Console pane of the messages window (center bottom), there is a problem in the Makefile.  This is to be expected since we moved the Makefile from the \projects\tiny folder in the original hierarchy to the root directory in our current project.

Let's fix Makefile.  In Project Explorer, double-click on Makefile to open it in the editing window.

Notice that the paths to various files has "../../" in front.  That was correct when Makefile was located two subdirectories deep in the layout, but not now.

Use the cursor to highlight the first "../../" and fix this problem by doing a "Replace all" (menu bar/Edit/Find-Replace).

Much better.

Now, do another "Build All".

This time the project should compile successfully.  Look especially at the last line in the Console pane.  It should end with "output/tiny.bin".  If you wanted, you could use MCHelper and download this bin onto your Make Controller and it will function.

In a perfect world -- where all software worked correctly the first time ... and where all children were above average ... and where politicians always told the truth -- you would be done and could start writing your own modifications to the source code.

But, in the real world, you are undoubtedly going to have to debug your code at some point.  But the current Makefile is not set up correctly to allow you to debug.

Let's add the debug information into our compile.

Find the line (towards the end of the file) that reads "DEBUG=" and change it to "DEBUG=-gdwarf-2".  This compiler instruction adds "dwarf-2" debug code into the tiny.elf file.  Get it?  dwarf-2.  elf file.  Get it?  I'm surprised there isn't a hobbit in there somewhere.

After you add the debug instruction in the Makefile, save the Makefile.

Then do a (menu bar/Project) "Clean" followed by another Build All.

Now expand the Output folder in Project Explorer, and expand tiny.elf.

You can see all the debug symbols are in there now (they weren't before).

You might want to take a break here.  At this point, we have produced a debug-ready compiled output ... but we don't have any way to connect Eclipse to our controller to exercise the (GDB) debugger.  That's next.

OK, back from your break ...

The original *.cfg files in the openOCD folder of the source from Making Things will not work with the version of openOCD that you downloaded from Yagarto (... nor with the version 0.1 from the OpenOCD website, but that's a different problem).  Luckily, however, version r1888 (from Yagarto) has the new style config files included in subdirectories under its install directory.

Using Import (like you did to get the source files), navigate to the openocd-r1888 installed directory.

In the "target" subdirectory, scroll until you find "sam7x256.cfg" and click the checkbox for it.  The Make Controller uses an ARM7x256 chip, also known as sam7x256.

In the "interface" subdirectory, scroll until you find the JTAG interface that you have.  Mine is the Olimex ARM-USB-OCD dongle, but you may be using something else.  If you are unsure which interface .cfg to use, the first few lines in each file describe which dongle it is for.

After selecting the target .cfg and a suitable interface .cfg, use the Browse button to locate the openOCD folder in your project.  Finally, click Finish to import the two .cfg files.

The Import operation also created a target and an interface folder in our project.  We just need the .cfg files themselves, so expand the folders in openOCD and drag-and-drop each .cfg so it is directly under openOCD.  The delete the target and interface folders.

Things should look something like this:

The OpenOCD program, when it starts, looks for a file named "openOCD.cfg".  We need to create this file to tell OpenOCD how to proceed.

Right-click on the openOCD folder in your project and choose New/File.  Name the file openOCD.cfg and click Finish.

If the new openOCD.cfg file doesn't open automatically in your edit window, double-click on it to open.

Comments start with # in the first column.  Blank lines are ignored.

Here's what's in my openOCD.cfg:

===================

# Make Controller

# config for uploading and debugging

# using Olimex Arm-USB-OCD JTAG Dongle

source [find olimex-arm-usb-ocd.cfg]

#define our ports

telnet_port 4444

gdb_port 3333

# GDB can also flash my flash!

gdb_memory_map enable

gdb_flash_program enable

source [find sam7x256.cfg]

===================

Start with the config for your OCD dongle -- "source [find <name of your interface>.cfg]".  Then define the TCP ports that OCD and the debugger (GDB) will use. 

GDB can download binaries to your Make Controller if you enable it with the two lines starting with "gdb-".

Finally, tell OpenOCD what chip you are targeting -- "source [find sam7x256.cfg]"

Save and close openOCD.cfg.

Next we will set the properties for OpenOCD to be run from within Eclipse.

Locate the External Tools icon on the tool bar.  It's the green circle with a white arrow and a little red tool box. 

Click the down-arrow to the right of the icon.

Select External Tools Configurations.

In the left pane, right-click on Program and select New.

Give your configuration a name (you may eventually have several configurations). 

For "Location", click the Browse File System button and navigate to the \bin subdirectory of the directory where you installed openOCD.  Select the file openocd-ftd2xx.exe.

For "Working Directory", click the Browse Workspace button and select the "openOCD" folder in your project.

Click Apply.

Click the Common tab and click the checkbox to display this configuration in External Tools "Favorites Menu".

Click Apply and Close.

For the next step, you must have your OCD dongle connected to your PC and to the Make Controller -- and the Make Controller must be powered on.

Click the down-arrow beside the External Tools icon and select the configuration you just created.

If everything was successful, you should see a bunch of red text in the Console pane.

The critical line to look for says "JTAG Tap/device matched".  If you see this line, then OpenOCD is up and running and is connected properly to your Make Controller.

OpenOCD is actually a TCP server and you can connect to it using Telnet, GDB and Tcl.  Try Telnetting to "localhost 4444" ... (remember the port number you set in openOCD.cfg?).  When your telnet session connects, type "reset", then type "resume".  Your Make Controller should start flashing the controller green led assuming you have heavy.bin loaded onto it.  Exit the telnet session with "exit".

OK, we're almost done.  This last step can be a doozy however.  If you have problems with it, all I can say is go read the info on Yagarto's web and re-read the James P. Lynch tutorial for clues.  Mostly you may have to do a little experimentation with the Initialize instructions when starting GDB.

Click on the down-arrow beside the Debug icon on the toolbar (yes, it's the icon of a small green beetle) and choose "Debug Configurations".

On the create configurations screen, right-click "GDB Hardware Debugging" and select New.

Give this configuration a name. 

Click the Browse button beside the Project textbox and select your project.

Click the Search Project button beside the C/C++ Application textbox and select tiny.elf.

Next we have to tell Eclipse which GDB executable to run ...

Click on the Debugger tab.

Click the Browse button beside the GDB Command textbox and navigate to the \bin directory in the Yagarto install directory.

Select arm-elf-gdb.exe.

Change the port number to "3333".  (remember the port number in openOCD.cfg?)

Next click on the Startup tab.

In the Initialization Commands multi-line textbox, type (or copy and paste) the following --

monitor reset

monitor sleep 500

monitor poll

set mem inaccessible-by-default off

load

break main

continue

Comment lines start with # in the first column, blank lines are ignored. 

After you have downloaded the binary to your Make Controller with the "load" command above, you may want to comment the load command out unless you have changed the source code and recompiled.  Just saves a little time is all.

The final step in debug configuration is setting this config to show in the "Debug favorites" menu.

Click on the Common tab.

Click the checkbox to put this config on the "favorites" menu.

Click Apply.

Click Close (not Debug).

At long last, we are ready.  This is where the rubber meets the road, the proof is in the pudding, the <insert your own cliche here>.

Make sure the OpenOCD program is running (in case you terminated it earlier).

Click the down-arrow beside the Debug icon on the toolbar.

Click on the debug name you just created.

Ta da !!

If everything worked as planned, the Eclipse "Debug Perspective" should now be showing and the firmware should be stopped at the "main" function in main.c.  You set this breakpoint in the debug config with the "break main" command ... you can also set breakpoints in the edit screens in the Eclipse C/C++ perspective.

I hope everything worked well for you.  If not, go back and check your work from the first to last step. 

If you are still having problems and just can't work it out by yourself, read (and search) the Make forum.  As a last resort, post in the Development Discussion forum to ask for help.