WinAVR User Manual - 20050214

WinAVRTM User Manual - 20050214

by Eric B. Weddington
<[email protected]>

WinAVRTM (pronounced "whenever") is a suite of executable, open source software development tools for
the Atmel AVR series of RISC microprocessors hosted on the Windows platform. It includes the GNU GCC
compiler for C and C++.

1.0 What's New

Below is just a sample of what's new.

● README:

The WinAVR README file has now become the WinAVR User Manual and is
available in HTML.

● GCC:

New version, 3.4.3.

● avr-libc:

New version, 1.2.3. Many bugs fixed.

● avrdude:

Built from CVS after 4.4.0.

New safe mode added. Will attempt to save the state of the fuses from
accidental change.

● uisp:

New version, 20050207.

● avarice:

New version, 2.3.

● SRecord

New version: 1.21

(Special Thanks to Jörg Wunsch for building this at the last minute!)

● Programmers Notepad

New version, 2.0.5.48.

● avrdude-gui:

http://winavr.sourceforge.net/WinAVR-user-manual.html (1 de 21) [8/30/2010 6:05:42 PM]

 WinAVR User Manual - 20050214

New package! This is a GUI fronted to the avrdude downloader software.

WARNING: avrdude-gui is in an alpha stage and is included as a preview. Use at your own risk!

● dwarfdump 20041122:

New package! This utility can display lots of information about your ELF file
that contains DWARF2 debugging information.

● GNU Make:

New version, 3.80. Now a native Win32 executable.

● avr-mem script

New addition. This is used by the Makefile Template to report memory usage.

● Makefile Template

Integrate the new avr-mem script to report memory usage.

New dependency generation flags.
New rule to generate preprocessed output for GCC bug reports.
New experimental rule to start debugging: make debug.
New macro to define a CPU frequency for all source code files.
DWARF2 is now the default debugging information.

● Installer:

The uninstaller is now smarter, it installs a log of the files that are included
and it only removes the files from the log.

A registry key was put back in giving the location of the installation. Look in
HKLM\SOFTWARE\WinAVR.

It is now optional to install Programmers Notepad.

2.0 WinAVR Installation

This section describes various information and notes about the installation of WinAVR.

2.1 Manifest

1. GNU Binutils 2.15 + coff-avr-patch (20030831)

Binary utilities for AVR target (including assembler, linker, etc.).

With the following patches:

❍ coff-avr-patch
The avr-coff patch adds coff-avr and coff-ext-avr targets for avr-objcopy and avr-
objdump. This provides an ELF to COFF converter. This is mainly for users of commercial debuggers.
❍ avr-new-devs patch

http://winavr.sourceforge.net/WinAVR-user-manual.html (2 de 21) [8/30/2010 6:05:42 PM]

WinAVR User Manual - 20050214

This adds new AVR devices to the toolchain: tiny13, tiny2313, at90can128, mega48, mega88,
mega168.
❍ no-lma-eeprom patch
This patch fixes a bug in the linker scripts to ensure that the .eeprom section is correctly relocated. See
this thread in the avarice mailing lists for more information about this issue.
2. GNU Compiler Collection (GCC) 3.4.3

C language and C++ language compiler for AVR target. There are
caveats for using the C++ compiler. See the installed avr-libc
User Manual in the <InstallDir>\doc directory.

With the following patches:

binary constants patch

❍

Written by Jörg Wunsch. This adds the ability to write and use binary constants in the form of:
0b01011010
❍ misspelled signal names patch
This patch will detect misspelled ISR signal names and provide warnings to the user.
❍ avr-new-devs patch
This adds new AVR devices to the toolchain: tiny13, tiny2313, at90can128, mega48, mega88,
mega168.
❍ collect2 patch and fixinc patch
These two patches allow GCC to be built for a Windows host.
3. avr-libc 1.2.3

C Standard Library for AVR.

4. avrdude 4.4.0cvs

avrdude is an open source programmer software that is user extensible.

5. avrdude-gui 0.2.0

avrdude-gui is a GUI front end to the avrdude program.

WARNING: avrdude-gui is in an alpha stage and is included as a preview. Use at your own risk!
❍

6. uisp 20050207

uisp is another open source programmer software.

7. GNU Debugger (GDB) 6.1

It's a debugger.

8. Insight 6.1

This is GDB with a GUI!

With the following patches:

❍ gdbtk-register.c
This is CVS revision 1.25 of the gdb/gdbtk/generic/gdbtk-register.c file which fixes Insight
PR 259
❍ insightexe patch
This patch allows avr-insight.exe to be created.
❍ cygwin-build patch

http://winavr.sourceforge.net/WinAVR-user-manual.html (3 de 21) [8/30/2010 6:05:42 PM]

 WinAVR User Manual - 20050214

This patch allows Insight to be built with more recent versions of Cygwin.
9. avarice 2.3

avarice is a program for interfacing the Atmel JTAG ICE to GDB and users
can debug their AVR. Use it in conjunction with GDB.

10. simulavr 0.1.2.1

simulavr is used in conjunction with GDB to provide AVR simulation.

11. dwarfdump 20041122

This utility can display lots of information about your ELF file that
contains DWARF2 debugging information.

12. SRecord 1.21

SRecord is a collection of powerful tools for manipulating EPROM load files.

It reads and writes numerous EPROM file formats, and can perform many
different manipulations.

13. MFile

An automatic makefile generator for AVR GCC.

14. Programmers Notepad 2.0.5.32

Programming editor and IDE. This editor includes the Scintilla editor
component.

15. TkInfo 2.6

A graphical browser for files in the GNU hypertext "info" format,

written in Tcl/Tk.

16. Cygwin DLLs

Certain DLLs from the Cygwin project are required for specific included
packages. See the Build Notes section for which packages require which DLL.

NOTE: Not all executables require these Cygwin DLLs.

17. Many native Win32 GNU programs and utilities including make and bash.
18. Tofrodos 1.6

A command-line text file line-ending convertor.

19. A Makefile Template for you to use in your projects.

20. Documentation in many formats for the various projects.
21. Source code patches used to build the various projects.

2.2 Layout

Listed below are some directories you might want to know about.

http://winavr.sourceforge.net/WinAVR-user-manual.html (4 de 21) [8/30/2010 6:05:42 PM]

 WinAVR User Manual - 20050214

<install> = The directory where you installed WinAVR.

<install>\bin

The AVR software development programs. This directory should be in your PATH environment variable. This
includes:

GNU Binutils
❍

GCC❍

❍ avrdude
❍ avrdude-gui
❍ uisp
❍ GNU Debugger (GDB)
❍ Insight
❍ AVaRICE
❍ SimulAVR
❍ SRecord
❍ TkInfo
❍ Various required DLLs
<install>\utils\bin

A collection of Unix programs built for the Windows platform. The programs make and sh (bash) reside here.
This directory should be in your PATH environment variable.
<install>\avr\lib

avr-libc libraries, startup files, linker scripts, and stuff.

<install>\avr\include

avr-libc header files. This is where, for example, #include <string.h> comes from.
<install>\avr\include\avr

avr-libc header files specific to the AVR microprocessor. This is where, for example, #include <avr/io.h>
comes from.
<install>\lib

GCC libraries, other libraries,headers and stuff.

<install>\libexec

GCC program components

<install>\doc

Various documentation. Before asking, RTFM! :-)

<install>\info

This also contains much documentation in the Info format.

<install>\examples

Example projects with source code. Have fun!

<install>\sample

Sample makefile (see below). Batch files to use in compiling from AVR Studio (see below).
<install>\pn

Programmers Notepad

http://winavr.sourceforge.net/WinAVR-user-manual.html (5 de 21) [8/30/2010 6:05:42 PM]

 WinAVR User Manual - 20050214

<install>\mfile

MFile
<install>\source

Documentation on where to find the source code for the various projects and source code patches that were
used to build the tools.

2.3 PATH Environment Variable

There are two directories in WinAVR that contain executable programs. If <install> is your install directory then
these two directories are:

<install>\bin
<install>\utils\bin

The <install>\bin directory contains the software development toolset proper. This includes GNU binutils,
GCC, and other programs.

The <install>\utils\bin contains many miscellaneous Unix or GNU programs that are built for Windows.
This includes sh (bash) and make among a host of other things.

For your operating system to easily locate these directories, they must be put at the beginning of the
PATH environment variable. WinAVR can do this automatically upon installation, if you selected this option.

These programs are put into two seperate directories in case you want to use a different set of utility
programs than the set that comes with WinAVR.

If you do not wish to use the utilities that comes with WinAVR, remove the <install>\utils\bin
directory from your PATH environment variable.

For Windows 95 and 98 users, see the autoexec.bat file in the root drive where your OS is installed. This is
usually in C:\.

For all other Windows users, the WinAVR installer modifies this registry key: HKEY_LOCAL_MACHINE
\SYSTEM\CurrentControlSet\Control\Session Manager\Environment\Path

IMPORTANT: On Windows NT/2K/XP you must have Administrator priviledges for the installer to
automatically put these directories in your PATH environment variable.

3.0 Toolset Background

WinAVR is a collection of executable software development tools for the Atmel AVR processor hosted on Windows.

These software development tools include:

● Compilers
● Assembler
● Linker
● Librarian
● File converter

http://winavr.sourceforge.net/WinAVR-user-manual.html (6 de 21) [8/30/2010 6:05:42 PM]

 WinAVR User Manual - 20050214

● Other file utilities

● C Library
● Programmer software
● Debugger
● In-Circuit Emulator software
● Editor / IDE
● Many support utilities

3.1 The Toolset and Open Source

Each of the tools included in WinAVR is Open Source and/or Free Software. Each tool has it's own project,
usually hosted on SourceForge or Savannah, with their own project maintainers and developers who all
volunteer their time and energy to creating these tools. Look in the Links section below to find out the websites
of each of these projects.

Especially note many of these programs come from the Unix and Linux platforms. These programs have
been ported to the Windows platform but generally behave for a Unix-like environment. If you are not used to
a Unix-like environment it can possibly be frustrating. Read as much documentation as you can. Look at
examples. Search the Internet. Many links are also provided in this manual.

Also remember that this software is updated and improved continually by many people who volunteer
their precious time to provide some of the best software for absolutely no cost or obligation to you. Volunteers
are always welcome in furthering any of these projects!

3.2 Compiler

The compiler in WinAVR is the GNU Compiler Collection, or GCC. This compiler is incredibly flexible and can
be hosted on many platforms, it can target many different different processors / operating systems (back-
ends), and can be configured for multiple different languages (front-ends).

The GCC included in WinAVR is targeted for the AVR processor, is built to execute on the Windows platform, and
is configured to compile C, or C++.

CAUTION: There are caveats on using C++. See the avr-libc FAQ.

Because this GCC is targeted for the AVR, the main executable that is created is prefixed with the target
name: avr-gcc.exe. It is also referred to as AVR GCC.

avr-gcc is just a "driver" program only. The compiler itself is called cc1.exe for C, or cc1plus.exe for C+
+. Also, the preprocessor cpp.exe will usually automatically be prepended with the target name: avr-cpp.
exe. The actual set of component programs called is usually derived from the suffix of each source code file
being processed.

GCC compiles a high-level computer language into assembly, and that is all. It cannot work alone. GCC is
coupled with another project, GNU Binutils, which provides the assembler, linker, librarian and more. Since GCC
is just a "driver" program, it can automatically call the assembler and linker directly to build the final program.

3.3 Assembler, Linker, Librarian and More

GNU Binutils is a collection of binary utilities. This also includes the assembler, as. Sometimes you will see
it referenced as GNU as or gas. Binutils includes the linker, ld; the librarian or archiver, ar. There are many
other programs included that provide various functionality.

Note that while the assembler uses the same mnemonics as proposed by Atmel, the "glue" (pseudo-ops,
operators, expression syntax) is derived from the common assembler syntax used in Unix assemblers, so it is

http://winavr.sourceforge.net/WinAVR-user-manual.html (7 de 21) [8/30/2010 6:05:42 PM]

 WinAVR User Manual - 20050214

not directly compatible to Atmel assembler source files.

Binutils is configured for the AVR target and each of the programs is prefixed with the target name. So you
have programs such as:

avr-as

The Assembler.
avr-ld

The Linker.
avr-ar

Create, modify, and extract from archives (libraries).

avr-ranlib

Generate index to archive (library) contents.

avr-objcopy

Copy and translate object files.

avr-objdump

Display information from object files including disassembly.

avr-size

List section sizes and total size.

avr-nm

List symbols from object files.

avr-strings

List printable strings from files.

avr-strip

Discard symbols.
avr-readelf

Display the contents of ELF format files.

avr-addr2line

Convert addresses to file and line.

avr-c++filt

Filter to demangle encoded C++ symbols.

See the binutils user manual for more information on what each program can do.

3.4 C Library

avr-libc is the Standard C Library for AVR GCC. It contains many of the standard C routines, and many
non-standard routines that are specific and useful for the AVR processor.

NOTE: The actual library is currently split into two main parts, libc.a and libm.a, where the latter

http://winavr.sourceforge.net/WinAVR-user-manual.html (8 de 21) [8/30/2010 6:05:42 PM]

 WinAVR User Manual - 20050214

contains mathematical functions (everything mentioned in <math.h>, and a bit more). Thus it is a good idea
to always include the -lm linker option. The WinAVR Makefile Template automatically includes the -lm
linker option. Also, there are additional libraries which allow a customization of the printf and scanf
function families.

avr-libc also contains the most documentation on how to use (and build) the entire toolset, including
code examples. The avr-libc user manual also contains the FAQ on using the toolset.

3.5 Making Your Software

There is one program that brings all of this together. This program is GNU make. The make program reads
and interprets a makefile. A makefile is a text file that you write that lists and controls how something is made. It is
most often used to control how software is made.

Each of these programs are Command Line Interface (CLI) tools. They are controlled by parameters or
switches that are added to the command line. Or, in the case of make, by text files that are written and used
as input.

Most commercial software development toolsets have an Integrated Development Environment (IDE). This
consists of a graphical user-interface (GUI) that contains a programming editor and graphical front-ends
to compiler, assembler, linker, standard C library, and librarian programs. These front-ends consist of dialog
boxes which allow you to set build options and a way of creating a list of files that are in a "project".
These graphical front-ends hide and encapsulate the real command-line compiler, assembler, linker, and
standard library that are in the background of any software development toolset.

WinAVR is a collection of open-source, software development tools from various projects. WinAVR does not have
a complete graphical IDE like a commerical toolset, yet. Because of this, learning to build software under
GCC means that it would be best to learn how to use the make program and learn how to write makefiles.
Learn the common flags that are used to control GCC which in turn can control gas and ld. You can learn a lot
by looking at the Makefile Template that comes with WinAVR and looking up all the programs and flags in
the included user manuals.

3.6 Programming

After creating your software, you'll want to program your device. There are two different software
packages included that can interface with various hardware to program your device: avrdude, and uisp.

avrdude is a very flexible package. All the information about AVR processors and various hardware
programmers is stored in a text database. This database can be modified by any user to had new hardware or
to add an AVR processor if it is not already listed.

3.7 Debugging

Debugging encompasses simulation and emulation. Both are available in WinAVR.

The GNU Debugger (GDB) is the main package that can be used for general debugging. GDB is a command-
line program only. Insight is GDB plus a GUI written in Tcl/Tk. Both GDB and Insight are configured for
the AVR and the main executables are prefixed with the target name: avr-gdb, and avr-insight. There is
now also a "text mode" GUI for GDB: avr-gdbtui.

To do emulation with the JTAG ICE, GDB / Insight requires a "helper" program called avarice which is
also included.

NOTE: The JTAG ICE mkII is not yet supported by avarice, though this feature is planned for the future.

http://winavr.sourceforge.net/WinAVR-user-manual.html (9 de 21) [8/30/2010 6:05:42 PM]

 WinAVR User Manual - 20050214

To do simulation, GDB / Insight requires a different "helper" program called simulavr which is also included.

There are also alternatives for simulation. Atmel offers a free package called AVR Studio which can also
do simulation. The latest version of AVR Studio is 4.11. Note that AVR Studio is currently free to the
public, but it is not Open Source.

Another simulation alternative is VMLab. However, this is a commercial package.

See the section, 5.0 Debugging, Simulating, and Emulating, for detailed information on debugging.

4.0 Setting Up a Project

4.1 Where's the GUI / IDE?

You won't find a typical GUI / IDE like you might be used to with other commercial cross-compilers, or like native
compilers on Windows. Each of the tools in WinAVR are from their own projects. In this case, an editor or IDE
is just another component in the toolset. And, everybody has their own favourite they want to use. WinAVR allows
flexibility.

WinAVR comes with an editor / IDE called Programmers Notepad. This is an Open Source editor with some
IDE capabilites. Because the compiler and associated utilities are all command-line driven, you are free to
use whatever editor / IDE you want to provided it can call command-line programs. See below for
more information on Programmers Notepad.

There is current work going on to continually improve the IDE capabilities of Programmers Notepad. Let us know
if you're interested in volunteering to help on these projects.

4.2 Programmers Notepad

Programmers Notepad (PN) is an Open Source editor with some IDE features. Version 2.x is is a complete
rewrite of version 1. Many new features are still being added.

PN contains the Open Source Scintilla editor component as the basis for its editor.

PN can call any command-line tool and capture it's output. This is ideal for calling the make utility, which
executes your makefile, which in turn calls the compiler, linker, and other utilities used to build your software.
PN will then capture the output and display it in a window. You can also click on any GCC warning or error and
PN will automatically open the file and go to the line where the warning or error occurred.

To set up tools, go to the Tools menu up top, select Options, then select Tools on the left side menu. The best
Scheme to add tools is under "(None - Global Tools)". After you add your tool, it will appear in the Main
Menu under Tools.

4.3 Make, Makefiles, and the Makefile Template

make is a program that is widely used to build software. make reads and executes makefiles, which
are descriptions of how to build something. Makefiles typical do things such as group files together, set lists
of compiler and linker flags, list rules of how to compile source code to object code, how to link object files, how
to convert files from one type to another, and many other things.

When you set up your project, add a makefile to control how to build your software. When you use

http://winavr.sourceforge.net/WinAVR-user-manual.html (10 de 21) [8/30/2010 6:05:42 PM]

 WinAVR User Manual - 20050214

Programmers Notepad, or other IDE, set it up to call make and have it execute your project's makefile.

A Makefile Template is included in WinAVR, which provides a lot of functionality already written for you. You
can can copy it to your project's directory and easily modify it to fit your project. This Makefile Template can
be found in the <install>\sample directory.

WinAVR now includes the MFile utility. MFile is a automatic makefile generator for AVR GCC written in Tcl/Tk
and can run on various platforms including Windows, FreeBSD, Linux, etc. You can use this utility to help
you quickly generate a makefile for your project based on some simple menu input. MFile for the
Windows platform uses the WinAVR Makefile Template for it's template.

NOTE: I HIGHLY RECOMMEND THAT YOU BECOME FAMILIAR WITH THE MAKE PROGRAM AND
WRITING MAKEFILES! PLEASE READ THE MAKE USER MANUAL!

For more information on the make program and writing makefiles, see the make user manual that is included
or see Links below for GNU Manuals Online.

5.0 Debugging, Simulating, and Emulating

NOTE: The term "debugging" is a generic term and can mean either simulation or emulation below.

There are several different ways to go about debugging, simulating, and emulating. Each solution has their
own requirements and may involve various tradeoffs.

There are open source applications that can be used for simulation and emulation, and they are included
with WinAVR. Use GDB or Insight, with the simulavr back-end for simulating, or with the avarice back-
end to emulate using the Atmel JTAG ICE.

There is a free application from Atmel that can be used for simulation or emulation: AVR Studio. The latest
version as of this writing is 4.11. AVR Studio can be downloaded from the Atmel web site.

There are also a number of commercial simulators, such as VMLab or Proteus VSM.

In general, debugging is dependent upon:

1. The application used to debug.

2. The file format used.
3. The type of debugging information generated in the object code.

Many times the application that is being used, determines the file format, and the type of debugging
information that needs to be generated.

This version of the compiler can generate both DWARF2 and stabs debugging information.

NOTE: The compiler will currently default to generating DWARF2 debugging info.

If you are using the WinAVR Makefile Template, or using MFile, there is a line in the makefile that controls the
type of debug information that is generated:

DEBUG = dwarf-2

http://winavr.sourceforge.net/WinAVR-user-manual.html (11 de 21) [8/30/2010 6:05:42 PM]

 WinAVR User Manual - 20050214

To generate stabs information change this line to:

DEBUG = stabs

TIP: MFile can change this setting automatically through a menu option.

This line in the makefile changes the -g compiler switch that is sent to GCC. See the GCC user manual for
more information.

The compiler will build your software and automatically output an ELF file.

5.1 GDB/Insight + simulavr or avarice

The GNU Debugger (GDB) can be used, with other programs, to simulate or emulate your AVR program. Insight
is GDB with a GUI (written in Tcl/Tk). Insight also has a console window which provides the traditional
command-line interface to GDB. The terms GDB and Insight will be used interchangably.

Use avarice with GDB for use with your JTAG In-Circuit Emulator (ICE).

Use simulavr with GDB for simulation.

See each of the package's documentation for more information on usage.

Requirements
File Format: ELF
Debugging Information: DWARF-2 (preferred) or stabs

TIP: There is a tutorial on how to use GDB and avarice at the WinAVR web site.

TIP: If you use avarice, when you specify a serial port to use with the --jtag flag, you must specify it in the
form of:

--jtag /dev/comX

where X is the COM port number you are using. This is due to the fact that avarice is linked to the Cygwin
DLL, which requires a Unix-type format for the COM port number.

5.2 AVR Studio

AVR Studio 4.10 and above has a new parser component that can read ELF files natively. These ELF files
must contain DWARF2 debugging information. This parser is still in beta and may not be complete.

Requirements (for AVR Studio version 4.10 and greater)

File Format: ELF
Debugging Information: DWARF-2

5.3 Commercial Simulators

Certain commercial simulators have more requirements to use their products. Namely, you must compile

http://winavr.sourceforge.net/WinAVR-user-manual.html (12 de 21) [8/30/2010 6:05:42 PM]

 WinAVR User Manual - 20050214

your software with the stabs debugging information, and you must convert your ELF file to either the
COFF format or to the Atmel Extended COFF format.

Requirements (dependent upon application used)

File Format: COFF / Atmel Extended COFF
Debugging Information: stabs

The GNU Binutils program objcopy (avr-objcopy) has been patched where it can now convert from ELF to either
of these formats. Note that the converter is a beta release.

The usage of avr-objcopy to convert ELF/stabs debugging information into AVR COFF debugging information
is (long lines wrapped with backslashes):

avr-objcopy \
--debugging \
-O $(FORMAT) \
--change-section-address .data-0x800000 \
--change-section-address .bss-0x800000 \
--change-section-address .noinit-0x800000 \
--change-section-address .eeprom-0x810000 \
$(filename).elf $(filename).cof

where $(FORMAT) should either be coff-avr (COFF format that matches the older Atmel AVR
COFF documentation, as understood by AVR Studio 3, early versions of AVR Studio 4, and also by VMLab),
or coff-ext-avr (current AVR Extended COFF specification, as understood by AVR Studio 4.07+; adds long
filenames and structure debugging).

There might be some warnings when you run the above, like

Warning: file {standard input} not found in symbol table, ignoring

Warning: ignoring function __vectors() outside any compilation unit
Warning: ignoring function __bad_interrupt() outside any compilation unit

Perhaps more of them if your avr-libc has been installed with debugging symbols (the default WinAVR
installation strips debugging symbols from the installed library files). There should be no other warning normally.

NOTE: The avr-objcopy usage describe above is in the Makefile Template that is included with WinAVR and in
the MFile template. You should only have to call make coff to convert to AVR COFF, or
call make extcoff to convert to AVR Extended COFF.

As Atmel has now moved towards the ELF file format with DWARF-2 debugging information, the (E)
COFF conversion is deprecated. Thus, there is currently no ongoing development on the COFF converter. There
are a few known bugs in it, in particular it is known that using forward struct references can crash the
converter. Unfortunately, fixing this bug would be close to a whole rewrite of it. As a workaround, just
avoid forward struct references.

Instead of writing:

http://winavr.sourceforge.net/WinAVR-user-manual.html (13 de 21) [8/30/2010 6:05:42 PM]

 WinAVR User Manual - 20050214

typedef struct foo *foo_p;

struct foo {
foo_p next;
int something;
};

reorder it to:

struct foo {
struct foo *next;
int something;
};
typedef struct foo *foo_p;

That strategy is known to work around that particular bug.

5.0 Useful Additions

5.1 Operating Systems

While an Operating System, or RTOS, isn't necessary to write software for the AVR, there may be times when it
is desirable. Below, are some links for free or open source operating systems / kernels for the AVR. Note that
this may not be a complete list.

AvrX

AvrX is a Real-Time Multitasking Kernel.

EtherNut - Nut/OS

Ethernut is an Open Source Hardware and Software Project for building Embedded Ethernet Devices. It
contains Nut/OS which is an intentionally simple RTOS for the ATmega128, which provides a minimum of
services to run Nut/Net, the TCP/IP stack.
FreeRTOS

FreeRTOS is a portable, open source, mini Real Time Scheduler (or mini RTOS kernel).
TinyOS

TinyOS is a component-based runtime environment designed to provide support for deeply embedded
systems which require concurrency intensive operations while constrained by minimal hardware resources.
Contiki

Contiki is an Internet-enabled operating system and desktop environment for a number of smallish systems.
XMK - eXtreme Minimal Kernel

XMK is a preemptive multitasking scheduler/kernel for 8bit microcontrollers. Its goal is to provide a bare
bones RTOS with a small enough footprint (RAM+ROM) to run on 8bit microcontrollers.
pico OS

http://winavr.sourceforge.net/WinAVR-user-manual.html (14 de 21) [8/30/2010 6:05:42 PM]

 WinAVR User Manual - 20050214

pico OS is a highly configurable and very fast real time operating system (RTOS). It targets a wide range of
architectures, from very small 8 bit processors and microcontrollers up to very huge platforms. An AVR port is
available.

5.2 TCP/IP

Here are some links to free or open source TCP/IP implementations.

uIP - TCP/IP Stack for Embedded Microcontrollers

uIP is an implementation of the TCP/IP protocol stack intended for small 8-bit and 16-bit microcontrollers. It
provides the necessary protocols for Internet communication, with a very small code footprint and RAM
requirements - the uIP code size is on the order of a few kilobytes and RAM usage is on the order of a few
hundred bytes.

6.0 Finding Help

WinAVR is a packaged collection of software devlopment tools built from open source projects.

There is a large community of people who use these tools. There are a number of these people who volunteer
their time to help other people with problems or questions. And then there are other people who also
volunteer their time to contribute to these open source projects.

The main places to find help is the Documenation and Online Sources. Please try and find the answer in the
documentation first before asking for help online.

TIP: If you need to ask for help online, please read this first: How To Ask Questions The Smart Way

6.1 Documentation

The first and best place to find help is in the documentation! WinAVR includes the user manuals for many of
the software tools that are shipped in the package.

The documentation for any particular package may come in different formats depending upon what is
available from that package and available space in the WinAVR installation. The different documentation
formats that you'll find in WinAVR are:

1. HTML - Hyper Text Markup Language. Requires a web browser to view.

2. PDF - Portable Document Format. Requires a PDF viewer such as Acrobat.
3. Info - A GNU "hypertext" format. Requires an info viewer (which is included).

Additionally many user manuals can also be found online, especially packages that are part of the GNU project.
You can find links to many of these in the Links section below.

For packages that have HTML, and PDF documentation, look in your <install>\doc directory.

WinAVR installs on your desktop, a shortcut to TkInfo, a graphical browser for info files. Many of the packages
in WinAVR contain help ONLY in this info format, especially those from the GNU project.

WinAVR also installs on your desktop two other shortcuts. One is to the HTML documentation on avr-libc that
is installed locally. The other shortcut is to the GNU Manuals online (which requires Internet connection).

http://winavr.sourceforge.net/WinAVR-user-manual.html (15 de 21) [8/30/2010 6:05:42 PM]

 WinAVR User Manual - 20050214

6.2 Online Sources

I'll say it again:

Please try and find the answer in the documentation first before asking for help online.

TIP: If you need to ask for help online, please read this first: How To Ask Questions The Smart Way

Help for the AVR software development toolset (and specifically AVR GCC) can be found at:

AVR Freaks

All AVR, all the time! This site has several forums including a general AVR Forum and an AVR GCC Forum
specifically for discussion of the GCC compiler for the AVR. They also have an Academy which contains user's
projects. This gives you access to a lot of sample code, libraries, and various AVR projects.
avr-gcc-list mailing list

The avr-gcc-list is intended as a forum for dicussion about the following: Bugs, Programming technique,
Installation and distributions, Hints and tips, Other avr-gcc related stuff. Note that all of the developers of the
toolset are subscribed to this list!
Mikrocontroller.net

For native German speakers. They have a forum for the AVR GCC compiler.

Help for other projects and tools included in WinAVR can usually be found at the individual project's web
page which usually includes links to their mailing lists.

If you need help, do not contact the WinAVR developers personally! Use these web sites and mailing lists first!

7.0 Toolset Bugs

You can fill out a relevant tracker on the WinAVR SourceForge project page, if you have one of the following:

● a bug in the packaging

● a bug in the installation
● any suggestions for a new tool to be added
● any suggestions for improvements to the overall package

IMPORTANT: IF THERE ARE BUGS IN THE SOFTWARE TOOLS THEMSELVES, THE MAINTAINERS OF
THE INDIVIDUAL SOFTWARE PROJECTS SHOULD BE NOTIFIED IN THE APPROPRIATE MANNER, NOT ME, OR THE
WINAVR PROJECT!!!!

Generally, if you encounter a bug with a library routine or a bug with a specifc AVR processor or header file,
notify the avr-libc project first (see Links below). They will let you know if the bug is truly in the avr-libc project,
or if it should be passed on to the GCC project. If the bug is in GCC, go to their web page (see Links below)
on how to report bugs to GCC.

For bugs with Programmer's Notepad 2, see it's SourceForge web site (see Links) to issue a Bug Tracker, or
email it's author (see Credits).

For bugs with avrdude, see it's Project page (see Links).

For bugs with uisp, see it's Project page (see Links).

http://winavr.sourceforge.net/WinAVR-user-manual.html (16 de 21) [8/30/2010 6:05:42 PM]

 WinAVR User Manual - 20050214

For bugs with simulavr, see it's Project page (see Links).

For bugs with avarice, see it's Project page (see Links).

For bugs with GDB, see it's web page (see Links).

For bugs with Insight, see it's web page (see Links).

For bugs with SRecord, see it's Home page (see Links).

8.0 WinAVR FAQ

This FAQ is specific to the WinAVR package and installation. For a programming issues, see the avr-libc FAQ in
the avr-libc documentation included in the WinAVR package or the avr-libc user manual online.

#1) When I run a program, why do

I get the error "You
have multiple copies of
cygwin1.dll on your system."?

Certain packages in WinAVR are built with Cygwin and are linked to their emulation library: cygwin1.dll. If you
also have Cygwin installed seperately, these programs will find the cygwin1.dll that is shipped and included
with WinAVR, and will also find the cygwin1.dll in your Cygwin installation. If these versions are different, you
will get this error.

WinAVR must ship the cygwin1.dll file to support it's packages, as most people do not have Cygwin installed
on their system and it's not fair to ask people to install such a huge package as a prerequisite.

Unfortunately, the Cygwin FAQ says that the only way around this is to remove other copies of cygwin1.dll.
This would mean either uninstalling Cygwin so the WinAVR programs work, or perhaps renaming the cygwin1.
dll found in the <install>\bin directory so the WinAVR programs will use the cygwin1.dll that is in the
Cygwin installation. However, if you do the latter, note that the version of cygwin1.dll you have in your
Cygwin installation is probably different than the version of cygwin1.dll that was used to build the
WinAVR programs. In this case, use at your own risk.

#2) I have any of the following

warnings when I create a
COFF file, what should I do?

Warning: file {standard input} not found in symbol table, ignoring

Warning: ignoring function __vectors() outside any compilation unit
Warning: ignoring function __bad_interrupt() outside any compilation unit
Discarding local symbol outside any compilation unit: .__do_copy_data_start
Discarding local symbol outside any compilation unit: .__do_copy_data_loop

Nothing. These warnings can be ignored.

9.0 WinAVR Project

http://winavr.sourceforge.net/WinAVR-user-manual.html (17 de 21) [8/30/2010 6:05:42 PM]
 WinAVR User Manual - 20050214

9.1 Build Notes

All packages are built in the Cygwin environment. Some packages use the MinGW GCC compiler package
provided by Cygwin. These will be marked below with "MinGW". Other packages are built with the Cygwin
GCC compiler and may have a dependency upon one or more Cygwin DLLs, which are included in WinAVR.

1. GNU Binutils: MinGW.

2. GCC: MinGW.
3. avr-libc: MinGW.
4. avrdude: MinGW.
5. uisp: Cygwin. Requires: cygwin1.dll.
6. GDB: Cygwin. Requires: cygwin1.dll,tcl84.dll,tk84.dll.
7. Insight: Cygwin. Requires: cygwin1.dll,tcl84.dll,tk84.dll.
8. AVaRICE: Cygwin. Requires: cygwin1.dll,
9. SimulAVR: Cygwin. Requires: cygwin1.dll.
10. SRecord: Cygwin. Requries: cygwin1.dll.
11. TkInfo: Requires: wish84.exe,cygwin1.dll,tcl84.dll,tk84.dll.

DLL Versions:

● cygwin1.dll: 1.5.12-1
● tcl84.dll: 8.4
● tk84.dll: 8.4

Programmer's Notepad 2 was built by it's author, Simon Steele (see Credits). Tofrodos was built by it's
author, Christopher Heng (see Credits).

9.2 Source Code

To find out more information about obtaining the source code to the software in these projects, download
the corresponding Source Code package on the WinAVR Project page. To find the correct Source Code
package, first look for the correct date code of the WinAVR package you want.

Previous releases had separate source code packages. Now there is just a single package. See the Links section
to find where to get the source code for the various projects. See the <install>\source subdirectory for
any patches to the main source that are being used.

9.3 Credits

Thank you to everyone who uses WinAVR!

● WinAVR software devleopment toolset distribution built by

Eric B. Weddington
email

Colin O'Flynn
email

● Very Special Thanks to Jörg Wunsch for helping to build the SRecord utilities at the last minute, and for
putting together an avr-libc release at the last minute too!
● Very Special Thanks to Colin O'Flynn for writing a tutorial on how to install and configure WinAVR, writing a
tutorial on how to use Insight, for testing WinAVR and all around assistance!
● Thanks to SourceForge for hosting the WinAVR project.

http://winavr.sourceforge.net/WinAVR-user-manual.html (18 de 21) [8/30/2010 6:05:42 PM]

 WinAVR User Manual - 20050214

● Special Thanks to major contributers to the AVR toolset: Denis Chertykov, Marek Michalkiewicz, Theodore
(Ted) A. Roth, Jörg Wunsch, Michael Stumpf, Reiner Patommel, Brian S. Dean, Scott Finneran, David Gay,
Jason Kyle.
● Very Special Thanks to Jörg Wunsch for helping this project in a number of ways including writing the AVR
COFF patch for binutils, patches for GCC to help with debugging and binary constants, reviewing,and being
the resident guru on AVR Freaks! :-). Portions of this manual were written by Jörg Wunsch.
● Very Special Thanks to Simon Steele for permission to include Programmers Notepad in WinAVR.
Programmer's Notepad is written and built by Simon Steele.
● Native Win32 Unix programs from:

❍ Karl M. Syring <http://www.weihenstephan.de/~syring/win32/UnxUtils.html>

❍ http://www.morpheus.demon.co.uk/ (bison and flex)
❍ MinGW
● Tofrodos 1.6 is written and built by Chistopher Heng
● Thanks to the following people for additional material for the Makefile Template: Tim Henigan, Peter Fleury,
Jörg Wunsch, Reiner Patommel, Sander Pool, Frederik Rouleau, Markus Pfaff.
● Special Thanks to Markus Assfalg for all his input in doing AVR COFF pre-alpha tests and to Svenn-Ivar
Svendsen from Atmel Norway, who willingly answered questions regarding Atmel's COFF specs.
● Very Special Thanks to Torleif Sandness of Atmel, the principal developer of Atmel's ELF parser for AVR
Studio, for really pioneering that area.
● Thanks to members of the AVR COFF Alpha Testing team, which include: Wallace White, Markus Assfalg,
Volkmar Dierkes, Marc Wetzel, Andrew Ghali, Ömer Sinan KAYA, Eric Weddington.
● Thanks to Atmel and to Advanced Micro Tools (AMTools), makers of the VMLAB debugger tool, for assistance
in the endeavour of writing the AVR COFF patch.
● Special thanks to Nick Moore for designing the WinAVR logos!
● Special thanks to Brian Brill for helping to move around some large files for the first release; to Ted Roth for
hosting the first WinAVR release on the avr-libc web site.
● And Extreme Thanks to Ted Roth and Jörg Wunsch for putting up with me. :-)

9.4 TODO / Open Projects

● Get SRecord to build, and then develop a native Win32 port.

● Add Project Management to Programmers Notepad. This feature would allow the user to graphically select
files for a project and select various compile and link options. There would also be a WinAVR specific build
manager that would automatically generate the makefile and launch make. This has been making good
progress recently.
● Add AVR-Ada to WinAVR. This is mostly done, but has some bugs.
● Add support for the Atmel JTAG ICE mkII to avarice.
● Add support for the STK500 version 2 protocol to avrdude. In progress.
● Convert the WinAVR user manual to a PDF.
● Add tutorial to WinAVR user manual.
● Add avarice tutorial to WinAVR user manual.
● Try to build simulavrxx for Windows and include in package.
● Improve the Makefile Template, including adding translations of the output messages.
● Add stacktool to package.
● Build and include a Code Wizard that will let a user select options graphically and generate C code, for use in
generating initialization code, or other code that is usefull. Contact me if you're interested in volunteering to
help on this.
● Add ability to avrdude to read the XML part files from Atmel's AVR Studio.
● Improve avrdude-gui.
● avarice needs a native Win32 port (no dependency on Cygwin DLL).
● simulavrxx needs a native Win32 port (no dependency on Cygwin DLL).
● GDB needs a native Win32 port (no dependency on Cygwin DLL).
● Continue with internationalisation of the installer and selected tools.

http://winavr.sourceforge.net/WinAVR-user-manual.html (19 de 21) [8/30/2010 6:05:42 PM]

 WinAVR User Manual - 20050214

10.0 Links
WinAVR Project
WinAVR Home Page

SourceForge

AVR Freaks

avr-gcc-list mailing list

Atmel
Atmel AVR microcontrollers
Atmel's AVR Tools and Software
Atmel Norway's AVR Tools Beta Site

GNU Project

GNU Manuals Online

GNU Binutils

GNU Compiler Collection (GCC)

GCC Manuals Online

avr-libc

avrdude

avrdude-gui

uisp

GNU Debugger (GDB)

Insight

avarice

simulavr

MFile

Programmers Notepad
Scintilla

SRecord

dwarfdump

AVR-Ada

http://winavr.sourceforge.net/WinAVR-user-manual.html (20 de 21) [8/30/2010 6:05:42 PM]

 WinAVR User Manual - 20050214

stacktool

AvrX

EtherNut - Nut/OS

FreeRTOS

TinyOS

Contiki

XMK - eXtreme Minimal Kernel

Pico OS

uIP - TCP/IP Stack for Embedded Microcontrollers

lwIP - A Lightweight TCP/IP Stack

TkInfo

Tofrodos

OpenAVR

GNU Make

MinGW

Cygwin

Free ICE

Pymite
Pymite Doc

Jargon

Last updated 15-Feb-2005 10:38:09 MDT

http://winavr.sourceforge.net/WinAVR-user-manual.html (21 de 21) [8/30/2010 6:05:42 PM]