2002-08-30 Theodore A. Roth * doc/api/Makefile.am: Add sections.dox. * doc/api/sections.dox: New file. Index: doc/api/Makefile.am =================================================================== RCS file: /cvsroot/avr-libc/avr-libc/doc/api/Makefile.am,v retrieving revision 1.15 diff -u -r1.15 Makefile.am --- doc/api/Makefile.am 21 Aug 2002 19:16:56 -0000 1.15 +++ doc/api/Makefile.am 30 Aug 2002 06:48:30 -0000 @@ -39,6 +39,7 @@ inline_asm.dox \ interrupts.dox \ acknowledge.dox \ + sections.dox \ sfr.dox \ tools-install.dox \ faq.dox Index: doc/api/sections.dox =================================================================== RCS file: doc/api/sections.dox diff -N doc/api/sections.dox --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ doc/api/sections.dox 30 Aug 2002 06:48:30 -0000 @@ -0,0 +1,211 @@ +/* Copyright (c) 2002, Theodore Roth + 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. + + 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$ */ + +/** \page mem_sections Memory Sections + +See \ref faq_startup for a simple intro to this for now. + +\remarks Need to list all the sections which are available to the avr. + +\par Weak Bindings +FIXME: need to discuss the .weak directive. + +The following describes the various sections available. + +\subsection sec_dot_text The .text Section + +The .text section contains the actual machine instructions which make up +your program. This section is further subdivided by the .initN and .finiN +sections dicussed below. + +\note The \c avr-size program (part of binutils), coming from a Unix +background, doesn't account for the .data initialization space added to the +.text section, so in order to know how much flash the final program will +consume, one needs to add the values for both, .text and .data (but not .bss), +while the amount of pre-allocated SRAM is the sum of .data and .bss. + +\subsection sec_dot_data The .data Section + +This section contains static data which was defined in your code. Things like +the following would end up in .data: + +\code +char err_str[] = "Your program has died a horrible death!"; + +struct point pt = { 1, 1 }; +\endcode + +\subsection sec_dot_bss The .bss Section + +Uninitialized global or static variables end up in the .bss section. + +\subsection sec_dot_text The .eeprom Section + +This is where eeprom variables are stored. + +\subsection sec_dot_noinit The .noinit Section + +This sections is a part of the .bss section. What makes the .noinit section +special is that variables which are defined as such: + +\code +int foo __attribute__ ((section (".noinit"))); +\endcode + +will not be initialized to zero during startup as would normal .bss data. + +Only uninitialized variables can be placed in the .noinit section. Thus, the +following code will cause \c avr-gcc to issue an error: + +\code +int bar __attribute__ ((section (".noinit"))) = 0xaa; +\endcode + +\subsection sec_dot_init The .init Sections + +These sections are used to define the startup code from reset up through +the start of main(). These all are subparts of the +\ref sec_dot_text ".text section". + +The purpose of these sections is to allow for more specific placement of code +within your program. + +The .initN sections are executed in order from 0 to 9. + +\par .init0: +Weakly bound to __init(). If user defines __init(), it will be jumped into +immediately after a reset. + +\par .init1: +Unused. User definable. + +\par .init2: +In C programs, weakly bound to initialize the stack. + +\par .init3: +Unused. User definable. + +\par .init4: + +Copies the .data section from flash to SRAM. Also sets up and zeros out the +.bss section. In Unix-like targets, .data is normally initialized by the OS +directly from the executable file. Since this is impossible in an MCU +environment, \c avr-gcc instead takes care of appending the .data variables +after .text in the flash ROM image. .init4 then defines the code (weakly +bound) which takes care of copying the contents of .data from the flash to +SRAM. + +\par .init5: +Unused. User definable. + +\par .init6: +Unsed for C programs, but used for constructors in C++ programs. + +\par .init7: +Unused. User definable. + +\par .init8: +Unused. User definable. + +\par .init9: +Jumps into main(). + +\subsection sec_dot_fini The .fini Sections + +These sections are used to define the exit code executed after return from +main() or a call to exit(). These all are subparts of the +\ref sec_dot_text ".text section". + +The .finiN sections are executed in descending order from 9 to 0. + +\par .fini0: +Jump into _exit(), which is just an infinite loop. This is the very last code +your program will execute. + +\par .fini1: +Unused. User definable. + +\par .fini2: +Unused. User definable. + +\par .fini3: +Unused. User definable. + +\par .fini4: +Unused. User definable. + +\par .fini5: +Unused. User definable. + +\par .fini6: +Unsed for C programs, but used for destructors in C++ programs. + +\par .fini7: +Unused. User definable. + +\par .fini8: +Unused. User definable. + +\par .finit9: +Unused. User definable. + +\subsection asm_sections Using Sections in Assembler Code + +Example: + +\code +#include + + .section .init1,"ax",@progbits + ldi r0, 0xff + out _SFR_IO_ADDR(PORTB), r0 + out _SFR_IO_ADDR(DDRB), r0 +\endcode + +\remarks What is ,"ax",@progbits part doing??? + + +\subsection c_sections Using Sections in C Code + +Example: + +\code +#include + +void my_init_portb (void) __attribute__ ((naked)) \ + __attribute__ ((section (".init1"))); + +void +my_init_portb (void) +{ + outb (PORTB, 0xff); + outb (DDRB, 0xff); +} +\endcode + +*/ +