avr-libc 1.6.7 Generated by Doxygen 1.6.2 Mon Mar 15 19:22:26 2010 CONTENTS i Contents 1 AVR Libc1 1.1 Introduction...............................1 1.2 General information about this library.................1 1.3 Supported Devices...........................2 1.4 avr-libc License.............................8 2 Toolchain Overview9 2.1 Introduction...............................9 2.2 FSF and GNU..............................9 2.3 GCC................................... 10 2.4 GNU Binutils.............................. 11 2.5 avr-libc................................. 12 2.6 Building Software............................ 12 2.7 AVRDUDE............................... 12 2.8 GDB / Insight / DDD.......................... 13 2.9 AVaRICE................................ 13 2.10 SimulAVR................................ 13 2.11 Utilities................................. 13 2.12 Toolchain Distributions (Distros).................... 13 2.13 Open Source............................... 14 3 Memory Areas and Using malloc() 14 3.1 Introduction............................... 14 3.2 Internal vs. external RAM....................... 15 3.3 Tunables for malloc().......................... 16 3.4 Implementation details......................... 18 4 Memory Sections 19 4.1 The .text Section............................ 19 4.2 The .data Section............................ 20 4.3 The .bss Section............................. 20 Generated on Mon Mar 15 19:22:26 2010 for avr-libc by Doxygen CONTENTS ii 4.4 The .eeprom Section.......................... 20 4.5 The .noinit Section........................... 20 4.6 The .initN Sections........................... 21 4.7 The .finiN Sections........................... 22 4.8 Using Sections in Assembler Code................... 23 4.9 Using Sections in C Code........................ 23 5 Data in Program Space 24 5.1 Introduction............................... 24 5.2 A Note On const............................ 25 5.3 Storing and Retrieving Data in the Program Space........... 25 5.4 Storing and Retrieving Strings in the Program Space......... 27 5.5 Caveats................................. 29 6 avr-libc and assembler programs 29 6.1 Introduction............................... 29 6.2 Invoking the compiler.......................... 30 6.3 Example program............................ 30 6.4 Pseudo-ops and operators........................ 34 7 Inline Assembler Cookbook 35 7.1 GCC asm Statement........................... 36 7.2 Assembler Code............................. 38 7.3 Input and Output Operands....................... 38 7.4 Clobbers................................. 43 7.5 Assembler Macros........................... 45 7.6 C Stub Functions............................ 45 7.7 C Names Used in Assembler Code................... 46 7.8 Links.................................. 47 8 How to Build a Library 47 8.1 Introduction............................... 47 8.2 How the Linker Works......................... 48 Generated on Mon Mar 15 19:22:26 2010 for avr-libc by Doxygen CONTENTS iii 8.3 How to Design a Library........................ 48 8.4 Creating a Library............................ 49 8.5 Using a Library............................. 50 9 Benchmarks 50 9.1 A few of libc functions.......................... 51 9.2 Math functions.............................. 53 10 Porting From IAR to AVR GCC 53 10.1 Introduction............................... 53 10.2 Registers................................ 54 10.3 Interrupt Service Routines (ISRs).................... 55 10.4 Intrinsic Routines............................ 55 10.5 Flash Variables............................. 56 10.6 Non-Returning main()......................... 57 10.7 Locking Registers............................ 57 11 Frequently Asked Questions 58 11.1 FAQ Index................................ 58 11.2 My program doesn’t recognize a variable updated within an interrupt routine.................................. 59 11.3 I get "undefined reference to..." for functions like "sin()"....... 60 11.4 How to permanently bind a variable to a register?........... 60 11.5 How to modify MCUCR or WDTCR early?.............. 61 11.6 What is all this _BV() stuff about?................... 61 11.7 Can I use C++ on the AVR?...................... 62 11.8 Shouldn’t I initialize all my variables?................. 63 11.9 Why do some 16-bit timer registers sometimes get trashed?...... 64 11.10How do I use a #define’d constant in an asm statement?........ 65 11.11Why does the PC randomly jump around when single-stepping through my program in avr-gdb?........................ 65 11.12How do I trace an assembler file in avr-gdb?.............. 66 11.13How do I pass an IO port as a parameter to a function?........ 67 Generated on Mon Mar 15 19:22:26 2010 for avr-libc by Doxygen CONTENTS iv 11.14What registers are used by the C compiler?.............. 69 11.15How do I put an array of strings completely in ROM?......... 71 11.16How to use external RAM?....................... 73 11.17Which -O flag to use?.......................... 73 11.18How do I relocate code to a fixed address?............... 74 11.19My UART is generating nonsense! My ATmega128 keeps crashing! Port F is completely broken!...................... 75 11.20Why do all my "foo...bar" strings eat up the SRAM?......... 75 11.21Why does the compiler compile an 8-bit operation that uses bitwise operators into a 16-bit operation in assembly?............. 76 11.22How to detect RAM memory and variable overlap problems?..... 77 11.23Is it really impossible to program the ATtinyXX in C?......... 77 11.24What is this "clock skew detected" message?.............. 78 11.25Why are (many) interrupt flags cleared by writing a logical 1?.... 78 11.26Why have "programmed" fuses the bit value 0?............ 79 11.27Which AVR-specific assembler operators are available?........ 79 11.28Why are interrupts re-enabled in the middle of writing the stack pointer? 79 11.29Why are there five different linker scripts?............... 80 11.30How to add a raw binary image to linker output?............ 80 11.31How do I perform a software reset of the AVR?............ 82 11.32I am using floating point math. Why is the compiled code so big? Why does my code not work?........................ 83 11.33What pitfalls exist when writing reentrant code?............ 83 11.34Why are some addresses of the EEPROM corrupted (usually address zero)?.................................. 85 11.35Why is my baud rate wrong?...................... 86 12 Building and Installing the GNU Tool Chain 86 12.1 Building and Installing under Linux, FreeBSD, and Others...... 87 12.2 Required Tools............................. 87 12.3 Optional Tools.............................. 88 12.4 GNU Binutils for the AVR target.................... 88 12.5 GCC for the AVR target......................... 90 Generated on Mon Mar 15 19:22:26 2010 for avr-libc by Doxygen CONTENTS v 12.6 AVR Libc................................ 90 12.7 AVRDUDE............................... 91 12.8 GDB for the AVR target........................ 91 12.9 SimulAVR................................ 92 12.10AVaRICE................................ 92 12.11Building and Installing under Windows................ 92 12.12Tools Required for Building the Toolchain for Windows........ 93 12.13Building the Toolchain for Windows.................. 96 13 Using the GNU tools 102 13.1 Options for the C compiler avr-gcc................... 102 13.1.1 Machine-specific options for the AVR............. 102 13.1.2 Selected general compiler options............... 108 13.2 Options for the assembler avr-as.................... 109 13.2.1 Machine-specific assembler options.............. 109 13.2.2 Examples for assembler options passed through the C compiler 111 13.3 Controlling the linker avr-ld...................... 111 13.3.1 Selected linker options..................... 111 13.3.2 Passing linker options from the C compiler.......... 112 14 Using the avrdude program 114 15 Release Numbering and Methodology 116 15.1 Release Version Numbering Scheme.................. 116 15.1.1 Stable Versions......................... 116 15.1.2 Development Versions..................... 116 15.2 Releasing AVR Libc.......................... 116 15.2.1 Creating a cvs branch...................... 117 15.2.2 Making a release........................ 118 16 Acknowledgments 119 17 Todo List 120 Generated on Mon Mar 15 19:22:26 2010 for avr-libc by Doxygen CONTENTS vi 18 Deprecated List 120 19 Module Index 121 19.1 Modules................................. 121 20 Data Structure Index 123 20.1 Data Structures............................. 123 21 File Index 123 21.1 File List................................. 123 22 Module Documentation 127 22.1 <alloca.h>: Allocate space in the stack................ 127 22.1.1 Detailed Description...................... 127 22.1.2 Function Documentation.................... 127 22.2 <assert.h>: Diagnostics........................ 128 22.2.1 Detailed Description...................... 128 22.2.2 Define Documentation..................... 128 22.3 <ctype.h>: Character Operations................... 129 22.3.1 Detailed Description...................... 129 22.3.2 Function Documentation.................... 130 22.4 <errno.h>: System Errors....................... 132 22.4.1 Detailed Description...................... 132 22.4.2 Define Documentation..................... 132 22.5 <inttypes.h>: Integer Type conversions................ 132 22.5.1 Detailed Description...................... 135 22.5.2 Define Documentation..................... 135 22.5.3 Typedef Documentation...................