Thursday, September 1, 2011

Part 3: Mac OS + Eclipse + OpenOCD + STM32 (ARM Cortex M3)

I really wanted to program and debug ARM processors from my Mac. This series of entries is a work in progress as I fine tune my setup for regular use.  Be sure to read the full story:
Part 1: Getting Started, what we are going to do and what parts we are going to use.
Part 2: Laying the Foundation, getting all the parts installed.
Part 3: Connecting the Plumbing, hook up all the pieces and run it.
Part 4
: Finishing Touches, troubleshooting and final thoughts.

Connecting the Plumbing
So at this point you have all the software and tools installed and it is time to hook everything together. I considered an infographic/flowchart to describe it all, but maybe later. For now, consider this
  • Eclipse uses OpenOCD to make the bridge to the hardware
  • Eclipse then uses a makefile in your project to invoke YAGARTO to compile your source into binary and debugger files
  • Eclipse then uses YAGARTO's GDB via Zylin to send the binary file over the OpenOCD bridge to the hardware using a simple (JTAG and chip dependent) OpenOCD script that I'll share with you
  • Now that your microcontroller is programmed Eclipse uses its built in debugger features to control YAGARTO's GDB via Zylin to control and debug your device over the OpenOCD bridge
As you can see, there is a lot of interaction between the parts, but after initial setup the complexity will be reduced to a three step process: 
  1. Build Project.
  2. Start OpenOCD. Even better: you only have to do this once per session.
  3. Start Debugging. Automatically downloads the latest binaries to your target each time.
Create a Test Project
  1. YAGARTO's example page has a nice starter project. It is their STM32Test project for the STM32-P103 board, but really its so simple it will work for anything. I modified the makefile to suit my setup and preferences, and I'll show you how to do it, too. Download it and extract it, doesn't matter where you put it.
  2. Time to import the project into Eclipse. Go File->New->C Project. Name it STM32Test for consistency, Project Type is "Makefile project"->Empty Project, Toolchain setting is "-- Other Toolchain --". Hit Finish.  My project is called STM32Test2 since I'm redoing this for you.
  3. In Project Explorer, right-click on your new project name and click "Import...". Set the Import source to be "General"->File System, then hit Next.  The From Directory is where you extracted the STM32Test project to. You want to import everything except for the root folder, see the image below (click to expand). To do this, expand the root folder, choose the three sub-folders, then click on the root folder to view its files and select the makefile.  The Into Folder path is set to your new project path because that was the one you right-clicked on to start the import. Press Finish to complete the import.
  4. Now that the files are in your project expand the project folder in the Project Explorer of Eclipse so you can see the contents.  Open the makefile by double-clicking on it. 
  5. Find the makefile line near the top that begins with TRGT.  Since Eclipse doesn't like to respect PATH variables I changed this line to reflect the absolute path to the YAGARTO compiler tools: TRGT = /Developer/YAGARTO/yagarto-4.6.0/bin/arm-none-eabi-
  6. My STM32 toolchain configuration wants binary files instead of hex files, so I went down a five lines and changed the BIN entry to be: BIN  = $(CP) -O binary
  7. I also wanted to run the program from the Flash memory of my micro so I scrolled down further and changed this setting: RUN_FROM_FLASH = 1
  8. Note that later when you add more source files to you project you will need to add them to the source files list in the makefile.  Header files are found automatically as long as they are in the project folder.
  9. Ok, that's it, save the makefile, then build your project from the Project menu or just by right-clicking on your project in Project Explorer. The Console window should show all the of the compiler commands rushing by then three new files should appear in your project: test_rom.elf (debugger data file), test_rom.hex (the image for your micro, its actually binary), and (like any map file, showing what is will be in the various memory areas of your micro).

Configure OpenOCD as an External Tool for Eclipse
  1. Look for External Tools icon on the toolbar and hit the drop-down arrow, or go to the Run menu -> External Tools, and choose "External Tools Configuration".
  2. On the left side of theExternal Tools Configuration dialog box click on "Program", if it's not already selected, and the right-side pane will show you what you can do with this dialog box.
  3. Choose the New option and the right-side pane will show you details of your new tool configuration.
  4. First thing to note is that the Helios release of Eclipse does not remember your global or project prefs settings for environment PATH variables.  So, where ever I use file paths I put in the absolute path rather than using relative paths and relying on the environment setting. You can either use the latest version of Eclipse or modify your Mac's PATH variable if you don't like this.  I understand the lack of portability, but I blame it on Eclipse and my laziness of not upgrading.
  5. Location is the path to the executable of the tool, and that tool is OpenOCD
  6. Arguments setup OpenOCD for your particular toolchain, my case is the Olimex ARM-USB-TINY-H and the ST Micro STM32.  The OpenOCD scripts folder contains quite a few different options here, but be aware that changing these options may result in necessary changes elsewhere in our IDE setup.
  7. The "Main" tab is all you need to worry about here. Fill in your new tool configuration as shown in the image below (click to enlarge), then press Apply then Close. You can run this external tool from the toolbar by clicking on the drop-down arrow of External Tools and finding the tool name (ARM-USB-TINY-H Start), you may have to Run the tool from inside its configuration window the first time to get it to appear in the drop-down menu. So, make sure that your JTAG is plugged into USB and plugged into your target, and make sure your target is powered, then run it!
  8. The console should show lots of red text (red doesn't mean error), and it should look something like this:
    Open On-Chip Debugger 0.4.0 (2011-07-22-14:08)Licensed under GNU GPL v2For bug reports, read kHzjtag_nsrst_delay: 100jtag_ntrst_delay: 100Info : max TCK change to: 30000 kHzInfo : clock speed 1000 kHzInfo : JTAG tap: stm32.cpu tap/device found: 0x3ba00477 (mfg: 0x23b, part: 0xba00, ver: 0x3)Info : JTAG tap: tap/device found: 0x16410041 (mfg: 0x020, part: 0x6410, ver: 0x1)Info : stm32.cpu: hardware has 6 breakpoints, 4 watchpointsInfo : JTAG tap: stm32.cpu tap/device found: 0x3ba00477 (mfg: 0x23b, part: 0xba00, ver: 0x3)Info : JTAG tap: tap/device found: 0x16410041 (mfg: 0x020, part: 0x6410, ver: 0x1)

Set the Debugger Configuration for Eclipse
  1. Find the Debugger icon on the toolbar and hit the drop-down arrow, or go to the Run menu, and choose "Debug Configurations".
  2. Since you've already installed the Zylin CDT Plugin you will have "Zylin Embedded Debug (Native)" in the list on the left side.  Select this and press the "New launch configuration" button at the top of the list.
  3. For this setup there are three tabs that we are interested in: Main, Debugger, and Commands.
  4. Main Tab: Thus far in my usage I've needed a separate debugger config for each project because there are pathnames hard coded into the debugger commands, I'm sure this can be improved on, but not yet. So, at the very top of the dialog box we are going to call this setup "STM32TestROM".  Then put in the optional project name, either browse for your new project or type in the name STM32Test (STM32Test2 in my case). The C/C++ Application is the .elf file created by the project build, which you can search or browse for, or just type in "test_rom.elf".  Note that since we pointed it at the "_rom" file this config is specific for running our program in Flash and not RAM, since our makefile uses "_ram" output filenames for non-Flash compiled programs.  Feel free to customize.
  5. Debugger Tab: Debugger is "Embedded GDB", Selected "Stop on startup at: " and put "main" in the text box. GDB debugger absolute path (for me) is: "/Developer/YAGARTO/yagarto-4.6.0/bin/arm-none-eabi-gdb". Clear out the GDB command file field.  GDB command set: standard. Protocol: mi.
  6. Commands Tab, 'Initialize' commands: 

  7. target remote localhost:3333
    monitor soft_reset_halt

  8. Commands Tab, 'Run' commands:

  9. monitor soft_reset_halt
    monitor wait_halt
    monitor poll
    monitor flash probe 0
    monitor stm32x mass_erase 0
    monitor flash write_bank 0 STM32Test2/test_rom.hex 0
    monitor soft_reset_halt
    symbol-file test_rom.elf
    thbreak main

  10. That's it.  Apply. Close.
  11. The OpenOCD JTAG interface is already running from before, so now we just need to run the debugger.  The Debug toolbar icon offers the drop-down arrow where you can find your debug configuration name.  Again, the first time you run it you may have to go click "Debug" from inside the debug configuration setup window to get it to appear on the toolbar menu. When you do this Eclipse will automatically switch the IDE to the Debug Perspective so you can see your typical debugger view and tools like Disassembly and Step controls. Eclipse has a powerful debugger that even allows you to hover the mouse over variables in your source code and read the realtime values when the program is halted.
Next Step
Ok, that was a long post, I went further than I expected, but ideally you are up and running now.  I'm going to leave it here for today, but next time I'll get into some troubleshooting and configuration tweaking items. Part 4: Finishing Touches.

1 comment: