SAM-ICE / J-Link
  Introduction
  Download and install
  Hardware
  Example project
  GDB Server
  Eclipse
  Additional information
  Trouble shooting
  Support
  Back


Introduction

This is a small tutorial which shows you how to debug your application with Eclipse using SAM-ICE, J-Link or a J-LInk EDU 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).

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.

What is J-Link EDU?

SEGGER offers now a new package for educational pupose, 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 EDU 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:

  1. J-Link "Software and documention pack"
  2. YAGARTO Tools (like make, sh, rm, cp and mkdir)
  3. YAGARTO (native GNU ARM toolchain for windows)
  4. Integrated Development Environment (Eclipse + Eclipse CDT)

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:

More information about the Integrated Development Enviroment and how to install can be found in this desction here.

^ 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 v4.10i and can be used to debug in RAM and ROM.

The SAM-ICE can only be used for an Atmel device. For the other one an
original J-Link / J-Link EDU 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-none-eabi-gcc -x assembler-with-cpp -c -mcpu=arm7tdmi -g -gdwarf-2 -Wa,-amhl
s=src/startup.lst src/startup.s -o src/startup.o
arm-none-eabi-gcc -c -mcpu=arm7tdmi -O0 -gdwarf-2 -mthumb-interwork -fomit-frame
-pointer -Wall -Wstrict-prototypes -fverbose-asm -Wa,-ahlms=src/low_level_init.l
st -MD -MP -MF .dep/low_level_init.o.d -I . -I./inc src/low_level_init.c -o sr
c/low_level_init.o
arm-none-eabi-gcc -c -mcpu=arm7tdmi -O0 -gdwarf-2 -mthumb-interwork -fomit-frame
-pointer -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-none-eabi-gcc ./src/startup.o ./src/low_level_init.o ./src/main.o -mcpu=arm7
tdmi -nostartfiles -T./prj/sam7x256_ram.ld -Wl,-Map=test_ram.map,--cref,--no-war
n-mismatch -o test_ram.elf
arm-none-eabi-objcopy -O ihex test_ram.elf test_ram.hex
arm-none-eabi-gcc ./src/startup.o ./src/low_level_init.o ./src/main.o -mcpu=arm7
tdmi -nostartfiles -T./prj/sam7x256_rom.ld -Wl,-Map=test_rom.map,--cref,--no-war
n-mismatch -o test_rom.elf
arm-none-eabi-objcopy -O ihex test_rom.elf test_rom.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 J-Link GDB Server.

^ 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 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 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 Eclipse.

^ 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-none-eabi-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 arm-none-eabi-gdb for 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:

  1. Close Eclipse
  2. Reset the target
  3. Start Eclipse again

Now debugging should be possible.

^ top  

Support

If you need support, take a look here:

^ top  


Creative Commons-Lizenz The tutorial on this site is licensed under a Creative Commons Attribution 2.5 License and is copyright (C) 2007 by me, Michael Fischer.