User guide

ManualsBrandsAtmel ManualsSwitchAT91

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

Summary of content (31 pages)

PAGE 1
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 however, 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.
PAGE 2
Figure 3-1. 3.2 Atmel SAM-ICE Emulator for AT91 Microcontrollers 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.
PAGE 3
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.
PAGE 4
3.5 Make Most 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.
PAGE 5
Application Note 4.1.2 Installing SAM-BA The Atmel ISP package is provided as a self-installing executable file named “Install AT91ISP 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.
PAGE 6
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.
PAGE 7
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 Eclipse Once 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 process is finished. 4.4 4.4.
PAGE 8
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” installation, as the required binaries are unpacked either way. Now, the tools must be made available system-wide.
PAGE 9
Application Note 4.5.2 Installing GDB Server The 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 Toolchain This section demonstrates how basic tasks are performed using the newly-installed toolchain.
PAGE 10
After a workspace has been chosen, the Eclipse main window opens. Initially, it will be completely 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.
PAGE 11
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.
PAGE 12
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.
PAGE 13
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 various tools called during compilation. Most of the time, this is not needed, as required variables are often defined in makefiles.
PAGE 14
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.
PAGE 15
Application Note Figure 5-7. Error Parsers Tab Figure 5-8.
PAGE 16
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.
PAGE 17
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.
PAGE 18
Figure 5-12.
PAGE 19
Application Note 5.2 Building Building 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 “Problems” tab.
PAGE 20
Figure 5-14. Error Parsing and Navigation in Eclipse Please note that for best debugging performance, a project must be compiled without any optimization. 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 5.3.
PAGE 21
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 Configuration In order to debug the project, the appropriate configuration must first be created in Eclipse. In the “Run” menu, select the “Debug...
PAGE 22
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.
PAGE 23
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 example for the AT91SAM7S builds two files, one for executing in SRAM and one for Flash. The first one should be chosen for this configuration.
PAGE 24
Figure 5-18. Binary File Selection In the “Debugger” tab, several details about the YAGARTO debugger must be entered. All settings 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.
PAGE 25
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.
PAGE 26
5.3.3 Creating a Flash Configuration Debugging 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.
PAGE 27
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 terminated before starting another one. 5.3.5.3 Closing A Debug Session To close a debug session, select the “Thread” item in the “Debug” tab.
PAGE 28
5.3.5.5 Memory View The “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 Programming Eclipse enables the user to configure and launch external tools.
PAGE 29
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.
PAGE 30
Revision History Doc. Rev Comments 6310A First issue 30 Change Request Ref.
PAGE 31
Atmel Corporation 2325 Orchard Parkway San Jose, CA 95131, USA Tel: 1(408) 441-0311 Fax: 1(408) 487-2600 Regional Headquarters Europe Atmel Europe Le Krebs 8, rue Jean-Pierre Timbaud BP 309 78054 St Quentin-en-Yvelines Cedex France Tel: (33) 1-30-60-70-00 Fax: (33) 1-30-60-71-11 Asia Room 1219 Chinachem Golden Plaza 77 Mody Road Tsimshatsui East Kowloon Hong Kong Tel: (852) 2721-9778 Fax: (852) 2722-1369 Japan 9F, Tonetsu Shinkawa Bldg.