Harald: Created page with "
= Elektor Internet Radio Source Code Debugging = This document explains how to setup Eclipse and [http://openocd.sourceforge.net/ OpenOCD] to allow source..."

2017-07-13T08:57:12Z

Created page with "<div id="content"> = Elektor Internet Radio Source Code Debugging = This document explains how to setup Eclipse and [http://openocd.sourceforge.net/ OpenOCD] to allow source..."

New page

<div id="content">

= Elektor Internet Radio Source Code Debugging =

This document explains how to setup Eclipse and [http://openocd.sourceforge.net/ 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 [http://www.ethernut.de/nutwiki/Sending_syslog_Messages 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 [http://www.egnite.de/en/egnite-shop.html www.egnite.de/en/egnite-shop.html] and from several [http://www.egnite.de/en/ueber-uns/distributoren.html 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 [http://www.oracle.com/technetwork/java/javase/downloads/ www.oracle.com/technetwork/java/javase/downloads].

Eclipse is available at [http://download.eclipse.org/eclipse/downloads/ download.eclipse.org/eclipse/downloads] and the CDT can be found at [http://www.eclipse.org/cdt/ 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 [http://ttssh2.sourceforge.jp/ 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:

<pre class="coding">apt-get install default-jre minicom openocd</pre>
Eclipse is available at [http://download.eclipse.org/eclipse/downloads/ download.eclipse.org/eclipse/downloads] and the CDT can be found at [http://www.eclipse.org/cdt/ 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

<pre class="coding">#TRGT = arm-none-eabi-</pre>
and remove the leading numero sign:

<pre class="coding">TRGT = arm-none-eabi-</pre>
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 .

<pre class="coding">rom(rx) : org = 0x00000000, len = 496k</pre>
and change the value 0x00200000 in line

<pre class="coding">iram(rw) : org = 0x00200000, len = 32k</pre>
to 0x00000000, resulting in

<pre class="coding">iram(rw) : org = 0x00000000, len = 32k</pre>
Somewhere in the middle you will find the line

<pre class="coding">.data : AT (__etext)</pre>
which needs to be replaced by

<pre class="coding">.data :</pre>
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:

<pre class="coding">/*
* 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]</pre>
Then remove all lines starting from

<pre class="coding">/*
* The watchdog is enabled after processor reset. Disable it.
*/
ldr r1, =WDT_BASE
ldr r0, =WDT_WDDIS
str r0, [r1, #WDT_MR_OFF] :</pre>
up to and including

<pre class="coding"> /*
* 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</pre>
Finally remove this part:

<pre class="coding"> /*
* 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</pre>
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 <code>PATH</code>. 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 <code>EIR Debugging</code> as the configuration name and <code>events</code> 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 <code>arm-none-eabi-gdb</code> 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 <code>NutInit</code> as the breakpoint target.

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

<pre class="coding">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</pre>
 
[[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 <code>C:\Ethernut-4.10\nut\tools\turtelizer2</code>. Add the Nut/OS tools directory for Windows to your path, using the following command

<pre class="coding">set PATH=C:\ethernut-4.10\nut\tools\win32;%PATH%</pre>
Yout don't need to set the path under Linux. Then start OpenOCD using

<pre class="coding">openocd -f board/eir.cfg -f interface/turtelizer2.cfg</pre>
 
[[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:

<pre class="coding">minicom -D /dev/ttyUSB0 -b 115200</pre>
You need to replace /dev/ttyUSB0 with the correct device.

 

Let's get back to ''Eclipse''. Remember that we specified a breakpoint at <code>NutInit</code> 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 <code>puts()</code> function call.

 
[[scd29.1.png|[[File:226px-scd29.1.png]]]]
When this statement has been executed, the text <code>Nut/OS Event Queue Demo</code> 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:

<pre class="coding">Error: address + size wrapped(0xfffffffe, 0x00000004)</pre>

</div>

Hardware/EIR/Debugging - Revision history

Harald: Created page with " = Elektor Internet Radio Source Code Debugging = This document explains how to setup Eclipse and [http://openocd.sourceforge.net/ OpenOCD] to allow source..."

Harald: Created page with "
= Elektor Internet Radio Source Code Debugging = This document explains how to setup Eclipse and [http://openocd.sourceforge.net/ OpenOCD] to allow source..."