AT91 ARM Thumb Microcontrollers. Application Note. GNU-Based Software Development on AT91SAM Microcontrollers. 1. Introduction. 2.

Transcription

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. 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. AT91 ARM Thumb Microcontrollers 2. References Atmel, Getting Started with AT91SAM7S Microcontrollers, lit Atmel SAM Boot Assistant (SAM-BA ) User Guide, lit 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

2 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). 2

3 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 YAGARTO YAGARTO (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 compiled 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 and 3

4 3.5 Make 3.6 GDB Server 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. The GnuWin32 project ( 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 To find out about the other tools provided by GnuWin32, please refer to The 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 creates 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: 4. Installation 4.1 SAM-BA Getting SAM-BA Since 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: 4

5 4.1.2 Installing SAM-BA The 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 Getting YAGARTO The YAGARTO home page, 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 ) Installing YAGARTO The installer for YAGARTO is an executable file. Launching it brings the following dialog: Figure 4-2. YAGARTO Installer Main Window 5

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. 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 Eclipse As 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 following two subsections Getting Eclipse The YAGARTO version of Eclipse (named YAGARTO IDE) can be found on the web site ( home page. The file to download is named Integrated Development Environment. 6

7 Eclipse requires the Java Runtime Environment (JRE). Most computers already have JRE installed. If not, it can be downloaded from 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 Make Getting Make The 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 Installing Make The 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 7

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. 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 Getting GDB Server GDB Server can be download from the SEGGER web site. It is part of the J-Link software package, which contains several other tools. The package can be downloaded from the following address: 8

9 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. 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: 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 Project The 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 9

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. Since the Getting Started example is written in C and has its own makefile, the Standard Make C Project template 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. 10

11 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. 11

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. 12

13 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. 13

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. 14

15 Figure 5-7. Error Parsers Tab Figure 5-8. Binary Parsers Tab 15

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. 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. 16

17 Figure 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 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 addition, Eclipse will automatically try to build the project using make when it is opened. 17

18 Figure Eclipse Main Window After New Project Creation 18

19 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 Figure Console Tab Showing Build Process Output In addition, Eclipse will also parse the command output to show compilation errors in the Problems 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). 19

20 Figure 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 Debugging Launching GDB Server The 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 window 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. 20

21 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 GDB Server Main Window 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... item to display the debug configuration management window. 21

22 Figure 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

23 Figure 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. 23

24 Figure 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 Debugger Configuration Tab 24

25 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 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 Commands Configuration Tab At this point, the configuration is correct and should be saved using the Apply button. 25

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 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 Creating a SDRAM Configuration Several 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 Debugging 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 oscillator, 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) Setting Breakpoints Setting 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 Starting a Debug Session To start a debug session, choose Debug... in the Run menu. Then, select the debug configuration 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: 26

27 Figure 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 Closing A Debug Session To 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 Debugging Commands The 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. 27

28 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 Eclipse Showing the Memory Contents at Address 0x Memory Programming Eclipse 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 execute 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. 28

29 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 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. 29

30 Revision History Doc. Rev 6310A Comments First issue Change Request Ref. 30

31 Atmel Corporation 2325 Orchard Parkway San Jose, CA 95131, USA Tel: 1(408) Fax: 1(408) Regional Headquarters Europe Atmel Europe Le Krebs 8, rue Jean-Pierre Timbaud BP St Quentin-en-Yvelines Cedex France Tel: (33) Fax: (33) Asia Room 1219 Chinachem Golden Plaza 77 Mody Road Tsimshatsui East Kowloon Hong Kong Tel: (852) Fax: (852) Japan 9F, Tonetsu Shinkawa Bldg Shinkawa Chuo-ku, Tokyo Japan Tel: (81) Fax: (81) Atmel Operations Memory 2325 Orchard Parkway San Jose, CA 95131, USA Tel: 1(408) Fax: 1(408) Microcontrollers 2325 Orchard Parkway San Jose, CA 95131, USA Tel: 1(408) Fax: 1(408) La Chantrerie BP Nantes Cedex 3, France Tel: (33) Fax: (33) ASIC/ASSP/Smart Cards Zone Industrielle Rousset Cedex, France Tel: (33) Fax: (33) East Cheyenne Mtn. Blvd. Colorado Springs, CO 80906, USA Tel: 1(719) Fax: 1(719) Scottish Enterprise Technology Park Maxwell Building East Kilbride G75 0QR, Scotland Tel: (44) Fax: (44) RF/Automotive Theresienstrasse 2 Postfach Heilbronn, Germany Tel: (49) Fax: (49) East Cheyenne Mtn. Blvd. Colorado Springs, CO 80906, USA Tel: 1(719) Fax: 1(719) Biometrics Avenue de Rochepleine BP Saint-Egreve Cedex, France Tel: (33) Fax: (33) Literature Requests 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. 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 Limited. Other terms and product names may be the trademarks of others.