<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
<title>avr-libc: A simple project</title>
<link href="dox.css" rel="stylesheet" type="text/css">
</head>
<body>
<center>
<table width="80%">
<tr>
<td align="left"><a href="http://www.nongnu.org/avr-libc/">AVR Libc Home Page</a></td>
<td align="center" colspan=4><img src="avrs.png" alt="AVRs" align="middle" border="0"></td>
<td align="right"><a href="https://savannah.nongnu.org/projects/avr-libc/">AVR Libc Development Pages</a></td>
</tr>
<tr>
<td align="center" width="13%"><a href="index.html">Main Page</a></td>
<td align="center" width="13%"><a href="pages.html">User Manual</a></td>
<td align="center" width="13%"><a href="modules.html">Library Reference</a></td>
<td align="center" width="13%"><a href="FAQ.html">FAQ</a></td>
<td align="center" width="13%"><a href="globals.html">Alphabetical Index</a></td>
<td align="center" width="13%"><a href="group__demos.html">Example Projects</a></td>
</tr>
</table>
</center>
<hr width="80%">
<!-- Generated by Doxygen 1.6.1 -->
<div class="contents">
<h1>A simple project<br/>
<small>
[<a class="el" href="group__demos.html">Demo projects</a>]</small>
</h1><table border="0" cellpadding="0" cellspacing="0">
</table>
<p>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 <code>Makefile</code> can be configured.</p>
<h2><a class="anchor" id="demo_project_desc">
The Project</a></h2>
<p>This project will use the pulse-width modulator (<code>PWM</code>) 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 <a class="el" href="group__demo__project.html#demo_project_schematic">schematic diagram</a>. If you have a development kit, you should be able to use it, rather than build the circuit, for this project.</p>
<dl class="note"><dt><b>Note:</b></dt><dd>Meanwhile, the AT90S2313 became obsolete. Either use its successor, the (pin-compatible) ATtiny2313 for the project, or perhaps the ATmega8 or one of its successors (ATmega48/88/168) which have become quite popular since the original demo project had been established. For all these more modern devices, it is no longer necessary to use an external crystal for clocking as they ship with the internal 1 MHz oscillator enabled, so C1, C2, and Q1 can be omitted. Normally, for this experiment, the external circuitry on /RESET (R1, C3) can be omitted as well, leaving only the AVR, the LED, the bypass capacitor C4, and perhaps R2. For the ATmega8/48/88/168, use PB1 (pin 15 at the DIP-28 package) to connect the LED to. Additionally, this demo has been ported to many different other AVRs. The location of the respective OC pin varies between different AVRs, and it is mandated by the AVR hardware.</dd></dl>
<p><a class="anchor" id="demo_project_schematic"></a> </p>
<div align="center">
<img src="demo.png" alt="demo.png"/>
<p><strong>Schematic of circuit for demo project</strong></p></div>
<p>The source code is given in <a class="el" href="group__demo__project.html#demo_project_src">demo.c</a>. For the sake of this example, create a file called <code>demo.c</code> containing this source code. Some of the more important parts of the code are:</p>
<dl class="user"><dt><b>Note [1]:</b></dt><dd>As the AVR microcontroller series has been developed during the past years, new features have been added over time. Even though the basic concepts of the timer/counter1 are still the same as they used to be back in early 2001 when this simple demo was written initially, the names of registers and bits have been changed slightly to reflect the new features. Also, the port and pin mapping of the output compare match 1A (or 1 for older devices) pin which is used to control the LED varies between different AVRs. The file <code>iocompat.h</code> tries to abstract between all this differences using some preprocessor <code>#ifdef</code> statements, so the actual program itself can operate on a common set of symbolic names. The macros defined by that file are:</dd></dl>
<ul>
<li><code>OCR</code> the name of the OCR register used to control the PWM (usually either OCR1 or OCR1A)</li>
<li><code>DDROC</code> the name of the DDR (data direction register) for the OC output</li>
<li><code>OC1</code> the pin number of the OC1[A] output within its port</li>
<li><code>TIMER1_TOP</code> 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)</li>
<li><code>TIMER1_PWM_INIT</code> the initialization bits to be set into control register 1A in order to setup 10-bit (or 8-bit) phase and frequency correct PWM mode</li>
<li><code>TIMER1_CLOCKSOURCE</code> 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 PWMs</li>
</ul>
<dl class="user"><dt><b>Note [2]:</b></dt><dd><a class="el" href="group__avr__interrupts.html#gad28590624d422cdf30d626e0a506255f">ISR()</a> is a macro that marks the function as an interrupt routine. In this case, the function will get called when timer 1 overflows. Setting up interrupts is explained in greater detail in <a class="el" href="group__avr__interrupts.html"><avr/interrupt.h>: Interrupts</a>.</dd></dl>
<dl class="user"><dt><b>Note [3]:</b></dt><dd>The <code>PWM</code> is being used in 10-bit mode, so we need a 16-bit variable to remember the current value.</dd></dl>
<dl class="user"><dt><b>Note [4]:</b></dt><dd>This section determines the new value of the <code>PWM</code>.</dd></dl>
<dl class="user"><dt><b>Note [5]:</b></dt><dd>Here's where the newly computed value is loaded into the <code>PWM</code> 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 <code>TEMP</code>), see the appropriate <a class="el" href="FAQ.html#faq_16bitio">FAQ entry</a>.</dd></dl>
<dl class="user"><dt><b>Note [6]:</b></dt><dd>This routine gets called after a reset. It initializes the <code>PWM</code> and enables interrupts.</dd></dl>
<dl class="user"><dt><b>Note [7]:</b></dt><dd>The main loop of the program does nothing -- all the work is done by the interrupt routine! The <code>sleep_mode()</code> 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.</dd></dl>
<dl class="user"><dt><b>Note [8]:</b></dt><dd>Early AVR devices saturate their outputs at rather low currents when sourcing current, so the LED can be connected directly, the resulting current through the LED will be about 15 mA. For modern parts (at least for the ATmega 128), however Atmel has drastically increased the IO source capability, so when operating at 5 V Vcc, R2 is needed. Its value should be about 150 Ohms. When operating the circuit at 3 V, it can still be omitted though.</dd></dl>
<h2><a class="anchor" id="demo_project_src">
The Source Code</a></h2>
<div class="fragment"><pre class="fragment"><span class="comment">/*</span>
<span class="comment"> * ----------------------------------------------------------------------------</span>
<span class="comment"> * "THE BEER-WARE LICENSE" (Revision 42):</span>
<span class="comment"> * <joerg@FreeBSD.ORG> wrote this file. As long as you retain this notice you</span>
<span class="comment"> * can do whatever you want with this stuff. If we meet some day, and you think</span>
<span class="comment"> * this stuff is worth it, you can buy me a beer in return. Joerg Wunsch</span>
<span class="comment"> * ----------------------------------------------------------------------------</span>
<span class="comment"> *</span>
<span class="comment"> * Simple AVR demonstration. Controls a LED that can be directly</span>
<span class="comment"> * connected from OC1/OC1A to GND. The brightness of the LED is</span>
<span class="comment"> * controlled with the PWM. After each period of the PWM, the PWM</span>
<span class="comment"> * value is either incremented or decremented, that's all.</span>
<span class="comment"> *</span>
<span class="comment"> * $Id: demo.c,v 1.9 2006/01/05 21:30:10 joerg_wunsch Exp $</span>
<span class="comment"> */</span>
<span class="preprocessor">#include <<a class="code" href="inttypes_8h.html">inttypes.h</a>></span>
<span class="preprocessor">#include <<a class="code" href="io_8h.html">avr/io.h</a>></span>
<span class="preprocessor">#include <<a class="code" href="interrupt_8h.html">avr/interrupt.h</a>></span>
<span class="preprocessor">#include <<a class="code" href="sleep_8h.html">avr/sleep.h</a>></span>
<span class="preprocessor">#include "iocompat.h"</span> <span class="comment">/* Note [1] */</span>
<span class="keyword">enum</span> { UP, DOWN };
<a class="code" href="group__avr__interrupts.html#gad28590624d422cdf30d626e0a506255f">ISR</a> (TIMER1_OVF_vect) <span class="comment">/* Note [2] */</span>
{
<span class="keyword">static</span> <a class="code" href="group__avr__stdint.html#ga1f1825b69244eb3ad2c7165ddc99c956">uint16_t</a> pwm; <span class="comment">/* Note [3] */</span>
<span class="keyword">static</span> <a class="code" href="group__avr__stdint.html#gaba7bc1797add20fe3efdf37ced1182c5">uint8_t</a> direction;
<span class="keywordflow">switch</span> (direction) <span class="comment">/* Note [4] */</span>
{
<span class="keywordflow">case</span> UP:
<span class="keywordflow">if</span> (++pwm == TIMER1_TOP)
direction = DOWN;
<span class="keywordflow">break</span>;
<span class="keywordflow">case</span> DOWN:
<span class="keywordflow">if</span> (--pwm == 0)
direction = UP;
<span class="keywordflow">break</span>;
}
OCR = pwm; <span class="comment">/* Note [5] */</span>
}
<span class="keywordtype">void</span>
ioinit (<span class="keywordtype">void</span>) <span class="comment">/* Note [6] */</span>
{
<span class="comment">/* Timer 1 is 10-bit PWM (8-bit PWM on some ATtinys). */</span>
TCCR1A = TIMER1_PWM_INIT;
<span class="comment">/*</span>
<span class="comment"> * Start timer 1.</span>
<span class="comment"> *</span>
<span class="comment"> * NB: TCCR1A and TCCR1B could actually be the same register, so</span>
<span class="comment"> * take care to not clobber it.</span>
<span class="comment"> */</span>
TCCR1B |= TIMER1_CLOCKSOURCE;
<span class="comment">/*</span>
<span class="comment"> * Run any device-dependent timer 1 setup hook if present.</span>
<span class="comment"> */</span>
<span class="preprocessor">#if defined(TIMER1_SETUP_HOOK)</span>
<span class="preprocessor"></span> TIMER1_SETUP_HOOK();
<span class="preprocessor">#endif</span>
<span class="preprocessor"></span>
<span class="comment">/* Set PWM value to 0. */</span>
OCR = 0;
<span class="comment">/* Enable OC1 as output. */</span>
DDROC = <a class="code" href="group__avr__sfr.html#ga11643f271076024c395a93800b3d9546">_BV</a> (OC1);
<span class="comment">/* Enable timer 1 overflow interrupt. */</span>
TIMSK = <a class="code" href="group__avr__sfr.html#ga11643f271076024c395a93800b3d9546">_BV</a> (TOIE1);
<a class="code" href="group__avr__interrupts.html#gaad5ebd34cb344c26ac87594f79b06b73">sei</a> ();
}
<span class="keywordtype">int</span>
main (<span class="keywordtype">void</span>)
{
ioinit ();
<span class="comment">/* loop forever, the interrupts are doing the rest */</span>
<span class="keywordflow">for</span> (;;) <span class="comment">/* Note [7] */</span>
sleep_mode();
<span class="keywordflow">return</span> (0);
}
</pre></div><h2><a class="anchor" id="demo_project_compile">
Compiling and Linking</a></h2>
<p>This first thing that needs to be done is compile the source. When compiling, the compiler needs to know the processor type so the <code>-mmcu</code> option is specified. The <code>-Os</code> option will tell the compiler to optimize the code for efficient space usage (at the possible expense of code execution speed). The <code>-g</code> is used to embed debug info. The debug info is useful for disassemblies and doesn't end up in the <code></code>.hex files, so I usually specify it. Finally, the <code>-c</code> 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.</p>
<div class="fragment"><pre class="fragment">
$ avr-gcc -g -Os -mmcu=atmega8 -c demo.c
</pre></div><p>The compilation will create a <code>demo.o</code> file. Next we link it into a binary called <code>demo.elf</code>.</p>
<div class="fragment"><pre class="fragment">
$ avr-gcc -g -mmcu=atmega8 -o demo.elf demo.o
</pre></div><p>It is important to specify the MCU type when linking. The compiler uses the <code>-mmcu</code> 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.</p>
<h2><a class="anchor" id="demo_project_obj">
Examining the Object File</a></h2>
<p></p>
<p>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 <code>avr-objdump</code>, 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.</p>
<p>For instance, to get a feel of the application's size, the <code>-h</code> option can be used. The output of this option shows how much space is used in each of the sections (the <code></code>.stab and <code></code>.stabstr sections hold the debugging information and won't make it into the ROM file).</p>
<p>An even more useful option is <code>-S</code>. 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 <code>-S</code> 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.</p>
<div class="fragment"><pre class="fragment">
$ avr-objdump -h -S demo.elf > demo.lst
</pre></div><p>Here's the output as saved in the <code>demo.lst</code> file:</p>
<div class="fragment"><pre class="fragment">
demo.elf: file format elf32-avr
Sections:
Idx Name Size VMA LMA File off Algn
0 .text 0000010a 00000000 00000000 00000074 2**1
CONTENTS, ALLOC, LOAD, READONLY, CODE
1 .bss 00000003 00800060 00800060 0000017e 2**0
ALLOC
2 .stab 00000b58 00000000 00000000 00000180 2**2
CONTENTS, READONLY, DEBUGGING
3 .stabstr 000007b0 00000000 00000000 00000cd8 2**0
CONTENTS, READONLY, DEBUGGING
Disassembly of section .text:
00000000 <__vectors>:
0: 12 c0 rjmp .+36 ; 0x26 <__ctors_end>
2: 7e c0 rjmp .+252 ; 0x100 <__bad_interrupt>
4: 7d c0 rjmp .+250 ; 0x100 <__bad_interrupt>
6: 7c c0 rjmp .+248 ; 0x100 <__bad_interrupt>
8: 7b c0 rjmp .+246 ; 0x100 <__bad_interrupt>
a: 7a c0 rjmp .+244 ; 0x100 <__bad_interrupt>
c: 79 c0 rjmp .+242 ; 0x100 <__bad_interrupt>
e: 78 c0 rjmp .+240 ; 0x100 <__bad_interrupt>
10: 25 c0 rjmp .+74 ; 0x5c <__vector_8>
12: 76 c0 rjmp .+236 ; 0x100 <__bad_interrupt>
14: 75 c0 rjmp .+234 ; 0x100 <__bad_interrupt>
16: 74 c0 rjmp .+232 ; 0x100 <__bad_interrupt>
18: 73 c0 rjmp .+230 ; 0x100 <__bad_interrupt>
1a: 72 c0 rjmp .+228 ; 0x100 <__bad_interrupt>
1c: 71 c0 rjmp .+226 ; 0x100 <__bad_interrupt>
1e: 70 c0 rjmp .+224 ; 0x100 <__bad_interrupt>
20: 6f c0 rjmp .+222 ; 0x100 <__bad_interrupt>
22: 6e c0 rjmp .+220 ; 0x100 <__bad_interrupt>
24: 6d c0 rjmp .+218 ; 0x100 <__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_copy_data>:
32: 10 e0 ldi r17, 0x00 ; 0
34: a0 e6 ldi r26, 0x60 ; 96
36: b0 e0 ldi r27, 0x00 ; 0
38: ea e0 ldi r30, 0x0A ; 10
3a: f1 e0 ldi r31, 0x01 ; 1
3c: 02 c0 rjmp .+4 ; 0x42 <__SREG__+0x3>
3e: 05 90 lpm r0, Z+
40: 0d 92 st X+, r0
42: a0 36 cpi r26, 0x60 ; 96
44: b1 07 cpc r27, r17
46: d9 f7 brne .-10 ; 0x3e <__SP_H__>
00000048 <__do_clear_bss>:
48: 10 e0 ldi r17, 0x00 ; 0
4a: a0 e6 ldi r26, 0x60 ; 96
4c: b0 e0 ldi r27, 0x00 ; 0
4e: 01 c0 rjmp .+2 ; 0x52 <.do_clear_bss_start>
00000050 <.do_clear_bss_loop>:
50: 1d 92 st X+, r1
00000052 <.do_clear_bss_start>:
52: a3 36 cpi r26, 0x63 ; 99
54: b1 07 cpc r27, r17
56: e1 f7 brne .-8 ; 0x50 <.do_clear_bss_loop>
58: 4a d0 rcall .+148 ; 0xee <main>
5a: 53 c0 rjmp .+166 ; 0x102 <exit>
0000005c <__vector_8>:
#include "iocompat.h" /* Note [1] */
enum { UP, DOWN };
ISR (TIMER1_OVF_vect) /* Note [2] */
{
5c: 1f 92 push r1
5e: 0f 92 push r0
60: 0f b6 in r0, 0x3f ; 63
62: 0f 92 push r0
64: 11 24 eor r1, r1
66: 2f 93 push r18
68: 8f 93 push r24
6a: 9f 93 push r25
static uint16_t pwm; /* Note [3] */
static uint8_t direction;
switch (direction) /* Note [4] */
6c: 80 91 60 00 lds r24, 0x0060
70: 88 23 and r24, r24
72: b9 f4 brne .+46 ; 0xa2 <__vector_8+0x46>
{
case UP:
if (++pwm == TIMER1_TOP)
74: 80 91 61 00 lds r24, 0x0061
78: 90 91 62 00 lds r25, 0x0062
7c: 01 96 adiw r24, 0x01 ; 1
7e: 90 93 62 00 sts 0x0062, r25
82: 80 93 61 00 sts 0x0061, r24
86: 23 e0 ldi r18, 0x03 ; 3
88: 8f 3f cpi r24, 0xFF ; 255
8a: 92 07 cpc r25, r18
8c: f9 f0 breq .+62 ; 0xcc <__vector_8+0x70>
if (--pwm == 0)
direction = UP;
break;
}
OCR = pwm; /* Note [5] */
8e: 9b bd out 0x2b, r25 ; 43
90: 8a bd out 0x2a, r24 ; 42
}
92: 9f 91 pop r25
94: 8f 91 pop r24
96: 2f 91 pop r18
98: 0f 90 pop r0
9a: 0f be out 0x3f, r0 ; 63
9c: 0f 90 pop r0
9e: 1f 90 pop r1
a0: 18 95 reti
ISR (TIMER1_OVF_vect) /* Note [2] */
{
static uint16_t pwm; /* Note [3] */
static uint8_t direction;
switch (direction) /* Note [4] */
a2: 81 30 cpi r24, 0x01 ; 1
a4: 29 f0 breq .+10 ; 0xb0 <__vector_8+0x54>
a6: 80 91 61 00 lds r24, 0x0061
aa: 90 91 62 00 lds r25, 0x0062
ae: ef cf rjmp .-34 ; 0x8e <__vector_8+0x32>
if (++pwm == TIMER1_TOP)
direction = DOWN;
break;
case DOWN:
if (--pwm == 0)
b0: 80 91 61 00 lds r24, 0x0061
b4: 90 91 62 00 lds r25, 0x0062
b8: 01 97 sbiw r24, 0x01 ; 1
ba: 90 93 62 00 sts 0x0062, r25
be: 80 93 61 00 sts 0x0061, r24
c2: 00 97 sbiw r24, 0x00 ; 0
c4: 21 f7 brne .-56 ; 0x8e <__vector_8+0x32>
direction = UP;
c6: 10 92 60 00 sts 0x0060, r1
ca: e1 cf rjmp .-62 ; 0x8e <__vector_8+0x32>
switch (direction) /* Note [4] */
{
case UP:
if (++pwm == TIMER1_TOP)
direction = DOWN;
cc: 21 e0 ldi r18, 0x01 ; 1
ce: 20 93 60 00 sts 0x0060, r18
d2: dd cf rjmp .-70 ; 0x8e <__vector_8+0x32>
000000d4 <ioinit>:
void
ioinit (void) /* Note [6] */
{
/* Timer 1 is 10-bit PWM (8-bit PWM on some ATtinys). */
TCCR1A = TIMER1_PWM_INIT;
d4: 83 e8 ldi r24, 0x83 ; 131
d6: 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;
d8: 8e b5 in r24, 0x2e ; 46
da: 81 60 ori r24, 0x01 ; 1
dc: 8e bd out 0x2e, r24 ; 46
#if defined(TIMER1_SETUP_HOOK)
TIMER1_SETUP_HOOK();
#endif
/* Set PWM value to 0. */
OCR = 0;
de: 1b bc out 0x2b, r1 ; 43
e0: 1a bc out 0x2a, r1 ; 42
/* Enable OC1 as output. */
DDROC = _BV (OC1);
e2: 82 e0 ldi r24, 0x02 ; 2
e4: 87 bb out 0x17, r24 ; 23
/* Enable timer 1 overflow interrupt. */
TIMSK = _BV (TOIE1);
e6: 84 e0 ldi r24, 0x04 ; 4
e8: 89 bf out 0x39, r24 ; 57
sei ();
ea: 78 94 sei
}
ec: 08 95 ret
000000ee <main>:
int
main (void)
{
ioinit ();
ee: f2 df rcall .-28 ; 0xd4 <ioinit>
/* loop forever, the interrupts are doing the rest */
for (;;) /* Note [7] */
sleep_mode();
f0: 85 b7 in r24, 0x35 ; 53
f2: 80 68 ori r24, 0x80 ; 128
f4: 85 bf out 0x35, r24 ; 53
f6: 88 95 sleep
f8: 85 b7 in r24, 0x35 ; 53
fa: 8f 77 andi r24, 0x7F ; 127
fc: 85 bf out 0x35, r24 ; 53
fe: f8 cf rjmp .-16 ; 0xf0 <main+0x2>
00000100 <__bad_interrupt>:
100: 7f cf rjmp .-258 ; 0x0 <__vectors>
00000102 <exit>:
ASSEMBLY_CLIB_SECTION
.global _U(exit)
.type _U(exit), "function"
_U(exit):
cli
102: f8 94 cli
XJMP _U(_exit)
104: 00 c0 rjmp .+0 ; 0x106 <_exit>
00000106 <_exit>:
106: f8 94 cli
00000108 <__stop_program>:
108: ff cf rjmp .-2 ; 0x108 <__stop_program>
</pre></div><h2><a class="anchor" id="demo_project_map">
Linker Map Files</a></h2>
<p><code>avr-objdump</code> 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 <code><b>-Wl,-Map,demo.map</b></code> to my link command. Relink the application using the following command to generate <code>demo.map</code> (a portion of which is shown below).</p>
<div class="fragment"><pre class="fragment">
$ avr-gcc -g -mmcu=atmega8 -Wl,-Map,demo.map -o demo.elf demo.o
</pre></div><p>Some points of interest in the <code>demo.map</code> file are:</p>
<p><div class="fragment"><pre class="fragment">.rela.plt
*(.rela.plt)
.text 0x0000000000000000 0x10a
*(.vectors)
.vectors 0x0000000000000000 0x26 /builddir/build/BUILD/avr-libc-1.6.7/avr/lib/avr4/atmega8/crtm8.o
0x0000000000000000 __vectors
0x0000000000000000 __vector_default
*(.vectors)
*(.progmem.gcc*)
*(.progmem*)
0x0000000000000026 . = ALIGN (0x2)
0x0000000000000026 __trampolines_start = .
*(.trampolines)
.trampolines 0x0000000000000026 0x0 linker stubs
*(.trampolines*)
0x0000000000000026 __trampolines_end = .
*(.jumptables)
*(.jumptables*)
*(.lowtext)
*(.lowtext*)
0x0000000000000026 __ctors_start = .
</pre></div></p>
<p>The <code></code>.text segment (where program instructions are stored) starts at location 0x0.</p>
<p><div class="fragment"><pre class="fragment"> *(.fini2)
*(.fini2)
*(.fini1)
*(.fini1)
*(.fini0)
.fini0 0x0000000000000106 0x4 /usr/lib/gcc/avr/4.4.2/avr4/libgcc.a(_exit.o)
*(.fini0)
0x000000000000010a _etext = .
.data 0x0000000000800060 0x0 load address 0x000000000000010a
0x0000000000800060 PROVIDE (__data_start, .)
*(.data)
.data 0x0000000000800060 0x0 demo.o
.data 0x0000000000800060 0x0 /builddir/build/BUILD/avr-libc-1.6.7/avr/lib/avr4/atmega8/crtm8.o
.data 0x0000000000800060 0x0 /builddir/build/BUILD/avr-libc-1.6.7/avr/lib/avr4/<a class="code" href="group__avr__stdlib.html#ga137096a48cc0c731052cadfb69c39b34">exit</a>.o
.data 0x0000000000800060 0x0 /usr/lib/gcc/avr/4.4.2/avr4/libgcc.a(_exit.o)
.data 0x0000000000800060 0x0 /usr/lib/gcc/avr/4.4.2/avr4/libgcc.a(_copy_data.o)
.data 0x0000000000800060 0x0 /usr/lib/gcc/avr/4.4.2/avr4/libgcc.a(_clear_bss.o)
*(.data*)
*(.rodata)
*(.rodata*)
*(.gnu.linkonce.d*)
0x0000000000800060 . = ALIGN (0x2)
0x0000000000800060 _edata = .
0x0000000000800060 PROVIDE (__data_end, .)
.bss 0x0000000000800060 0x3
0x0000000000800060 PROVIDE (__bss_start, .)
*(.bss)
.bss 0x0000000000800060 0x3 demo.o
.bss 0x0000000000800063 0x0 /builddir/build/BUILD/avr-libc-1.6.7/avr/lib/avr4/atmega8/crtm8.o
.bss 0x0000000000800063 0x0 /builddir/build/BUILD/avr-libc-1.6.7/avr/lib/avr4/<a class="code" href="group__avr__stdlib.html#ga137096a48cc0c731052cadfb69c39b34">exit</a>.o
.bss 0x0000000000800063 0x0 /usr/lib/gcc/avr/4.4.2/avr4/libgcc.a(_exit.o)
.bss 0x0000000000800063 0x0 /usr/lib/gcc/avr/4.4.2/avr4/libgcc.a(_copy_data.o)
.bss 0x0000000000800063 0x0 /usr/lib/gcc/avr/4.4.2/avr4/libgcc.a(_clear_bss.o)
*(.bss*)
*(COMMON)
0x0000000000800063 PROVIDE (__bss_end, .)
0x000000000000010a __data_load_start = LOADADDR (.data)
0x000000000000010a __data_load_end = (__data_load_start + SIZEOF (.data))
.noinit 0x0000000000800063 0x0
0x0000000000800063 PROVIDE (__noinit_start, .)
*(.noinit*)
0x0000000000800063 PROVIDE (__noinit_end, .)
0x0000000000800063 _end = .
0x0000000000800063 PROVIDE (__heap_start, .)
.eeprom 0x0000000000810000 0x0
*(.eeprom*)
0x0000000000810000 __eeprom_end = .
</pre></div></p>
<p>The last address in the <code></code>.text segment is location <code>0x114</code> ( denoted by <code>_etext</code> ), so the instructions use up 276 bytes of FLASH.</p>
<p>The <code></code>.data segment (where initialized static variables are stored) starts at location <code>0x60</code>, which is the first address after the register bank on an ATmega8 processor.</p>
<p>The next available address in the <code></code>.data segment is also location <code>0x60</code>, so the application has no initialized data.</p>
<p>The <code></code>.bss segment (where uninitialized data is stored) starts at location <code>0x60</code>.</p>
<p>The next available address in the <code></code>.bss segment is location 0x63, so the application uses 3 bytes of uninitialized data.</p>
<p>The <code></code>.eeprom segment (where EEPROM variables are stored) starts at location 0x0.</p>
<p>The next available address in the <code></code>.eeprom segment is also location 0x0, so there aren't any EEPROM variables.</p>
<h2><a class="anchor" id="demo_ihex">
Generating Intel Hex Files</a></h2>
<p>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 <code></code>.hex files. The GNU utility that does this is called <code>avr-objcopy</code>.</p>
<p>The ROM contents can be pulled from our project's binary and put into the file demo.hex using the following command:</p>
<div class="fragment"><pre class="fragment">
$ avr-objcopy -j .text -j .data -O ihex demo.elf demo.hex
</pre></div><p>The resulting <code>demo.hex</code> file contains:</p>
<div class="fragment"><pre class="fragment">:1000000012C07EC07DC07CC07BC07AC079C078C081
:1000100025C076C075C074C073C072C071C070C096
:100020006FC06EC06DC011241FBECFE5D4E0DEBF2F
:10003000CDBF10E0A0E6B0E0EAE0F1E002C005903C
:100040000D92A036B107D9F710E0A0E6B0E001C0EC
:100050001D92A336B107E1F74AD053C01F920F9209
:100060000FB60F9211242F938F939F93809160006E
:100070008823B9F480916100909162000196909379
:1000800062008093610023E08F3F9207F9F09BBDEF
:100090008ABD9F918F912F910F900FBE0F901F904F
:1000A0001895813029F08091610090916200EFCF26
:1000B000809161009091620001979093620080931B
:1000C0006100009721F710926000E1CF21E02093BA
:1000D0006000DDCF83E88FBD8EB581608EBD1BBC17
:1000E0001ABC82E087BB84E089BF78940895F2DF70
:1000F00085B7806885BF889585B78F7785BFF8CF2E
:0A0100007FCFF89400C0F894FFCF01
:00000001FF
</pre></div><p>The <code>-j</code> option indicates that we want the information from the <code></code>.text and <code></code>.data segment extracted. If we specify the EEPROM segment, we can generate a <code></code>.hex file that can be used to program the EEPROM:</p>
<div class="fragment"><pre class="fragment">
$ avr-objcopy -j .eeprom --change-section-lma .eeprom=0 -O ihex demo.elf demo_eeprom.hex
</pre></div><p>There is no <code>demo_eeprom.hex</code> file written, as that file would be empty.</p>
<p>Starting with version 2.17 of the GNU binutils, the <code>avr-objcopy</code> command that used to generate the empty EEPROM files now aborts because of the empty input section <code></code>.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.</p>
<h2><a class="anchor" id="demo_make">
Letting Make Build the Project</a></h2>
<p>Rather than type these commands over and over, they can all be placed in a make file. To build the demo project using <code>make</code>, save the following in a file called <code>Makefile</code>.</p>
<dl class="note"><dt><b>Note:</b></dt><dd>This <code>Makefile</code> can only be used as input for the GNU version of <code>make</code>.</dd></dl>
<div class="fragment"><pre class="fragment">PRG = demo
OBJ = demo.o
<span class="preprocessor">#MCU_TARGET = at90s2313</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = at90s2333</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = at90s4414</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = at90s4433</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = at90s4434</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = at90s8515</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = at90s8535</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = atmega128</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = atmega1280</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = atmega1281</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = atmega1284p</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = atmega16</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = atmega163</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = atmega164p</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = atmega165</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = atmega165p</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = atmega168</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = atmega169</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = atmega169p</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = atmega2560</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = atmega2561</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = atmega32</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = atmega324p</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = atmega325</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = atmega3250</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = atmega329</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = atmega3290</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = atmega48</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = atmega64</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = atmega640</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = atmega644</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = atmega644p</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = atmega645</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = atmega6450</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = atmega649</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = atmega6490</span>
<span class="preprocessor"></span>MCU_TARGET = atmega8
<span class="preprocessor">#MCU_TARGET = atmega8515</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = atmega8535</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = atmega88</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = attiny2313</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = attiny24</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = attiny25</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = attiny26</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = attiny261</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = attiny44</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = attiny45</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = attiny461</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = attiny84</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = attiny85</span>
<span class="preprocessor"></span><span class="preprocessor">#MCU_TARGET = attiny861</span>
<span class="preprocessor"></span>OPTIMIZE = -O2
DEFS =
LIBS =
<span class="preprocessor"># You should not have to change anything below here.</span>
<span class="preprocessor"></span>
CC = avr-gcc
<span class="preprocessor"># Override is only needed by avr-lib build system.</span>
<span class="preprocessor"></span>
<span class="keyword">override</span> CFLAGS = -g -Wall $(OPTIMIZE) -mmcu=$(MCU_TARGET) $(DEFS)
<span class="keyword">override</span> LDFLAGS = -Wl,-Map,$(PRG).map
OBJCOPY = avr-objcopy
OBJDUMP = avr-objdump
all: $(PRG).elf lst text eeprom
$(PRG).elf: $(OBJ)
$(CC) $(CFLAGS) $(LDFLAGS) -o $@ $^ $(LIBS)
# dependency:
demo.o: demo.c iocompat.h
clean:
rm -rf *.o $(PRG).elf *.eps *.png *.pdf *.bak
rm -rf *.lst *.map $(EXTRA_CLEAN_FILES)
lst: $(PRG).lst
%.lst: %.elf
$(OBJDUMP) -h -S $< > $@
# Rules <span class="keywordflow">for</span> building the .text rom images
text: hex bin srec
hex: $(PRG).hex
bin: $(PRG).bin
srec: $(PRG).srec
%.hex: %.elf
$(OBJCOPY) -j .text -j .data -O ihex $< $@
%.srec: %.elf
$(OBJCOPY) -j .text -j .data -O srec $< $@
%.bin: %.elf
$(OBJCOPY) -j .text -j .data -O binary $< $@
# Rules <span class="keywordflow">for</span> building the .eeprom rom images
eeprom: ehex ebin esrec
ehex: $(PRG)_eeprom.hex
ebin: $(PRG)_eeprom.bin
esrec: $(PRG)_eeprom.srec
%_eeprom.hex: %.elf
$(OBJCOPY) -j .eeprom --change-section-lma .eeprom=0 -O ihex $< $@ \
|| { echo empty $@ not generated; <a class="code" href="group__avr__stdlib.html#ga137096a48cc0c731052cadfb69c39b34">exit</a> 0; }
%_eeprom.srec: %.elf
$(OBJCOPY) -j .eeprom --change-section-lma .eeprom=0 -O srec $< $@ \
|| { echo empty $@ not generated; <a class="code" href="group__avr__stdlib.html#ga137096a48cc0c731052cadfb69c39b34">exit</a> 0; }
%_eeprom.bin: %.elf
$(OBJCOPY) -j .eeprom --change-section-lma .eeprom=0 -O binary $< $@ \
|| { echo empty $@ not generated; <a class="code" href="group__avr__stdlib.html#ga137096a48cc0c731052cadfb69c39b34">exit</a> 0; }
<span class="preprocessor"># Every thing below here is used by avr-libc's build system and can be ignored</span>
<span class="preprocessor"></span><span class="preprocessor"># by the casual user.</span>
<span class="preprocessor"></span>
FIG2DEV = fig2dev
EXTRA_CLEAN_FILES = *.hex *.bin *.srec
dox: eps png pdf
eps: $(PRG).eps
png: $(PRG).png
pdf: $(PRG).pdf
%.eps: %.fig
$(FIG2DEV) -L eps $< $@
%.pdf: %.fig
$(FIG2DEV) -L pdf $< $@
%.png: %.fig
$(FIG2DEV) -L png $< $@
</pre></div><h2><a class="anchor" id="demo_sourceref">
Reference to the source code</a></h2>
<ul>
<li><a href="../examples/demo/demo.c">demo.c</a></li>
<li><a href="../examples/demo/iocompat.h">iocompat.h</a></li>
<li><a href="../examples/demo/Makefile">Makefile</a></li>
</ul>
</div>
<hr width="80%">
<p><center>Automatically generated by Doxygen 1.6.1 on 30 Nov 2009.</center></p>
</body>
</html>
