gnu-based software development on at91sam...

31
GNU-Based Software Development on AT91SAM Microcontrollers 1. Introduction Most development solutions used today in the ARM ® world are commercial packages, such as IAR ® EWARM or ARM ® RealView ® . Indeed, they integrate all the tools required for embedded software programming and are well-supported. Recently how- ever, open-source solutions like the GNU toolchain have become much more competitive. But, conversely to commercial offers, they lack a full-fledged and easy to use package for the end user. The goal of the present document is to solve this issue by providing a step-by-step guide for setting up a working GNU-based environment targeted at the Atmel AT91 microcontroller family. It will offer the following features: Compilation and building of projects using the GNU compiler toolchain Debugging using the Atmel SAM-ICE emulator and SEGGER GDB-server Memory programming using SAM-BA , Atmel In-Situ Programming (ISP) tool Integration of those tasks in an Eclipse -based development environment In addition, use of this toolchain will be demonstrated using an existing project for Atmel AT91 microcontrollers. Covered topics include importing the project, compiling it, debugging it and flashing it in the microcontroller memory. 2. References Atmel, Getting Started with AT91SAM7S Microcontrollers, lit° 6293. Atmel SAM Boot Assistant (SAM-BA™) User Guide, lit° 6132. 3. Components Several different packages have to be combined in order to obtain a fully-featured system which can be compared with commercial offers. This section describes each component of the GNU environment about to be setup. 3.1 SAM-ICE Atmel SAM-ICE is a JTAG emulator designed for all Atmel AT91 microcontrollers. Its features include: Support for all Atmel AT91 ARM7 /ARM9 based microcontrollers No power supply required, powered through USB Maximum JTAG speed 8 MHz Auto speed recognition Support for multiple devices Fully plug and play compatible Standard 20-pin JTAG connector Support for adaptable clocking AT91 ARM Thumb Microcontrollers Application Note 6310A–ATARM–26-Mar-07

Upload: buiminh

Post on 23-Apr-2018

230 views

Category:

Documents


2 download

TRANSCRIPT

Page 1: GNU-Based Software Development on AT91SAM Microcontrollersww1.microchip.com/downloads/en/AppNotes/doc6310.pdf · GNU-Based Software Development on AT91SAM Microcontrollers 1. Introduction

AT91 ARM Thumb Microcontrollers

Application Note

6310A–ATARM–26-Mar-07

GNU-Based Software Development on AT91SAM Microcontrollers

1. IntroductionMost development solutions used today in the ARM® world are commercial packages, such as IAR® EWARM or ARM®RealView®. Indeed, they integrate all the tools required for embedded software programming and are well-supported. Recently how-ever, open-source solutions like the GNU toolchain have become much more competitive. But, conversely to commercial offers, they lack a full-fledged and easy to use package for the end user.

The goal of the present document is to solve this issue by providing a step-by-step guide for setting up a working GNU-based environment targeted at the Atmel AT91 microcontroller family. It will offer the following features:

• Compilation and building of projects using the GNU compiler toolchain

• Debugging using the Atmel SAM-ICE™ emulator and SEGGER GDB-server

• Memory programming using SAM-BA™, Atmel In-Situ Programming (ISP) tool

• Integration of those tasks in an Eclipse™-based development environment

In addition, use of this toolchain will be demonstrated using an existing project for Atmel AT91 microcontrollers. Covered topics include importing the project, compiling it, debugging it and flashing it in the microcontroller memory.

2. ReferencesAtmel, Getting Started with AT91SAM7S Microcontrollers, lit° 6293.

Atmel SAM Boot Assistant (SAM-BA™) User Guide, lit° 6132.

3. ComponentsSeveral different packages have to be combined in order to obtain a fully-featured system which can be compared with commercial offers. This section describes each component of the GNU environment about to be setup.

3.1 SAM-ICEAtmel SAM-ICE is a JTAG emulator designed for all Atmel AT91 microcontrollers. Its features include:

• Support for all Atmel AT91 ARM7™/ARM9™ based microcontrollers

• No power supply required, powered through USB

• Maximum JTAG speed 8 MHz

• Auto speed recognition

• Support for multiple devices

• Fully plug and play compatible

• Standard 20-pin JTAG connector

• Support for adaptable clocking

Page 2: GNU-Based Software Development on AT91SAM Microcontrollersww1.microchip.com/downloads/en/AppNotes/doc6310.pdf · GNU-Based Software Development on AT91SAM Microcontrollers 1. Introduction

Figure 3-1. Atmel SAM-ICE Emulator for AT91 Microcontrollers

3.2 SAM-BA™

SAM-BA (Boot Assistant) is one of the tools provided in Atmel AT91 In-System Programming (ISP) solution. It provides an easy way for programming AT91 family microcontrollers using a graphical or command-line interface.

It is also possible to create powerful scripts which can then be run via the command line, enabling the automation of many tasks. Those scripts can be hand written by the programmer or recorded through the graphical interface.

Figure 3-2. SAM-BA Main Window

3.3 Eclipse™

Eclipse is an open-source Integrated Development Environment (IDE) originally targeted at Java® programming. However, thanks to its modularity, multiple plug-ins have been developed to enable C/C++ programming & debugging, or to integrate version control systems (such as CVS and SVN).

26310A–ATARM–26-Mar-07

Application Note

Page 3: GNU-Based Software Development on AT91SAM Microcontrollersww1.microchip.com/downloads/en/AppNotes/doc6310.pdf · GNU-Based Software Development on AT91SAM Microcontrollers 1. Introduction

Application Note

In addition, since Eclipse is itself based on a Java architecture, it can be used on any operating system on which a Java Runtime Environment (JRE) exists. It thus provide a solid solution for companies working with several different platforms, e.g. Linux® and Microsoft Windows®.

Figure 3-3. Screenshot of Eclipse Main Window

More details about Eclipse can be found on the project web site at http://www.eclipse.org.

3.4 YAGARTOYAGARTO (Yet Another GNU ARM Toolchain) is an implementation of the GNU ARM toolchain. Among other utilities, it includes a C/C++ compiler (gcc/g++), an assembler (as), a linker (ld) and a debugger (gdb).

Compared to other GNU ARM-based toolchains, YAGARTO has the advantage of being com-piled natively for Windows. Most other implementations use a porting of several Unix® layers (like Cygwin or MinGW), which is less convenient than having a binary dedicated to Windows®.

Finally, special care has been taken to ensure that all the tools provided by YAGARTO are fully compatible with Eclipse. This makes up another reason for choosing this particular toolchain over others.

For more information about YAGARTO and GNU tools, please refer to http://www.yagarto.deand http://www.gnu.org.

36310A–ATARM–26-Mar-07

Page 4: GNU-Based Software Development on AT91SAM Microcontrollersww1.microchip.com/downloads/en/AppNotes/doc6310.pdf · GNU-Based Software Development on AT91SAM Microcontrollers 1. Introduction

3.5 MakeMost GNU-based projects (including Atmel software examples) use the make utility to manage their building process. It tells the compiler(s) and linker(s) which files must be compiled or linked and how they should be, according to a set of rules written by the programmer in a makefile. The advantage is that any tool chain can be used with make, thus rendering projects built using makefiles more portable.

Since the YAGARTO toolchain does not provide make, another package must be installed to get it. The GnuWin32 project (http://gnuwin32.sourceforge.net/) provides native ports of GNU tools for Windows, this includes make.

The GNU manual gives more information about make and makefiles. It can be found at http://www.gnu.org/software/make/manual/make.html. To find out about the other tools provided by GnuWin32, please refer to http://gnuwin32.sourceforge.net/packages.html.

3.6 GDB ServerThe GDB Server utility developed by SEGGER enables the GNU GDB debugger to connect remotely to an ARM microcontroller through a JLink-compatible device. In addition, since it cre-ates a TCP/IP server on the local network, any connected computer can debug the target.

Figure 3-4. GDB Server Main Window

GDB Server is a commercial package; however, Atmel has acquired the licence for its SAM-ICE emulator. Thus, it can be used without restriction when using a SAM-ICE probe and an AT91 microcontroller.

More information about GDB Server can be found by visiting the following website: http://www.segger.com/jlink_gdb.html.

4. Installation

4.1 SAM-BA™

4.1.1 Getting SAM-BASince SAM-BA is part of the Atmel ISP solution, the whole package must be downloaded and installed. The latest version of ISP is available on the Atmel web site, at the following address: http://www.Atmel.com/dyn/products/tools_card.asp?tool_id=3883.

46310A–ATARM–26-Mar-07

Application Note

Page 5: GNU-Based Software Development on AT91SAM Microcontrollersww1.microchip.com/downloads/en/AppNotes/doc6310.pdf · GNU-Based Software Development on AT91SAM Microcontrollers 1. Introduction

Application Note

4.1.2 Installing SAM-BAThe Atmel ISP package is provided as a self-installing executable file named “Install AT91-ISP vX.Y.exe“ (X.Y is the version number). Double-clicking on this file starts the installation process by displaying the following screen:

Figure 4-1. AT91 ISP Installation Splash Screen

The installation steps are very straightforward. Note that if there already is a version of ISP on the system, it will have to be uninstalled (this case is automatically detected by the setup program).

Once the wizard is finished, SAM-BA will be available in the startup menu under:

Start Menu > Programs > Atmel Corporation > AT91 ISP vX.Y > SAM-BA vX’.Y’.exe

4.2 YAGARTO

4.2.1 Getting YAGARTOThe YAGARTO home page, http://www.yagarto.de offers three binary packages for download: an open On-Chip Debugger (OCD), the GNU ARM toolchain and an Integrated Development Environment. For this section, the package to download and install is the second one (“YAGARTO GNU ARM toolchain”).

4.2.2 Installing YAGARTOThe installer for YAGARTO is an executable file. Launching it brings the following dialog:

Figure 4-2. YAGARTO Installer Main Window

56310A–ATARM–26-Mar-07

Page 6: GNU-Based Software Development on AT91SAM Microcontrollersww1.microchip.com/downloads/en/AppNotes/doc6310.pdf · GNU-Based Software Development on AT91SAM Microcontrollers 1. Introduction

The first steps are the standard “Welcome” and “User agreement” dialogs. At some point, the installer will ask which components to install. By default, they are all checked; do not uncheck any component as they are all required.

Figure 4-3. Components Window

The rest of the installation process is trivial: click “Next >” until the final “Installation complete” dialog appears.

YAGARTO tools should now be available from the command line. If you wish to test if this is the case, do the following:

• Click on the start menu

• Select “Run...”

• Enter “cmd” and click on Ok

• A shell window should appear, type “arm-elf-gcc”

• If the installation went correctly, this message should be displayed:

arm-elf-gcc: no input files

Figure 4-4. Shell Window with Working arm-elf-gcc Command

4.3 EclipseAs Eclipse was primarily designed with Java development in mind, several extensions are required for embedded C/C++ integration. However, installing each component separately can quickly become tedious.

A package available on the YAGARTO web site offers a fully-functional Eclipse-based C/C++ environment. It makes it easier to deploy a working system, so this is what is described in the fol-lowing two subsections.

4.3.1 Getting EclipseThe YAGARTO version of Eclipse (named YAGARTO IDE) can be found on the web site (http://www.yagarto.de) home page. The file to download is named “Integrated Development Environment”.

66310A–ATARM–26-Mar-07

Application Note

Page 7: GNU-Based Software Development on AT91SAM Microcontrollersww1.microchip.com/downloads/en/AppNotes/doc6310.pdf · GNU-Based Software Development on AT91SAM Microcontrollers 1. Introduction

Application Note

Eclipse requires the Java Runtime Environment (JRE). Most computers already have JRE installed. If not, it can be downloaded from http://www.java.com.

4.3.2 Installing EclipseOnce again, the installer provided by YAGARTO is an .exe file, which launches a setup program when double-clicked:

Figure 4-5. YAGARTO IDE Installer Main Window

There is no option to specify to the installer, simply click the “Next >” button until the install pro-cess is finished.

4.4 Make

4.4.1 Getting MakeThe website of the GnuWin32 projects provides a download for each package they offer. Simply go to the “Packages” section of the site and browse to Make. Click on the “Setup” link on the right to start downloading the package.

4.4.2 Installing MakeThe file retrieved from the GnuWin32 web page is an .exe installer. When launched, it displays the following window:

Figure 4-6. GnuWin32 Make Install Window

76310A–ATARM–26-Mar-07

Page 8: GNU-Based Software Development on AT91SAM Microcontrollersww1.microchip.com/downloads/en/AppNotes/doc6310.pdf · GNU-Based Software Development on AT91SAM Microcontrollers 1. Introduction

The installer will ask for a target directory, which components to install as well as other minor details. The installation directory can be located anywhere, however it should be noted as it will be used for the rest of the configuration. It is possible to select either “Full” or “Compact” installa-tion, as the required binaries are unpacked either way.

Now, the tools must be made available system-wide. Otherwise, it will not be possible to call make when in a project directory, unless its complete path is specified (which can be tedious). In order to do that, the directory where make.exe is must be added to the PATH environment variable.

The PATH variable can be modified by doing the following:

• Click on the start menu

• In the “Settings” submenu, select “Control Panel”

• Double-click on the “System” icon

• Select the “Advanced” tab

• Click on the “Environment Variables” button located at the bottom

• Look for the PATH variable under the second section (“System variables”)

• Select it and click on the “Edit” button

• Append “;DIRECTORY\bin” to the variable value, where DIRECTORY is the directory where the GnuWin32 make package has been installed

• Click “Ok” three times to validate changes

To check that the configuration is now correct, do as described below:

• Click on the Start menu

• Select “Run...”

• Type “cmd” and click on the “Ok” button

• A shell should appear, type:

make -v

This command tells make to print its version number, which should match the name of the installer provided by the GnuWin32 project.

Figure 4-7. Shell with Working make Command

4.5 GDB Server

4.5.1 Getting GDB ServerGDB Server can be download from the SEGGER web site. It is part of the J-Link software pack-age, which contains several other tools. The package can be downloaded from the following address: http://www.segger.com/download_jlink.html.

86310A–ATARM–26-Mar-07

Application Note

Page 9: GNU-Based Software Development on AT91SAM Microcontrollersww1.microchip.com/downloads/en/AppNotes/doc6310.pdf · GNU-Based Software Development on AT91SAM Microcontrollers 1. Introduction

Application Note

4.5.2 Installing GDB ServerThe J-Link software package is delivered as a ZIP file containing the setup program. After decompressing and launching it, the following window appears:

Figure 4-8. J-Link Software Installer Main Window

Simply click on the “Next >” button until the setup completes.

5. Using the ToolchainThis section demonstrates how basic tasks are performed using the newly-installed toolchain. It uses the “Getting Started with the AT91SAM7S Microcontroller” software example that can be downloaded along with the corresponding application note on the Atmel web site, at this address: http://www.Atmel.com/dyn/products/app_notes.asp?family_id=605.

The Getting Started example shall be unzipped in any directory of the file system. This is the project which is going to be referred to in the following subsections. However, keep in mind that the make utility does not currently support spaces in directory or file names, so they should be avoided.

5.1 Importing an Existing ProjectThe first step is to launch the Eclipse IDE. A shortcut to the program can be found in:

Start Menu > Programs > YAGARTO IDE > Eclipse Platform X.Y

Upon startup, Eclipse will ask for a workspace directory. This is the directory where new projects will be saved. For the purpose of this example, any location can be chosen.

Figure 5-1. Eclipse Workspace Launcher Window

96310A–ATARM–26-Mar-07

Page 10: GNU-Based Software Development on AT91SAM Microcontrollersww1.microchip.com/downloads/en/AppNotes/doc6310.pdf · GNU-Based Software Development on AT91SAM Microcontrollers 1. Introduction

After a workspace has been chosen, the Eclipse main window opens. Initially, it will be com-pletely empty since no project is created yet.

To import an existing GNU project in Eclipse, start by creating a new project by selecting the “New > Project...” option in the file menu. The project wizard window should appear. It offers a list of standard templates which can be used to construct the new project. Since the Getting Started example is written in C and has its own makefile, the “Standard Make C Project” tem-plate should be selected.

Figure 5-2. Project Wizard Window

The next step is to name the project and select its root directory. The name can be set to any value, e.g. “Getting Started”. The root directory must be set manually however, since the goal is to import an existing project and not create a new one in the workspace. Therefore, the “use default location” option should be unchecked and the path of the getting started example should be set in the “Location” field. Once both values are setup correctly, click on the “Next >” button.

106310A–ATARM–26-Mar-07

Application Note

Page 11: GNU-Based Software Development on AT91SAM Microcontrollersww1.microchip.com/downloads/en/AppNotes/doc6310.pdf · GNU-Based Software Development on AT91SAM Microcontrollers 1. Introduction

Application Note

Figure 5-3. Project Name & Directory Window

The final step involves configuring details about the project. The last window shows several tabs, each one of them holding settings that will now be described.

The first tab is used to specify referenced C/C++ projects. This might be useful if the new project needs to use an executable or a library build by another project. For now, the list should be empty since no project has been created yet.

116310A–ATARM–26-Mar-07

Page 12: GNU-Based Software Development on AT91SAM Microcontrollersww1.microchip.com/downloads/en/AppNotes/doc6310.pdf · GNU-Based Software Development on AT91SAM Microcontrollers 1. Introduction

Figure 5-4. Referenced C/C++ Projects Tab

The next tab contains parameters for the make utility, which will be used to compile the code. Unless the makefile used by the project requires some specific parameters, the build command should be left untouched. A useful feature which can be enabled here is the “Build on resource save” option. It automatically recompiles the project if a file changes, freeing the developer from having to wait for the build process after he has finished coding.

126310A–ATARM–26-Mar-07

Application Note

Page 13: GNU-Based Software Development on AT91SAM Microcontrollersww1.microchip.com/downloads/en/AppNotes/doc6310.pdf · GNU-Based Software Development on AT91SAM Microcontrollers 1. Introduction

Application Note

Figure 5-5. Make Builder Settings Tab

It is then possible to add one or several environment variables, which can be used by the vari-ous tools called during compilation. Most of the time, this is not needed, as required variables are often defined in makefiles.

136310A–ATARM–26-Mar-07

Page 14: GNU-Based Software Development on AT91SAM Microcontrollersww1.microchip.com/downloads/en/AppNotes/doc6310.pdf · GNU-Based Software Development on AT91SAM Microcontrollers 1. Introduction

Figure 5-6. Environment Variables Tab

The “Error Parsers” and “Binary Parsers” tabs specify how the make output and the resulting binary file(s) are parsed to display errors and information. As they are correctly set by default, they should be left unaltered.

146310A–ATARM–26-Mar-07

Application Note

Page 15: GNU-Based Software Development on AT91SAM Microcontrollersww1.microchip.com/downloads/en/AppNotes/doc6310.pdf · GNU-Based Software Development on AT91SAM Microcontrollers 1. Introduction

Application Note

Figure 5-7. Error Parsers Tab

Figure 5-8. Binary Parsers Tab

156310A–ATARM–26-Mar-07

Page 16: GNU-Based Software Development on AT91SAM Microcontrollersww1.microchip.com/downloads/en/AppNotes/doc6310.pdf · GNU-Based Software Development on AT91SAM Microcontrollers 1. Introduction

Next comes the “Discovery Options” tab. By default, automatic discovery of paths and symbols is turned on, which enables Eclipse to collect a list of the project functions, variables, and so on. This is useful for navigating in the code, so it is best to leave it enabled. The only modification is to change the “Compiler invocation command” field value from gcc to arm-elf-gcc, since the project is using the GNU ARM compiler and not the standard one.

Figure 5-9. Discovery Options Tab

Finally, the last tab allows the user to choose between three different indexing modes. Indexing makes search functions faster and more accurate, so it should be enabled. For a small project, using the full indexer should not pose any problem. It can slow down bigger ones however, in which case the fast indexer can be chosen instead.

166310A–ATARM–26-Mar-07

Application Note

Page 17: GNU-Based Software Development on AT91SAM Microcontrollersww1.microchip.com/downloads/en/AppNotes/doc6310.pdf · GNU-Based Software Development on AT91SAM Microcontrollers 1. Introduction

Application Note

Figure 5-10. Indexer Settings Tab

After the project configuration is set, clicking the “Finish” button creates the project. Eclipse will ask if it should open the C/C++ perspective, i.e. change its visual appearance for C/C++ coding. Since most of the time this is the desired behavior, the “Remember my decision” box can be checked before clicking the “Yes” button.

Figure 5-11. Eclipse Asking to Open the C/C++ Perspective

The new project should appear in the left pane, with all its files and subdirectories listed. In addi-tion, Eclipse will automatically try to build the project using make when it is opened.

176310A–ATARM–26-Mar-07

Page 18: GNU-Based Software Development on AT91SAM Microcontrollersww1.microchip.com/downloads/en/AppNotes/doc6310.pdf · GNU-Based Software Development on AT91SAM Microcontrollers 1. Introduction

Figure 5-12. Eclipse Main Window After New Project Creation

186310A–ATARM–26-Mar-07

Application Note

Page 19: GNU-Based Software Development on AT91SAM Microcontrollersww1.microchip.com/downloads/en/AppNotes/doc6310.pdf · GNU-Based Software Development on AT91SAM Microcontrollers 1. Introduction

Application Note

5.2 BuildingBuilding the project is either done automatically (if the option was enabled during configuration) or by selecting the “Build Project” item of the “Project” menu. The output of the make command will be shown in the bottom “Console” tab, as shown in Figure 5-13.

Figure 5-13. Console Tab Showing Build Process Output

In addition, Eclipse will also parse the command output to show compilation errors in the “Prob-lems” tab. This is convenient, as detected errors can be clicked on to open the corresponding file at the error location (as demonstrated by Figure 5-14 on page 20).

196310A–ATARM–26-Mar-07

Page 20: GNU-Based Software Development on AT91SAM Microcontrollersww1.microchip.com/downloads/en/AppNotes/doc6310.pdf · GNU-Based Software Development on AT91SAM Microcontrollers 1. Introduction

Figure 5-14. Error Parsing and Navigation in Eclipse

Please note that for best debugging performance, a project must be compiled without any opti-mization. Usually, a variable can be set or unset in the makefile to enable/disable them. In the Getting Started example, the $(OPTIM) variable performs that task. To enable debug support, write the comment as follows;

# Comment the line below for debug mode

#OPTIM = -Os

5.3 Debugging

5.3.1 Launching GDB ServerThe SEGGER GDB Server tool enables the GNU debugger to connect remotely to the target through the JTAG.

When launched, GDB Server connects to the board and waits for debugger connections. A win-dow displaying useful information is also shown (see Figure 5-15). It indicates the connection statuses of the debugger, the SAM-ICE and the target. As written in the log window, a local server is created on TCP/IP port 2331 to allow the debugger to connect.

206310A–ATARM–26-Mar-07

Application Note

Page 21: GNU-Based Software Development on AT91SAM Microcontrollersww1.microchip.com/downloads/en/AppNotes/doc6310.pdf · GNU-Based Software Development on AT91SAM Microcontrollers 1. Introduction

Application Note

It is also possible to set the speed at which the SAM-ICE is operating using the “Initial JTAG speed” combobox. The “adaptive” setting should be used to get the best performance results with AT91SAM7 microcontrollers and it is mandatory to use it with AT91SAM9 devices.

Figure 5-15. GDB Server Main Window

5.3.2 Creating a SRAM ConfigurationIn order to debug the project, the appropriate configuration must first be created in Eclipse. In the “Run” menu, select the “Debug...” item to display the debug configuration management window.

216310A–ATARM–26-Mar-07

Page 22: GNU-Based Software Development on AT91SAM Microcontrollersww1.microchip.com/downloads/en/AppNotes/doc6310.pdf · GNU-Based Software Development on AT91SAM Microcontrollers 1. Introduction

Figure 5-16. Debug Configuration Management Dialog

Since the project is for an embedded target, the configuration should be created under one of the two bottom sections (“Embedded debug (Cygwin)” and “Embedded debug (Native)”). The YAGARTO toolchain is compiled natively for the Win32® environment, so the very last section is the appropriate one. Right-clicking on its name and selecting the “New” option creates a basic configuration named after the project, as shown in Figure 5-17.

226310A–ATARM–26-Mar-07

Application Note

Page 23: GNU-Based Software Development on AT91SAM Microcontrollersww1.microchip.com/downloads/en/AppNotes/doc6310.pdf · GNU-Based Software Development on AT91SAM Microcontrollers 1. Introduction

Application Note

Figure 5-17. Basic Embedded Debug Configuration

There are five tabs holding information about the debug configuration. In the first one, the binary file to debug must be specified in the “C/C++ Application” field. If the project was built without any errors, the “Search Project...” button should list the possible files. The Getting Started exam-ple for the AT91SAM7S builds two files, one for executing in SRAM and one for Flash. The first one should be chosen for this configuration.

236310A–ATARM–26-Mar-07

Page 24: GNU-Based Software Development on AT91SAM Microcontrollersww1.microchip.com/downloads/en/AppNotes/doc6310.pdf · GNU-Based Software Development on AT91SAM Microcontrollers 1. Introduction

Figure 5-18. Binary File Selection

In the “Debugger” tab, several details about the YAGARTO debugger must be entered. All set-tings are correct, except the command to call the debugger is arm-elf-gdb and not gdb, so this shall be corrected in the first text field.

Figure 5-19. Debugger Configuration Tab

246310A–ATARM–26-Mar-07

Application Note

Page 25: GNU-Based Software Development on AT91SAM Microcontrollersww1.microchip.com/downloads/en/AppNotes/doc6310.pdf · GNU-Based Software Development on AT91SAM Microcontrollers 1. Introduction

Application Note

The last tab to examine is the “Commands” tab. (There is nothing to do in the “Source” and “Common” tabs as they are automatically set to correct values and are rarely modified.) There are several initialization and runtime commands to enter in order for the debugger to work correctly.

Since the debugger will connect to the target remotely, this must be specified using this line:

target remote localhost:2331

This command tells arm-elf-gdb to connect remotely to a server running on TCP/IP port 2331 on the local machine. This settings are the ones given by GDB Server (see Section 5.3.1 on page 20). When the command is executed, the connection status of the debugger should change in the GDB server window. This command must be put in the ‘Initialize’ commands box.

Once the debugger is connected, it is best to reset the target. This ensure that changes made during previous iterations of the debug process are discarded and will not affect a new session. This can be done by adding:

monitor reset 1

Finally, since for debug configuration the program will run in SRAM, it must be uploaded to the target. This is done with the load command:

load

Both the reset and load commands should be put in the ‘Run’ commands box.

Figure 5-20. Commands Configuration Tab

At this point, the configuration is correct and should be saved using the “Apply” button.

256310A–ATARM–26-Mar-07

Page 26: GNU-Based Software Development on AT91SAM Microcontrollersww1.microchip.com/downloads/en/AppNotes/doc6310.pdf · GNU-Based Software Development on AT91SAM Microcontrollers 1. Introduction

5.3.3 Creating a Flash ConfigurationDebugging in Flash is almost the same as debugging in SRAM, except the program must be flashed prior to execution and is not reloaded when a debug session starts.

To create a Flash debug configuration, do as described in section Section 5.3.2 on page 21 with two differences:

• The binary file selected in the “Main” tab must be the one linked for Flash

• The load command (in the “Commands” tab) must be omitted

5.3.4 Creating a SDRAM ConfigurationSeveral microcontrollers of the AT91 family can interface with an external SDRAM chip. This additional memory is useful for debugging programs since it is much larger than internal SRAM.

However, conversely to SRAM, it is not possible to directly load code in the SDRAM, it must be initialized first. To do this, a GDB command file (“init_sdram.gdb”) is provided with the Getting Started examples for chips which have an SDRAM controller. The script enables the main oscil-lator, PLL and SDRAM.

The source command executes the specified GDB command file, therefore the SDRAM debug configuration is identical to the SRAM one except for two differences:

• The binary file selected in the “Main” tab must be the one linked for SDRAM

• In the “Commands” tab, the source init_sdram.gdb command must be added right before load (among the ‘Run’ commands)

5.3.5 Debugging

5.3.5.1 Setting BreakpointsSetting or removing breakpoints is done as in other IDEs, i.e. by double-clicking on the right of the line to put the breakpoint on. Another option is to select the “Toggle Line Breakpoint” item of the “Run” menu when in the Debug perspective.

5.3.5.2 Starting a Debug SessionTo start a debug session, choose “Debug...” in the “Run” menu. Then, select the debug configu-ration to use and click on the “Debug” button. This should open the Debug perspective, with the program stopped. Make sure that GDB Server is actually running before starting a debug session.

To actually execute the program, click on the “Resume” item in the “Run” menu, or press the F8 key. If a breakpoint has been set in the code, the program should stop at the corresponding location, as demonstrated in the following screenshot:

266310A–ATARM–26-Mar-07

Application Note

Page 27: GNU-Based Software Development on AT91SAM Microcontrollersww1.microchip.com/downloads/en/AppNotes/doc6310.pdf · GNU-Based Software Development on AT91SAM Microcontrollers 1. Introduction

Application Note

Figure 5-21. Debug Perspective Showing Program Execution Stopped on a Breakpoint

Once debugging is finished, the session can be stopped by selecting “Run > Terminate”. Note that only a single session can be active at once. This means the current session must be termi-nated before starting another one.

5.3.5.3 Closing A Debug SessionTo close a debug session, select the “Thread” item in the “Debug” tab. Then, close the session by clicking on either the red square button in the above tab, or select “Terminate” in the “Run” menu.

5.3.5.4 Debugging CommandsThe usual debugging functionalities are available in Eclipse, namely:

• Step into

• Step over

• Step return

• Run to line

They can all be accessed either from the “Run” menu, or through button located in the “Debug” tab.

276310A–ATARM–26-Mar-07

Page 28: GNU-Based Software Development on AT91SAM Microcontrollersww1.microchip.com/downloads/en/AppNotes/doc6310.pdf · GNU-Based Software Development on AT91SAM Microcontrollers 1. Introduction

5.3.5.5 Memory ViewThe “Memory” tab at the bottom allows the user to monitor the content at a given memory address. To add a memory region, right-click in the “Monitors” area and select “Add Memory Monitor”. Eclipse will ask for the base address of the region, and then show its content.

Figure 5-22. Eclipse Showing the Memory Contents at Address 0x200000

5.4 Memory ProgrammingEclipse enables the user to configure and launch external tools. Combined with the Atmel SAM-BA utility, it is easy to program the memory of the target microcontroller directly in Eclipse.

To do this, a script performing the flashing operation is required. The Getting Started example provides a script which puts the binary into flash and runs it, along with a batch file to easily exe-cute the script. It will be used for the purpose of this demonstration. Please refer to the SAM-BA manual for more information about writing scripts.

Start by creating a new external tool configuration by selecting the “External Tools > External Tools...” item of the “Run” menu. This opens a new dialog for managing existing configurations and creating new ones.

286310A–ATARM–26-Mar-07

Application Note

Page 29: GNU-Based Software Development on AT91SAM Microcontrollersww1.microchip.com/downloads/en/AppNotes/doc6310.pdf · GNU-Based Software Development on AT91SAM Microcontrollers 1. Introduction

Application Note

Create a new configuration by right-clicking in the left pane and selecting “New”. The right pane should now show several tabs with the available parameters:

Figure 5-23. External Tool Configuration Dialog

There are only two field values to set for basic operation, both of which are in the “Main” tab. The first one is the “Location” field, simply select the “prog_flash.bat” file in the dialog displayed when pressing the “Browse Workspace...” button. The other value is the working directory, which must be set to where the batch file is located. Normally, this is at the base of the project directory.

After the settings have been entered, click on “Apply” to save them and “Run” to try the script.

296310A–ATARM–26-Mar-07

Page 30: GNU-Based Software Development on AT91SAM Microcontrollersww1.microchip.com/downloads/en/AppNotes/doc6310.pdf · GNU-Based Software Development on AT91SAM Microcontrollers 1. Introduction

Revision History

Doc. Rev CommentsChange Request Ref.

6310A First issue

306310A–ATARM–26-Mar-07

Application Note

Page 31: GNU-Based Software Development on AT91SAM Microcontrollersww1.microchip.com/downloads/en/AppNotes/doc6310.pdf · GNU-Based Software Development on AT91SAM Microcontrollers 1. Introduction

Disclaimer: The information in this document is provided in connection with Atmel products. No license, express or implied, by estoppel or otherwise, to any intellectual property right is granted by this document or in connection with the sale of Atmel products. EXCEPT AS SET FORTH IN ATMEL’S TERMS AND CONDI-TIONS OF SALE LOCATED ON ATMEL’S WEB SITE, ATMEL ASSUMES NO LIABILITY WHATSOEVER AND DISCLAIMS ANY EXPRESS, IMPLIED OR STATUTORY WARRANTY RELATING TO ITS PRODUCTS INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT, CONSEQUENTIAL, PUNITIVE, SPECIAL OR INCIDEN-TAL DAMAGES (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF PROFITS, BUSINESS INTERRUPTION, OR LOSS OF INFORMATION) ARISING OUT OF THE USE OR INABILITY TO USE THIS DOCUMENT, EVEN IF ATMEL HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Atmel makes no representations or warranties with respect to the accuracy or completeness of the contents of this document and reserves the right to make changes to specifications and product descriptions at any time without notice. Atmel does not make any commitment to update the information contained herein. Unless specifically provided otherwise, Atmel products are not suitable for, and shall not be used in, automotive applications. Atmel’s products are not intended, authorized, or warranted for use as components in applications intended to support or sustain life.

Atmel Corporation Atmel Operations

2325 Orchard ParkwaySan Jose, CA 95131, USATel: 1(408) 441-0311Fax: 1(408) 487-2600

Regional Headquarters

EuropeAtmel EuropeLe Krebs8, rue Jean-Pierre TimbaudBP 30978054 St Quentin-en-Yvelines CedexFranceTel: (33) 1-30-60-70-00 Fax: (33) 1-30-60-71-11

AsiaRoom 1219Chinachem Golden Plaza77 Mody Road TsimshatsuiEast KowloonHong KongTel: (852) 2721-9778Fax: (852) 2722-1369

Japan9F, Tonetsu Shinkawa Bldg.1-24-8 ShinkawaChuo-ku, Tokyo 104-0033JapanTel: (81) 3-3523-3551Fax: (81) 3-3523-7581

Memory2325 Orchard ParkwaySan Jose, CA 95131, USATel: 1(408) 441-0311Fax: 1(408) 436-4314

Microcontrollers2325 Orchard ParkwaySan Jose, CA 95131, USATel: 1(408) 441-0311Fax: 1(408) 436-4314

La ChantrerieBP 7060244306 Nantes Cedex 3, FranceTel: (33) 2-40-18-18-18Fax: (33) 2-40-18-19-60

ASIC/ASSP/Smart CardsZone Industrielle13106 Rousset Cedex, FranceTel: (33) 4-42-53-60-00Fax: (33) 4-42-53-60-01

1150 East Cheyenne Mtn. Blvd.Colorado Springs, CO 80906, USATel: 1(719) 576-3300Fax: 1(719) 540-1759

Scottish Enterprise Technology ParkMaxwell BuildingEast Kilbride G75 0QR, Scotland Tel: (44) 1355-803-000Fax: (44) 1355-242-743

RF/AutomotiveTheresienstrasse 2Postfach 353574025 Heilbronn, GermanyTel: (49) 71-31-67-0Fax: (49) 71-31-67-2340

1150 East Cheyenne Mtn. Blvd.Colorado Springs, CO 80906, USATel: 1(719) 576-3300Fax: 1(719) 540-1759

BiometricsAvenue de RochepleineBP 12338521 Saint-Egreve Cedex, FranceTel: (33) 4-76-58-47-50Fax: (33) 4-76-58-47-60

Literature Requestswww.atmel.com/literature

6310A–ATARM–26-Mar-07

© 2007 Atmel Corporation. All rights reserved. Atmel®, logo and combinations thereof, Everywhere You Are®, and others, are registered trademarks SAM-BA™ and others are trademarks of Atmel Corporation or its subsidiaries. Windows® and others, are registered trademarks or trademarks of Microsoft Corporation in the US and/or other countries. ARM®, the ARM Powered® logo, Thumb® and others, are registered trademarks or trademarks of ARM Lim-ited. Other terms and product names may be the trademarks of others.