A GNU Development Environment for the AVR Microcontroller | ECE 473, Study Guides, Projects, Research of Microprocessors

Download A GNU Development Environment for the AVR Microcontroller | ECE 473 and more Study Guides, Projects, Research Microprocessors in PDF only on Docsity!

A GNU Development Environment for

the AVR Microcontroller

Rich Neswold

[email protected]

A GNU Development Environment for the AVR Microcontroller

by Rich Neswold

Published $Date$

Copyright © 1999, 2000, 2001, 2002 by Richard M. Neswold, Jr.

This document attempts to cover the details of the GNU Tools that are specific to the AVR family of processors.

Table of Contents

• 1. Installing the GNU Tools ..........................................................................................................................................
  • 1.1. GNU Binutils..................................................................................................................................................
  • 1.2. AVR-GCC ......................................................................................................................................................
    • 1.2.1. Downloading the Source....................................................................................................................
    • 1.2.2. Building the Project ...........................................................................................................................
    • 1.2.3. Installing the Tools.............................................................................................................................
  • 1.3. AVR-LIBC......................................................................................................................................................
    • 1.3.1. Downloading the Source....................................................................................................................
    • 1.3.2. Building the Libraries ........................................................................................................................
    • 1.3.3. Installing the Libraries and Header Files...........................................................................................
  • 1.4. Programming Your Processor.........................................................................................................................
    • 1.4.1. Using avrprog ...................................................................................................................................
    • 1.4.2. Using uisp ..........................................................................................................................................
• 1. Using the GNU Tools.................................................................................................................................................
  • 2.1. The Project .....................................................................................................................................................
  • 2.2. Compiling and Linking ..................................................................................................................................
  • 2.3. “Map” Files ..................................................................................................................................................
  • 2.4. Generating .hex Files..................................................................................................................................
  • 2.5. Letting Make Build the Project ...................................................................................................................
• 1. Application Start-up ...............................................................................................................................................
• 1. Standard C Library ................................................................................................................................................
  • 4.1. Function Reference ......................................................................................................................................
    • 4.1.1. abort...............................................................................................................................................
    • 4.1.2. abs...................................................................................................................................................
    • 4.1.3. atoi.................................................................................................................................................
    • 4.1.4. atol.................................................................................................................................................
    • 4.1.5. bsearch ..........................................................................................................................................
    • 4.1.6. cos...................................................................................................................................................
    • 4.1.7. cosh.................................................................................................................................................
    • 4.1.8. div...................................................................................................................................................
    • 4.1.9. exit.................................................................................................................................................
    • 4.1.10. fabs...............................................................................................................................................
      • ispunct, isspace, isupper, isxdigit ..................................................................................... 4.1.11. isalnum, isalpha, isascii, isblank, iscntrl, isdigit, isgraph, islower, isprint,
    • 4.1.12. labs...............................................................................................................................................
    • 4.1.13. ldiv...............................................................................................................................................
    • 4.1.14. longjmp ........................................................................................................................................
    • 4.1.15. qsort.............................................................................................................................................
    • 4.1.16. setjmp ..........................................................................................................................................
    • 4.1.17. sin.................................................................................................................................................
    • 4.1.18. sinh...............................................................................................................................................
    • 4.1.19. sqrt...............................................................................................................................................
    • 4.1.20. tan.................................................................................................................................................
    • 4.1.21. toascii ........................................................................................................................................
    • 4.1.22. tolower, toupper .......................................................................................................................
• 1. Memory APIs ..........................................................................................................................................................
  • 5.1. Program Memory .........................................................................................................................................
  • 5.2. Function Reference ......................................................................................................................................
    • 5.2.1. ATTR_CONST, ATTR_PROGMEM, ATTR_PURE ........................................................
    • 5.2.2. __elpm_inline .............................................................................................................................
    • 5.2.3. __lpm_inline ...............................................................................................................................
    • 5.2.4. memcpy_P ........................................................................................................................................
    • 5.2.5. PRG_RDB ..........................................................................................................................................
    • 5.2.6. PSTR.................................................................................................................................................
    • 5.2.7. strcat_P ........................................................................................................................................
    • 5.2.8. strcmp_P ........................................................................................................................................
    • 5.2.9. strcpy_P ........................................................................................................................................
    • 5.2.10. strcasecmp_P .............................................................................................................................
    • 5.2.11. strlen_P ......................................................................................................................................
    • 5.2.12. strncasecmp_P ...........................................................................................................................
    • 5.2.13. strncmp_P....................................................................................................................................
    • 5.2.14. strncpy_P....................................................................................................................................
  • 5.3. EEPROM......................................................................................................................................................
  • 5.4. Function Reference ......................................................................................................................................
    • 5.4.1. eeprom_is_ready .........................................................................................................................
    • 5.4.2. eeprom_rb......................................................................................................................................
    • 5.4.3. eeprom_read_block.....................................................................................................................
    • 5.4.4. eeprom_rw......................................................................................................................................
    • 5.4.5. eeprom_wb......................................................................................................................................
• 1. Interrupt API ..........................................................................................................................................................
  • 6.1. Function Reference ......................................................................................................................................
    • 6.1.1. cli...................................................................................................................................................
    • 6.1.2. enable_external_int ................................................................................................................
    • 6.1.3. INTERRUPT......................................................................................................................................
    • 6.1.4. sei...................................................................................................................................................
    • 6.1.5. SIGNAL ............................................................................................................................................
    • 6.1.6. timer_enable_int.......................................................................................................................
• 1. I/O API.....................................................................................................................................................................
  • 7.1. I/O Port APIs................................................................................................................................................
  • 7.2. Function Reference ......................................................................................................................................
    • 7.2.1. BV .....................................................................................................................................................
    • 7.2.2. bit_is_clear ...............................................................................................................................
    • 7.2.3. bit_is_set....................................................................................................................................
    • 7.2.4. cbi...................................................................................................................................................
    • 7.2.5. inp...................................................................................................................................................
    • 7.2.6. __inw...............................................................................................................................................
    • 7.2.7. __inw_atomic ...............................................................................................................................
    • 7.2.8. loop_until_bit_is_clear........................................................................................................
    • 7.2.9. loop_until_bit_is_set ............................................................................................................
    • 7.2.10. outp...............................................................................................................................................
    • 7.2.11. __outw ..........................................................................................................................................
    • 7.2.12. __outw_atomic ...........................................................................................................................
    • 7.2.13. parity_even_bit .......................................................................................................................
    • 7.2.14. sbi.................................................................................................................................................
  • 7.3. Watchdog API ..............................................................................................................................................
  • 7.4. Function Reference ......................................................................................................................................
    • 7.4.1. wdt_disable..................................................................................................................................
    • 7.4.2. wdt_enable....................................................................................................................................
    • 7.4.3. wdt_reset......................................................................................................................................
• A. AVR-GCC Configuration ......................................................................................................................................
  • A.1. avr-as Options ..........................................................................................................................................
  • A.2. avr-gcc Options ........................................................................................................................................
• 1-1. Tarball Locations ..................................................................................................................................................... List of Tables
• 5-1. Primitive types in program memory ......................................................................................................................
• 6-1. Signal names..........................................................................................................................................................
• A-1. avr-as Options....................................................................................................................................................
• A-2. avr-gcc Options .................................................................................................................................................
• 2-1. Schematic of demo project ...................................................................................................................................... List of Figures
• 3-1. Hex file for empty main()....................................................................................................................................
• 2-1. Demo source code ................................................................................................................................................... List of Examples
• 2-2. Disassembly of Demo Application..........................................................................................................................
• 2-3. Portion of demo map file .......................................................................................................................................
• 2-4. Makefile for Demo Project .................................................................................................................................
• 3-1. Code that runs immediately after RESET..............................................................................................................
• 3-2. Configuring the watchdog during reset .................................................................................................................
• 5-1. Proper use of EEPROM variables .........................................................................................................................
• 6-1. Setting up an interrupt handler ..............................................................................................................................
• 6-2. Setting up a signal handler.....................................................................................................................................

Chapter 1. Installing the GNU Tools

This chapter shows how to build and install a complete development environment for the AVR processors using the

GNU toolset.

I created an area for the AVR tools under /usr/local to keep this stuff separate from the base system. As root, I

chown’ed /usr/local/avr under my normal account. This way, I don’t have to be root to install the tools. All the

instructions assume the tools will be installed in this location. If you want to place them in a different locations you

need to specify the new location using the --prefix option.

Table 1-1. Tarball Locations

Tool Version Location

GNU Binutils 2.11 binutils-2.11.tar.bz

(http://mirrors.rcn.net/pub/sourceware/binutils/releases/binutils-

2.11.tar.bz2)

AVR-GCC 3.0.1 gcc-core-3.0.1.tar.gz

(ftp://gatekeeper.dec.com/pub/GNU/gcc/gcc-3.0.1/gcc-core-

3.0.1.tar.gz)

AVR libc 20020203 avr-libc-20020203.tar.gz

(http://www.amelek.gda.pl/avr/libc/avr-libc-20020203.tar.gz)

AVR Programmer 1.0b uisp-1.0b.src.tar.gz ()

1.1. GNU Binutils

The binutils package provides all the low-level utilities needed in building and manipulating object files. Once

installed, your environment will have an AVR assembler (avr-as), linker (avr-ld), and librarian (avr-ar and

avr-ranlib). In addition, you get tools which extract data from object files (avr-objcopy), dissassemble object

file information (avr-objdump), and strip information from object files (avr-strip). Before we can build the C

compiler, these tools need to be in place.

The binutils source archive, used in preparing this document, is version 2.11. Its location is given in Table 1-1.

Download the file and extract^1 its contents.

% bunzip2 -c binutils-2.11.tar.bz2 | tar xf - % cd binutils-2.

The next step is to configure and build the tools. This is done by supplying arguments to the configure script that

enable the AVR-specific options.

% configure --target=avr --prefix=/usr/local/avr

When configure is run, it generates a lot of messages while it determines what is available on your operating

system. When it finishes, it will have created several Makefiles that are custom tailored to your platform. At this

point, you can build the project.^2

Chapter 1. Installing the GNU Tools

% make install

1.3. AVR-LIBC

1.3.1. Downloading the Source

The AVR standard library archive used in this document is version 20020203. The archive can be obtained using the

URL in Table 1-1. Download this file and place it in your working directory.

1.3.2. Building the Libraries

Before we can build the libraries, we need to unarchive the tarball.

% tar zxf avr-libc-20020203.tar.gz % cd avr-libc-

Now simply build the project.

Note: At this point, the user can configure some library options, like setting whether the watchdog can be initialized through the linker hack.

% cd src % make prefix=/usr/local/avr

1.3.3. Installing the Libraries and Header Files

Once the libraries have been built, you need to install them with the rest of the tools.

% make prefix=/usr/local/avr install

1.4. Programming Your Processor

There are several applications that will burn your .hex files into an AVR processor. This section covers these tools.

1.4.1. Using avrprog

(This section was contributed by Brian Dean .)

Chapter 1. Installing the GNU Tools

avrprog is a program that is used to update or read the flash and EEPROM memories of Atmel AVR

microcontrollers on FreeBSD Unix. It supports the Atmel serial programming protocol using the PC’s parallel port

and can upload either a raw binary file or an Intel Hex format file. It can also be used in an interactive mode to

individually update EEPROM cells, fuse bits, and/or lock bits (if their access is supported by the Atmel serial

programming protocol.) The main flash instruction memory of the AVR can also be programmed in interactive mode,

however this is not very useful because one can only turn bits off. The only way to turn flash bits on is to erase the

entire memory (using AVRPROG’s -e option).

avrprog is part of the FreeBSD ports system. To install it, simply do the following:

cd /usr/ports/devel/avrprog

make install

Once installed, avrprog can program processors using the contents of the .hex file specified on the command line.

In this example, the file main.hex is burned into the flash memory:

avrprog -p 2313 -e -m flash -i main.hex

avrprog: AVR device initialized and ready to accept instructions

avrprog: Device signature = 0x1e

avrprog: erasing chip avrprog: done. avrprog: reading input file "main.hex" avrprog: input file main.hex auto detected as Intel Hex

avrprog: writing flash: 1749 0x avrprog: 1750 bytes of flash written avrprog: verifying flash memory against main.hex: avrprog: reading on-chip flash data: 1749 0x avrprog: verifying ... avrprog: 1750 bytes of flash verified

avrprog done. Thank you.

The "-p 2313" option lets avrprog know that we are operating on an AT90S2313 chip. This option specifies the

device id and is matched up with the device of the same id in AVRPROG’s configuration file

(/usr/local/etc/avrprog.conf). To list valid parts, specify the "-v" option. The "-e" option instructs avrprog

to perform a chip-erase before programming; this is almost always necessary before programming the flash. The "-m

flash" option indicates that we want to upload data into the flash memory, while "-i main.hex" specifies the

name of the input file.

The EEPROM is uploaded in the same way, the only difference is that you would use "-m eeprom" instead of "-m

flash".

To use interactive mode, use the "-t" option:

avrprog -p 2313 -t

avrprog: AVR device initialized and ready to accept instructions avrprog: Device signature = 0x1e

Chapter 2. Using the GNU Tools

At this point, you should have the GNU tools configured, built, and installed on your system. In this chapter, we

present a simple example of using the GNU tools in an AVR project. After reading this chapter, you should have a

better feel as to how the tools are used and how a Makefile can be configured.

2.1. The Project

This project will use the pulse-width modulator (PWM) to ramp an LED on and off every two seconds. An

AT90S2313 processor will be used as the controller. The circuit for this demonstration is shown in Figure 2-1. If you

have a development kit, you should be able to use it, rather than build the circuit, for this project.

Figure 2-1. Schematic of demo project

The source code is given in Example 2-1. For the sake of this example, create a file called demo.c containing this

source code. Some of the more important parts are:

Ê The PWM is being used in 10-bit mode, so we need a 16-bit variable to remember the current value.

Ë SIGNAL() is a macro that marks the function as an interrupt routine. In this case, the function will get called

when the timer overflows. Setting up interrupts is explained in greater detail in Chapter 6.

Ì This section determines the new value of the PWM.

Í Here’s where the newly computed value is loaded into the PWM regsiter. Since we are in an interrupt routine, it

is safe to use outw(). Outside of an interrupt, outw_atomic() should be used.

Î This routine gets called after a reset. It initializes the PWM and enables interrupts.

Ï The main loop of the program does nothing -- all the work is done by the interrupt routine! If this was a real

product, we’d probably put a sleep instruction in this loop to conserve power.

Example 2-1. Demo source code

• "THE BEER-WARE LICENSE" (Revision 42):

Chapter 2. Using the GNU Tools

• wrote this file. As long as you retain this notice you
• can do whatever you want with this stuff. If we meet some day, and you think
• this stuff is worth it, you can buy me a beer in return. Joerg Wunsch
• Simple AVR demonstration. Controls a LED that can be directly
• connected from OC1/OC1A to GND. The brightness of the LED is
• controlled with the PWM. After each period of the PWM, the PWM
• value is either incremented or decremented, that’s all.
• $Id: simple-demo.c,v 1.3 2002/02/11 19:51:51 j Exp $ */

#include #include #include

#if defined(AVR_AT90S2313)

define OC1 PB

define OCR OCR1L

define DDROC DDRB

#elif defined(AVR_AT90S2333) || defined(AVR_AT90S4433)

define OC1 PB

define DDROC DDRB

define OCR OCR1L

#elif defined(AVR_AT90S4414) || defined(AVR_AT90S8515) || defined(AVR_AT90S4434) || defined(AVR_AT90S8535) || defined(AVR_ATmega163)

define OC1 PD

define DDROC DDRD

define OCR OCR1AL

#else

error "Don’t know what kind of MCU you are compiling for"

#endif

volatile uint16_t pwm;Ê volatile enum { UP, DOWN } direction;

SIGNAL(SIG_OVERFLOW1)Ë

switch (direction)Ì { case UP: if (++pwm == 1023) direction = DOWN; break;

Chapter 2. Using the GNU Tools

However, real-world projects will have several modules and will typically need to break up the building of the project

into several compiles and one link.

% avr-gcc -g -Os -mmcu=at90s2313 -c demo.c

The compilation will create a demo.o file. Next we link it into a binary called demo.out.

% avr-gcc -g -mmcu=at90s2313 -o demo.out demo.o

It is important to specify the MCU type when linking. The compiler uses the -mmcu option to choose start-up files

and run-time libraries that get linked together. If this option isn’t specified, the compiler defaults to the 8515

processor environment, which is most certainly what you didn’t want.

Now we have a binary file. Can we do anything useful with it (besides put it into the processor?) The GNU Binutils

suite is made up of many useful tools for manipulating object files that get generated. One tool is avr-objdump,

which takes information from the object file and displays it in many useful ways. Typing the command by itself will

cause it to list out its options.

For instance, to get a feel of the application’s size, the -h option can be used:

% avr-objdump -h demo.out

demo.out: file format elf32-avr

Sections: Idx Name Size VMA LMA File off Algn 0 .text 000000ec 00000000 00000000 00000094 2** CONTENTS, ALLOC, LOAD, READONLY, CODE 1 .data 00000000 00800060 000000ec 00000180 2** CONTENTS, ALLOC, LOAD, DATA 2 .bss 00000004 00800060 00800060 00000180 2** ALLOC 3 .eeprom 00000000 00810000 00810000 00000180 2** CONTENTS 4 .stab 00000690 00000000 00000000 00000180 2** CONTENTS, READONLY, DEBUGGING 5 .stabstr 00000637 00000000 00000000 00000810 2** CONTENTS, READONLY, DEBUGGING

The output of this command shows how much space is used in each of the sections (the .stab and .stabstr sections

hold the debugging information and won’t make it into the ROM file.)

An even more useful option is -S. This option disassembles the binary file and intersperses the source code in the

output! This method is much better, in my opinion, than using the -S with the compiler because this listing includes

routines from the libraries and the vector table contents. Also, all the “fix-ups” have been satisfied. In other words,

the listing generated by this option reflects the actual code that the processor will run.

% avr-objdump -S demo.out

This command generates the output shown in Example 2-2.

Chapter 2. Using the GNU Tools

Example 2-2. Disassembly of Demo Application

demo.out: file format elf32-avr

Disassembly of section .text:

00000000 <.start_of_init>: 0: 0a c0 rjmp .+20 ; 0x 2: 21 c0 rjmp .+66 ; 0x 4: 20 c0 rjmp .+64 ; 0x 6: 1f c0 rjmp .+62 ; 0x 8: 1e c0 rjmp .+60 ; 0x a: 1f c0 rjmp .+62 ; 0x4a c: 1c c0 rjmp .+56 ; 0x e: 1b c0 rjmp .+54 ; 0x 10: 1a c0 rjmp .+52 ; 0x 12: 19 c0 rjmp .+50 ; 0x 14: 18 c0 rjmp .+48 ; 0x

00000016 <real_init>: 16: 11 24 eor r1, r 18: 1f be out 0x3f, r1 ; 63 1a: 20 e0 ldi r18, 0x00 ; 0 1c: a8 95 wdr 1e: 21 bd out 0x21, r18 ; 33 20: 20 e0 ldi r18, 0x00 ; 0 22: 25 bf out 0x35, r18 ; 53 24: ec ee ldi r30, 0xEC ; 236 26: f0 e0 ldi r31, 0x00 ; 0 28: a0 e6 ldi r26, 0x60 ; 96 2a: b0 e0 ldi r27, 0x00 ; 0 2c: 03 c0 rjmp .+6 ; 0x

0000002e <.copy_data_loop>: 2e: c8 95 lpm 30: 31 96 adiw r30, 0x01 ; 1 32: 0d 92 st X+, r

00000034 <.copy_data_start>: 34: a0 36 cpi r26, 0x60 ; 96 36: d9 f7 brne .-10 ; 0x2e 38: a0 e6 ldi r26, 0x60 ; 96 3a: b0 e0 ldi r27, 0x00 ; 0 3c: 01 c0 rjmp .+2 ; 0x

0000003e <.zero_bss_loop>: 3e: 1d 92 st X+, r

00000040 <.zero_bss_start>: 40: a4 36 cpi r26, 0x64 ; 100 42: e9 f7 brne .-6 ; 0x3e 44: 4c c0 rjmp .+152 ; 0xde

Chapter 2. Using the GNU Tools

9e: 90 93 63 00 sts 0x0063, r a2: 80 93 62 00 sts 0x0062, r break; } __outw(pwm, OCR1L); a6: 80 91 60 00 lds r24, 0x aa: 90 91 61 00 lds r25, 0x ae: 9b bd out 0x2b, r25 ; 43 b0: 8a bd out 0x2a, r24 ; 42 b2: 9f 91 pop r b4: 8f 91 pop r b6: 2f 91 pop r b8: 0f 90 pop r ba: 0f be out 0x3f, r0 ; 63 bc: 0f 90 pop r be: 1f 90 pop r c0: 18 95 reti

000000c2 : }

void ioinit(void) { #if defined(COM11) outp(BV(PWM10)|BV(PWM11)|BV(COM11), TCCR1A); /* tmr1 is 10-bit PWM / #elif defined(COM1A1) outp(BV(PWM10)|BV(PWM11)|BV(COM1A1), TCCR1A); / tmr1 is 10-bit PWM */ c2: 83 e8 ldi r24, 0x83 ; 131 c4: 8f bd out 0x2f, r24 ; 47 #else

error "need either COM1A1 or COM11"

#endif outp(BV(CS10), TCCR1B); /* tmr1 running on full MCU clock */ c6: 81 e0 ldi r24, 0x01 ; 1 c8: 8e bd out 0x2e, r24 ; 46

__outw(0, OCR1L); /* set PWM value to 0 */ ca: 80 e0 ldi r24, 0x00 ; 0 cc: 90 e0 ldi r25, 0x00 ; 0 ce: 9b bd out 0x2b, r25 ; 43 d0: 8a bd out 0x2a, r24 ; 42

outp(BV(OC1), DDRB); /* enable OC1 and PB2 as output */ d2: 88 e0 ldi r24, 0x08 ; 8 d4: 87 bb out 0x17, r24 ; 23 #endif }

extern inline void timer_enable_int (unsigned char ints) { d6: 80 e8 ldi r24, 0x80 ; 128 #ifdef TIMSK

Chapter 2. Using the GNU Tools

outp (ints, TIMSK); d8: 89 bf out 0x39, r24 ; 57

timer_enable_int(BV(TOIE1)); sei(); /* enable interrupts */ da: 78 94 sei } dc: 08 95 ret

000000de :

int main(void) { de: cf ed ldi r28, 0xDF ; 223 e0: d0 e0 ldi r29, 0x00 ; 0 e2: de bf out 0x3e, r29 ; 62 e4: cd bf out 0x3d, r28 ; 61 ioinit(); e6: ed df rcall .-38 ; 0xc

for (;;) e8: ff cf rjmp .-2 ; 0xe

000000ea <stop_progIi>: ea: ff cf rjmp .-2 ; 0xea

2.3. “Map” Files

avr-objdump is very useful, but sometimes it’s necessary to see information about the link that can only be

generated by the linker. A map file contains this information. A map file is useful for monitoring the sizes of your

code and data. It also shows where modules are loaded and which modules were loaded from libraries. It is yet

another view of your application. To get a map file, I usually add -Wl,-Map,demo.map to my link command. Relink

the application using the following command to generate demo.map (a portion of which is shown in Example 2-3.

% avr-gcc -g -mmcu=at90s2313 -Wl,-Map,demo.map -o demo.out demo.o

Some points of interest in the map file are:

Ê The .text segment (where program instructions are stored) starts at location 0x0.

Ë The next available address in the .text segment is location 0xec, so the instructions use up 234 bytes of FLASH.

Ì The .data segment (where initialized static variables are stored) starts at location 0x60, which is the first address

after the register bank on a 2313 processor.

Í The next available address in the .data segment is also location 0x60, so the application has no initialized data.

Î The .bss segment (where uninitialized data is stored) starts at location 0x60.