Sunday, November 25, 2012

The complete tutorial for Stellaris LaunchPad development with GNU/Linux (III)

We set-up the toolchain and built StellarisWare libraries and lm4flash tool. We are also able to debug programs using gdb + openocd. But command line building and debugging projects isn't fun, is it? No problem. In this chapter we will create an Eclipse project, and will be able to build the sources, flash them and debug with a few mouse clicks.


Installing Eclipse

You have to install Eclipse + CDT (C/C++ Development Tooling). If you are using Ubuntu (or any other Debian based distro), use this command:
sudo apt-get install eclipse-cdt
If like me, you are using Arch Linux, try this one:
sudo pacman -Sy eclipse-cdt
And that's all for the installation. This tutorial has been written using Eclipse version 4.2.1. If you are using other revision, there might be some differences, but you should be able to configure everything anyway. When watching screenshots, if the text is not legible, click the image to watch it full size.

Let's create a new project with the files from the template we built in the previous chapter.

Creating the project

  1. Launch Eclipse. You'll be asked to select a directory for the workspace. Select src/stellaris/projects directory, under your home (/home/jalon in my PC):
  1. Create a new project. Click File/New/Project...:
  1. Select C Project (under C/C++) and click Next >:

  1. In the Project name text box, write "template". In the Project type tree, select Executable/Empty Project. Then select Cross GCC Toolchain and click Next >:
  1. Now click Advanced Settings:
  1. Select C/C++ Build/Settings in the tree. In the Configuration combo box, select [ All configurations ]Make sure you keep [ All configurations ] selected for all the following steps, until number 14. In the Tool Settings tab, in the Cross Settings section write "arm-none-eabi-" into the Prefix text box:
  1. Click Symbols under Cross GCC Compiler. Add the following symbols: PART_LM4F120H5QRARM_MATH_CM4TARGET_IS_BLIZZARD_RA1:
  1. Jump to the Includes section and add the path to StellarisWare libraries. It should be in src/stellaris/stellarisware directory, under your home:
  1. In the Miscellaneous section, in the Other flags: text box, you should see "-c -fmessage-length=0". To these two flags, add these all: "-mthumb -mcpu=cortex-m4 -mfpu=fpv4-sp-d16 -mfloat-abi=softfp -ffunction-sections -fdata-sections".
  1. It's time to add StellarisWare driver library. Go to the Cross GCC Linker / Libraries section, add "driver-cm4f" to the Libraries (-l) list, and "src/stellaris/stellarisware/driverlib/gcc-cm4f" prefixed by your home to the Library search path (-L) list:
  1. In the Miscellaneous section add the following Linker flags"-Wl,--static,--gc-sections,-T../LM4F.ld -mthumb -mcpu=cortex-m4":
  1. Go to the Build Steps tab, and in the Command text box inside the Post-build steps frame, type "arm-none-eabi-objcopy -O binary ${ProjName}.elf ${ProjName}.bin". Then in the Description: text box below, type "Generate binary file from elf file":
  1. Switch to the Build Artifact tab and add ".elf" to the "${ProjName}" text inside the Artifact name: text box. The resulting string should be "${ProjName}.elf". When finished, click OK:
  1. That was a long configuration, but when you click Finish, the project will be ready. You might need to advance to the next step before the Finish button becomes enabled. If that's the case, click the Next > button to advance to the next step, enter "arm-none-eabi-" in the Cross compiler prefix text box, and finally click Finish. If Eclipse asks you if it should open the C/C++ perspective, say yes. Also, if it's still opened, close the Welcome tab.
  1. You should see the Eclipse layout for an empty project. We will not use the Java perspective, so right click it and then click Close:
  1. It's time to start adding files to the project. We will use the template project by Scompo. We downloaded it in the previous chapter. Let's copy the source files. Go to the terminal and type:
cd ~/src/stellaris/stellaris-launchpad-template-gcc
cp LM4F.ld LM4F_startup.c main.c ../projects/template
  1. Files are automatically added to the project once you put them in the project folder. If you don't see the files in the project explorer, just right click the template project and then click Refresh. If the project tree is collapsed, also make sure to expand it.
  1. The source files should apper in the project tree. Everything is set to start using Eclipse for coding. I'll not explain how to use Eclipse, I'll only say you can open a file by double clicking it in the project explorer, and you can build the project (and select the configuration to build) using the hammer button. Try it, the project should be built without a problem. If something goes wrong, right click the project name in the Project Explorer, then click Properties, and repeat configuration steps from 6 to 14.

Flashing programs

You have built a program using Eclipse and you want to test it, but you refuse to flash it using a boring terminal. Today it's your lucky day, I have the solution to your problem. You can configure Eclipse to launch lm4flash and flash your program.

  1. Click Run/External Tools/External Tools Configurations...:
  1. Right click Program, then click New:
  1. Change Name for example to "Release flash", Location to the place where lm4flash is (we installed it to sat/bin/lm4flash under your home), Working Directory to "${workspace_loc:/template/Release}" (Release directory of your project) and Arguments to "template.bin" (the binary file we want to flash):
  1. Switch to Common tab and enable External Tools in the Display in favorites menu frame. Then click Apply and finally click Close:
  1. And that's all. To flash the binary generated in the Release configuration, just pop the External Tools menu and click Release flash:
Each time you flash a program, in the Eclipse Console tab should appear a message similar to "Found ICDI device with serial: XXXXXXXX. It confirms lm4flash was called, found the MCU and flashed the program. I don't know why, but it looks like the first time I try to flash a program, this message doesn't appear, and lm4flash appears to be blocked. If this happens to you, go to the Eclipse Console tab and terminate lm4flash (click the button with the red rectangle). Try flashing again and from now on, it should work.

Debugging

The main reason I have, to embrace Eclipse or other similar IDEs (like for example Code::Blocks), its because of it's wonderful integrated debugger. If you don't like command line debugging with gdb, you'll love Eclipse once you set up the debugger. Let's get to it.
  1. First we have to add another External Tool, to launch openocd. Repeat steps 1 and 2 in the previous subchapter (Flashing programs), to add a new program.
  2. Change Name to "openocd", Location to your home directory plus "src/stellaris/openocd-bin/openocd"Working Directory to your home directory plus "src/stellaris/openocd-bin" and Arguments to "--file LM4F120XL.cfg". Then click Apply and finally click Close:
  1. Now we have to configure gdb. Click Run/Debug Configurations...:
  1. Right click GDB Hardware Debugging, then click New. James Kemp pointed me out some Eclipse installations lack GDB Hardware Debugging options. If that's the case in your setup, you'll have first to install the GDB Hardware Debugging by using the Help / Install New Software dialog.
  1. Change Name to "gdb", C/C++ Application to "Debug/template.elf" and Project to "template":
  1. Switch to the Debugger tab. Then change GDB Command to "arm-none-eabi-gdb", and uncheck Use remote target:
  1. Now go to the Startup tab. Uncheck Reset and Delay (seconds) and Halt checkmarks. In the Initialization Commands text box enter two lines: "target extended-remote :3333" and "monitor reset halt". In the Run Commands text box enter "monitor reset init". Then click Apply and finally click CloseWARNING: If you had the problem with gdb/openocd explained in the troubleshooting section in the previous chapter, you also will have to copy to the project directory the "target.xml" file you used, and add the line "set tdesc filename target.xml" to the Initialization Commands. This added line must be the first one in the list.
  1. We could start debugging right now. To do this, we could launch using Eclipse menus, first openocd and then gdb. But we can make Eclipse launch both programs with a single menu action. Click Run/Debug Configurations...:
  1. Right click Launch Group, then click New:
  1. Change Name to "Debug", then click Add... button:
  1. Change Launch Mode to "run", select "openocd" and click OK:
  1. Click Add again. The same window will pop up. Now select "gdb" and click OK.
  1. Go to the Common tab. Add a checkmark to Debug in the Display in favorites menu frame. Then click Apply and Close:
  1. It took us some time, but I swear everything is configured now. No more configuration steps from now on. To start a debug session, click the Debug template menu, and then click Debug. If Eclipse asks you if you want to switch to the Debug Perspective, say yes. I have found that if I use lm4flash tool before debugging, openocd doesn't start properly until I unplug the LaunchPad from the USB port and plug it again, so if the debug session doesn't start, try unplugging and plugging the LaunchPad again.
Here you can see the debug layout. In the Debug window you can see the launched applications. There you can see openocd and gdb, and also the Debug launch group. Over the Debug window, you can find the buttons for controlling the program execution (continue, stop, step into, step over, etc.). You can set breakpoints, watch variables, registers and memory, you have a disassembler, etc. Really cool, isn't it?
To stop the debug session, I'd recommend to click the Debug launch group, then the Terminate button (the one with the red square), and then the Remove all Terminated Launches button (the one with the two grey crosses, to the upper right of the Debug window). If you want to continue coding, it's also recommended to switch back to the C/C++ perspective.

That's all! It was a looooooooooooong entry! I hope you enjoy coding with Eclipse as much as I do. For the next chapter, I'll show you how to build the CMSIS DSPLib, a powerful library for signal processing and other CPU intensive maths algorithms.

Happy hacking and stay tuned!

31 comments:

  1. I tried to debug using the same way but getting some error as below.

    "Error in final launch sequence
    Failed to execute MI command:
    -exec-run
    Error message from debugger back end:
    Don't know how to run. Try "help target".
    Don't know how to run. Try "help target"."

    It was working in commandline bye troubleshooting (xml file) and an additional line in the gdb prompt. I added those also but not working in eclipse.
    Any suggestions?

    ReplyDelete
    Replies
    1. Did you copy the XML file to the root of your project (it should be at ~/src/stellaris/projects/template/target.xml)?

      Do you have the following lines for Initialization commands, and in the same order? (step 7):
      set tdesc filename target.xml
      target extended-remote :3333
      monitor reset halt

      Did you uncheck "Reset and delay" and "Halt" (step 7)?
      Did you uncheck "Use remote target" (step 6)?

      Delete
    2. Hi! I also got the same error. I repeated the steps and redid the instructions from your reply but the error still persists. Any other suggestions? Thanks. :)

      Delete
  2. Really nice, man! I can't wait to set up eclipse and try this out!

    ReplyDelete
    Replies
    1. No problems at all, works fine!
      What about using more variables inside the commands to make a template project?

      Delete
    2. Thanks for trying. I'm glad you like it, my debugger setup tutorial is based on yours :-)

      I tried using more variables, but I wasn't able to get a fully working debugger configuration using generic variables.

      Delete
    3. I tried and I wasn't able to get it working too with variables :(
      Well anyway it's really cool and easy to edit when needed.

      Delete
  3. No reason but why do you not use OpenOCD to program aswell?

    May not be an issue for smaller programs, but the flash programming time will be quicker as we use an async algorithm to program.

    I generally setup one debug profile to program and the other to just debug.

    ReplyDelete
    Replies
    1. As you wrote, there's really no reason to do it like this. In the first chapter of this tutorial (http://kernelhacks.blogspot.com.es/2012/11/the-complete-tutorial-for-stellaris.html), I already pointed out building lm4flash is optional, because we can flash the chip using gdb + openocd. But as we built the tool anyway, I just wanted to show how to integrate it in Eclipse.

      Delete
  4. This comment has been removed by the author.

    ReplyDelete
    Replies
    1. This comment has been removed by the author.

      Delete
  5. Just curious, do these instructions work in a windows setup with eclipse?

    ReplyDelete
    Replies
    1. Paths will differ, but if you have a working toolchain (compiler + GDB + openocd), I suppose you should be able to integrate it into Eclipse in a similar way.

      Delete
  6. Bingo!!!

    Finally made it. What a slog to get to the end. But, Oh Man - such a thing of beauty when it all works. Thanks again for providing the road map.

    Two things.

    Within the "Debugging Section" on step four, my Eclipse did not have "GDB Hardware Debugging" as a thing to add. Luckily, I knew just enough to know that I needed to use the menu option "Help / Install New Software" to add GDB Hardware Debugging to my Eclipse setup. However, I could see new people getting totally messed up over that.

    Second thing, my first attempt running through your steps was done using a VMWare Ubuntu machine running on a Ubuntu host. Everything work great (of course) until the last step. OpenOCD / GDB seemed to kinda work. Both OpenOCD and GDB would fire up and run. And if I set a breakpoint in main or the irq everything worked fine. The breakpoint would fire and I could see the current value of var_init and count. However, if I removed the breakpoints and hit the run button I could never pause the target again. Maddening, I can tell you.

    Oh, I tried a bunch of stuff. Increased the timeout value in OpenOCD from one to two seconds. Also, tried a bunch of OpenOCD command parameters plus updating the hardware firmware. Nothing seemed to work after hours of effort.

    Starting over without VMWare in the mix worked like a charm.

    My grand plan was to post a VMWare virtual machine on my Google drive that anyone could download and run inside VMWare Player for free. The plan was to have everything installed, setup, and working.

    Oh well, some kinda VMWare USB weirdness I guess.

    Anyway, thanks again for all the great info.

    I'm off to the races,
    Jim

    ReplyDelete
    Replies
    1. I'm glad you got it working! I'm using Arch Linux, and my Eclipse install already came with GDB Hardware Debugging support. I'll add a warning to the tutorial.

      Thanks a lot for sharing your findings :-)

      Delete
  7. Thanks for the great tutorial. Here a couple of my thoughts:

    1) I had to add the path to the arm-gcc compilers (/home/username/sat/bin) in the "Path" option of the Cross Settings tool setting. (Step 6 under "Building the project".) Not sure why I had to add this since these executable are in my PATH variable.

    2) By making a couple changes to the lm4flash external program, you can make this project a true "template"

    a) Change the Working Directory field of the Release Flash External Program Configuration to "${workspace_loc:/${project_name}/Release}"

    b) Change the Arguments section to "${project_name}.bin"

    You are now no longer tied to the name "template". I was able to copy and rename the entire template folder from the command line, import the the newly named project, and everything worked. This way you can keep your "template" project as a template, and just copy and rename it anytime you want to start a new project.

    ReplyDelete
    Replies
    1. I tried to create a template project, but couldn't find the right variables.

      Thanks a lot for the suggestions!

      Delete
  8. Great tutorial! Please explain how to use external makefiles in case of multiple .c files and some other rules.

    Regards,
    Semen

    ReplyDelete
  9. Hi!
    Thank you very much for this wonderful article.
    TI recently changes the name of their Stellaris Software to "Tiva SoftWare" ... Well basically all the drivers and libs are exactly the same, expect this little name changes.
    And they add some little modification, step 10, in the Cross GCC Linker - Librairies section we should change "driver-cm4f" to just "driver". And everything else is fully working!

    Thank you again!

    ReplyDelete
    Replies
    1. Thanks a lot for sharing the changes!!!

      Delete
  10. I've got problems under Ubuntu 12.04 to launch eclipse. The log file stated:

    no swt-gtk-3740 in java.library.path

    no swt-gtk in java.library.path

    Can't load library: /home/gerbil/.swt/lib/linux/x86/libswt-gtk-3740.so

    Can't load library: /home/gerbil/.swt/lib/linux/x86/libswt-gtk.so

    I found the following solution on http://stackoverflow.com/questions/10165693/eclipse-cannot-load-swt-libraries:

    > ln -s /usr/lib/jni/libswt-* ~/.swt/lib/linux/x86/

    It now works.

    Regards
    Gerhard

    ReplyDelete
    Replies
    1. Thanks for sharing the solution!

      Delete
  11. Hi,

    How did you get the driver-cm4f library?

    When a try to build the project template with Eclipse I got this result:
    /home/alexandre/sat/lib/gcc/arm-none-eabi/4.7.3/../../../../arm-none-eabi/bin/ld: cannot find -ldriver-cm4f

    I search for it in ~/src/stellaris/stellarisware/driverlib/gcc-cm4f, but I not found. There are several .d and .o files in this folder, but there isn't the driver-cm4f file (library)...

    Note: I followed all steps in the first and second tutorial.

    Regards,

    Alexandre

    ReplyDelete
    Replies
    1. It's difficult to know, but it looks like you are linking using "ld". It's better to link using "gcc", because "ld" is very strict with libraries configuration. Make sure in Settings/Tool Settings/Cross GCC Linker/General you are using "gcc" instead of "ld" to link.

      Delete
    2. I have the same problem, but my linker is set to gcc. What is special about my setup is that I'm using Windows with msys to build all the libraries. However, heres my console output:
      arm-none-eabi-gcc -Wl,--static,--gc-sections,-T../LM4F.ld -mthumb -mcpu=cortex-m4 -o "template.elf" ./LM4F_startup.o ./main.o -ldriver-cm4f
      e:/development/cdt/crosscompiler/bin/../lib/gcc/arm-none-eabi/4.8.3/../../../../arm-none-eabi/bin/ld.exe: cannot find -ldriver-cm4f
      Do you have an suggestion about what is the problem?

      Delete
    3. It looks like you did not set the right library search path (step 10) of project creation, as the library path does not appear in the command line. Also verify there is a file named "libdriver-cm4f.a" in that path.

      Delete
    4. My problem was that I had some resource filters activated in eclipse to prevent it from compiling StellarisWare. I just had to configure those more, so that they work. But in the moment I have the problem that the sin() and cos() (and all the other math functions) aren't available to me, although CCS seems to have them. Do you know how I can get them as normal functions? (The math.c seems to include os.h, so just copying and including them would not help)

      Delete
    5. To use math functions, you have to link using the math library, i.e. have you added "-lm" switch to the link flags?

      If your problem is the linker spits some "unresolved externals", this is most likely your problem.

      Delete
  12. Everything running - thanks again for the tutorials!

    ReplyDelete
  13. I have a problem with the GDB section:

    /bin/bash: /home/scm1hewf/src/stellaris/projects/template/Debug/template.elf: cannot execute binary file
    /bin/bash: /home/scm1hewf/src/stellaris/projects/template/Debug/template.elf: Success

    Any ideas what could be causing this?

    ReplyDelete
  14. Excellent tutorial!! Work smooth at the 1st attempt!

    ReplyDelete