| /* Copyright (c) 2002,2005, 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: sections.dox 845 2005-09-06 18:17:43Z joerg_wunsch $ */ |
| |
| /** \page mem_sections Memory Sections |
| |
| \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. |
| |
| \section 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. |
| |
| \section 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 |
| |
| It is possible to tell the linker the SRAM address of the beginning of the |
| .data section. This is accomplished by adding |
| <b><tt>-Wl,-Tdata,<em>addr</em></tt></b> to the \c avr-gcc command used to the |
| link your program. Not that <em><tt>addr</tt></em> must be offset by adding |
| 0x800000 the to real SRAM address so that the linker knows that the address is |
| in the SRAM memory space. Thus, if you want the .data section to start at |
| 0x1100, pass 0x801100 at the address to the linker. |
| [offset \ref harvard_arch "explained"] |
| |
| \note |
| When using \c malloc() in the application (which could even happen inside |
| library calls), \ref malloc_extram "additional adjustments" are required. |
| |
| \section sec_dot_bss The .bss Section |
| |
| Uninitialized global or static variables end up in the .bss section. |
| |
| \section sec_dot_eeprom The .eeprom Section |
| |
| This is where eeprom variables are stored. |
| |
| \section 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 |
| |
| It is possible to tell the linker explicitly where to place the .noinit |
| section by adding <tt>-Wl,--section-start=.noinit=0x802000</tt> to the |
| <tt>avr-gcc</tt> command line at the linking stage. For example, suppose you |
| wish to place the .noinit section at SRAM address 0x2000: |
| |
| \verbatim |
| $ avr-gcc ... -Wl,--section-start=.noinit=0x802000 ... |
| \endverbatim |
| |
| \anchor harvard_arch |
| \note Because of the Harvard architecture of the AVR devices, you must |
| manually add 0x800000 to the address you pass to the linker as the start of |
| the section. Otherwise, the linker thinks you want to put the .noinit section |
| into the .text section instead of .data/.bss and will complain. |
| |
| Alternatively, you can write your own linker script to automate this. [FIXME: |
| need an example or ref to dox for writing linker scripts.] |
| |
| \section sec_dot_init The .initN 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. |
| |
| \note Sometimes, it is convenient to think of the .initN and .finiN sections as |
| functions, but in reality they are just symbolic names which tell the linker |
| where to stick a chunk of code which is \em not a function. Notice that the |
| examples for \ref asm_sections "asm" and \ref c_sections "C" can not be called |
| as functions and should not be jumped into. |
| |
| The <b>.initN</b> 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, and to clear |
| __zero_reg__ (r1). |
| |
| \par .init3: |
| Unused. User definable. |
| |
| \par .init4: |
| |
| For devices with > 64 KB of ROM, .init4 defines the code |
| which takes care of copying the contents of .data from the flash to |
| SRAM. |
| For all other devices, this code as well as the code to zero out the .bss |
| section is loaded from libgcc.a. |
| |
| \par .init5: |
| Unused. User definable. |
| |
| \par .init6: |
| Unused 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(). |
| |
| \section sec_dot_fini The .finiN 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 <b>.finiN</b> sections are executed in descending order from 9 to 0. |
| |
| \par .finit9: |
| Unused. User definable. This is effectively where _exit() starts. |
| |
| \par .fini8: |
| Unused. User definable. |
| |
| \par .fini7: |
| Unused. User definable. |
| |
| \par .fini6: |
| Unused for C programs, but used for destructors in C++ programs. |
| |
| \par .fini5: |
| Unused. User definable. |
| |
| \par .fini4: |
| Unused. User definable. |
| |
| \par .fini3: |
| Unused. User definable. |
| |
| \par .fini2: |
| Unused. User definable. |
| |
| \par .fini1: |
| Unused. User definable. |
| |
| \par .fini0: |
| Goes into an infinite loop after program termination and completion of any |
| _exit() code (execution of code in the .fini9 -> .fini1 sections). |
| |
| \section asm_sections Using Sections in Assembler Code |
| |
| Example: |
| |
| \code |
| #include <avr/io.h> |
| |
| .section .init1,"ax",@progbits |
| ldi r0, 0xff |
| out _SFR_IO_ADDR(PORTB), r0 |
| out _SFR_IO_ADDR(DDRB), r0 |
| \endcode |
| |
| \note The <b><tt>,"ax",\@progbits</tt></b> tells the assembler that the section |
| is allocatable ("a"), executable ("x") and contains data ("@progbits"). For |
| more detailed information on the .section directive, see the gas user manual. |
| |
| <!-- I know, poorly named section. - TRoth --> |
| \section c_sections Using Sections in C Code |
| |
| Example: |
| |
| \code |
| #include <avr/io.h> |
| |
| void my_init_portb (void) __attribute__ ((naked)) \ |
| __attribute__ ((section (".init3"))); |
| |
| void |
| my_init_portb (void) |
| { |
| PORTB = 0xff; |
| DDRB = 0xff; |
| } |
| \endcode |
| |
| \note Section .init3 is used in this example, as this ensures the |
| inernal <tt>__zero_reg__</tt> has already been set up. The code |
| generated by the compiler might blindly rely on <tt>__zero_reg__</tt> |
| being really 0. |
| |
| */ |
| |