|
AVR-LibC
2.2.0
Standard C library for AVR-GCC
|
|
AVR-LibC Documentation |
 |
AVR-LibC Development Pages |
|||
Main Page |
User Manual |
Library Reference |
FAQ |
Example Projects |
File List |
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.
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 the schematic diagram. If you have a development kit, you should be able to use it, rather than build the circuit, for this project.
The source code is given in demo.c. For the sake of this example, create a file called demo.c containing this source code. Some of the more important parts of the code are:
iocompat.h tries to abstract between all this differences using some preprocessor #ifdef statements, so the actual program itself can operate on a common set of symbolic names. The macros defined by that file are:OCR the name of the OCR register used to control the PWM (usually either OCR1 or OCR1A)DDROC the name of the DDR (data direction register) for the OC outputOC1 the pin number of the OC1[A] output within its portTIMER1_TOP the TOP value of the timer used for the PWM (1023 for 10-bit PWMs, 255 for devices that can only handle an 8-bit PWM)TIMER1_PWM_INIT the initialization bits to be set into control register 1A in order to setup 10-bit (or 8-bit) phase and frequency correct PWM modeTIMER1_CLOCKSOURCE the clock bits to set in the respective control register to start the PWM timer; usually the timer runs at full CPU clock for 10-bit PWMs, while it runs on a prescaled clock for 8-bit PWMsPWM is being used in 10-bit mode, so we need a 16-bit variable to remember the current value.PWM.PWM register. Since we are in an interrupt routine, it is safe to use a 16-bit assignment to the register. Outside of an interrupt, the assignment should only be performed with interrupts disabled if there's a chance that an interrupt routine could also access this register (or another register that uses TEMP), see the appropriate FAQ entry.PWM and enables interrupts.sleep_mode() puts the processor on sleep until the next interrupt, to conserve power. Of course, that probably won't be noticable as we are still driving a LED, it is merely mentioned here to demonstrate the basic principle.This first thing that needs to be done is compile the source. When compiling, the compiler needs to know the processor type so the -mmcu option is specified. The -Os option will tell the compiler to optimize the code for efficient space usage (at the possible expense of code execution speed). The -g is used to embed debug info. The debug info is useful for disassemblies and doesn't end up in the .hex files, so I usually specify it. Finally, the -c tells the compiler to compile and stop – don't link. This demo is small enough that we could compile and link in one step. 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=atmega8 -c demo.c
The compilation will create a demo.o file. Next we link it into a binary called demo.elf.
$ avr-gcc -g -mmcu=atmega8 -o demo.elf 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. The output of this option 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 -h -S demo.elf > demo.lst
Here's the output as saved in the demo.lst file:
demo.elf: file format elf32-avr
Sections:
Idx Name Size VMA LMA File off Algn
0 .text 000000dc 00000000 00000000 00000094 2**1
CONTENTS, ALLOC, LOAD, READONLY, CODE
1 .data 00000000 00800060 000000dc 00000170 2**0
CONTENTS, ALLOC, LOAD, DATA
2 .bss 00000003 00800060 00800060 00000170 2**0
ALLOC
3 .stab 00000234 00000000 00000000 00000170 2**2
CONTENTS, READONLY, DEBUGGING
4 .stabstr 0000015e 00000000 00000000 000003a4 2**0
CONTENTS, READONLY, DEBUGGING
5 .comment 00000012 00000000 00000000 00000502 2**0
CONTENTS, READONLY
6 .note.gnu.avr.deviceinfo 0000003c 00000000 00000000 00000514 2**2
CONTENTS, READONLY
7 .debug_info 0000048c 00000000 00000000 00000550 2**0
CONTENTS, READONLY, DEBUGGING
8 .debug_abbrev 0000044e 00000000 00000000 000009dc 2**0
CONTENTS, READONLY, DEBUGGING
9 .debug_line 0000001d 00000000 00000000 00000e2a 2**0
CONTENTS, READONLY, DEBUGGING
10 .debug_str 0000017a 00000000 00000000 00000e47 2**0
CONTENTS, READONLY, DEBUGGING
Disassembly of section .text:
00000000 <__vectors>:
0: 12 c0 rjmp .+36 ; 0x26 <__ctors_end>
2: 5e c0 rjmp .+188 ; 0xc0 <__bad_interrupt>
4: 5d c0 rjmp .+186 ; 0xc0 <__bad_interrupt>
6: 5c c0 rjmp .+184 ; 0xc0 <__bad_interrupt>
8: 5b c0 rjmp .+182 ; 0xc0 <__bad_interrupt>
a: 5a c0 rjmp .+180 ; 0xc0 <__bad_interrupt>
c: 59 c0 rjmp .+178 ; 0xc0 <__bad_interrupt>
e: 58 c0 rjmp .+176 ; 0xc0 <__bad_interrupt>
10: 1a c0 rjmp .+52 ; 0x46 <__vector_8>
12: 56 c0 rjmp .+172 ; 0xc0 <__bad_interrupt>
14: 55 c0 rjmp .+170 ; 0xc0 <__bad_interrupt>
16: 54 c0 rjmp .+168 ; 0xc0 <__bad_interrupt>
18: 53 c0 rjmp .+166 ; 0xc0 <__bad_interrupt>
1a: 52 c0 rjmp .+164 ; 0xc0 <__bad_interrupt>
1c: 51 c0 rjmp .+162 ; 0xc0 <__bad_interrupt>
1e: 50 c0 rjmp .+160 ; 0xc0 <__bad_interrupt>
20: 4f c0 rjmp .+158 ; 0xc0 <__bad_interrupt>
22: 4e c0 rjmp .+156 ; 0xc0 <__bad_interrupt>
24: 4d c0 rjmp .+154 ; 0xc0 <__bad_interrupt>
00000026 <__ctors_end>:
26: 11 24 eor r1, r1
28: 1f be out 0x3f, r1 ; 63
2a: cf e5 ldi r28, 0x5F ; 95
2c: d4 e0 ldi r29, 0x04 ; 4
2e: de bf out 0x3e, r29 ; 62
30: cd bf out 0x3d, r28 ; 61
00000032 <__do_clear_bss>:
32: 20 e0 ldi r18, 0x00 ; 0
34: a0 e6 ldi r26, 0x60 ; 96
36: b0 e0 ldi r27, 0x00 ; 0
38: 01 c0 rjmp .+2 ; 0x3c <.do_clear_bss_start>
0000003a <.do_clear_bss_loop>:
3a: 1d 92 st X+, r1
0000003c <.do_clear_bss_start>:
3c: a3 36 cpi r26, 0x63 ; 99
3e: b2 07 cpc r27, r18
40: e1 f7 brne .-8 ; 0x3a <.do_clear_bss_loop>
42: 3f d0 rcall .+126 ; 0xc2 <main>
44: 47 c0 rjmp .+142 ; 0xd4 <exit>
00000046 <__vector_8>:
#include "iocompat.h" /* Note [1] */
enum { UP, DOWN };
ISR (TIMER1_OVF_vect) /* Note [2] */
{
46: 1f 92 push r1
48: 1f b6 in r1, 0x3f ; 63
4a: 1f 92 push r1
4c: 11 24 eor r1, r1
4e: 2f 93 push r18
50: 8f 93 push r24
52: 9f 93 push r25
static uint16_t pwm; /* Note [3] */
static uint8_t direction;
switch (direction) /* Note [4] */
54: 20 91 62 00 lds r18, 0x0062 ; 0x800062 <direction.1>
{
case UP:
if (++pwm == TIMER1_TOP)
58: 80 91 60 00 lds r24, 0x0060 ; 0x800060 <__DATA_REGION_ORIGIN__>
5c: 90 91 61 00 lds r25, 0x0061 ; 0x800061 <__DATA_REGION_ORIGIN__+0x1>
switch (direction) /* Note [4] */
60: 22 23 and r18, r18
62: a1 f0 breq .+40 ; 0x8c <__vector_8+0x46>
64: 21 30 cpi r18, 0x01 ; 1
66: 49 f4 brne .+18 ; 0x7a <__vector_8+0x34>
direction = DOWN;
break;
case DOWN:
if (--pwm == 0)
68: 01 97 sbiw r24, 0x01 ; 1
6a: 90 93 61 00 sts 0x0061, r25 ; 0x800061 <__DATA_REGION_ORIGIN__+0x1>
6e: 80 93 60 00 sts 0x0060, r24 ; 0x800060 <__DATA_REGION_ORIGIN__>
72: 00 97 sbiw r24, 0x00 ; 0
74: 11 f4 brne .+4 ; 0x7a <__vector_8+0x34>
direction = UP;
76: 10 92 62 00 sts 0x0062, r1 ; 0x800062 <direction.1>
break;
}
OCR = pwm; /* Note [5] */
7a: 9b bd out 0x2b, r25 ; 43
7c: 8a bd out 0x2a, r24 ; 42
}
7e: 9f 91 pop r25
80: 8f 91 pop r24
82: 2f 91 pop r18
84: 1f 90 pop r1
86: 1f be out 0x3f, r1 ; 63
88: 1f 90 pop r1
8a: 18 95 reti
if (++pwm == TIMER1_TOP)
8c: 01 96 adiw r24, 0x01 ; 1
8e: 90 93 61 00 sts 0x0061, r25 ; 0x800061 <__DATA_REGION_ORIGIN__+0x1>
92: 80 93 60 00 sts 0x0060, r24 ; 0x800060 <__DATA_REGION_ORIGIN__>
96: 8f 3f cpi r24, 0xFF ; 255
98: 23 e0 ldi r18, 0x03 ; 3
9a: 92 07 cpc r25, r18
9c: 71 f7 brne .-36 ; 0x7a <__vector_8+0x34>
direction = DOWN;
9e: 21 e0 ldi r18, 0x01 ; 1
a0: 20 93 62 00 sts 0x0062, r18 ; 0x800062 <direction.1>
a4: ea cf rjmp .-44 ; 0x7a <__vector_8+0x34>
000000a6 <ioinit>:
void
ioinit (void) /* Note [6] */
{
/* Timer 1 is 10-bit PWM (8-bit PWM on some ATtinys). */
TCCR1A = TIMER1_PWM_INIT;
a6: 83 e8 ldi r24, 0x83 ; 131
a8: 8f bd out 0x2f, r24 ; 47
* Start timer 1.
*
* NB: TCCR1A and TCCR1B could actually be the same register, so
* take care to not clobber it.
*/
TCCR1B |= TIMER1_CLOCKSOURCE;
aa: 8e b5 in r24, 0x2e ; 46
ac: 81 60 ori r24, 0x01 ; 1
ae: 8e bd out 0x2e, r24 ; 46
#if defined(TIMER1_SETUP_HOOK)
TIMER1_SETUP_HOOK();
#endif
/* Set PWM value to 0. */
OCR = 0;
b0: 1b bc out 0x2b, r1 ; 43
b2: 1a bc out 0x2a, r1 ; 42
/* Enable OC1 as output. */
DDROC = _BV (OC1);
b4: 82 e0 ldi r24, 0x02 ; 2
b6: 87 bb out 0x17, r24 ; 23
/* Enable timer 1 overflow interrupt. */
TIMSK = _BV (TOIE1);
b8: 84 e0 ldi r24, 0x04 ; 4
ba: 89 bf out 0x39, r24 ; 57
sei ();
bc: 78 94 sei
}
be: 08 95 ret
000000c0 <__bad_interrupt>:
c0: 9f cf rjmp .-194 ; 0x0 <__vectors>
000000c2 <main>:
int
main (void)
{
ioinit ();
c2: f1 df rcall .-30 ; 0xa6 <ioinit>
/* loop forever, the interrupts are doing the rest */
for (;;) /* Note [7] */
sleep_mode();
c4: 85 b7 in r24, 0x35 ; 53
c6: 80 68 ori r24, 0x80 ; 128
c8: 85 bf out 0x35, r24 ; 53
ca: 88 95 sleep
cc: 85 b7 in r24, 0x35 ; 53
ce: 8f 77 andi r24, 0x7F ; 127
d0: 85 bf out 0x35, r24 ; 53
d2: f8 cf rjmp .-16 ; 0xc4 <main+0x2>
000000d4 <exit>:
d4: f8 94 cli
d6: 00 c0 rjmp .+0 ; 0xd8 <_exit>
000000d8 <_exit>:
d8: f8 94 cli
000000da <__stop_program>:
da: ff cf rjmp .-2 ; 0xda <__stop_program>
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 below).
$ avr-gcc -g -mmcu=atmega8 -Wl,-Map,demo.map -o demo.elf demo.o
Some points of interest in the demo.map file are:
The .text segment (where program instructions are stored) starts at location 0x0.
The last address in the .text segment is location 0x114 ( denoted by _etext ), so the instructions use up 276 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 an ATmega8 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.
The next available address in the .bss segment is location 0x63, so the application uses 3 bytes of uninitialized data.
The .eeprom segment (where EEPROM variables are stored) starts at location 0x0.
The next available address in the .eeprom segment is also location 0x0, so there aren't any EEPROM variables.
We have a binary of the application, but how do we get it into the processor? Most (if not all) programmers will not accept a GNU executable as an input file, so we need to do a little more processing. The next step is to extract portions of the binary and save the information into .hex files. The GNU utility that does this is called avr-objcopy.
The ROM contents can be pulled from our project's binary and put into the file demo.hex using the following command:
$ avr-objcopy -j .text -j .data -O ihex demo.elf demo.hex
The resulting demo.hex file contains:
:1000000012C05EC05DC05CC05BC05AC059C058C061 :100010001AC056C055C054C053C052C051C050C081 :100020004FC04EC04DC011241FBECFE5D4E0DEBF8F :10003000CDBF20E0A0E6B0E001C01D92A336B2071C :10004000E1F73FD047C01F921FB61F9211242F9394 :100050008F939F9320916200809160009091610046 :100060002223A1F0213049F40197909361008093FD :100070006000009711F4109262009BBD8ABD9F91B1 :100080008F912F911F901FBE1F90189501969093EE :100090006100809360008F3F23E0920771F721E0B9 :1000A00020936200EACF83E88FBD8EB581608EBD5C :1000B0001BBC1ABC82E087BB84E089BF789408959A :1000C0009FCFF1DF85B7806885BF889585B78F772B :0C00D00085BFF8CFF89400C0F894FFCF73 :00000001FF
The -j option indicates that we want the information from the .text and .data segment extracted. If we specify the EEPROM segment, we can generate a .hex file that can be used to program the EEPROM:
$ avr-objcopy -j .eeprom --change-section-lma .eeprom=0 -O ihex demo.elf demo_eeprom.hex
There is no demo_eeprom.hex file written, as that file would be empty.
Starting with version 2.17 of the GNU binutils, the avr-objcopy command that used to generate the empty EEPROM files now aborts because of the empty input section .eeprom, so these empty files are not generated. It also signals an error to the Makefile which will be caught there, and makes it print a message about the empty file not being generated.
Rather than type these commands over and over, they can all be placed in a make file. To build the demo project using make, save the following in a file called Makefile.
Makefile can only be used as input for the GNU version of make.
1.9.6