avr-libc-1.7.1/doc/api/overview.dox - toolchain/avr-libc - Git at Google

 /* Copyright (c) 2007  Eric B. Weddington
    All rights reserved.

    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions are met:

    * Redistributions of source code must retain the above copyright
      notice, this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright
      notice, this list of conditions and the following disclaimer in
      the documentation and/or other materials provided with the
      distribution.
    * Neither the name of the copyright holders nor the names of
      contributors may be used to endorse or promote products derived
      from this software without specific prior written permission.

   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
   AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
   IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
   ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
   LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
   CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
   SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
   INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
   CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
   ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
   POSSIBILITY OF SUCH DAMAGE. */

 /* $Id: overview.dox 1526 2007-12-20 14:17:56Z joerg_wunsch $ */

 /**

 \page overview Toolchain Overview

 \section overview_introduction Introduction

 Welcome to the open source software development toolset for the Atmel AVR!

 There is not a single tool that provides everything needed to develop software
 for the AVR. It takes many tools working together. Collectively, the group of
 tools are called a toolset, or commonly a toolchain, as the tools are chained
 together to produce the final executable application for the AVR
 microcontroller.

 The following sections provide an overview of all of these tools. You may be
 used to cross-compilers that provide everything with a GUI front-end, and not
 know what goes on "underneath the hood". You may be coming from a desktop or
 server computer background and not used to embedded systems. Or you may be
 just learning about the most common software development toolchain available
 on Unix and Linux systems. Hopefully the following overview will be helpful
 in putting everything in perspective.


 \section overview_fsf_and_gnu FSF and GNU

 According to its website, "the Free Software Foundation (FSF), established in
 1985, is dedicated to promoting computer users' rights to use, study, copy,
 modify, and redistribute computer programs. The FSF promotes the development
 and use of free software, particularly the GNU operating system, used widely in
 its GNU/Linux variant." The FSF remains the primary sponsor of the GNU project.

 The GNU Project was launched in 1984 to develop a complete Unix-like operating
 system which is free software: the GNU system. GNU is a recursive acronym for
 »GNU's Not Unix«; it is pronounced guh-noo, approximately like canoe.

 One of the main projects of the GNU system is the GNU Compiler Collection, or
 GCC, and its sister project, GNU Binutils. These two open source projects
 provide a foundation for a software development toolchain. Note that these
 projects were designed to originally run on Unix-like systems.


 \section overview_gcc GCC

 GCC stands for GNU Compiler Collection. GCC is highly flexible compiler system.
 It has different compiler front-ends for different languages. It has many
 back-ends that generate assembly code for many different processors and host
 operating systems. All share a common "middle-end", containing the generic
 parts of the compiler, including a lot of optimizations.

 In GCC, a \e host system is the system (processor/OS) that the compiler
 runs on. A \e target system is the system that the compiler compiles code for.
 And, a \e build system is the system that the compiler is built (from source code)
 on. If a compiler has the same system for \e host and for \e target, it is
 known as a \e native compiler. If a compiler has different systems for \e host
 and \e target, it is known as a cross-compiler. (And if all three, \e build,
 \e host, and \e target systems are different, it is known as a Canadian cross
 compiler, but we won't discuss that here.) When GCC is built to execute on a
 \e host system such as FreeBSD, Linux, or Windows, and it is built to generate
 code for the AVR microcontroller \e target, then it is a cross compiler, and
 this version of GCC is commonly known as "AVR GCC". In documentation, or
 discussion, AVR GCC is used when referring to GCC targeting specifically the
 AVR, or something that is AVR specific about GCC. The term "GCC" is usually
 used to refer to something generic about GCC, or about GCC as a whole.

 GCC is different from most other compilers. GCC focuses on translating a
 high-level language to the target assembly only. AVR GCC has three available
 compilers for the AVR: C language, C++, and Ada. The compiler itself does not
 assemble or link the final code.

 GCC is also known as a "driver" program, in that it knows about, and drives
 other programs seamlessly to create the final output. The assembler, and the
 linker are part of another open source project called GNU Binutils. GCC knows
 how to drive the GNU assembler (gas) to assemble the output of the compiler.
 GCC knows how to drive the GNU linker (ld) to link all of the object modules
 into a final executable.

 The two projects, GCC and Binutils, are very much interrelated and many of the
 same volunteers work on both open source projects.

 When GCC is built for the AVR target, the actual program names are prefixed
 with "avr-". So the actual executable name for AVR GCC is: avr-gcc. The
 name "avr-gcc" is used in documentation and discussion when referring to the
 program itself and not just the whole AVR GCC system.

 See the GCC Web Site and GCC User Manual for more information about GCC.


 \section overview_binutils GNU Binutils

 The name GNU Binutils stands for "Binary Utilities". It contains the GNU
 assembler (gas), and the GNU linker (ld), but also contains many other utilities
 that work with binary files that are created as part of the software
 development toolchain.

 Again, when these tools are built for the AVR target, the actual program names
 are prefixed with "avr-". For example, the assembler program name, for a native
 assembler is "as" (even though in documentation the GNU assembler is commonly
 referred to as "gas"). But when built for an AVR target, it becomes "avr-as".
 Below is a list of the programs that are included in Binutils:

 \par avr-as
 The Assembler.

 \par avr-ld
 The Linker.

 \par avr-ar
 Create, modify, and extract from libraries (archives).

 \par avr-ranlib
 Generate index to library (archive) contents.

 \par avr-objcopy
 Copy and translate object files to different formats.

 \par avr-objdump
 Display information from object files including disassembly.

 \par avr-size
 List section sizes and total size.

 \par avr-nm
 List symbols from object files.

 \par avr-strings
 List printable strings from files.

 \par avr-strip
 Discard symbols from files.

 \par avr-readelf
 Display the contents of ELF format files.

 \par avr-addr2line
 Convert addresses to file and line.

 \par avr-c++filt
 Filter to demangle encoded C++ symbols.


 \section overview_avr-libc avr-libc

 GCC and Binutils provides a lot of the tools to develop software, but there is
 one critical component that they do not provide: a Standard C Library.

 There are different open source projects that provide a Standard C Library
 depending upon your system time, whether for a native compiler (GNU Libc),
 for some other embedded system (newlib), or for some versions of Linux (uCLibc).
 The open source AVR toolchain has its own Standard C Library project: avr-libc.

 AVR-Libc provides many of the same functions found in a regular Standard C
 Library and many additional library functions that is specific to an AVR. Some
 of the Standard C Library functions that are commonly used on a PC environment
 have limitations or additional issues that a user needs to be aware of when
 used on an embedded system.

 AVR-Libc also contains the most documentation about the whole AVR toolchain.


 \section overview_building_software Building Software

 Even though GCC, Binutils, and avr-libc are the core projects that are used
 to build software for the AVR, there is another piece of software that
 ties it all together: Make. GNU Make is a program that makes things, and
 mainly software. Make interprets and executes a Makefile that is written
 for a project. A Makefile contains dependency rules, showing which
 output files are dependent upon which input files, and instructions on how
 to build output files from input files.

 Some distributions of the toolchains, and other AVR tools such as MFile,
 contain a Makefile template written for the AVR toolchain and AVR applications
 that you can copy and modify for your application.

 See the GNU Make User Manual for more information.


 \section overview_avrdude AVRDUDE

 After creating your software, you'll want to program your device. You can do
 this by using the program AVRDUDE which can interface with various hardware
 devices to program your processor.

 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 add new hardware or to add an AVR processor
 if it is not already listed.


 \section overview_gdb_insight_ddd GDB / Insight / DDD

 The GNU Debugger (GDB) is a command-line debugger that can be used with
 the rest of the AVR toolchain. 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 also a "text mode" GUI for GDB: avr-gdbtui. DDD (Data Display Debugger)
 is another popular GUI front end to GDB, available on Unix and Linux systems.


 \section overview_avarice AVaRICE

 AVaRICE is a back-end program to AVR GDB and interfaces to the Atmel JTAG
 In-Circuit Emulator (ICE), to provide emulation capabilities.


 \section overview_simulavr SimulAVR

 SimulAVR is an AVR simulator used as a back-end with AVR GDB. Unfortunately,
 this project is currently unmaintained and could use some help.


 \section overview_utilities Utilities

 There are also other optional utilities available that may be useful to add
 to your toolset.

 \c 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.

 \c MFile is a simple Makefile generator is meant as an aid to quickly customize
 a Makefile to use for your AVR application.


 \section overview_distros Toolchain Distributions (Distros)

 All of the various open source projects that comprise the entire toolchain
 are normally distributed as source code. It is left up to the user to build
 the tool application from its source code. This can be a very daunting task
 to any potential user of these tools.

 Luckily there are people who help out in this area. Volunteers take the time
 to build the application from source code on particular host platforms and
 sometimes packaging the tools for convenient installation by the end user.
 These packages contain the binary executables of the tools, pre-made and ready
 to use. These packages are known as "distributions" of the AVR toolchain,
 or by a more shortened name, "distros".

 AVR toolchain distros are available on FreeBSD, Windows, Mac OS X, and
 certain flavors of Linux.


 \section overview_open_source Open Source

 All of these tools, from the original source code in the multitude of projects,
 to the various distros, are put together by many, many volunteers. All of these
 projects could always use more help from other people who are willing to
 volunteer some of their time. There are many different ways to help, for people
 with varying skill levels, abilities, and available time.

 You can help to answer questions in mailing lists such as the avr-gcc-list, or
 on forums at the AVR Freaks website. This helps many people new to the open
 source AVR tools.

 If you think you found a bug in any of the tools, it is always a big help to
 submit a good bug report to the proper project. A good bug report always
 helps other volunteers to analyze the problem and to get it fixed for future
 versions of the software.

 You can also help to fix bugs in various software projects, or to add desirable
 new features.

 Volunteers are always welcome! :-)

 */
	/* Copyright (c) 2007 Eric B. Weddington
	All rights reserved.

	Redistribution and use in source and binary forms, with or without
	modification, are permitted provided that the following conditions are met:

	* Redistributions of source code must retain the above copyright
	notice, this list of conditions and the following disclaimer.
	* Redistributions in binary form must reproduce the above copyright
	notice, this list of conditions and the following disclaimer in
	the documentation and/or other materials provided with the
	distribution.
	* Neither the name of the copyright holders nor the names of
	contributors may be used to endorse or promote products derived
	from this software without specific prior written permission.

	THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
	AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
	LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
	CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
	SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
	INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
	CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
	ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
	POSSIBILITY OF SUCH DAMAGE. */

	/* $Id: overview.dox 1526 2007-12-20 14:17:56Z joerg_wunsch $ */

	/**

	\page overview Toolchain Overview

	\section overview_introduction Introduction

	Welcome to the open source software development toolset for the Atmel AVR!

	There is not a single tool that provides everything needed to develop software
	for the AVR. It takes many tools working together. Collectively, the group of
	tools are called a toolset, or commonly a toolchain, as the tools are chained
	together to produce the final executable application for the AVR
	microcontroller.

	The following sections provide an overview of all of these tools. You may be
	used to cross-compilers that provide everything with a GUI front-end, and not
	know what goes on "underneath the hood". You may be coming from a desktop or
	server computer background and not used to embedded systems. Or you may be
	just learning about the most common software development toolchain available
	on Unix and Linux systems. Hopefully the following overview will be helpful
	in putting everything in perspective.


	\section overview_fsf_and_gnu FSF and GNU

	According to its website, "the Free Software Foundation (FSF), established in
	1985, is dedicated to promoting computer users' rights to use, study, copy,
	modify, and redistribute computer programs. The FSF promotes the development
	and use of free software, particularly the GNU operating system, used widely in
	its GNU/Linux variant." The FSF remains the primary sponsor of the GNU project.

	The GNU Project was launched in 1984 to develop a complete Unix-like operating
	system which is free software: the GNU system. GNU is a recursive acronym for
	»GNU's Not Unix«; it is pronounced guh-noo, approximately like canoe.

	One of the main projects of the GNU system is the GNU Compiler Collection, or
	GCC, and its sister project, GNU Binutils. These two open source projects
	provide a foundation for a software development toolchain. Note that these
	projects were designed to originally run on Unix-like systems.


	\section overview_gcc GCC

	GCC stands for GNU Compiler Collection. GCC is highly flexible compiler system.
	It has different compiler front-ends for different languages. It has many
	back-ends that generate assembly code for many different processors and host
	operating systems. All share a common "middle-end", containing the generic
	parts of the compiler, including a lot of optimizations.

	In GCC, a \e host system is the system (processor/OS) that the compiler
	runs on. A \e target system is the system that the compiler compiles code for.
	And, a \e build system is the system that the compiler is built (from source code)
	on. If a compiler has the same system for \e host and for \e target, it is
	known as a \e native compiler. If a compiler has different systems for \e host
	and \e target, it is known as a cross-compiler. (And if all three, \e build,
	\e host, and \e target systems are different, it is known as a Canadian cross
	compiler, but we won't discuss that here.) When GCC is built to execute on a
	\e host system such as FreeBSD, Linux, or Windows, and it is built to generate
	code for the AVR microcontroller \e target, then it is a cross compiler, and
	this version of GCC is commonly known as "AVR GCC". In documentation, or
	discussion, AVR GCC is used when referring to GCC targeting specifically the
	AVR, or something that is AVR specific about GCC. The term "GCC" is usually
	used to refer to something generic about GCC, or about GCC as a whole.

	GCC is different from most other compilers. GCC focuses on translating a
	high-level language to the target assembly only. AVR GCC has three available
	compilers for the AVR: C language, C++, and Ada. The compiler itself does not
	assemble or link the final code.

	GCC is also known as a "driver" program, in that it knows about, and drives
	other programs seamlessly to create the final output. The assembler, and the
	linker are part of another open source project called GNU Binutils. GCC knows
	how to drive the GNU assembler (gas) to assemble the output of the compiler.
	GCC knows how to drive the GNU linker (ld) to link all of the object modules
	into a final executable.

	The two projects, GCC and Binutils, are very much interrelated and many of the
	same volunteers work on both open source projects.

	When GCC is built for the AVR target, the actual program names are prefixed
	with "avr-". So the actual executable name for AVR GCC is: avr-gcc. The
	name "avr-gcc" is used in documentation and discussion when referring to the
	program itself and not just the whole AVR GCC system.

	See the GCC Web Site and GCC User Manual for more information about GCC.


	\section overview_binutils GNU Binutils

	The name GNU Binutils stands for "Binary Utilities". It contains the GNU
	assembler (gas), and the GNU linker (ld), but also contains many other utilities
	that work with binary files that are created as part of the software
	development toolchain.

	Again, when these tools are built for the AVR target, the actual program names
	are prefixed with "avr-". For example, the assembler program name, for a native
	assembler is "as" (even though in documentation the GNU assembler is commonly
	referred to as "gas"). But when built for an AVR target, it becomes "avr-as".
	Below is a list of the programs that are included in Binutils:

	\par avr-as
	The Assembler.

	\par avr-ld
	The Linker.

	\par avr-ar
	Create, modify, and extract from libraries (archives).

	\par avr-ranlib
	Generate index to library (archive) contents.

	\par avr-objcopy
	Copy and translate object files to different formats.

	\par avr-objdump
	Display information from object files including disassembly.

	\par avr-size
	List section sizes and total size.

	\par avr-nm
	List symbols from object files.

	\par avr-strings
	List printable strings from files.

	\par avr-strip
	Discard symbols from files.

	\par avr-readelf
	Display the contents of ELF format files.

	\par avr-addr2line
	Convert addresses to file and line.

	\par avr-c++filt
	Filter to demangle encoded C++ symbols.


	\section overview_avr-libc avr-libc

	GCC and Binutils provides a lot of the tools to develop software, but there is
	one critical component that they do not provide: a Standard C Library.

	There are different open source projects that provide a Standard C Library
	depending upon your system time, whether for a native compiler (GNU Libc),
	for some other embedded system (newlib), or for some versions of Linux (uCLibc).
	The open source AVR toolchain has its own Standard C Library project: avr-libc.

	AVR-Libc provides many of the same functions found in a regular Standard C
	Library and many additional library functions that is specific to an AVR. Some
	of the Standard C Library functions that are commonly used on a PC environment
	have limitations or additional issues that a user needs to be aware of when
	used on an embedded system.

	AVR-Libc also contains the most documentation about the whole AVR toolchain.


	\section overview_building_software Building Software

	Even though GCC, Binutils, and avr-libc are the core projects that are used
	to build software for the AVR, there is another piece of software that
	ties it all together: Make. GNU Make is a program that makes things, and
	mainly software. Make interprets and executes a Makefile that is written
	for a project. A Makefile contains dependency rules, showing which
	output files are dependent upon which input files, and instructions on how
	to build output files from input files.

	Some distributions of the toolchains, and other AVR tools such as MFile,
	contain a Makefile template written for the AVR toolchain and AVR applications
	that you can copy and modify for your application.

	See the GNU Make User Manual for more information.


	\section overview_avrdude AVRDUDE

	After creating your software, you'll want to program your device. You can do
	this by using the program AVRDUDE which can interface with various hardware
	devices to program your processor.

	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 add new hardware or to add an AVR processor
	if it is not already listed.


	\section overview_gdb_insight_ddd GDB / Insight / DDD

	The GNU Debugger (GDB) is a command-line debugger that can be used with
	the rest of the AVR toolchain. 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 also a "text mode" GUI for GDB: avr-gdbtui. DDD (Data Display Debugger)
	is another popular GUI front end to GDB, available on Unix and Linux systems.


	\section overview_avarice AVaRICE

	AVaRICE is a back-end program to AVR GDB and interfaces to the Atmel JTAG
	In-Circuit Emulator (ICE), to provide emulation capabilities.


	\section overview_simulavr SimulAVR

	SimulAVR is an AVR simulator used as a back-end with AVR GDB. Unfortunately,
	this project is currently unmaintained and could use some help.


	\section overview_utilities Utilities

	There are also other optional utilities available that may be useful to add
	to your toolset.

	\c 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.

	\c MFile is a simple Makefile generator is meant as an aid to quickly customize
	a Makefile to use for your AVR application.


	\section overview_distros Toolchain Distributions (Distros)

	All of the various open source projects that comprise the entire toolchain
	are normally distributed as source code. It is left up to the user to build
	the tool application from its source code. This can be a very daunting task
	to any potential user of these tools.

	Luckily there are people who help out in this area. Volunteers take the time
	to build the application from source code on particular host platforms and
	sometimes packaging the tools for convenient installation by the end user.
	These packages contain the binary executables of the tools, pre-made and ready
	to use. These packages are known as "distributions" of the AVR toolchain,
	or by a more shortened name, "distros".

	AVR toolchain distros are available on FreeBSD, Windows, Mac OS X, and
	certain flavors of Linux.


	\section overview_open_source Open Source

	All of these tools, from the original source code in the multitude of projects,
	to the various distros, are put together by many, many volunteers. All of these
	projects could always use more help from other people who are willing to
	volunteer some of their time. There are many different ways to help, for people
	with varying skill levels, abilities, and available time.

	You can help to answer questions in mailing lists such as the avr-gcc-list, or
	on forums at the AVR Freaks website. This helps many people new to the open
	source AVR tools.

	If you think you found a bug in any of the tools, it is always a big help to
	submit a good bug report to the proper project. A good bug report always
	helps other volunteers to analyze the problem and to get it fixed for future
	versions of the software.

	You can also help to fix bugs in various software projects, or to add desirable
	new features.

	Volunteers are always welcome! :-)

	*/