Hardware/EIR/Debugging

From Nutwiki
Jump to: navigation, search

Elektor Internet Radio Source Code Debugging

This document explains how to setup Eclipse and OpenOCD to allow source code debugging of Nut/OS applications running on Elektor Internet Radio. It is assumed, that you are already familiar with creating Nut/OS applications. The [[../../pdf/enswm28e.pdf|Nut/OS Software Manual]] describes the required steps.

This document has been originally written for Nut/OS 4.9 beta. Additional comments had been included later to cover Nut/OS 4.10.

Note, that you don't need to use Eclipse to create your own Nut/OS applications. You favorite text editor is just fine to create the source code and building your application can be done on the command line.

The same is true for debugging. There are a number of alternative tools available, like GDB for the command line purists or Insight, which provides a GUI for GDB. Actually, Eclipse uses GDB too, but provides a nicely integrated user interface for editing, compiling, uploading and debugging Nut/OS applications. While based on Java, it is available on all major platforms.

One last word before you move on: If you got here, because you assume that either your application or any of the Nut/OS libraries contains a bug, you should carefully think about, whether source code debugging will really help. Multithreaded network applications often fail because of timing problems or racing conditions. Setting breakpoints and inspecting variables will seldom help to find such bugs. What you need is some sort of tracing. In its most simple form, you can use the devDebug device to let your program output additional information on the serial port while running. In almost the same way you can use syslog. A similar situation may occur, when parts of memory are overwritten by bad pointers or buffer overflows. You should consider other debugging methods provided by Nut/OS, which are explained in the chapter Error Handling of the Nut/OS Software Manual.

Requirements

This is a short listing only. For Details please refer to the related manuals.

Required Hardware

  • Elektor Internet Radio Board
  • Turtelizer 2 JTAG Dongle
  • JTAG Connector Adapter
  • PC with USB and RS-232 port
  • 12V Power Supply
  • RS-232 DB9 Null Modem Cable
  • USB A/B Cable

The first 2 items you can build yourself, using the Eagle 4.11 CAD files for [[../../../arc/eir10c.zip|Elektor Internet Radio]] and [[../../../arc/turtle20b.zip|Tutelizer 2.0]]. Readily built and tested devices are available at www.egnite.de/en/egnite-shop.html and from several distributors.

Required Software (Windows)

The following software needs to be installed on the Windows PC:

  • Windows XP or later
  • Java Runtime Environment 1.6 or later
  • Eclipse Platform Runtime Binary 3.6.2 (Helios)
  • Eclipse CDT 7.0.2
  • TeraTerm or similar Terminal Emulator
  • Nut/OS 4.10
  • Turtelizer OpenOCD Package
  • Turtelizer FTDI Driver

You can download the Java Runtime at www.oracle.com/technetwork/java/javase/downloads.

Eclipse is available at download.eclipse.org/eclipse/downloads and the CDT can be found at www.eclipse.org/cdt. Remember to install the Platform Runtime Binary. You may try Eclipse IDE for C/C++ Developers, which includes the CDT, but this version is not covered here.

TeraTerm can be downloaded at ttssh2.sourceforge.jp.

The last 3 items are available at our [[../download/|download page]].

Installation details can be found in the documents that come with the specific product.

Required Software (Ubuntu)

The following software needs to be installed on the Linux PC (tested with Ubuntu 10.10):

  • Java Runtime Environment 1.6 or later
  • Eclipse Platform Runtime Binary 3.7 (Helios)
  • Eclipse CDT 7.0.2
  • minicom or other Terminal Emulator
  • gcc-arm-elf
  • Nut/OS 4.10
  • Turtelizer OpenOCD Package

You can install the Java Runtime Environment, minicom and openocd with the following command: 

apt-get install default-jre minicom openocd

Eclipse is available at download.eclipse.org/eclipse/downloads and the CDT can be found at www.eclipse.org/cdt Remember to install the Platform Runtime Binary. You may try Eclipse IDE for C/C++ Developers, which includes the CDT, but this version is not covered here. Also the eclipse package of Ubuntu doesn't work.

Installation details can be found in the documents that come with the specific product.

Configuring Nut/OS

When using the latest YAGARTO distribution, you must be aware of a significant change. While earlier releases used arm-elf-gcc, YAGARTO is now using arm-none-eabi-gcc. While Nut/OS 4.10 should work with this environment out of the box, Nut/OS 4.9 has been prepared to make this switch easy. Open the file nut/Makevars.arm-gcc with your text editor. Locate the line 

#TRGT = arm-none-eabi-

and remove the leading numero sign: 

TRGT = arm-none-eabi-

Save your changes.

In order to include debugging information in the compiled binaries you need to switch from arm-gcc to arm-gccdbg. When done, rebuild Nut/OS and recreate the application directory. The following steps will give detailed instructions.

The screenshots were taken while running the wxWidgets version of the Nut/OS Configurator. In Nut/OS 4.10, this tool had been replaced by Qt based version. Thus, the images will slightly differ from your screen output.

[[ccd01.png|File:381px-ccd01.png]] When started for the first time, the Nut/OS Configurator will display a file selection dialog. If this is hidden by the splash window, simply click on that window to close it.


[[ccd02.png|File:381px-ccd02.png]] Select the file eir10c.cfg and click on Open.


[[ccd03.png|File:389px-ccd03.png]] The Configurators main window will show the Nut/OS Components in a tree structure on the right side.


[[ccd04.png|File:389px-ccd04.png]] From the Edit menu select Settings....


[[ccd05.png|File:208px-ccd05.png]] Nothing needs to be changed on the Repository page of the settings dialog. You may check Enable multiple configurations if you are concurrently working with different target boards.


[[ccd06.png|File:215px-ccd06.png]] Select arm-gccdbg as the platform on the Build page.


[[ccd07.png|File:215px-ccd07.png]] On the Tools page you need to enter the path to all required tools, separated by semicolons. For the EIR board this should point to the Nut/OS win32 tools directory and the YAGARTO bin directory. While all other settings use normal slashes in paths, here we must use backslashes. If you are using Linux and the compiler is in a standard path, you don't need to insert a path here.


[[ccd08.png|File:215px-ccd08.png]] On the last page titled Samples you may select arm-oocd as the programmer of choice, but this is only required for programming the flash memory, not for debugging in RAM.


[[ccd09.png|File:389px-ccd09.png]] Before building the system, change the Linker Script in the components tree under Tools/GCC Settings to at91sam7se512_ram.


[[ccd10.png|File:389px-ccd10.png]] We are using YAGARTO with Newlib 1.19. Make sure that Posix compatible unsetenv is checked under C runtime (target specific)/Environment.


[[Nut-OS_Configurator-Non-BSD.png|File:389px-Nut-OS Configurator-Non-BSD.png]] Under Linux you may need to disable Non-DSDL Code/RealNetworks RPSL/RCSL.


Nut/OS 4.9.10 contains 2 bugs, which let debugging in RAM fail for AT91SAM7SE targets. The first one is with the linker script at91sam7se512_ram.ld in directory nut\arch\arm\ldscripts. You can use a simple text editor like Notepad to fix this.

Near the beginning of the file remove the line . 

rom(rx)  : org = 0x00000000, len = 496k

and change the value 0x00200000 in line 

iram(rw) : org = 0x00200000, len = 32k

to 0x00000000, resulting in 

iram(rw) : org = 0x00000000, len = 32k

Somewhere in the middle you will find the line 

.data : AT (__etext)

which needs to be replaced by 

.data :

The second bug is in the file crtat91sam7se512_ram.S in directory nut\arch\arm\init. Again use your favorite text editor to remove the following part: 

/*
 * Remapping memory, SRAM to 0x00000000
 */
ldr     r1, =MC_BASE
mov     r0, #01
str     r0, [r1, #MC_RCR_OFF]

/*
 * Use 2 cycles for flash access.
 */
ldr     r1, =MC_BASE
mov     r0, #MC_FWS_2R3W
str     r0, [r1, #MC_FMR_OFF]

Then remove all lines starting from 

/*
 * The watchdog is enabled after processor reset. Disable it.
 */
ldr     r1, =WDT_BASE
ldr     r0, =WDT_WDDIS
str     r0, [r1, #WDT_MR_OFF] :

up to and including 

        /*
         * Switch to PLL clock.
         */
        ldr     r0, [r1, #PMC_MCKR_OFF]
        orr     r0, r0, #PMC_CSS_PLL_CLK
        str     r0, [r1, #PMC_MCKR_OFF]
wait_pllsel:
        ldr     r0, [r1, #PMC_SR_OFF]
        tst     r0, #PMC_MCKRDY
        beq     wait_pllsel

Finally remove this part: 

        /*
         * Relocate .data section (Copy from ROM to RAM).
         */
        ldr     r1, =__etext
        ldr     r2, =__data_start
        ldr     r3, =__data_end

_41:
        cmp     r2, r3
        ldrlo   r0, [r1], #4
        strlo   r0, [r2], #4
        blo     _41

Save your changes.


[[ccd11.png|File:389px-ccd11.png]] Now we are ready to build Nut/OS for debugging. Select Build Nut/OS in the Build menu.


[[ccd12.png|File:176px-ccd12.png]] A message box shows the settings for creating the build directory. Verify them and click OK to build this directory.


[[ccd13.png|File:183px-ccd13.png]] A second message box shows the settings for building the system. Again verify them and click OK.


[[ccd14.png|File:381px-ccd14.png]] The build may take a few minutes.


[[ccd15.png|File:389px-ccd15.png]] When done, make sure that it has been terminated successfully.


[[ccd16.png|File:389px-ccd16.png]] Nut/OS uses a separate directory for the application code. A template can be created by selecting Create Sample Directory, containing all Nut/OS samples that are included in the distribution. Remember, that we will use the events sample.


[[ccd17.png|File:214px-ccd17.png]] When runnign the wxWidget based Configurator, a message box will show the current settings. Click OK, if everything looks as expected.


[[ccd18.png|File:389px-ccd18.png]] When done, you may exit the Configurator by selecting Exit in the File menu.


[[ccd19.png|File:207px-ccd19.png]] Because we changed at least the linker script, the Configurator asks, whether to save these changes. In order to preserve the original settings, you may simply click No. Alternatively you can select Yes and choose a different filename like eir10c-debug.cfg in the following file selection dialog.


Configuring Eclipse

It is assumed that you successfully installed Eclipse and the CDT plug-in. For a first demonstration we will use the events sample that is included in the Nut/OS distribution.

[[scd01.png|File:330px-scd01.png]] When started, Eclipse will ask for the Workspace Path. Choose the Nut/OS sample directory, e.g. C:\Ethernut-4.10\nutapp or ~/ethernut-4.9.10/nutapp under Linux.


[[scd02.png|File:431px-scd02.png]] The welcome page appears. Click on Workbench in the upper right corner.


[[scd03.png|File:431px-scd03.png]] The so called Java Perspective appears. We will later change to the C Perspective.


[[scd04.png|File:431px-scd04.png]] In the File menu select New and Project....


[[scd05.png|File:278px-scd05.png]] In the New Project dialog choose C Project and click on Next.


[[scd06.png|File:278px-scd06.png]] In the C Project dialog enter events for the project name. Then choose Empty Project and -- Other Toolchain --. Again click on Next.


[[scd07.png|File:278px-scd07.png]] On the next page click on Advanced settings....


[[scd08.png|File:437px-scd08.png]] In the Project Properties page select Settings and check GNU Elf Parser. Then click on OK.


[[scd09.png|File:298px-scd09.png]] Back in the C Project dialog click Finish.


[[scd11.png|File:281px-scd11.png]] Click Yes to open the C/C++ perspective.


[[scd12.png|File:484px-scd12.png]] We do not need the Java Perspective, therefore you should close it.


[[scd13.png|File:441px-scd13.png]] Uncheck Build Automatically in the Project menu.


[[scd13.1.png|File:441px-scd13.1.png]] In the same menu select Properties.


[[scd13.2.png|File:524px-scd13.2.png]] In the Properties dialog select Environment in the tree on the right. Then click Add.


[[scd13.3.png|File:343px-scd13.3.png]] The variable Name must be PATH. You need to enter the path to all required tools as the Value, separated by semicolons. The first path should point to the Nut/OS win32 tools directory and the second one to the YAGARTO bin directory.


[[scd13.4.png|File:524px-scd13.4.png]] Click OK to store the updated Environment.


[[scd14.png|File:441px-scd14.png]] Then, in the same menu, select Build Project.


[[scd15.png|File:434px-scd15.png]] Building this simple application requires a few seconds only.


When done, the newly created files appear in the Project Explorer. The file events.elf contains the executable binary including all debug information.


Debugging the Application

[[scd16.png|File:451px-scd16.png]] Click on the Open Perspective button File:30px-b02.png and select Debug. This will open the Debug Perspective.


[[scd17.png|File:441px-scd17.png]] Click on the tiny arrow near the bug File:26px-b01.png in the toolbar to open the related menu. Then select Debug Configuration....


[[scd18.png|File:314px-scd18.png]] In the Debug Configurations dialog select GDB Hardware Debugging and click on the New button.


[[scd19.png|File:384px-scd19.png]] Enter EIR Debugging as the configuration name and events as the project name. Next click on Search Project....


[[scd20.png|File:195px-scd20.png]] Select events.elf and click OK.


[[scd22.png|File:357px-scd22.png]] Back in the Debug Configurations dialog click on Select other.


[[scd21.png|File:240px-scd21.png]] Choose Standard GDB Hardware Debugging Launcher as the preferred launcher and click OK.


[[scd21.1.png|File:402px-scd21.1.png]] Back in the Debug Configurations dialog click on the Debugger tab and enter arm-none-eabi-gdb in GDB Command. Although we will use remote target debugging, Use remote target must be unchecked here.


[[scd21.2.png|File:402px-scd21.2.png]] Now click on the Startup tab. Set breakpoint at and Resume must be checked. Enter NutInit as the breakpoint target.

Then copy and paste the following commands into the field Initialization Commands. 

target remote localhost:3333
monitor jtag_khz 30
monitor reset
monitor sleep 500
monitor poll
monitor soft_reset_halt
monitor gdb_breakpoint_override soft
monitor mww 0xfffff130 0xffffffff
monitor mww 0xfffff124 0xffffffff
monitor mww 0xfffffd44 0x00008000
monitor mww 0xffffff00 0x00000001
monitor mww 0xFFFFFC20 0x00000601
monitor sleep 10
monitor mww 0xFFFFFC2C 0x00481c0e
monitor sleep 10
monitor mww 0xFFFFFC30 0x00000004
monitor sleep 10
monitor mww 0xFFFFFC30 0x00000007
monitor sleep 10
monitor mww 0xfffff474 0x3f800000
monitor mww 0xfffff404 0x3f800000
monitor mww 0xfffff674 0x0003effd
monitor mww 0xfffff604 0x0003effd
monitor mww 0xfffff870 0x0000ffff
monitor mww 0xfffff804 0x0000ffff
monitor mww 0xffffff80 0x00000002
monitor mww 0xffffffb8 0x2192215a
monitor sleep 10
monitor mww 0xffffffb0 0x00000011
monitor mww 0x20000000 0x00000000
monitor mww 0xffffffb0 0x00000012
monitor mww 0x20000000 0x00000000
monitor mww 0xffffffb0 0x00000014
monitor mww 0x20000000 0x00000000
monitor mww 0xffffffb0 0x00000014
monitor mww 0x20000000 0x00000000
monitor mww 0xffffffb0 0x00000014
monitor mww 0x20000000 0x00000000
monitor mww 0xffffffb0 0x00000014
monitor mww 0x20000000 0x00000000
monitor mww 0xffffffb0 0x00000014
monitor mww 0x20000000 0x00000000
monitor mww 0xffffffb0 0x00000014
monitor mww 0x20000000 0x00000000
monitor mww 0xffffffb0 0x00000014
monitor mww 0x20000000 0x00000000
monitor mww 0xffffffb0 0x00000014
monitor mww 0x20000000 0x00000000
monitor mww 0xffffffb0 0x00000013
monitor mww 0x20000014 0xcafedede
monitor mww 0xffffffb4 0x00000013
monitor mww 0xffffffb0 0x00000010
monitor mww 0x20000000 0x00000180
monitor jtag_khz 12000
set mem inaccessible-by-default off


[[scd22.1.png|File:357px-scd22.1.png]] Finally click Apply to store the settings and Close to close the dialog.


[[scd23.png|File:441px-scd23.png]] Once again click on the tiny arrow near the bug to open the menu and select Organize Favorites....


[[scd24.png|File:190px-scd24.png]] Click Add.


[[scd25.png|File:170px-scd25.png]] Check EIR Debugging and click OK.


[[scd26.png|File:190px-scd26.png]] In the previous dialog click OK again.


We will now setup the hardware, using the following steps:

  • Connect the Turtelizer's JTAG port to the JTAG Connector board's 10-pin connector.
  • Connect the JTAG port of the EIR to the JTAG Connector board's 20-pin connector.
  • Attach the power supply to the EIR and switch it on. The red LED on the EIR should go on.
  • Connect the Turtelizer's USB port to the PC using the USB A/B cable.

[[EIR-JTAG-TURT.png|File:480px-EIR-JTAG-TURT.png]] If the Turtelizer is used for the first time, it will be required to install the FTDI driver. For more details please refer to the Turtelizer's documentation.


Next we will start OpenOCD. We could do this within Eclipse, but for the first time it makes sense to start it manually to check the output in case of problems.

[[scd26.1.png|File:438px-scd26.1.png]] Now open a command line and change to directory C:\Ethernut-4.10\nut\tools\turtelizer2. Add the Nut/OS tools directory for Windows to your path, using the following command 

set PATH=C:\ethernut-4.10\nut\tools\win32;%PATH%

Yout don't need to set the path under Linux. Then start OpenOCD using 

openocd -f board/eir.cfg -f interface/turtelizer2.cfg


[[scd27.2.png|File:250px-scd27.2.png]] The events sample will create some output on the RS-232. To make it visible, we start a terminal emulator. On Windows PCs we could use HyperTerminal, but TeraTerm is the preferred one. After TeraTerm started, select Serial port... from the Setup menu.


[[scd27.1.png|File:213px-scd27.1.png]] Select the COM port to which the Ethernut board is connected. Configure the port to 8 data bits, no parity, 1 stop bit and no flow control and click on OK.


[[Bildschirmfoto-Terminal-minicom.png|File:300px-Bildschirmfoto-Terminal-minicom.png]] Under Linux you can use the following command on a terminal to start minicom: 

minicom -D /dev/ttyUSB0 -b 115200

You need to replace /dev/ttyUSB0 with the correct device.


Let's get back to Eclipse. Remember that we specified a breakpoint at NutInit in the debugger configuration. For some unknown reason the debugger fails, if this is not defined. However, the function NutInit is located in the initialization of Nut/OS, while you will be mostly interested in debugging your application code.

[[scd26.2.png|File:441px-scd26.2.png]] Lets specify a second breakpoint at the beginning of the application code, which is the function main. Click on the tab C/C++ in the upper right corner to change to the C Perspective.

In the Project Explorer double click on the events folder to expand it. Then click on the tiny arrow in front of events.c to expand this part of the tree. Note, that this arrow will appear only when moving the mouse over the Project Explorer window.

Now double click on main(void) to open the source file at this location.


[[scd26.3.png|File:441px-scd26.3.png]] At the first line click with the right mouse button on blue border to open the context menu. Select Toggle Breakpoint.


[[scd27.png|File:441px-scd27.png]] Switch back to the debug perspective by clicking on the tab Debug in the upper right corner. Click on the bug button in the toolbar to start debugging.


[[scd28.png|File:441px-scd28.png]] The code will be downloaded to the target and started. Then it stops at the first breakpoint at the beginning of NutInit. Press F8 or click the Resume button File:30px-b03.png.


[[scd29.png|File:441px-scd29.png]] The target code will run up to the next breakpoint in main. You can now press F5 or click the button File:30px-b04.png to step execute a single line, F6 or click the button File:30px-b05.png to step over a function call.


[[scd29.2.png|File:439px-scd29.2.png]] Now continue pressing F6 until we stepped over the first puts() function call.


[[scd29.1.png|File:226px-scd29.1.png]] When this statement has been executed, the text Nut/OS Event Queue Demo should appear in the terminal emulator window.


[[scd29.4.png|File:439px-scd29.4.png]] As you continue stepping through the main loop...


[[scd29.3.png|File:226px-scd29.3.png]] ...additional output appears on the serial port.


You may set additional breakpoints, evaluate variables or memory areas and do many other useful things during debugging. Please refer to the Eclipse documentation for further details.

Under Linux an Error occures in the output of openocd, when debugging: 

Error: address + size wrapped(0xfffffffe, 0x00000004)
Retrieved from "http://www.ethernut.de/nutwiki/index.php?title=Hardware/EIR/Debugging&oldid=388"