YAGARTO - Yet another GNU ARM toolchain

SAM-ICE / J-Link

Additional information

Trouble shooting

Support

Back

Introduction

This is a small tutorial which shows you how to debug your application with Eclipse or Insight using SAM-ICE or J-Link for the JTAG interface.

It is highly recommended that you installed the YAGARTO Tools and read
part 2 and part 3 of the YAGARTO tutorial. Furthermore YAGARTO and Eclipse must be installed (Some more information in the next section).

The tutorials from part 2 and part 3 use OpenOCD for the JTAG interface, but here we will use a SAM-ICE / J-Link. OpenOCD can not be used with SAM-ICE / J-Link.

What is SAM-ICE?

SAM-ICE is a JTAG emulator, developed by SEGGER and designed for Atmel AT91 ARM cores. It connects via USB to a PC running Microsoft Windows2000 or XP. SAM-ICE has a built-in 20-pin JTAG connector, which is compatible with the standard 20-pin connector defined by ARM.

Note: SAM-ICE can only be used with Atmel devices, but comes with a free GDB Server license.

What is J-Link?

J-Link is a JTAG emulator like the SAM-ICE too, developed by SEGGER and designed for any ARM7/ARM9 core.It comes with Cortex M3 support.

If you need more general information about the
J-Link, take a look at the J-Link page.

The J-Link software 3.66a and above comes with a free
GDB Server for non-commercial purposes. This GDB server is limited to 32KBytes download size.

SEGGER offers now a non-commercial-use package of J-Link (J-Link NCU), which is available at a discounted price for everybody who does not use the software to develop a product for sale. The offer includes free use of the GDB Server, Flash download and Flash breakpoints. The only limitation is that it may not be used to develop a product. More information about the NCU version of the J-Link can be found here.

^ top

Download and install

For a complete C/C++ development system we need the following components:

J-Link "Software and documention pack"
YAGARTO Tools (like make, sh, rm, cp and mkdir)
YAGARTO (native GNU ARM toolchain for windows)
Integrated Development Environment (Eclipse + Zylin plugin)

1. J-Link "Software and documention pack":

The SAM-ICE / J-Link is developed by SEGGER, therefore you can download the latest software from the SEGGER J-Link ARM software page.

Download the "Software and documentation pack", expand the zip file, and start the setup program. For more information about how to install and setup the SAM-ICE itself, take a look in the SAM-ICE User Guide (pdf, 440 KB), which can be found at the Atmel Site or at the following SEGGER page.

If you already installed the YAGARTO Tools, YAGARTO and IDE from the front page, you can go to the next section.

2. YAGARTO Tools:

If you do not have the utilities like make, sh, rm, cp and mkdir, I recomended to use these tools from the latest YAGARTO Tools installer, which can be found at the front page.

Start the installer, at the "Choose Components" page you can accept the defaults:

Press the "Next >" button and follow the instruction of the installer.

3. YAGARTO:

If you did not already install the YAGARTO toolchain, you can download the installer from the front page.

Start the installer, at the "Choose Components" page you can accept the defaults:

Press the "Next >" button and follow the instruction of the installer.

4. Integrated Development Environment:

If you did not already install the Integrated Development Environment, we will do it here. Only download, and do not install these files yet, I assumed you will download the files in your temp directory (c:\temp). We will install these files later.

First we will check if the JRE is already installed on your PC. Therefore open a command prompt and type:

C:\>java -version

The result should look like:

java version "1.5.0_07"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_07-b03)
Java HotSpot(TM) Client VM (build 1.5.0_07-b03, mixed mode, sharing)

(Note: The Zylin plugin does not work with java 1.4.2)

If the Java Runtime Environment (JRE) is not installed on your PC, you can download the JRE from the following Sun website:

Java SE Downloads (about 16 MB)

Here you will find the "JRE 5.0 Update 7" (that was the current version when I created this tutorial). Download the JRE and save it in the temp directory.

Now you need the Eclipse CDT and the Zylin plugin too.

Zylin made some modifications in Eclipse CDT for Windows and created a plugin to improve the support for GDB embedded debugging in CDT.

The Eclipse Platform Runtime Binary, the Eclipse CDT and the GDB embedded plugin are included in the installer (Integrated Development Environment), which you can find at the front page too.

At this point the following files should be downloaded in your temp directory:

1.		jre-1_5_0_07-windows-i586-p.exe
2.		yagarto-ide-20061002-setup.exe

Let's start with the JRE (1). If the JRE was not installed on your PC, start the installer and follow the instructions. After the JRE installation start the install program for the IDE (2) and follow the instruction.

^ top

Hardware

For the SAM7X256 project the following hardware was used:

This is a AT91SAM7X-EK development board from Atmel, which is equipped with an AT91SAM7X256 cpu.

For the STM3210E project the following hardware was used:

This is a STM3210E-EVAL development board from STMicroelectronics, which is equipped with a STM32F103ZE cpu.

^ top

Example projects

Here I will show you, how to compile your first program. These examples was tested with JLinkARM v3.88 and can be used to debug in RAM and ROM:

SAM7X256Test for a AT91SAM7X-EK board

SAM7S256Test for a SAM7S256 board

Ethernut3Test for an Ethernut3 board

EIRTest for an ELEKTOR Internet Radio board

LPC2148Test for a LPC2148 board

LPC2294Test for a LPC2294 board

STR7Test for a STR710 board

STM3210ETest for a STM3210E-EVAL board
(J-Link software v4.04 and YAGARTO-20090329 or above is needed)

The SAM-ICE can only be used for an Atmel device. For the other one an
original J-Link is needed.

Download the example you need and expand the zip file to your working directory.

I will show you the next steps with the SAM7X256Test example, and expanded it in the following directory:

D:\projekte\ARM\SAM7X256Test

This directory is only an example, choose what is the best for you. For the next steps I will use this directory.

Open a command prompt and change in the D:\projekte\ARM\SAM7X256Test directory. First you must clean the project, therefore type:

D:\Projekte\ARM\SAM7X256Test>make clean

The result should look like:

rm -f ./src/crt.o ./src/main.o
rm -f test.elf
rm -f test.map
rm -f test.hex
rm -f ./src/main.c.bak
rm -f ./src/main.lst
rm -f ./src/crt.s.bak
rm -f ./src/crt.lst
rm -fR .dep

All list and object files are deleted, now we want to compile the program, type:

D:\Projekte\ARM\SAM7X256Test>make all

The output should look like:

arm-elf-gcc -x assembler-with-cpp -c -mcpu=arm7tdmi -g -gdwarf-2 -Wa,-amhls=src/
crt.lst src/crt.s -o src/crt.o
arm-elf-gcc -c -mcpu=arm7tdmi -O0 -gdwarf-2 -mthumb-interwork -fomit-frame-point
er -Wall -Wstrict-prototypes -fverbose-asm -Wa,-ahlms=src/main.lst -MD -MP -MF
.dep/main.o.d -I . -I./inc src/main.c -o src/main.o
arm-elf-gcc ./src/crt.o ./src/main.o -mcpu=arm7tdmi -nostartfiles -T./prj/at91sa
m7s256_ram.ld -Wl,-Map=test.map,--cref,--no-warn-mismatch -o test.elf
arm-elf-objcopy -O ihex test.elf test.hex

A file test.elf should now be created in your build directory. If you could find it, congratulations! You have compiled your first ARM program with the new toolchain.

Now we want to start the JLinkGDBServer.

^ top

GDB Server

The GNU Project Debugger (GDB) is a freely available debugger, distributed under the terms of the GPL. It connects to an emulator via a TCP/IP connection. It can connect to every emulator for which a GDB Server software is available.

For debuging with Insight or Eclipse we will use the GDB, therefore we need a GDB Server too.

At this point you must install the J-Link "Software and documention pack". Connect the SAM-ICE / J-Link to the PC and to the target (do not forget to power the target) and start the JLinkGDBServer.

You will find the JLinkGDBServer in the "SEGGER \ J-Link ARM" program goup.
When the GDB Server will be started you should see the following window:

Remove the checkmark of the "Stay on top" option. Then set the checkmark at "Show log window", "Cache reads" and "Init regs on start". The DGB Server window will now look like:

The "Show log window" options can help us if we will get in trouble with Insight or Eclipse.
"Cache reads" will enable a memory read-ahead optimization which can speed up debugging. If you have a big screen resolution you can let the checkmark at "Stay on top", but we need all the available screen space for the next step. Debugging with Insight.

^ top

Insight

Debugging with Insight will only be supported if you had installed a YAGARTO version which support it. Only an installer which contains the part _gi- will support debugging with Insight.

Example:

yagarto-bu-2.19.1_gcc-4.4.2-c-c++_nl-1.17.0_gi-6.8.50_20091018.exe
yagarto-bu-2.20_gcc-4.4.2-c-c++_nl-1.18.0_gdb-7.0.1_20091223.exe

Version #1 will support debugging with Insight and Eclipse, but version #2 will support debugging with Eclipse only. If you have installed an Eclipse only version, you can go to the Eclipse chapter.

Now we can start debugging with Insight. The J-Link GDB Server must be running and be connected to the J-LIink and the target, before you start Insight.

Open a command prompt and change in the D:\projekte\ARM\SAM7X256Test directory, this is the directory where I expanded my example. Then compile the project with:

D:\Projekte\ARM\SAM7X256Test>make all

This should create a file "test_arm.elf". Now we want to use that command prompt for the
Insight debugger.

For this purpose I created a batch file "dram_jlink.bat" (debug in RAM) to start Insigt. Run this batch file now (Insight will be started).

Now you can start debugging using the following button:

from inside the debugger. The result should be the next window:

Press "YES" in the dialog above. The "Target Selection" window will be opened, configure the settings as shown in the following picture:

(Click inside the picture to expand)

Set the Port to 2331. This is the default of the JLinkGDBServer. Finish this dialog with the "OK" button, Insight will now load the program and you can start debugging.

A debug session may look like:

(Click inside the picture to expand)

If you need more information about Insight in general, take a look here.

Now it is time for a break, and you can play with your new toy. If you like to know how to use Eclipse, take a look to the next section.

Note: Do not close the GDB Server before Insight, you will get in trouble!

^ top

Eclipse

Lets try to debug with Eclipse. The J-Link GDB Server must be running and be connected to the J-LIink and the target, before you start the debug sesion. It is best to start the GDB Server before you start Eclipse.

Here I use the fast way, and do not demonstrate step by step. The detailed tutorial how to use Eclipse and how to setup a project can be found in part3. If you are not very familiar with Eclipse, take a look at part3 too.

Download the SAM7X256Test project and expand the zip file to your temp directory.
I expanded it in the following directory:

C:\temp\sam7x256

For the next steps I will refer to it. Now you can start Eclipse.

To create an Eclipse project use "File / New / Standard Make C Project". For the project name use "sam7x256".

Now use "Project / Properties" select "C/C++ Make Project" and change the "Compiler invocation command", on the "Discovery Options" tab, to your compiler executable arm-elf-gcc.exe. Press "OK" to finish this dialog.

Your project is empty, and you must import the project files to Eclipse.
Use the "File / Import..." menu and select the "File System" as input source. You will find the "File System" under "General".

Browse to your temp directory C:\temp\sam7x256 and select all files with the checkmark, press "Finish" to close the dialog.

For more information on how to create a project, take a look at part3.

You can build your project with "Project / Build Project" now, the result of the build process will be displayed in the "Console" window. A file "test.elf" should be created.

Change to the "Debug Perspective" and configure the debugger.

(Click inside the picture to expand)

Select the "Debugger" tab and use the "Browse..." button to set the "GDB debugger".

For the debugger "Commands" copy and paste the content of the eclipse_ram_jlink.gdb text file into the window. The eclipse_jlink_ram.gdb file is part of the example (.\prj\eclispe_ram_jlink.gdb).

For more information on how to configure the debugger, take a look at part3.

The debugger is configured, and the GDB Server is hopefully running. You may start your debug session now, which could look like:

(Click inside the picture to expand)

^ top

Additional information

An other very detailed tutorial by Jim Lynch "Using Open Source Tools for AT91SAM7S Cross Development, Revision 2" which based on YAGARTO can be found at the Atmel web site (tutorial + sample projects, 6MB).

SEGGER supports students too, a student discount of 50% is available (Proof of Inscription required).

^ top

Trouble shooting

In case Eclipse refuse to download the code to the target (seems like something is blocked), take the following steps: