Georg-Johann Lay wrote: > This is basically documentation of AVR specific extensions and stuff like > > * command line options like -maccumulate-args etc. > * AVR named address spaces > > Section doc/extend.texi::Named Address Spaces is split into several > subsections > now; each subsection taking care of one target in alphabetical order: > AVR, M32C, RL78, SPU. > > As I already wrote in http://gcc.gnu.org/ml/gcc/2012-01/msg00175.html > references in the documentation miss their intended anchors/targets. That is a > general problem and not specific to the new references introduced by this > patch. > > Ok to commit? > > Johann > > * doc/extend.texi (Named Address Spaces): Split into subsections. > (AVR Named Address Spaces): New subsection. > (M32C Named Address Spaces): New subsection. > (RL78 Named Address Spaces): New subsection. > (SPU Named Address Spaces): New subsection. > (Variable Attributes): New anchor "AVR Variable Attributes". > (AVR Variable Attributes): Rewrite and avoid wording > "address space" in this context. > * doc/invoke.texi (AVR Options): Rewrite and add documentation > for -maccumulate-args, -mbranch-cost=, -mrelax, -mshort-calls. > (AVR Built-in Macros): New subsubsection therein. > * doc/md.texi (AVR constraints): Remove "C04", "R".
...and for the curious, here is the patch.
Index: doc/extend.texi =================================================================== --- doc/extend.texi (revision 183305) +++ doc/extend.texi (working copy) @@ -1215,15 +1215,192 @@ Pragmas to control overflow and rounding Fixed-point types are supported by the DWARF2 debug information format. @node Named Address Spaces -@section Named address spaces -@cindex named address spaces +@section Named Address Spaces +@cindex Named Address Spaces As an extension, the GNU C compiler supports named address spaces as defined in the N1275 draft of ISO/IEC DTR 18037. Support for named address spaces in GCC will evolve as the draft technical report changes. Calling conventions for any target might also change. At -present, only the SPU, M32C, and RL78 targets support other address -spaces. On the SPU target, for example, variables may be declared as +present, only the AVR, SPU, M32C, and RL78 targets support address +spaces other than the generic address space. + +Address space identifiers may be used exactly like any other C type +qualifier (e.g., @code{const} or @code{volatile}). See the N1275 +document for more details. + +@anchor{AVR Named Address Spaces} +@subsection AVR Named Address Spaces + +On the AVR target, there are several address spaces that can be used +in order to put read-only data into the flash memory and access that +data by means of the special instructions @code{LPM} or @code{ELPM} +needed to read from flash. + +Per default, any data including read-only data is located in RAM so +that address spaces are needed to locate the data in flash memory +@emph{and} to generate the right instructions to access the data +without using (inline) assembler code. + +@table @code +@item __pgm +@cindex @code{__pgm} AVR Named Address Spaces +The @code{__pgm} qualifier will locate data in the +@code{.progmem.data} section. Data will be read using the @code{LPM} +instruction. Pointers to this address space are 16 bits wide. + +@item __pgm1 +@item __pgm2 +@item __pgm3 +@item __pgm4 +@item __pgm5 +@cindex @code{__pgm1} AVR Named Address Spaces +@cindex @code{__pgm2} AVR Named Address Spaces +@cindex @code{__pgm3} AVR Named Address Spaces +@cindex @code{__pgm4} AVR Named Address Spaces +@cindex @code{__pgm5} AVR Named Address Spaces +These are 16-bit address spaces locating data in section +@code{.progmem@var{N}.data} where @var{N} refers to +address space @code{__pgm@var{N}}. +The compiler will set the @code{RAMPZ} segment register approptiately +before reading data by means of the @code{ELPM} instruction. +On devices with less 64kiB flash segments as indicated by the address +space, the compiler will cut down the segment number to a number the +device actually supports (where counting starts at @code{0} +for space @code{__pgm}). For example, if you access address space +@code{__pgm3} on an ATmega128 device with two 64kiB flash segments, +the compiler will generate a read from space @code{__pgm1}, i.e.@: it +will load @code{RAMPZ} with @code{1} before reading. +@item __pgmx +@cindex @code{__pgmx} AVR Named Address Spaces +This is a 24-bit address space that linearizes flash and RAM: +If the high bit of the address is set, data is read from +RAM using the lower two bytes as RAM address. +If the high bit of the address is clear, data is read from flash +with @code{RAMPZ} set according to the high byte of the address. +Objects in this address space will be located in @code{.progmem.data}. +@end table + +For each named address space supported by avr-gcc there is an equally +named but uppercase built-in macro defined. +The purpose is to facilitate testing if respective address space +support is available or not: + +@example +#ifdef __PGM +const __pgm int var = 1; +#else +const int var __attribute__((progmem)) = 1; +#endif /* __PGM */ +@end example + +Notice that attribute @ref{AVR Variable Attributes,@code{progmem}} +locates data in flash but +accesses to these data will be to generic address space, i.e.@: RAM, +so that you need special access functions like @code{pgm_read_byte} +from @w{@uref{http://nongnu.org/avr-libc/user-manual,avr-libc}}. + +@b{Limitations and caveats} + +@itemize +@item +Reading across the 64@tie{}KiB section boundary of +the @code{__pgm} or @code{__pgm@var{N}} address spaces +will show undefined behaviour. The only address space that +supports reading across the 64@tie{}KiB flash segment boundaries is +@code{__pgmx}. + +@item +If you use one if the @code{__pgm@var{N}} address spaces +you will have to arrange your linker skript to +locate the @code{.progmem@var{N}.data} sections according to +your needs. + +@item +Any data or pointers to the AVR address spaces spaces must +also be qualified as @code{const}, i.e.@: as read-only data. +This still applies if the data in one of these address +spaces like software version number or lookup tables are intended to +be changed after load time by, say, a boot loader. In this case +the right qualification is @code{const} @code{volatile} so that the compiler +cannot optimize away known values or insert them +as immediates into operands of instructions. + +@item +Code like the following is not yet supported because of missing +support in avr-binutils, +see @w{@uref{http://sourceware.org/PR13503,PR13503}}. +@example +extern const __pgmx char foo; +const __pgmx void *pointer = &foo; +@end example +The code will throw an assembler warning and the high byte of +@code{pointer} will be initialized with @code{0}, i.e.@: the +initialization will be as if @code{foo} was located in the first +64@tie{}KiB chunk of flash. +@item +Address arithmetic for the @code{__pgmx} address space is carried out +as 16-bit signed integer arithmetic. This means that in the following +code array positions with offsets @math{idx > 8191} are +inaccessible. + +@example +extern const __pgmx long lookup[]; + +long read_lookup (unsigned idx) +@{ + return lookup[idx]; +@} +@end example + +@end itemize + +@b{Example} + +@example +char my_read (const __pgm ** p) +@{ + /* p is a pointer to RAM that points to a pointer to flash. + The first indirection of p will read that flash pointer + from RAM and the second indirection reads a char from this + flash address. */ + + return **p; +@} + +/* Locate array[] in flash memory */ +const __pgm int array[] = @{ 3, 5, 7, 11, 13, 17, 19 @}; + +int i = 1; + +int main (void) +@{ + /* Return 17 by reading from flash memory */ + return array[array[i]]; +@} +@end example + +@subsection M32C Named Address Spaces +@cindex @code{__far} M32C Named Address Spaces + +On the M32C target, with the R8C and M16C cpu variants, variables +qualified with @code{__far} are accessed using 32-bit addresses in +order to access memory beyond the first 64@tie{}Ki bytes. If +@code{__far} is used with the M32CM or M32C cpu variants, it has no +effect. + +@subsection RL78 Named Address Spaces +@cindex @code{__far} RL78 Named Address Spaces + +On the RL78 target, variables qualified with @code{__far} are accessed +with 32-bit pointers (20-bit addresses) rather than the default 16-bit +addresses. Non-far variables are assumed to appear in the topmost +64@tie{}KiB of the address space. + +@subsection SPU Named Address Spaces +@cindex @code{__ea} SPU Named Address Spaces + +On the SPU target variables may be declared as belonging to another address space by qualifying the type with the @code{__ea} address space identifier: @@ -1236,20 +1413,6 @@ special code to access this variable. I support, or generate special machine instructions to access that address space. -The @code{__ea} identifier may be used exactly like any other C type -qualifier (e.g., @code{const} or @code{volatile}). See the N1275 -document for more details. - -On the M32C target, with the R8C and M16C cpu variants, variables -qualified with @code{__far} are accessed using 32-bit addresses in -order to access memory beyond the first 64k bytes. If @code{__far} is -used with the M32CM or M32C cpu variants, it has no effect. - -On the RL78 target, variables qualified with @code{__far} are accessed -with 32-bit pointers (20-bit addresses) rather than the default 16-bit -addresses. Non-far variables are assumed to appear in the topmost 64 -kB of the address space. - @node Zero Length @section Arrays of Length Zero @cindex arrays of length zero @@ -4563,17 +4726,24 @@ The @code{dllexport} attribute is descri @end table +@anchor{AVR Variable Attributes} @subsection AVR Variable Attributes @table @code @item progmem @cindex @code{progmem} AVR variable attribute -The @code{progmem} attribute is used on the AVR to place data in the program -memory address space (flash). This is accomplished by putting -respective variables into a section whose name starts with @code{.progmem}. +The @code{progmem} attribute is used on the AVR to place read-only +data in the non-volatile program memory (flash). The @code{progmem} +attribute accomplishes this by putting respective variables into a +section whose name starts with @code{.progmem}. + +This attrubute wirks similar to the @code{section} attribute +but adds additional checking. Notice that just like the +@code{section} attribute, @code{progmem} affects the location +of the data but not how this data is accessed. -AVR is a Harvard architecture processor and data and reas only data -normally resides in the data memory address space (RAM). +AVR is a Harvard architecture processor and data and read-only data +normally resides in the data memory (RAM). @end table @subsection Blackfin Variable Attributes Index: doc/invoke.texi =================================================================== --- doc/invoke.texi (revision 183305) +++ doc/invoke.texi (working copy) @@ -495,8 +495,9 @@ Objective-C and Objective-C++ Dialects}. -mfix-cortex-m3-ldrd} @emph{AVR Options} -@gccoptlist{-mmcu=@var{mcu} -mno-interrupts @gol --mcall-prologues -mtiny-stack -mint8 -mstrict-X} +@gccoptlist{-mmcu=@var{mcu} -maccumulate-args -mbranch-cost=@var{cost} @gol +-mcall-prologues -mint8 -mno-interrupts -mrelax -mshort-calls @gol +-mstrict-X -mtiny-stack} @emph{Blackfin Options} @gccoptlist{-mcpu=@var{cpu}@r{[}-@var{sirevision}@r{]} @gol @@ -10897,41 +10898,99 @@ These options are defined for AVR implem @table @gcctabopt @item -mmcu=@var{mcu} @opindex mmcu -Specify ATMEL AVR instruction set or MCU type. +Specify Atmel AVR instruction set architectures (ISA) or MCU type. -Instruction set avr1 is for the minimal AVR core, not supported by the C -compiler, only for assembler programs (MCU types: at90s1200, attiny10, -attiny11, attiny12, attiny15, attiny28). - -Instruction set avr2 (default) is for the classic AVR core with up to -8K program memory space (MCU types: at90s2313, at90s2323, attiny22, -at90s2333, at90s2343, at90s4414, at90s4433, at90s4434, at90s8515, -at90c8534, at90s8535). - -Instruction set avr3 is for the classic AVR core with up to 128K program -memory space (MCU types: atmega103, atmega603, at43usb320, at76c711). - -Instruction set avr4 is for the enhanced AVR core with up to 8K program -memory space (MCU types: atmega8, atmega83, atmega85). - -Instruction set avr5 is for the enhanced AVR core with up to 128K program -memory space (MCU types: atmega16, atmega161, atmega163, atmega32, atmega323, -atmega64, atmega128, at43usb355, at94k). +For a complete list of @var{mcu} values that are supported by avr-gcc, +see the compiler output when called with the @code{--help=target} +command line option. +The default for this option is@tie{}@code{avr2}. -@item -mno-interrupts -@opindex mno-interrupts -Generated code is not compatible with hardware interrupts. -Code size will be smaller. +avr-gcc supports the following AVR devices and ISAs: + +@table @code + +@item avr1 +This ISA is implemented by the minimal AVR core and supported +for assembler only. +@*@var{mcu}@tie{}= @code{at90s1200}, +@code{attiny10}, @code{attiny11}, @code{attiny12}, @code{attiny15}, +@code{attiny28}. + +@item avr2 +``Classic'' devices with up to 8@tie{}KiB of program memory. +@*@var{mcu}@tie{}= @code{at90s2313}, @code{attiny26}, @code{at90c8534}, +@dots{} + +@item avr25 +``Classic'' devices with up to 8@tie{}KiB of program memory and with +the @code{MOVW} instruction. +@*@var{mcu}@tie{}= @code{attiny2313}, @code{attiny261}, @code{attiny24}, +@dots{} + +@item avr3 +``Classic'' devices with 16@tie{}KiB up to 64@tie{}KiB of program memory. +@*@var{mcu}@tie{}= @code{at43usb355}, @code{at76c711}. + +@item avr31 +``Classic'' devices with 128@tie{}KiB of program memory. +@*@var{mcu}@tie{}= @code{atmega103}, @code{at43usb320}. + +@item avr35 +``Classic'' devices with 16@tie{}KiB up to 64@tie{}KiB of program +memory and with the @code{MOVW} instruction. +@*@var{mcu}@tie{}= @code{at90usb162}, @code{atmega8u2}, +@code{attiny167}, @dots{} + +@item avr4 +``Enhanced'' devices with up to 8@tie{}KiB of program memory. +@*@var{mcu}@tie{}= @code{atmega8}, @code{atmega88}, @code{at90pwm81}, +@dots{} + +@item avr5 +``Enhanced'' devices with 16@tie{}KiB up to 64@tie{}KiB of program memory. +@*@var{mcu}@tie{}= @code{atmega16}, @code{atmega6490}, @code{at90can64}, +@dots{} + +@item avr51 +``Enhanced'' devices with 128@tie{}KiB of program memory. +@*@var{mcu}@tie{}= @code{atmega128}, @code{at90can128}, @code{at90usb1287}, +@dots{} + +@item avr6 +``Enhanced'' devices with 3-byte PC, i.e.@: with at least 256@tie{}KiB +of program memory. +@*@var{mcu}@tie{}= @code{atmega2560}, @code{atmega2561}. + +@end table + + +@item -maccumulate-args +@opindex maccumulate-args +Accumulate outgoing function arguments and acquire/release the needed +stack space for outgoing function arguments once in function +prologue/epilogue. Without this option, outgoing arguments are pushed +before calling a function and popped afterwards. + +Popping the arguments after the function call can be expensive on +AVR so that accumulating the stack space might lead to smaller +executables because areguments need not to be removed from the +stack after such a function call. + +This option can lead to reduced code size for functions that get +their arguments on the stack like functions that perform several +calls to printf-like functions. + +@item -mbranch-cost=@var{cost} +@opindex mbranch-cost +Set the branch costs for conditional branch instructions to +@var{cost}. Reasonable values for @var{cost} are small, non-negative +integers. The default branch cost is 0. @item -mcall-prologues @opindex mcall-prologues Functions prologues/epilogues expanded as call to appropriate subroutines. Code size will be smaller. -@item -mtiny-stack -@opindex mtiny-stack -Change only the low 8 bits of the stack pointer. - @item -mint8 @opindex mint8 Assume int to be 8 bit integer. This affects the sizes of all types: A @@ -10940,9 +10999,33 @@ and long long will be 4 bytes. Please n comply to the C standards, but it will provide you with smaller code size. +@item -mno-interrupts +@opindex mno-interrupts +Generated code is not compatible with hardware interrupts. +Code size will be smaller. + +@item -mrelax +@opindex mrelax +Try to replace @code{CALL} resp.@: @code{JMP} instruction by the shorter +@code{RCALL} resp.@: @code{RJMP} instruction if applicable. +Setting @code{-mrelax} just adds the @code{--relax} option to the +linker command line when the linker is called. + +Jump relaxing is performed by the linker because jump offsets are not +known before code is located. Therefore, the assembler code generated by the +compiler will be the same, but the instructions in the executable may +differ from instructions in the assembler code. + +@item -mshort-calls +@opindex mshort-calls +Use @code{RCALL}/@code{RJMP} instructions even on devices with +16@tie{}KiB or more of program memory, i.e.@: on devices that +have the @code{CALL} and @code{JMP} instructions. +See also the @code{-mrelax} command line option. + @item -mstrict-X @opindex mstrict-X -Use register @code{X} in a way proposed by the hardware. This means +Use address register @code{X} in a way proposed by the hardware. This means that @code{X} will only be used in indirect, post-increment or pre-decrement addressing. @@ -10950,28 +11033,35 @@ Without this option, the @code{X} regist as @code{Y} or @code{Z} which then is emulated by additional instructions. For example, loading a value with @code{X+const} addressing with a -small @code{const <= 63} to a register @var{Rn} will be printed as +small non-negative @code{const < 64} to a register @var{Rn} will be +performed as + @example -adiw r26, const -ld @var{Rn}, X -sbiw r26, const +adiw r26, const ; X += const +ld @var{Rn}, X ; @var{Rn} = *X +sbiw r26, const ; X -= const @end example + +@item -mtiny-stack +@opindex mtiny-stack +Only use the lower 8@tie{}bits of the stack pointer and assume that the high +byte of SP is always zero. @end table -@subsubsection @code{EIND} and Devices with more than 128k Bytes of Flash +@subsubsection @code{EIND} and Devices with more than 128 Ki Bytes of Flash -Pointers in the implementation are 16 bits wide. +Pointers in the implementation are 16@tie{}bits wide. The address of a function or label is represented as word address so -that indirect jumps and calls can address any code address in the -range of 64k words. +that indirect jumps and calls can target any code address in the +range of 64@tie{}Ki words. -In order to faciliate indirect jump on devices with more than 128k +In order to facilitate indirect jump on devices with more than 128@tie{}Ki bytes of program memory space, there is a special function register called @code{EIND} that serves as most significant part of the target address when @code{EICALL} or @code{EIJMP} instructions are used. -Indirect jumps and calls on these devices are handled as follows and -are subject to some limitations: +Indirect jumps and calls on these devices are handled as follows by +the compiler and are subject to some limitations: @itemize @bullet @@ -10986,19 +11076,20 @@ For the impact of avr-libc on @code{EIND @item The compiler uses @code{EIND} implicitely in @code{EICALL}/@code{EIJMP} -instructions or might read @code{EIND} directly. +instructions or might read @code{EIND} directly in order to emulate an +indirect call/jump by means of a @code{RET} instruction. @item The compiler assumes that @code{EIND} never changes during the startup -code or run of the application. In particular, @code{EIND} is not +code or during the application. In particular, @code{EIND} is not saved/restored in function or interrupt service routine prologue/epilogue. @item It is legitimate for user-specific startup code to set up @code{EIND} early, for example by means of initialization code located in -section @code{.init3}, and thus prior to general startup code that -initializes RAM and calls constructors. +section @code{.init3}. Such code runs prior to general startup code +that initializes RAM and calls constructors. @item For indirect calls to functions and computed goto, the linker will @@ -11053,7 +11144,8 @@ int main (void) @} @end example -Instead, a stub has to be set up: +Instead, a stub has to be set up, i.e.@: the function has to be called +through a symbol (@code{func_4} in the example): @example int main (void) @@ -11069,6 +11161,93 @@ and the application be linked with @code Alternatively, @code{func_4} can be defined in the linker script. @end itemize +@subsubsection AVR Built-in Macros + +avr-gcc defines several built-in macros so that the user code can test +for presence of absence of features. Almost any of the following +built-in macros are deduced from device capabilities and thus +triggered by the @code{-mmcu=} command line option. + +For even more AVR-specific built-in macros see +@ref{AVR Named Address Spaces} and @ref{AVR Built-in Functions}. + + +@table @code + +@item __AVR_@var{Device}__ +Setting @code{-mmcu=@var{device}} defines this built-in macro that reflects +the device's name. For example, @code{-mmcu=atmega8} will define the +built-in macro @code{__AVR_ATmega8__}, @code{-mmcu=attiny261a} defines +@code{__AVR_ATtiny261A__}, etc. + +The built-in macros' names follow +the scheme @code{__AVR_@var{Device}__} where @var{Device} is +the device name as from the AVR user manual. The difference between +@var{Device} in the built-in macro and @var{device} in +@code{-mmcu=@var{device}} is that the latter is always lower case. + +@item __AVR_HAVE_RAMPZ__ +@item __AVR_HAVE_ELPM__ +The device has the @code{RAMPZ} special function register and thus the +@code{ELPM} instruction. + +@item __AVR_HAVE_ELPMX__ +The device has the the @code{ELPM R@var{n},Z} and @code{ELPM +R@var{n},Z+} instructions. + +@item __AVR_HAVE_MOVW__ +The device has the the @code{MOVW} instruction to perform 16-bit +register-register moves. + +@item __AVR_HAVE_LPMX__ +The device has the the @code{LPM R@var{n},Z} and @code{LPM +R@var{n},Z+} instructions. + +@item __AVR_HAVE_MUL__ +The device has a hardware multiplier. + +@item __AVR_HAVE_JMP_CALL__ +The device has the @code{JMP} and @code{CALL} instructions. +This is the case for devices with at least 16@tie{}KiB of program +memory and if @code{-mshort-calls} is not set. + +@item __AVR_HAVE_EIJMP_EICALL__ +@item __AVR_3_BYTE_PC__ +The device has the the @code{EIJMP} and @code{EICALL} instructions. +This is the case for devices with at least 256@tie{}KiB of program memory. +This also means that the program counter +(PC) is 3@tie{}bytes wide. + +@item __AVR_2_BYTE_PC__ +The program counter (PC) is 2@tie{}bytes wide. This is the case for devices +with up to 128@tie{}KiB of program memory. + +@item __AVR_HAVE_8BIT_SP__ +@item __AVR_HAVE_16BIT_SP__ +The stack pointer (SP) is 8@tie{}bits resp. 16@tie{}bits wide. +The definition of these macros is affected by @code{-mtiny-stack}. + +@item __NO_INTERRUPTS__ +This macro reflects the @code{-mno-interrupts} command line option. + +@item __AVR_ERRATA_SKIP__ +@item __AVR_ERRATA_SKIP_JMP_CALL__ +Some AVR devices (AT90S8515, ATmega103) must not skip 32-bit +instructions because of a hardware erratum. Skip instructions are +@code{SBRS}, @code{SBRC}, @code{SBIS}, @code{SBIC} and @code{CPSE}. +The second macro is only defined if @code{__AVR_HAVE_JMP_CALL__} is also +set. + +@item __AVR_SFR_OFFSET__=@var{offset} +Instructions that can address I/O special function registers directly +like @code{IN}, @code{OUT}, @code{SBI}, etc.@: may use a different +address as if addressed by an instruction to access RAM like @code{LD} +or @code{STS}. This offset depends on the device architecture and has +to be subtracted from the RAM address in order to get the +respective I/O@tie{}address. + +@end table + @node Blackfin Options @subsection Blackfin Options @cindex Blackfin Options Index: doc/md.texi =================================================================== --- doc/md.texi (revision 183305) +++ doc/md.texi (working copy) @@ -1768,14 +1768,8 @@ Constant integer 1 @item G A floating point constant 0.0 -@item R -Integer constant in the range @minus{}6 @dots{} 5. - @item Q A memory address based on Y or Z pointer with displacement. - -@item C04 -Constant integer 4 @end table @item Epiphany---@file{config/epiphany/constraints.md}