diff options
Diffstat (limited to 'gcc-4.6/gcc/doc/invoke.texi')
| -rw-r--r-- | gcc-4.6/gcc/doc/invoke.texi | 320 |
1 files changed, 234 insertions, 86 deletions
diff --git a/gcc-4.6/gcc/doc/invoke.texi b/gcc-4.6/gcc/doc/invoke.texi index 05b6df9..98c270c 100644 --- a/gcc-4.6/gcc/doc/invoke.texi +++ b/gcc-4.6/gcc/doc/invoke.texi @@ -391,10 +391,12 @@ Objective-C and Objective-C++ Dialects}. -fpmu-profile-generate=@var{pmuoption} @gol -fpmu-profile-use=@var{pmuoption} @gol -freciprocal-math -fregmove -frename-registers -freorder-blocks @gol +-frecord-gcc-switches-in-elf@gol -freorder-blocks-and-partition -freorder-functions @gol -frerun-cse-after-loop -freschedule-modulo-scheduled-loops @gol -fripa -fripa-disallow-asm-modules -fripa-disallow-opt-mismatch @gol --fripa-no-promote-always-inline-func -fripa-verbose -frounding-math @gol +-fripa-no-promote-always-inline-func -fripa-verbose @gol +-fripa-peel-size-limit -fripa-unroll-size-limit -frounding-math @gol -fsched2-use-superblocks -fsched-pressure @gol -fsched-spec-load -fsched-spec-load-dangerous @gol -fsched-stalled-insns-dep[=@var{n}] -fsched-stalled-insns[=@var{n}] @gol @@ -406,8 +408,8 @@ Objective-C and Objective-C++ Dialects}. -fsel-sched-pipelining -fsel-sched-pipelining-outer-loops @gol -fsignaling-nans -fsingle-precision-constant -fsplit-ivs-in-unroller @gol -fsplit-wide-types -fstack-protector -fstack-protector-all @gol --fstrict-aliasing -fstrict-overflow -fthread-jumps -ftracer @gol --ftree-bit-ccp @gol +-fstack-protector-strong -fstrict-aliasing -fstrict-overflow @gol +-fthread-jumps -ftracer -ftree-bit-ccp @gol -ftree-builtin-call-dce -ftree-ccp -ftree-ch -ftree-copy-prop @gol -ftree-copyrename -ftree-dce -ftree-dominator-opts -ftree-dse @gol -ftree-forwprop -ftree-fre -ftree-loop-if-convert @gol @@ -893,7 +895,8 @@ See RS/6000 and PowerPC Options. -mlittle-endian @gol -mstack-bias -mno-stack-bias @gol -munaligned-doubles -mno-unaligned-doubles @gol --mv8plus -mno-v8plus -mvis -mno-vis} +-mv8plus -mno-v8plus -mvis -mno-vis @gol +-mfix-at697f} @emph{SPU Options} @gccoptlist{-mwarn-reloc -merror-reloc @gol @@ -7802,8 +7805,8 @@ file. When the object files are linked together, all the function bodies are read from these ELF sections and instantiated as if they had been part of the same translation unit. -To use the link-timer optimizer, @option{-flto} needs to be specified at -compile time and during the final link. For example, +To use the link-time optimizer, @option{-flto} needs to be specified at +compile time and during the final link. For example: @smallexample gcc -c -O2 -flto foo.c @@ -7811,25 +7814,25 @@ gcc -c -O2 -flto bar.c gcc -o myprog -flto -O2 foo.o bar.o @end smallexample -The first two invocations to GCC will save a bytecode representation +The first two invocations to GCC save a bytecode representation of GIMPLE into special ELF sections inside @file{foo.o} and -@file{bar.o}. The final invocation will read the GIMPLE bytecode from -@file{foo.o} and @file{bar.o}, merge the two files into a single -internal image, and compile the result as usual. Since both +@file{bar.o}. The final invocation reads the GIMPLE bytecode from +@file{foo.o} and @file{bar.o}, merges the two files into a single +internal image, and compiles the result as usual. Since both @file{foo.o} and @file{bar.o} are merged into a single image, this -causes all the inter-procedural analyses and optimizations in GCC to +causes all the interprocedural analyses and optimizations in GCC to work across the two files as if they were a single one. This means, -for example, that the inliner will be able to inline functions in +for example, that the inliner is able to inline functions in @file{bar.o} into functions in @file{foo.o} and vice-versa. -Another (simpler) way to enable link-time optimization is, +Another (simpler) way to enable link-time optimization is: @smallexample gcc -o myprog -flto -O2 foo.c bar.c @end smallexample -The above will generate bytecode for @file{foo.c} and @file{bar.c}, -merge them together into a single GIMPLE representation and optimize +The above generates bytecode for @file{foo.c} and @file{bar.c}, +merges them together into a single GIMPLE representation and optimizes them as usual to produce @file{myprog}. The only important thing to keep in mind is that to enable link-time @@ -7839,30 +7842,22 @@ compile and the link commands. To make whole program optimization effective, it is necessary to make certain whole program assumptions. The compiler needs to know what functions and variables can be accessed by libraries and runtime -outside of the link time optimized unit. When supported by the linker, -the linker plugin (see @option{-fuse-linker-plugin}) passes to the -compiler information about used and externally visible symbols. When +outside of the link-time optimized unit. When supported by the linker, +the linker plugin (see @option{-fuse-linker-plugin}) passes information +to the compiler about used and externally visible symbols. When the linker plugin is not available, @option{-fwhole-program} should be -used to allow the compiler to make these assumptions, which will lead +used to allow the compiler to make these assumptions, which leads to more aggressive optimization decisions. Note that when a file is compiled with @option{-flto}, the generated -object file will be larger than a regular object file because it will -contain GIMPLE bytecodes and the usual final code. This means that -object files with LTO information can be linked as a normal object -file. So, in the previous example, if the final link is done with - -@smallexample -gcc -o myprog foo.o bar.o -@end smallexample - -The only difference will be that no inter-procedural optimizations -will be applied to produce @file{myprog}. The two object files -@file{foo.o} and @file{bar.o} will be simply sent to the regular -linker. +object file is larger than a regular object file because it +contains GIMPLE bytecodes and the usual final code. This means that +object files with LTO information can be linked as normal object +files; if @option{-flto} is not passed to the linker, no +interprocedural optimizations are applied. Additionally, the optimization flags used to compile individual files -are not necessarily related to those used at link-time. For instance, +are not necessarily related to those used at link time. For instance, @smallexample gcc -c -O0 -flto foo.c @@ -7870,37 +7865,42 @@ gcc -c -O0 -flto bar.c gcc -o myprog -flto -O3 foo.o bar.o @end smallexample -This will produce individual object files with unoptimized assembler -code, but the resulting binary @file{myprog} will be optimized at -@option{-O3}. Now, if the final binary is generated without -@option{-flto}, then @file{myprog} will not be optimized. +This produces individual object files with unoptimized assembler +code, but the resulting binary @file{myprog} is optimized at +@option{-O3}. If, instead, the final binary is generated without +@option{-flto}, then @file{myprog} is not optimized. -When producing the final binary with @option{-flto}, GCC will only -apply link-time optimizations to those files that contain bytecode. +When producing the final binary with @option{-flto}, GCC only +applies link-time optimizations to those files that contain bytecode. Therefore, you can mix and match object files and libraries with -GIMPLE bytecodes and final object code. GCC will automatically select +GIMPLE bytecodes and final object code. GCC automatically selects which files to optimize in LTO mode and which files to link without further processing. -There are some code generation flags that GCC will preserve when +There are some code generation flags that GCC preserves when generating bytecodes, as they need to be used during the final link stage. Currently, the following options are saved into the GIMPLE bytecode files: @option{-fPIC}, @option{-fcommon} and all the @option{-m} target flags. -At link time, these options are read-in and reapplied. Note that the -current implementation makes no attempt at recognizing conflicting -values for these options. If two or more files have a conflicting -value (e.g., one file is compiled with @option{-fPIC} and another -isn't), the compiler will simply use the last value read from the -bytecode files. It is recommended, then, that all the files -participating in the same link be compiled with the same options. +At link time, these options are read in and reapplied. Note that the +current implementation makes no attempt to recognize conflicting +values for these options. If different files have conflicting option +values (e.g., one file is compiled with @option{-fPIC} and another +isn't), the compiler simply uses the last value read from the +bytecode files. It is recommended, then, that you compile all the files +participating in the same link with the same options. + +If LTO encounters objects with C linkage declared with incompatible +types in separate translation units to be linked together (undefined +behavior according to ISO C99 6.2.7), a non-fatal diagnostic may be +issued. The behavior is still undefined at runtime. Another feature of LTO is that it is possible to apply interprocedural optimizations on files written in different languages. This requires -some support in the language front end. Currently, the C, C++ and +support in the language front end. Currently, the C, C++ and Fortran front ends are capable of emitting GIMPLE bytecodes, so -something like this should work +something like this should work: @smallexample gcc -c -flto foo.c @@ -7912,49 +7912,43 @@ g++ -o myprog -flto -O3 foo.o bar.o baz.o -lgfortran Notice that the final link is done with @command{g++} to get the C++ runtime libraries and @option{-lgfortran} is added to get the Fortran runtime libraries. In general, when mixing languages in LTO mode, you -should use the same link command used when mixing languages in a -regular (non-LTO) compilation. This means that if your build process -was mixing languages before, all you need to add is @option{-flto} to +should use the same link command options as when mixing languages in a +regular (non-LTO) compilation; all you need to add is @option{-flto} to all the compile and link commands. -If LTO encounters objects with C linkage declared with incompatible -types in separate translation units to be linked together (undefined -behavior according to ISO C99 6.2.7), a non-fatal diagnostic may be -issued. The behavior is still undefined at runtime. - If object files containing GIMPLE bytecode are stored in a library archive, say @file{libfoo.a}, it is possible to extract and use them in an LTO link if you -are using a linker with linker plugin support. To enable this feature, use -the flag @option{-fuse-linker-plugin} at link-time: +are using a linker with plugin support. To enable this feature, use +the flag @option{-fuse-linker-plugin} at link time: @smallexample gcc -o myprog -O2 -flto -fuse-linker-plugin a.o b.o -lfoo @end smallexample -With the linker plugin enabled, the linker will extract the needed -GIMPLE files from @file{libfoo.a} and pass them on to the running GCC +With the linker plugin enabled, the linker extracts the needed +GIMPLE files from @file{libfoo.a} and passes them on to the running GCC to make them part of the aggregated GIMPLE image to be optimized. -If you are not using a linker with linker plugin support and/or do not -enable linker plugin then the objects inside @file{libfoo.a} -will be extracted and linked as usual, but they will not participate +If you are not using a linker with plugin support and/or do not +enable the linker plugin, then the objects inside @file{libfoo.a} +are extracted and linked as usual, but they do not participate in the LTO optimization process. -Link time optimizations do not require the presence of the whole program to +Link-time optimizations do not require the presence of the whole program to operate. If the program does not require any symbols to be exported, it is -possible to combine @option{-flto} and with @option{-fwhole-program} to allow +possible to combine @option{-flto} and @option{-fwhole-program} to allow the interprocedural optimizers to use more aggressive assumptions which may lead to improved optimization opportunities. Use of @option{-fwhole-program} is not needed when linker plugin is active (see @option{-fuse-linker-plugin}). -Regarding portability: the current implementation of LTO makes no -attempt at generating bytecode that can be ported between different +The current implementation of LTO makes no +attempt to generate bytecode that is portable between different types of hosts. The bytecode files are versioned and there is a strict version check, so bytecode files generated in one version of GCC will not work with an older/newer version of GCC. -Link time optimization does not play well with generating debugging +Link-time optimization does not work well with generation of debugging information. Combining @option{-flto} with @option{-g} is currently experimental and expected to produce wrong results. @@ -7968,15 +7962,15 @@ used. The default value for @var{n} is 1. You can also specify @option{-flto=jobserver} to use GNU make's job server mode to determine the number of parallel jobs. This is useful when the Makefile calling GCC is already executing in parallel. -The parent Makefile will need a @samp{+} prepended to the command recipe -for this to work. This will likely only work if @env{MAKE} is +You must prepend a @samp{+} to the command recipe in the parent Makefile +for this to work. This option likely only works if @env{MAKE} is GNU make. This option is disabled by default. @item -flto-partition=@var{alg} @opindex flto-partition -Specify the partitioning algorithm used by the link time optimizer. +Specify the partitioning algorithm used by the link-time optimizer. The value is either @code{1to1} to specify a partitioning mirroring the original source files or @code{balanced} to specify partitioning into equally sized chunks (whenever possible). Specifying @code{none} @@ -7993,27 +7987,29 @@ given, a default balanced compression setting is used. @item -flto-report Prints a report with internal details on the workings of the link-time -optimizer. The contents of this report vary from version to version, -it is meant to be useful to GCC developers when processing object +optimizer. The contents of this report vary from version to version. +It is meant to be useful to GCC developers when processing object files in LTO mode (via @option{-flto}). Disabled by default. @item -fuse-linker-plugin -Enables the use of linker plugin during link time optimization. This option -relies on the linker plugin support in linker that is available in gold +Enables the use of a linker plugin during link-time optimization. This +option relies on the linker plugin support in linker that is available in gold or in GNU ld 2.21 or newer. -This option enables the extraction of object files with GIMPLE bytecode out of -library archives. This improves the quality of optimization by exposing more -code the the link time optimizer. This information specify what symbols -can be accessed externally (by non-LTO object or during dynamic linking). -Resulting code quality improvements on binaries (and shared libraries that do -use hidden visibility) is similar to @code{-fwhole-program}. See -@option{-flto} for a description on the effect of this flag and how to use it. +This option enables the extraction of object files with GIMPLE bytecode out +of library archives. This improves the quality of optimization by exposing +more code to the link-time optimizer. This information specifies what +symbols can be accessed externally (by non-LTO object or during dynamic +linking). Resulting code quality improvements on binaries (and shared +libraries that use hidden visibility) are similar to @code{-fwhole-program}. +See @option{-flto} for a description of the effect of this flag and how to +use it. -Enabled by default when LTO support in GCC is enabled and GCC was compiled -with a linker supporting plugins (GNU ld 2.21 or newer or gold). +This option is enabled by default when LTO support in GCC is enabled +and GCC was configured for use with +a linker supporting plugins (GNU ld 2.21 or newer or gold). @item -fcompare-elim @opindex fcompare-elim @@ -8162,6 +8158,20 @@ Do not promote static functions with always inline attribute in LIPO compilation Enable printing of verbose information about dynamic inter-procedural optimizations. This is used in conjunction with the @option{-fripa}. +@item -fripa-peel-size-limit +@opindex fripa-peel-size-limit +Limit loop peeling of non-const non-FP loops in a LIPO compilation under estimates +of a large code footprint. Enabled by default under @option{-fripa}. Code size +estimation and thresholds are controlled by the @option{codesize-hotness-threshold} +and @option{unrollpeel-codesize-threshold} parameters. + +@item -fripa-unroll-size-limit +@opindex fripa-unroll-size-limit +Limit loop unrolling of non-const non-FP loops in a LIPO compilation under estimates +of a large code footprint. Enabled by default under @option{-fripa}. Code size +estimation and thresholds are controlled by the @option{codesize-hotness-threshold} +and @option{unrollpeel-codesize-threshold} parameters. + @item -fcallgraph-profiles-sections @opindex fcallgraph-profiles-sections Emit call graph edge profile counts in .note.callgraph.text sections. This is @@ -8170,6 +8180,11 @@ section is created for each function. This section lists every callee and the number of times it is called. The params variable "note-cgraph-section-edge-threshold" can be used to only list edges above a certain threshold. + +@item -frecord-gcc-switches-in-elf +@opindex frecord-gcc-switches-in-elf +Record the command line options in the .gnu.switches.text elf section for sample +based LIPO to do module grouping. @end table The following options control compiler behavior regarding floating @@ -8564,6 +8579,12 @@ If a guard check fails, an error message is printed and the program exits. @opindex fstack-protector-all Like @option{-fstack-protector} except that all functions are protected. +@item -fstack-protector-strong +@opindex fstack-protector-strong +Like @option{-fstack-protector} but includes additional functions to be +protected - those that have local array definitions, or have references to +local frame addresses. + @item -fsection-anchors @opindex fsection-anchors Try to reduce the number of symbolic address calculations by using @@ -8877,6 +8898,13 @@ hot loops. Its default value is 16. @item max-completely-peel-loop-nest-depth The maximum depth of a loop nest suitable for complete peeling. +@item codesize-hotness-threshold +The minimum profile count of basic blocks to look at when estimating +the code size footprint of the call graph in a LIPO compile. + +@item unrollpeel-codesize-threshold +Maximum LIPO code size footprint estimate for loop unrolling and peeling. + @item max-unswitch-insns The maximum number of insns of an unswitched loop. @@ -10888,6 +10916,117 @@ comply to the C standards, but it will provide you with smaller code size. @end table +@subsubsection @code{EIND} and Devices with more than 128k Bytes of Flash + +Pointers in the implementation are 16 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. + +In order to faciliate indirect jump on devices with more than 128k +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: + +@itemize @bullet + +@item +The compiler never sets @code{EIND}. + +@item +The startup code from libgcc never sets @code{EIND}. +Notice that startup code is a blend of code from libgcc and avr-libc. +For the impact of avr-libc on @code{EIND}, see the +@w{@uref{http://nongnu.org/avr-libc/user-manual,avr-libc user manual}}. + +@item +The compiler uses @code{EIND} implicitely in @code{EICALL}/@code{EIJMP} +instructions or might read @code{EIND} directly. + +@item +The compiler assumes that @code{EIND} never changes during the startup +code or run of 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. + +@item +For indirect calls to functions and computed goto, the linker will +generate @emph{stubs}. Stubs are jump pads sometimes also called +@emph{trampolines}. Thus, the indirect call/jump will jump to such a stub. +The stub contains a direct jump to the desired address. + +@item +Stubs will be generated automatically by the linker if +the following two conditions are met: +@itemize @minus + +@item The address of a label is taken by means of the @code{gs} modifier +(short for @emph{generate stubs}) like so: +@example +LDI r24, lo8(gs(@var{func})) +LDI r25, hi8(gs(@var{func})) +@end example +@item The final location of that label is in a code segment +@emph{outside} the segment where the stubs are located. +@end itemize + +@item +The compiler will emit such @code{gs} modifiers for code labels in the +following situations: +@itemize @minus +@item Taking address of a function or code label. +@item Computed goto. +@item If prologue-save function is used, see @option{-mcall-prologues} +command line option. +@item Switch/case dispatch tables. If you do not want such dispatch +tables you can specify the @option{-fno-jump-tables} command line option. +@item C and C++ constructors/destructors called during startup/shutdown. +@item If the tools hit a @code{gs()} modifier explained above. +@end itemize + +@item +The default linker script is arranged for code with @code{EIND = 0}. +If code is supposed to work for a setup with @code{EIND != 0}, a custom +linker script has to be used in order to place the sections whose +name start with @code{.trampolines} into the segment where @code{EIND} +points to. + +@item +Jumping to non-symbolic addresses like so is @emph{not} supported: + +@example +int main (void) +@{ + /* Call function at word address 0x2 */ + return ((int(*)(void)) 0x2)(); +@} +@end example + +Instead, a stub has to be set up: + +@example +int main (void) +@{ + extern int func_4 (void); + + /* Call function at byte address 0x4 */ + return func_4(); +@} +@end example + +and the application be linked with @code{-Wl,--defsym,func_4=0x4}. +Alternatively, @code{func_4} can be defined in the linker script. +@end itemize + @node Blackfin Options @subsection Blackfin Options @cindex Blackfin Options @@ -12585,6 +12724,10 @@ and SSE4.2 instruction set support. @item corei7-avx Intel Core i7 CPU with 64-bit extensions, MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, AVX, AES and PCLMUL instruction set support. +@item core-avx-i +Intel Core CPU with 64-bit extensions, MMX, SSE, SSE2, SSE3, SSSE3, +SSE4.1, SSE4.2, AVX, AES, PCLMUL, FSGSBASE, RDRND and F16C instruction +set support. @item atom Intel Atom CPU with 64-bit extensions, MMX, SSE, SSE2, SSE3 and SSSE3 instruction set support. @@ -17625,6 +17768,11 @@ mode for all SPARC-V9 processors. @opindex mno-vis With @option{-mvis}, GCC generates code that takes advantage of the UltraSPARC Visual Instruction Set extensions. The default is @option{-mno-vis}. + +@item -mfix-at697f +@opindex mfix-at697f +Enable the documented workaround for the single erratum of the Atmel AT697F +processor (which corresponds to erratum #13 of the AT697E processor). @end table These @samp{-m} options are supported in addition to the above |