Uzebox Developement Under Eclipse

Windows

• Install the latest WinAVR -- Currently WinAVR-20100110
• Install Eclipe CDT (C Developement Toolkit) -- Currently 6.0.x. Be sure to install the GDB options.
• Install the AVR Eclipse Plugin -- Currently 2.3.1
• If using the AVRISP mkII under Windows XP, you will also need libusb-win32 drivers. Important: *do not* install on Vista or Win7, some have reported crashes and BSODs.

Debugging

Overview

This article will take you through the steps necessary to debug your program in the Eclipse debugging view, where you will be able to set breakpoints, watch variables and do all the other fun stuff you may be used to doing with other programs. Unfortunately, this takes quite a bit of manual configuration with Eclipse, and is not as straightforward on Windows as it is on Linux. Despite the frustration involved in setting this up, i find using PrintInt just isn't sufficient for debugging those hard to conceptualize problems.

Assumptions

This article assumes that you have at least successfully configured Eclipse on windows to build a hex file for the uzebox.

Steps

Compiling the Emulator

The first step is to compile the most recent version of the emulator. (The old version did not support debugging) As of 04/11/10 there are no windows binaries for the new emulator. You will have to compile them from source yourself. If you've ever tried to compile a program using a makefile written in linux, you know what a pain this can be! The makefile will seldom work out of the box.

Follow this tutorial for how to compile the emulator on windows exactly. If your like me you hate the idea of installing a directory to the root of your C drive, just install it there temporarily, and delete it after your done building. After a hour of failed attempts at editing the makefile, you can trust me on this. (If any of you have figured out how to do this to point to directories other than the ones specified in the tutorial, please update this article)

Once you have compiled the emulator, lets do a few check from the command prompt to verify that everything is working properly before attempting to configure eclipse.

Testing the emulator with avr-gdb

First, lets run the emulator in debug mode. Lets make our lives a little easier by creating a shortcut to the program that will run our hex file in debug mode, so we don't have to slough through the prompt. Right click on uzem.exe and hit create shortcut from the menu. Right lickc on the shortcut you just created and select properties. Next edit the shortcuts target field by adding two arguments to the end of the string.

first, add a -d which will put the emulator in debug mode.

second, add the path to your hex file. (I put mine in a subdirectory call roms, so my hex files need to be copied to this directory each time i build a new version of the game)

My path looks like this: E:\uzeboxdev\UzeboxEmu\uzem.exe -d roms/YFTGH.hex

Okay, so double click on your shortcut and you should now see two windows popup. One will be labled SDL_app and the other the uzem. Both windows should be totally blank!. (This is normal) The emulator is waiting for the debugger to connect. You may see a windows firewall exception window pop up. Please allow the connection.

Next, lets fire up the debugger from the command prompt and connect it to the emulator. Debugging is accomplished by running the program in a sort of client/server mode. The emulator is the server, which sets up a TCP port and waits for a client to connect. The client, is actually the debugger itself. This is why you needed to add a windows firewall exception for the emulator.

Open up a terminal and type avr-gdb, if the path to avr-gdb is in your PATH variable, you should see the license and copyright information and the the prompt (gdb). Next tell gdb to connect to the emulator. Type

target remote localhost:1284

you should see gdb respond with:

Remote debugging using localhost:1284
0x00000000 in ?? ()

hit c to continue, and you should now see your app running as it normally would. You can debug your entire application like this, from the command prompt if you are so inclined. It looks pretty bad-ass, and everyone who sees you using it assumes your a super-genius. Somethings are easier via the prompt, but I tend to prefer the GUI.

If you want to learn more you can read all of the commands here:

You can close the emulator when you want. GDB will complain, but it gets you the prompt back and you can type quit to leave GDB. (i'm sure there's a better way of doing that)

Setting up Eclipse for Debugging

These settings are made for Eclipse IDE for C/C++ developers (Build id: 20100218-1602). More recent version may slightly vary. The setup involves creating a launch group that will, in turn, start the emulator in debug mode with your game and then start the gdb client debugger. We will use Megatris as an example.

Create the emulator launch configuration

• Open menu Run->External Tools->External Tools Configuration...
• Press the New button to create a new launch configuration
• Name the configuration like "Run in emulator (Megatris)"
• In the "Main" tab, under "location" browse to uzem.exe (i.e: C:\uzebox\trunk\bin\uzem.exe)
• In working directory, browse to the "default" directory (i.e: ${workspace_loc:/Megatris/default})
• In "Arguments", enter the "-d" switch followed with your game's HEX file (i.e: -d Megatris.hex)
• Click apply

Create the GDB debugger client configuration

• Open menu Run->Debug Configuration...
• Select the "C/C++ Application" group in the left panel and press the new button
• Named you configuration like "Megatris Debug configuration"
• Choose you project. "Build configuration" should be set to "Debug" and "C/C++ Application" should point to "default\megatris.elf"
• Click the debugger tab
• In the "Debugger" drop-down, choose "gdbserver Debugger"
• Uncheck "Stop on startup" if you do not want the debugged to stop in main() when you start debugging
• Under the debugger options, in the "Main" tab, set GDB debugger to "avr-gdb" or browse to your local copy (i.e: C:\winavr\bin\avr-gdb.exe)
• Clear the field "GDB command file"
• Enter the "Connection" tab
• For type choose TCP, set hostname to "localhost" and port to "1284"
• If you get a red "X" with something mentionning a process launcher, click "select other..." , check "use configuration specific settings" and choose the "standard create process laucher"
• Click Apply

Create the launch group

• Within the same Debug Configurations window, select "Lauch Group" in the left panel and click the new button
• Name you configuration like "Debug on uzem (Megatris)"
• In the right panel, click the "Add..." button
• In the "Launch mode" drop-down, select "run"
• Expand "Program", select "Run in emulator (Megatris)" and click Ok
• Click "Add..." again
• Expand "C/C++ Application", select "Megatris Debug configuration" and click Ok
• Click Apply

Makefile parameters

To be able to fully use the uzem GDB debugging features (like variable visualization) your must set these debugging options in the Makefile. Note that these changes from the dwarf-2 format required by AVRStudio's emulator.

ASMFLAGS += -g3 -gstabs+

CFLAGS += -g3 -gstabs+

Click the debug icon's little down arrow and select "Debug on uzem (Megatris)" from the list. Uzem will launch your game, then the debugger will start. You are now ready to debug!

From here you can set breakpoints (I personally, can't see any variables in the variables tab, but I can see the values of all the CPU registers, which is super useful);

Terminating the debugger will close the session, and the emulator.

Beware the optimizing compiler! Compiler optomizations will often, strip out of reorder code you have written. This can cause strange behavior in the debugger if you set a breakpoint to a piece of code that was removed, or want to check the value of a variable that was removed. This is especially bad if your fond of writing test functions like I am that perform computations but don't return a value.

You should do one of two things. 1.) set the optimizations switch in the MakeFile to -O0 to build without any optimizations. In my case, I could not do this, building without optimizations made my code too bug to fit on ROM. So I had to go with method 2.) make sure your code "does" something with the variable you want to look at.

I'm sure this is not the optimal work flow. Its probably possible to automate this by having eclipse copy your hex file to the right directory, and launch the emulator in debug mode for you. Experiment with your debugging environment and please update this article with any tips or tricks you learn!

External Links

• Follow this tutorial on how to configure eclipse to use GDB.

TODO: add screen shots of the steps