From: Sandra Loosemore Date: Sat, 16 Jan 2016 23:06:43 +0000 (-0500) Subject: invoke.texi (Invoking GCC): Add new section to menu. X-Git-Tag: basepoints/gcc-7~1561 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b81946e524624ce3ec8ddd6acadf52803adb0a12;p=thirdparty%2Fgcc.git invoke.texi (Invoking GCC): Add new section to menu. 2016-01-16 Sandra Loosemore gcc/ * doc/invoke.texi (Invoking GCC): Add new section to menu. (Option Summary): Update to reflect new section and moved options. (C++ Dialect Options): Move -fvtable-verify and related options. (Debugging Options): Move Sanitizer, Pointer Bounds Checker, and profiling-related options. (Optimization Options): Move profile generation options and -fstack-protector and related options. (Instrumentation Options): New section incorporating moved options. (Code Generation Options): Move -finstrument-functions and related options, -fstack-check, -fstack-limit*, and -fbounds-check. From-SVN: r232475 --- diff --git a/gcc/ChangeLog b/gcc/ChangeLog index f840fc785a62..1b446ac75e0d 100644 --- a/gcc/ChangeLog +++ b/gcc/ChangeLog @@ -1,3 +1,16 @@ +2016-01-16 Sandra Loosemore + + * doc/invoke.texi (Invoking GCC): Add new section to menu. + (Option Summary): Update to reflect new section and moved options. + (C++ Dialect Options): Move -fvtable-verify and related options. + (Debugging Options): Move Sanitizer, Pointer Bounds Checker, + and profiling-related options. + (Optimization Options): Move profile generation options and + -fstack-protector and related options. + (Instrumentation Options): New section incorporating moved options. + (Code Generation Options): Move -finstrument-functions and + related options, -fstack-check, -fstack-limit*, and -fbounds-check. + 2016-01-16 Tom de Vries * passes.def: Move pass_expand_omp_ssa out of pass_parallelize_loops. diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi index 070a51624995..66861937d811 100644 --- a/gcc/doc/invoke.texi +++ b/gcc/doc/invoke.texi @@ -140,6 +140,7 @@ only one of these two forms, whichever one is not the default. * Warning Options:: How picky should the compiler be? * Debugging Options:: Symbol tables, measurements, and debugging dumps. * Optimize Options:: How much optimization? +* Instrumentation Options:: Enabling profiling and extra run-time error checking. * Preprocessor Options:: Controlling header files and macro definitions. Also, getting dependency information for Make. * Assembler Options:: Passing options to the assembler. @@ -203,8 +204,6 @@ in the following sections. -fno-threadsafe-statics -fuse-cxa-atexit @gol -fno-weak -nostdinc++ @gol -fvisibility-inlines-hidden @gol --fvtable-verify=@r{[}std@r{|}preinit@r{|}none@r{]} @gol --fvtv-counts -fvtv-debug @gol -fvisibility-ms-compat @gol -fext-numeric-literals @gol -Wabi=@var{n} -Wabi-tag -Wconversion-null -Wctor-dtor-privacy @gol @@ -316,19 +315,7 @@ Objective-C and Objective-C++ Dialects}. @item Debugging Options @xref{Debugging Options,,Options for Debugging Your Program or GCC}. @gccoptlist{-d@var{letters} -dumpspecs -dumpmachine -dumpversion @gol --fsanitize=@var{style} -fsanitize-recover -fsanitize-recover=@var{style} @gol --fasan-shadow-offset=@var{number} -fsanitize-sections=@var{s1},@var{s2},... @gol --fsanitize-undefined-trap-on-error @gol --fcheck-pointer-bounds -fchecking -fchkp-check-incomplete-type @gol --fchkp-first-field-has-own-bounds -fchkp-narrow-bounds @gol --fchkp-narrow-to-innermost-array -fchkp-optimize @gol --fchkp-use-fast-string-functions -fchkp-use-nochk-string-functions @gol --fchkp-use-static-bounds -fchkp-use-static-const-bounds @gol --fchkp-treat-zero-dynamic-size-as-infinite -fchkp-check-read @gol --fchkp-check-read -fchkp-check-write -fchkp-store-bounds @gol --fchkp-instrument-calls -fchkp-instrument-marked-only @gol --fchkp-use-wrappers @gol --fdbg-cnt-list -fdbg-cnt=@var{counter-value-list} @gol +-fchecking -fdbg-cnt-list -fdbg-cnt=@var{counter-value-list} @gol -fdisable-ipa-@var{pass_name} @gol -fdisable-rtl-@var{pass_name} @gol -fdisable-rtl-@var{pass-name}=@var{range-list} @gol @@ -370,12 +357,13 @@ Objective-C and Objective-C++ Dialects}. -fenable-@var{kind}-@var{pass} @gol -fenable-@var{kind}-@var{pass}=@var{range-list} @gol -fdebug-types-section -fmem-report-wpa @gol --fmem-report -fpre-ipa-mem-report -fpost-ipa-mem-report -fprofile-arcs @gol +-fmem-report -fpre-ipa-mem-report -fpost-ipa-mem-report @gol -fopt-info @gol -fopt-info-@var{options}@r{[}=@var{file}@r{]} @gol +-fprofile-report @gol -frandom-seed=@var{string} -fsched-verbose=@var{n} @gol -fsel-sched-verbose -fsel-sched-dump-cfg -fsel-sched-pipelining-verbose @gol --fstack-usage -ftest-coverage -ftime-report -fvar-tracking @gol +-fstack-usage -ftime-report -fvar-tracking @gol -fvar-tracking-assignments -fvar-tracking-assignments-toggle @gol -g -g@var{level} -gtoggle -gcoff -gdwarf-@var{version} @gol -ggdb -grecord-gcc-switches -gno-record-gcc-switches @gol @@ -385,7 +373,7 @@ Objective-C and Objective-C++ Dialects}. -fdebug-prefix-map=@var{old}=@var{new} @gol -femit-struct-debug-baseonly -femit-struct-debug-reduced @gol -femit-struct-debug-detailed@r{[}=@var{spec-list}@r{]} @gol --p -pg -print-file-name=@var{library} -print-libgcc-file-name @gol +-print-file-name=@var{library} -print-libgcc-file-name @gol -print-multi-directory -print-multi-lib -print-multi-os-directory @gol -print-prog-name=@var{program} -print-search-dirs -Q @gol -print-sysroot -print-sysroot-headers-suffix @gol @@ -435,9 +423,8 @@ Objective-C and Objective-C++ Dialects}. -fno-toplevel-reorder -fno-trapping-math -fno-zero-initialized-in-bss @gol -fomit-frame-pointer -foptimize-sibling-calls @gol -fpartial-inlining -fpeel-loops -fpredictive-commoning @gol --fprefetch-loop-arrays -fprofile-report @gol --fprofile-correction -fprofile-dir=@var{path} -fprofile-generate @gol --fprofile-generate=@var{path} @gol +-fprefetch-loop-arrays @gol +-fprofile-correction @gol -fprofile-use -fprofile-use=@var{path} -fprofile-values @gol -fprofile-reorder-functions @gol -freciprocal-math -free -frename-registers -freorder-blocks @gol @@ -458,8 +445,7 @@ Objective-C and Objective-C++ Dialects}. -fsingle-precision-constant -fsplit-ivs-in-unroller @gol -fsplit-paths @gol -fsplit-wide-types -fssa-backprop -fssa-phiopt @gol --fstack-protector -fstack-protector-all -fstack-protector-strong @gol --fstack-protector-explicit -fstdarg-opt -fstrict-aliasing @gol +-fstdarg-opt -fstrict-aliasing @gol -fstrict-overflow -fthread-jumps -ftracer -ftree-bit-ccp @gol -ftree-builtin-call-dce -ftree-ccp -ftree-ch @gol -ftree-coalesce-vars -ftree-copy-prop -ftree-dce -ftree-dominator-opts @gol @@ -479,6 +465,32 @@ Objective-C and Objective-C++ Dialects}. --param @var{name}=@var{value} -O -O0 -O1 -O2 -O3 -Os -Ofast -Og} +@item Program Instrumentation Options +@xref{Instrumentation Options,,Program Instrumentation Options}. +@gccoptlist{-p -pg -fprofile-arcs --coverage -ftest-coverage @gol +-fprofile-dir=@var{path} -fprofile-generate -fprofile-generate=@var{path} @gol +-fsanitize=@var{style} -fsanitize-recover -fsanitize-recover=@var{style} @gol +-fasan-shadow-offset=@var{number} -fsanitize-sections=@var{s1},@var{s2},... @gol +-fsanitize-undefined-trap-on-error -fbounds-check @gol +-fcheck-pointer-bounds -fchkp-check-incomplete-type @gol +-fchkp-first-field-has-own-bounds -fchkp-narrow-bounds @gol +-fchkp-narrow-to-innermost-array -fchkp-optimize @gol +-fchkp-use-fast-string-functions -fchkp-use-nochk-string-functions @gol +-fchkp-use-static-bounds -fchkp-use-static-const-bounds @gol +-fchkp-treat-zero-dynamic-size-as-infinite -fchkp-check-read @gol +-fchkp-check-read -fchkp-check-write -fchkp-store-bounds @gol +-fchkp-instrument-calls -fchkp-instrument-marked-only @gol +-fchkp-use-wrappers @gol +-fstack-protector -fstack-protector-all -fstack-protector-strong @gol +-fstack-protector-explicit -fstack-check @gol +-fstack-limit-register=@var{reg} -fstack-limit-symbol=@var{sym} @gol +-fno-stack-limit -fsplit-stack @gol +-fvtable-verify=@r{[}std@r{|}preinit@r{|}none@r{]} @gol +-fvtv-counts -fvtv-debug @gol +-finstrument-functions @gol +-finstrument-functions-exclude-function-list=@var{sym},@var{sym},@dots{} @gol +-finstrument-functions-exclude-file-list=@var{file},@var{file},@dots{}} + @item Preprocessor Options @xref{Preprocessor Options,,Options Controlling the Preprocessor}. @gccoptlist{-A@var{question}=@var{answer} @gol @@ -523,21 +535,16 @@ Objective-C and Objective-C++ Dialects}. -fnon-call-exceptions -fdelete-dead-exceptions -funwind-tables @gol -fasynchronous-unwind-tables @gol -fno-gnu-unique @gol --finhibit-size-directive -finstrument-functions @gol --finstrument-functions-exclude-function-list=@var{sym},@var{sym},@dots{} @gol --finstrument-functions-exclude-file-list=@var{file},@var{file},@dots{} @gol --fno-common -fno-ident @gol +-finhibit-size-directive -fno-common -fno-ident @gol -fpcc-struct-return -fpic -fPIC -fpie -fPIE -fno-plt @gol -fno-jump-tables @gol -frecord-gcc-switches @gol -freg-struct-return -fshort-enums @gol -fshort-double -fshort-wchar @gol --fverbose-asm -fpack-struct[=@var{n}] -fstack-check @gol --fstack-limit-register=@var{reg} -fstack-limit-symbol=@var{sym} @gol --fno-stack-limit -fsplit-stack @gol +-fverbose-asm -fpack-struct[=@var{n}] @gol -fleading-underscore -ftls-model=@var{model} @gol -fstack-reuse=@var{reuse_level} @gol --ftrapv -fwrapv -fbounds-check @gol +-ftrapv -fwrapv @gol -fvisibility=@r{[}default@r{|}internal@r{|}hidden@r{|}protected@r{]} @gol -fstrict-volatile-bitfields -fsync-libcalls} @@ -2537,61 +2544,6 @@ and that pointers to function members defined in different shared objects may not compare equal. When this flag is given, it is a violation of the ODR to define types with the same name differently. -@item -fvtable-verify=@r{[}std@r{|}preinit@r{|}none@r{]} -@opindex fvtable-verify -Turn on (or off, if using @option{-fvtable-verify=none}) the security -feature that verifies at run time, for every virtual call, that -the vtable pointer through which the call is made is valid for the type of -the object, and has not been corrupted or overwritten. If an invalid vtable -pointer is detected at run time, an error is reported and execution of the -program is immediately halted. - -This option causes run-time data structures to be built at program startup, -which are used for verifying the vtable pointers. -The options @samp{std} and @samp{preinit} -control the timing of when these data structures are built. In both cases the -data structures are built before execution reaches @code{main}. Using -@option{-fvtable-verify=std} causes the data structures to be built after -shared libraries have been loaded and initialized. -@option{-fvtable-verify=preinit} causes them to be built before shared -libraries have been loaded and initialized. - -If this option appears multiple times in the command line with different -values specified, @samp{none} takes highest priority over both @samp{std} and -@samp{preinit}; @samp{preinit} takes priority over @samp{std}. - -@item -fvtv-debug -@opindex fvtv-debug -When used in conjunction with @option{-fvtable-verify=std} or -@option{-fvtable-verify=preinit}, causes debug versions of the -runtime functions for the vtable verification feature to be called. -This flag also causes the compiler to log information about which -vtable pointers it finds for each class. -This information is written to a file named @file{vtv_set_ptr_data.log} -in the directory named by the environment variable @env{VTV_LOGS_DIR} -if that is defined or the current working directory otherwise. - -Note: This feature @emph{appends} data to the log file. If you want a fresh log -file, be sure to delete any existing one. - -@item -fvtv-counts -@opindex fvtv-counts -This is a debugging flag. When used in conjunction with -@option{-fvtable-verify=std} or @option{-fvtable-verify=preinit}, this -causes the compiler to keep track of the total number of virtual calls -it encounters and the number of verifications it inserts. It also -counts the number of calls to certain run-time library functions -that it inserts and logs this information for each compilation unit. -The compiler writes this information to a file named -@file{vtv_count_data.log} in the directory named by the environment -variable @env{VTV_LOGS_DIR} if that is defined or the current working -directory otherwise. It also counts the size of the vtable pointer sets -for each class, and writes this information to @file{vtv_class_set_sizes.log} -in the same directory. - -Note: This feature @emph{appends} data to the log files. To get fresh log -files, be sure to delete any existing ones. - @item -fno-weak @opindex fno-weak Do not use weak symbol support, even if it is provided by the linker. @@ -5954,5335 +5906,5586 @@ other options are processed, and it does so only once, no matter how many times it is given. This is mainly intended to be used with @option{-fcompare-debug}. -@item -fsanitize=address -@opindex fsanitize=address -Enable AddressSanitizer, a fast memory error detector. -Memory access instructions are instrumented to detect -out-of-bounds and use-after-free bugs. -See @uref{https://github.com/google/sanitizers/wiki/AddressSanitizer} for -more details. The run-time behavior can be influenced using the -@env{ASAN_OPTIONS} environment variable. When set to @code{help=1}, -the available options are shown at startup of the instrumended program. See -@url{https://github.com/google/sanitizers/wiki/AddressSanitizerFlags#run-time-flags} -for a list of supported options. +@item -fchecking +@opindex fchecking +@opindex fno-checking +Enable internal consistency checking. The default depends on +the compiler configuration. -@item -fsanitize=kernel-address -@opindex fsanitize=kernel-address -Enable AddressSanitizer for Linux kernel. -See @uref{https://github.com/google/kasan/wiki} for more details. +@item -fdump-final-insns@r{[}=@var{file}@r{]} +@opindex fdump-final-insns +Dump the final internal representation (RTL) to @var{file}. If the +optional argument is omitted (or if @var{file} is @code{.}), the name +of the dump file is determined by appending @code{.gkd} to the +compilation output file name. -@item -fsanitize=thread -@opindex fsanitize=thread -Enable ThreadSanitizer, a fast data race detector. -Memory access instructions are instrumented to detect -data race bugs. See @uref{https://github.com/google/sanitizers/wiki#threadsanitizer} for more -details. The run-time behavior can be influenced using the @env{TSAN_OPTIONS} -environment variable; see -@url{https://github.com/google/sanitizers/wiki/ThreadSanitizerFlags} for a list of -supported options. +@item -fcompare-debug@r{[}=@var{opts}@r{]} +@opindex fcompare-debug +@opindex fno-compare-debug +If no error occurs during compilation, run the compiler a second time, +adding @var{opts} and @option{-fcompare-debug-second} to the arguments +passed to the second compilation. Dump the final internal +representation in both compilations, and print an error if they differ. -@item -fsanitize=leak -@opindex fsanitize=leak -Enable LeakSanitizer, a memory leak detector. -This option only matters for linking of executables and if neither -@option{-fsanitize=address} nor @option{-fsanitize=thread} is used. In that -case the executable is linked against a library that overrides @code{malloc} -and other allocator functions. See -@uref{https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer} for more -details. The run-time behavior can be influenced using the -@env{LSAN_OPTIONS} environment variable. +If the equal sign is omitted, the default @option{-gtoggle} is used. -@item -fsanitize=undefined -@opindex fsanitize=undefined -Enable UndefinedBehaviorSanitizer, a fast undefined behavior detector. -Various computations are instrumented to detect undefined behavior -at runtime. Current suboptions are: +The environment variable @env{GCC_COMPARE_DEBUG}, if defined, non-empty +and nonzero, implicitly enables @option{-fcompare-debug}. If +@env{GCC_COMPARE_DEBUG} is defined to a string starting with a dash, +then it is used for @var{opts}, otherwise the default @option{-gtoggle} +is used. -@table @gcctabopt +@option{-fcompare-debug=}, with the equal sign but without @var{opts}, +is equivalent to @option{-fno-compare-debug}, which disables the dumping +of the final representation and the second compilation, preventing even +@env{GCC_COMPARE_DEBUG} from taking effect. -@item -fsanitize=shift -@opindex fsanitize=shift -This option enables checking that the result of a shift operation is -not undefined. Note that what exactly is considered undefined differs -slightly between C and C++, as well as between ISO C90 and C99, etc. +To verify full coverage during @option{-fcompare-debug} testing, set +@env{GCC_COMPARE_DEBUG} to say @option{-fcompare-debug-not-overridden}, +which GCC rejects as an invalid option in any actual compilation +(rather than preprocessing, assembly or linking). To get just a +warning, setting @env{GCC_COMPARE_DEBUG} to @samp{-w%n-fcompare-debug +not overridden} will do. -@item -fsanitize=integer-divide-by-zero -@opindex fsanitize=integer-divide-by-zero -Detect integer division by zero as well as @code{INT_MIN / -1} division. +@item -fcompare-debug-second +@opindex fcompare-debug-second +This option is implicitly passed to the compiler for the second +compilation requested by @option{-fcompare-debug}, along with options to +silence warnings, and omitting other options that would cause +side-effect compiler outputs to files or to the standard output. Dump +files and preserved temporary files are renamed so as to contain the +@code{.gk} additional extension during the second compilation, to avoid +overwriting those generated by the first. -@item -fsanitize=unreachable -@opindex fsanitize=unreachable -With this option, the compiler turns the @code{__builtin_unreachable} -call into a diagnostics message call instead. When reaching the -@code{__builtin_unreachable} call, the behavior is undefined. +When this option is passed to the compiler driver, it causes the +@emph{first} compilation to be skipped, which makes it useful for little +other than debugging the compiler proper. -@item -fsanitize=vla-bound -@opindex fsanitize=vla-bound -This option instructs the compiler to check that the size of a variable -length array is positive. +@item -feliminate-dwarf2-dups +@opindex feliminate-dwarf2-dups +Compress DWARF 2 debugging information by eliminating duplicated +information about each symbol. This option only makes sense when +generating DWARF 2 debugging information with @option{-gdwarf-2}. -@item -fsanitize=null -@opindex fsanitize=null -This option enables pointer checking. Particularly, the application -built with this option turned on will issue an error message when it -tries to dereference a NULL pointer, or if a reference (possibly an -rvalue reference) is bound to a NULL pointer, or if a method is invoked -on an object pointed by a NULL pointer. +@item -femit-struct-debug-baseonly +@opindex femit-struct-debug-baseonly +Emit debug information for struct-like types +only when the base name of the compilation source file +matches the base name of file in which the struct is defined. -@item -fsanitize=return -@opindex fsanitize=return -This option enables return statement checking. Programs -built with this option turned on will issue an error message -when the end of a non-void function is reached without actually -returning a value. This option works in C++ only. +This option substantially reduces the size of debugging information, +but at significant potential loss in type information to the debugger. +See @option{-femit-struct-debug-reduced} for a less aggressive option. +See @option{-femit-struct-debug-detailed} for more detailed control. -@item -fsanitize=signed-integer-overflow -@opindex fsanitize=signed-integer-overflow -This option enables signed integer overflow checking. We check that -the result of @code{+}, @code{*}, and both unary and binary @code{-} -does not overflow in the signed arithmetics. Note, integer promotion -rules must be taken into account. That is, the following is not an -overflow: -@smallexample -signed char a = SCHAR_MAX; -a++; -@end smallexample +This option works only with DWARF 2. -@item -fsanitize=bounds -@opindex fsanitize=bounds -This option enables instrumentation of array bounds. Various out of bounds -accesses are detected. Flexible array members, flexible array member-like -arrays, and initializers of variables with static storage are not instrumented. +@item -femit-struct-debug-reduced +@opindex femit-struct-debug-reduced +Emit debug information for struct-like types +only when the base name of the compilation source file +matches the base name of file in which the type is defined, +unless the struct is a template or defined in a system header. -@item -fsanitize=bounds-strict -@opindex fsanitize=bounds-strict -This option enables strict instrumentation of array bounds. Most out of bounds -accesses are detected, including flexible array members and flexible array -member-like arrays. Initializers of variables with static storage are not -instrumented. +This option significantly reduces the size of debugging information, +with some potential loss in type information to the debugger. +See @option{-femit-struct-debug-baseonly} for a more aggressive option. +See @option{-femit-struct-debug-detailed} for more detailed control. -@item -fsanitize=alignment -@opindex fsanitize=alignment +This option works only with DWARF 2. -This option enables checking of alignment of pointers when they are -dereferenced, or when a reference is bound to insufficiently aligned target, -or when a method or constructor is invoked on insufficiently aligned object. +@item -femit-struct-debug-detailed@r{[}=@var{spec-list}@r{]} +@opindex femit-struct-debug-detailed +Specify the struct-like types +for which the compiler generates debug information. +The intent is to reduce duplicate struct debug information +between different object files within the same program. -@item -fsanitize=object-size -@opindex fsanitize=object-size -This option enables instrumentation of memory references using the -@code{__builtin_object_size} function. Various out of bounds pointer -accesses are detected. +This option is a detailed version of +@option{-femit-struct-debug-reduced} and @option{-femit-struct-debug-baseonly}, +which serves for most needs. -@item -fsanitize=float-divide-by-zero -@opindex fsanitize=float-divide-by-zero -Detect floating-point division by zero. Unlike other similar options, -@option{-fsanitize=float-divide-by-zero} is not enabled by -@option{-fsanitize=undefined}, since floating-point division by zero can -be a legitimate way of obtaining infinities and NaNs. +A specification has the syntax@* +[@samp{dir:}|@samp{ind:}][@samp{ord:}|@samp{gen:}](@samp{any}|@samp{sys}|@samp{base}|@samp{none}) -@item -fsanitize=float-cast-overflow -@opindex fsanitize=float-cast-overflow -This option enables floating-point type to integer conversion checking. -We check that the result of the conversion does not overflow. -Unlike other similar options, @option{-fsanitize=float-cast-overflow} is -not enabled by @option{-fsanitize=undefined}. -This option does not work well with @code{FE_INVALID} exceptions enabled. +The optional first word limits the specification to +structs that are used directly (@samp{dir:}) or used indirectly (@samp{ind:}). +A struct type is used directly when it is the type of a variable, member. +Indirect uses arise through pointers to structs. +That is, when use of an incomplete struct is valid, the use is indirect. +An example is +@samp{struct one direct; struct two * indirect;}. -@item -fsanitize=nonnull-attribute -@opindex fsanitize=nonnull-attribute +The optional second word limits the specification to +ordinary structs (@samp{ord:}) or generic structs (@samp{gen:}). +Generic structs are a bit complicated to explain. +For C++, these are non-explicit specializations of template classes, +or non-template classes within the above. +Other programming languages have generics, +but @option{-femit-struct-debug-detailed} does not yet implement them. -This option enables instrumentation of calls, checking whether null values -are not passed to arguments marked as requiring a non-null value by the -@code{nonnull} function attribute. +The third word specifies the source files for those +structs for which the compiler should emit debug information. +The values @samp{none} and @samp{any} have the normal meaning. +The value @samp{base} means that +the base of name of the file in which the type declaration appears +must match the base of the name of the main compilation file. +In practice, this means that when compiling @file{foo.c}, debug information +is generated for types declared in that file and @file{foo.h}, +but not other header files. +The value @samp{sys} means those types satisfying @samp{base} +or declared in system or compiler headers. -@item -fsanitize=returns-nonnull-attribute -@opindex fsanitize=returns-nonnull-attribute +You may need to experiment to determine the best settings for your application. -This option enables instrumentation of return statements in functions -marked with @code{returns_nonnull} function attribute, to detect returning -of null values from such functions. +The default is @option{-femit-struct-debug-detailed=all}. -@item -fsanitize=bool -@opindex fsanitize=bool +This option works only with DWARF 2. -This option enables instrumentation of loads from bool. If a value other -than 0/1 is loaded, a run-time error is issued. +@item -fno-merge-debug-strings +@opindex fmerge-debug-strings +@opindex fno-merge-debug-strings +Direct the linker to not merge together strings in the debugging +information that are identical in different object files. Merging is +not supported by all assemblers or linkers. Merging decreases the size +of the debug information in the output file at the cost of increasing +link processing time. Merging is enabled by default. -@item -fsanitize=enum -@opindex fsanitize=enum +@item -fdebug-prefix-map=@var{old}=@var{new} +@opindex fdebug-prefix-map +When compiling files in directory @file{@var{old}}, record debugging +information describing them as in @file{@var{new}} instead. -This option enables instrumentation of loads from an enum type. If -a value outside the range of values for the enum type is loaded, -a run-time error is issued. +@item -fno-dwarf2-cfi-asm +@opindex fdwarf2-cfi-asm +@opindex fno-dwarf2-cfi-asm +Emit DWARF 2 unwind info as compiler generated @code{.eh_frame} section +instead of using GAS @code{.cfi_*} directives. -@item -fsanitize=vptr -@opindex fsanitize=vptr +@item -Q +@opindex Q +Makes the compiler print out each function name as it is compiled, and +print some statistics about each pass when it finishes. -This option enables instrumentation of C++ member function calls, member -accesses and some conversions between pointers to base and derived classes, -to verify the referenced object has the correct dynamic type. +@item -ftime-report +@opindex ftime-report +Makes the compiler print some statistics about the time consumed by each +pass when it finishes. -@end table +@item -fmem-report +@opindex fmem-report +Makes the compiler print some statistics about permanent memory +allocation when it finishes. -While @option{-ftrapv} causes traps for signed overflows to be emitted, -@option{-fsanitize=undefined} gives a diagnostic message. -This currently works only for the C family of languages. +@item -fmem-report-wpa +@opindex fmem-report-wpa +Makes the compiler print some statistics about permanent memory +allocation for the WPA phase only. -@item -fno-sanitize=all -@opindex fno-sanitize=all +@item -fpre-ipa-mem-report +@opindex fpre-ipa-mem-report +@item -fpost-ipa-mem-report +@opindex fpost-ipa-mem-report +Makes the compiler print some statistics about permanent memory +allocation before or after interprocedural optimization. -This option disables all previously enabled sanitizers. -@option{-fsanitize=all} is not allowed, as some sanitizers cannot be used -together. +@item -fprofile-report +@opindex fprofile-report +Makes the compiler print some statistics about consistency of the +(estimated) profile and effect of individual passes. -@item -fasan-shadow-offset=@var{number} -@opindex fasan-shadow-offset -This option forces GCC to use custom shadow offset in AddressSanitizer checks. -It is useful for experimenting with different shadow memory layouts in -Kernel AddressSanitizer. +@item -fstack-usage +@opindex fstack-usage +Makes the compiler output stack usage information for the program, on a +per-function basis. The filename for the dump is made by appending +@file{.su} to the @var{auxname}. @var{auxname} is generated from the name of +the output file, if explicitly specified and it is not an executable, +otherwise it is the basename of the source file. An entry is made up +of three fields: -@item -fsanitize-sections=@var{s1},@var{s2},... -@opindex fsanitize-sections -Sanitize global variables in selected user-defined sections. @var{si} may -contain wildcards. +@itemize +@item +The name of the function. +@item +A number of bytes. +@item +One or more qualifiers: @code{static}, @code{dynamic}, @code{bounded}. +@end itemize -@item -fsanitize-recover@r{[}=@var{opts}@r{]} -@opindex fsanitize-recover -@opindex fno-sanitize-recover -@option{-fsanitize-recover=} controls error recovery mode for sanitizers -mentioned in comma-separated list of @var{opts}. Enabling this option -for a sanitizer component causes it to attempt to continue -running the program as if no error happened. This means multiple -runtime errors can be reported in a single program run, and the exit -code of the program may indicate success even when errors -have been reported. The @option{-fno-sanitize-recover=} option -can be used to alter -this behavior: only the first detected error is reported -and program then exits with a non-zero exit code. +The qualifier @code{static} means that the function manipulates the stack +statically: a fixed number of bytes are allocated for the frame on function +entry and released on function exit; no stack adjustments are otherwise made +in the function. The second field is this fixed number of bytes. -Currently this feature only works for @option{-fsanitize=undefined} (and its suboptions -except for @option{-fsanitize=unreachable} and @option{-fsanitize=return}), -@option{-fsanitize=float-cast-overflow}, @option{-fsanitize=float-divide-by-zero}, -@option{-fsanitize=kernel-address} and @option{-fsanitize=address}. -For these sanitizers error recovery is turned on by default, except @option{-fsanitize=address}, -for which this feature is experimental. -@option{-fsanitize-recover=all} and @option{-fno-sanitize-recover=all} is also -accepted, the former enables recovery for all sanitizers that support it, -the latter disables recovery for all sanitizers that support it. +The qualifier @code{dynamic} means that the function manipulates the stack +dynamically: in addition to the static allocation described above, stack +adjustments are made in the body of the function, for example to push/pop +arguments around function calls. If the qualifier @code{bounded} is also +present, the amount of these adjustments is bounded at compile time and +the second field is an upper bound of the total amount of stack used by +the function. If it is not present, the amount of these adjustments is +not bounded at compile time and the second field only represents the +bounded part. -Syntax without explicit @var{opts} parameter is deprecated. It is equivalent to -@smallexample --fsanitize-recover=undefined,float-cast-overflow,float-divide-by-zero -@end smallexample -@noindent -Similarly @option{-fno-sanitize-recover} is equivalent to -@smallexample --fno-sanitize-recover=undefined,float-cast-overflow,float-divide-by-zero -@end smallexample +@item -fdbg-cnt-list +@opindex fdbg-cnt-list +Print the name and the counter upper bound for all debug counters. -@item -fsanitize-undefined-trap-on-error -@opindex fsanitize-undefined-trap-on-error -The @option{-fsanitize-undefined-trap-on-error} option instructs the compiler to -report undefined behavior using @code{__builtin_trap} rather than -a @code{libubsan} library routine. The advantage of this is that the -@code{libubsan} library is not needed and is not linked in, so this -is usable even in freestanding environments. -@item -fsanitize-coverage=trace-pc -@opindex fsanitize-coverage=trace-pc -Enable coverage-guided fuzzing code instrumentation. -Inserts call to __sanitizer_cov_trace_pc into every basic block. +@item -fdbg-cnt=@var{counter-value-list} +@opindex fdbg-cnt +Set the internal debug counter upper bound. @var{counter-value-list} +is a comma-separated list of @var{name}:@var{value} pairs +which sets the upper bound of each debug counter @var{name} to @var{value}. +All debug counters have the initial upper bound of @code{UINT_MAX}; +thus @code{dbg_cnt} returns true always unless the upper bound +is set by this option. +For example, with @option{-fdbg-cnt=dce:10,tail_call:0}, +@code{dbg_cnt(dce)} returns true only for first 10 invocations. -@item -fcheck-pointer-bounds -@opindex fcheck-pointer-bounds -@opindex fno-check-pointer-bounds -@cindex Pointer Bounds Checker options -Enable Pointer Bounds Checker instrumentation. Each memory reference -is instrumented with checks of the pointer used for memory access against -bounds associated with that pointer. +@item -fenable-@var{kind}-@var{pass} +@itemx -fdisable-@var{kind}-@var{pass}=@var{range-list} +@opindex fdisable- +@opindex fenable- -Currently there -is only an implementation for Intel MPX available, thus x86 target -and @option{-mmpx} are required to enable this feature. -MPX-based instrumentation requires -a runtime library to enable MPX in hardware and handle bounds -violation signals. By default when @option{-fcheck-pointer-bounds} -and @option{-mmpx} options are used to link a program, the GCC driver -links against the @file{libmpx} runtime library and @file{libmpxwrappers} -library. It also passes '-z bndplt' to a linker in case it supports this -option (which is checked on libmpx configuration). Note that old versions -of linker may ignore option. Gold linker doesn't support '-z bndplt' -option. With no '-z bndplt' support in linker all calls to dynamic libraries -lose passed bounds reducing overall protection level. It's highly -recommended to use linker with '-z bndplt' support. In case such linker -is not available it is adviced to always use @option{-static-libmpxwrappers} -for better protection level or use @option{-static} to completely avoid -external calls to dynamic libraries. MPX-based instrumentation -may be used for debugging and also may be included in production code -to increase program security. Depending on usage, you may -have different requirements for the runtime library. The current version -of the MPX runtime library is more oriented for use as a debugging -tool. MPX runtime library usage implies @option{-lpthread}. See -also @option{-static-libmpx}. The runtime library behavior can be -influenced using various @env{CHKP_RT_*} environment variables. See -@uref{https://gcc.gnu.org/wiki/Intel%20MPX%20support%20in%20the%20GCC%20compiler} -for more details. +This is a set of options that are used to explicitly disable/enable +optimization passes. These options are intended for use for debugging GCC. +Compiler users should use regular options for enabling/disabling +passes instead. -Generated instrumentation may be controlled by various -@option{-fchkp-*} options and by the @code{bnd_variable_size} -structure field attribute (@pxref{Type Attributes}) and -@code{bnd_legacy}, and @code{bnd_instrument} function attributes -(@pxref{Function Attributes}). GCC also provides a number of built-in -functions for controlling the Pointer Bounds Checker. @xref{Pointer -Bounds Checker builtins}, for more information. +@table @gcctabopt -@item -fchecking -@opindex fchecking -@opindex fno-checking -Enable internal consistency checking. The default depends on -the compiler configuration. +@item -fdisable-ipa-@var{pass} +Disable IPA pass @var{pass}. @var{pass} is the pass name. If the same pass is +statically invoked in the compiler multiple times, the pass name should be +appended with a sequential number starting from 1. -@item -fchkp-check-incomplete-type -@opindex fchkp-check-incomplete-type -@opindex fno-chkp-check-incomplete-type -Generate pointer bounds checks for variables with incomplete type. -Enabled by default. +@item -fdisable-rtl-@var{pass} +@itemx -fdisable-rtl-@var{pass}=@var{range-list} +Disable RTL pass @var{pass}. @var{pass} is the pass name. If the same pass is +statically invoked in the compiler multiple times, the pass name should be +appended with a sequential number starting from 1. @var{range-list} is a +comma-separated list of function ranges or assembler names. Each range is a number +pair separated by a colon. The range is inclusive in both ends. If the range +is trivial, the number pair can be simplified as a single number. If the +function's call graph node's @var{uid} falls within one of the specified ranges, +the @var{pass} is disabled for that function. The @var{uid} is shown in the +function header of a dump file, and the pass names can be dumped by using +option @option{-fdump-passes}. -@item -fchkp-narrow-bounds -@opindex fchkp-narrow-bounds -@opindex fno-chkp-narrow-bounds -Controls bounds used by Pointer Bounds Checker for pointers to object -fields. If narrowing is enabled then field bounds are used. Otherwise -object bounds are used. See also @option{-fchkp-narrow-to-innermost-array} -and @option{-fchkp-first-field-has-own-bounds}. Enabled by default. +@item -fdisable-tree-@var{pass} +@itemx -fdisable-tree-@var{pass}=@var{range-list} +Disable tree pass @var{pass}. See @option{-fdisable-rtl} for the description of +option arguments. -@item -fchkp-first-field-has-own-bounds -@opindex fchkp-first-field-has-own-bounds -@opindex fno-chkp-first-field-has-own-bounds -Forces Pointer Bounds Checker to use narrowed bounds for the address of the -first field in the structure. By default a pointer to the first field has -the same bounds as a pointer to the whole structure. +@item -fenable-ipa-@var{pass} +Enable IPA pass @var{pass}. @var{pass} is the pass name. If the same pass is +statically invoked in the compiler multiple times, the pass name should be +appended with a sequential number starting from 1. -@item -fchkp-narrow-to-innermost-array -@opindex fchkp-narrow-to-innermost-array -@opindex fno-chkp-narrow-to-innermost-array -Forces Pointer Bounds Checker to use bounds of the innermost arrays in -case of nested static array access. By default this option is disabled and -bounds of the outermost array are used. +@item -fenable-rtl-@var{pass} +@itemx -fenable-rtl-@var{pass}=@var{range-list} +Enable RTL pass @var{pass}. See @option{-fdisable-rtl} for option argument +description and examples. -@item -fchkp-optimize -@opindex fchkp-optimize -@opindex fno-chkp-optimize -Enables Pointer Bounds Checker optimizations. Enabled by default at -optimization levels @option{-O}, @option{-O2}, @option{-O3}. +@item -fenable-tree-@var{pass} +@itemx -fenable-tree-@var{pass}=@var{range-list} +Enable tree pass @var{pass}. See @option{-fdisable-rtl} for the description +of option arguments. -@item -fchkp-use-fast-string-functions -@opindex fchkp-use-fast-string-functions -@opindex fno-chkp-use-fast-string-functions -Enables use of @code{*_nobnd} versions of string functions (not copying bounds) -by Pointer Bounds Checker. Disabled by default. +@end table -@item -fchkp-use-nochk-string-functions -@opindex fchkp-use-nochk-string-functions -@opindex fno-chkp-use-nochk-string-functions -Enables use of @code{*_nochk} versions of string functions (not checking bounds) -by Pointer Bounds Checker. Disabled by default. +Here are some examples showing uses of these options. -@item -fchkp-use-static-bounds -@opindex fchkp-use-static-bounds -@opindex fno-chkp-use-static-bounds -Allow Pointer Bounds Checker to generate static bounds holding -bounds of static variables. Enabled by default. +@smallexample -@item -fchkp-use-static-const-bounds -@opindex fchkp-use-static-const-bounds -@opindex fno-chkp-use-static-const-bounds -Use statically-initialized bounds for constant bounds instead of -generating them each time they are required. By default enabled when -@option{-fchkp-use-static-bounds} is enabled. +# disable ccp1 for all functions + -fdisable-tree-ccp1 +# disable complete unroll for function whose cgraph node uid is 1 + -fenable-tree-cunroll=1 +# disable gcse2 for functions at the following ranges [1,1], +# [300,400], and [400,1000] +# disable gcse2 for functions foo and foo2 + -fdisable-rtl-gcse2=foo,foo2 +# disable early inlining + -fdisable-tree-einline +# disable ipa inlining + -fdisable-ipa-inline +# enable tree full unroll + -fenable-tree-unroll -@item -fchkp-treat-zero-dynamic-size-as-infinite -@opindex fchkp-treat-zero-dynamic-size-as-infinite -@opindex fno-chkp-treat-zero-dynamic-size-as-infinite -With this option, objects with incomplete type whose -dynamically-obtained size is zero are treated as having infinite size -instead by Pointer Bounds -Checker. This option may be helpful if a program is linked with a library -missing size information for some symbols. Disabled by default. +@end smallexample -@item -fchkp-check-read -@opindex fchkp-check-read -@opindex fno-chkp-check-read -Instructs Pointer Bounds Checker to generate checks for all read -accesses to memory. Enabled by default. +@item -d@var{letters} +@itemx -fdump-rtl-@var{pass} +@itemx -fdump-rtl-@var{pass}=@var{filename} +@opindex d +@opindex fdump-rtl-@var{pass} +Says to make debugging dumps during compilation at times specified by +@var{letters}. This is used for debugging the RTL-based passes of the +compiler. The file names for most of the dumps are made by appending +a pass number and a word to the @var{dumpname}, and the files are +created in the directory of the output file. In case of +@option{=@var{filename}} option, the dump is output on the given file +instead of the pass numbered dump files. Note that the pass number is +assigned as passes are registered into the pass manager. Most passes +are registered in the order that they will execute and for these passes +the number corresponds to the pass execution order. However, passes +registered by plugins, passes specific to compilation targets, or +passes that are otherwise registered after all the other passes are +numbered higher than a pass named "final", even if they are executed +earlier. @var{dumpname} is generated from the name of the output +file if explicitly specified and not an executable, otherwise it is +the basename of the source file. These switches may have different +effects when @option{-E} is used for preprocessing. -@item -fchkp-check-write -@opindex fchkp-check-write -@opindex fno-chkp-check-write -Instructs Pointer Bounds Checker to generate checks for all write -accesses to memory. Enabled by default. +Debug dumps can be enabled with a @option{-fdump-rtl} switch or some +@option{-d} option @var{letters}. Here are the possible +letters for use in @var{pass} and @var{letters}, and their meanings: -@item -fchkp-store-bounds -@opindex fchkp-store-bounds -@opindex fno-chkp-store-bounds -Instructs Pointer Bounds Checker to generate bounds stores for -pointer writes. Enabled by default. +@table @gcctabopt -@item -fchkp-instrument-calls -@opindex fchkp-instrument-calls -@opindex fno-chkp-instrument-calls -Instructs Pointer Bounds Checker to pass pointer bounds to calls. -Enabled by default. +@item -fdump-rtl-alignments +@opindex fdump-rtl-alignments +Dump after branch alignments have been computed. -@item -fchkp-instrument-marked-only -@opindex fchkp-instrument-marked-only -@opindex fno-chkp-instrument-marked-only -Instructs Pointer Bounds Checker to instrument only functions -marked with the @code{bnd_instrument} attribute -(@pxref{Function Attributes}). Disabled by default. +@item -fdump-rtl-asmcons +@opindex fdump-rtl-asmcons +Dump after fixing rtl statements that have unsatisfied in/out constraints. -@item -fchkp-use-wrappers -@opindex fchkp-use-wrappers -@opindex fno-chkp-use-wrappers -Allows Pointer Bounds Checker to replace calls to built-in functions -with calls to wrapper functions. When @option{-fchkp-use-wrappers} -is used to link a program, the GCC driver automatically links -against @file{libmpxwrappers}. See also @option{-static-libmpxwrappers}. -Enabled by default. +@item -fdump-rtl-auto_inc_dec +@opindex fdump-rtl-auto_inc_dec +Dump after auto-inc-dec discovery. This pass is only run on +architectures that have auto inc or auto dec instructions. -@item -fdump-final-insns@r{[}=@var{file}@r{]} -@opindex fdump-final-insns -Dump the final internal representation (RTL) to @var{file}. If the -optional argument is omitted (or if @var{file} is @code{.}), the name -of the dump file is determined by appending @code{.gkd} to the -compilation output file name. +@item -fdump-rtl-barriers +@opindex fdump-rtl-barriers +Dump after cleaning up the barrier instructions. -@item -fcompare-debug@r{[}=@var{opts}@r{]} -@opindex fcompare-debug -@opindex fno-compare-debug -If no error occurs during compilation, run the compiler a second time, -adding @var{opts} and @option{-fcompare-debug-second} to the arguments -passed to the second compilation. Dump the final internal -representation in both compilations, and print an error if they differ. +@item -fdump-rtl-bbpart +@opindex fdump-rtl-bbpart +Dump after partitioning hot and cold basic blocks. -If the equal sign is omitted, the default @option{-gtoggle} is used. +@item -fdump-rtl-bbro +@opindex fdump-rtl-bbro +Dump after block reordering. -The environment variable @env{GCC_COMPARE_DEBUG}, if defined, non-empty -and nonzero, implicitly enables @option{-fcompare-debug}. If -@env{GCC_COMPARE_DEBUG} is defined to a string starting with a dash, -then it is used for @var{opts}, otherwise the default @option{-gtoggle} -is used. +@item -fdump-rtl-btl1 +@itemx -fdump-rtl-btl2 +@opindex fdump-rtl-btl2 +@opindex fdump-rtl-btl2 +@option{-fdump-rtl-btl1} and @option{-fdump-rtl-btl2} enable dumping +after the two branch +target load optimization passes. -@option{-fcompare-debug=}, with the equal sign but without @var{opts}, -is equivalent to @option{-fno-compare-debug}, which disables the dumping -of the final representation and the second compilation, preventing even -@env{GCC_COMPARE_DEBUG} from taking effect. +@item -fdump-rtl-bypass +@opindex fdump-rtl-bypass +Dump after jump bypassing and control flow optimizations. -To verify full coverage during @option{-fcompare-debug} testing, set -@env{GCC_COMPARE_DEBUG} to say @option{-fcompare-debug-not-overridden}, -which GCC rejects as an invalid option in any actual compilation -(rather than preprocessing, assembly or linking). To get just a -warning, setting @env{GCC_COMPARE_DEBUG} to @samp{-w%n-fcompare-debug -not overridden} will do. +@item -fdump-rtl-combine +@opindex fdump-rtl-combine +Dump after the RTL instruction combination pass. -@item -fcompare-debug-second -@opindex fcompare-debug-second -This option is implicitly passed to the compiler for the second -compilation requested by @option{-fcompare-debug}, along with options to -silence warnings, and omitting other options that would cause -side-effect compiler outputs to files or to the standard output. Dump -files and preserved temporary files are renamed so as to contain the -@code{.gk} additional extension during the second compilation, to avoid -overwriting those generated by the first. +@item -fdump-rtl-compgotos +@opindex fdump-rtl-compgotos +Dump after duplicating the computed gotos. -When this option is passed to the compiler driver, it causes the -@emph{first} compilation to be skipped, which makes it useful for little -other than debugging the compiler proper. +@item -fdump-rtl-ce1 +@itemx -fdump-rtl-ce2 +@itemx -fdump-rtl-ce3 +@opindex fdump-rtl-ce1 +@opindex fdump-rtl-ce2 +@opindex fdump-rtl-ce3 +@option{-fdump-rtl-ce1}, @option{-fdump-rtl-ce2}, and +@option{-fdump-rtl-ce3} enable dumping after the three +if conversion passes. -@item -feliminate-dwarf2-dups -@opindex feliminate-dwarf2-dups -Compress DWARF 2 debugging information by eliminating duplicated -information about each symbol. This option only makes sense when -generating DWARF 2 debugging information with @option{-gdwarf-2}. +@item -fdump-rtl-cprop_hardreg +@opindex fdump-rtl-cprop_hardreg +Dump after hard register copy propagation. -@item -femit-struct-debug-baseonly -@opindex femit-struct-debug-baseonly -Emit debug information for struct-like types -only when the base name of the compilation source file -matches the base name of file in which the struct is defined. +@item -fdump-rtl-csa +@opindex fdump-rtl-csa +Dump after combining stack adjustments. -This option substantially reduces the size of debugging information, -but at significant potential loss in type information to the debugger. -See @option{-femit-struct-debug-reduced} for a less aggressive option. -See @option{-femit-struct-debug-detailed} for more detailed control. +@item -fdump-rtl-cse1 +@itemx -fdump-rtl-cse2 +@opindex fdump-rtl-cse1 +@opindex fdump-rtl-cse2 +@option{-fdump-rtl-cse1} and @option{-fdump-rtl-cse2} enable dumping after +the two common subexpression elimination passes. -This option works only with DWARF 2. +@item -fdump-rtl-dce +@opindex fdump-rtl-dce +Dump after the standalone dead code elimination passes. -@item -femit-struct-debug-reduced -@opindex femit-struct-debug-reduced -Emit debug information for struct-like types -only when the base name of the compilation source file -matches the base name of file in which the type is defined, -unless the struct is a template or defined in a system header. +@item -fdump-rtl-dbr +@opindex fdump-rtl-dbr +Dump after delayed branch scheduling. -This option significantly reduces the size of debugging information, -with some potential loss in type information to the debugger. -See @option{-femit-struct-debug-baseonly} for a more aggressive option. -See @option{-femit-struct-debug-detailed} for more detailed control. +@item -fdump-rtl-dce1 +@itemx -fdump-rtl-dce2 +@opindex fdump-rtl-dce1 +@opindex fdump-rtl-dce2 +@option{-fdump-rtl-dce1} and @option{-fdump-rtl-dce2} enable dumping after +the two dead store elimination passes. -This option works only with DWARF 2. +@item -fdump-rtl-eh +@opindex fdump-rtl-eh +Dump after finalization of EH handling code. -@item -femit-struct-debug-detailed@r{[}=@var{spec-list}@r{]} -@opindex femit-struct-debug-detailed -Specify the struct-like types -for which the compiler generates debug information. -The intent is to reduce duplicate struct debug information -between different object files within the same program. +@item -fdump-rtl-eh_ranges +@opindex fdump-rtl-eh_ranges +Dump after conversion of EH handling range regions. -This option is a detailed version of -@option{-femit-struct-debug-reduced} and @option{-femit-struct-debug-baseonly}, -which serves for most needs. +@item -fdump-rtl-expand +@opindex fdump-rtl-expand +Dump after RTL generation. -A specification has the syntax@* -[@samp{dir:}|@samp{ind:}][@samp{ord:}|@samp{gen:}](@samp{any}|@samp{sys}|@samp{base}|@samp{none}) +@item -fdump-rtl-fwprop1 +@itemx -fdump-rtl-fwprop2 +@opindex fdump-rtl-fwprop1 +@opindex fdump-rtl-fwprop2 +@option{-fdump-rtl-fwprop1} and @option{-fdump-rtl-fwprop2} enable +dumping after the two forward propagation passes. -The optional first word limits the specification to -structs that are used directly (@samp{dir:}) or used indirectly (@samp{ind:}). -A struct type is used directly when it is the type of a variable, member. -Indirect uses arise through pointers to structs. -That is, when use of an incomplete struct is valid, the use is indirect. -An example is -@samp{struct one direct; struct two * indirect;}. +@item -fdump-rtl-gcse1 +@itemx -fdump-rtl-gcse2 +@opindex fdump-rtl-gcse1 +@opindex fdump-rtl-gcse2 +@option{-fdump-rtl-gcse1} and @option{-fdump-rtl-gcse2} enable dumping +after global common subexpression elimination. -The optional second word limits the specification to -ordinary structs (@samp{ord:}) or generic structs (@samp{gen:}). -Generic structs are a bit complicated to explain. -For C++, these are non-explicit specializations of template classes, -or non-template classes within the above. -Other programming languages have generics, -but @option{-femit-struct-debug-detailed} does not yet implement them. +@item -fdump-rtl-init-regs +@opindex fdump-rtl-init-regs +Dump after the initialization of the registers. -The third word specifies the source files for those -structs for which the compiler should emit debug information. -The values @samp{none} and @samp{any} have the normal meaning. -The value @samp{base} means that -the base of name of the file in which the type declaration appears -must match the base of the name of the main compilation file. -In practice, this means that when compiling @file{foo.c}, debug information -is generated for types declared in that file and @file{foo.h}, -but not other header files. -The value @samp{sys} means those types satisfying @samp{base} -or declared in system or compiler headers. +@item -fdump-rtl-initvals +@opindex fdump-rtl-initvals +Dump after the computation of the initial value sets. -You may need to experiment to determine the best settings for your application. +@item -fdump-rtl-into_cfglayout +@opindex fdump-rtl-into_cfglayout +Dump after converting to cfglayout mode. -The default is @option{-femit-struct-debug-detailed=all}. +@item -fdump-rtl-ira +@opindex fdump-rtl-ira +Dump after iterated register allocation. -This option works only with DWARF 2. +@item -fdump-rtl-jump +@opindex fdump-rtl-jump +Dump after the second jump optimization. -@item -fno-merge-debug-strings -@opindex fmerge-debug-strings -@opindex fno-merge-debug-strings -Direct the linker to not merge together strings in the debugging -information that are identical in different object files. Merging is -not supported by all assemblers or linkers. Merging decreases the size -of the debug information in the output file at the cost of increasing -link processing time. Merging is enabled by default. +@item -fdump-rtl-loop2 +@opindex fdump-rtl-loop2 +@option{-fdump-rtl-loop2} enables dumping after the rtl +loop optimization passes. -@item -fdebug-prefix-map=@var{old}=@var{new} -@opindex fdebug-prefix-map -When compiling files in directory @file{@var{old}}, record debugging -information describing them as in @file{@var{new}} instead. +@item -fdump-rtl-mach +@opindex fdump-rtl-mach +Dump after performing the machine dependent reorganization pass, if that +pass exists. -@item -fno-dwarf2-cfi-asm -@opindex fdwarf2-cfi-asm -@opindex fno-dwarf2-cfi-asm -Emit DWARF 2 unwind info as compiler generated @code{.eh_frame} section -instead of using GAS @code{.cfi_*} directives. +@item -fdump-rtl-mode_sw +@opindex fdump-rtl-mode_sw +Dump after removing redundant mode switches. -@cindex @command{prof} -@item -p -@opindex p -Generate extra code to write profile information suitable for the -analysis program @command{prof}. You must use this option when compiling -the source files you want data about, and you must also use it when -linking. +@item -fdump-rtl-rnreg +@opindex fdump-rtl-rnreg +Dump after register renumbering. -@cindex @command{gprof} -@item -pg -@opindex pg -Generate extra code to write profile information suitable for the -analysis program @command{gprof}. You must use this option when compiling -the source files you want data about, and you must also use it when -linking. +@item -fdump-rtl-outof_cfglayout +@opindex fdump-rtl-outof_cfglayout +Dump after converting from cfglayout mode. -@item -Q -@opindex Q -Makes the compiler print out each function name as it is compiled, and -print some statistics about each pass when it finishes. +@item -fdump-rtl-peephole2 +@opindex fdump-rtl-peephole2 +Dump after the peephole pass. -@item -ftime-report -@opindex ftime-report -Makes the compiler print some statistics about the time consumed by each -pass when it finishes. +@item -fdump-rtl-postreload +@opindex fdump-rtl-postreload +Dump after post-reload optimizations. -@item -fmem-report -@opindex fmem-report -Makes the compiler print some statistics about permanent memory -allocation when it finishes. +@item -fdump-rtl-pro_and_epilogue +@opindex fdump-rtl-pro_and_epilogue +Dump after generating the function prologues and epilogues. -@item -fmem-report-wpa -@opindex fmem-report-wpa -Makes the compiler print some statistics about permanent memory -allocation for the WPA phase only. +@item -fdump-rtl-sched1 +@itemx -fdump-rtl-sched2 +@opindex fdump-rtl-sched1 +@opindex fdump-rtl-sched2 +@option{-fdump-rtl-sched1} and @option{-fdump-rtl-sched2} enable dumping +after the basic block scheduling passes. -@item -fpre-ipa-mem-report -@opindex fpre-ipa-mem-report -@item -fpost-ipa-mem-report -@opindex fpost-ipa-mem-report -Makes the compiler print some statistics about permanent memory -allocation before or after interprocedural optimization. +@item -fdump-rtl-ree +@opindex fdump-rtl-ree +Dump after sign/zero extension elimination. -@item -fprofile-report -@opindex fprofile-report -Makes the compiler print some statistics about consistency of the -(estimated) profile and effect of individual passes. +@item -fdump-rtl-seqabstr +@opindex fdump-rtl-seqabstr +Dump after common sequence discovery. -@item -fstack-usage -@opindex fstack-usage -Makes the compiler output stack usage information for the program, on a -per-function basis. The filename for the dump is made by appending -@file{.su} to the @var{auxname}. @var{auxname} is generated from the name of -the output file, if explicitly specified and it is not an executable, -otherwise it is the basename of the source file. An entry is made up -of three fields: +@item -fdump-rtl-shorten +@opindex fdump-rtl-shorten +Dump after shortening branches. -@itemize -@item -The name of the function. -@item -A number of bytes. -@item -One or more qualifiers: @code{static}, @code{dynamic}, @code{bounded}. -@end itemize - -The qualifier @code{static} means that the function manipulates the stack -statically: a fixed number of bytes are allocated for the frame on function -entry and released on function exit; no stack adjustments are otherwise made -in the function. The second field is this fixed number of bytes. +@item -fdump-rtl-sibling +@opindex fdump-rtl-sibling +Dump after sibling call optimizations. -The qualifier @code{dynamic} means that the function manipulates the stack -dynamically: in addition to the static allocation described above, stack -adjustments are made in the body of the function, for example to push/pop -arguments around function calls. If the qualifier @code{bounded} is also -present, the amount of these adjustments is bounded at compile time and -the second field is an upper bound of the total amount of stack used by -the function. If it is not present, the amount of these adjustments is -not bounded at compile time and the second field only represents the -bounded part. +@item -fdump-rtl-split1 +@itemx -fdump-rtl-split2 +@itemx -fdump-rtl-split3 +@itemx -fdump-rtl-split4 +@itemx -fdump-rtl-split5 +@opindex fdump-rtl-split1 +@opindex fdump-rtl-split2 +@opindex fdump-rtl-split3 +@opindex fdump-rtl-split4 +@opindex fdump-rtl-split5 +These options enable dumping after five rounds of +instruction splitting. -@item -fprofile-arcs -@opindex fprofile-arcs -Add code so that program flow @dfn{arcs} are instrumented. During -execution the program records how many times each branch and call is -executed and how many times it is taken or returns. When the compiled -program exits it saves this data to a file called -@file{@var{auxname}.gcda} for each source file. The data may be used for -profile-directed optimizations (@option{-fbranch-probabilities}), or for -test coverage analysis (@option{-ftest-coverage}). Each object file's -@var{auxname} is generated from the name of the output file, if -explicitly specified and it is not the final executable, otherwise it is -the basename of the source file. In both cases any suffix is removed -(e.g.@: @file{foo.gcda} for input file @file{dir/foo.c}, or -@file{dir/foo.gcda} for output file specified as @option{-o dir/foo.o}). -@xref{Cross-profiling}. +@item -fdump-rtl-sms +@opindex fdump-rtl-sms +Dump after modulo scheduling. This pass is only run on some +architectures. -@cindex @command{gcov} -@item --coverage -@opindex coverage +@item -fdump-rtl-stack +@opindex fdump-rtl-stack +Dump after conversion from GCC's ``flat register file'' registers to the +x87's stack-like registers. This pass is only run on x86 variants. -This option is used to compile and link code instrumented for coverage -analysis. The option is a synonym for @option{-fprofile-arcs} -@option{-ftest-coverage} (when compiling) and @option{-lgcov} (when -linking). See the documentation for those options for more details. +@item -fdump-rtl-subreg1 +@itemx -fdump-rtl-subreg2 +@opindex fdump-rtl-subreg1 +@opindex fdump-rtl-subreg2 +@option{-fdump-rtl-subreg1} and @option{-fdump-rtl-subreg2} enable dumping after +the two subreg expansion passes. -@itemize +@item -fdump-rtl-unshare +@opindex fdump-rtl-unshare +Dump after all rtl has been unshared. -@item -Compile the source files with @option{-fprofile-arcs} plus optimization -and code generation options. For test coverage analysis, use the -additional @option{-ftest-coverage} option. You do not need to profile -every source file in a program. +@item -fdump-rtl-vartrack +@opindex fdump-rtl-vartrack +Dump after variable tracking. -@item -Link your object files with @option{-lgcov} or @option{-fprofile-arcs} -(the latter implies the former). +@item -fdump-rtl-vregs +@opindex fdump-rtl-vregs +Dump after converting virtual registers to hard registers. -@item -Run the program on a representative workload to generate the arc profile -information. This may be repeated any number of times. You can run -concurrent instances of your program, and provided that the file system -supports locking, the data files will be correctly updated. Also -@code{fork} calls are detected and correctly handled (double counting -will not happen). +@item -fdump-rtl-web +@opindex fdump-rtl-web +Dump after live range splitting. -@item -For profile-directed optimizations, compile the source files again with -the same optimization and code generation options plus -@option{-fbranch-probabilities} (@pxref{Optimize Options,,Options that -Control Optimization}). +@item -fdump-rtl-regclass +@itemx -fdump-rtl-subregs_of_mode_init +@itemx -fdump-rtl-subregs_of_mode_finish +@itemx -fdump-rtl-dfinit +@itemx -fdump-rtl-dfinish +@opindex fdump-rtl-regclass +@opindex fdump-rtl-subregs_of_mode_init +@opindex fdump-rtl-subregs_of_mode_finish +@opindex fdump-rtl-dfinit +@opindex fdump-rtl-dfinish +These dumps are defined but always produce empty files. -@item -For test coverage analysis, use @command{gcov} to produce human readable -information from the @file{.gcno} and @file{.gcda} files. Refer to the -@command{gcov} documentation for further information. +@item -da +@itemx -fdump-rtl-all +@opindex da +@opindex fdump-rtl-all +Produce all the dumps listed above. -@end itemize +@item -dA +@opindex dA +Annotate the assembler output with miscellaneous debugging information. -With @option{-fprofile-arcs}, for each function of your program GCC -creates a program flow graph, then finds a spanning tree for the graph. -Only arcs that are not on the spanning tree have to be instrumented: the -compiler adds code to count the number of times that these arcs are -executed. When an arc is the only exit or only entrance to a block, the -instrumentation code can be added to the block; otherwise, a new basic -block must be created to hold the instrumentation code. +@item -dD +@opindex dD +Dump all macro definitions, at the end of preprocessing, in addition to +normal output. -@need 2000 -@item -ftest-coverage -@opindex ftest-coverage -Produce a notes file that the @command{gcov} code-coverage utility -(@pxref{Gcov,, @command{gcov}---a Test Coverage Program}) can use to -show program coverage. Each source file's note file is called -@file{@var{auxname}.gcno}. Refer to the @option{-fprofile-arcs} option -above for a description of @var{auxname} and instructions on how to -generate test coverage data. Coverage data matches the source files -more closely if you do not optimize. +@item -dH +@opindex dH +Produce a core dump whenever an error occurs. -@item -fdbg-cnt-list -@opindex fdbg-cnt-list -Print the name and the counter upper bound for all debug counters. +@item -dp +@opindex dp +Annotate the assembler output with a comment indicating which +pattern and alternative is used. The length of each instruction is +also printed. +@item -dP +@opindex dP +Dump the RTL in the assembler output as a comment before each instruction. +Also turns on @option{-dp} annotation. -@item -fdbg-cnt=@var{counter-value-list} -@opindex fdbg-cnt -Set the internal debug counter upper bound. @var{counter-value-list} -is a comma-separated list of @var{name}:@var{value} pairs -which sets the upper bound of each debug counter @var{name} to @var{value}. -All debug counters have the initial upper bound of @code{UINT_MAX}; -thus @code{dbg_cnt} returns true always unless the upper bound -is set by this option. -For example, with @option{-fdbg-cnt=dce:10,tail_call:0}, -@code{dbg_cnt(dce)} returns true only for first 10 invocations. +@item -dx +@opindex dx +Just generate RTL for a function instead of compiling it. Usually used +with @option{-fdump-rtl-expand}. +@end table -@item -fenable-@var{kind}-@var{pass} -@itemx -fdisable-@var{kind}-@var{pass}=@var{range-list} -@opindex fdisable- -@opindex fenable- +@item -fdump-noaddr +@opindex fdump-noaddr +When doing debugging dumps, suppress address output. This makes it more +feasible to use diff on debugging dumps for compiler invocations with +different compiler binaries and/or different +text / bss / data / heap / stack / dso start locations. -This is a set of options that are used to explicitly disable/enable -optimization passes. These options are intended for use for debugging GCC. -Compiler users should use regular options for enabling/disabling -passes instead. +@item -freport-bug +@opindex freport-bug +Collect and dump debug information into temporary file if ICE in C/C++ +compiler occured. -@table @gcctabopt +@item -fdump-unnumbered +@opindex fdump-unnumbered +When doing debugging dumps, suppress instruction numbers and address output. +This makes it more feasible to use diff on debugging dumps for compiler +invocations with different options, in particular with and without +@option{-g}. -@item -fdisable-ipa-@var{pass} -Disable IPA pass @var{pass}. @var{pass} is the pass name. If the same pass is -statically invoked in the compiler multiple times, the pass name should be -appended with a sequential number starting from 1. +@item -fdump-unnumbered-links +@opindex fdump-unnumbered-links +When doing debugging dumps (see @option{-d} option above), suppress +instruction numbers for the links to the previous and next instructions +in a sequence. -@item -fdisable-rtl-@var{pass} -@itemx -fdisable-rtl-@var{pass}=@var{range-list} -Disable RTL pass @var{pass}. @var{pass} is the pass name. If the same pass is -statically invoked in the compiler multiple times, the pass name should be -appended with a sequential number starting from 1. @var{range-list} is a -comma-separated list of function ranges or assembler names. Each range is a number -pair separated by a colon. The range is inclusive in both ends. If the range -is trivial, the number pair can be simplified as a single number. If the -function's call graph node's @var{uid} falls within one of the specified ranges, -the @var{pass} is disabled for that function. The @var{uid} is shown in the -function header of a dump file, and the pass names can be dumped by using -option @option{-fdump-passes}. +@item -fdump-translation-unit @r{(C++ only)} +@itemx -fdump-translation-unit-@var{options} @r{(C++ only)} +@opindex fdump-translation-unit +Dump a representation of the tree structure for the entire translation +unit to a file. The file name is made by appending @file{.tu} to the +source file name, and the file is created in the same directory as the +output file. If the @samp{-@var{options}} form is used, @var{options} +controls the details of the dump as described for the +@option{-fdump-tree} options. -@item -fdisable-tree-@var{pass} -@itemx -fdisable-tree-@var{pass}=@var{range-list} -Disable tree pass @var{pass}. See @option{-fdisable-rtl} for the description of -option arguments. +@item -fdump-class-hierarchy @r{(C++ only)} +@itemx -fdump-class-hierarchy-@var{options} @r{(C++ only)} +@opindex fdump-class-hierarchy +Dump a representation of each class's hierarchy and virtual function +table layout to a file. The file name is made by appending +@file{.class} to the source file name, and the file is created in the +same directory as the output file. If the @samp{-@var{options}} form +is used, @var{options} controls the details of the dump as described +for the @option{-fdump-tree} options. -@item -fenable-ipa-@var{pass} -Enable IPA pass @var{pass}. @var{pass} is the pass name. If the same pass is -statically invoked in the compiler multiple times, the pass name should be -appended with a sequential number starting from 1. +@item -fdump-ipa-@var{switch} +@opindex fdump-ipa +Control the dumping at various stages of inter-procedural analysis +language tree to a file. The file name is generated by appending a +switch specific suffix to the source file name, and the file is created +in the same directory as the output file. The following dumps are +possible: -@item -fenable-rtl-@var{pass} -@itemx -fenable-rtl-@var{pass}=@var{range-list} -Enable RTL pass @var{pass}. See @option{-fdisable-rtl} for option argument -description and examples. - -@item -fenable-tree-@var{pass} -@itemx -fenable-tree-@var{pass}=@var{range-list} -Enable tree pass @var{pass}. See @option{-fdisable-rtl} for the description -of option arguments. +@table @samp +@item all +Enables all inter-procedural analysis dumps. -@end table +@item cgraph +Dumps information about call-graph optimization, unused function removal, +and inlining decisions. -Here are some examples showing uses of these options. +@item inline +Dump after function inlining. -@smallexample +@end table -# disable ccp1 for all functions - -fdisable-tree-ccp1 -# disable complete unroll for function whose cgraph node uid is 1 - -fenable-tree-cunroll=1 -# disable gcse2 for functions at the following ranges [1,1], -# [300,400], and [400,1000] -# disable gcse2 for functions foo and foo2 - -fdisable-rtl-gcse2=foo,foo2 -# disable early inlining - -fdisable-tree-einline -# disable ipa inlining - -fdisable-ipa-inline -# enable tree full unroll - -fenable-tree-unroll +@item -fdump-passes +@opindex fdump-passes +Dump the list of optimization passes that are turned on and off by +the current command-line options. -@end smallexample +@item -fdump-statistics-@var{option} +@opindex fdump-statistics +Enable and control dumping of pass statistics in a separate file. The +file name is generated by appending a suffix ending in +@samp{.statistics} to the source file name, and the file is created in +the same directory as the output file. If the @samp{-@var{option}} +form is used, @samp{-stats} causes counters to be summed over the +whole compilation unit while @samp{-details} dumps every event as +the passes generate them. The default with no option is to sum +counters for each function compiled. -@item -d@var{letters} -@itemx -fdump-rtl-@var{pass} -@itemx -fdump-rtl-@var{pass}=@var{filename} -@opindex d -@opindex fdump-rtl-@var{pass} -Says to make debugging dumps during compilation at times specified by -@var{letters}. This is used for debugging the RTL-based passes of the -compiler. The file names for most of the dumps are made by appending -a pass number and a word to the @var{dumpname}, and the files are -created in the directory of the output file. In case of +@item -fdump-tree-@var{switch} +@itemx -fdump-tree-@var{switch}-@var{options} +@itemx -fdump-tree-@var{switch}-@var{options}=@var{filename} +@opindex fdump-tree +Control the dumping at various stages of processing the intermediate +language tree to a file. The file name is generated by appending a +switch-specific suffix to the source file name, and the file is +created in the same directory as the output file. In case of @option{=@var{filename}} option, the dump is output on the given file -instead of the pass numbered dump files. Note that the pass number is -assigned as passes are registered into the pass manager. Most passes -are registered in the order that they will execute and for these passes -the number corresponds to the pass execution order. However, passes -registered by plugins, passes specific to compilation targets, or -passes that are otherwise registered after all the other passes are -numbered higher than a pass named "final", even if they are executed -earlier. @var{dumpname} is generated from the name of the output -file if explicitly specified and not an executable, otherwise it is -the basename of the source file. These switches may have different -effects when @option{-E} is used for preprocessing. - -Debug dumps can be enabled with a @option{-fdump-rtl} switch or some -@option{-d} option @var{letters}. Here are the possible -letters for use in @var{pass} and @var{letters}, and their meanings: +instead of the auto named dump files. If the @samp{-@var{options}} +form is used, @var{options} is a list of @samp{-} separated options +which control the details of the dump. Not all options are applicable +to all dumps; those that are not meaningful are ignored. The +following options are available -@table @gcctabopt +@table @samp +@item address +Print the address of each node. Usually this is not meaningful as it +changes according to the environment and source file. Its primary use +is for tying up a dump file with a debug environment. +@item asmname +If @code{DECL_ASSEMBLER_NAME} has been set for a given decl, use that +in the dump instead of @code{DECL_NAME}. Its primary use is ease of +use working backward from mangled names in the assembly file. +@item slim +When dumping front-end intermediate representations, inhibit dumping +of members of a scope or body of a function merely because that scope +has been reached. Only dump such items when they are directly reachable +by some other path. -@item -fdump-rtl-alignments -@opindex fdump-rtl-alignments -Dump after branch alignments have been computed. +When dumping pretty-printed trees, this option inhibits dumping the +bodies of control structures. -@item -fdump-rtl-asmcons -@opindex fdump-rtl-asmcons -Dump after fixing rtl statements that have unsatisfied in/out constraints. +When dumping RTL, print the RTL in slim (condensed) form instead of +the default LISP-like representation. +@item raw +Print a raw representation of the tree. By default, trees are +pretty-printed into a C-like representation. +@item details +Enable more detailed dumps (not honored by every dump option). Also +include information from the optimization passes. +@item stats +Enable dumping various statistics about the pass (not honored by every dump +option). +@item blocks +Enable showing basic block boundaries (disabled in raw dumps). +@item graph +For each of the other indicated dump files (@option{-fdump-rtl-@var{pass}}), +dump a representation of the control flow graph suitable for viewing with +GraphViz to @file{@var{file}.@var{passid}.@var{pass}.dot}. Each function in +the file is pretty-printed as a subgraph, so that GraphViz can render them +all in a single plot. -@item -fdump-rtl-auto_inc_dec -@opindex fdump-rtl-auto_inc_dec -Dump after auto-inc-dec discovery. This pass is only run on -architectures that have auto inc or auto dec instructions. +This option currently only works for RTL dumps, and the RTL is always +dumped in slim form. +@item vops +Enable showing virtual operands for every statement. +@item lineno +Enable showing line numbers for statements. +@item uid +Enable showing the unique ID (@code{DECL_UID}) for each variable. +@item verbose +Enable showing the tree dump for each statement. +@item eh +Enable showing the EH region number holding each statement. +@item scev +Enable showing scalar evolution analysis details. +@item optimized +Enable showing optimization information (only available in certain +passes). +@item missed +Enable showing missed optimization information (only available in certain +passes). +@item note +Enable other detailed optimization information (only available in +certain passes). +@item =@var{filename} +Instead of an auto named dump file, output into the given file +name. The file names @file{stdout} and @file{stderr} are treated +specially and are considered already open standard streams. For +example, -@item -fdump-rtl-barriers -@opindex fdump-rtl-barriers -Dump after cleaning up the barrier instructions. +@smallexample +gcc -O2 -ftree-vectorize -fdump-tree-vect-blocks=foo.dump + -fdump-tree-pre=stderr file.c +@end smallexample -@item -fdump-rtl-bbpart -@opindex fdump-rtl-bbpart -Dump after partitioning hot and cold basic blocks. +outputs vectorizer dump into @file{foo.dump}, while the PRE dump is +output on to @file{stderr}. If two conflicting dump filenames are +given for the same pass, then the latter option overrides the earlier +one. -@item -fdump-rtl-bbro -@opindex fdump-rtl-bbro -Dump after block reordering. +@item split-paths +@opindex fdump-tree-split-paths +Dump each function after splitting paths to loop backedges. The file +name is made by appending @file{.split-paths} to the source file name. -@item -fdump-rtl-btl1 -@itemx -fdump-rtl-btl2 -@opindex fdump-rtl-btl2 -@opindex fdump-rtl-btl2 -@option{-fdump-rtl-btl1} and @option{-fdump-rtl-btl2} enable dumping -after the two branch -target load optimization passes. +@item all +Turn on all options, except @option{raw}, @option{slim}, @option{verbose} +and @option{lineno}. -@item -fdump-rtl-bypass -@opindex fdump-rtl-bypass -Dump after jump bypassing and control flow optimizations. +@item optall +Turn on all optimization options, i.e., @option{optimized}, +@option{missed}, and @option{note}. +@end table -@item -fdump-rtl-combine -@opindex fdump-rtl-combine -Dump after the RTL instruction combination pass. +The following tree dumps are possible: +@table @samp -@item -fdump-rtl-compgotos -@opindex fdump-rtl-compgotos -Dump after duplicating the computed gotos. +@item original +@opindex fdump-tree-original +Dump before any tree based optimization, to @file{@var{file}.original}. -@item -fdump-rtl-ce1 -@itemx -fdump-rtl-ce2 -@itemx -fdump-rtl-ce3 -@opindex fdump-rtl-ce1 -@opindex fdump-rtl-ce2 -@opindex fdump-rtl-ce3 -@option{-fdump-rtl-ce1}, @option{-fdump-rtl-ce2}, and -@option{-fdump-rtl-ce3} enable dumping after the three -if conversion passes. +@item optimized +@opindex fdump-tree-optimized +Dump after all tree based optimization, to @file{@var{file}.optimized}. -@item -fdump-rtl-cprop_hardreg -@opindex fdump-rtl-cprop_hardreg -Dump after hard register copy propagation. +@item gimple +@opindex fdump-tree-gimple +Dump each function before and after the gimplification pass to a file. The +file name is made by appending @file{.gimple} to the source file name. -@item -fdump-rtl-csa -@opindex fdump-rtl-csa -Dump after combining stack adjustments. +@item cfg +@opindex fdump-tree-cfg +Dump the control flow graph of each function to a file. The file name is +made by appending @file{.cfg} to the source file name. -@item -fdump-rtl-cse1 -@itemx -fdump-rtl-cse2 -@opindex fdump-rtl-cse1 -@opindex fdump-rtl-cse2 -@option{-fdump-rtl-cse1} and @option{-fdump-rtl-cse2} enable dumping after -the two common subexpression elimination passes. +@item ch +@opindex fdump-tree-ch +Dump each function after copying loop headers. The file name is made by +appending @file{.ch} to the source file name. -@item -fdump-rtl-dce -@opindex fdump-rtl-dce -Dump after the standalone dead code elimination passes. +@item ssa +@opindex fdump-tree-ssa +Dump SSA related information to a file. The file name is made by appending +@file{.ssa} to the source file name. -@item -fdump-rtl-dbr -@opindex fdump-rtl-dbr -Dump after delayed branch scheduling. +@item alias +@opindex fdump-tree-alias +Dump aliasing information for each function. The file name is made by +appending @file{.alias} to the source file name. -@item -fdump-rtl-dce1 -@itemx -fdump-rtl-dce2 -@opindex fdump-rtl-dce1 -@opindex fdump-rtl-dce2 -@option{-fdump-rtl-dce1} and @option{-fdump-rtl-dce2} enable dumping after -the two dead store elimination passes. +@item ccp +@opindex fdump-tree-ccp +Dump each function after CCP@. The file name is made by appending +@file{.ccp} to the source file name. -@item -fdump-rtl-eh -@opindex fdump-rtl-eh -Dump after finalization of EH handling code. +@item storeccp +@opindex fdump-tree-storeccp +Dump each function after STORE-CCP@. The file name is made by appending +@file{.storeccp} to the source file name. -@item -fdump-rtl-eh_ranges -@opindex fdump-rtl-eh_ranges -Dump after conversion of EH handling range regions. +@item pre +@opindex fdump-tree-pre +Dump trees after partial redundancy elimination. The file name is made +by appending @file{.pre} to the source file name. -@item -fdump-rtl-expand -@opindex fdump-rtl-expand -Dump after RTL generation. +@item fre +@opindex fdump-tree-fre +Dump trees after full redundancy elimination. The file name is made +by appending @file{.fre} to the source file name. -@item -fdump-rtl-fwprop1 -@itemx -fdump-rtl-fwprop2 -@opindex fdump-rtl-fwprop1 -@opindex fdump-rtl-fwprop2 -@option{-fdump-rtl-fwprop1} and @option{-fdump-rtl-fwprop2} enable -dumping after the two forward propagation passes. +@item copyprop +@opindex fdump-tree-copyprop +Dump trees after copy propagation. The file name is made +by appending @file{.copyprop} to the source file name. -@item -fdump-rtl-gcse1 -@itemx -fdump-rtl-gcse2 -@opindex fdump-rtl-gcse1 -@opindex fdump-rtl-gcse2 -@option{-fdump-rtl-gcse1} and @option{-fdump-rtl-gcse2} enable dumping -after global common subexpression elimination. +@item store_copyprop +@opindex fdump-tree-store_copyprop +Dump trees after store copy-propagation. The file name is made +by appending @file{.store_copyprop} to the source file name. -@item -fdump-rtl-init-regs -@opindex fdump-rtl-init-regs -Dump after the initialization of the registers. +@item dce +@opindex fdump-tree-dce +Dump each function after dead code elimination. The file name is made by +appending @file{.dce} to the source file name. -@item -fdump-rtl-initvals -@opindex fdump-rtl-initvals -Dump after the computation of the initial value sets. +@item sra +@opindex fdump-tree-sra +Dump each function after performing scalar replacement of aggregates. The +file name is made by appending @file{.sra} to the source file name. -@item -fdump-rtl-into_cfglayout -@opindex fdump-rtl-into_cfglayout -Dump after converting to cfglayout mode. +@item sink +@opindex fdump-tree-sink +Dump each function after performing code sinking. The file name is made +by appending @file{.sink} to the source file name. -@item -fdump-rtl-ira -@opindex fdump-rtl-ira -Dump after iterated register allocation. +@item dom +@opindex fdump-tree-dom +Dump each function after applying dominator tree optimizations. The file +name is made by appending @file{.dom} to the source file name. -@item -fdump-rtl-jump -@opindex fdump-rtl-jump -Dump after the second jump optimization. +@item dse +@opindex fdump-tree-dse +Dump each function after applying dead store elimination. The file +name is made by appending @file{.dse} to the source file name. -@item -fdump-rtl-loop2 -@opindex fdump-rtl-loop2 -@option{-fdump-rtl-loop2} enables dumping after the rtl -loop optimization passes. +@item phiopt +@opindex fdump-tree-phiopt +Dump each function after optimizing PHI nodes into straightline code. The file +name is made by appending @file{.phiopt} to the source file name. -@item -fdump-rtl-mach -@opindex fdump-rtl-mach -Dump after performing the machine dependent reorganization pass, if that -pass exists. +@item backprop +@opindex fdump-tree-backprop +Dump each function after back-propagating use information up the definition +chain. The file name is made by appending @file{.backprop} to the +source file name. -@item -fdump-rtl-mode_sw -@opindex fdump-rtl-mode_sw -Dump after removing redundant mode switches. +@item forwprop +@opindex fdump-tree-forwprop +Dump each function after forward propagating single use variables. The file +name is made by appending @file{.forwprop} to the source file name. -@item -fdump-rtl-rnreg -@opindex fdump-rtl-rnreg -Dump after register renumbering. +@item nrv +@opindex fdump-tree-nrv +Dump each function after applying the named return value optimization on +generic trees. The file name is made by appending @file{.nrv} to the source +file name. -@item -fdump-rtl-outof_cfglayout -@opindex fdump-rtl-outof_cfglayout -Dump after converting from cfglayout mode. +@item vect +@opindex fdump-tree-vect +Dump each function after applying vectorization of loops. The file name is +made by appending @file{.vect} to the source file name. -@item -fdump-rtl-peephole2 -@opindex fdump-rtl-peephole2 -Dump after the peephole pass. +@item slp +@opindex fdump-tree-slp +Dump each function after applying vectorization of basic blocks. The file name +is made by appending @file{.slp} to the source file name. -@item -fdump-rtl-postreload -@opindex fdump-rtl-postreload -Dump after post-reload optimizations. +@item vrp +@opindex fdump-tree-vrp +Dump each function after Value Range Propagation (VRP). The file name +is made by appending @file{.vrp} to the source file name. -@item -fdump-rtl-pro_and_epilogue -@opindex fdump-rtl-pro_and_epilogue -Dump after generating the function prologues and epilogues. +@item oaccdevlow +@opindex fdump-tree-oaccdevlow +Dump each function after applying device-specific OpenACC transformations. +The file name is made by appending @file{.oaccdevlow} to the source file name. -@item -fdump-rtl-sched1 -@itemx -fdump-rtl-sched2 -@opindex fdump-rtl-sched1 -@opindex fdump-rtl-sched2 -@option{-fdump-rtl-sched1} and @option{-fdump-rtl-sched2} enable dumping -after the basic block scheduling passes. +@item all +@opindex fdump-tree-all +Enable all the available tree dumps with the flags provided in this option. +@end table -@item -fdump-rtl-ree -@opindex fdump-rtl-ree -Dump after sign/zero extension elimination. +@item -fopt-info +@itemx -fopt-info-@var{options} +@itemx -fopt-info-@var{options}=@var{filename} +@opindex fopt-info +Controls optimization dumps from various optimization passes. If the +@samp{-@var{options}} form is used, @var{options} is a list of +@samp{-} separated option keywords to select the dump details and +optimizations. -@item -fdump-rtl-seqabstr -@opindex fdump-rtl-seqabstr -Dump after common sequence discovery. +The @var{options} can be divided into two groups: options describing the +verbosity of the dump, and options describing which optimizations +should be included. The options from both the groups can be freely +mixed as they are non-overlapping. However, in case of any conflicts, +the later options override the earlier options on the command +line. -@item -fdump-rtl-shorten -@opindex fdump-rtl-shorten -Dump after shortening branches. +The following options control the dump verbosity: -@item -fdump-rtl-sibling -@opindex fdump-rtl-sibling -Dump after sibling call optimizations. +@table @samp +@item optimized +Print information when an optimization is successfully applied. It is +up to a pass to decide which information is relevant. For example, the +vectorizer passes print the source location of loops which are +successfully vectorized. +@item missed +Print information about missed optimizations. Individual passes +control which information to include in the output. +@item note +Print verbose information about optimizations, such as certain +transformations, more detailed messages about decisions etc. +@item all +Print detailed optimization information. This includes +@samp{optimized}, @samp{missed}, and @samp{note}. +@end table -@item -fdump-rtl-split1 -@itemx -fdump-rtl-split2 -@itemx -fdump-rtl-split3 -@itemx -fdump-rtl-split4 -@itemx -fdump-rtl-split5 -@opindex fdump-rtl-split1 -@opindex fdump-rtl-split2 -@opindex fdump-rtl-split3 -@opindex fdump-rtl-split4 -@opindex fdump-rtl-split5 -These options enable dumping after five rounds of -instruction splitting. +One or more of the following option keywords can be used to describe a +group of optimizations: -@item -fdump-rtl-sms -@opindex fdump-rtl-sms -Dump after modulo scheduling. This pass is only run on some -architectures. +@table @samp +@item ipa +Enable dumps from all interprocedural optimizations. +@item loop +Enable dumps from all loop optimizations. +@item inline +Enable dumps from all inlining optimizations. +@item vec +Enable dumps from all vectorization optimizations. +@item optall +Enable dumps from all optimizations. This is a superset of +the optimization groups listed above. +@end table -@item -fdump-rtl-stack -@opindex fdump-rtl-stack -Dump after conversion from GCC's ``flat register file'' registers to the -x87's stack-like registers. This pass is only run on x86 variants. +If @var{options} is +omitted, it defaults to @samp{optimized-optall}, which means to dump all +info about successful optimizations from all the passes. -@item -fdump-rtl-subreg1 -@itemx -fdump-rtl-subreg2 -@opindex fdump-rtl-subreg1 -@opindex fdump-rtl-subreg2 -@option{-fdump-rtl-subreg1} and @option{-fdump-rtl-subreg2} enable dumping after -the two subreg expansion passes. +If the @var{filename} is provided, then the dumps from all the +applicable optimizations are concatenated into the @var{filename}. +Otherwise the dump is output onto @file{stderr}. Though multiple +@option{-fopt-info} options are accepted, only one of them can include +a @var{filename}. If other filenames are provided then all but the +first such option are ignored. -@item -fdump-rtl-unshare -@opindex fdump-rtl-unshare -Dump after all rtl has been unshared. - -@item -fdump-rtl-vartrack -@opindex fdump-rtl-vartrack -Dump after variable tracking. +Note that the output @var{filename} is overwritten +in case of multiple translation units. If a combined output from +multiple translation units is desired, @file{stderr} should be used +instead. -@item -fdump-rtl-vregs -@opindex fdump-rtl-vregs -Dump after converting virtual registers to hard registers. +In the following example, the optimization info is output to +@file{stderr}: -@item -fdump-rtl-web -@opindex fdump-rtl-web -Dump after live range splitting. +@smallexample +gcc -O3 -fopt-info +@end smallexample -@item -fdump-rtl-regclass -@itemx -fdump-rtl-subregs_of_mode_init -@itemx -fdump-rtl-subregs_of_mode_finish -@itemx -fdump-rtl-dfinit -@itemx -fdump-rtl-dfinish -@opindex fdump-rtl-regclass -@opindex fdump-rtl-subregs_of_mode_init -@opindex fdump-rtl-subregs_of_mode_finish -@opindex fdump-rtl-dfinit -@opindex fdump-rtl-dfinish -These dumps are defined but always produce empty files. +This example: +@smallexample +gcc -O3 -fopt-info-missed=missed.all +@end smallexample -@item -da -@itemx -fdump-rtl-all -@opindex da -@opindex fdump-rtl-all -Produce all the dumps listed above. +@noindent +outputs missed optimization report from all the passes into +@file{missed.all}, and this one: -@item -dA -@opindex dA -Annotate the assembler output with miscellaneous debugging information. +@smallexample +gcc -O2 -ftree-vectorize -fopt-info-vec-missed +@end smallexample -@item -dD -@opindex dD -Dump all macro definitions, at the end of preprocessing, in addition to -normal output. +@noindent +prints information about missed optimization opportunities from +vectorization passes on @file{stderr}. +Note that @option{-fopt-info-vec-missed} is equivalent to +@option{-fopt-info-missed-vec}. -@item -dH -@opindex dH -Produce a core dump whenever an error occurs. +As another example, +@smallexample +gcc -O3 -fopt-info-inline-optimized-missed=inline.txt +@end smallexample -@item -dp -@opindex dp -Annotate the assembler output with a comment indicating which -pattern and alternative is used. The length of each instruction is -also printed. +@noindent +outputs information about missed optimizations as well as +optimized locations from all the inlining passes into +@file{inline.txt}. -@item -dP -@opindex dP -Dump the RTL in the assembler output as a comment before each instruction. -Also turns on @option{-dp} annotation. +Finally, consider: -@item -dx -@opindex dx -Just generate RTL for a function instead of compiling it. Usually used -with @option{-fdump-rtl-expand}. -@end table +@smallexample +gcc -fopt-info-vec-missed=vec.miss -fopt-info-loop-optimized=loop.opt +@end smallexample -@item -fdump-noaddr -@opindex fdump-noaddr -When doing debugging dumps, suppress address output. This makes it more -feasible to use diff on debugging dumps for compiler invocations with -different compiler binaries and/or different -text / bss / data / heap / stack / dso start locations. +@noindent +Here the two output filenames @file{vec.miss} and @file{loop.opt} are +in conflict since only one output file is allowed. In this case, only +the first option takes effect and the subsequent options are +ignored. Thus only @file{vec.miss} is produced which contains +dumps from the vectorizer about missed opportunities. -@item -freport-bug -@opindex freport-bug -Collect and dump debug information into temporary file if ICE in C/C++ -compiler occured. +@item -frandom-seed=@var{string} +@opindex frandom-seed +This option provides a seed that GCC uses in place of +random numbers in generating certain symbol names +that have to be different in every compiled file. It is also used to +place unique stamps in coverage data files and the object files that +produce them. You can use the @option{-frandom-seed} option to produce +reproducibly identical object files. -@item -fdump-unnumbered -@opindex fdump-unnumbered -When doing debugging dumps, suppress instruction numbers and address output. -This makes it more feasible to use diff on debugging dumps for compiler -invocations with different options, in particular with and without -@option{-g}. +The @var{string} can either be a number (decimal, octal or hex) or an +arbitrary string (in which case it's converted to a number by +computing CRC32). -@item -fdump-unnumbered-links -@opindex fdump-unnumbered-links -When doing debugging dumps (see @option{-d} option above), suppress -instruction numbers for the links to the previous and next instructions -in a sequence. +The @var{string} should be different for every file you compile. -@item -fdump-translation-unit @r{(C++ only)} -@itemx -fdump-translation-unit-@var{options} @r{(C++ only)} -@opindex fdump-translation-unit -Dump a representation of the tree structure for the entire translation -unit to a file. The file name is made by appending @file{.tu} to the -source file name, and the file is created in the same directory as the -output file. If the @samp{-@var{options}} form is used, @var{options} -controls the details of the dump as described for the -@option{-fdump-tree} options. +@item -fsched-verbose=@var{n} +@opindex fsched-verbose +On targets that use instruction scheduling, this option controls the +amount of debugging output the scheduler prints to the dump files. -@item -fdump-class-hierarchy @r{(C++ only)} -@itemx -fdump-class-hierarchy-@var{options} @r{(C++ only)} -@opindex fdump-class-hierarchy -Dump a representation of each class's hierarchy and virtual function -table layout to a file. The file name is made by appending -@file{.class} to the source file name, and the file is created in the -same directory as the output file. If the @samp{-@var{options}} form -is used, @var{options} controls the details of the dump as described -for the @option{-fdump-tree} options. +For @var{n} greater than zero, @option{-fsched-verbose} outputs the +same information as @option{-fdump-rtl-sched1} and @option{-fdump-rtl-sched2}. +For @var{n} greater than one, it also output basic block probabilities, +detailed ready list information and unit/insn info. For @var{n} greater +than two, it includes RTL at abort point, control-flow and regions info. +And for @var{n} over four, @option{-fsched-verbose} also includes +dependence info. -@item -fdump-ipa-@var{switch} -@opindex fdump-ipa -Control the dumping at various stages of inter-procedural analysis -language tree to a file. The file name is generated by appending a -switch specific suffix to the source file name, and the file is created -in the same directory as the output file. The following dumps are -possible: +@item -save-temps +@itemx -save-temps=cwd +@opindex save-temps +Store the usual ``temporary'' intermediate files permanently; place them +in the current directory and name them based on the source file. Thus, +compiling @file{foo.c} with @option{-c -save-temps} produces files +@file{foo.i} and @file{foo.s}, as well as @file{foo.o}. This creates a +preprocessed @file{foo.i} output file even though the compiler now +normally uses an integrated preprocessor. -@table @samp -@item all -Enables all inter-procedural analysis dumps. +When used in combination with the @option{-x} command-line option, +@option{-save-temps} is sensible enough to avoid over writing an +input source file with the same extension as an intermediate file. +The corresponding intermediate file may be obtained by renaming the +source file before using @option{-save-temps}. -@item cgraph -Dumps information about call-graph optimization, unused function removal, -and inlining decisions. +If you invoke GCC in parallel, compiling several different source +files that share a common base name in different subdirectories or the +same source file compiled for multiple output destinations, it is +likely that the different parallel compilers will interfere with each +other, and overwrite the temporary files. For instance: -@item inline -Dump after function inlining. +@smallexample +gcc -save-temps -o outdir1/foo.o indir1/foo.c& +gcc -save-temps -o outdir2/foo.o indir2/foo.c& +@end smallexample -@end table +may result in @file{foo.i} and @file{foo.o} being written to +simultaneously by both compilers. -@item -fdump-passes -@opindex fdump-passes -Dump the list of optimization passes that are turned on and off by -the current command-line options. +@item -save-temps=obj +@opindex save-temps=obj +Store the usual ``temporary'' intermediate files permanently. If the +@option{-o} option is used, the temporary files are based on the +object file. If the @option{-o} option is not used, the +@option{-save-temps=obj} switch behaves like @option{-save-temps}. -@item -fdump-statistics-@var{option} -@opindex fdump-statistics -Enable and control dumping of pass statistics in a separate file. The -file name is generated by appending a suffix ending in -@samp{.statistics} to the source file name, and the file is created in -the same directory as the output file. If the @samp{-@var{option}} -form is used, @samp{-stats} causes counters to be summed over the -whole compilation unit while @samp{-details} dumps every event as -the passes generate them. The default with no option is to sum -counters for each function compiled. +For example: -@item -fdump-tree-@var{switch} -@itemx -fdump-tree-@var{switch}-@var{options} -@itemx -fdump-tree-@var{switch}-@var{options}=@var{filename} -@opindex fdump-tree -Control the dumping at various stages of processing the intermediate -language tree to a file. The file name is generated by appending a -switch-specific suffix to the source file name, and the file is -created in the same directory as the output file. In case of -@option{=@var{filename}} option, the dump is output on the given file -instead of the auto named dump files. If the @samp{-@var{options}} -form is used, @var{options} is a list of @samp{-} separated options -which control the details of the dump. Not all options are applicable -to all dumps; those that are not meaningful are ignored. The -following options are available +@smallexample +gcc -save-temps=obj -c foo.c +gcc -save-temps=obj -c bar.c -o dir/xbar.o +gcc -save-temps=obj foobar.c -o dir2/yfoobar +@end smallexample -@table @samp -@item address -Print the address of each node. Usually this is not meaningful as it -changes according to the environment and source file. Its primary use -is for tying up a dump file with a debug environment. -@item asmname -If @code{DECL_ASSEMBLER_NAME} has been set for a given decl, use that -in the dump instead of @code{DECL_NAME}. Its primary use is ease of -use working backward from mangled names in the assembly file. -@item slim -When dumping front-end intermediate representations, inhibit dumping -of members of a scope or body of a function merely because that scope -has been reached. Only dump such items when they are directly reachable -by some other path. +@noindent +creates @file{foo.i}, @file{foo.s}, @file{dir/xbar.i}, +@file{dir/xbar.s}, @file{dir2/yfoobar.i}, @file{dir2/yfoobar.s}, and +@file{dir2/yfoobar.o}. -When dumping pretty-printed trees, this option inhibits dumping the -bodies of control structures. - -When dumping RTL, print the RTL in slim (condensed) form instead of -the default LISP-like representation. -@item raw -Print a raw representation of the tree. By default, trees are -pretty-printed into a C-like representation. -@item details -Enable more detailed dumps (not honored by every dump option). Also -include information from the optimization passes. -@item stats -Enable dumping various statistics about the pass (not honored by every dump -option). -@item blocks -Enable showing basic block boundaries (disabled in raw dumps). -@item graph -For each of the other indicated dump files (@option{-fdump-rtl-@var{pass}}), -dump a representation of the control flow graph suitable for viewing with -GraphViz to @file{@var{file}.@var{passid}.@var{pass}.dot}. Each function in -the file is pretty-printed as a subgraph, so that GraphViz can render them -all in a single plot. +@item -time@r{[}=@var{file}@r{]} +@opindex time +Report the CPU time taken by each subprocess in the compilation +sequence. For C source files, this is the compiler proper and assembler +(plus the linker if linking is done). -This option currently only works for RTL dumps, and the RTL is always -dumped in slim form. -@item vops -Enable showing virtual operands for every statement. -@item lineno -Enable showing line numbers for statements. -@item uid -Enable showing the unique ID (@code{DECL_UID}) for each variable. -@item verbose -Enable showing the tree dump for each statement. -@item eh -Enable showing the EH region number holding each statement. -@item scev -Enable showing scalar evolution analysis details. -@item optimized -Enable showing optimization information (only available in certain -passes). -@item missed -Enable showing missed optimization information (only available in certain -passes). -@item note -Enable other detailed optimization information (only available in -certain passes). -@item =@var{filename} -Instead of an auto named dump file, output into the given file -name. The file names @file{stdout} and @file{stderr} are treated -specially and are considered already open standard streams. For -example, +Without the specification of an output file, the output looks like this: @smallexample -gcc -O2 -ftree-vectorize -fdump-tree-vect-blocks=foo.dump - -fdump-tree-pre=stderr file.c +# cc1 0.12 0.01 +# as 0.00 0.01 @end smallexample -outputs vectorizer dump into @file{foo.dump}, while the PRE dump is -output on to @file{stderr}. If two conflicting dump filenames are -given for the same pass, then the latter option overrides the earlier -one. - -@item split-paths -@opindex fdump-tree-split-paths -Dump each function after splitting paths to loop backedges. The file -name is made by appending @file{.split-paths} to the source file name. +The first number on each line is the ``user time'', that is time spent +executing the program itself. The second number is ``system time'', +time spent executing operating system routines on behalf of the program. +Both numbers are in seconds. -@item all -Turn on all options, except @option{raw}, @option{slim}, @option{verbose} -and @option{lineno}. +With the specification of an output file, the output is appended to the +named file, and it looks like this: -@item optall -Turn on all optimization options, i.e., @option{optimized}, -@option{missed}, and @option{note}. -@end table +@smallexample +0.12 0.01 cc1 @var{options} +0.00 0.01 as @var{options} +@end smallexample -The following tree dumps are possible: -@table @samp +The ``user time'' and the ``system time'' are moved before the program +name, and the options passed to the program are displayed, so that one +can later tell what file was being compiled, and with which options. -@item original -@opindex fdump-tree-original -Dump before any tree based optimization, to @file{@var{file}.original}. +@item -fvar-tracking +@opindex fvar-tracking +Run variable tracking pass. It computes where variables are stored at each +position in code. Better debugging information is then generated +(if the debugging information format supports this information). -@item optimized -@opindex fdump-tree-optimized -Dump after all tree based optimization, to @file{@var{file}.optimized}. +It is enabled by default when compiling with optimization (@option{-Os}, +@option{-O}, @option{-O2}, @dots{}), debugging information (@option{-g}) and +the debug info format supports it. -@item gimple -@opindex fdump-tree-gimple -Dump each function before and after the gimplification pass to a file. The -file name is made by appending @file{.gimple} to the source file name. +@item -fvar-tracking-assignments +@opindex fvar-tracking-assignments +@opindex fno-var-tracking-assignments +Annotate assignments to user variables early in the compilation and +attempt to carry the annotations over throughout the compilation all the +way to the end, in an attempt to improve debug information while +optimizing. Use of @option{-gdwarf-4} is recommended along with it. -@item cfg -@opindex fdump-tree-cfg -Dump the control flow graph of each function to a file. The file name is -made by appending @file{.cfg} to the source file name. +It can be enabled even if var-tracking is disabled, in which case +annotations are created and maintained, but discarded at the end. +By default, this flag is enabled together with @option{-fvar-tracking}, +except when selective scheduling is enabled. -@item ch -@opindex fdump-tree-ch -Dump each function after copying loop headers. The file name is made by -appending @file{.ch} to the source file name. +@item -fvar-tracking-assignments-toggle +@opindex fvar-tracking-assignments-toggle +@opindex fno-var-tracking-assignments-toggle +Toggle @option{-fvar-tracking-assignments}, in the same way that +@option{-gtoggle} toggles @option{-g}. -@item ssa -@opindex fdump-tree-ssa -Dump SSA related information to a file. The file name is made by appending -@file{.ssa} to the source file name. +@item -print-file-name=@var{library} +@opindex print-file-name +Print the full absolute name of the library file @var{library} that +would be used when linking---and don't do anything else. With this +option, GCC does not compile or link anything; it just prints the +file name. -@item alias -@opindex fdump-tree-alias -Dump aliasing information for each function. The file name is made by -appending @file{.alias} to the source file name. +@item -print-multi-directory +@opindex print-multi-directory +Print the directory name corresponding to the multilib selected by any +other switches present in the command line. This directory is supposed +to exist in @env{GCC_EXEC_PREFIX}. -@item ccp -@opindex fdump-tree-ccp -Dump each function after CCP@. The file name is made by appending -@file{.ccp} to the source file name. +@item -print-multi-lib +@opindex print-multi-lib +Print the mapping from multilib directory names to compiler switches +that enable them. The directory name is separated from the switches by +@samp{;}, and each switch starts with an @samp{@@} instead of the +@samp{-}, without spaces between multiple switches. This is supposed to +ease shell processing. -@item storeccp -@opindex fdump-tree-storeccp -Dump each function after STORE-CCP@. The file name is made by appending -@file{.storeccp} to the source file name. +@item -print-multi-os-directory +@opindex print-multi-os-directory +Print the path to OS libraries for the selected +multilib, relative to some @file{lib} subdirectory. If OS libraries are +present in the @file{lib} subdirectory and no multilibs are used, this is +usually just @file{.}, if OS libraries are present in @file{lib@var{suffix}} +sibling directories this prints e.g.@: @file{../lib64}, @file{../lib} or +@file{../lib32}, or if OS libraries are present in @file{lib/@var{subdir}} +subdirectories it prints e.g.@: @file{amd64}, @file{sparcv9} or @file{ev6}. -@item pre -@opindex fdump-tree-pre -Dump trees after partial redundancy elimination. The file name is made -by appending @file{.pre} to the source file name. +@item -print-multiarch +@opindex print-multiarch +Print the path to OS libraries for the selected multiarch, +relative to some @file{lib} subdirectory. -@item fre -@opindex fdump-tree-fre -Dump trees after full redundancy elimination. The file name is made -by appending @file{.fre} to the source file name. +@item -print-prog-name=@var{program} +@opindex print-prog-name +Like @option{-print-file-name}, but searches for a program such as @command{cpp}. -@item copyprop -@opindex fdump-tree-copyprop -Dump trees after copy propagation. The file name is made -by appending @file{.copyprop} to the source file name. +@item -print-libgcc-file-name +@opindex print-libgcc-file-name +Same as @option{-print-file-name=libgcc.a}. -@item store_copyprop -@opindex fdump-tree-store_copyprop -Dump trees after store copy-propagation. The file name is made -by appending @file{.store_copyprop} to the source file name. +This is useful when you use @option{-nostdlib} or @option{-nodefaultlibs} +but you do want to link with @file{libgcc.a}. You can do: -@item dce -@opindex fdump-tree-dce -Dump each function after dead code elimination. The file name is made by -appending @file{.dce} to the source file name. +@smallexample +gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name` +@end smallexample -@item sra -@opindex fdump-tree-sra -Dump each function after performing scalar replacement of aggregates. The -file name is made by appending @file{.sra} to the source file name. +@item -print-search-dirs +@opindex print-search-dirs +Print the name of the configured installation directory and a list of +program and library directories @command{gcc} searches---and don't do anything else. -@item sink -@opindex fdump-tree-sink -Dump each function after performing code sinking. The file name is made -by appending @file{.sink} to the source file name. +This is useful when @command{gcc} prints the error message +@samp{installation problem, cannot exec cpp0: No such file or directory}. +To resolve this you either need to put @file{cpp0} and the other compiler +components where @command{gcc} expects to find them, or you can set the environment +variable @env{GCC_EXEC_PREFIX} to the directory where you installed them. +Don't forget the trailing @samp{/}. +@xref{Environment Variables}. -@item dom -@opindex fdump-tree-dom -Dump each function after applying dominator tree optimizations. The file -name is made by appending @file{.dom} to the source file name. +@item -print-sysroot +@opindex print-sysroot +Print the target sysroot directory that is used during +compilation. This is the target sysroot specified either at configure +time or using the @option{--sysroot} option, possibly with an extra +suffix that depends on compilation options. If no target sysroot is +specified, the option prints nothing. -@item dse -@opindex fdump-tree-dse -Dump each function after applying dead store elimination. The file -name is made by appending @file{.dse} to the source file name. +@item -print-sysroot-headers-suffix +@opindex print-sysroot-headers-suffix +Print the suffix added to the target sysroot when searching for +headers, or give an error if the compiler is not configured with such +a suffix---and don't do anything else. -@item phiopt -@opindex fdump-tree-phiopt -Dump each function after optimizing PHI nodes into straightline code. The file -name is made by appending @file{.phiopt} to the source file name. +@item -dumpmachine +@opindex dumpmachine +Print the compiler's target machine (for example, +@samp{i686-pc-linux-gnu})---and don't do anything else. -@item backprop -@opindex fdump-tree-backprop -Dump each function after back-propagating use information up the definition -chain. The file name is made by appending @file{.backprop} to the -source file name. +@item -dumpversion +@opindex dumpversion +Print the compiler version (for example, @code{3.0})---and don't do +anything else. -@item forwprop -@opindex fdump-tree-forwprop -Dump each function after forward propagating single use variables. The file -name is made by appending @file{.forwprop} to the source file name. +@item -dumpspecs +@opindex dumpspecs +Print the compiler's built-in specs---and don't do anything else. (This +is used when GCC itself is being built.) @xref{Spec Files}. -@item nrv -@opindex fdump-tree-nrv -Dump each function after applying the named return value optimization on -generic trees. The file name is made by appending @file{.nrv} to the source -file name. +@item -fno-eliminate-unused-debug-types +@opindex feliminate-unused-debug-types +@opindex fno-eliminate-unused-debug-types +Normally, when producing DWARF 2 output, GCC avoids producing debug symbol +output for types that are nowhere used in the source file being compiled. +Sometimes it is useful to have GCC emit debugging +information for all types declared in a compilation +unit, regardless of whether or not they are actually used +in that compilation unit, for example +if, in the debugger, you want to cast a value to a type that is +not actually used in your program (but is declared). More often, +however, this results in a significant amount of wasted space. +@end table -@item vect -@opindex fdump-tree-vect -Dump each function after applying vectorization of loops. The file name is -made by appending @file{.vect} to the source file name. +@node Optimize Options +@section Options That Control Optimization +@cindex optimize options +@cindex options, optimization -@item slp -@opindex fdump-tree-slp -Dump each function after applying vectorization of basic blocks. The file name -is made by appending @file{.slp} to the source file name. +These options control various sorts of optimizations. -@item vrp -@opindex fdump-tree-vrp -Dump each function after Value Range Propagation (VRP). The file name -is made by appending @file{.vrp} to the source file name. +Without any optimization option, the compiler's goal is to reduce the +cost of compilation and to make debugging produce the expected +results. Statements are independent: if you stop the program with a +breakpoint between statements, you can then assign a new value to any +variable or change the program counter to any other statement in the +function and get exactly the results you expect from the source +code. -@item oaccdevlow -@opindex fdump-tree-oaccdevlow -Dump each function after applying device-specific OpenACC transformations. -The file name is made by appending @file{.oaccdevlow} to the source file name. +Turning on optimization flags makes the compiler attempt to improve +the performance and/or code size at the expense of compilation time +and possibly the ability to debug the program. -@item all -@opindex fdump-tree-all -Enable all the available tree dumps with the flags provided in this option. +The compiler performs optimization based on the knowledge it has of the +program. Compiling multiple files at once to a single output file mode allows +the compiler to use information gained from all of the files when compiling +each of them. + +Not all optimizations are controlled directly by a flag. Only +optimizations that have a flag are listed in this section. + +Most optimizations are only enabled if an @option{-O} level is set on +the command line. Otherwise they are disabled, even if individual +optimization flags are specified. + +Depending on the target and how GCC was configured, a slightly different +set of optimizations may be enabled at each @option{-O} level than +those listed here. You can invoke GCC with @option{-Q --help=optimizers} +to find out the exact set of optimizations that are enabled at each level. +@xref{Overall Options}, for examples. + +@table @gcctabopt +@item -O +@itemx -O1 +@opindex O +@opindex O1 +Optimize. Optimizing compilation takes somewhat more time, and a lot +more memory for a large function. + +With @option{-O}, the compiler tries to reduce code size and execution +time, without performing any optimizations that take a great deal of +compilation time. + +@option{-O} turns on the following optimization flags: +@gccoptlist{ +-fauto-inc-dec @gol +-fbranch-count-reg @gol +-fcombine-stack-adjustments @gol +-fcompare-elim @gol +-fcprop-registers @gol +-fdce @gol +-fdefer-pop @gol +-fdelayed-branch @gol +-fdse @gol +-fforward-propagate @gol +-fguess-branch-probability @gol +-fif-conversion2 @gol +-fif-conversion @gol +-finline-functions-called-once @gol +-fipa-pure-const @gol +-fipa-profile @gol +-fipa-reference @gol +-fmerge-constants @gol +-fmove-loop-invariants @gol +-freorder-blocks @gol +-fshrink-wrap @gol +-fsplit-wide-types @gol +-fssa-backprop @gol +-fssa-phiopt @gol +-ftree-bit-ccp @gol +-ftree-ccp @gol +-ftree-ch @gol +-ftree-coalesce-vars @gol +-ftree-copy-prop @gol +-ftree-dce @gol +-ftree-dominator-opts @gol +-ftree-dse @gol +-ftree-forwprop @gol +-ftree-fre @gol +-ftree-phiprop @gol +-ftree-sink @gol +-ftree-slsr @gol +-ftree-sra @gol +-ftree-pta @gol +-ftree-ter @gol +-funit-at-a-time} + +@option{-O} also turns on @option{-fomit-frame-pointer} on machines +where doing so does not interfere with debugging. + +@item -O2 +@opindex O2 +Optimize even more. GCC performs nearly all supported optimizations +that do not involve a space-speed tradeoff. +As compared to @option{-O}, this option increases both compilation time +and the performance of the generated code. + +@option{-O2} turns on all optimization flags specified by @option{-O}. It +also turns on the following optimization flags: +@gccoptlist{-fthread-jumps @gol +-falign-functions -falign-jumps @gol +-falign-loops -falign-labels @gol +-fcaller-saves @gol +-fcrossjumping @gol +-fcse-follow-jumps -fcse-skip-blocks @gol +-fdelete-null-pointer-checks @gol +-fdevirtualize -fdevirtualize-speculatively @gol +-fexpensive-optimizations @gol +-fgcse -fgcse-lm @gol +-fhoist-adjacent-loads @gol +-finline-small-functions @gol +-findirect-inlining @gol +-fipa-cp @gol +-fipa-cp-alignment @gol +-fipa-sra @gol +-fipa-icf @gol +-fisolate-erroneous-paths-dereference @gol +-flra-remat @gol +-foptimize-sibling-calls @gol +-foptimize-strlen @gol +-fpartial-inlining @gol +-fpeephole2 @gol +-freorder-blocks-algorithm=stc @gol +-freorder-blocks-and-partition -freorder-functions @gol +-frerun-cse-after-loop @gol +-fsched-interblock -fsched-spec @gol +-fschedule-insns -fschedule-insns2 @gol +-fstrict-aliasing -fstrict-overflow @gol +-ftree-builtin-call-dce @gol +-ftree-switch-conversion -ftree-tail-merge @gol +-ftree-pre @gol +-ftree-vrp @gol +-fipa-ra} + +Please note the warning under @option{-fgcse} about +invoking @option{-O2} on programs that use computed gotos. + +@item -O3 +@opindex O3 +Optimize yet more. @option{-O3} turns on all optimizations specified +by @option{-O2} and also turns on the @option{-finline-functions}, +@option{-funswitch-loops}, @option{-fpredictive-commoning}, +@option{-fgcse-after-reload}, @option{-ftree-loop-vectorize}, +@option{-ftree-loop-distribute-patterns}, @option{-fsplit-paths} +@option{-ftree-slp-vectorize}, @option{-fvect-cost-model}, +@option{-ftree-partial-pre} and @option{-fipa-cp-clone} options. + +@item -O0 +@opindex O0 +Reduce compilation time and make debugging produce the expected +results. This is the default. + +@item -Os +@opindex Os +Optimize for size. @option{-Os} enables all @option{-O2} optimizations that +do not typically increase code size. It also performs further +optimizations designed to reduce code size. + +@option{-Os} disables the following optimization flags: +@gccoptlist{-falign-functions -falign-jumps -falign-loops @gol +-falign-labels -freorder-blocks -freorder-blocks-algorithm=stc @gol +-freorder-blocks-and-partition -fprefetch-loop-arrays} + +@item -Ofast +@opindex Ofast +Disregard strict standards compliance. @option{-Ofast} enables all +@option{-O3} optimizations. It also enables optimizations that are not +valid for all standard-compliant programs. +It turns on @option{-ffast-math} and the Fortran-specific +@option{-fno-protect-parens} and @option{-fstack-arrays}. + +@item -Og +@opindex Og +Optimize debugging experience. @option{-Og} enables optimizations +that do not interfere with debugging. It should be the optimization +level of choice for the standard edit-compile-debug cycle, offering +a reasonable level of optimization while maintaining fast compilation +and a good debugging experience. @end table -@item -fopt-info -@itemx -fopt-info-@var{options} -@itemx -fopt-info-@var{options}=@var{filename} -@opindex fopt-info -Controls optimization dumps from various optimization passes. If the -@samp{-@var{options}} form is used, @var{options} is a list of -@samp{-} separated option keywords to select the dump details and -optimizations. +If you use multiple @option{-O} options, with or without level numbers, +the last such option is the one that is effective. -The @var{options} can be divided into two groups: options describing the -verbosity of the dump, and options describing which optimizations -should be included. The options from both the groups can be freely -mixed as they are non-overlapping. However, in case of any conflicts, -the later options override the earlier options on the command -line. +Options of the form @option{-f@var{flag}} specify machine-independent +flags. Most flags have both positive and negative forms; the negative +form of @option{-ffoo} is @option{-fno-foo}. In the table +below, only one of the forms is listed---the one you typically +use. You can figure out the other form by either removing @samp{no-} +or adding it. + +The following options control specific optimizations. They are either +activated by @option{-O} options or are related to ones that are. You +can use the following flags in the rare cases when ``fine-tuning'' of +optimizations to be performed is desired. + +@table @gcctabopt +@item -fno-defer-pop +@opindex fno-defer-pop +Always pop the arguments to each function call as soon as that function +returns. For machines that must pop arguments after a function call, +the compiler normally lets arguments accumulate on the stack for several +function calls and pops them all at once. + +Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. + +@item -fforward-propagate +@opindex fforward-propagate +Perform a forward propagation pass on RTL@. The pass tries to combine two +instructions and checks if the result can be simplified. If loop unrolling +is active, two passes are performed and the second is scheduled after +loop unrolling. + +This option is enabled by default at optimization levels @option{-O}, +@option{-O2}, @option{-O3}, @option{-Os}. + +@item -ffp-contract=@var{style} +@opindex ffp-contract +@option{-ffp-contract=off} disables floating-point expression contraction. +@option{-ffp-contract=fast} enables floating-point expression contraction +such as forming of fused multiply-add operations if the target has +native support for them. +@option{-ffp-contract=on} enables floating-point expression contraction +if allowed by the language standard. This is currently not implemented +and treated equal to @option{-ffp-contract=off}. + +The default is @option{-ffp-contract=fast}. + +@item -fomit-frame-pointer +@opindex fomit-frame-pointer +Don't keep the frame pointer in a register for functions that +don't need one. This avoids the instructions to save, set up and +restore frame pointers; it also makes an extra register available +in many functions. @strong{It also makes debugging impossible on +some machines.} + +On some machines, such as the VAX, this flag has no effect, because +the standard calling sequence automatically handles the frame pointer +and nothing is saved by pretending it doesn't exist. The +machine-description macro @code{FRAME_POINTER_REQUIRED} controls +whether a target machine supports this flag. @xref{Registers,,Register +Usage, gccint, GNU Compiler Collection (GCC) Internals}. -The following options control the dump verbosity: +The default setting (when not optimizing for +size) for 32-bit GNU/Linux x86 and 32-bit Darwin x86 targets is +@option{-fomit-frame-pointer}. You can configure GCC with the +@option{--enable-frame-pointer} configure option to change the default. -@table @samp -@item optimized -Print information when an optimization is successfully applied. It is -up to a pass to decide which information is relevant. For example, the -vectorizer passes print the source location of loops which are -successfully vectorized. -@item missed -Print information about missed optimizations. Individual passes -control which information to include in the output. -@item note -Print verbose information about optimizations, such as certain -transformations, more detailed messages about decisions etc. -@item all -Print detailed optimization information. This includes -@samp{optimized}, @samp{missed}, and @samp{note}. -@end table +Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. -One or more of the following option keywords can be used to describe a -group of optimizations: +@item -foptimize-sibling-calls +@opindex foptimize-sibling-calls +Optimize sibling and tail recursive calls. -@table @samp -@item ipa -Enable dumps from all interprocedural optimizations. -@item loop -Enable dumps from all loop optimizations. -@item inline -Enable dumps from all inlining optimizations. -@item vec -Enable dumps from all vectorization optimizations. -@item optall -Enable dumps from all optimizations. This is a superset of -the optimization groups listed above. -@end table +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. -If @var{options} is -omitted, it defaults to @samp{optimized-optall}, which means to dump all -info about successful optimizations from all the passes. +@item -foptimize-strlen +@opindex foptimize-strlen +Optimize various standard C string functions (e.g. @code{strlen}, +@code{strchr} or @code{strcpy}) and +their @code{_FORTIFY_SOURCE} counterparts into faster alternatives. -If the @var{filename} is provided, then the dumps from all the -applicable optimizations are concatenated into the @var{filename}. -Otherwise the dump is output onto @file{stderr}. Though multiple -@option{-fopt-info} options are accepted, only one of them can include -a @var{filename}. If other filenames are provided then all but the -first such option are ignored. +Enabled at levels @option{-O2}, @option{-O3}. -Note that the output @var{filename} is overwritten -in case of multiple translation units. If a combined output from -multiple translation units is desired, @file{stderr} should be used -instead. +@item -fno-inline +@opindex fno-inline +Do not expand any functions inline apart from those marked with +the @code{always_inline} attribute. This is the default when not +optimizing. -In the following example, the optimization info is output to -@file{stderr}: +Single functions can be exempted from inlining by marking them +with the @code{noinline} attribute. -@smallexample -gcc -O3 -fopt-info -@end smallexample +@item -finline-small-functions +@opindex finline-small-functions +Integrate functions into their callers when their body is smaller than expected +function call code (so overall size of program gets smaller). The compiler +heuristically decides which functions are simple enough to be worth integrating +in this way. This inlining applies to all functions, even those not declared +inline. -This example: -@smallexample -gcc -O3 -fopt-info-missed=missed.all -@end smallexample +Enabled at level @option{-O2}. -@noindent -outputs missed optimization report from all the passes into -@file{missed.all}, and this one: +@item -findirect-inlining +@opindex findirect-inlining +Inline also indirect calls that are discovered to be known at compile +time thanks to previous inlining. This option has any effect only +when inlining itself is turned on by the @option{-finline-functions} +or @option{-finline-small-functions} options. -@smallexample -gcc -O2 -ftree-vectorize -fopt-info-vec-missed -@end smallexample +Enabled at level @option{-O2}. -@noindent -prints information about missed optimization opportunities from -vectorization passes on @file{stderr}. -Note that @option{-fopt-info-vec-missed} is equivalent to -@option{-fopt-info-missed-vec}. +@item -finline-functions +@opindex finline-functions +Consider all functions for inlining, even if they are not declared inline. +The compiler heuristically decides which functions are worth integrating +in this way. -As another example, -@smallexample -gcc -O3 -fopt-info-inline-optimized-missed=inline.txt -@end smallexample +If all calls to a given function are integrated, and the function is +declared @code{static}, then the function is normally not output as +assembler code in its own right. -@noindent -outputs information about missed optimizations as well as -optimized locations from all the inlining passes into -@file{inline.txt}. +Enabled at level @option{-O3}. -Finally, consider: +@item -finline-functions-called-once +@opindex finline-functions-called-once +Consider all @code{static} functions called once for inlining into their +caller even if they are not marked @code{inline}. If a call to a given +function is integrated, then the function is not output as assembler code +in its own right. -@smallexample -gcc -fopt-info-vec-missed=vec.miss -fopt-info-loop-optimized=loop.opt -@end smallexample +Enabled at levels @option{-O1}, @option{-O2}, @option{-O3} and @option{-Os}. -@noindent -Here the two output filenames @file{vec.miss} and @file{loop.opt} are -in conflict since only one output file is allowed. In this case, only -the first option takes effect and the subsequent options are -ignored. Thus only @file{vec.miss} is produced which contains -dumps from the vectorizer about missed opportunities. +@item -fearly-inlining +@opindex fearly-inlining +Inline functions marked by @code{always_inline} and functions whose body seems +smaller than the function call overhead early before doing +@option{-fprofile-generate} instrumentation and real inlining pass. Doing so +makes profiling significantly cheaper and usually inlining faster on programs +having large chains of nested wrapper functions. -@item -frandom-seed=@var{string} -@opindex frandom-seed -This option provides a seed that GCC uses in place of -random numbers in generating certain symbol names -that have to be different in every compiled file. It is also used to -place unique stamps in coverage data files and the object files that -produce them. You can use the @option{-frandom-seed} option to produce -reproducibly identical object files. +Enabled by default. -The @var{string} can either be a number (decimal, octal or hex) or an -arbitrary string (in which case it's converted to a number by -computing CRC32). +@item -fipa-sra +@opindex fipa-sra +Perform interprocedural scalar replacement of aggregates, removal of +unused parameters and replacement of parameters passed by reference +by parameters passed by value. -The @var{string} should be different for every file you compile. +Enabled at levels @option{-O2}, @option{-O3} and @option{-Os}. -@item -fsched-verbose=@var{n} -@opindex fsched-verbose -On targets that use instruction scheduling, this option controls the -amount of debugging output the scheduler prints to the dump files. +@item -finline-limit=@var{n} +@opindex finline-limit +By default, GCC limits the size of functions that can be inlined. This flag +allows coarse control of this limit. @var{n} is the size of functions that +can be inlined in number of pseudo instructions. -For @var{n} greater than zero, @option{-fsched-verbose} outputs the -same information as @option{-fdump-rtl-sched1} and @option{-fdump-rtl-sched2}. -For @var{n} greater than one, it also output basic block probabilities, -detailed ready list information and unit/insn info. For @var{n} greater -than two, it includes RTL at abort point, control-flow and regions info. -And for @var{n} over four, @option{-fsched-verbose} also includes -dependence info. +Inlining is actually controlled by a number of parameters, which may be +specified individually by using @option{--param @var{name}=@var{value}}. +The @option{-finline-limit=@var{n}} option sets some of these parameters +as follows: -@item -save-temps -@itemx -save-temps=cwd -@opindex save-temps -Store the usual ``temporary'' intermediate files permanently; place them -in the current directory and name them based on the source file. Thus, -compiling @file{foo.c} with @option{-c -save-temps} produces files -@file{foo.i} and @file{foo.s}, as well as @file{foo.o}. This creates a -preprocessed @file{foo.i} output file even though the compiler now -normally uses an integrated preprocessor. +@table @gcctabopt +@item max-inline-insns-single +is set to @var{n}/2. +@item max-inline-insns-auto +is set to @var{n}/2. +@end table -When used in combination with the @option{-x} command-line option, -@option{-save-temps} is sensible enough to avoid over writing an -input source file with the same extension as an intermediate file. -The corresponding intermediate file may be obtained by renaming the -source file before using @option{-save-temps}. +See below for a documentation of the individual +parameters controlling inlining and for the defaults of these parameters. -If you invoke GCC in parallel, compiling several different source -files that share a common base name in different subdirectories or the -same source file compiled for multiple output destinations, it is -likely that the different parallel compilers will interfere with each -other, and overwrite the temporary files. For instance: +@emph{Note:} there may be no value to @option{-finline-limit} that results +in default behavior. -@smallexample -gcc -save-temps -o outdir1/foo.o indir1/foo.c& -gcc -save-temps -o outdir2/foo.o indir2/foo.c& -@end smallexample +@emph{Note:} pseudo instruction represents, in this particular context, an +abstract measurement of function's size. In no way does it represent a count +of assembly instructions and as such its exact meaning might change from one +release to an another. -may result in @file{foo.i} and @file{foo.o} being written to -simultaneously by both compilers. +@item -fno-keep-inline-dllexport +@opindex fno-keep-inline-dllexport +This is a more fine-grained version of @option{-fkeep-inline-functions}, +which applies only to functions that are declared using the @code{dllexport} +attribute or declspec (@xref{Function Attributes,,Declaring Attributes of +Functions}.) -@item -save-temps=obj -@opindex save-temps=obj -Store the usual ``temporary'' intermediate files permanently. If the -@option{-o} option is used, the temporary files are based on the -object file. If the @option{-o} option is not used, the -@option{-save-temps=obj} switch behaves like @option{-save-temps}. +@item -fkeep-inline-functions +@opindex fkeep-inline-functions +In C, emit @code{static} functions that are declared @code{inline} +into the object file, even if the function has been inlined into all +of its callers. This switch does not affect functions using the +@code{extern inline} extension in GNU C90@. In C++, emit any and all +inline functions into the object file. -For example: +@item -fkeep-static-functions +@opindex fkeep-static-functions +Emit @code{static} functions into the object file, even if the function +is never used. -@smallexample -gcc -save-temps=obj -c foo.c -gcc -save-temps=obj -c bar.c -o dir/xbar.o -gcc -save-temps=obj foobar.c -o dir2/yfoobar -@end smallexample +@item -fkeep-static-consts +@opindex fkeep-static-consts +Emit variables declared @code{static const} when optimization isn't turned +on, even if the variables aren't referenced. -@noindent -creates @file{foo.i}, @file{foo.s}, @file{dir/xbar.i}, -@file{dir/xbar.s}, @file{dir2/yfoobar.i}, @file{dir2/yfoobar.s}, and -@file{dir2/yfoobar.o}. +GCC enables this option by default. If you want to force the compiler to +check if a variable is referenced, regardless of whether or not +optimization is turned on, use the @option{-fno-keep-static-consts} option. -@item -time@r{[}=@var{file}@r{]} -@opindex time -Report the CPU time taken by each subprocess in the compilation -sequence. For C source files, this is the compiler proper and assembler -(plus the linker if linking is done). +@item -fmerge-constants +@opindex fmerge-constants +Attempt to merge identical constants (string constants and floating-point +constants) across compilation units. -Without the specification of an output file, the output looks like this: +This option is the default for optimized compilation if the assembler and +linker support it. Use @option{-fno-merge-constants} to inhibit this +behavior. -@smallexample -# cc1 0.12 0.01 -# as 0.00 0.01 -@end smallexample +Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. -The first number on each line is the ``user time'', that is time spent -executing the program itself. The second number is ``system time'', -time spent executing operating system routines on behalf of the program. -Both numbers are in seconds. +@item -fmerge-all-constants +@opindex fmerge-all-constants +Attempt to merge identical constants and identical variables. -With the specification of an output file, the output is appended to the -named file, and it looks like this: +This option implies @option{-fmerge-constants}. In addition to +@option{-fmerge-constants} this considers e.g.@: even constant initialized +arrays or initialized constant variables with integral or floating-point +types. Languages like C or C++ require each variable, including multiple +instances of the same variable in recursive calls, to have distinct locations, +so using this option results in non-conforming +behavior. -@smallexample -0.12 0.01 cc1 @var{options} -0.00 0.01 as @var{options} -@end smallexample +@item -fmodulo-sched +@opindex fmodulo-sched +Perform swing modulo scheduling immediately before the first scheduling +pass. This pass looks at innermost loops and reorders their +instructions by overlapping different iterations. -The ``user time'' and the ``system time'' are moved before the program -name, and the options passed to the program are displayed, so that one -can later tell what file was being compiled, and with which options. +@item -fmodulo-sched-allow-regmoves +@opindex fmodulo-sched-allow-regmoves +Perform more aggressive SMS-based modulo scheduling with register moves +allowed. By setting this flag certain anti-dependences edges are +deleted, which triggers the generation of reg-moves based on the +life-range analysis. This option is effective only with +@option{-fmodulo-sched} enabled. -@item -fvar-tracking -@opindex fvar-tracking -Run variable tracking pass. It computes where variables are stored at each -position in code. Better debugging information is then generated -(if the debugging information format supports this information). +@item -fno-branch-count-reg +@opindex fno-branch-count-reg +Do not use ``decrement and branch'' instructions on a count register, +but instead generate a sequence of instructions that decrement a +register, compare it against zero, then branch based upon the result. +This option is only meaningful on architectures that support such +instructions, which include x86, PowerPC, IA-64 and S/390. -It is enabled by default when compiling with optimization (@option{-Os}, -@option{-O}, @option{-O2}, @dots{}), debugging information (@option{-g}) and -the debug info format supports it. +Enabled by default at @option{-O1} and higher. -@item -fvar-tracking-assignments -@opindex fvar-tracking-assignments -@opindex fno-var-tracking-assignments -Annotate assignments to user variables early in the compilation and -attempt to carry the annotations over throughout the compilation all the -way to the end, in an attempt to improve debug information while -optimizing. Use of @option{-gdwarf-4} is recommended along with it. +The default is @option{-fbranch-count-reg}. -It can be enabled even if var-tracking is disabled, in which case -annotations are created and maintained, but discarded at the end. -By default, this flag is enabled together with @option{-fvar-tracking}, -except when selective scheduling is enabled. +@item -fno-function-cse +@opindex fno-function-cse +Do not put function addresses in registers; make each instruction that +calls a constant function contain the function's address explicitly. -@item -fvar-tracking-assignments-toggle -@opindex fvar-tracking-assignments-toggle -@opindex fno-var-tracking-assignments-toggle -Toggle @option{-fvar-tracking-assignments}, in the same way that -@option{-gtoggle} toggles @option{-g}. +This option results in less efficient code, but some strange hacks +that alter the assembler output may be confused by the optimizations +performed when this option is not used. -@item -print-file-name=@var{library} -@opindex print-file-name -Print the full absolute name of the library file @var{library} that -would be used when linking---and don't do anything else. With this -option, GCC does not compile or link anything; it just prints the -file name. +The default is @option{-ffunction-cse} -@item -print-multi-directory -@opindex print-multi-directory -Print the directory name corresponding to the multilib selected by any -other switches present in the command line. This directory is supposed -to exist in @env{GCC_EXEC_PREFIX}. +@item -fno-zero-initialized-in-bss +@opindex fno-zero-initialized-in-bss +If the target supports a BSS section, GCC by default puts variables that +are initialized to zero into BSS@. This can save space in the resulting +code. -@item -print-multi-lib -@opindex print-multi-lib -Print the mapping from multilib directory names to compiler switches -that enable them. The directory name is separated from the switches by -@samp{;}, and each switch starts with an @samp{@@} instead of the -@samp{-}, without spaces between multiple switches. This is supposed to -ease shell processing. +This option turns off this behavior because some programs explicitly +rely on variables going to the data section---e.g., so that the +resulting executable can find the beginning of that section and/or make +assumptions based on that. -@item -print-multi-os-directory -@opindex print-multi-os-directory -Print the path to OS libraries for the selected -multilib, relative to some @file{lib} subdirectory. If OS libraries are -present in the @file{lib} subdirectory and no multilibs are used, this is -usually just @file{.}, if OS libraries are present in @file{lib@var{suffix}} -sibling directories this prints e.g.@: @file{../lib64}, @file{../lib} or -@file{../lib32}, or if OS libraries are present in @file{lib/@var{subdir}} -subdirectories it prints e.g.@: @file{amd64}, @file{sparcv9} or @file{ev6}. +The default is @option{-fzero-initialized-in-bss}. -@item -print-multiarch -@opindex print-multiarch -Print the path to OS libraries for the selected multiarch, -relative to some @file{lib} subdirectory. +@item -fthread-jumps +@opindex fthread-jumps +Perform optimizations that check to see if a jump branches to a +location where another comparison subsumed by the first is found. If +so, the first branch is redirected to either the destination of the +second branch or a point immediately following it, depending on whether +the condition is known to be true or false. -@item -print-prog-name=@var{program} -@opindex print-prog-name -Like @option{-print-file-name}, but searches for a program such as @command{cpp}. +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. -@item -print-libgcc-file-name -@opindex print-libgcc-file-name -Same as @option{-print-file-name=libgcc.a}. +@item -fsplit-wide-types +@opindex fsplit-wide-types +When using a type that occupies multiple registers, such as @code{long +long} on a 32-bit system, split the registers apart and allocate them +independently. This normally generates better code for those types, +but may make debugging more difficult. -This is useful when you use @option{-nostdlib} or @option{-nodefaultlibs} -but you do want to link with @file{libgcc.a}. You can do: +Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, +@option{-Os}. -@smallexample -gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name` -@end smallexample +@item -fcse-follow-jumps +@opindex fcse-follow-jumps +In common subexpression elimination (CSE), scan through jump instructions +when the target of the jump is not reached by any other path. For +example, when CSE encounters an @code{if} statement with an +@code{else} clause, CSE follows the jump when the condition +tested is false. -@item -print-search-dirs -@opindex print-search-dirs -Print the name of the configured installation directory and a list of -program and library directories @command{gcc} searches---and don't do anything else. +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. -This is useful when @command{gcc} prints the error message -@samp{installation problem, cannot exec cpp0: No such file or directory}. -To resolve this you either need to put @file{cpp0} and the other compiler -components where @command{gcc} expects to find them, or you can set the environment -variable @env{GCC_EXEC_PREFIX} to the directory where you installed them. -Don't forget the trailing @samp{/}. -@xref{Environment Variables}. +@item -fcse-skip-blocks +@opindex fcse-skip-blocks +This is similar to @option{-fcse-follow-jumps}, but causes CSE to +follow jumps that conditionally skip over blocks. When CSE +encounters a simple @code{if} statement with no else clause, +@option{-fcse-skip-blocks} causes CSE to follow the jump around the +body of the @code{if}. -@item -print-sysroot -@opindex print-sysroot -Print the target sysroot directory that is used during -compilation. This is the target sysroot specified either at configure -time or using the @option{--sysroot} option, possibly with an extra -suffix that depends on compilation options. If no target sysroot is -specified, the option prints nothing. +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. -@item -print-sysroot-headers-suffix -@opindex print-sysroot-headers-suffix -Print the suffix added to the target sysroot when searching for -headers, or give an error if the compiler is not configured with such -a suffix---and don't do anything else. +@item -frerun-cse-after-loop +@opindex frerun-cse-after-loop +Re-run common subexpression elimination after loop optimizations are +performed. -@item -dumpmachine -@opindex dumpmachine -Print the compiler's target machine (for example, -@samp{i686-pc-linux-gnu})---and don't do anything else. +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. -@item -dumpversion -@opindex dumpversion -Print the compiler version (for example, @code{3.0})---and don't do -anything else. +@item -fgcse +@opindex fgcse +Perform a global common subexpression elimination pass. +This pass also performs global constant and copy propagation. -@item -dumpspecs -@opindex dumpspecs -Print the compiler's built-in specs---and don't do anything else. (This -is used when GCC itself is being built.) @xref{Spec Files}. +@emph{Note:} When compiling a program using computed gotos, a GCC +extension, you may get better run-time performance if you disable +the global common subexpression elimination pass by adding +@option{-fno-gcse} to the command line. -@item -fno-eliminate-unused-debug-types -@opindex feliminate-unused-debug-types -@opindex fno-eliminate-unused-debug-types -Normally, when producing DWARF 2 output, GCC avoids producing debug symbol -output for types that are nowhere used in the source file being compiled. -Sometimes it is useful to have GCC emit debugging -information for all types declared in a compilation -unit, regardless of whether or not they are actually used -in that compilation unit, for example -if, in the debugger, you want to cast a value to a type that is -not actually used in your program (but is declared). More often, -however, this results in a significant amount of wasted space. -@end table +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. + +@item -fgcse-lm +@opindex fgcse-lm +When @option{-fgcse-lm} is enabled, global common subexpression elimination +attempts to move loads that are only killed by stores into themselves. This +allows a loop containing a load/store sequence to be changed to a load outside +the loop, and a copy/store within the loop. -@node Optimize Options -@section Options That Control Optimization -@cindex optimize options -@cindex options, optimization +Enabled by default when @option{-fgcse} is enabled. -These options control various sorts of optimizations. +@item -fgcse-sm +@opindex fgcse-sm +When @option{-fgcse-sm} is enabled, a store motion pass is run after +global common subexpression elimination. This pass attempts to move +stores out of loops. When used in conjunction with @option{-fgcse-lm}, +loops containing a load/store sequence can be changed to a load before +the loop and a store after the loop. -Without any optimization option, the compiler's goal is to reduce the -cost of compilation and to make debugging produce the expected -results. Statements are independent: if you stop the program with a -breakpoint between statements, you can then assign a new value to any -variable or change the program counter to any other statement in the -function and get exactly the results you expect from the source -code. +Not enabled at any optimization level. -Turning on optimization flags makes the compiler attempt to improve -the performance and/or code size at the expense of compilation time -and possibly the ability to debug the program. +@item -fgcse-las +@opindex fgcse-las +When @option{-fgcse-las} is enabled, the global common subexpression +elimination pass eliminates redundant loads that come after stores to the +same memory location (both partial and full redundancies). -The compiler performs optimization based on the knowledge it has of the -program. Compiling multiple files at once to a single output file mode allows -the compiler to use information gained from all of the files when compiling -each of them. +Not enabled at any optimization level. -Not all optimizations are controlled directly by a flag. Only -optimizations that have a flag are listed in this section. +@item -fgcse-after-reload +@opindex fgcse-after-reload +When @option{-fgcse-after-reload} is enabled, a redundant load elimination +pass is performed after reload. The purpose of this pass is to clean up +redundant spilling. -Most optimizations are only enabled if an @option{-O} level is set on -the command line. Otherwise they are disabled, even if individual -optimization flags are specified. +@item -faggressive-loop-optimizations +@opindex faggressive-loop-optimizations +This option tells the loop optimizer to use language constraints to +derive bounds for the number of iterations of a loop. This assumes that +loop code does not invoke undefined behavior by for example causing signed +integer overflows or out-of-bound array accesses. The bounds for the +number of iterations of a loop are used to guide loop unrolling and peeling +and loop exit test optimizations. +This option is enabled by default. -Depending on the target and how GCC was configured, a slightly different -set of optimizations may be enabled at each @option{-O} level than -those listed here. You can invoke GCC with @option{-Q --help=optimizers} -to find out the exact set of optimizations that are enabled at each level. -@xref{Overall Options}, for examples. +@item -funsafe-loop-optimizations +@opindex funsafe-loop-optimizations +This option tells the loop optimizer to assume that loop indices do not +overflow, and that loops with nontrivial exit condition are not +infinite. This enables a wider range of loop optimizations even if +the loop optimizer itself cannot prove that these assumptions are valid. +If you use @option{-Wunsafe-loop-optimizations}, the compiler warns you +if it finds this kind of loop. -@table @gcctabopt -@item -O -@itemx -O1 -@opindex O -@opindex O1 -Optimize. Optimizing compilation takes somewhat more time, and a lot -more memory for a large function. +@item -fcrossjumping +@opindex fcrossjumping +Perform cross-jumping transformation. +This transformation unifies equivalent code and saves code size. The +resulting code may or may not perform better than without cross-jumping. -With @option{-O}, the compiler tries to reduce code size and execution -time, without performing any optimizations that take a great deal of -compilation time. +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. -@option{-O} turns on the following optimization flags: -@gccoptlist{ --fauto-inc-dec @gol --fbranch-count-reg @gol --fcombine-stack-adjustments @gol --fcompare-elim @gol --fcprop-registers @gol --fdce @gol --fdefer-pop @gol --fdelayed-branch @gol --fdse @gol --fforward-propagate @gol --fguess-branch-probability @gol --fif-conversion2 @gol --fif-conversion @gol --finline-functions-called-once @gol --fipa-pure-const @gol --fipa-profile @gol --fipa-reference @gol --fmerge-constants @gol --fmove-loop-invariants @gol --freorder-blocks @gol --fshrink-wrap @gol --fsplit-wide-types @gol --fssa-backprop @gol --fssa-phiopt @gol --ftree-bit-ccp @gol --ftree-ccp @gol --ftree-ch @gol --ftree-coalesce-vars @gol --ftree-copy-prop @gol --ftree-dce @gol --ftree-dominator-opts @gol --ftree-dse @gol --ftree-forwprop @gol --ftree-fre @gol --ftree-phiprop @gol --ftree-sink @gol --ftree-slsr @gol --ftree-sra @gol --ftree-pta @gol --ftree-ter @gol --funit-at-a-time} +@item -fauto-inc-dec +@opindex fauto-inc-dec +Combine increments or decrements of addresses with memory accesses. +This pass is always skipped on architectures that do not have +instructions to support this. Enabled by default at @option{-O} and +higher on architectures that support this. -@option{-O} also turns on @option{-fomit-frame-pointer} on machines -where doing so does not interfere with debugging. +@item -fdce +@opindex fdce +Perform dead code elimination (DCE) on RTL@. +Enabled by default at @option{-O} and higher. -@item -O2 -@opindex O2 -Optimize even more. GCC performs nearly all supported optimizations -that do not involve a space-speed tradeoff. -As compared to @option{-O}, this option increases both compilation time -and the performance of the generated code. +@item -fdse +@opindex fdse +Perform dead store elimination (DSE) on RTL@. +Enabled by default at @option{-O} and higher. -@option{-O2} turns on all optimization flags specified by @option{-O}. It -also turns on the following optimization flags: -@gccoptlist{-fthread-jumps @gol --falign-functions -falign-jumps @gol --falign-loops -falign-labels @gol --fcaller-saves @gol --fcrossjumping @gol --fcse-follow-jumps -fcse-skip-blocks @gol --fdelete-null-pointer-checks @gol --fdevirtualize -fdevirtualize-speculatively @gol --fexpensive-optimizations @gol --fgcse -fgcse-lm @gol --fhoist-adjacent-loads @gol --finline-small-functions @gol --findirect-inlining @gol --fipa-cp @gol --fipa-cp-alignment @gol --fipa-sra @gol --fipa-icf @gol --fisolate-erroneous-paths-dereference @gol --flra-remat @gol --foptimize-sibling-calls @gol --foptimize-strlen @gol --fpartial-inlining @gol --fpeephole2 @gol --freorder-blocks-algorithm=stc @gol --freorder-blocks-and-partition -freorder-functions @gol --frerun-cse-after-loop @gol --fsched-interblock -fsched-spec @gol --fschedule-insns -fschedule-insns2 @gol --fstrict-aliasing -fstrict-overflow @gol --ftree-builtin-call-dce @gol --ftree-switch-conversion -ftree-tail-merge @gol --ftree-pre @gol --ftree-vrp @gol --fipa-ra} +@item -fif-conversion +@opindex fif-conversion +Attempt to transform conditional jumps into branch-less equivalents. This +includes use of conditional moves, min, max, set flags and abs instructions, and +some tricks doable by standard arithmetics. The use of conditional execution +on chips where it is available is controlled by @option{-fif-conversion2}. -Please note the warning under @option{-fgcse} about -invoking @option{-O2} on programs that use computed gotos. +Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. -@item -O3 -@opindex O3 -Optimize yet more. @option{-O3} turns on all optimizations specified -by @option{-O2} and also turns on the @option{-finline-functions}, -@option{-funswitch-loops}, @option{-fpredictive-commoning}, -@option{-fgcse-after-reload}, @option{-ftree-loop-vectorize}, -@option{-ftree-loop-distribute-patterns}, @option{-fsplit-paths} -@option{-ftree-slp-vectorize}, @option{-fvect-cost-model}, -@option{-ftree-partial-pre} and @option{-fipa-cp-clone} options. +@item -fif-conversion2 +@opindex fif-conversion2 +Use conditional execution (where available) to transform conditional jumps into +branch-less equivalents. -@item -O0 -@opindex O0 -Reduce compilation time and make debugging produce the expected -results. This is the default. +Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. -@item -Os -@opindex Os -Optimize for size. @option{-Os} enables all @option{-O2} optimizations that -do not typically increase code size. It also performs further -optimizations designed to reduce code size. +@item -fdeclone-ctor-dtor +@opindex fdeclone-ctor-dtor +The C++ ABI requires multiple entry points for constructors and +destructors: one for a base subobject, one for a complete object, and +one for a virtual destructor that calls operator delete afterwards. +For a hierarchy with virtual bases, the base and complete variants are +clones, which means two copies of the function. With this option, the +base and complete variants are changed to be thunks that call a common +implementation. -@option{-Os} disables the following optimization flags: -@gccoptlist{-falign-functions -falign-jumps -falign-loops @gol --falign-labels -freorder-blocks -freorder-blocks-algorithm=stc @gol --freorder-blocks-and-partition -fprefetch-loop-arrays} +Enabled by @option{-Os}. -@item -Ofast -@opindex Ofast -Disregard strict standards compliance. @option{-Ofast} enables all -@option{-O3} optimizations. It also enables optimizations that are not -valid for all standard-compliant programs. -It turns on @option{-ffast-math} and the Fortran-specific -@option{-fno-protect-parens} and @option{-fstack-arrays}. +@item -fdelete-null-pointer-checks +@opindex fdelete-null-pointer-checks +Assume that programs cannot safely dereference null pointers, and that +no code or data element resides at address zero. +This option enables simple constant +folding optimizations at all optimization levels. In addition, other +optimization passes in GCC use this flag to control global dataflow +analyses that eliminate useless checks for null pointers; these assume +that a memory access to address zero always results in a trap, so +that if a pointer is checked after it has already been dereferenced, +it cannot be null. -@item -Og -@opindex Og -Optimize debugging experience. @option{-Og} enables optimizations -that do not interfere with debugging. It should be the optimization -level of choice for the standard edit-compile-debug cycle, offering -a reasonable level of optimization while maintaining fast compilation -and a good debugging experience. -@end table +Note however that in some environments this assumption is not true. +Use @option{-fno-delete-null-pointer-checks} to disable this optimization +for programs that depend on that behavior. -If you use multiple @option{-O} options, with or without level numbers, -the last such option is the one that is effective. +This option is enabled by default on most targets. On Nios II ELF, it +defaults to off. On AVR and CR16, this option is completely disabled. -Options of the form @option{-f@var{flag}} specify machine-independent -flags. Most flags have both positive and negative forms; the negative -form of @option{-ffoo} is @option{-fno-foo}. In the table -below, only one of the forms is listed---the one you typically -use. You can figure out the other form by either removing @samp{no-} -or adding it. +Passes that use the dataflow information +are enabled independently at different optimization levels. -The following options control specific optimizations. They are either -activated by @option{-O} options or are related to ones that are. You -can use the following flags in the rare cases when ``fine-tuning'' of -optimizations to be performed is desired. +@item -fdevirtualize +@opindex fdevirtualize +Attempt to convert calls to virtual functions to direct calls. This +is done both within a procedure and interprocedurally as part of +indirect inlining (@option{-findirect-inlining}) and interprocedural constant +propagation (@option{-fipa-cp}). +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. -@table @gcctabopt -@item -fno-defer-pop -@opindex fno-defer-pop -Always pop the arguments to each function call as soon as that function -returns. For machines that must pop arguments after a function call, -the compiler normally lets arguments accumulate on the stack for several -function calls and pops them all at once. +@item -fdevirtualize-speculatively +@opindex fdevirtualize-speculatively +Attempt to convert calls to virtual functions to speculative direct calls. +Based on the analysis of the type inheritance graph, determine for a given call +the set of likely targets. If the set is small, preferably of size 1, change +the call into a conditional deciding between direct and indirect calls. The +speculative calls enable more optimizations, such as inlining. When they seem +useless after further optimization, they are converted back into original form. -Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. +@item -fdevirtualize-at-ltrans +@opindex fdevirtualize-at-ltrans +Stream extra information needed for aggressive devirtualization when running +the link-time optimizer in local transformation mode. +This option enables more devirtualization but +significantly increases the size of streamed data. For this reason it is +disabled by default. -@item -fforward-propagate -@opindex fforward-propagate -Perform a forward propagation pass on RTL@. The pass tries to combine two -instructions and checks if the result can be simplified. If loop unrolling -is active, two passes are performed and the second is scheduled after -loop unrolling. +@item -fexpensive-optimizations +@opindex fexpensive-optimizations +Perform a number of minor optimizations that are relatively expensive. -This option is enabled by default at optimization levels @option{-O}, -@option{-O2}, @option{-O3}, @option{-Os}. +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. -@item -ffp-contract=@var{style} -@opindex ffp-contract -@option{-ffp-contract=off} disables floating-point expression contraction. -@option{-ffp-contract=fast} enables floating-point expression contraction -such as forming of fused multiply-add operations if the target has -native support for them. -@option{-ffp-contract=on} enables floating-point expression contraction -if allowed by the language standard. This is currently not implemented -and treated equal to @option{-ffp-contract=off}. +@item -free +@opindex free +Attempt to remove redundant extension instructions. This is especially +helpful for the x86-64 architecture, which implicitly zero-extends in 64-bit +registers after writing to their lower 32-bit half. -The default is @option{-ffp-contract=fast}. +Enabled for Alpha, AArch64 and x86 at levels @option{-O2}, +@option{-O3}, @option{-Os}. -@item -fomit-frame-pointer -@opindex fomit-frame-pointer -Don't keep the frame pointer in a register for functions that -don't need one. This avoids the instructions to save, set up and -restore frame pointers; it also makes an extra register available -in many functions. @strong{It also makes debugging impossible on -some machines.} +@item -fno-lifetime-dse +@opindex fno-lifetime-dse +In C++ the value of an object is only affected by changes within its +lifetime: when the constructor begins, the object has an indeterminate +value, and any changes during the lifetime of the object are dead when +the object is destroyed. Normally dead store elimination will take +advantage of this; if your code relies on the value of the object +storage persisting beyond the lifetime of the object, you can use this +flag to disable this optimization. -On some machines, such as the VAX, this flag has no effect, because -the standard calling sequence automatically handles the frame pointer -and nothing is saved by pretending it doesn't exist. The -machine-description macro @code{FRAME_POINTER_REQUIRED} controls -whether a target machine supports this flag. @xref{Registers,,Register -Usage, gccint, GNU Compiler Collection (GCC) Internals}. +@item -flive-range-shrinkage +@opindex flive-range-shrinkage +Attempt to decrease register pressure through register live range +shrinkage. This is helpful for fast processors with small or moderate +size register sets. -The default setting (when not optimizing for -size) for 32-bit GNU/Linux x86 and 32-bit Darwin x86 targets is -@option{-fomit-frame-pointer}. You can configure GCC with the -@option{--enable-frame-pointer} configure option to change the default. +@item -fira-algorithm=@var{algorithm} +@opindex fira-algorithm +Use the specified coloring algorithm for the integrated register +allocator. The @var{algorithm} argument can be @samp{priority}, which +specifies Chow's priority coloring, or @samp{CB}, which specifies +Chaitin-Briggs coloring. Chaitin-Briggs coloring is not implemented +for all architectures, but for those targets that do support it, it is +the default because it generates better code. -Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. +@item -fira-region=@var{region} +@opindex fira-region +Use specified regions for the integrated register allocator. The +@var{region} argument should be one of the following: -@item -foptimize-sibling-calls -@opindex foptimize-sibling-calls -Optimize sibling and tail recursive calls. +@table @samp -Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. +@item all +Use all loops as register allocation regions. +This can give the best results for machines with a small and/or +irregular register set. -@item -foptimize-strlen -@opindex foptimize-strlen -Optimize various standard C string functions (e.g. @code{strlen}, -@code{strchr} or @code{strcpy}) and -their @code{_FORTIFY_SOURCE} counterparts into faster alternatives. +@item mixed +Use all loops except for loops with small register pressure +as the regions. This value usually gives +the best results in most cases and for most architectures, +and is enabled by default when compiling with optimization for speed +(@option{-O}, @option{-O2}, @dots{}). -Enabled at levels @option{-O2}, @option{-O3}. +@item one +Use all functions as a single region. +This typically results in the smallest code size, and is enabled by default for +@option{-Os} or @option{-O0}. -@item -fno-inline -@opindex fno-inline -Do not expand any functions inline apart from those marked with -the @code{always_inline} attribute. This is the default when not -optimizing. +@end table -Single functions can be exempted from inlining by marking them -with the @code{noinline} attribute. +@item -fira-hoist-pressure +@opindex fira-hoist-pressure +Use IRA to evaluate register pressure in the code hoisting pass for +decisions to hoist expressions. This option usually results in smaller +code, but it can slow the compiler down. -@item -finline-small-functions -@opindex finline-small-functions -Integrate functions into their callers when their body is smaller than expected -function call code (so overall size of program gets smaller). The compiler -heuristically decides which functions are simple enough to be worth integrating -in this way. This inlining applies to all functions, even those not declared -inline. +This option is enabled at level @option{-Os} for all targets. -Enabled at level @option{-O2}. +@item -fira-loop-pressure +@opindex fira-loop-pressure +Use IRA to evaluate register pressure in loops for decisions to move +loop invariants. This option usually results in generation +of faster and smaller code on machines with large register files (>= 32 +registers), but it can slow the compiler down. -@item -findirect-inlining -@opindex findirect-inlining -Inline also indirect calls that are discovered to be known at compile -time thanks to previous inlining. This option has any effect only -when inlining itself is turned on by the @option{-finline-functions} -or @option{-finline-small-functions} options. +This option is enabled at level @option{-O3} for some targets. -Enabled at level @option{-O2}. +@item -fno-ira-share-save-slots +@opindex fno-ira-share-save-slots +Disable sharing of stack slots used for saving call-used hard +registers living through a call. Each hard register gets a +separate stack slot, and as a result function stack frames are +larger. -@item -finline-functions -@opindex finline-functions -Consider all functions for inlining, even if they are not declared inline. -The compiler heuristically decides which functions are worth integrating -in this way. +@item -fno-ira-share-spill-slots +@opindex fno-ira-share-spill-slots +Disable sharing of stack slots allocated for pseudo-registers. Each +pseudo-register that does not get a hard register gets a separate +stack slot, and as a result function stack frames are larger. -If all calls to a given function are integrated, and the function is -declared @code{static}, then the function is normally not output as -assembler code in its own right. +@item -fira-verbose=@var{n} +@opindex fira-verbose +Control the verbosity of the dump file for the integrated register allocator. +The default value is 5. If the value @var{n} is greater or equal to 10, +the dump output is sent to stderr using the same format as @var{n} minus 10. -Enabled at level @option{-O3}. +@item -flra-remat +@opindex flra-remat +Enable CFG-sensitive rematerialization in LRA. Instead of loading +values of spilled pseudos, LRA tries to rematerialize (recalculate) +values if it is profitable. -@item -finline-functions-called-once -@opindex finline-functions-called-once -Consider all @code{static} functions called once for inlining into their -caller even if they are not marked @code{inline}. If a call to a given -function is integrated, then the function is not output as assembler code -in its own right. +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. -Enabled at levels @option{-O1}, @option{-O2}, @option{-O3} and @option{-Os}. +@item -fdelayed-branch +@opindex fdelayed-branch +If supported for the target machine, attempt to reorder instructions +to exploit instruction slots available after delayed branch +instructions. -@item -fearly-inlining -@opindex fearly-inlining -Inline functions marked by @code{always_inline} and functions whose body seems -smaller than the function call overhead early before doing -@option{-fprofile-generate} instrumentation and real inlining pass. Doing so -makes profiling significantly cheaper and usually inlining faster on programs -having large chains of nested wrapper functions. +Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. -Enabled by default. +@item -fschedule-insns +@opindex fschedule-insns +If supported for the target machine, attempt to reorder instructions to +eliminate execution stalls due to required data being unavailable. This +helps machines that have slow floating point or memory load instructions +by allowing other instructions to be issued until the result of the load +or floating-point instruction is required. -@item -fipa-sra -@opindex fipa-sra -Perform interprocedural scalar replacement of aggregates, removal of -unused parameters and replacement of parameters passed by reference -by parameters passed by value. +Enabled at levels @option{-O2}, @option{-O3}. -Enabled at levels @option{-O2}, @option{-O3} and @option{-Os}. +@item -fschedule-insns2 +@opindex fschedule-insns2 +Similar to @option{-fschedule-insns}, but requests an additional pass of +instruction scheduling after register allocation has been done. This is +especially useful on machines with a relatively small number of +registers and where memory load instructions take more than one cycle. + +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. -@item -finline-limit=@var{n} -@opindex finline-limit -By default, GCC limits the size of functions that can be inlined. This flag -allows coarse control of this limit. @var{n} is the size of functions that -can be inlined in number of pseudo instructions. +@item -fno-sched-interblock +@opindex fno-sched-interblock +Don't schedule instructions across basic blocks. This is normally +enabled by default when scheduling before register allocation, i.e.@: +with @option{-fschedule-insns} or at @option{-O2} or higher. -Inlining is actually controlled by a number of parameters, which may be -specified individually by using @option{--param @var{name}=@var{value}}. -The @option{-finline-limit=@var{n}} option sets some of these parameters -as follows: +@item -fno-sched-spec +@opindex fno-sched-spec +Don't allow speculative motion of non-load instructions. This is normally +enabled by default when scheduling before register allocation, i.e.@: +with @option{-fschedule-insns} or at @option{-O2} or higher. -@table @gcctabopt -@item max-inline-insns-single -is set to @var{n}/2. -@item max-inline-insns-auto -is set to @var{n}/2. -@end table +@item -fsched-pressure +@opindex fsched-pressure +Enable register pressure sensitive insn scheduling before register +allocation. This only makes sense when scheduling before register +allocation is enabled, i.e.@: with @option{-fschedule-insns} or at +@option{-O2} or higher. Usage of this option can improve the +generated code and decrease its size by preventing register pressure +increase above the number of available hard registers and subsequent +spills in register allocation. -See below for a documentation of the individual -parameters controlling inlining and for the defaults of these parameters. +@item -fsched-spec-load +@opindex fsched-spec-load +Allow speculative motion of some load instructions. This only makes +sense when scheduling before register allocation, i.e.@: with +@option{-fschedule-insns} or at @option{-O2} or higher. -@emph{Note:} there may be no value to @option{-finline-limit} that results -in default behavior. +@item -fsched-spec-load-dangerous +@opindex fsched-spec-load-dangerous +Allow speculative motion of more load instructions. This only makes +sense when scheduling before register allocation, i.e.@: with +@option{-fschedule-insns} or at @option{-O2} or higher. -@emph{Note:} pseudo instruction represents, in this particular context, an -abstract measurement of function's size. In no way does it represent a count -of assembly instructions and as such its exact meaning might change from one -release to an another. +@item -fsched-stalled-insns +@itemx -fsched-stalled-insns=@var{n} +@opindex fsched-stalled-insns +Define how many insns (if any) can be moved prematurely from the queue +of stalled insns into the ready list during the second scheduling pass. +@option{-fno-sched-stalled-insns} means that no insns are moved +prematurely, @option{-fsched-stalled-insns=0} means there is no limit +on how many queued insns can be moved prematurely. +@option{-fsched-stalled-insns} without a value is equivalent to +@option{-fsched-stalled-insns=1}. -@item -fno-keep-inline-dllexport -@opindex fno-keep-inline-dllexport -This is a more fine-grained version of @option{-fkeep-inline-functions}, -which applies only to functions that are declared using the @code{dllexport} -attribute or declspec (@xref{Function Attributes,,Declaring Attributes of -Functions}.) +@item -fsched-stalled-insns-dep +@itemx -fsched-stalled-insns-dep=@var{n} +@opindex fsched-stalled-insns-dep +Define how many insn groups (cycles) are examined for a dependency +on a stalled insn that is a candidate for premature removal from the queue +of stalled insns. This has an effect only during the second scheduling pass, +and only if @option{-fsched-stalled-insns} is used. +@option{-fno-sched-stalled-insns-dep} is equivalent to +@option{-fsched-stalled-insns-dep=0}. +@option{-fsched-stalled-insns-dep} without a value is equivalent to +@option{-fsched-stalled-insns-dep=1}. -@item -fkeep-inline-functions -@opindex fkeep-inline-functions -In C, emit @code{static} functions that are declared @code{inline} -into the object file, even if the function has been inlined into all -of its callers. This switch does not affect functions using the -@code{extern inline} extension in GNU C90@. In C++, emit any and all -inline functions into the object file. +@item -fsched2-use-superblocks +@opindex fsched2-use-superblocks +When scheduling after register allocation, use superblock scheduling. +This allows motion across basic block boundaries, +resulting in faster schedules. This option is experimental, as not all machine +descriptions used by GCC model the CPU closely enough to avoid unreliable +results from the algorithm. -@item -fkeep-static-functions -@opindex fkeep-static-functions -Emit @code{static} functions into the object file, even if the function -is never used. +This only makes sense when scheduling after register allocation, i.e.@: with +@option{-fschedule-insns2} or at @option{-O2} or higher. -@item -fkeep-static-consts -@opindex fkeep-static-consts -Emit variables declared @code{static const} when optimization isn't turned -on, even if the variables aren't referenced. +@item -fsched-group-heuristic +@opindex fsched-group-heuristic +Enable the group heuristic in the scheduler. This heuristic favors +the instruction that belongs to a schedule group. This is enabled +by default when scheduling is enabled, i.e.@: with @option{-fschedule-insns} +or @option{-fschedule-insns2} or at @option{-O2} or higher. -GCC enables this option by default. If you want to force the compiler to -check if a variable is referenced, regardless of whether or not -optimization is turned on, use the @option{-fno-keep-static-consts} option. +@item -fsched-critical-path-heuristic +@opindex fsched-critical-path-heuristic +Enable the critical-path heuristic in the scheduler. This heuristic favors +instructions on the critical path. This is enabled by default when +scheduling is enabled, i.e.@: with @option{-fschedule-insns} +or @option{-fschedule-insns2} or at @option{-O2} or higher. -@item -fmerge-constants -@opindex fmerge-constants -Attempt to merge identical constants (string constants and floating-point -constants) across compilation units. +@item -fsched-spec-insn-heuristic +@opindex fsched-spec-insn-heuristic +Enable the speculative instruction heuristic in the scheduler. This +heuristic favors speculative instructions with greater dependency weakness. +This is enabled by default when scheduling is enabled, i.e.@: +with @option{-fschedule-insns} or @option{-fschedule-insns2} +or at @option{-O2} or higher. -This option is the default for optimized compilation if the assembler and -linker support it. Use @option{-fno-merge-constants} to inhibit this -behavior. +@item -fsched-rank-heuristic +@opindex fsched-rank-heuristic +Enable the rank heuristic in the scheduler. This heuristic favors +the instruction belonging to a basic block with greater size or frequency. +This is enabled by default when scheduling is enabled, i.e.@: +with @option{-fschedule-insns} or @option{-fschedule-insns2} or +at @option{-O2} or higher. -Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. +@item -fsched-last-insn-heuristic +@opindex fsched-last-insn-heuristic +Enable the last-instruction heuristic in the scheduler. This heuristic +favors the instruction that is less dependent on the last instruction +scheduled. This is enabled by default when scheduling is enabled, +i.e.@: with @option{-fschedule-insns} or @option{-fschedule-insns2} or +at @option{-O2} or higher. -@item -fmerge-all-constants -@opindex fmerge-all-constants -Attempt to merge identical constants and identical variables. +@item -fsched-dep-count-heuristic +@opindex fsched-dep-count-heuristic +Enable the dependent-count heuristic in the scheduler. This heuristic +favors the instruction that has more instructions depending on it. +This is enabled by default when scheduling is enabled, i.e.@: +with @option{-fschedule-insns} or @option{-fschedule-insns2} or +at @option{-O2} or higher. -This option implies @option{-fmerge-constants}. In addition to -@option{-fmerge-constants} this considers e.g.@: even constant initialized -arrays or initialized constant variables with integral or floating-point -types. Languages like C or C++ require each variable, including multiple -instances of the same variable in recursive calls, to have distinct locations, -so using this option results in non-conforming -behavior. +@item -freschedule-modulo-scheduled-loops +@opindex freschedule-modulo-scheduled-loops +Modulo scheduling is performed before traditional scheduling. If a loop +is modulo scheduled, later scheduling passes may change its schedule. +Use this option to control that behavior. -@item -fmodulo-sched -@opindex fmodulo-sched -Perform swing modulo scheduling immediately before the first scheduling -pass. This pass looks at innermost loops and reorders their -instructions by overlapping different iterations. +@item -fselective-scheduling +@opindex fselective-scheduling +Schedule instructions using selective scheduling algorithm. Selective +scheduling runs instead of the first scheduler pass. -@item -fmodulo-sched-allow-regmoves -@opindex fmodulo-sched-allow-regmoves -Perform more aggressive SMS-based modulo scheduling with register moves -allowed. By setting this flag certain anti-dependences edges are -deleted, which triggers the generation of reg-moves based on the -life-range analysis. This option is effective only with -@option{-fmodulo-sched} enabled. +@item -fselective-scheduling2 +@opindex fselective-scheduling2 +Schedule instructions using selective scheduling algorithm. Selective +scheduling runs instead of the second scheduler pass. -@item -fno-branch-count-reg -@opindex fno-branch-count-reg -Do not use ``decrement and branch'' instructions on a count register, -but instead generate a sequence of instructions that decrement a -register, compare it against zero, then branch based upon the result. -This option is only meaningful on architectures that support such -instructions, which include x86, PowerPC, IA-64 and S/390. +@item -fsel-sched-pipelining +@opindex fsel-sched-pipelining +Enable software pipelining of innermost loops during selective scheduling. +This option has no effect unless one of @option{-fselective-scheduling} or +@option{-fselective-scheduling2} is turned on. -Enabled by default at @option{-O1} and higher. +@item -fsel-sched-pipelining-outer-loops +@opindex fsel-sched-pipelining-outer-loops +When pipelining loops during selective scheduling, also pipeline outer loops. +This option has no effect unless @option{-fsel-sched-pipelining} is turned on. -The default is @option{-fbranch-count-reg}. +@item -fsemantic-interposition +@opindex fsemantic-interposition +Some object formats, like ELF, allow interposing of symbols by the +dynamic linker. +This means that for symbols exported from the DSO, the compiler cannot perform +interprocedural propagation, inlining and other optimizations in anticipation +that the function or variable in question may change. While this feature is +useful, for example, to rewrite memory allocation functions by a debugging +implementation, it is expensive in the terms of code quality. +With @option{-fno-semantic-interposition} the compiler assumes that +if interposition happens for functions the overwriting function will have +precisely the same semantics (and side effects). +Similarly if interposition happens +for variables, the constructor of the variable will be the same. The flag +has no effect for functions explicitly declared inline +(where it is never allowed for interposition to change semantics) +and for symbols explicitly declared weak. -@item -fno-function-cse -@opindex fno-function-cse -Do not put function addresses in registers; make each instruction that -calls a constant function contain the function's address explicitly. +@item -fshrink-wrap +@opindex fshrink-wrap +Emit function prologues only before parts of the function that need it, +rather than at the top of the function. This flag is enabled by default at +@option{-O} and higher. -This option results in less efficient code, but some strange hacks -that alter the assembler output may be confused by the optimizations -performed when this option is not used. +@item -fcaller-saves +@opindex fcaller-saves +Enable allocation of values to registers that are clobbered by +function calls, by emitting extra instructions to save and restore the +registers around such calls. Such allocation is done only when it +seems to result in better code. -The default is @option{-ffunction-cse} +This option is always enabled by default on certain machines, usually +those which have no call-preserved registers to use instead. -@item -fno-zero-initialized-in-bss -@opindex fno-zero-initialized-in-bss -If the target supports a BSS section, GCC by default puts variables that -are initialized to zero into BSS@. This can save space in the resulting -code. +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. -This option turns off this behavior because some programs explicitly -rely on variables going to the data section---e.g., so that the -resulting executable can find the beginning of that section and/or make -assumptions based on that. +@item -fcombine-stack-adjustments +@opindex fcombine-stack-adjustments +Tracks stack adjustments (pushes and pops) and stack memory references +and then tries to find ways to combine them. -The default is @option{-fzero-initialized-in-bss}. +Enabled by default at @option{-O1} and higher. -@item -fthread-jumps -@opindex fthread-jumps -Perform optimizations that check to see if a jump branches to a -location where another comparison subsumed by the first is found. If -so, the first branch is redirected to either the destination of the -second branch or a point immediately following it, depending on whether -the condition is known to be true or false. +@item -fipa-ra +@opindex fipa-ra +Use caller save registers for allocation if those registers are not used by +any called function. In that case it is not necessary to save and restore +them around calls. This is only possible if called functions are part of +same compilation unit as current function and they are compiled before it. Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. -@item -fsplit-wide-types -@opindex fsplit-wide-types -When using a type that occupies multiple registers, such as @code{long -long} on a 32-bit system, split the registers apart and allocate them -independently. This normally generates better code for those types, -but may make debugging more difficult. +@item -fconserve-stack +@opindex fconserve-stack +Attempt to minimize stack usage. The compiler attempts to use less +stack space, even if that makes the program slower. This option +implies setting the @option{large-stack-frame} parameter to 100 +and the @option{large-stack-frame-growth} parameter to 400. -Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, -@option{-Os}. +@item -ftree-reassoc +@opindex ftree-reassoc +Perform reassociation on trees. This flag is enabled by default +at @option{-O} and higher. -@item -fcse-follow-jumps -@opindex fcse-follow-jumps -In common subexpression elimination (CSE), scan through jump instructions -when the target of the jump is not reached by any other path. For -example, when CSE encounters an @code{if} statement with an -@code{else} clause, CSE follows the jump when the condition -tested is false. +@item -ftree-pre +@opindex ftree-pre +Perform partial redundancy elimination (PRE) on trees. This flag is +enabled by default at @option{-O2} and @option{-O3}. -Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. +@item -ftree-partial-pre +@opindex ftree-partial-pre +Make partial redundancy elimination (PRE) more aggressive. This flag is +enabled by default at @option{-O3}. -@item -fcse-skip-blocks -@opindex fcse-skip-blocks -This is similar to @option{-fcse-follow-jumps}, but causes CSE to -follow jumps that conditionally skip over blocks. When CSE -encounters a simple @code{if} statement with no else clause, -@option{-fcse-skip-blocks} causes CSE to follow the jump around the -body of the @code{if}. +@item -ftree-forwprop +@opindex ftree-forwprop +Perform forward propagation on trees. This flag is enabled by default +at @option{-O} and higher. -Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. +@item -ftree-fre +@opindex ftree-fre +Perform full redundancy elimination (FRE) on trees. The difference +between FRE and PRE is that FRE only considers expressions +that are computed on all paths leading to the redundant computation. +This analysis is faster than PRE, though it exposes fewer redundancies. +This flag is enabled by default at @option{-O} and higher. -@item -frerun-cse-after-loop -@opindex frerun-cse-after-loop -Re-run common subexpression elimination after loop optimizations are -performed. +@item -ftree-phiprop +@opindex ftree-phiprop +Perform hoisting of loads from conditional pointers on trees. This +pass is enabled by default at @option{-O} and higher. -Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. +@item -fhoist-adjacent-loads +@opindex fhoist-adjacent-loads +Speculatively hoist loads from both branches of an if-then-else if the +loads are from adjacent locations in the same structure and the target +architecture has a conditional move instruction. This flag is enabled +by default at @option{-O2} and higher. -@item -fgcse -@opindex fgcse -Perform a global common subexpression elimination pass. -This pass also performs global constant and copy propagation. +@item -ftree-copy-prop +@opindex ftree-copy-prop +Perform copy propagation on trees. This pass eliminates unnecessary +copy operations. This flag is enabled by default at @option{-O} and +higher. -@emph{Note:} When compiling a program using computed gotos, a GCC -extension, you may get better run-time performance if you disable -the global common subexpression elimination pass by adding -@option{-fno-gcse} to the command line. +@item -fipa-pure-const +@opindex fipa-pure-const +Discover which functions are pure or constant. +Enabled by default at @option{-O} and higher. -Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. +@item -fipa-reference +@opindex fipa-reference +Discover which static variables do not escape the +compilation unit. +Enabled by default at @option{-O} and higher. -@item -fgcse-lm -@opindex fgcse-lm -When @option{-fgcse-lm} is enabled, global common subexpression elimination -attempts to move loads that are only killed by stores into themselves. This -allows a loop containing a load/store sequence to be changed to a load outside -the loop, and a copy/store within the loop. +@item -fipa-pta +@opindex fipa-pta +Perform interprocedural pointer analysis and interprocedural modification +and reference analysis. This option can cause excessive memory and +compile-time usage on large compilation units. It is not enabled by +default at any optimization level. -Enabled by default when @option{-fgcse} is enabled. +@item -fipa-profile +@opindex fipa-profile +Perform interprocedural profile propagation. The functions called only from +cold functions are marked as cold. Also functions executed once (such as +@code{cold}, @code{noreturn}, static constructors or destructors) are identified. Cold +functions and loop less parts of functions executed once are then optimized for +size. +Enabled by default at @option{-O} and higher. -@item -fgcse-sm -@opindex fgcse-sm -When @option{-fgcse-sm} is enabled, a store motion pass is run after -global common subexpression elimination. This pass attempts to move -stores out of loops. When used in conjunction with @option{-fgcse-lm}, -loops containing a load/store sequence can be changed to a load before -the loop and a store after the loop. +@item -fipa-cp +@opindex fipa-cp +Perform interprocedural constant propagation. +This optimization analyzes the program to determine when values passed +to functions are constants and then optimizes accordingly. +This optimization can substantially increase performance +if the application has constants passed to functions. +This flag is enabled by default at @option{-O2}, @option{-Os} and @option{-O3}. -Not enabled at any optimization level. +@item -fipa-cp-clone +@opindex fipa-cp-clone +Perform function cloning to make interprocedural constant propagation stronger. +When enabled, interprocedural constant propagation performs function cloning +when externally visible function can be called with constant arguments. +Because this optimization can create multiple copies of functions, +it may significantly increase code size +(see @option{--param ipcp-unit-growth=@var{value}}). +This flag is enabled by default at @option{-O3}. -@item -fgcse-las -@opindex fgcse-las -When @option{-fgcse-las} is enabled, the global common subexpression -elimination pass eliminates redundant loads that come after stores to the -same memory location (both partial and full redundancies). +@item -fipa-cp-alignment +@opindex -fipa-cp-alignment +When enabled, this optimization propagates alignment of function +parameters to support better vectorization and string operations. -Not enabled at any optimization level. +This flag is enabled by default at @option{-O2} and @option{-Os}. It +requires that @option{-fipa-cp} is enabled. -@item -fgcse-after-reload -@opindex fgcse-after-reload -When @option{-fgcse-after-reload} is enabled, a redundant load elimination -pass is performed after reload. The purpose of this pass is to clean up -redundant spilling. +@item -fipa-icf +@opindex fipa-icf +Perform Identical Code Folding for functions and read-only variables. +The optimization reduces code size and may disturb unwind stacks by replacing +a function by equivalent one with a different name. The optimization works +more effectively with link time optimization enabled. -@item -faggressive-loop-optimizations -@opindex faggressive-loop-optimizations -This option tells the loop optimizer to use language constraints to -derive bounds for the number of iterations of a loop. This assumes that -loop code does not invoke undefined behavior by for example causing signed -integer overflows or out-of-bound array accesses. The bounds for the -number of iterations of a loop are used to guide loop unrolling and peeling -and loop exit test optimizations. -This option is enabled by default. +Nevertheless the behavior is similar to Gold Linker ICF optimization, GCC ICF +works on different levels and thus the optimizations are not same - there are +equivalences that are found only by GCC and equivalences found only by Gold. -@item -funsafe-loop-optimizations -@opindex funsafe-loop-optimizations -This option tells the loop optimizer to assume that loop indices do not -overflow, and that loops with nontrivial exit condition are not -infinite. This enables a wider range of loop optimizations even if -the loop optimizer itself cannot prove that these assumptions are valid. -If you use @option{-Wunsafe-loop-optimizations}, the compiler warns you -if it finds this kind of loop. +This flag is enabled by default at @option{-O2} and @option{-Os}. -@item -fcrossjumping -@opindex fcrossjumping -Perform cross-jumping transformation. -This transformation unifies equivalent code and saves code size. The -resulting code may or may not perform better than without cross-jumping. +@item -fisolate-erroneous-paths-dereference +@opindex fisolate-erroneous-paths-dereference +Detect paths that trigger erroneous or undefined behavior due to +dereferencing a null pointer. Isolate those paths from the main control +flow and turn the statement with erroneous or undefined behavior into a trap. +This flag is enabled by default at @option{-O2} and higher and depends on +@option{-fdelete-null-pointer-checks} also being enabled. -Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. +@item -fisolate-erroneous-paths-attribute +@opindex fisolate-erroneous-paths-attribute +Detect paths that trigger erroneous or undefined behavior due a null value +being used in a way forbidden by a @code{returns_nonnull} or @code{nonnull} +attribute. Isolate those paths from the main control flow and turn the +statement with erroneous or undefined behavior into a trap. This is not +currently enabled, but may be enabled by @option{-O2} in the future. -@item -fauto-inc-dec -@opindex fauto-inc-dec -Combine increments or decrements of addresses with memory accesses. -This pass is always skipped on architectures that do not have -instructions to support this. Enabled by default at @option{-O} and -higher on architectures that support this. +@item -ftree-sink +@opindex ftree-sink +Perform forward store motion on trees. This flag is +enabled by default at @option{-O} and higher. -@item -fdce -@opindex fdce -Perform dead code elimination (DCE) on RTL@. -Enabled by default at @option{-O} and higher. +@item -ftree-bit-ccp +@opindex ftree-bit-ccp +Perform sparse conditional bit constant propagation on trees and propagate +pointer alignment information. +This pass only operates on local scalar variables and is enabled by default +at @option{-O} and higher. It requires that @option{-ftree-ccp} is enabled. + +@item -ftree-ccp +@opindex ftree-ccp +Perform sparse conditional constant propagation (CCP) on trees. This +pass only operates on local scalar variables and is enabled by default +at @option{-O} and higher. + +@item -fssa-backprop +@opindex fssa-backprop +Propagate information about uses of a value up the definition chain +in order to simplify the definitions. For example, this pass strips +sign operations if the sign of a value never matters. The flag is +enabled by default at @option{-O} and higher. + +@item -fssa-phiopt +@opindex fssa-phiopt +Perform pattern matching on SSA PHI nodes to optimize conditional +code. This pass is enabled by default at @option{-O} and higher. -@item -fdse -@opindex fdse -Perform dead store elimination (DSE) on RTL@. -Enabled by default at @option{-O} and higher. +@item -ftree-switch-conversion +@opindex ftree-switch-conversion +Perform conversion of simple initializations in a switch to +initializations from a scalar array. This flag is enabled by default +at @option{-O2} and higher. -@item -fif-conversion -@opindex fif-conversion -Attempt to transform conditional jumps into branch-less equivalents. This -includes use of conditional moves, min, max, set flags and abs instructions, and -some tricks doable by standard arithmetics. The use of conditional execution -on chips where it is available is controlled by @option{-fif-conversion2}. +@item -ftree-tail-merge +@opindex ftree-tail-merge +Look for identical code sequences. When found, replace one with a jump to the +other. This optimization is known as tail merging or cross jumping. This flag +is enabled by default at @option{-O2} and higher. The compilation time +in this pass can +be limited using @option{max-tail-merge-comparisons} parameter and +@option{max-tail-merge-iterations} parameter. -Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. +@item -ftree-dce +@opindex ftree-dce +Perform dead code elimination (DCE) on trees. This flag is enabled by +default at @option{-O} and higher. -@item -fif-conversion2 -@opindex fif-conversion2 -Use conditional execution (where available) to transform conditional jumps into -branch-less equivalents. +@item -ftree-builtin-call-dce +@opindex ftree-builtin-call-dce +Perform conditional dead code elimination (DCE) for calls to built-in functions +that may set @code{errno} but are otherwise side-effect free. This flag is +enabled by default at @option{-O2} and higher if @option{-Os} is not also +specified. -Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. +@item -ftree-dominator-opts +@opindex ftree-dominator-opts +Perform a variety of simple scalar cleanups (constant/copy +propagation, redundancy elimination, range propagation and expression +simplification) based on a dominator tree traversal. This also +performs jump threading (to reduce jumps to jumps). This flag is +enabled by default at @option{-O} and higher. -@item -fdeclone-ctor-dtor -@opindex fdeclone-ctor-dtor -The C++ ABI requires multiple entry points for constructors and -destructors: one for a base subobject, one for a complete object, and -one for a virtual destructor that calls operator delete afterwards. -For a hierarchy with virtual bases, the base and complete variants are -clones, which means two copies of the function. With this option, the -base and complete variants are changed to be thunks that call a common -implementation. +@item -ftree-dse +@opindex ftree-dse +Perform dead store elimination (DSE) on trees. A dead store is a store into +a memory location that is later overwritten by another store without +any intervening loads. In this case the earlier store can be deleted. This +flag is enabled by default at @option{-O} and higher. -Enabled by @option{-Os}. +@item -ftree-ch +@opindex ftree-ch +Perform loop header copying on trees. This is beneficial since it increases +effectiveness of code motion optimizations. It also saves one jump. This flag +is enabled by default at @option{-O} and higher. It is not enabled +for @option{-Os}, since it usually increases code size. -@item -fdelete-null-pointer-checks -@opindex fdelete-null-pointer-checks -Assume that programs cannot safely dereference null pointers, and that -no code or data element resides at address zero. -This option enables simple constant -folding optimizations at all optimization levels. In addition, other -optimization passes in GCC use this flag to control global dataflow -analyses that eliminate useless checks for null pointers; these assume -that a memory access to address zero always results in a trap, so -that if a pointer is checked after it has already been dereferenced, -it cannot be null. +@item -ftree-loop-optimize +@opindex ftree-loop-optimize +Perform loop optimizations on trees. This flag is enabled by default +at @option{-O} and higher. -Note however that in some environments this assumption is not true. -Use @option{-fno-delete-null-pointer-checks} to disable this optimization -for programs that depend on that behavior. +@item -ftree-loop-linear +@itemx -floop-interchange +@itemx -floop-strip-mine +@itemx -floop-block +@itemx -floop-unroll-and-jam +@opindex ftree-loop-linear +@opindex floop-interchange +@opindex floop-strip-mine +@opindex floop-block +@opindex floop-unroll-and-jam +Perform loop nest optimizations. Same as +@option{-floop-nest-optimize}. To use this code transformation, GCC has +to be configured with @option{--with-isl} to enable the Graphite loop +transformation infrastructure. -This option is enabled by default on most targets. On Nios II ELF, it -defaults to off. On AVR and CR16, this option is completely disabled. +@item -fgraphite-identity +@opindex fgraphite-identity +Enable the identity transformation for graphite. For every SCoP we generate +the polyhedral representation and transform it back to gimple. Using +@option{-fgraphite-identity} we can check the costs or benefits of the +GIMPLE -> GRAPHITE -> GIMPLE transformation. Some minimal optimizations +are also performed by the code generator isl, like index splitting and +dead code elimination in loops. -Passes that use the dataflow information -are enabled independently at different optimization levels. +@item -floop-nest-optimize +@opindex floop-nest-optimize +Enable the isl based loop nest optimizer. This is a generic loop nest +optimizer based on the Pluto optimization algorithms. It calculates a loop +structure optimized for data-locality and parallelism. This option +is experimental. -@item -fdevirtualize -@opindex fdevirtualize -Attempt to convert calls to virtual functions to direct calls. This -is done both within a procedure and interprocedurally as part of -indirect inlining (@option{-findirect-inlining}) and interprocedural constant -propagation (@option{-fipa-cp}). -Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. +@item -floop-parallelize-all +@opindex floop-parallelize-all +Use the Graphite data dependence analysis to identify loops that can +be parallelized. Parallelize all the loops that can be analyzed to +not contain loop carried dependences without checking that it is +profitable to parallelize the loops. -@item -fdevirtualize-speculatively -@opindex fdevirtualize-speculatively -Attempt to convert calls to virtual functions to speculative direct calls. -Based on the analysis of the type inheritance graph, determine for a given call -the set of likely targets. If the set is small, preferably of size 1, change -the call into a conditional deciding between direct and indirect calls. The -speculative calls enable more optimizations, such as inlining. When they seem -useless after further optimization, they are converted back into original form. +@item -ftree-coalesce-vars +@opindex ftree-coalesce-vars +While transforming the program out of the SSA representation, attempt to +reduce copying by coalescing versions of different user-defined +variables, instead of just compiler temporaries. This may severely +limit the ability to debug an optimized program compiled with +@option{-fno-var-tracking-assignments}. In the negated form, this flag +prevents SSA coalescing of user variables. This option is enabled by +default if optimization is enabled, and it does very little otherwise. -@item -fdevirtualize-at-ltrans -@opindex fdevirtualize-at-ltrans -Stream extra information needed for aggressive devirtualization when running -the link-time optimizer in local transformation mode. -This option enables more devirtualization but -significantly increases the size of streamed data. For this reason it is -disabled by default. +@item -ftree-loop-if-convert +@opindex ftree-loop-if-convert +Attempt to transform conditional jumps in the innermost loops to +branch-less equivalents. The intent is to remove control-flow from +the innermost loops in order to improve the ability of the +vectorization pass to handle these loops. This is enabled by default +if vectorization is enabled. -@item -fexpensive-optimizations -@opindex fexpensive-optimizations -Perform a number of minor optimizations that are relatively expensive. +@item -ftree-loop-if-convert-stores +@opindex ftree-loop-if-convert-stores +Attempt to also if-convert conditional jumps containing memory writes. +This transformation can be unsafe for multi-threaded programs as it +transforms conditional memory writes into unconditional memory writes. +For example, +@smallexample +for (i = 0; i < N; i++) + if (cond) + A[i] = expr; +@end smallexample +is transformed to +@smallexample +for (i = 0; i < N; i++) + A[i] = cond ? expr : A[i]; +@end smallexample +potentially producing data races. -Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. +@item -ftree-loop-distribution +@opindex ftree-loop-distribution +Perform loop distribution. This flag can improve cache performance on +big loop bodies and allow further loop optimizations, like +parallelization or vectorization, to take place. For example, the loop +@smallexample +DO I = 1, N + A(I) = B(I) + C + D(I) = E(I) * F +ENDDO +@end smallexample +is transformed to +@smallexample +DO I = 1, N + A(I) = B(I) + C +ENDDO +DO I = 1, N + D(I) = E(I) * F +ENDDO +@end smallexample -@item -free -@opindex free -Attempt to remove redundant extension instructions. This is especially -helpful for the x86-64 architecture, which implicitly zero-extends in 64-bit -registers after writing to their lower 32-bit half. +@item -ftree-loop-distribute-patterns +@opindex ftree-loop-distribute-patterns +Perform loop distribution of patterns that can be code generated with +calls to a library. This flag is enabled by default at @option{-O3}. -Enabled for Alpha, AArch64 and x86 at levels @option{-O2}, -@option{-O3}, @option{-Os}. +This pass distributes the initialization loops and generates a call to +memset zero. For example, the loop +@smallexample +DO I = 1, N + A(I) = 0 + B(I) = A(I) + I +ENDDO +@end smallexample +is transformed to +@smallexample +DO I = 1, N + A(I) = 0 +ENDDO +DO I = 1, N + B(I) = A(I) + I +ENDDO +@end smallexample +and the initialization loop is transformed into a call to memset zero. -@item -fno-lifetime-dse -@opindex fno-lifetime-dse -In C++ the value of an object is only affected by changes within its -lifetime: when the constructor begins, the object has an indeterminate -value, and any changes during the lifetime of the object are dead when -the object is destroyed. Normally dead store elimination will take -advantage of this; if your code relies on the value of the object -storage persisting beyond the lifetime of the object, you can use this -flag to disable this optimization. +@item -ftree-loop-im +@opindex ftree-loop-im +Perform loop invariant motion on trees. This pass moves only invariants that +are hard to handle at RTL level (function calls, operations that expand to +nontrivial sequences of insns). With @option{-funswitch-loops} it also moves +operands of conditions that are invariant out of the loop, so that we can use +just trivial invariantness analysis in loop unswitching. The pass also includes +store motion. + +@item -ftree-loop-ivcanon +@opindex ftree-loop-ivcanon +Create a canonical counter for number of iterations in loops for which +determining number of iterations requires complicated analysis. Later +optimizations then may determine the number easily. Useful especially +in connection with unrolling. -@item -flive-range-shrinkage -@opindex flive-range-shrinkage -Attempt to decrease register pressure through register live range -shrinkage. This is helpful for fast processors with small or moderate -size register sets. +@item -fivopts +@opindex fivopts +Perform induction variable optimizations (strength reduction, induction +variable merging and induction variable elimination) on trees. -@item -fira-algorithm=@var{algorithm} -@opindex fira-algorithm -Use the specified coloring algorithm for the integrated register -allocator. The @var{algorithm} argument can be @samp{priority}, which -specifies Chow's priority coloring, or @samp{CB}, which specifies -Chaitin-Briggs coloring. Chaitin-Briggs coloring is not implemented -for all architectures, but for those targets that do support it, it is -the default because it generates better code. +@item -ftree-parallelize-loops=n +@opindex ftree-parallelize-loops +Parallelize loops, i.e., split their iteration space to run in n threads. +This is only possible for loops whose iterations are independent +and can be arbitrarily reordered. The optimization is only +profitable on multiprocessor machines, for loops that are CPU-intensive, +rather than constrained e.g.@: by memory bandwidth. This option +implies @option{-pthread}, and thus is only supported on targets +that have support for @option{-pthread}. -@item -fira-region=@var{region} -@opindex fira-region -Use specified regions for the integrated register allocator. The -@var{region} argument should be one of the following: +@item -ftree-pta +@opindex ftree-pta +Perform function-local points-to analysis on trees. This flag is +enabled by default at @option{-O} and higher. -@table @samp +@item -ftree-sra +@opindex ftree-sra +Perform scalar replacement of aggregates. This pass replaces structure +references with scalars to prevent committing structures to memory too +early. This flag is enabled by default at @option{-O} and higher. -@item all -Use all loops as register allocation regions. -This can give the best results for machines with a small and/or -irregular register set. +@item -ftree-ter +@opindex ftree-ter +Perform temporary expression replacement during the SSA->normal phase. Single +use/single def temporaries are replaced at their use location with their +defining expression. This results in non-GIMPLE code, but gives the expanders +much more complex trees to work on resulting in better RTL generation. This is +enabled by default at @option{-O} and higher. -@item mixed -Use all loops except for loops with small register pressure -as the regions. This value usually gives -the best results in most cases and for most architectures, -and is enabled by default when compiling with optimization for speed -(@option{-O}, @option{-O2}, @dots{}). +@item -ftree-slsr +@opindex ftree-slsr +Perform straight-line strength reduction on trees. This recognizes related +expressions involving multiplications and replaces them by less expensive +calculations when possible. This is enabled by default at @option{-O} and +higher. -@item one -Use all functions as a single region. -This typically results in the smallest code size, and is enabled by default for -@option{-Os} or @option{-O0}. +@item -ftree-vectorize +@opindex ftree-vectorize +Perform vectorization on trees. This flag enables @option{-ftree-loop-vectorize} +and @option{-ftree-slp-vectorize} if not explicitly specified. -@end table +@item -ftree-loop-vectorize +@opindex ftree-loop-vectorize +Perform loop vectorization on trees. This flag is enabled by default at +@option{-O3} and when @option{-ftree-vectorize} is enabled. -@item -fira-hoist-pressure -@opindex fira-hoist-pressure -Use IRA to evaluate register pressure in the code hoisting pass for -decisions to hoist expressions. This option usually results in smaller -code, but it can slow the compiler down. +@item -ftree-slp-vectorize +@opindex ftree-slp-vectorize +Perform basic block vectorization on trees. This flag is enabled by default at +@option{-O3} and when @option{-ftree-vectorize} is enabled. -This option is enabled at level @option{-Os} for all targets. +@item -fvect-cost-model=@var{model} +@opindex fvect-cost-model +Alter the cost model used for vectorization. The @var{model} argument +should be one of @samp{unlimited}, @samp{dynamic} or @samp{cheap}. +With the @samp{unlimited} model the vectorized code-path is assumed +to be profitable while with the @samp{dynamic} model a runtime check +guards the vectorized code-path to enable it only for iteration +counts that will likely execute faster than when executing the original +scalar loop. The @samp{cheap} model disables vectorization of +loops where doing so would be cost prohibitive for example due to +required runtime checks for data dependence or alignment but otherwise +is equal to the @samp{dynamic} model. +The default cost model depends on other optimization flags and is +either @samp{dynamic} or @samp{cheap}. -@item -fira-loop-pressure -@opindex fira-loop-pressure -Use IRA to evaluate register pressure in loops for decisions to move -loop invariants. This option usually results in generation -of faster and smaller code on machines with large register files (>= 32 -registers), but it can slow the compiler down. +@item -fsimd-cost-model=@var{model} +@opindex fsimd-cost-model +Alter the cost model used for vectorization of loops marked with the OpenMP +or Cilk Plus simd directive. The @var{model} argument should be one of +@samp{unlimited}, @samp{dynamic}, @samp{cheap}. All values of @var{model} +have the same meaning as described in @option{-fvect-cost-model} and by +default a cost model defined with @option{-fvect-cost-model} is used. -This option is enabled at level @option{-O3} for some targets. +@item -ftree-vrp +@opindex ftree-vrp +Perform Value Range Propagation on trees. This is similar to the +constant propagation pass, but instead of values, ranges of values are +propagated. This allows the optimizers to remove unnecessary range +checks like array bound checks and null pointer checks. This is +enabled by default at @option{-O2} and higher. Null pointer check +elimination is only done if @option{-fdelete-null-pointer-checks} is +enabled. -@item -fno-ira-share-save-slots -@opindex fno-ira-share-save-slots -Disable sharing of stack slots used for saving call-used hard -registers living through a call. Each hard register gets a -separate stack slot, and as a result function stack frames are -larger. +@item -fsplit-paths +@opindex fsplit-paths +Split paths leading to loop backedges. This can improve dead code +elimination and common subexpression elimination. This is enabled by +default at @option{-O2} and above. -@item -fno-ira-share-spill-slots -@opindex fno-ira-share-spill-slots -Disable sharing of stack slots allocated for pseudo-registers. Each -pseudo-register that does not get a hard register gets a separate -stack slot, and as a result function stack frames are larger. +@item -fsplit-ivs-in-unroller +@opindex fsplit-ivs-in-unroller +Enables expression of values of induction variables in later iterations +of the unrolled loop using the value in the first iteration. This breaks +long dependency chains, thus improving efficiency of the scheduling passes. -@item -fira-verbose=@var{n} -@opindex fira-verbose -Control the verbosity of the dump file for the integrated register allocator. -The default value is 5. If the value @var{n} is greater or equal to 10, -the dump output is sent to stderr using the same format as @var{n} minus 10. +A combination of @option{-fweb} and CSE is often sufficient to obtain the +same effect. However, that is not reliable in cases where the loop body +is more complicated than a single basic block. It also does not work at all +on some architectures due to restrictions in the CSE pass. -@item -flra-remat -@opindex flra-remat -Enable CFG-sensitive rematerialization in LRA. Instead of loading -values of spilled pseudos, LRA tries to rematerialize (recalculate) -values if it is profitable. +This optimization is enabled by default. -Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. +@item -fvariable-expansion-in-unroller +@opindex fvariable-expansion-in-unroller +With this option, the compiler creates multiple copies of some +local variables when unrolling a loop, which can result in superior code. -@item -fdelayed-branch -@opindex fdelayed-branch -If supported for the target machine, attempt to reorder instructions -to exploit instruction slots available after delayed branch -instructions. +@item -fpartial-inlining +@opindex fpartial-inlining +Inline parts of functions. This option has any effect only +when inlining itself is turned on by the @option{-finline-functions} +or @option{-finline-small-functions} options. -Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. +Enabled at level @option{-O2}. -@item -fschedule-insns -@opindex fschedule-insns -If supported for the target machine, attempt to reorder instructions to -eliminate execution stalls due to required data being unavailable. This -helps machines that have slow floating point or memory load instructions -by allowing other instructions to be issued until the result of the load -or floating-point instruction is required. +@item -fpredictive-commoning +@opindex fpredictive-commoning +Perform predictive commoning optimization, i.e., reusing computations +(especially memory loads and stores) performed in previous +iterations of loops. -Enabled at levels @option{-O2}, @option{-O3}. +This option is enabled at level @option{-O3}. -@item -fschedule-insns2 -@opindex fschedule-insns2 -Similar to @option{-fschedule-insns}, but requests an additional pass of -instruction scheduling after register allocation has been done. This is -especially useful on machines with a relatively small number of -registers and where memory load instructions take more than one cycle. +@item -fprefetch-loop-arrays +@opindex fprefetch-loop-arrays +If supported by the target machine, generate instructions to prefetch +memory to improve the performance of loops that access large arrays. -Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. +This option may generate better or worse code; results are highly +dependent on the structure of loops within the source code. -@item -fno-sched-interblock -@opindex fno-sched-interblock -Don't schedule instructions across basic blocks. This is normally -enabled by default when scheduling before register allocation, i.e.@: -with @option{-fschedule-insns} or at @option{-O2} or higher. +Disabled at level @option{-Os}. -@item -fno-sched-spec -@opindex fno-sched-spec -Don't allow speculative motion of non-load instructions. This is normally -enabled by default when scheduling before register allocation, i.e.@: -with @option{-fschedule-insns} or at @option{-O2} or higher. +@item -fno-peephole +@itemx -fno-peephole2 +@opindex fno-peephole +@opindex fno-peephole2 +Disable any machine-specific peephole optimizations. The difference +between @option{-fno-peephole} and @option{-fno-peephole2} is in how they +are implemented in the compiler; some targets use one, some use the +other, a few use both. -@item -fsched-pressure -@opindex fsched-pressure -Enable register pressure sensitive insn scheduling before register -allocation. This only makes sense when scheduling before register -allocation is enabled, i.e.@: with @option{-fschedule-insns} or at -@option{-O2} or higher. Usage of this option can improve the -generated code and decrease its size by preventing register pressure -increase above the number of available hard registers and subsequent -spills in register allocation. +@option{-fpeephole} is enabled by default. +@option{-fpeephole2} enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. -@item -fsched-spec-load -@opindex fsched-spec-load -Allow speculative motion of some load instructions. This only makes -sense when scheduling before register allocation, i.e.@: with -@option{-fschedule-insns} or at @option{-O2} or higher. +@item -fno-guess-branch-probability +@opindex fno-guess-branch-probability +Do not guess branch probabilities using heuristics. -@item -fsched-spec-load-dangerous -@opindex fsched-spec-load-dangerous -Allow speculative motion of more load instructions. This only makes -sense when scheduling before register allocation, i.e.@: with -@option{-fschedule-insns} or at @option{-O2} or higher. +GCC uses heuristics to guess branch probabilities if they are +not provided by profiling feedback (@option{-fprofile-arcs}). These +heuristics are based on the control flow graph. If some branch probabilities +are specified by @code{__builtin_expect}, then the heuristics are +used to guess branch probabilities for the rest of the control flow graph, +taking the @code{__builtin_expect} info into account. The interactions +between the heuristics and @code{__builtin_expect} can be complex, and in +some cases, it may be useful to disable the heuristics so that the effects +of @code{__builtin_expect} are easier to understand. -@item -fsched-stalled-insns -@itemx -fsched-stalled-insns=@var{n} -@opindex fsched-stalled-insns -Define how many insns (if any) can be moved prematurely from the queue -of stalled insns into the ready list during the second scheduling pass. -@option{-fno-sched-stalled-insns} means that no insns are moved -prematurely, @option{-fsched-stalled-insns=0} means there is no limit -on how many queued insns can be moved prematurely. -@option{-fsched-stalled-insns} without a value is equivalent to -@option{-fsched-stalled-insns=1}. +The default is @option{-fguess-branch-probability} at levels +@option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. -@item -fsched-stalled-insns-dep -@itemx -fsched-stalled-insns-dep=@var{n} -@opindex fsched-stalled-insns-dep -Define how many insn groups (cycles) are examined for a dependency -on a stalled insn that is a candidate for premature removal from the queue -of stalled insns. This has an effect only during the second scheduling pass, -and only if @option{-fsched-stalled-insns} is used. -@option{-fno-sched-stalled-insns-dep} is equivalent to -@option{-fsched-stalled-insns-dep=0}. -@option{-fsched-stalled-insns-dep} without a value is equivalent to -@option{-fsched-stalled-insns-dep=1}. +@item -freorder-blocks +@opindex freorder-blocks +Reorder basic blocks in the compiled function in order to reduce number of +taken branches and improve code locality. -@item -fsched2-use-superblocks -@opindex fsched2-use-superblocks -When scheduling after register allocation, use superblock scheduling. -This allows motion across basic block boundaries, -resulting in faster schedules. This option is experimental, as not all machine -descriptions used by GCC model the CPU closely enough to avoid unreliable -results from the algorithm. +Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. -This only makes sense when scheduling after register allocation, i.e.@: with -@option{-fschedule-insns2} or at @option{-O2} or higher. +@item -freorder-blocks-algorithm=@var{algorithm} +@opindex freorder-blocks-algorithm +Use the specified algorithm for basic block reordering. The +@var{algorithm} argument can be @samp{simple}, which does not increase +code size (except sometimes due to secondary effects like alignment), +or @samp{stc}, the ``software trace cache'' algorithm, which tries to +put all often executed code together, minimizing the number of branches +executed by making extra copies of code. -@item -fsched-group-heuristic -@opindex fsched-group-heuristic -Enable the group heuristic in the scheduler. This heuristic favors -the instruction that belongs to a schedule group. This is enabled -by default when scheduling is enabled, i.e.@: with @option{-fschedule-insns} -or @option{-fschedule-insns2} or at @option{-O2} or higher. +The default is @samp{simple} at levels @option{-O}, @option{-Os}, and +@samp{stc} at levels @option{-O2}, @option{-O3}. -@item -fsched-critical-path-heuristic -@opindex fsched-critical-path-heuristic -Enable the critical-path heuristic in the scheduler. This heuristic favors -instructions on the critical path. This is enabled by default when -scheduling is enabled, i.e.@: with @option{-fschedule-insns} -or @option{-fschedule-insns2} or at @option{-O2} or higher. +@item -freorder-blocks-and-partition +@opindex freorder-blocks-and-partition +In addition to reordering basic blocks in the compiled function, in order +to reduce number of taken branches, partitions hot and cold basic blocks +into separate sections of the assembly and .o files, to improve +paging and cache locality performance. -@item -fsched-spec-insn-heuristic -@opindex fsched-spec-insn-heuristic -Enable the speculative instruction heuristic in the scheduler. This -heuristic favors speculative instructions with greater dependency weakness. -This is enabled by default when scheduling is enabled, i.e.@: -with @option{-fschedule-insns} or @option{-fschedule-insns2} -or at @option{-O2} or higher. +This optimization is automatically turned off in the presence of +exception handling, for linkonce sections, for functions with a user-defined +section attribute and on any architecture that does not support named +sections. -@item -fsched-rank-heuristic -@opindex fsched-rank-heuristic -Enable the rank heuristic in the scheduler. This heuristic favors -the instruction belonging to a basic block with greater size or frequency. -This is enabled by default when scheduling is enabled, i.e.@: -with @option{-fschedule-insns} or @option{-fschedule-insns2} or -at @option{-O2} or higher. +Enabled for x86 at levels @option{-O2}, @option{-O3}. -@item -fsched-last-insn-heuristic -@opindex fsched-last-insn-heuristic -Enable the last-instruction heuristic in the scheduler. This heuristic -favors the instruction that is less dependent on the last instruction -scheduled. This is enabled by default when scheduling is enabled, -i.e.@: with @option{-fschedule-insns} or @option{-fschedule-insns2} or -at @option{-O2} or higher. +@item -freorder-functions +@opindex freorder-functions +Reorder functions in the object file in order to +improve code locality. This is implemented by using special +subsections @code{.text.hot} for most frequently executed functions and +@code{.text.unlikely} for unlikely executed functions. Reordering is done by +the linker so object file format must support named sections and linker must +place them in a reasonable way. -@item -fsched-dep-count-heuristic -@opindex fsched-dep-count-heuristic -Enable the dependent-count heuristic in the scheduler. This heuristic -favors the instruction that has more instructions depending on it. -This is enabled by default when scheduling is enabled, i.e.@: -with @option{-fschedule-insns} or @option{-fschedule-insns2} or -at @option{-O2} or higher. +Also profile feedback must be available to make this option effective. See +@option{-fprofile-arcs} for details. -@item -freschedule-modulo-scheduled-loops -@opindex freschedule-modulo-scheduled-loops -Modulo scheduling is performed before traditional scheduling. If a loop -is modulo scheduled, later scheduling passes may change its schedule. -Use this option to control that behavior. +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. -@item -fselective-scheduling -@opindex fselective-scheduling -Schedule instructions using selective scheduling algorithm. Selective -scheduling runs instead of the first scheduler pass. +@item -fstrict-aliasing +@opindex fstrict-aliasing +Allow the compiler to assume the strictest aliasing rules applicable to +the language being compiled. For C (and C++), this activates +optimizations based on the type of expressions. In particular, an +object of one type is assumed never to reside at the same address as an +object of a different type, unless the types are almost the same. For +example, an @code{unsigned int} can alias an @code{int}, but not a +@code{void*} or a @code{double}. A character type may alias any other +type. -@item -fselective-scheduling2 -@opindex fselective-scheduling2 -Schedule instructions using selective scheduling algorithm. Selective -scheduling runs instead of the second scheduler pass. +@anchor{Type-punning}Pay special attention to code like this: +@smallexample +union a_union @{ + int i; + double d; +@}; -@item -fsel-sched-pipelining -@opindex fsel-sched-pipelining -Enable software pipelining of innermost loops during selective scheduling. -This option has no effect unless one of @option{-fselective-scheduling} or -@option{-fselective-scheduling2} is turned on. +int f() @{ + union a_union t; + t.d = 3.0; + return t.i; +@} +@end smallexample +The practice of reading from a different union member than the one most +recently written to (called ``type-punning'') is common. Even with +@option{-fstrict-aliasing}, type-punning is allowed, provided the memory +is accessed through the union type. So, the code above works as +expected. @xref{Structures unions enumerations and bit-fields +implementation}. However, this code might not: +@smallexample +int f() @{ + union a_union t; + int* ip; + t.d = 3.0; + ip = &t.i; + return *ip; +@} +@end smallexample -@item -fsel-sched-pipelining-outer-loops -@opindex fsel-sched-pipelining-outer-loops -When pipelining loops during selective scheduling, also pipeline outer loops. -This option has no effect unless @option{-fsel-sched-pipelining} is turned on. +Similarly, access by taking the address, casting the resulting pointer +and dereferencing the result has undefined behavior, even if the cast +uses a union type, e.g.: +@smallexample +int f() @{ + double d = 3.0; + return ((union a_union *) &d)->i; +@} +@end smallexample -@item -fsemantic-interposition -@opindex fsemantic-interposition -Some object formats, like ELF, allow interposing of symbols by the -dynamic linker. -This means that for symbols exported from the DSO, the compiler cannot perform -interprocedural propagation, inlining and other optimizations in anticipation -that the function or variable in question may change. While this feature is -useful, for example, to rewrite memory allocation functions by a debugging -implementation, it is expensive in the terms of code quality. -With @option{-fno-semantic-interposition} the compiler assumes that -if interposition happens for functions the overwriting function will have -precisely the same semantics (and side effects). -Similarly if interposition happens -for variables, the constructor of the variable will be the same. The flag -has no effect for functions explicitly declared inline -(where it is never allowed for interposition to change semantics) -and for symbols explicitly declared weak. +The @option{-fstrict-aliasing} option is enabled at levels +@option{-O2}, @option{-O3}, @option{-Os}. -@item -fshrink-wrap -@opindex fshrink-wrap -Emit function prologues only before parts of the function that need it, -rather than at the top of the function. This flag is enabled by default at -@option{-O} and higher. +@item -fstrict-overflow +@opindex fstrict-overflow +Allow the compiler to assume strict signed overflow rules, depending +on the language being compiled. For C (and C++) this means that +overflow when doing arithmetic with signed numbers is undefined, which +means that the compiler may assume that it does not happen. This +permits various optimizations. For example, the compiler assumes +that an expression like @code{i + 10 > i} is always true for +signed @code{i}. This assumption is only valid if signed overflow is +undefined, as the expression is false if @code{i + 10} overflows when +using twos complement arithmetic. When this option is in effect any +attempt to determine whether an operation on signed numbers +overflows must be written carefully to not actually involve overflow. -@item -fcaller-saves -@opindex fcaller-saves -Enable allocation of values to registers that are clobbered by -function calls, by emitting extra instructions to save and restore the -registers around such calls. Such allocation is done only when it -seems to result in better code. +This option also allows the compiler to assume strict pointer +semantics: given a pointer to an object, if adding an offset to that +pointer does not produce a pointer to the same object, the addition is +undefined. This permits the compiler to conclude that @code{p + u > +p} is always true for a pointer @code{p} and unsigned integer +@code{u}. This assumption is only valid because pointer wraparound is +undefined, as the expression is false if @code{p + u} overflows using +twos complement arithmetic. -This option is always enabled by default on certain machines, usually -those which have no call-preserved registers to use instead. +See also the @option{-fwrapv} option. Using @option{-fwrapv} means +that integer signed overflow is fully defined: it wraps. When +@option{-fwrapv} is used, there is no difference between +@option{-fstrict-overflow} and @option{-fno-strict-overflow} for +integers. With @option{-fwrapv} certain types of overflow are +permitted. For example, if the compiler gets an overflow when doing +arithmetic on constants, the overflowed value can still be used with +@option{-fwrapv}, but not otherwise. -Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. +The @option{-fstrict-overflow} option is enabled at levels +@option{-O2}, @option{-O3}, @option{-Os}. -@item -fcombine-stack-adjustments -@opindex fcombine-stack-adjustments -Tracks stack adjustments (pushes and pops) and stack memory references -and then tries to find ways to combine them. +@item -falign-functions +@itemx -falign-functions=@var{n} +@opindex falign-functions +Align the start of functions to the next power-of-two greater than +@var{n}, skipping up to @var{n} bytes. For instance, +@option{-falign-functions=32} aligns functions to the next 32-byte +boundary, but @option{-falign-functions=24} aligns to the next +32-byte boundary only if this can be done by skipping 23 bytes or less. + +@option{-fno-align-functions} and @option{-falign-functions=1} are +equivalent and mean that functions are not aligned. -Enabled by default at @option{-O1} and higher. +Some assemblers only support this flag when @var{n} is a power of two; +in that case, it is rounded up. -@item -fipa-ra -@opindex fipa-ra -Use caller save registers for allocation if those registers are not used by -any called function. In that case it is not necessary to save and restore -them around calls. This is only possible if called functions are part of -same compilation unit as current function and they are compiled before it. +If @var{n} is not specified or is zero, use a machine-dependent default. -Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. +Enabled at levels @option{-O2}, @option{-O3}. -@item -fconserve-stack -@opindex fconserve-stack -Attempt to minimize stack usage. The compiler attempts to use less -stack space, even if that makes the program slower. This option -implies setting the @option{large-stack-frame} parameter to 100 -and the @option{large-stack-frame-growth} parameter to 400. +@item -falign-labels +@itemx -falign-labels=@var{n} +@opindex falign-labels +Align all branch targets to a power-of-two boundary, skipping up to +@var{n} bytes like @option{-falign-functions}. This option can easily +make code slower, because it must insert dummy operations for when the +branch target is reached in the usual flow of the code. -@item -ftree-reassoc -@opindex ftree-reassoc -Perform reassociation on trees. This flag is enabled by default -at @option{-O} and higher. +@option{-fno-align-labels} and @option{-falign-labels=1} are +equivalent and mean that labels are not aligned. -@item -ftree-pre -@opindex ftree-pre -Perform partial redundancy elimination (PRE) on trees. This flag is -enabled by default at @option{-O2} and @option{-O3}. +If @option{-falign-loops} or @option{-falign-jumps} are applicable and +are greater than this value, then their values are used instead. -@item -ftree-partial-pre -@opindex ftree-partial-pre -Make partial redundancy elimination (PRE) more aggressive. This flag is -enabled by default at @option{-O3}. +If @var{n} is not specified or is zero, use a machine-dependent default +which is very likely to be @samp{1}, meaning no alignment. -@item -ftree-forwprop -@opindex ftree-forwprop -Perform forward propagation on trees. This flag is enabled by default -at @option{-O} and higher. +Enabled at levels @option{-O2}, @option{-O3}. -@item -ftree-fre -@opindex ftree-fre -Perform full redundancy elimination (FRE) on trees. The difference -between FRE and PRE is that FRE only considers expressions -that are computed on all paths leading to the redundant computation. -This analysis is faster than PRE, though it exposes fewer redundancies. -This flag is enabled by default at @option{-O} and higher. +@item -falign-loops +@itemx -falign-loops=@var{n} +@opindex falign-loops +Align loops to a power-of-two boundary, skipping up to @var{n} bytes +like @option{-falign-functions}. If the loops are +executed many times, this makes up for any execution of the dummy +operations. -@item -ftree-phiprop -@opindex ftree-phiprop -Perform hoisting of loads from conditional pointers on trees. This -pass is enabled by default at @option{-O} and higher. +@option{-fno-align-loops} and @option{-falign-loops=1} are +equivalent and mean that loops are not aligned. -@item -fhoist-adjacent-loads -@opindex fhoist-adjacent-loads -Speculatively hoist loads from both branches of an if-then-else if the -loads are from adjacent locations in the same structure and the target -architecture has a conditional move instruction. This flag is enabled -by default at @option{-O2} and higher. +If @var{n} is not specified or is zero, use a machine-dependent default. -@item -ftree-copy-prop -@opindex ftree-copy-prop -Perform copy propagation on trees. This pass eliminates unnecessary -copy operations. This flag is enabled by default at @option{-O} and -higher. +Enabled at levels @option{-O2}, @option{-O3}. -@item -fipa-pure-const -@opindex fipa-pure-const -Discover which functions are pure or constant. -Enabled by default at @option{-O} and higher. +@item -falign-jumps +@itemx -falign-jumps=@var{n} +@opindex falign-jumps +Align branch targets to a power-of-two boundary, for branch targets +where the targets can only be reached by jumping, skipping up to @var{n} +bytes like @option{-falign-functions}. In this case, no dummy operations +need be executed. -@item -fipa-reference -@opindex fipa-reference -Discover which static variables do not escape the -compilation unit. -Enabled by default at @option{-O} and higher. +@option{-fno-align-jumps} and @option{-falign-jumps=1} are +equivalent and mean that loops are not aligned. -@item -fipa-pta -@opindex fipa-pta -Perform interprocedural pointer analysis and interprocedural modification -and reference analysis. This option can cause excessive memory and -compile-time usage on large compilation units. It is not enabled by -default at any optimization level. +If @var{n} is not specified or is zero, use a machine-dependent default. -@item -fipa-profile -@opindex fipa-profile -Perform interprocedural profile propagation. The functions called only from -cold functions are marked as cold. Also functions executed once (such as -@code{cold}, @code{noreturn}, static constructors or destructors) are identified. Cold -functions and loop less parts of functions executed once are then optimized for -size. -Enabled by default at @option{-O} and higher. +Enabled at levels @option{-O2}, @option{-O3}. -@item -fipa-cp -@opindex fipa-cp -Perform interprocedural constant propagation. -This optimization analyzes the program to determine when values passed -to functions are constants and then optimizes accordingly. -This optimization can substantially increase performance -if the application has constants passed to functions. -This flag is enabled by default at @option{-O2}, @option{-Os} and @option{-O3}. +@item -funit-at-a-time +@opindex funit-at-a-time +This option is left for compatibility reasons. @option{-funit-at-a-time} +has no effect, while @option{-fno-unit-at-a-time} implies +@option{-fno-toplevel-reorder} and @option{-fno-section-anchors}. -@item -fipa-cp-clone -@opindex fipa-cp-clone -Perform function cloning to make interprocedural constant propagation stronger. -When enabled, interprocedural constant propagation performs function cloning -when externally visible function can be called with constant arguments. -Because this optimization can create multiple copies of functions, -it may significantly increase code size -(see @option{--param ipcp-unit-growth=@var{value}}). -This flag is enabled by default at @option{-O3}. +Enabled by default. -@item -fipa-cp-alignment -@opindex -fipa-cp-alignment -When enabled, this optimization propagates alignment of function -parameters to support better vectorization and string operations. +@item -fno-toplevel-reorder +@opindex fno-toplevel-reorder +Do not reorder top-level functions, variables, and @code{asm} +statements. Output them in the same order that they appear in the +input file. When this option is used, unreferenced static variables +are not removed. This option is intended to support existing code +that relies on a particular ordering. For new code, it is better to +use attributes when possible. -This flag is enabled by default at @option{-O2} and @option{-Os}. It -requires that @option{-fipa-cp} is enabled. +Enabled at level @option{-O0}. When disabled explicitly, it also implies +@option{-fno-section-anchors}, which is otherwise enabled at @option{-O0} on some +targets. -@item -fipa-icf -@opindex fipa-icf -Perform Identical Code Folding for functions and read-only variables. -The optimization reduces code size and may disturb unwind stacks by replacing -a function by equivalent one with a different name. The optimization works -more effectively with link time optimization enabled. +@item -fweb +@opindex fweb +Constructs webs as commonly used for register allocation purposes and assign +each web individual pseudo register. This allows the register allocation pass +to operate on pseudos directly, but also strengthens several other optimization +passes, such as CSE, loop optimizer and trivial dead code remover. It can, +however, make debugging impossible, since variables no longer stay in a +``home register''. -Nevertheless the behavior is similar to Gold Linker ICF optimization, GCC ICF -works on different levels and thus the optimizations are not same - there are -equivalences that are found only by GCC and equivalences found only by Gold. +Enabled by default with @option{-funroll-loops}. -This flag is enabled by default at @option{-O2} and @option{-Os}. +@item -fwhole-program +@opindex fwhole-program +Assume that the current compilation unit represents the whole program being +compiled. All public functions and variables with the exception of @code{main} +and those merged by attribute @code{externally_visible} become static functions +and in effect are optimized more aggressively by interprocedural optimizers. -@item -fisolate-erroneous-paths-dereference -@opindex fisolate-erroneous-paths-dereference -Detect paths that trigger erroneous or undefined behavior due to -dereferencing a null pointer. Isolate those paths from the main control -flow and turn the statement with erroneous or undefined behavior into a trap. -This flag is enabled by default at @option{-O2} and higher and depends on -@option{-fdelete-null-pointer-checks} also being enabled. +This option should not be used in combination with @option{-flto}. +Instead relying on a linker plugin should provide safer and more precise +information. -@item -fisolate-erroneous-paths-attribute -@opindex fisolate-erroneous-paths-attribute -Detect paths that trigger erroneous or undefined behavior due a null value -being used in a way forbidden by a @code{returns_nonnull} or @code{nonnull} -attribute. Isolate those paths from the main control flow and turn the -statement with erroneous or undefined behavior into a trap. This is not -currently enabled, but may be enabled by @option{-O2} in the future. +@item -flto[=@var{n}] +@opindex flto +This option runs the standard link-time optimizer. When invoked +with source code, it generates GIMPLE (one of GCC's internal +representations) and writes it to special ELF sections in the object +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. -@item -ftree-sink -@opindex ftree-sink -Perform forward store motion on trees. This flag is -enabled by default at @option{-O} and higher. +To use the link-time optimizer, @option{-flto} and optimization +options should be specified at compile time and during the final link. +For example: -@item -ftree-bit-ccp -@opindex ftree-bit-ccp -Perform sparse conditional bit constant propagation on trees and propagate -pointer alignment information. -This pass only operates on local scalar variables and is enabled by default -at @option{-O} and higher. It requires that @option{-ftree-ccp} is enabled. +@smallexample +gcc -c -O2 -flto foo.c +gcc -c -O2 -flto bar.c +gcc -o myprog -flto -O2 foo.o bar.o +@end smallexample -@item -ftree-ccp -@opindex ftree-ccp -Perform sparse conditional constant propagation (CCP) on trees. This -pass only operates on local scalar variables and is enabled by default -at @option{-O} and higher. +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 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 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 is able to inline functions in +@file{bar.o} into functions in @file{foo.o} and vice-versa. -@item -fssa-backprop -@opindex fssa-backprop -Propagate information about uses of a value up the definition chain -in order to simplify the definitions. For example, this pass strips -sign operations if the sign of a value never matters. The flag is -enabled by default at @option{-O} and higher. +Another (simpler) way to enable link-time optimization is: -@item -fssa-phiopt -@opindex fssa-phiopt -Perform pattern matching on SSA PHI nodes to optimize conditional -code. This pass is enabled by default at @option{-O} and higher. +@smallexample +gcc -o myprog -flto -O2 foo.c bar.c +@end smallexample + +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}. -@item -ftree-switch-conversion -@opindex ftree-switch-conversion -Perform conversion of simple initializations in a switch to -initializations from a scalar array. This flag is enabled by default -at @option{-O2} and higher. +The only important thing to keep in mind is that to enable link-time +optimizations you need to use the GCC driver to perform the link-step. +GCC then automatically performs link-time optimization if any of the +objects involved were compiled with the @option{-flto} command-line option. +You generally +should specify the optimization options to be used for link-time +optimization though GCC tries to be clever at guessing an +optimization level to use from the options used at compile-time +if you fail to specify one at link-time. You can always override +the automatic decision to do link-time optimization at link-time +by passing @option{-fno-lto} to the link command. -@item -ftree-tail-merge -@opindex ftree-tail-merge -Look for identical code sequences. When found, replace one with a jump to the -other. This optimization is known as tail merging or cross jumping. This flag -is enabled by default at @option{-O2} and higher. The compilation time -in this pass can -be limited using @option{max-tail-merge-comparisons} parameter and -@option{max-tail-merge-iterations} parameter. +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 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 leads +to more aggressive optimization decisions. -@item -ftree-dce -@opindex ftree-dce -Perform dead code elimination (DCE) on trees. This flag is enabled by -default at @option{-O} and higher. +When @option{-fuse-linker-plugin} is not enabled then, when a file is +compiled with @option{-flto}, the generated object file is larger than +a regular object file because it contains GIMPLE bytecodes and the usual +final code (see @option{-ffat-lto-objects}. This means that +object files with LTO information can be linked as normal object +files; if @option{-fno-lto} is passed to the linker, no +interprocedural optimizations are applied. Note that when +@option{-fno-fat-lto-objects} is enabled the compile-stage is faster +but you cannot perform a regular, non-LTO link on them. -@item -ftree-builtin-call-dce -@opindex ftree-builtin-call-dce -Perform conditional dead code elimination (DCE) for calls to built-in functions -that may set @code{errno} but are otherwise side-effect free. This flag is -enabled by default at @option{-O2} and higher if @option{-Os} is not also -specified. +Additionally, the optimization flags used to compile individual files +are not necessarily related to those used at link time. For instance, -@item -ftree-dominator-opts -@opindex ftree-dominator-opts -Perform a variety of simple scalar cleanups (constant/copy -propagation, redundancy elimination, range propagation and expression -simplification) based on a dominator tree traversal. This also -performs jump threading (to reduce jumps to jumps). This flag is -enabled by default at @option{-O} and higher. +@smallexample +gcc -c -O0 -ffat-lto-objects -flto foo.c +gcc -c -O0 -ffat-lto-objects -flto bar.c +gcc -o myprog -O3 foo.o bar.o +@end smallexample -@item -ftree-dse -@opindex ftree-dse -Perform dead store elimination (DSE) on trees. A dead store is a store into -a memory location that is later overwritten by another store without -any intervening loads. In this case the earlier store can be deleted. This -flag is enabled by default at @option{-O} and higher. +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 with +@option{-fno-lto}, then @file{myprog} is not optimized. -@item -ftree-ch -@opindex ftree-ch -Perform loop header copying on trees. This is beneficial since it increases -effectiveness of code motion optimizations. It also saves one jump. This flag -is enabled by default at @option{-O} and higher. It is not enabled -for @option{-Os}, since it usually increases code size. +When producing the final binary, 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 automatically selects +which files to optimize in LTO mode and which files to link without +further processing. -@item -ftree-loop-optimize -@opindex ftree-loop-optimize -Perform loop optimizations on trees. This flag is enabled by default -at @option{-O} and higher. +There are some code generation flags preserved by GCC when +generating bytecodes, as they need to be used during the final link +stage. Generally options specified at link-time override those +specified at compile-time. -@item -ftree-loop-linear -@itemx -floop-interchange -@itemx -floop-strip-mine -@itemx -floop-block -@itemx -floop-unroll-and-jam -@opindex ftree-loop-linear -@opindex floop-interchange -@opindex floop-strip-mine -@opindex floop-block -@opindex floop-unroll-and-jam -Perform loop nest optimizations. Same as -@option{-floop-nest-optimize}. To use this code transformation, GCC has -to be configured with @option{--with-isl} to enable the Graphite loop -transformation infrastructure. +If you do not specify an optimization level option @option{-O} at +link-time then GCC computes one based on the optimization levels +used when compiling the object files. The highest optimization +level wins here. -@item -fgraphite-identity -@opindex fgraphite-identity -Enable the identity transformation for graphite. For every SCoP we generate -the polyhedral representation and transform it back to gimple. Using -@option{-fgraphite-identity} we can check the costs or benefits of the -GIMPLE -> GRAPHITE -> GIMPLE transformation. Some minimal optimizations -are also performed by the code generator isl, like index splitting and -dead code elimination in loops. +Currently, the following options and their setting are take from +the first object file that explicitely specified it: +@option{-fPIC}, @option{-fpic}, @option{-fpie}, @option{-fcommon}, +@option{-fexceptions}, @option{-fnon-call-exceptions}, @option{-fgnu-tm} +and all the @option{-m} target flags. -@item -floop-nest-optimize -@opindex floop-nest-optimize -Enable the isl based loop nest optimizer. This is a generic loop nest -optimizer based on the Pluto optimization algorithms. It calculates a loop -structure optimized for data-locality and parallelism. This option -is experimental. +Certain ABI changing flags are required to match in all compilation-units +and trying to override this at link-time with a conflicting value +is ignored. This includes options such as @option{-freg-struct-return} +and @option{-fpcc-struct-return}. -@item -floop-parallelize-all -@opindex floop-parallelize-all -Use the Graphite data dependence analysis to identify loops that can -be parallelized. Parallelize all the loops that can be analyzed to -not contain loop carried dependences without checking that it is -profitable to parallelize the loops. +Other options such as @option{-ffp-contract}, @option{-fno-strict-overflow}, +@option{-fwrapv}, @option{-fno-trapv} or @option{-fno-strict-aliasing} +are passed through to the link stage and merged conservatively for +conflicting translation units. Specifically +@option{-fno-strict-overflow}, @option{-fwrapv} and @option{-fno-trapv} take +precedence and for example @option{-ffp-contract=off} takes precedence +over @option{-ffp-contract=fast}. You can override them at linke-time. -@item -ftree-coalesce-vars -@opindex ftree-coalesce-vars -While transforming the program out of the SSA representation, attempt to -reduce copying by coalescing versions of different user-defined -variables, instead of just compiler temporaries. This may severely -limit the ability to debug an optimized program compiled with -@option{-fno-var-tracking-assignments}. In the negated form, this flag -prevents SSA coalescing of user variables. This option is enabled by -default if optimization is enabled, and it does very little otherwise. +It is recommended that you compile all the files participating in the +same link with the same options and also specify those options at +link time. -@item -ftree-loop-if-convert -@opindex ftree-loop-if-convert -Attempt to transform conditional jumps in the innermost loops to -branch-less equivalents. The intent is to remove control-flow from -the innermost loops in order to improve the ability of the -vectorization pass to handle these loops. This is enabled by default -if vectorization is enabled. +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 run time. Similar +diagnostics may be raised for other languages. -@item -ftree-loop-if-convert-stores -@opindex ftree-loop-if-convert-stores -Attempt to also if-convert conditional jumps containing memory writes. -This transformation can be unsafe for multi-threaded programs as it -transforms conditional memory writes into unconditional memory writes. -For example, -@smallexample -for (i = 0; i < N; i++) - if (cond) - A[i] = expr; -@end smallexample -is transformed to -@smallexample -for (i = 0; i < N; i++) - A[i] = cond ? expr : A[i]; -@end smallexample -potentially producing data races. +Another feature of LTO is that it is possible to apply interprocedural +optimizations on files written in different languages: -@item -ftree-loop-distribution -@opindex ftree-loop-distribution -Perform loop distribution. This flag can improve cache performance on -big loop bodies and allow further loop optimizations, like -parallelization or vectorization, to take place. For example, the loop -@smallexample -DO I = 1, N - A(I) = B(I) + C - D(I) = E(I) * F -ENDDO -@end smallexample -is transformed to @smallexample -DO I = 1, N - A(I) = B(I) + C -ENDDO -DO I = 1, N - D(I) = E(I) * F -ENDDO +gcc -c -flto foo.c +g++ -c -flto bar.cc +gfortran -c -flto baz.f90 +g++ -o myprog -flto -O3 foo.o bar.o baz.o -lgfortran @end smallexample -@item -ftree-loop-distribute-patterns -@opindex ftree-loop-distribute-patterns -Perform loop distribution of patterns that can be code generated with -calls to a library. This flag is enabled by default at @option{-O3}. +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 options as when mixing languages in a +regular (non-LTO) compilation. + +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 plugin support. To create static libraries suitable +for LTO, use @command{gcc-ar} and @command{gcc-ranlib} instead of @command{ar} +and @command{ranlib}; +to show the symbols of object files with GIMPLE bytecode, use +@command{gcc-nm}. Those commands require that @command{ar}, @command{ranlib} +and @command{nm} have been compiled with plugin support. At link time, use the the +flag @option{-fuse-linker-plugin} to ensure that the library participates in +the LTO optimization process: -This pass distributes the initialization loops and generates a call to -memset zero. For example, the loop -@smallexample -DO I = 1, N - A(I) = 0 - B(I) = A(I) + I -ENDDO -@end smallexample -is transformed to @smallexample -DO I = 1, N - A(I) = 0 -ENDDO -DO I = 1, N - B(I) = A(I) + I -ENDDO +gcc -o myprog -O2 -flto -fuse-linker-plugin a.o b.o -lfoo @end smallexample -and the initialization loop is transformed into a call to memset zero. -@item -ftree-loop-im -@opindex ftree-loop-im -Perform loop invariant motion on trees. This pass moves only invariants that -are hard to handle at RTL level (function calls, operations that expand to -nontrivial sequences of insns). With @option{-funswitch-loops} it also moves -operands of conditions that are invariant out of the loop, so that we can use -just trivial invariantness analysis in loop unswitching. The pass also includes -store motion. +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 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. In order to make a static library suitable +for both LTO optimization and usual linkage, compile its object files with +@option{-flto} @option{-ffat-lto-objects}. -@item -ftree-loop-ivcanon -@opindex ftree-loop-ivcanon -Create a canonical counter for number of iterations in loops for which -determining number of iterations requires complicated analysis. Later -optimizations then may determine the number easily. Useful especially -in connection with unrolling. +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 @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}). -@item -fivopts -@opindex fivopts -Perform induction variable optimizations (strength reduction, induction -variable merging and induction variable elimination) on trees. +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 do not work with an older or newer version of GCC. -@item -ftree-parallelize-loops=n -@opindex ftree-parallelize-loops -Parallelize loops, i.e., split their iteration space to run in n threads. -This is only possible for loops whose iterations are independent -and can be arbitrarily reordered. The optimization is only -profitable on multiprocessor machines, for loops that are CPU-intensive, -rather than constrained e.g.@: by memory bandwidth. This option -implies @option{-pthread}, and thus is only supported on targets -that have support for @option{-pthread}. +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 unexpected +results. -@item -ftree-pta -@opindex ftree-pta -Perform function-local points-to analysis on trees. This flag is -enabled by default at @option{-O} and higher. +If you specify the optional @var{n}, the optimization and code +generation done at link time is executed in parallel using @var{n} +parallel jobs by utilizing an installed @command{make} program. The +environment variable @env{MAKE} may be used to override the program +used. The default value for @var{n} is 1. -@item -ftree-sra -@opindex ftree-sra -Perform scalar replacement of aggregates. This pass replaces structure -references with scalars to prevent committing structures to memory too -early. This flag is enabled by default at @option{-O} and higher. +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. +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. -@item -ftree-ter -@opindex ftree-ter -Perform temporary expression replacement during the SSA->normal phase. Single -use/single def temporaries are replaced at their use location with their -defining expression. This results in non-GIMPLE code, but gives the expanders -much more complex trees to work on resulting in better RTL generation. This is -enabled by default at @option{-O} and higher. +@item -flto-partition=@var{alg} +@opindex flto-partition +Specify the partitioning algorithm used by the link-time optimizer. +The value is either @samp{1to1} to specify a partitioning mirroring +the original source files or @samp{balanced} to specify partitioning +into equally sized chunks (whenever possible) or @samp{max} to create +new partition for every symbol where possible. Specifying @samp{none} +as an algorithm disables partitioning and streaming completely. +The default value is @samp{balanced}. While @samp{1to1} can be used +as an workaround for various code ordering issues, the @samp{max} +partitioning is intended for internal testing only. +The value @samp{one} specifies that exactly one partition should be +used while the value @samp{none} bypasses partitioning and executes +the link-time optimization step directly from the WPA phase. -@item -ftree-slsr -@opindex ftree-slsr -Perform straight-line strength reduction on trees. This recognizes related -expressions involving multiplications and replaces them by less expensive -calculations when possible. This is enabled by default at @option{-O} and -higher. +@item -flto-odr-type-merging +@opindex flto-odr-type-merging +Enable streaming of mangled types names of C++ types and their unification +at linktime. This increases size of LTO object files, but enable +diagnostics about One Definition Rule violations. -@item -ftree-vectorize -@opindex ftree-vectorize -Perform vectorization on trees. This flag enables @option{-ftree-loop-vectorize} -and @option{-ftree-slp-vectorize} if not explicitly specified. +@item -flto-compression-level=@var{n} +@opindex flto-compression-level +This option specifies the level of compression used for intermediate +language written to LTO object files, and is only meaningful in +conjunction with LTO mode (@option{-flto}). Valid +values are 0 (no compression) to 9 (maximum compression). Values +outside this range are clamped to either 0 or 9. If the option is not +given, a default balanced compression setting is used. -@item -ftree-loop-vectorize -@opindex ftree-loop-vectorize -Perform loop vectorization on trees. This flag is enabled by default at -@option{-O3} and when @option{-ftree-vectorize} is enabled. +@item -flto-report +@opindex 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 +files in LTO mode (via @option{-flto}). -@item -ftree-slp-vectorize -@opindex ftree-slp-vectorize -Perform basic block vectorization on trees. This flag is enabled by default at -@option{-O3} and when @option{-ftree-vectorize} is enabled. +Disabled by default. -@item -fvect-cost-model=@var{model} -@opindex fvect-cost-model -Alter the cost model used for vectorization. The @var{model} argument -should be one of @samp{unlimited}, @samp{dynamic} or @samp{cheap}. -With the @samp{unlimited} model the vectorized code-path is assumed -to be profitable while with the @samp{dynamic} model a runtime check -guards the vectorized code-path to enable it only for iteration -counts that will likely execute faster than when executing the original -scalar loop. The @samp{cheap} model disables vectorization of -loops where doing so would be cost prohibitive for example due to -required runtime checks for data dependence or alignment but otherwise -is equal to the @samp{dynamic} model. -The default cost model depends on other optimization flags and is -either @samp{dynamic} or @samp{cheap}. +@item -flto-report-wpa +@opindex flto-report-wpa +Like @option{-flto-report}, but only print for the WPA phase of Link +Time Optimization. -@item -fsimd-cost-model=@var{model} -@opindex fsimd-cost-model -Alter the cost model used for vectorization of loops marked with the OpenMP -or Cilk Plus simd directive. The @var{model} argument should be one of -@samp{unlimited}, @samp{dynamic}, @samp{cheap}. All values of @var{model} -have the same meaning as described in @option{-fvect-cost-model} and by -default a cost model defined with @option{-fvect-cost-model} is used. +@item -fuse-linker-plugin +@opindex fuse-linker-plugin +Enables the use of a linker plugin during link-time optimization. This +option relies on plugin support in the linker, which is available in gold +or in GNU ld 2.21 or newer. -@item -ftree-vrp -@opindex ftree-vrp -Perform Value Range Propagation on trees. This is similar to the -constant propagation pass, but instead of values, ranges of values are -propagated. This allows the optimizers to remove unnecessary range -checks like array bound checks and null pointer checks. This is -enabled by default at @option{-O2} and higher. Null pointer check -elimination is only done if @option{-fdelete-null-pointer-checks} is -enabled. +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 @option{-fwhole-program}. +See @option{-flto} for a description of the effect of this flag and how to +use it. -@item -fsplit-paths -@opindex fsplit-paths -Split paths leading to loop backedges. This can improve dead code -elimination and common subexpression elimination. This is enabled by -default at @option{-O2} and above. +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 -fsplit-ivs-in-unroller -@opindex fsplit-ivs-in-unroller -Enables expression of values of induction variables in later iterations -of the unrolled loop using the value in the first iteration. This breaks -long dependency chains, thus improving efficiency of the scheduling passes. +@item -ffat-lto-objects +@opindex ffat-lto-objects +Fat LTO objects are object files that contain both the intermediate language +and the object code. This makes them usable for both LTO linking and normal +linking. This option is effective only when compiling with @option{-flto} +and is ignored at link time. -A combination of @option{-fweb} and CSE is often sufficient to obtain the -same effect. However, that is not reliable in cases where the loop body -is more complicated than a single basic block. It also does not work at all -on some architectures due to restrictions in the CSE pass. +@option{-fno-fat-lto-objects} improves compilation time over plain LTO, but +requires the complete toolchain to be aware of LTO. It requires a linker with +linker plugin support for basic functionality. Additionally, +@command{nm}, @command{ar} and @command{ranlib} +need to support linker plugins to allow a full-featured build environment +(capable of building static libraries etc). GCC provides the @command{gcc-ar}, +@command{gcc-nm}, @command{gcc-ranlib} wrappers to pass the right options +to these tools. With non fat LTO makefiles need to be modified to use them. -This optimization is enabled by default. +The default is @option{-fno-fat-lto-objects} on targets with linker plugin +support. -@item -fvariable-expansion-in-unroller -@opindex fvariable-expansion-in-unroller -With this option, the compiler creates multiple copies of some -local variables when unrolling a loop, which can result in superior code. +@item -fcompare-elim +@opindex fcompare-elim +After register allocation and post-register allocation instruction splitting, +identify arithmetic instructions that compute processor flags similar to a +comparison operation based on that arithmetic. If possible, eliminate the +explicit comparison operation. -@item -fpartial-inlining -@opindex fpartial-inlining -Inline parts of functions. This option has any effect only -when inlining itself is turned on by the @option{-finline-functions} -or @option{-finline-small-functions} options. +This pass only applies to certain targets that cannot explicitly represent +the comparison operation before register allocation is complete. -Enabled at level @option{-O2}. +Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. -@item -fpredictive-commoning -@opindex fpredictive-commoning -Perform predictive commoning optimization, i.e., reusing computations -(especially memory loads and stores) performed in previous -iterations of loops. +@item -fcprop-registers +@opindex fcprop-registers +After register allocation and post-register allocation instruction splitting, +perform a copy-propagation pass to try to reduce scheduling dependencies +and occasionally eliminate the copy. -This option is enabled at level @option{-O3}. +Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. -@item -fprefetch-loop-arrays -@opindex fprefetch-loop-arrays -If supported by the target machine, generate instructions to prefetch -memory to improve the performance of loops that access large arrays. +@item -fprofile-correction +@opindex fprofile-correction +Profiles collected using an instrumented binary for multi-threaded programs may +be inconsistent due to missed counter updates. When this option is specified, +GCC uses heuristics to correct or smooth out such inconsistencies. By +default, GCC emits an error message when an inconsistent profile is detected. + +@item -fprofile-use +@itemx -fprofile-use=@var{path} +@opindex fprofile-use +Enable profile feedback-directed optimizations, +and the following optimizations +which are generally profitable only with profile feedback available: +@option{-fbranch-probabilities}, @option{-fvpt}, +@option{-funroll-loops}, @option{-fpeel-loops}, @option{-ftracer}, +@option{-ftree-vectorize}, and @option{ftree-loop-distribute-patterns}. -This option may generate better or worse code; results are highly -dependent on the structure of loops within the source code. +Before you can use this option, you must first generate profiling information. +@xref{Optimize Options}, for information about the @option{-fprofile-generate} +option. -Disabled at level @option{-Os}. +By default, GCC emits an error message if the feedback profiles do not +match the source code. This error can be turned into a warning by using +@option{-Wcoverage-mismatch}. Note this may result in poorly optimized +code. -@item -fno-peephole -@itemx -fno-peephole2 -@opindex fno-peephole -@opindex fno-peephole2 -Disable any machine-specific peephole optimizations. The difference -between @option{-fno-peephole} and @option{-fno-peephole2} is in how they -are implemented in the compiler; some targets use one, some use the -other, a few use both. +If @var{path} is specified, GCC looks at the @var{path} to find +the profile feedback data files. See @option{-fprofile-dir}. -@option{-fpeephole} is enabled by default. -@option{-fpeephole2} enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. +@item -fauto-profile +@itemx -fauto-profile=@var{path} +@opindex fauto-profile +Enable sampling-based feedback-directed optimizations, +and the following optimizations +which are generally profitable only with profile feedback available: +@option{-fbranch-probabilities}, @option{-fvpt}, +@option{-funroll-loops}, @option{-fpeel-loops}, @option{-ftracer}, +@option{-ftree-vectorize}, +@option{-finline-functions}, @option{-fipa-cp}, @option{-fipa-cp-clone}, +@option{-fpredictive-commoning}, @option{-funswitch-loops}, +@option{-fgcse-after-reload}, and @option{-ftree-loop-distribute-patterns}. -@item -fno-guess-branch-probability -@opindex fno-guess-branch-probability -Do not guess branch probabilities using heuristics. +@var{path} is the name of a file containing AutoFDO profile information. +If omitted, it defaults to @file{fbdata.afdo} in the current directory. -GCC uses heuristics to guess branch probabilities if they are -not provided by profiling feedback (@option{-fprofile-arcs}). These -heuristics are based on the control flow graph. If some branch probabilities -are specified by @code{__builtin_expect}, then the heuristics are -used to guess branch probabilities for the rest of the control flow graph, -taking the @code{__builtin_expect} info into account. The interactions -between the heuristics and @code{__builtin_expect} can be complex, and in -some cases, it may be useful to disable the heuristics so that the effects -of @code{__builtin_expect} are easier to understand. +Producing an AutoFDO profile data file requires running your program +with the @command{perf} utility on a supported GNU/Linux target system. +For more information, see @uref{https://perf.wiki.kernel.org/}. -The default is @option{-fguess-branch-probability} at levels -@option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. +E.g. +@smallexample +perf record -e br_inst_retired:near_taken -b -o perf.data \ + -- your_program +@end smallexample -@item -freorder-blocks -@opindex freorder-blocks -Reorder basic blocks in the compiled function in order to reduce number of -taken branches and improve code locality. +Then use the @command{create_gcov} tool to convert the raw profile data +to a format that can be used by GCC.@ You must also supply the +unstripped binary for your program to this tool. +See @uref{https://github.com/google/autofdo}. -Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. +E.g. +@smallexample +create_gcov --binary=your_program.unstripped --profile=perf.data \ + --gcov=profile.afdo +@end smallexample +@end table -@item -freorder-blocks-algorithm=@var{algorithm} -@opindex freorder-blocks-algorithm -Use the specified algorithm for basic block reordering. The -@var{algorithm} argument can be @samp{simple}, which does not increase -code size (except sometimes due to secondary effects like alignment), -or @samp{stc}, the ``software trace cache'' algorithm, which tries to -put all often executed code together, minimizing the number of branches -executed by making extra copies of code. +The following options control compiler behavior regarding floating-point +arithmetic. These options trade off between speed and +correctness. All must be specifically enabled. -The default is @samp{simple} at levels @option{-O}, @option{-Os}, and -@samp{stc} at levels @option{-O2}, @option{-O3}. +@table @gcctabopt +@item -ffloat-store +@opindex ffloat-store +Do not store floating-point variables in registers, and inhibit other +options that might change whether a floating-point value is taken from a +register or memory. -@item -freorder-blocks-and-partition -@opindex freorder-blocks-and-partition -In addition to reordering basic blocks in the compiled function, in order -to reduce number of taken branches, partitions hot and cold basic blocks -into separate sections of the assembly and .o files, to improve -paging and cache locality performance. +@cindex floating-point precision +This option prevents undesirable excess precision on machines such as +the 68000 where the floating registers (of the 68881) keep more +precision than a @code{double} is supposed to have. Similarly for the +x86 architecture. For most programs, the excess precision does only +good, but a few programs rely on the precise definition of IEEE floating +point. Use @option{-ffloat-store} for such programs, after modifying +them to store all pertinent intermediate computations into variables. -This optimization is automatically turned off in the presence of -exception handling, for linkonce sections, for functions with a user-defined -section attribute and on any architecture that does not support named -sections. +@item -fexcess-precision=@var{style} +@opindex fexcess-precision +This option allows further control over excess precision on machines +where floating-point registers have more precision than the IEEE +@code{float} and @code{double} types and the processor does not +support operations rounding to those types. By default, +@option{-fexcess-precision=fast} is in effect; this means that +operations are carried out in the precision of the registers and that +it is unpredictable when rounding to the types specified in the source +code takes place. When compiling C, if +@option{-fexcess-precision=standard} is specified then excess +precision follows the rules specified in ISO C99; in particular, +both casts and assignments cause values to be rounded to their +semantic types (whereas @option{-ffloat-store} only affects +assignments). This option is enabled by default for C if a strict +conformance option such as @option{-std=c99} is used. -Enabled for x86 at levels @option{-O2}, @option{-O3}. +@opindex mfpmath +@option{-fexcess-precision=standard} is not implemented for languages +other than C, and has no effect if +@option{-funsafe-math-optimizations} or @option{-ffast-math} is +specified. On the x86, it also has no effect if @option{-mfpmath=sse} +or @option{-mfpmath=sse+387} is specified; in the former case, IEEE +semantics apply without excess precision, and in the latter, rounding +is unpredictable. -@item -freorder-functions -@opindex freorder-functions -Reorder functions in the object file in order to -improve code locality. This is implemented by using special -subsections @code{.text.hot} for most frequently executed functions and -@code{.text.unlikely} for unlikely executed functions. Reordering is done by -the linker so object file format must support named sections and linker must -place them in a reasonable way. +@item -ffast-math +@opindex ffast-math +Sets the options @option{-fno-math-errno}, @option{-funsafe-math-optimizations}, +@option{-ffinite-math-only}, @option{-fno-rounding-math}, +@option{-fno-signaling-nans} and @option{-fcx-limited-range}. -Also profile feedback must be available to make this option effective. See -@option{-fprofile-arcs} for details. +This option causes the preprocessor macro @code{__FAST_MATH__} to be defined. -Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. +This option is not turned on by any @option{-O} option besides +@option{-Ofast} since it can result in incorrect output for programs +that depend on an exact implementation of IEEE or ISO rules/specifications +for math functions. It may, however, yield faster code for programs +that do not require the guarantees of these specifications. -@item -fstrict-aliasing -@opindex fstrict-aliasing -Allow the compiler to assume the strictest aliasing rules applicable to -the language being compiled. For C (and C++), this activates -optimizations based on the type of expressions. In particular, an -object of one type is assumed never to reside at the same address as an -object of a different type, unless the types are almost the same. For -example, an @code{unsigned int} can alias an @code{int}, but not a -@code{void*} or a @code{double}. A character type may alias any other -type. +@item -fno-math-errno +@opindex fno-math-errno +Do not set @code{errno} after calling math functions that are executed +with a single instruction, e.g., @code{sqrt}. A program that relies on +IEEE exceptions for math error handling may want to use this flag +for speed while maintaining IEEE arithmetic compatibility. -@anchor{Type-punning}Pay special attention to code like this: -@smallexample -union a_union @{ - int i; - double d; -@}; +This option is not turned on by any @option{-O} option since +it can result in incorrect output for programs that depend on +an exact implementation of IEEE or ISO rules/specifications for +math functions. It may, however, yield faster code for programs +that do not require the guarantees of these specifications. -int f() @{ - union a_union t; - t.d = 3.0; - return t.i; -@} -@end smallexample -The practice of reading from a different union member than the one most -recently written to (called ``type-punning'') is common. Even with -@option{-fstrict-aliasing}, type-punning is allowed, provided the memory -is accessed through the union type. So, the code above works as -expected. @xref{Structures unions enumerations and bit-fields -implementation}. However, this code might not: -@smallexample -int f() @{ - union a_union t; - int* ip; - t.d = 3.0; - ip = &t.i; - return *ip; -@} -@end smallexample +The default is @option{-fmath-errno}. -Similarly, access by taking the address, casting the resulting pointer -and dereferencing the result has undefined behavior, even if the cast -uses a union type, e.g.: -@smallexample -int f() @{ - double d = 3.0; - return ((union a_union *) &d)->i; -@} -@end smallexample +On Darwin systems, the math library never sets @code{errno}. There is +therefore no reason for the compiler to consider the possibility that +it might, and @option{-fno-math-errno} is the default. -The @option{-fstrict-aliasing} option is enabled at levels -@option{-O2}, @option{-O3}, @option{-Os}. +@item -funsafe-math-optimizations +@opindex funsafe-math-optimizations -@item -fstrict-overflow -@opindex fstrict-overflow -Allow the compiler to assume strict signed overflow rules, depending -on the language being compiled. For C (and C++) this means that -overflow when doing arithmetic with signed numbers is undefined, which -means that the compiler may assume that it does not happen. This -permits various optimizations. For example, the compiler assumes -that an expression like @code{i + 10 > i} is always true for -signed @code{i}. This assumption is only valid if signed overflow is -undefined, as the expression is false if @code{i + 10} overflows when -using twos complement arithmetic. When this option is in effect any -attempt to determine whether an operation on signed numbers -overflows must be written carefully to not actually involve overflow. +Allow optimizations for floating-point arithmetic that (a) assume +that arguments and results are valid and (b) may violate IEEE or +ANSI standards. When used at link-time, it may include libraries +or startup files that change the default FPU control word or other +similar optimizations. -This option also allows the compiler to assume strict pointer -semantics: given a pointer to an object, if adding an offset to that -pointer does not produce a pointer to the same object, the addition is -undefined. This permits the compiler to conclude that @code{p + u > -p} is always true for a pointer @code{p} and unsigned integer -@code{u}. This assumption is only valid because pointer wraparound is -undefined, as the expression is false if @code{p + u} overflows using -twos complement arithmetic. +This option is not turned on by any @option{-O} option since +it can result in incorrect output for programs that depend on +an exact implementation of IEEE or ISO rules/specifications for +math functions. It may, however, yield faster code for programs +that do not require the guarantees of these specifications. +Enables @option{-fno-signed-zeros}, @option{-fno-trapping-math}, +@option{-fassociative-math} and @option{-freciprocal-math}. -See also the @option{-fwrapv} option. Using @option{-fwrapv} means -that integer signed overflow is fully defined: it wraps. When -@option{-fwrapv} is used, there is no difference between -@option{-fstrict-overflow} and @option{-fno-strict-overflow} for -integers. With @option{-fwrapv} certain types of overflow are -permitted. For example, if the compiler gets an overflow when doing -arithmetic on constants, the overflowed value can still be used with -@option{-fwrapv}, but not otherwise. +The default is @option{-fno-unsafe-math-optimizations}. -The @option{-fstrict-overflow} option is enabled at levels -@option{-O2}, @option{-O3}, @option{-Os}. +@item -fassociative-math +@opindex fassociative-math -@item -falign-functions -@itemx -falign-functions=@var{n} -@opindex falign-functions -Align the start of functions to the next power-of-two greater than -@var{n}, skipping up to @var{n} bytes. For instance, -@option{-falign-functions=32} aligns functions to the next 32-byte -boundary, but @option{-falign-functions=24} aligns to the next -32-byte boundary only if this can be done by skipping 23 bytes or less. +Allow re-association of operands in series of floating-point operations. +This violates the ISO C and C++ language standard by possibly changing +computation result. NOTE: re-ordering may change the sign of zero as +well as ignore NaNs and inhibit or create underflow or overflow (and +thus cannot be used on code that relies on rounding behavior like +@code{(x + 2**52) - 2**52}. May also reorder floating-point comparisons +and thus may not be used when ordered comparisons are required. +This option requires that both @option{-fno-signed-zeros} and +@option{-fno-trapping-math} be in effect. Moreover, it doesn't make +much sense with @option{-frounding-math}. For Fortran the option +is automatically enabled when both @option{-fno-signed-zeros} and +@option{-fno-trapping-math} are in effect. -@option{-fno-align-functions} and @option{-falign-functions=1} are -equivalent and mean that functions are not aligned. +The default is @option{-fno-associative-math}. -Some assemblers only support this flag when @var{n} is a power of two; -in that case, it is rounded up. +@item -freciprocal-math +@opindex freciprocal-math -If @var{n} is not specified or is zero, use a machine-dependent default. +Allow the reciprocal of a value to be used instead of dividing by +the value if this enables optimizations. For example @code{x / y} +can be replaced with @code{x * (1/y)}, which is useful if @code{(1/y)} +is subject to common subexpression elimination. Note that this loses +precision and increases the number of flops operating on the value. -Enabled at levels @option{-O2}, @option{-O3}. +The default is @option{-fno-reciprocal-math}. -@item -falign-labels -@itemx -falign-labels=@var{n} -@opindex falign-labels -Align all branch targets to a power-of-two boundary, skipping up to -@var{n} bytes like @option{-falign-functions}. This option can easily -make code slower, because it must insert dummy operations for when the -branch target is reached in the usual flow of the code. +@item -ffinite-math-only +@opindex ffinite-math-only +Allow optimizations for floating-point arithmetic that assume +that arguments and results are not NaNs or +-Infs. -@option{-fno-align-labels} and @option{-falign-labels=1} are -equivalent and mean that labels are not aligned. +This option is not turned on by any @option{-O} option since +it can result in incorrect output for programs that depend on +an exact implementation of IEEE or ISO rules/specifications for +math functions. It may, however, yield faster code for programs +that do not require the guarantees of these specifications. -If @option{-falign-loops} or @option{-falign-jumps} are applicable and -are greater than this value, then their values are used instead. +The default is @option{-fno-finite-math-only}. -If @var{n} is not specified or is zero, use a machine-dependent default -which is very likely to be @samp{1}, meaning no alignment. +@item -fno-signed-zeros +@opindex fno-signed-zeros +Allow optimizations for floating-point arithmetic that ignore the +signedness of zero. IEEE arithmetic specifies the behavior of +distinct +0.0 and @minus{}0.0 values, which then prohibits simplification +of expressions such as x+0.0 or 0.0*x (even with @option{-ffinite-math-only}). +This option implies that the sign of a zero result isn't significant. -Enabled at levels @option{-O2}, @option{-O3}. +The default is @option{-fsigned-zeros}. -@item -falign-loops -@itemx -falign-loops=@var{n} -@opindex falign-loops -Align loops to a power-of-two boundary, skipping up to @var{n} bytes -like @option{-falign-functions}. If the loops are -executed many times, this makes up for any execution of the dummy -operations. +@item -fno-trapping-math +@opindex fno-trapping-math +Compile code assuming that floating-point operations cannot generate +user-visible traps. These traps include division by zero, overflow, +underflow, inexact result and invalid operation. This option requires +that @option{-fno-signaling-nans} be in effect. Setting this option may +allow faster code if one relies on ``non-stop'' IEEE arithmetic, for example. -@option{-fno-align-loops} and @option{-falign-loops=1} are -equivalent and mean that loops are not aligned. +This option should never be turned on by any @option{-O} option since +it can result in incorrect output for programs that depend on +an exact implementation of IEEE or ISO rules/specifications for +math functions. -If @var{n} is not specified or is zero, use a machine-dependent default. +The default is @option{-ftrapping-math}. -Enabled at levels @option{-O2}, @option{-O3}. +@item -frounding-math +@opindex frounding-math +Disable transformations and optimizations that assume default floating-point +rounding behavior. This is round-to-zero for all floating point +to integer conversions, and round-to-nearest for all other arithmetic +truncations. This option should be specified for programs that change +the FP rounding mode dynamically, or that may be executed with a +non-default rounding mode. This option disables constant folding of +floating-point expressions at compile time (which may be affected by +rounding mode) and arithmetic transformations that are unsafe in the +presence of sign-dependent rounding modes. -@item -falign-jumps -@itemx -falign-jumps=@var{n} -@opindex falign-jumps -Align branch targets to a power-of-two boundary, for branch targets -where the targets can only be reached by jumping, skipping up to @var{n} -bytes like @option{-falign-functions}. In this case, no dummy operations -need be executed. +The default is @option{-fno-rounding-math}. -@option{-fno-align-jumps} and @option{-falign-jumps=1} are -equivalent and mean that loops are not aligned. +This option is experimental and does not currently guarantee to +disable all GCC optimizations that are affected by rounding mode. +Future versions of GCC may provide finer control of this setting +using C99's @code{FENV_ACCESS} pragma. This command-line option +will be used to specify the default state for @code{FENV_ACCESS}. -If @var{n} is not specified or is zero, use a machine-dependent default. +@item -fsignaling-nans +@opindex fsignaling-nans +Compile code assuming that IEEE signaling NaNs may generate user-visible +traps during floating-point operations. Setting this option disables +optimizations that may change the number of exceptions visible with +signaling NaNs. This option implies @option{-ftrapping-math}. -Enabled at levels @option{-O2}, @option{-O3}. +This option causes the preprocessor macro @code{__SUPPORT_SNAN__} to +be defined. -@item -funit-at-a-time -@opindex funit-at-a-time -This option is left for compatibility reasons. @option{-funit-at-a-time} -has no effect, while @option{-fno-unit-at-a-time} implies -@option{-fno-toplevel-reorder} and @option{-fno-section-anchors}. +The default is @option{-fno-signaling-nans}. -Enabled by default. +This option is experimental and does not currently guarantee to +disable all GCC optimizations that affect signaling NaN behavior. -@item -fno-toplevel-reorder -@opindex fno-toplevel-reorder -Do not reorder top-level functions, variables, and @code{asm} -statements. Output them in the same order that they appear in the -input file. When this option is used, unreferenced static variables -are not removed. This option is intended to support existing code -that relies on a particular ordering. For new code, it is better to -use attributes when possible. +@item -fsingle-precision-constant +@opindex fsingle-precision-constant +Treat floating-point constants as single precision instead of +implicitly converting them to double-precision constants. -Enabled at level @option{-O0}. When disabled explicitly, it also implies -@option{-fno-section-anchors}, which is otherwise enabled at @option{-O0} on some -targets. +@item -fcx-limited-range +@opindex fcx-limited-range +When enabled, this option states that a range reduction step is not +needed when performing complex division. Also, there is no checking +whether the result of a complex multiplication or division is @code{NaN ++ I*NaN}, with an attempt to rescue the situation in that case. The +default is @option{-fno-cx-limited-range}, but is enabled by +@option{-ffast-math}. -@item -fweb -@opindex fweb -Constructs webs as commonly used for register allocation purposes and assign -each web individual pseudo register. This allows the register allocation pass -to operate on pseudos directly, but also strengthens several other optimization -passes, such as CSE, loop optimizer and trivial dead code remover. It can, -however, make debugging impossible, since variables no longer stay in a -``home register''. +This option controls the default setting of the ISO C99 +@code{CX_LIMITED_RANGE} pragma. Nevertheless, the option applies to +all languages. -Enabled by default with @option{-funroll-loops}. +@item -fcx-fortran-rules +@opindex fcx-fortran-rules +Complex multiplication and division follow Fortran rules. Range +reduction is done as part of complex division, but there is no checking +whether the result of a complex multiplication or division is @code{NaN ++ I*NaN}, with an attempt to rescue the situation in that case. -@item -fwhole-program -@opindex fwhole-program -Assume that the current compilation unit represents the whole program being -compiled. All public functions and variables with the exception of @code{main} -and those merged by attribute @code{externally_visible} become static functions -and in effect are optimized more aggressively by interprocedural optimizers. +The default is @option{-fno-cx-fortran-rules}. -This option should not be used in combination with @option{-flto}. -Instead relying on a linker plugin should provide safer and more precise -information. +@end table -@item -flto[=@var{n}] -@opindex flto -This option runs the standard link-time optimizer. When invoked -with source code, it generates GIMPLE (one of GCC's internal -representations) and writes it to special ELF sections in the object -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. +The following options control optimizations that may improve +performance, but are not enabled by any @option{-O} options. This +section includes experimental options that may produce broken code. -To use the link-time optimizer, @option{-flto} and optimization -options should be specified at compile time and during the final link. -For example: +@table @gcctabopt +@item -fbranch-probabilities +@opindex fbranch-probabilities +After running a program compiled with @option{-fprofile-arcs} +(@pxref{Instrumentation Options}), +you can compile it a second time using +@option{-fbranch-probabilities}, to improve optimizations based on +the number of times each branch was taken. When a program +compiled with @option{-fprofile-arcs} exits, it saves arc execution +counts to a file called @file{@var{sourcename}.gcda} for each source +file. The information in this data file is very dependent on the +structure of the generated code, so you must use the same source code +and the same optimization options for both compilations. -@smallexample -gcc -c -O2 -flto foo.c -gcc -c -O2 -flto bar.c -gcc -o myprog -flto -O2 foo.o bar.o -@end smallexample +With @option{-fbranch-probabilities}, GCC puts a +@samp{REG_BR_PROB} note on each @samp{JUMP_INSN} and @samp{CALL_INSN}. +These can be used to improve optimization. Currently, they are only +used in one place: in @file{reorg.c}, instead of guessing which path a +branch is most likely to take, the @samp{REG_BR_PROB} values are used to +exactly determine which path is taken more often. -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 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 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 is able to inline functions in -@file{bar.o} into functions in @file{foo.o} and vice-versa. +@item -fprofile-values +@opindex fprofile-values +If combined with @option{-fprofile-arcs}, it adds code so that some +data about values of expressions in the program is gathered. + +With @option{-fbranch-probabilities}, it reads back the data gathered +from profiling values of expressions for usage in optimizations. + +Enabled with @option{-fprofile-generate} and @option{-fprofile-use}. -Another (simpler) way to enable link-time optimization is: +@item -fprofile-reorder-functions +@opindex fprofile-reorder-functions +Function reordering based on profile instrumentation collects +first time of execution of a function and orders these functions +in ascending order. -@smallexample -gcc -o myprog -flto -O2 foo.c bar.c -@end smallexample +Enabled with @option{-fprofile-use}. -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}. +@item -fvpt +@opindex fvpt +If combined with @option{-fprofile-arcs}, this option instructs the compiler +to add code to gather information about values of expressions. -The only important thing to keep in mind is that to enable link-time -optimizations you need to use the GCC driver to perform the link-step. -GCC then automatically performs link-time optimization if any of the -objects involved were compiled with the @option{-flto} command-line option. -You generally -should specify the optimization options to be used for link-time -optimization though GCC tries to be clever at guessing an -optimization level to use from the options used at compile-time -if you fail to specify one at link-time. You can always override -the automatic decision to do link-time optimization at link-time -by passing @option{-fno-lto} to the link command. +With @option{-fbranch-probabilities}, it reads back the data gathered +and actually performs the optimizations based on them. +Currently the optimizations include specialization of division operations +using the knowledge about the value of the denominator. -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 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 leads -to more aggressive optimization decisions. +@item -frename-registers +@opindex frename-registers +Attempt to avoid false dependencies in scheduled code by making use +of registers left over after register allocation. This optimization +most benefits processors with lots of registers. Depending on the +debug information format adopted by the target, however, it can +make debugging impossible, since variables no longer stay in +a ``home register''. -When @option{-fuse-linker-plugin} is not enabled then, when a file is -compiled with @option{-flto}, the generated object file is larger than -a regular object file because it contains GIMPLE bytecodes and the usual -final code (see @option{-ffat-lto-objects}. This means that -object files with LTO information can be linked as normal object -files; if @option{-fno-lto} is passed to the linker, no -interprocedural optimizations are applied. Note that when -@option{-fno-fat-lto-objects} is enabled the compile-stage is faster -but you cannot perform a regular, non-LTO link on them. +Enabled by default with @option{-funroll-loops} and @option{-fpeel-loops}. -Additionally, the optimization flags used to compile individual files -are not necessarily related to those used at link time. For instance, +@item -fschedule-fusion +@opindex fschedule-fusion +Performs a target dependent pass over the instruction stream to schedule +instructions of same type together because target machine can execute them +more efficiently if they are adjacent to each other in the instruction flow. -@smallexample -gcc -c -O0 -ffat-lto-objects -flto foo.c -gcc -c -O0 -ffat-lto-objects -flto bar.c -gcc -o myprog -O3 foo.o bar.o -@end smallexample +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. -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 with -@option{-fno-lto}, then @file{myprog} is not optimized. +@item -ftracer +@opindex ftracer +Perform tail duplication to enlarge superblock size. This transformation +simplifies the control flow of the function allowing other optimizations to do +a better job. -When producing the final binary, 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 automatically selects -which files to optimize in LTO mode and which files to link without -further processing. +Enabled with @option{-fprofile-use}. -There are some code generation flags preserved by GCC when -generating bytecodes, as they need to be used during the final link -stage. Generally options specified at link-time override those -specified at compile-time. +@item -funroll-loops +@opindex funroll-loops +Unroll loops whose number of iterations can be determined at compile time or +upon entry to the loop. @option{-funroll-loops} implies +@option{-frerun-cse-after-loop}, @option{-fweb} and @option{-frename-registers}. +It also turns on complete loop peeling (i.e.@: complete removal of loops with +a small constant number of iterations). This option makes code larger, and may +or may not make it run faster. -If you do not specify an optimization level option @option{-O} at -link-time then GCC computes one based on the optimization levels -used when compiling the object files. The highest optimization -level wins here. +Enabled with @option{-fprofile-use}. -Currently, the following options and their setting are take from -the first object file that explicitely specified it: -@option{-fPIC}, @option{-fpic}, @option{-fpie}, @option{-fcommon}, -@option{-fexceptions}, @option{-fnon-call-exceptions}, @option{-fgnu-tm} -and all the @option{-m} target flags. +@item -funroll-all-loops +@opindex funroll-all-loops +Unroll all loops, even if their number of iterations is uncertain when +the loop is entered. This usually makes programs run more slowly. +@option{-funroll-all-loops} implies the same options as +@option{-funroll-loops}. -Certain ABI changing flags are required to match in all compilation-units -and trying to override this at link-time with a conflicting value -is ignored. This includes options such as @option{-freg-struct-return} -and @option{-fpcc-struct-return}. +@item -fpeel-loops +@opindex fpeel-loops +Peels loops for which there is enough information that they do not +roll much (from profile feedback). It also turns on complete loop peeling +(i.e.@: complete removal of loops with small constant number of iterations). -Other options such as @option{-ffp-contract}, @option{-fno-strict-overflow}, -@option{-fwrapv}, @option{-fno-trapv} or @option{-fno-strict-aliasing} -are passed through to the link stage and merged conservatively for -conflicting translation units. Specifically -@option{-fno-strict-overflow}, @option{-fwrapv} and @option{-fno-trapv} take -precedence and for example @option{-ffp-contract=off} takes precedence -over @option{-ffp-contract=fast}. You can override them at linke-time. +Enabled with @option{-fprofile-use}. -It is recommended that you compile all the files participating in the -same link with the same options and also specify those options at -link time. +@item -fmove-loop-invariants +@opindex fmove-loop-invariants +Enables the loop invariant motion pass in the RTL loop optimizer. Enabled +at level @option{-O1} -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 run time. Similar -diagnostics may be raised for other languages. +@item -funswitch-loops +@opindex funswitch-loops +Move branches with loop invariant conditions out of the loop, with duplicates +of the loop on both branches (modified according to result of the condition). -Another feature of LTO is that it is possible to apply interprocedural -optimizations on files written in different languages: +@item -ffunction-sections +@itemx -fdata-sections +@opindex ffunction-sections +@opindex fdata-sections +Place each function or data item into its own section in the output +file if the target supports arbitrary sections. The name of the +function or the name of the data item determines the section's name +in the output file. -@smallexample -gcc -c -flto foo.c -g++ -c -flto bar.cc -gfortran -c -flto baz.f90 -g++ -o myprog -flto -O3 foo.o bar.o baz.o -lgfortran -@end smallexample +Use these options on systems where the linker can perform optimizations +to improve locality of reference in the instruction space. Most systems +using the ELF object format and SPARC processors running Solaris 2 have +linkers with such optimizations. AIX may have these optimizations in +the future. -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 options as when mixing languages in a -regular (non-LTO) compilation. +Only use these options when there are significant benefits from doing +so. When you specify these options, the assembler and linker +create larger object and executable files and are also slower. +You cannot use @command{gprof} on all systems if you +specify this option, and you may have problems with debugging if +you specify both this option and @option{-g}. -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 plugin support. To create static libraries suitable -for LTO, use @command{gcc-ar} and @command{gcc-ranlib} instead of @command{ar} -and @command{ranlib}; -to show the symbols of object files with GIMPLE bytecode, use -@command{gcc-nm}. Those commands require that @command{ar}, @command{ranlib} -and @command{nm} have been compiled with plugin support. At link time, use the the -flag @option{-fuse-linker-plugin} to ensure that the library participates in -the LTO optimization process: +@item -fbranch-target-load-optimize +@opindex fbranch-target-load-optimize +Perform branch target register load optimization before prologue / epilogue +threading. +The use of target registers can typically be exposed only during reload, +thus hoisting loads out of loops and doing inter-block scheduling needs +a separate optimization pass. -@smallexample -gcc -o myprog -O2 -flto -fuse-linker-plugin a.o b.o -lfoo -@end smallexample +@item -fbranch-target-load-optimize2 +@opindex fbranch-target-load-optimize2 +Perform branch target register load optimization after prologue / epilogue +threading. -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. +@item -fbtr-bb-exclusive +@opindex fbtr-bb-exclusive +When performing branch target register load optimization, don't reuse +branch target registers within any basic block. -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. In order to make a static library suitable -for both LTO optimization and usual linkage, compile its object files with -@option{-flto} @option{-ffat-lto-objects}. +@item -fstdarg-opt +@opindex fstdarg-opt +Optimize the prologue of variadic argument functions with respect to usage of +those arguments. -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 @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}). +@item -fsection-anchors +@opindex fsection-anchors +Try to reduce the number of symbolic address calculations by using +shared ``anchor'' symbols to address nearby objects. This transformation +can help to reduce the number of GOT entries and GOT accesses on some +targets. -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 do not work with an older or newer version of GCC. +For example, the implementation of the following function @code{foo}: -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 unexpected -results. +@smallexample +static int a, b, c; +int foo (void) @{ return a + b + c; @} +@end smallexample + +@noindent +usually calculates the addresses of all three variables, but if you +compile it with @option{-fsection-anchors}, it accesses the variables +from a common anchor point instead. The effect is similar to the +following pseudocode (which isn't valid C): -If you specify the optional @var{n}, the optimization and code -generation done at link time is executed in parallel using @var{n} -parallel jobs by utilizing an installed @command{make} program. The -environment variable @env{MAKE} may be used to override the program -used. The default value for @var{n} is 1. +@smallexample +int foo (void) +@{ + register int *xr = &x; + return xr[&a - &x] + xr[&b - &x] + xr[&c - &x]; +@} +@end smallexample -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. -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. +Not all targets support this option. -@item -flto-partition=@var{alg} -@opindex flto-partition -Specify the partitioning algorithm used by the link-time optimizer. -The value is either @samp{1to1} to specify a partitioning mirroring -the original source files or @samp{balanced} to specify partitioning -into equally sized chunks (whenever possible) or @samp{max} to create -new partition for every symbol where possible. Specifying @samp{none} -as an algorithm disables partitioning and streaming completely. -The default value is @samp{balanced}. While @samp{1to1} can be used -as an workaround for various code ordering issues, the @samp{max} -partitioning is intended for internal testing only. -The value @samp{one} specifies that exactly one partition should be -used while the value @samp{none} bypasses partitioning and executes -the link-time optimization step directly from the WPA phase. +@item --param @var{name}=@var{value} +@opindex param +In some places, GCC uses various constants to control the amount of +optimization that is done. For example, GCC does not inline functions +that contain more than a certain number of instructions. You can +control some of these constants on the command line using the +@option{--param} option. -@item -flto-odr-type-merging -@opindex flto-odr-type-merging -Enable streaming of mangled types names of C++ types and their unification -at linktime. This increases size of LTO object files, but enable -diagnostics about One Definition Rule violations. +The names of specific parameters, and the meaning of the values, are +tied to the internals of the compiler, and are subject to change +without notice in future releases. -@item -flto-compression-level=@var{n} -@opindex flto-compression-level -This option specifies the level of compression used for intermediate -language written to LTO object files, and is only meaningful in -conjunction with LTO mode (@option{-flto}). Valid -values are 0 (no compression) to 9 (maximum compression). Values -outside this range are clamped to either 0 or 9. If the option is not -given, a default balanced compression setting is used. +In each case, the @var{value} is an integer. The allowable choices for +@var{name} are: -@item -flto-report -@opindex 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 -files in LTO mode (via @option{-flto}). +@table @gcctabopt +@item predictable-branch-outcome +When branch is predicted to be taken with probability lower than this threshold +(in percent), then it is considered well predictable. The default is 10. -Disabled by default. +@item max-rtl-if-conversion-insns +RTL if-conversion tries to remove conditional branches around a block and +replace them with conditionally executed instructions. This parameter +gives the maximum number of instructions in a block which should be +considered for if-conversion. The default is 10, though the compiler will +also use other heuristics to decide whether if-conversion is likely to be +profitable. -@item -flto-report-wpa -@opindex flto-report-wpa -Like @option{-flto-report}, but only print for the WPA phase of Link -Time Optimization. +@item max-crossjump-edges +The maximum number of incoming edges to consider for cross-jumping. +The algorithm used by @option{-fcrossjumping} is @math{O(N^2)} in +the number of edges incoming to each block. Increasing values mean +more aggressive optimization, making the compilation time increase with +probably small improvement in executable size. -@item -fuse-linker-plugin -@opindex fuse-linker-plugin -Enables the use of a linker plugin during link-time optimization. This -option relies on plugin support in the linker, which is available in gold -or in GNU ld 2.21 or newer. +@item min-crossjump-insns +The minimum number of instructions that must be matched at the end +of two blocks before cross-jumping is performed on them. This +value is ignored in the case where all instructions in the block being +cross-jumped from are matched. The default value is 5. -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 @option{-fwhole-program}. -See @option{-flto} for a description of the effect of this flag and how to -use it. +@item max-grow-copy-bb-insns +The maximum code size expansion factor when copying basic blocks +instead of jumping. The expansion is relative to a jump instruction. +The default value is 8. -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 max-goto-duplication-insns +The maximum number of instructions to duplicate to a block that jumps +to a computed goto. To avoid @math{O(N^2)} behavior in a number of +passes, GCC factors computed gotos early in the compilation process, +and unfactors them as late as possible. Only computed jumps at the +end of a basic blocks with no more than max-goto-duplication-insns are +unfactored. The default value is 8. -@item -ffat-lto-objects -@opindex ffat-lto-objects -Fat LTO objects are object files that contain both the intermediate language -and the object code. This makes them usable for both LTO linking and normal -linking. This option is effective only when compiling with @option{-flto} -and is ignored at link time. +@item max-delay-slot-insn-search +The maximum number of instructions to consider when looking for an +instruction to fill a delay slot. If more than this arbitrary number of +instructions are searched, the time savings from filling the delay slot +are minimal, so stop searching. Increasing values mean more +aggressive optimization, making the compilation time increase with probably +small improvement in execution time. -@option{-fno-fat-lto-objects} improves compilation time over plain LTO, but -requires the complete toolchain to be aware of LTO. It requires a linker with -linker plugin support for basic functionality. Additionally, -@command{nm}, @command{ar} and @command{ranlib} -need to support linker plugins to allow a full-featured build environment -(capable of building static libraries etc). GCC provides the @command{gcc-ar}, -@command{gcc-nm}, @command{gcc-ranlib} wrappers to pass the right options -to these tools. With non fat LTO makefiles need to be modified to use them. +@item max-delay-slot-live-search +When trying to fill delay slots, the maximum number of instructions to +consider when searching for a block with valid live register +information. Increasing this arbitrarily chosen value means more +aggressive optimization, increasing the compilation time. This parameter +should be removed when the delay slot code is rewritten to maintain the +control-flow graph. -The default is @option{-fno-fat-lto-objects} on targets with linker plugin -support. +@item max-gcse-memory +The approximate maximum amount of memory that can be allocated in +order to perform the global common subexpression elimination +optimization. If more memory than specified is required, the +optimization is not done. -@item -fcompare-elim -@opindex fcompare-elim -After register allocation and post-register allocation instruction splitting, -identify arithmetic instructions that compute processor flags similar to a -comparison operation based on that arithmetic. If possible, eliminate the -explicit comparison operation. +@item max-gcse-insertion-ratio +If the ratio of expression insertions to deletions is larger than this value +for any expression, then RTL PRE inserts or removes the expression and thus +leaves partially redundant computations in the instruction stream. The default value is 20. -This pass only applies to certain targets that cannot explicitly represent -the comparison operation before register allocation is complete. +@item max-pending-list-length +The maximum number of pending dependencies scheduling allows +before flushing the current state and starting over. Large functions +with few branches or calls can create excessively large lists which +needlessly consume memory and resources. -Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. +@item max-modulo-backtrack-attempts +The maximum number of backtrack attempts the scheduler should make +when modulo scheduling a loop. Larger values can exponentially increase +compilation time. -@item -fcprop-registers -@opindex fcprop-registers -After register allocation and post-register allocation instruction splitting, -perform a copy-propagation pass to try to reduce scheduling dependencies -and occasionally eliminate the copy. +@item max-inline-insns-single +Several parameters control the tree inliner used in GCC@. +This number sets the maximum number of instructions (counted in GCC's +internal representation) in a single function that the tree inliner +considers for inlining. This only affects functions declared +inline and methods implemented in a class declaration (C++). +The default value is 400. -Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. +@item max-inline-insns-auto +When you use @option{-finline-functions} (included in @option{-O3}), +a lot of functions that would otherwise not be considered for inlining +by the compiler are investigated. To those functions, a different +(more restrictive) limit compared to functions declared inline can +be applied. +The default value is 40. -@item -fprofile-correction -@opindex fprofile-correction -Profiles collected using an instrumented binary for multi-threaded programs may -be inconsistent due to missed counter updates. When this option is specified, -GCC uses heuristics to correct or smooth out such inconsistencies. By -default, GCC emits an error message when an inconsistent profile is detected. +@item inline-min-speedup +When estimated performance improvement of caller + callee runtime exceeds this +threshold (in precent), the function can be inlined regardless the limit on +@option{--param max-inline-insns-single} and @option{--param +max-inline-insns-auto}. -@item -fprofile-dir=@var{path} -@opindex fprofile-dir +@item large-function-insns +The limit specifying really large functions. For functions larger than this +limit after inlining, inlining is constrained by +@option{--param large-function-growth}. This parameter is useful primarily +to avoid extreme compilation time caused by non-linear algorithms used by the +back end. +The default value is 2700. -Set the directory to search for the profile data files in to @var{path}. -This option affects only the profile data generated by -@option{-fprofile-generate}, @option{-ftest-coverage}, @option{-fprofile-arcs} -and used by @option{-fprofile-use} and @option{-fbranch-probabilities} -and its related options. Both absolute and relative paths can be used. -By default, GCC uses the current directory as @var{path}, thus the -profile data file appears in the same directory as the object file. +@item large-function-growth +Specifies maximal growth of large function caused by inlining in percents. +The default value is 100 which limits large function growth to 2.0 times +the original size. -@item -fprofile-generate -@itemx -fprofile-generate=@var{path} -@opindex fprofile-generate +@item large-unit-insns +The limit specifying large translation unit. Growth caused by inlining of +units larger than this limit is limited by @option{--param inline-unit-growth}. +For small units this might be too tight. +For example, consider a unit consisting of function A +that is inline and B that just calls A three times. If B is small relative to +A, the growth of unit is 300\% and yet such inlining is very sane. For very +large units consisting of small inlineable functions, however, the overall unit +growth limit is needed to avoid exponential explosion of code size. Thus for +smaller units, the size is increased to @option{--param large-unit-insns} +before applying @option{--param inline-unit-growth}. The default is 10000. -Enable options usually used for instrumenting application to produce -profile useful for later recompilation with profile feedback based -optimization. You must use @option{-fprofile-generate} both when -compiling and when linking your program. +@item inline-unit-growth +Specifies maximal overall growth of the compilation unit caused by inlining. +The default value is 20 which limits unit growth to 1.2 times the original +size. Cold functions (either marked cold via an attribute or by profile +feedback) are not accounted into the unit size. -The following options are enabled: @option{-fprofile-arcs}, @option{-fprofile-values}, @option{-fvpt}. +@item ipcp-unit-growth +Specifies maximal overall growth of the compilation unit caused by +interprocedural constant propagation. The default value is 10 which limits +unit growth to 1.1 times the original size. + +@item large-stack-frame +The limit specifying large stack frames. While inlining the algorithm is trying +to not grow past this limit too much. The default value is 256 bytes. -If @var{path} is specified, GCC looks at the @var{path} to find -the profile feedback data files. See @option{-fprofile-dir}. +@item large-stack-frame-growth +Specifies maximal growth of large stack frames caused by inlining in percents. +The default value is 1000 which limits large stack frame growth to 11 times +the original size. -@item -fprofile-use -@itemx -fprofile-use=@var{path} -@opindex fprofile-use -Enable profile feedback-directed optimizations, -and the following optimizations -which are generally profitable only with profile feedback available: -@option{-fbranch-probabilities}, @option{-fvpt}, -@option{-funroll-loops}, @option{-fpeel-loops}, @option{-ftracer}, -@option{-ftree-vectorize}, and @option{ftree-loop-distribute-patterns}. +@item max-inline-insns-recursive +@itemx max-inline-insns-recursive-auto +Specifies the maximum number of instructions an out-of-line copy of a +self-recursive inline +function can grow into by performing recursive inlining. -By default, GCC emits an error message if the feedback profiles do not -match the source code. This error can be turned into a warning by using -@option{-Wcoverage-mismatch}. Note this may result in poorly optimized -code. +@option{--param max-inline-insns-recursive} applies to functions +declared inline. +For functions not declared inline, recursive inlining +happens only when @option{-finline-functions} (included in @option{-O3}) is +enabled; @option{--param max-inline-insns-recursive-auto} applies instead. The +default value is 450. -If @var{path} is specified, GCC looks at the @var{path} to find -the profile feedback data files. See @option{-fprofile-dir}. +@item max-inline-recursive-depth +@itemx max-inline-recursive-depth-auto +Specifies the maximum recursion depth used for recursive inlining. -@item -fauto-profile -@itemx -fauto-profile=@var{path} -@opindex fauto-profile -Enable sampling-based feedback-directed optimizations, -and the following optimizations -which are generally profitable only with profile feedback available: -@option{-fbranch-probabilities}, @option{-fvpt}, -@option{-funroll-loops}, @option{-fpeel-loops}, @option{-ftracer}, -@option{-ftree-vectorize}, -@option{-finline-functions}, @option{-fipa-cp}, @option{-fipa-cp-clone}, -@option{-fpredictive-commoning}, @option{-funswitch-loops}, -@option{-fgcse-after-reload}, and @option{-ftree-loop-distribute-patterns}. +@option{--param max-inline-recursive-depth} applies to functions +declared inline. For functions not declared inline, recursive inlining +happens only when @option{-finline-functions} (included in @option{-O3}) is +enabled; @option{--param max-inline-recursive-depth-auto} applies instead. The +default value is 8. -@var{path} is the name of a file containing AutoFDO profile information. -If omitted, it defaults to @file{fbdata.afdo} in the current directory. +@item min-inline-recursive-probability +Recursive inlining is profitable only for function having deep recursion +in average and can hurt for function having little recursion depth by +increasing the prologue size or complexity of function body to other +optimizers. -Producing an AutoFDO profile data file requires running your program -with the @command{perf} utility on a supported GNU/Linux target system. -For more information, see @uref{https://perf.wiki.kernel.org/}. +When profile feedback is available (see @option{-fprofile-generate}) the actual +recursion depth can be guessed from probability that function recurses via a +given call expression. This parameter limits inlining only to call expressions +whose probability exceeds the given threshold (in percents). +The default value is 10. -E.g. -@smallexample -perf record -e br_inst_retired:near_taken -b -o perf.data \ - -- your_program -@end smallexample +@item early-inlining-insns +Specify growth that the early inliner can make. In effect it increases +the amount of inlining for code having a large abstraction penalty. +The default value is 14. -Then use the @command{create_gcov} tool to convert the raw profile data -to a format that can be used by GCC.@ You must also supply the -unstripped binary for your program to this tool. -See @uref{https://github.com/google/autofdo}. +@item max-early-inliner-iterations +Limit of iterations of the early inliner. This basically bounds +the number of nested indirect calls the early inliner can resolve. +Deeper chains are still handled by late inlining. -E.g. -@smallexample -create_gcov --binary=your_program.unstripped --profile=perf.data \ - --gcov=profile.afdo -@end smallexample -@end table +@item comdat-sharing-probability +Probability (in percent) that C++ inline function with comdat visibility +are shared across multiple compilation units. The default value is 20. -The following options control compiler behavior regarding floating-point -arithmetic. These options trade off between speed and -correctness. All must be specifically enabled. +@item profile-func-internal-id +A parameter to control whether to use function internal id in profile +database lookup. If the value is 0, the compiler uses an id that +is based on function assembler name and filename, which makes old profile +data more tolerant to source changes such as function reordering etc. +The default value is 0. -@table @gcctabopt -@item -ffloat-store -@opindex ffloat-store -Do not store floating-point variables in registers, and inhibit other -options that might change whether a floating-point value is taken from a -register or memory. +@item min-vect-loop-bound +The minimum number of iterations under which loops are not vectorized +when @option{-ftree-vectorize} is used. The number of iterations after +vectorization needs to be greater than the value specified by this option +to allow vectorization. The default value is 0. -@cindex floating-point precision -This option prevents undesirable excess precision on machines such as -the 68000 where the floating registers (of the 68881) keep more -precision than a @code{double} is supposed to have. Similarly for the -x86 architecture. For most programs, the excess precision does only -good, but a few programs rely on the precise definition of IEEE floating -point. Use @option{-ffloat-store} for such programs, after modifying -them to store all pertinent intermediate computations into variables. +@item gcse-cost-distance-ratio +Scaling factor in calculation of maximum distance an expression +can be moved by GCSE optimizations. This is currently supported only in the +code hoisting pass. The bigger the ratio, the more aggressive code hoisting +is with simple expressions, i.e., the expressions that have cost +less than @option{gcse-unrestricted-cost}. Specifying 0 disables +hoisting of simple expressions. The default value is 10. -@item -fexcess-precision=@var{style} -@opindex fexcess-precision -This option allows further control over excess precision on machines -where floating-point registers have more precision than the IEEE -@code{float} and @code{double} types and the processor does not -support operations rounding to those types. By default, -@option{-fexcess-precision=fast} is in effect; this means that -operations are carried out in the precision of the registers and that -it is unpredictable when rounding to the types specified in the source -code takes place. When compiling C, if -@option{-fexcess-precision=standard} is specified then excess -precision follows the rules specified in ISO C99; in particular, -both casts and assignments cause values to be rounded to their -semantic types (whereas @option{-ffloat-store} only affects -assignments). This option is enabled by default for C if a strict -conformance option such as @option{-std=c99} is used. +@item gcse-unrestricted-cost +Cost, roughly measured as the cost of a single typical machine +instruction, at which GCSE optimizations do not constrain +the distance an expression can travel. This is currently +supported only in the code hoisting pass. The lesser the cost, +the more aggressive code hoisting is. Specifying 0 +allows all expressions to travel unrestricted distances. +The default value is 3. -@opindex mfpmath -@option{-fexcess-precision=standard} is not implemented for languages -other than C, and has no effect if -@option{-funsafe-math-optimizations} or @option{-ffast-math} is -specified. On the x86, it also has no effect if @option{-mfpmath=sse} -or @option{-mfpmath=sse+387} is specified; in the former case, IEEE -semantics apply without excess precision, and in the latter, rounding -is unpredictable. +@item max-hoist-depth +The depth of search in the dominator tree for expressions to hoist. +This is used to avoid quadratic behavior in hoisting algorithm. +The value of 0 does not limit on the search, but may slow down compilation +of huge functions. The default value is 30. -@item -ffast-math -@opindex ffast-math -Sets the options @option{-fno-math-errno}, @option{-funsafe-math-optimizations}, -@option{-ffinite-math-only}, @option{-fno-rounding-math}, -@option{-fno-signaling-nans} and @option{-fcx-limited-range}. +@item max-tail-merge-comparisons +The maximum amount of similar bbs to compare a bb with. This is used to +avoid quadratic behavior in tree tail merging. The default value is 10. -This option causes the preprocessor macro @code{__FAST_MATH__} to be defined. +@item max-tail-merge-iterations +The maximum amount of iterations of the pass over the function. This is used to +limit compilation time in tree tail merging. The default value is 2. -This option is not turned on by any @option{-O} option besides -@option{-Ofast} since it can result in incorrect output for programs -that depend on an exact implementation of IEEE or ISO rules/specifications -for math functions. It may, however, yield faster code for programs -that do not require the guarantees of these specifications. +@item max-unrolled-insns +The maximum number of instructions that a loop may have to be unrolled. +If a loop is unrolled, this parameter also determines how many times +the loop code is unrolled. -@item -fno-math-errno -@opindex fno-math-errno -Do not set @code{errno} after calling math functions that are executed -with a single instruction, e.g., @code{sqrt}. A program that relies on -IEEE exceptions for math error handling may want to use this flag -for speed while maintaining IEEE arithmetic compatibility. +@item max-average-unrolled-insns +The maximum number of instructions biased by probabilities of their execution +that a loop may have to be unrolled. If a loop is unrolled, +this parameter also determines how many times the loop code is unrolled. -This option is not turned on by any @option{-O} option since -it can result in incorrect output for programs that depend on -an exact implementation of IEEE or ISO rules/specifications for -math functions. It may, however, yield faster code for programs -that do not require the guarantees of these specifications. +@item max-unroll-times +The maximum number of unrollings of a single loop. -The default is @option{-fmath-errno}. +@item max-peeled-insns +The maximum number of instructions that a loop may have to be peeled. +If a loop is peeled, this parameter also determines how many times +the loop code is peeled. -On Darwin systems, the math library never sets @code{errno}. There is -therefore no reason for the compiler to consider the possibility that -it might, and @option{-fno-math-errno} is the default. +@item max-peel-times +The maximum number of peelings of a single loop. -@item -funsafe-math-optimizations -@opindex funsafe-math-optimizations +@item max-peel-branches +The maximum number of branches on the hot path through the peeled sequence. -Allow optimizations for floating-point arithmetic that (a) assume -that arguments and results are valid and (b) may violate IEEE or -ANSI standards. When used at link-time, it may include libraries -or startup files that change the default FPU control word or other -similar optimizations. +@item max-completely-peeled-insns +The maximum number of insns of a completely peeled loop. -This option is not turned on by any @option{-O} option since -it can result in incorrect output for programs that depend on -an exact implementation of IEEE or ISO rules/specifications for -math functions. It may, however, yield faster code for programs -that do not require the guarantees of these specifications. -Enables @option{-fno-signed-zeros}, @option{-fno-trapping-math}, -@option{-fassociative-math} and @option{-freciprocal-math}. +@item max-completely-peel-times +The maximum number of iterations of a loop to be suitable for complete peeling. -The default is @option{-fno-unsafe-math-optimizations}. +@item max-completely-peel-loop-nest-depth +The maximum depth of a loop nest suitable for complete peeling. -@item -fassociative-math -@opindex fassociative-math +@item max-unswitch-insns +The maximum number of insns of an unswitched loop. -Allow re-association of operands in series of floating-point operations. -This violates the ISO C and C++ language standard by possibly changing -computation result. NOTE: re-ordering may change the sign of zero as -well as ignore NaNs and inhibit or create underflow or overflow (and -thus cannot be used on code that relies on rounding behavior like -@code{(x + 2**52) - 2**52}. May also reorder floating-point comparisons -and thus may not be used when ordered comparisons are required. -This option requires that both @option{-fno-signed-zeros} and -@option{-fno-trapping-math} be in effect. Moreover, it doesn't make -much sense with @option{-frounding-math}. For Fortran the option -is automatically enabled when both @option{-fno-signed-zeros} and -@option{-fno-trapping-math} are in effect. +@item max-unswitch-level +The maximum number of branches unswitched in a single loop. -The default is @option{-fno-associative-math}. +@item lim-expensive +The minimum cost of an expensive expression in the loop invariant motion. -@item -freciprocal-math -@opindex freciprocal-math +@item iv-consider-all-candidates-bound +Bound on number of candidates for induction variables, below which +all candidates are considered for each use in induction variable +optimizations. If there are more candidates than this, +only the most relevant ones are considered to avoid quadratic time complexity. -Allow the reciprocal of a value to be used instead of dividing by -the value if this enables optimizations. For example @code{x / y} -can be replaced with @code{x * (1/y)}, which is useful if @code{(1/y)} -is subject to common subexpression elimination. Note that this loses -precision and increases the number of flops operating on the value. +@item iv-max-considered-uses +The induction variable optimizations give up on loops that contain more +induction variable uses. -The default is @option{-fno-reciprocal-math}. +@item iv-always-prune-cand-set-bound +If the number of candidates in the set is smaller than this value, +always try to remove unnecessary ivs from the set +when adding a new one. -@item -ffinite-math-only -@opindex ffinite-math-only -Allow optimizations for floating-point arithmetic that assume -that arguments and results are not NaNs or +-Infs. +@item scev-max-expr-size +Bound on size of expressions used in the scalar evolutions analyzer. +Large expressions slow the analyzer. -This option is not turned on by any @option{-O} option since -it can result in incorrect output for programs that depend on -an exact implementation of IEEE or ISO rules/specifications for -math functions. It may, however, yield faster code for programs -that do not require the guarantees of these specifications. +@item scev-max-expr-complexity +Bound on the complexity of the expressions in the scalar evolutions analyzer. +Complex expressions slow the analyzer. -The default is @option{-fno-finite-math-only}. +@item vect-max-version-for-alignment-checks +The maximum number of run-time checks that can be performed when +doing loop versioning for alignment in the vectorizer. -@item -fno-signed-zeros -@opindex fno-signed-zeros -Allow optimizations for floating-point arithmetic that ignore the -signedness of zero. IEEE arithmetic specifies the behavior of -distinct +0.0 and @minus{}0.0 values, which then prohibits simplification -of expressions such as x+0.0 or 0.0*x (even with @option{-ffinite-math-only}). -This option implies that the sign of a zero result isn't significant. +@item vect-max-version-for-alias-checks +The maximum number of run-time checks that can be performed when +doing loop versioning for alias in the vectorizer. -The default is @option{-fsigned-zeros}. +@item vect-max-peeling-for-alignment +The maximum number of loop peels to enhance access alignment +for vectorizer. Value -1 means 'no limit'. -@item -fno-trapping-math -@opindex fno-trapping-math -Compile code assuming that floating-point operations cannot generate -user-visible traps. These traps include division by zero, overflow, -underflow, inexact result and invalid operation. This option requires -that @option{-fno-signaling-nans} be in effect. Setting this option may -allow faster code if one relies on ``non-stop'' IEEE arithmetic, for example. +@item max-iterations-to-track +The maximum number of iterations of a loop the brute-force algorithm +for analysis of the number of iterations of the loop tries to evaluate. -This option should never be turned on by any @option{-O} option since -it can result in incorrect output for programs that depend on -an exact implementation of IEEE or ISO rules/specifications for -math functions. +@item hot-bb-count-ws-permille +A basic block profile count is considered hot if it contributes to +the given permillage (i.e. 0...1000) of the entire profiled execution. -The default is @option{-ftrapping-math}. +@item hot-bb-frequency-fraction +Select fraction of the entry block frequency of executions of basic block in +function given basic block needs to have to be considered hot. -@item -frounding-math -@opindex frounding-math -Disable transformations and optimizations that assume default floating-point -rounding behavior. This is round-to-zero for all floating point -to integer conversions, and round-to-nearest for all other arithmetic -truncations. This option should be specified for programs that change -the FP rounding mode dynamically, or that may be executed with a -non-default rounding mode. This option disables constant folding of -floating-point expressions at compile time (which may be affected by -rounding mode) and arithmetic transformations that are unsafe in the -presence of sign-dependent rounding modes. +@item max-predicted-iterations +The maximum number of loop iterations we predict statically. This is useful +in cases where a function contains a single loop with known bound and +another loop with unknown bound. +The known number of iterations is predicted correctly, while +the unknown number of iterations average to roughly 10. This means that the +loop without bounds appears artificially cold relative to the other one. -The default is @option{-fno-rounding-math}. +@item builtin-expect-probability +Control the probability of the expression having the specified value. This +parameter takes a percentage (i.e. 0 ... 100) as input. +The default probability of 90 is obtained empirically. -This option is experimental and does not currently guarantee to -disable all GCC optimizations that are affected by rounding mode. -Future versions of GCC may provide finer control of this setting -using C99's @code{FENV_ACCESS} pragma. This command-line option -will be used to specify the default state for @code{FENV_ACCESS}. +@item align-threshold -@item -fsignaling-nans -@opindex fsignaling-nans -Compile code assuming that IEEE signaling NaNs may generate user-visible -traps during floating-point operations. Setting this option disables -optimizations that may change the number of exceptions visible with -signaling NaNs. This option implies @option{-ftrapping-math}. +Select fraction of the maximal frequency of executions of a basic block in +a function to align the basic block. -This option causes the preprocessor macro @code{__SUPPORT_SNAN__} to -be defined. +@item align-loop-iterations -The default is @option{-fno-signaling-nans}. +A loop expected to iterate at least the selected number of iterations is +aligned. -This option is experimental and does not currently guarantee to -disable all GCC optimizations that affect signaling NaN behavior. +@item tracer-dynamic-coverage +@itemx tracer-dynamic-coverage-feedback -@item -fsingle-precision-constant -@opindex fsingle-precision-constant -Treat floating-point constants as single precision instead of -implicitly converting them to double-precision constants. +This value is used to limit superblock formation once the given percentage of +executed instructions is covered. This limits unnecessary code size +expansion. -@item -fcx-limited-range -@opindex fcx-limited-range -When enabled, this option states that a range reduction step is not -needed when performing complex division. Also, there is no checking -whether the result of a complex multiplication or division is @code{NaN -+ I*NaN}, with an attempt to rescue the situation in that case. The -default is @option{-fno-cx-limited-range}, but is enabled by -@option{-ffast-math}. +The @option{tracer-dynamic-coverage-feedback} parameter +is used only when profile +feedback is available. The real profiles (as opposed to statically estimated +ones) are much less balanced allowing the threshold to be larger value. -This option controls the default setting of the ISO C99 -@code{CX_LIMITED_RANGE} pragma. Nevertheless, the option applies to -all languages. +@item tracer-max-code-growth +Stop tail duplication once code growth has reached given percentage. This is +a rather artificial limit, as most of the duplicates are eliminated later in +cross jumping, so it may be set to much higher values than is the desired code +growth. -@item -fcx-fortran-rules -@opindex fcx-fortran-rules -Complex multiplication and division follow Fortran rules. Range -reduction is done as part of complex division, but there is no checking -whether the result of a complex multiplication or division is @code{NaN -+ I*NaN}, with an attempt to rescue the situation in that case. +@item tracer-min-branch-ratio -The default is @option{-fno-cx-fortran-rules}. +Stop reverse growth when the reverse probability of best edge is less than this +threshold (in percent). -@end table +@item tracer-min-branch-ratio +@itemx tracer-min-branch-ratio-feedback -The following options control optimizations that may improve -performance, but are not enabled by any @option{-O} options. This -section includes experimental options that may produce broken code. +Stop forward growth if the best edge has probability lower than this +threshold. -@table @gcctabopt -@item -fbranch-probabilities -@opindex fbranch-probabilities -After running a program compiled with @option{-fprofile-arcs} -(@pxref{Debugging Options,, Options for Debugging Your Program or -@command{gcc}}), you can compile it a second time using -@option{-fbranch-probabilities}, to improve optimizations based on -the number of times each branch was taken. When a program -compiled with @option{-fprofile-arcs} exits, it saves arc execution -counts to a file called @file{@var{sourcename}.gcda} for each source -file. The information in this data file is very dependent on the -structure of the generated code, so you must use the same source code -and the same optimization options for both compilations. +Similarly to @option{tracer-dynamic-coverage} two values are present, one for +compilation for profile feedback and one for compilation without. The value +for compilation with profile feedback needs to be more conservative (higher) in +order to make tracer effective. -With @option{-fbranch-probabilities}, GCC puts a -@samp{REG_BR_PROB} note on each @samp{JUMP_INSN} and @samp{CALL_INSN}. -These can be used to improve optimization. Currently, they are only -used in one place: in @file{reorg.c}, instead of guessing which path a -branch is most likely to take, the @samp{REG_BR_PROB} values are used to -exactly determine which path is taken more often. +@item max-cse-path-length -@item -fprofile-values -@opindex fprofile-values -If combined with @option{-fprofile-arcs}, it adds code so that some -data about values of expressions in the program is gathered. +The maximum number of basic blocks on path that CSE considers. +The default is 10. -With @option{-fbranch-probabilities}, it reads back the data gathered -from profiling values of expressions for usage in optimizations. +@item max-cse-insns +The maximum number of instructions CSE processes before flushing. +The default is 1000. -Enabled with @option{-fprofile-generate} and @option{-fprofile-use}. +@item ggc-min-expand -@item -fprofile-reorder-functions -@opindex fprofile-reorder-functions -Function reordering based on profile instrumentation collects -first time of execution of a function and orders these functions -in ascending order. +GCC uses a garbage collector to manage its own memory allocation. This +parameter specifies the minimum percentage by which the garbage +collector's heap should be allowed to expand between collections. +Tuning this may improve compilation speed; it has no effect on code +generation. -Enabled with @option{-fprofile-use}. +The default is 30% + 70% * (RAM/1GB) with an upper bound of 100% when +RAM >= 1GB@. If @code{getrlimit} is available, the notion of ``RAM'' is +the smallest of actual RAM and @code{RLIMIT_DATA} or @code{RLIMIT_AS}. If +GCC is not able to calculate RAM on a particular platform, the lower +bound of 30% is used. Setting this parameter and +@option{ggc-min-heapsize} to zero causes a full collection to occur at +every opportunity. This is extremely slow, but can be useful for +debugging. -@item -fvpt -@opindex fvpt -If combined with @option{-fprofile-arcs}, this option instructs the compiler -to add code to gather information about values of expressions. +@item ggc-min-heapsize -With @option{-fbranch-probabilities}, it reads back the data gathered -and actually performs the optimizations based on them. -Currently the optimizations include specialization of division operations -using the knowledge about the value of the denominator. +Minimum size of the garbage collector's heap before it begins bothering +to collect garbage. The first collection occurs after the heap expands +by @option{ggc-min-expand}% beyond @option{ggc-min-heapsize}. Again, +tuning this may improve compilation speed, and has no effect on code +generation. -@item -frename-registers -@opindex frename-registers -Attempt to avoid false dependencies in scheduled code by making use -of registers left over after register allocation. This optimization -most benefits processors with lots of registers. Depending on the -debug information format adopted by the target, however, it can -make debugging impossible, since variables no longer stay in -a ``home register''. +The default is the smaller of RAM/8, RLIMIT_RSS, or a limit that +tries to ensure that RLIMIT_DATA or RLIMIT_AS are not exceeded, but +with a lower bound of 4096 (four megabytes) and an upper bound of +131072 (128 megabytes). If GCC is not able to calculate RAM on a +particular platform, the lower bound is used. Setting this parameter +very large effectively disables garbage collection. Setting this +parameter and @option{ggc-min-expand} to zero causes a full collection +to occur at every opportunity. + +@item max-reload-search-insns +The maximum number of instruction reload should look backward for equivalent +register. Increasing values mean more aggressive optimization, making the +compilation time increase with probably slightly better performance. +The default value is 100. -Enabled by default with @option{-funroll-loops} and @option{-fpeel-loops}. +@item max-cselib-memory-locations +The maximum number of memory locations cselib should take into account. +Increasing values mean more aggressive optimization, making the compilation time +increase with probably slightly better performance. The default value is 500. -@item -fschedule-fusion -@opindex fschedule-fusion -Performs a target dependent pass over the instruction stream to schedule -instructions of same type together because target machine can execute them -more efficiently if they are adjacent to each other in the instruction flow. +@item reorder-blocks-duplicate +@itemx reorder-blocks-duplicate-feedback -Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. +Used by the basic block reordering pass to decide whether to use unconditional +branch or duplicate the code on its destination. Code is duplicated when its +estimated size is smaller than this value multiplied by the estimated size of +unconditional jump in the hot spots of the program. -@item -ftracer -@opindex ftracer -Perform tail duplication to enlarge superblock size. This transformation -simplifies the control flow of the function allowing other optimizations to do -a better job. +The @option{reorder-block-duplicate-feedback} parameter +is used only when profile +feedback is available. It may be set to higher values than +@option{reorder-block-duplicate} since information about the hot spots is more +accurate. -Enabled with @option{-fprofile-use}. +@item max-sched-ready-insns +The maximum number of instructions ready to be issued the scheduler should +consider at any given time during the first scheduling pass. Increasing +values mean more thorough searches, making the compilation time increase +with probably little benefit. The default value is 100. -@item -funroll-loops -@opindex funroll-loops -Unroll loops whose number of iterations can be determined at compile time or -upon entry to the loop. @option{-funroll-loops} implies -@option{-frerun-cse-after-loop}, @option{-fweb} and @option{-frename-registers}. -It also turns on complete loop peeling (i.e.@: complete removal of loops with -a small constant number of iterations). This option makes code larger, and may -or may not make it run faster. +@item max-sched-region-blocks +The maximum number of blocks in a region to be considered for +interblock scheduling. The default value is 10. -Enabled with @option{-fprofile-use}. +@item max-pipeline-region-blocks +The maximum number of blocks in a region to be considered for +pipelining in the selective scheduler. The default value is 15. -@item -funroll-all-loops -@opindex funroll-all-loops -Unroll all loops, even if their number of iterations is uncertain when -the loop is entered. This usually makes programs run more slowly. -@option{-funroll-all-loops} implies the same options as -@option{-funroll-loops}. +@item max-sched-region-insns +The maximum number of insns in a region to be considered for +interblock scheduling. The default value is 100. -@item -fpeel-loops -@opindex fpeel-loops -Peels loops for which there is enough information that they do not -roll much (from profile feedback). It also turns on complete loop peeling -(i.e.@: complete removal of loops with small constant number of iterations). +@item max-pipeline-region-insns +The maximum number of insns in a region to be considered for +pipelining in the selective scheduler. The default value is 200. -Enabled with @option{-fprofile-use}. +@item min-spec-prob +The minimum probability (in percents) of reaching a source block +for interblock speculative scheduling. The default value is 40. -@item -fmove-loop-invariants -@opindex fmove-loop-invariants -Enables the loop invariant motion pass in the RTL loop optimizer. Enabled -at level @option{-O1} +@item max-sched-extend-regions-iters +The maximum number of iterations through CFG to extend regions. +A value of 0 (the default) disables region extensions. -@item -funswitch-loops -@opindex funswitch-loops -Move branches with loop invariant conditions out of the loop, with duplicates -of the loop on both branches (modified according to result of the condition). +@item max-sched-insn-conflict-delay +The maximum conflict delay for an insn to be considered for speculative motion. +The default value is 3. -@item -ffunction-sections -@itemx -fdata-sections -@opindex ffunction-sections -@opindex fdata-sections -Place each function or data item into its own section in the output -file if the target supports arbitrary sections. The name of the -function or the name of the data item determines the section's name -in the output file. +@item sched-spec-prob-cutoff +The minimal probability of speculation success (in percents), so that +speculative insns are scheduled. +The default value is 40. -Use these options on systems where the linker can perform optimizations -to improve locality of reference in the instruction space. Most systems -using the ELF object format and SPARC processors running Solaris 2 have -linkers with such optimizations. AIX may have these optimizations in -the future. +@item sched-spec-state-edge-prob-cutoff +The minimum probability an edge must have for the scheduler to save its +state across it. +The default value is 10. -Only use these options when there are significant benefits from doing -so. When you specify these options, the assembler and linker -create larger object and executable files and are also slower. -You cannot use @command{gprof} on all systems if you -specify this option, and you may have problems with debugging if -you specify both this option and @option{-g}. +@item sched-mem-true-dep-cost +Minimal distance (in CPU cycles) between store and load targeting same +memory locations. The default value is 1. -@item -fbranch-target-load-optimize -@opindex fbranch-target-load-optimize -Perform branch target register load optimization before prologue / epilogue -threading. -The use of target registers can typically be exposed only during reload, -thus hoisting loads out of loops and doing inter-block scheduling needs -a separate optimization pass. +@item selsched-max-lookahead +The maximum size of the lookahead window of selective scheduling. It is a +depth of search for available instructions. +The default value is 50. -@item -fbranch-target-load-optimize2 -@opindex fbranch-target-load-optimize2 -Perform branch target register load optimization after prologue / epilogue -threading. +@item selsched-max-sched-times +The maximum number of times that an instruction is scheduled during +selective scheduling. This is the limit on the number of iterations +through which the instruction may be pipelined. The default value is 2. -@item -fbtr-bb-exclusive -@opindex fbtr-bb-exclusive -When performing branch target register load optimization, don't reuse -branch target registers within any basic block. +@item selsched-max-insns-to-rename +The maximum number of best instructions in the ready list that are considered +for renaming in the selective scheduler. The default value is 2. -@item -fstack-protector -@opindex fstack-protector -Emit extra code to check for buffer overflows, such as stack smashing -attacks. This is done by adding a guard variable to functions with -vulnerable objects. This includes functions that call @code{alloca}, and -functions with buffers larger than 8 bytes. The guards are initialized -when a function is entered and then checked when the function exits. -If a guard check fails, an error message is printed and the program exits. +@item sms-min-sc +The minimum value of stage count that swing modulo scheduler +generates. The default value is 2. -@item -fstack-protector-all -@opindex fstack-protector-all -Like @option{-fstack-protector} except that all functions are protected. +@item max-last-value-rtl +The maximum size measured as number of RTLs that can be recorded in an expression +in combiner for a pseudo register as last known value of that register. The default +is 10000. -@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 max-combine-insns +The maximum number of instructions the RTL combiner tries to combine. +The default value is 2 at @option{-Og} and 4 otherwise. -@item -fstack-protector-explicit -@opindex fstack-protector-explicit -Like @option{-fstack-protector} but only protects those functions which -have the @code{stack_protect} attribute. +@item integer-share-limit +Small integer constants can use a shared data structure, reducing the +compiler's memory usage and increasing its speed. This sets the maximum +value of a shared integer constant. The default value is 256. -@item -fstdarg-opt -@opindex fstdarg-opt -Optimize the prologue of variadic argument functions with respect to usage of -those arguments. +@item ssp-buffer-size +The minimum size of buffers (i.e.@: arrays) that receive stack smashing +protection when @option{-fstack-protection} is used. -@item -fsection-anchors -@opindex fsection-anchors -Try to reduce the number of symbolic address calculations by using -shared ``anchor'' symbols to address nearby objects. This transformation -can help to reduce the number of GOT entries and GOT accesses on some -targets. +@item min-size-for-stack-sharing +The minimum size of variables taking part in stack slot sharing when not +optimizing. The default value is 32. -For example, the implementation of the following function @code{foo}: +@item max-jump-thread-duplication-stmts +Maximum number of statements allowed in a block that needs to be +duplicated when threading jumps. -@smallexample -static int a, b, c; -int foo (void) @{ return a + b + c; @} -@end smallexample +@item max-fields-for-field-sensitive +Maximum number of fields in a structure treated in +a field sensitive manner during pointer analysis. The default is zero +for @option{-O0} and @option{-O1}, +and 100 for @option{-Os}, @option{-O2}, and @option{-O3}. -@noindent -usually calculates the addresses of all three variables, but if you -compile it with @option{-fsection-anchors}, it accesses the variables -from a common anchor point instead. The effect is similar to the -following pseudocode (which isn't valid C): +@item prefetch-latency +Estimate on average number of instructions that are executed before +prefetch finishes. The distance prefetched ahead is proportional +to this constant. Increasing this number may also lead to less +streams being prefetched (see @option{simultaneous-prefetches}). -@smallexample -int foo (void) -@{ - register int *xr = &x; - return xr[&a - &x] + xr[&b - &x] + xr[&c - &x]; -@} -@end smallexample +@item simultaneous-prefetches +Maximum number of prefetches that can run at the same time. -Not all targets support this option. +@item l1-cache-line-size +The size of cache line in L1 cache, in bytes. -@item --param @var{name}=@var{value} -@opindex param -In some places, GCC uses various constants to control the amount of -optimization that is done. For example, GCC does not inline functions -that contain more than a certain number of instructions. You can -control some of these constants on the command line using the -@option{--param} option. +@item l1-cache-size +The size of L1 cache, in kilobytes. -The names of specific parameters, and the meaning of the values, are -tied to the internals of the compiler, and are subject to change -without notice in future releases. +@item l2-cache-size +The size of L2 cache, in kilobytes. -In each case, the @var{value} is an integer. The allowable choices for -@var{name} are: +@item min-insn-to-prefetch-ratio +The minimum ratio between the number of instructions and the +number of prefetches to enable prefetching in a loop. -@table @gcctabopt -@item predictable-branch-outcome -When branch is predicted to be taken with probability lower than this threshold -(in percent), then it is considered well predictable. The default is 10. +@item prefetch-min-insn-to-mem-ratio +The minimum ratio between the number of instructions and the +number of memory references to enable prefetching in a loop. + +@item use-canonical-types +Whether the compiler should use the ``canonical'' type system. By +default, this should always be 1, which uses a more efficient internal +mechanism for comparing types in C++ and Objective-C++. However, if +bugs in the canonical type system are causing compilation failures, +set this value to 0 to disable canonical types. -@item max-rtl-if-conversion-insns -RTL if-conversion tries to remove conditional branches around a block and -replace them with conditionally executed instructions. This parameter -gives the maximum number of instructions in a block which should be -considered for if-conversion. The default is 10, though the compiler will -also use other heuristics to decide whether if-conversion is likely to be -profitable. +@item switch-conversion-max-branch-ratio +Switch initialization conversion refuses to create arrays that are +bigger than @option{switch-conversion-max-branch-ratio} times the number of +branches in the switch. -@item max-crossjump-edges -The maximum number of incoming edges to consider for cross-jumping. -The algorithm used by @option{-fcrossjumping} is @math{O(N^2)} in -the number of edges incoming to each block. Increasing values mean -more aggressive optimization, making the compilation time increase with -probably small improvement in executable size. +@item max-partial-antic-length +Maximum length of the partial antic set computed during the tree +partial redundancy elimination optimization (@option{-ftree-pre}) when +optimizing at @option{-O3} and above. For some sorts of source code +the enhanced partial redundancy elimination optimization can run away, +consuming all of the memory available on the host machine. This +parameter sets a limit on the length of the sets that are computed, +which prevents the runaway behavior. Setting a value of 0 for +this parameter allows an unlimited set length. -@item min-crossjump-insns -The minimum number of instructions that must be matched at the end -of two blocks before cross-jumping is performed on them. This -value is ignored in the case where all instructions in the block being -cross-jumped from are matched. The default value is 5. +@item sccvn-max-scc-size +Maximum size of a strongly connected component (SCC) during SCCVN +processing. If this limit is hit, SCCVN processing for the whole +function is not done and optimizations depending on it are +disabled. The default maximum SCC size is 10000. -@item max-grow-copy-bb-insns -The maximum code size expansion factor when copying basic blocks -instead of jumping. The expansion is relative to a jump instruction. -The default value is 8. +@item sccvn-max-alias-queries-per-access +Maximum number of alias-oracle queries we perform when looking for +redundancies for loads and stores. If this limit is hit the search +is aborted and the load or store is not considered redundant. The +number of queries is algorithmically limited to the number of +stores on all paths from the load to the function entry. +The default maxmimum number of queries is 1000. -@item max-goto-duplication-insns -The maximum number of instructions to duplicate to a block that jumps -to a computed goto. To avoid @math{O(N^2)} behavior in a number of -passes, GCC factors computed gotos early in the compilation process, -and unfactors them as late as possible. Only computed jumps at the -end of a basic blocks with no more than max-goto-duplication-insns are -unfactored. The default value is 8. +@item ira-max-loops-num +IRA uses regional register allocation by default. If a function +contains more loops than the number given by this parameter, only at most +the given number of the most frequently-executed loops form regions +for regional register allocation. The default value of the +parameter is 100. -@item max-delay-slot-insn-search -The maximum number of instructions to consider when looking for an -instruction to fill a delay slot. If more than this arbitrary number of -instructions are searched, the time savings from filling the delay slot -are minimal, so stop searching. Increasing values mean more -aggressive optimization, making the compilation time increase with probably -small improvement in execution time. +@item ira-max-conflict-table-size +Although IRA uses a sophisticated algorithm to compress the conflict +table, the table can still require excessive amounts of memory for +huge functions. If the conflict table for a function could be more +than the size in MB given by this parameter, the register allocator +instead uses a faster, simpler, and lower-quality +algorithm that does not require building a pseudo-register conflict table. +The default value of the parameter is 2000. -@item max-delay-slot-live-search -When trying to fill delay slots, the maximum number of instructions to -consider when searching for a block with valid live register -information. Increasing this arbitrarily chosen value means more -aggressive optimization, increasing the compilation time. This parameter -should be removed when the delay slot code is rewritten to maintain the -control-flow graph. +@item ira-loop-reserved-regs +IRA can be used to evaluate more accurate register pressure in loops +for decisions to move loop invariants (see @option{-O3}). The number +of available registers reserved for some other purposes is given +by this parameter. The default value of the parameter is 2, which is +the minimal number of registers needed by typical instructions. +This value is the best found from numerous experiments. -@item max-gcse-memory -The approximate maximum amount of memory that can be allocated in -order to perform the global common subexpression elimination -optimization. If more memory than specified is required, the -optimization is not done. +@item lra-inheritance-ebb-probability-cutoff +LRA tries to reuse values reloaded in registers in subsequent insns. +This optimization is called inheritance. EBB is used as a region to +do this optimization. The parameter defines a minimal fall-through +edge probability in percentage used to add BB to inheritance EBB in +LRA. The default value of the parameter is 40. The value was chosen +from numerous runs of SPEC2000 on x86-64. -@item max-gcse-insertion-ratio -If the ratio of expression insertions to deletions is larger than this value -for any expression, then RTL PRE inserts or removes the expression and thus -leaves partially redundant computations in the instruction stream. The default value is 20. +@item loop-invariant-max-bbs-in-loop +Loop invariant motion can be very expensive, both in compilation time and +in amount of needed compile-time memory, with very large loops. Loops +with more basic blocks than this parameter won't have loop invariant +motion optimization performed on them. The default value of the +parameter is 1000 for @option{-O1} and 10000 for @option{-O2} and above. -@item max-pending-list-length -The maximum number of pending dependencies scheduling allows -before flushing the current state and starting over. Large functions -with few branches or calls can create excessively large lists which -needlessly consume memory and resources. +@item loop-max-datarefs-for-datadeps +Building data dapendencies is expensive for very large loops. This +parameter limits the number of data references in loops that are +considered for data dependence analysis. These large loops are no +handled by the optimizations using loop data dependencies. +The default value is 1000. -@item max-modulo-backtrack-attempts -The maximum number of backtrack attempts the scheduler should make -when modulo scheduling a loop. Larger values can exponentially increase -compilation time. +@item max-vartrack-size +Sets a maximum number of hash table slots to use during variable +tracking dataflow analysis of any function. If this limit is exceeded +with variable tracking at assignments enabled, analysis for that +function is retried without it, after removing all debug insns from +the function. If the limit is exceeded even without debug insns, var +tracking analysis is completely disabled for the function. Setting +the parameter to zero makes it unlimited. -@item max-inline-insns-single -Several parameters control the tree inliner used in GCC@. -This number sets the maximum number of instructions (counted in GCC's -internal representation) in a single function that the tree inliner -considers for inlining. This only affects functions declared -inline and methods implemented in a class declaration (C++). -The default value is 400. +@item max-vartrack-expr-depth +Sets a maximum number of recursion levels when attempting to map +variable names or debug temporaries to value expressions. This trades +compilation time for more complete debug information. If this is set too +low, value expressions that are available and could be represented in +debug information may end up not being used; setting this higher may +enable the compiler to find more complex debug expressions, but compile +time and memory use may grow. The default is 12. -@item max-inline-insns-auto -When you use @option{-finline-functions} (included in @option{-O3}), -a lot of functions that would otherwise not be considered for inlining -by the compiler are investigated. To those functions, a different -(more restrictive) limit compared to functions declared inline can -be applied. -The default value is 40. +@item min-nondebug-insn-uid +Use uids starting at this parameter for nondebug insns. The range below +the parameter is reserved exclusively for debug insns created by +@option{-fvar-tracking-assignments}, but debug insns may get +(non-overlapping) uids above it if the reserved range is exhausted. -@item inline-min-speedup -When estimated performance improvement of caller + callee runtime exceeds this -threshold (in precent), the function can be inlined regardless the limit on -@option{--param max-inline-insns-single} and @option{--param -max-inline-insns-auto}. +@item ipa-sra-ptr-growth-factor +IPA-SRA replaces a pointer to an aggregate with one or more new +parameters only when their cumulative size is less or equal to +@option{ipa-sra-ptr-growth-factor} times the size of the original +pointer parameter. -@item large-function-insns -The limit specifying really large functions. For functions larger than this -limit after inlining, inlining is constrained by -@option{--param large-function-growth}. This parameter is useful primarily -to avoid extreme compilation time caused by non-linear algorithms used by the -back end. -The default value is 2700. +@item sra-max-scalarization-size-Ospeed +@item sra-max-scalarization-size-Osize +The two Scalar Reduction of Aggregates passes (SRA and IPA-SRA) aim to +replace scalar parts of aggregates with uses of independent scalar +variables. These parameters control the maximum size, in storage units, +of aggregate which is considered for replacement when compiling for +speed +(@option{sra-max-scalarization-size-Ospeed}) or size +(@option{sra-max-scalarization-size-Osize}) respectively. -@item large-function-growth -Specifies maximal growth of large function caused by inlining in percents. -The default value is 100 which limits large function growth to 2.0 times -the original size. +@item tm-max-aggregate-size +When making copies of thread-local variables in a transaction, this +parameter specifies the size in bytes after which variables are +saved with the logging functions as opposed to save/restore code +sequence pairs. This option only applies when using +@option{-fgnu-tm}. -@item large-unit-insns -The limit specifying large translation unit. Growth caused by inlining of -units larger than this limit is limited by @option{--param inline-unit-growth}. -For small units this might be too tight. -For example, consider a unit consisting of function A -that is inline and B that just calls A three times. If B is small relative to -A, the growth of unit is 300\% and yet such inlining is very sane. For very -large units consisting of small inlineable functions, however, the overall unit -growth limit is needed to avoid exponential explosion of code size. Thus for -smaller units, the size is increased to @option{--param large-unit-insns} -before applying @option{--param inline-unit-growth}. The default is 10000. +@item graphite-max-nb-scop-params +To avoid exponential effects in the Graphite loop transforms, the +number of parameters in a Static Control Part (SCoP) is bounded. The +default value is 10 parameters. A variable whose value is unknown at +compilation time and defined outside a SCoP is a parameter of the SCoP. -@item inline-unit-growth -Specifies maximal overall growth of the compilation unit caused by inlining. -The default value is 20 which limits unit growth to 1.2 times the original -size. Cold functions (either marked cold via an attribute or by profile -feedback) are not accounted into the unit size. +@item graphite-max-bbs-per-function +To avoid exponential effects in the detection of SCoPs, the size of +the functions analyzed by Graphite is bounded. The default value is +100 basic blocks. -@item ipcp-unit-growth -Specifies maximal overall growth of the compilation unit caused by -interprocedural constant propagation. The default value is 10 which limits -unit growth to 1.1 times the original size. +@item loop-block-tile-size +Loop blocking or strip mining transforms, enabled with +@option{-floop-block} or @option{-floop-strip-mine}, strip mine each +loop in the loop nest by a given number of iterations. The strip +length can be changed using the @option{loop-block-tile-size} +parameter. The default value is 51 iterations. -@item large-stack-frame -The limit specifying large stack frames. While inlining the algorithm is trying -to not grow past this limit too much. The default value is 256 bytes. +@item loop-unroll-jam-size +Specify the unroll factor for the @option{-floop-unroll-and-jam} option. The +default value is 4. -@item large-stack-frame-growth -Specifies maximal growth of large stack frames caused by inlining in percents. -The default value is 1000 which limits large stack frame growth to 11 times -the original size. +@item loop-unroll-jam-depth +Specify the dimension to be unrolled (counting from the most inner loop) +for the @option{-floop-unroll-and-jam}. The default value is 2. -@item max-inline-insns-recursive -@itemx max-inline-insns-recursive-auto -Specifies the maximum number of instructions an out-of-line copy of a -self-recursive inline -function can grow into by performing recursive inlining. +@item ipa-cp-value-list-size +IPA-CP attempts to track all possible values and types passed to a function's +parameter in order to propagate them and perform devirtualization. +@option{ipa-cp-value-list-size} is the maximum number of values and types it +stores per one formal parameter of a function. -@option{--param max-inline-insns-recursive} applies to functions -declared inline. -For functions not declared inline, recursive inlining -happens only when @option{-finline-functions} (included in @option{-O3}) is -enabled; @option{--param max-inline-insns-recursive-auto} applies instead. The -default value is 450. +@item ipa-cp-eval-threshold +IPA-CP calculates its own score of cloning profitability heuristics +and performs those cloning opportunities with scores that exceed +@option{ipa-cp-eval-threshold}. -@item max-inline-recursive-depth -@itemx max-inline-recursive-depth-auto -Specifies the maximum recursion depth used for recursive inlining. +@item ipa-cp-recursion-penalty +Percentage penalty the recursive functions will receive when they +are evaluated for cloning. -@option{--param max-inline-recursive-depth} applies to functions -declared inline. For functions not declared inline, recursive inlining -happens only when @option{-finline-functions} (included in @option{-O3}) is -enabled; @option{--param max-inline-recursive-depth-auto} applies instead. The -default value is 8. +@item ipa-cp-single-call-penalty +Percentage penalty functions containg a single call to another +function will receive when they are evaluated for cloning. -@item min-inline-recursive-probability -Recursive inlining is profitable only for function having deep recursion -in average and can hurt for function having little recursion depth by -increasing the prologue size or complexity of function body to other -optimizers. -When profile feedback is available (see @option{-fprofile-generate}) the actual -recursion depth can be guessed from probability that function recurses via a -given call expression. This parameter limits inlining only to call expressions -whose probability exceeds the given threshold (in percents). -The default value is 10. +@item ipa-max-agg-items +IPA-CP is also capable to propagate a number of scalar values passed +in an aggregate. @option{ipa-max-agg-items} controls the maximum +number of such values per one parameter. -@item early-inlining-insns -Specify growth that the early inliner can make. In effect it increases -the amount of inlining for code having a large abstraction penalty. -The default value is 14. +@item ipa-cp-loop-hint-bonus +When IPA-CP determines that a cloning candidate would make the number +of iterations of a loop known, it adds a bonus of +@option{ipa-cp-loop-hint-bonus} to the profitability score of +the candidate. -@item max-early-inliner-iterations -Limit of iterations of the early inliner. This basically bounds -the number of nested indirect calls the early inliner can resolve. -Deeper chains are still handled by late inlining. +@item ipa-cp-array-index-hint-bonus +When IPA-CP determines that a cloning candidate would make the index of +an array access known, it adds a bonus of +@option{ipa-cp-array-index-hint-bonus} to the profitability +score of the candidate. -@item comdat-sharing-probability -Probability (in percent) that C++ inline function with comdat visibility -are shared across multiple compilation units. The default value is 20. +@item ipa-max-aa-steps +During its analysis of function bodies, IPA-CP employs alias analysis +in order to track values pointed to by function parameters. In order +not spend too much time analyzing huge functions, it gives up and +consider all memory clobbered after examining +@option{ipa-max-aa-steps} statements modifying memory. -@item profile-func-internal-id -A parameter to control whether to use function internal id in profile -database lookup. If the value is 0, the compiler uses an id that -is based on function assembler name and filename, which makes old profile -data more tolerant to source changes such as function reordering etc. -The default value is 0. +@item lto-partitions +Specify desired number of partitions produced during WHOPR compilation. +The number of partitions should exceed the number of CPUs used for compilation. +The default value is 32. -@item min-vect-loop-bound -The minimum number of iterations under which loops are not vectorized -when @option{-ftree-vectorize} is used. The number of iterations after -vectorization needs to be greater than the value specified by this option -to allow vectorization. The default value is 0. +@item lto-minpartition +Size of minimal partition for WHOPR (in estimated instructions). +This prevents expenses of splitting very small programs into too many +partitions. -@item gcse-cost-distance-ratio -Scaling factor in calculation of maximum distance an expression -can be moved by GCSE optimizations. This is currently supported only in the -code hoisting pass. The bigger the ratio, the more aggressive code hoisting -is with simple expressions, i.e., the expressions that have cost -less than @option{gcse-unrestricted-cost}. Specifying 0 disables -hoisting of simple expressions. The default value is 10. +@item cxx-max-namespaces-for-diagnostic-help +The maximum number of namespaces to consult for suggestions when C++ +name lookup fails for an identifier. The default is 1000. -@item gcse-unrestricted-cost -Cost, roughly measured as the cost of a single typical machine -instruction, at which GCSE optimizations do not constrain -the distance an expression can travel. This is currently -supported only in the code hoisting pass. The lesser the cost, -the more aggressive code hoisting is. Specifying 0 -allows all expressions to travel unrestricted distances. -The default value is 3. +@item sink-frequency-threshold +The maximum relative execution frequency (in percents) of the target block +relative to a statement's original block to allow statement sinking of a +statement. Larger numbers result in more aggressive statement sinking. +The default value is 75. A small positive adjustment is applied for +statements with memory operands as those are even more profitable so sink. -@item max-hoist-depth -The depth of search in the dominator tree for expressions to hoist. -This is used to avoid quadratic behavior in hoisting algorithm. -The value of 0 does not limit on the search, but may slow down compilation -of huge functions. The default value is 30. +@item max-stores-to-sink +The maximum number of conditional stores paires that can be sunk. Set to 0 +if either vectorization (@option{-ftree-vectorize}) or if-conversion +(@option{-ftree-loop-if-convert}) is disabled. The default is 2. -@item max-tail-merge-comparisons -The maximum amount of similar bbs to compare a bb with. This is used to -avoid quadratic behavior in tree tail merging. The default value is 10. +@item allow-store-data-races +Allow optimizers to introduce new data races on stores. +Set to 1 to allow, otherwise to 0. This option is enabled by default +at optimization level @option{-Ofast}. -@item max-tail-merge-iterations -The maximum amount of iterations of the pass over the function. This is used to -limit compilation time in tree tail merging. The default value is 2. +@item case-values-threshold +The smallest number of different values for which it is best to use a +jump-table instead of a tree of conditional branches. If the value is +0, use the default for the machine. The default is 0. -@item max-unrolled-insns -The maximum number of instructions that a loop may have to be unrolled. -If a loop is unrolled, this parameter also determines how many times -the loop code is unrolled. +@item tree-reassoc-width +Set the maximum number of instructions executed in parallel in +reassociated tree. This parameter overrides target dependent +heuristics used by default if has non zero value. -@item max-average-unrolled-insns -The maximum number of instructions biased by probabilities of their execution -that a loop may have to be unrolled. If a loop is unrolled, -this parameter also determines how many times the loop code is unrolled. +@item sched-pressure-algorithm +Choose between the two available implementations of +@option{-fsched-pressure}. Algorithm 1 is the original implementation +and is the more likely to prevent instructions from being reordered. +Algorithm 2 was designed to be a compromise between the relatively +conservative approach taken by algorithm 1 and the rather aggressive +approach taken by the default scheduler. It relies more heavily on +having a regular register file and accurate register pressure classes. +See @file{haifa-sched.c} in the GCC sources for more details. -@item max-unroll-times -The maximum number of unrollings of a single loop. +The default choice depends on the target. -@item max-peeled-insns -The maximum number of instructions that a loop may have to be peeled. -If a loop is peeled, this parameter also determines how many times -the loop code is peeled. +@item max-slsr-cand-scan +Set the maximum number of existing candidates that are considered when +seeking a basis for a new straight-line strength reduction candidate. -@item max-peel-times -The maximum number of peelings of a single loop. +@item asan-globals +Enable buffer overflow detection for global objects. This kind +of protection is enabled by default if you are using +@option{-fsanitize=address} option. +To disable global objects protection use @option{--param asan-globals=0}. -@item max-peel-branches -The maximum number of branches on the hot path through the peeled sequence. +@item asan-stack +Enable buffer overflow detection for stack objects. This kind of +protection is enabled by default when using @option{-fsanitize=address}. +To disable stack protection use @option{--param asan-stack=0} option. -@item max-completely-peeled-insns -The maximum number of insns of a completely peeled loop. +@item asan-instrument-reads +Enable buffer overflow detection for memory reads. This kind of +protection is enabled by default when using @option{-fsanitize=address}. +To disable memory reads protection use +@option{--param asan-instrument-reads=0}. -@item max-completely-peel-times -The maximum number of iterations of a loop to be suitable for complete peeling. +@item asan-instrument-writes +Enable buffer overflow detection for memory writes. This kind of +protection is enabled by default when using @option{-fsanitize=address}. +To disable memory writes protection use +@option{--param asan-instrument-writes=0} option. -@item max-completely-peel-loop-nest-depth -The maximum depth of a loop nest suitable for complete peeling. +@item asan-memintrin +Enable detection for built-in functions. This kind of protection +is enabled by default when using @option{-fsanitize=address}. +To disable built-in functions protection use +@option{--param asan-memintrin=0}. -@item max-unswitch-insns -The maximum number of insns of an unswitched loop. +@item asan-use-after-return +Enable detection of use-after-return. This kind of protection +is enabled by default when using @option{-fsanitize=address} option. +To disable use-after-return detection use +@option{--param asan-use-after-return=0}. -@item max-unswitch-level -The maximum number of branches unswitched in a single loop. +@item asan-instrumentation-with-call-threshold +If number of memory accesses in function being instrumented +is greater or equal to this number, use callbacks instead of inline checks. +E.g. to disable inline code use +@option{--param asan-instrumentation-with-call-threshold=0}. -@item lim-expensive -The minimum cost of an expensive expression in the loop invariant motion. +@item chkp-max-ctor-size +Static constructors generated by Pointer Bounds Checker may become very +large and significantly increase compile time at optimization level +@option{-O1} and higher. This parameter is a maximum nubmer of statements +in a single generated constructor. Default value is 5000. -@item iv-consider-all-candidates-bound -Bound on number of candidates for induction variables, below which -all candidates are considered for each use in induction variable -optimizations. If there are more candidates than this, -only the most relevant ones are considered to avoid quadratic time complexity. +@item max-fsm-thread-path-insns +Maximum number of instructions to copy when duplicating blocks on a +finite state automaton jump thread path. The default is 100. -@item iv-max-considered-uses -The induction variable optimizations give up on loops that contain more -induction variable uses. +@item max-fsm-thread-length +Maximum number of basic blocks on a finite state automaton jump thread +path. The default is 10. -@item iv-always-prune-cand-set-bound -If the number of candidates in the set is smaller than this value, -always try to remove unnecessary ivs from the set -when adding a new one. +@item max-fsm-thread-paths +Maximum number of new jump thread paths to create for a finite state +automaton. The default is 50. -@item scev-max-expr-size -Bound on size of expressions used in the scalar evolutions analyzer. -Large expressions slow the analyzer. +@item parloops-chunk-size +Chunk size of omp schedule for loops parallelized by parloops. The default +is 0. -@item scev-max-expr-complexity -Bound on the complexity of the expressions in the scalar evolutions analyzer. -Complex expressions slow the analyzer. +@item parloops-schedule +Schedule type of omp schedule for loops parallelized by parloops (static, +dynamic, guided, auto, runtime). The default is static. -@item vect-max-version-for-alignment-checks -The maximum number of run-time checks that can be performed when -doing loop versioning for alignment in the vectorizer. +@item max-ssa-name-query-depth +Maximum depth of recursion when querying properties of SSA names in things +like fold routines. One level of recursion corresponds to following a +use-def chain. +@end table +@end table -@item vect-max-version-for-alias-checks -The maximum number of run-time checks that can be performed when -doing loop versioning for alias in the vectorizer. +@node Instrumentation Options +@section Program Instrumentation Options +@cindex instrumentation options +@cindex program instrumentation options +@cindex run-time error checking options +@cindex profiling options +@cindex options, program instrumentation +@cindex options, run-time error checking +@cindex options, profiling + +GCC supports a number of command-line options that control adding +run-time instrumentation to the code it normally generates. +For example, one purpose of instrumentation is collect profiling +statistics for use in finding program hot spots, code coverage +analysis, or profile-guided optimizations. +Another class of program instrumentation is adding run-time checking +to detect programming errors like invalid pointer +dereferences or out-of-bounds array accesses, as well as deliberately +hostile attacks such as stack smashing or C++ vtable hijacking. +There is also a general hook which can be used to implement other +forms of tracing or function-level instrumentation for debug or +program analysis purposes. -@item vect-max-peeling-for-alignment -The maximum number of loop peels to enhance access alignment -for vectorizer. Value -1 means 'no limit'. +@table @gcctabopt +@cindex @command{prof} +@item -p +@opindex p +Generate extra code to write profile information suitable for the +analysis program @command{prof}. You must use this option when compiling +the source files you want data about, and you must also use it when +linking. -@item max-iterations-to-track -The maximum number of iterations of a loop the brute-force algorithm -for analysis of the number of iterations of the loop tries to evaluate. +@cindex @command{gprof} +@item -pg +@opindex pg +Generate extra code to write profile information suitable for the +analysis program @command{gprof}. You must use this option when compiling +the source files you want data about, and you must also use it when +linking. -@item hot-bb-count-ws-permille -A basic block profile count is considered hot if it contributes to -the given permillage (i.e. 0...1000) of the entire profiled execution. +@item -fprofile-arcs +@opindex fprofile-arcs +Add code so that program flow @dfn{arcs} are instrumented. During +execution the program records how many times each branch and call is +executed and how many times it is taken or returns. When the compiled +program exits it saves this data to a file called +@file{@var{auxname}.gcda} for each source file. The data may be used for +profile-directed optimizations (@option{-fbranch-probabilities}), or for +test coverage analysis (@option{-ftest-coverage}). Each object file's +@var{auxname} is generated from the name of the output file, if +explicitly specified and it is not the final executable, otherwise it is +the basename of the source file. In both cases any suffix is removed +(e.g.@: @file{foo.gcda} for input file @file{dir/foo.c}, or +@file{dir/foo.gcda} for output file specified as @option{-o dir/foo.o}). +@xref{Cross-profiling}. -@item hot-bb-frequency-fraction -Select fraction of the entry block frequency of executions of basic block in -function given basic block needs to have to be considered hot. +@cindex @command{gcov} +@item --coverage +@opindex coverage -@item max-predicted-iterations -The maximum number of loop iterations we predict statically. This is useful -in cases where a function contains a single loop with known bound and -another loop with unknown bound. -The known number of iterations is predicted correctly, while -the unknown number of iterations average to roughly 10. This means that the -loop without bounds appears artificially cold relative to the other one. +This option is used to compile and link code instrumented for coverage +analysis. The option is a synonym for @option{-fprofile-arcs} +@option{-ftest-coverage} (when compiling) and @option{-lgcov} (when +linking). See the documentation for those options for more details. -@item builtin-expect-probability -Control the probability of the expression having the specified value. This -parameter takes a percentage (i.e. 0 ... 100) as input. -The default probability of 90 is obtained empirically. +@itemize -@item align-threshold +@item +Compile the source files with @option{-fprofile-arcs} plus optimization +and code generation options. For test coverage analysis, use the +additional @option{-ftest-coverage} option. You do not need to profile +every source file in a program. -Select fraction of the maximal frequency of executions of a basic block in -a function to align the basic block. +@item +Link your object files with @option{-lgcov} or @option{-fprofile-arcs} +(the latter implies the former). -@item align-loop-iterations +@item +Run the program on a representative workload to generate the arc profile +information. This may be repeated any number of times. You can run +concurrent instances of your program, and provided that the file system +supports locking, the data files will be correctly updated. Also +@code{fork} calls are detected and correctly handled (double counting +will not happen). -A loop expected to iterate at least the selected number of iterations is -aligned. +@item +For profile-directed optimizations, compile the source files again with +the same optimization and code generation options plus +@option{-fbranch-probabilities} (@pxref{Optimize Options,,Options that +Control Optimization}). -@item tracer-dynamic-coverage -@itemx tracer-dynamic-coverage-feedback +@item +For test coverage analysis, use @command{gcov} to produce human readable +information from the @file{.gcno} and @file{.gcda} files. Refer to the +@command{gcov} documentation for further information. -This value is used to limit superblock formation once the given percentage of -executed instructions is covered. This limits unnecessary code size -expansion. +@end itemize -The @option{tracer-dynamic-coverage-feedback} parameter -is used only when profile -feedback is available. The real profiles (as opposed to statically estimated -ones) are much less balanced allowing the threshold to be larger value. +With @option{-fprofile-arcs}, for each function of your program GCC +creates a program flow graph, then finds a spanning tree for the graph. +Only arcs that are not on the spanning tree have to be instrumented: the +compiler adds code to count the number of times that these arcs are +executed. When an arc is the only exit or only entrance to a block, the +instrumentation code can be added to the block; otherwise, a new basic +block must be created to hold the instrumentation code. -@item tracer-max-code-growth -Stop tail duplication once code growth has reached given percentage. This is -a rather artificial limit, as most of the duplicates are eliminated later in -cross jumping, so it may be set to much higher values than is the desired code -growth. +@need 2000 +@item -ftest-coverage +@opindex ftest-coverage +Produce a notes file that the @command{gcov} code-coverage utility +(@pxref{Gcov,, @command{gcov}---a Test Coverage Program}) can use to +show program coverage. Each source file's note file is called +@file{@var{auxname}.gcno}. Refer to the @option{-fprofile-arcs} option +above for a description of @var{auxname} and instructions on how to +generate test coverage data. Coverage data matches the source files +more closely if you do not optimize. -@item tracer-min-branch-ratio +@item -fprofile-dir=@var{path} +@opindex fprofile-dir -Stop reverse growth when the reverse probability of best edge is less than this -threshold (in percent). +Set the directory to search for the profile data files in to @var{path}. +This option affects only the profile data generated by +@option{-fprofile-generate}, @option{-ftest-coverage}, @option{-fprofile-arcs} +and used by @option{-fprofile-use} and @option{-fbranch-probabilities} +and its related options. Both absolute and relative paths can be used. +By default, GCC uses the current directory as @var{path}, thus the +profile data file appears in the same directory as the object file. -@item tracer-min-branch-ratio -@itemx tracer-min-branch-ratio-feedback +@item -fprofile-generate +@itemx -fprofile-generate=@var{path} +@opindex fprofile-generate -Stop forward growth if the best edge has probability lower than this -threshold. +Enable options usually used for instrumenting application to produce +profile useful for later recompilation with profile feedback based +optimization. You must use @option{-fprofile-generate} both when +compiling and when linking your program. -Similarly to @option{tracer-dynamic-coverage} two values are present, one for -compilation for profile feedback and one for compilation without. The value -for compilation with profile feedback needs to be more conservative (higher) in -order to make tracer effective. +The following options are enabled: @option{-fprofile-arcs}, @option{-fprofile-values}, @option{-fvpt}. -@item max-cse-path-length +If @var{path} is specified, GCC looks at the @var{path} to find +the profile feedback data files. See @option{-fprofile-dir}. -The maximum number of basic blocks on path that CSE considers. -The default is 10. +To optimize the program based on the collected profile information, use +@option{-fprofile-use}. @xref{Optimize Options}, for more information. -@item max-cse-insns -The maximum number of instructions CSE processes before flushing. -The default is 1000. +@item -fsanitize=address +@opindex fsanitize=address +Enable AddressSanitizer, a fast memory error detector. +Memory access instructions are instrumented to detect +out-of-bounds and use-after-free bugs. +See @uref{https://github.com/google/sanitizers/wiki/AddressSanitizer} for +more details. The run-time behavior can be influenced using the +@env{ASAN_OPTIONS} environment variable. When set to @code{help=1}, +the available options are shown at startup of the instrumended program. See +@url{https://github.com/google/sanitizers/wiki/AddressSanitizerFlags#run-time-flags} +for a list of supported options. -@item ggc-min-expand +@item -fsanitize=kernel-address +@opindex fsanitize=kernel-address +Enable AddressSanitizer for Linux kernel. +See @uref{https://github.com/google/kasan/wiki} for more details. -GCC uses a garbage collector to manage its own memory allocation. This -parameter specifies the minimum percentage by which the garbage -collector's heap should be allowed to expand between collections. -Tuning this may improve compilation speed; it has no effect on code -generation. +@item -fsanitize=thread +@opindex fsanitize=thread +Enable ThreadSanitizer, a fast data race detector. +Memory access instructions are instrumented to detect +data race bugs. See @uref{https://github.com/google/sanitizers/wiki#threadsanitizer} for more +details. The run-time behavior can be influenced using the @env{TSAN_OPTIONS} +environment variable; see +@url{https://github.com/google/sanitizers/wiki/ThreadSanitizerFlags} for a list of +supported options. -The default is 30% + 70% * (RAM/1GB) with an upper bound of 100% when -RAM >= 1GB@. If @code{getrlimit} is available, the notion of ``RAM'' is -the smallest of actual RAM and @code{RLIMIT_DATA} or @code{RLIMIT_AS}. If -GCC is not able to calculate RAM on a particular platform, the lower -bound of 30% is used. Setting this parameter and -@option{ggc-min-heapsize} to zero causes a full collection to occur at -every opportunity. This is extremely slow, but can be useful for -debugging. +@item -fsanitize=leak +@opindex fsanitize=leak +Enable LeakSanitizer, a memory leak detector. +This option only matters for linking of executables and if neither +@option{-fsanitize=address} nor @option{-fsanitize=thread} is used. In that +case the executable is linked against a library that overrides @code{malloc} +and other allocator functions. See +@uref{https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer} for more +details. The run-time behavior can be influenced using the +@env{LSAN_OPTIONS} environment variable. -@item ggc-min-heapsize +@item -fsanitize=undefined +@opindex fsanitize=undefined +Enable UndefinedBehaviorSanitizer, a fast undefined behavior detector. +Various computations are instrumented to detect undefined behavior +at runtime. Current suboptions are: -Minimum size of the garbage collector's heap before it begins bothering -to collect garbage. The first collection occurs after the heap expands -by @option{ggc-min-expand}% beyond @option{ggc-min-heapsize}. Again, -tuning this may improve compilation speed, and has no effect on code -generation. +@table @gcctabopt -The default is the smaller of RAM/8, RLIMIT_RSS, or a limit that -tries to ensure that RLIMIT_DATA or RLIMIT_AS are not exceeded, but -with a lower bound of 4096 (four megabytes) and an upper bound of -131072 (128 megabytes). If GCC is not able to calculate RAM on a -particular platform, the lower bound is used. Setting this parameter -very large effectively disables garbage collection. Setting this -parameter and @option{ggc-min-expand} to zero causes a full collection -to occur at every opportunity. +@item -fsanitize=shift +@opindex fsanitize=shift +This option enables checking that the result of a shift operation is +not undefined. Note that what exactly is considered undefined differs +slightly between C and C++, as well as between ISO C90 and C99, etc. -@item max-reload-search-insns -The maximum number of instruction reload should look backward for equivalent -register. Increasing values mean more aggressive optimization, making the -compilation time increase with probably slightly better performance. -The default value is 100. +@item -fsanitize=integer-divide-by-zero +@opindex fsanitize=integer-divide-by-zero +Detect integer division by zero as well as @code{INT_MIN / -1} division. -@item max-cselib-memory-locations -The maximum number of memory locations cselib should take into account. -Increasing values mean more aggressive optimization, making the compilation time -increase with probably slightly better performance. The default value is 500. +@item -fsanitize=unreachable +@opindex fsanitize=unreachable +With this option, the compiler turns the @code{__builtin_unreachable} +call into a diagnostics message call instead. When reaching the +@code{__builtin_unreachable} call, the behavior is undefined. -@item reorder-blocks-duplicate -@itemx reorder-blocks-duplicate-feedback +@item -fsanitize=vla-bound +@opindex fsanitize=vla-bound +This option instructs the compiler to check that the size of a variable +length array is positive. -Used by the basic block reordering pass to decide whether to use unconditional -branch or duplicate the code on its destination. Code is duplicated when its -estimated size is smaller than this value multiplied by the estimated size of -unconditional jump in the hot spots of the program. +@item -fsanitize=null +@opindex fsanitize=null +This option enables pointer checking. Particularly, the application +built with this option turned on will issue an error message when it +tries to dereference a NULL pointer, or if a reference (possibly an +rvalue reference) is bound to a NULL pointer, or if a method is invoked +on an object pointed by a NULL pointer. -The @option{reorder-block-duplicate-feedback} parameter -is used only when profile -feedback is available. It may be set to higher values than -@option{reorder-block-duplicate} since information about the hot spots is more -accurate. +@item -fsanitize=return +@opindex fsanitize=return +This option enables return statement checking. Programs +built with this option turned on will issue an error message +when the end of a non-void function is reached without actually +returning a value. This option works in C++ only. -@item max-sched-ready-insns -The maximum number of instructions ready to be issued the scheduler should -consider at any given time during the first scheduling pass. Increasing -values mean more thorough searches, making the compilation time increase -with probably little benefit. The default value is 100. +@item -fsanitize=signed-integer-overflow +@opindex fsanitize=signed-integer-overflow +This option enables signed integer overflow checking. We check that +the result of @code{+}, @code{*}, and both unary and binary @code{-} +does not overflow in the signed arithmetics. Note, integer promotion +rules must be taken into account. That is, the following is not an +overflow: +@smallexample +signed char a = SCHAR_MAX; +a++; +@end smallexample -@item max-sched-region-blocks -The maximum number of blocks in a region to be considered for -interblock scheduling. The default value is 10. +@item -fsanitize=bounds +@opindex fsanitize=bounds +This option enables instrumentation of array bounds. Various out of bounds +accesses are detected. Flexible array members, flexible array member-like +arrays, and initializers of variables with static storage are not instrumented. -@item max-pipeline-region-blocks -The maximum number of blocks in a region to be considered for -pipelining in the selective scheduler. The default value is 15. +@item -fsanitize=bounds-strict +@opindex fsanitize=bounds-strict +This option enables strict instrumentation of array bounds. Most out of bounds +accesses are detected, including flexible array members and flexible array +member-like arrays. Initializers of variables with static storage are not +instrumented. -@item max-sched-region-insns -The maximum number of insns in a region to be considered for -interblock scheduling. The default value is 100. +@item -fsanitize=alignment +@opindex fsanitize=alignment -@item max-pipeline-region-insns -The maximum number of insns in a region to be considered for -pipelining in the selective scheduler. The default value is 200. +This option enables checking of alignment of pointers when they are +dereferenced, or when a reference is bound to insufficiently aligned target, +or when a method or constructor is invoked on insufficiently aligned object. -@item min-spec-prob -The minimum probability (in percents) of reaching a source block -for interblock speculative scheduling. The default value is 40. +@item -fsanitize=object-size +@opindex fsanitize=object-size +This option enables instrumentation of memory references using the +@code{__builtin_object_size} function. Various out of bounds pointer +accesses are detected. -@item max-sched-extend-regions-iters -The maximum number of iterations through CFG to extend regions. -A value of 0 (the default) disables region extensions. +@item -fsanitize=float-divide-by-zero +@opindex fsanitize=float-divide-by-zero +Detect floating-point division by zero. Unlike other similar options, +@option{-fsanitize=float-divide-by-zero} is not enabled by +@option{-fsanitize=undefined}, since floating-point division by zero can +be a legitimate way of obtaining infinities and NaNs. -@item max-sched-insn-conflict-delay -The maximum conflict delay for an insn to be considered for speculative motion. -The default value is 3. +@item -fsanitize=float-cast-overflow +@opindex fsanitize=float-cast-overflow +This option enables floating-point type to integer conversion checking. +We check that the result of the conversion does not overflow. +Unlike other similar options, @option{-fsanitize=float-cast-overflow} is +not enabled by @option{-fsanitize=undefined}. +This option does not work well with @code{FE_INVALID} exceptions enabled. -@item sched-spec-prob-cutoff -The minimal probability of speculation success (in percents), so that -speculative insns are scheduled. -The default value is 40. +@item -fsanitize=nonnull-attribute +@opindex fsanitize=nonnull-attribute -@item sched-spec-state-edge-prob-cutoff -The minimum probability an edge must have for the scheduler to save its -state across it. -The default value is 10. +This option enables instrumentation of calls, checking whether null values +are not passed to arguments marked as requiring a non-null value by the +@code{nonnull} function attribute. -@item sched-mem-true-dep-cost -Minimal distance (in CPU cycles) between store and load targeting same -memory locations. The default value is 1. +@item -fsanitize=returns-nonnull-attribute +@opindex fsanitize=returns-nonnull-attribute -@item selsched-max-lookahead -The maximum size of the lookahead window of selective scheduling. It is a -depth of search for available instructions. -The default value is 50. +This option enables instrumentation of return statements in functions +marked with @code{returns_nonnull} function attribute, to detect returning +of null values from such functions. -@item selsched-max-sched-times -The maximum number of times that an instruction is scheduled during -selective scheduling. This is the limit on the number of iterations -through which the instruction may be pipelined. The default value is 2. +@item -fsanitize=bool +@opindex fsanitize=bool -@item selsched-max-insns-to-rename -The maximum number of best instructions in the ready list that are considered -for renaming in the selective scheduler. The default value is 2. +This option enables instrumentation of loads from bool. If a value other +than 0/1 is loaded, a run-time error is issued. -@item sms-min-sc -The minimum value of stage count that swing modulo scheduler -generates. The default value is 2. +@item -fsanitize=enum +@opindex fsanitize=enum -@item max-last-value-rtl -The maximum size measured as number of RTLs that can be recorded in an expression -in combiner for a pseudo register as last known value of that register. The default -is 10000. +This option enables instrumentation of loads from an enum type. If +a value outside the range of values for the enum type is loaded, +a run-time error is issued. -@item max-combine-insns -The maximum number of instructions the RTL combiner tries to combine. -The default value is 2 at @option{-Og} and 4 otherwise. +@item -fsanitize=vptr +@opindex fsanitize=vptr -@item integer-share-limit -Small integer constants can use a shared data structure, reducing the -compiler's memory usage and increasing its speed. This sets the maximum -value of a shared integer constant. The default value is 256. +This option enables instrumentation of C++ member function calls, member +accesses and some conversions between pointers to base and derived classes, +to verify the referenced object has the correct dynamic type. -@item ssp-buffer-size -The minimum size of buffers (i.e.@: arrays) that receive stack smashing -protection when @option{-fstack-protection} is used. +@end table -@item min-size-for-stack-sharing -The minimum size of variables taking part in stack slot sharing when not -optimizing. The default value is 32. +While @option{-ftrapv} causes traps for signed overflows to be emitted, +@option{-fsanitize=undefined} gives a diagnostic message. +This currently works only for the C family of languages. -@item max-jump-thread-duplication-stmts -Maximum number of statements allowed in a block that needs to be -duplicated when threading jumps. +@item -fno-sanitize=all +@opindex fno-sanitize=all -@item max-fields-for-field-sensitive -Maximum number of fields in a structure treated in -a field sensitive manner during pointer analysis. The default is zero -for @option{-O0} and @option{-O1}, -and 100 for @option{-Os}, @option{-O2}, and @option{-O3}. +This option disables all previously enabled sanitizers. +@option{-fsanitize=all} is not allowed, as some sanitizers cannot be used +together. -@item prefetch-latency -Estimate on average number of instructions that are executed before -prefetch finishes. The distance prefetched ahead is proportional -to this constant. Increasing this number may also lead to less -streams being prefetched (see @option{simultaneous-prefetches}). +@item -fasan-shadow-offset=@var{number} +@opindex fasan-shadow-offset +This option forces GCC to use custom shadow offset in AddressSanitizer checks. +It is useful for experimenting with different shadow memory layouts in +Kernel AddressSanitizer. -@item simultaneous-prefetches -Maximum number of prefetches that can run at the same time. +@item -fsanitize-sections=@var{s1},@var{s2},... +@opindex fsanitize-sections +Sanitize global variables in selected user-defined sections. @var{si} may +contain wildcards. -@item l1-cache-line-size -The size of cache line in L1 cache, in bytes. +@item -fsanitize-recover@r{[}=@var{opts}@r{]} +@opindex fsanitize-recover +@opindex fno-sanitize-recover +@option{-fsanitize-recover=} controls error recovery mode for sanitizers +mentioned in comma-separated list of @var{opts}. Enabling this option +for a sanitizer component causes it to attempt to continue +running the program as if no error happened. This means multiple +runtime errors can be reported in a single program run, and the exit +code of the program may indicate success even when errors +have been reported. The @option{-fno-sanitize-recover=} option +can be used to alter +this behavior: only the first detected error is reported +and program then exits with a non-zero exit code. -@item l1-cache-size -The size of L1 cache, in kilobytes. +Currently this feature only works for @option{-fsanitize=undefined} (and its suboptions +except for @option{-fsanitize=unreachable} and @option{-fsanitize=return}), +@option{-fsanitize=float-cast-overflow}, @option{-fsanitize=float-divide-by-zero}, +@option{-fsanitize=kernel-address} and @option{-fsanitize=address}. +For these sanitizers error recovery is turned on by default, except @option{-fsanitize=address}, +for which this feature is experimental. +@option{-fsanitize-recover=all} and @option{-fno-sanitize-recover=all} is also +accepted, the former enables recovery for all sanitizers that support it, +the latter disables recovery for all sanitizers that support it. -@item l2-cache-size -The size of L2 cache, in kilobytes. +Syntax without explicit @var{opts} parameter is deprecated. It is equivalent to +@smallexample +-fsanitize-recover=undefined,float-cast-overflow,float-divide-by-zero +@end smallexample +@noindent +Similarly @option{-fno-sanitize-recover} is equivalent to +@smallexample +-fno-sanitize-recover=undefined,float-cast-overflow,float-divide-by-zero +@end smallexample -@item min-insn-to-prefetch-ratio -The minimum ratio between the number of instructions and the -number of prefetches to enable prefetching in a loop. +@item -fsanitize-undefined-trap-on-error +@opindex fsanitize-undefined-trap-on-error +The @option{-fsanitize-undefined-trap-on-error} option instructs the compiler to +report undefined behavior using @code{__builtin_trap} rather than +a @code{libubsan} library routine. The advantage of this is that the +@code{libubsan} library is not needed and is not linked in, so this +is usable even in freestanding environments. -@item prefetch-min-insn-to-mem-ratio -The minimum ratio between the number of instructions and the -number of memory references to enable prefetching in a loop. +@item -fsanitize-coverage=trace-pc +@opindex fsanitize-coverage=trace-pc +Enable coverage-guided fuzzing code instrumentation. +Inserts call to __sanitizer_cov_trace_pc into every basic block. + +@item -fbounds-check +@opindex fbounds-check +For front ends that support it, generate additional code to check that +indices used to access arrays are within the declared range. This is +currently only supported by the Java and Fortran front ends, where +this option defaults to true and false respectively. -@item use-canonical-types -Whether the compiler should use the ``canonical'' type system. By -default, this should always be 1, which uses a more efficient internal -mechanism for comparing types in C++ and Objective-C++. However, if -bugs in the canonical type system are causing compilation failures, -set this value to 0 to disable canonical types. +@item -fcheck-pointer-bounds +@opindex fcheck-pointer-bounds +@opindex fno-check-pointer-bounds +@cindex Pointer Bounds Checker options +Enable Pointer Bounds Checker instrumentation. Each memory reference +is instrumented with checks of the pointer used for memory access against +bounds associated with that pointer. -@item switch-conversion-max-branch-ratio -Switch initialization conversion refuses to create arrays that are -bigger than @option{switch-conversion-max-branch-ratio} times the number of -branches in the switch. +Currently there +is only an implementation for Intel MPX available, thus x86 target +and @option{-mmpx} are required to enable this feature. +MPX-based instrumentation requires +a runtime library to enable MPX in hardware and handle bounds +violation signals. By default when @option{-fcheck-pointer-bounds} +and @option{-mmpx} options are used to link a program, the GCC driver +links against the @file{libmpx} runtime library and @file{libmpxwrappers} +library. It also passes '-z bndplt' to a linker in case it supports this +option (which is checked on libmpx configuration). Note that old versions +of linker may ignore option. Gold linker doesn't support '-z bndplt' +option. With no '-z bndplt' support in linker all calls to dynamic libraries +lose passed bounds reducing overall protection level. It's highly +recommended to use linker with '-z bndplt' support. In case such linker +is not available it is adviced to always use @option{-static-libmpxwrappers} +for better protection level or use @option{-static} to completely avoid +external calls to dynamic libraries. MPX-based instrumentation +may be used for debugging and also may be included in production code +to increase program security. Depending on usage, you may +have different requirements for the runtime library. The current version +of the MPX runtime library is more oriented for use as a debugging +tool. MPX runtime library usage implies @option{-lpthread}. See +also @option{-static-libmpx}. The runtime library behavior can be +influenced using various @env{CHKP_RT_*} environment variables. See +@uref{https://gcc.gnu.org/wiki/Intel%20MPX%20support%20in%20the%20GCC%20compiler} +for more details. -@item max-partial-antic-length -Maximum length of the partial antic set computed during the tree -partial redundancy elimination optimization (@option{-ftree-pre}) when -optimizing at @option{-O3} and above. For some sorts of source code -the enhanced partial redundancy elimination optimization can run away, -consuming all of the memory available on the host machine. This -parameter sets a limit on the length of the sets that are computed, -which prevents the runaway behavior. Setting a value of 0 for -this parameter allows an unlimited set length. +Generated instrumentation may be controlled by various +@option{-fchkp-*} options and by the @code{bnd_variable_size} +structure field attribute (@pxref{Type Attributes}) and +@code{bnd_legacy}, and @code{bnd_instrument} function attributes +(@pxref{Function Attributes}). GCC also provides a number of built-in +functions for controlling the Pointer Bounds Checker. @xref{Pointer +Bounds Checker builtins}, for more information. -@item sccvn-max-scc-size -Maximum size of a strongly connected component (SCC) during SCCVN -processing. If this limit is hit, SCCVN processing for the whole -function is not done and optimizations depending on it are -disabled. The default maximum SCC size is 10000. +@item -fchkp-check-incomplete-type +@opindex fchkp-check-incomplete-type +@opindex fno-chkp-check-incomplete-type +Generate pointer bounds checks for variables with incomplete type. +Enabled by default. -@item sccvn-max-alias-queries-per-access -Maximum number of alias-oracle queries we perform when looking for -redundancies for loads and stores. If this limit is hit the search -is aborted and the load or store is not considered redundant. The -number of queries is algorithmically limited to the number of -stores on all paths from the load to the function entry. -The default maxmimum number of queries is 1000. +@item -fchkp-narrow-bounds +@opindex fchkp-narrow-bounds +@opindex fno-chkp-narrow-bounds +Controls bounds used by Pointer Bounds Checker for pointers to object +fields. If narrowing is enabled then field bounds are used. Otherwise +object bounds are used. See also @option{-fchkp-narrow-to-innermost-array} +and @option{-fchkp-first-field-has-own-bounds}. Enabled by default. -@item ira-max-loops-num -IRA uses regional register allocation by default. If a function -contains more loops than the number given by this parameter, only at most -the given number of the most frequently-executed loops form regions -for regional register allocation. The default value of the -parameter is 100. +@item -fchkp-first-field-has-own-bounds +@opindex fchkp-first-field-has-own-bounds +@opindex fno-chkp-first-field-has-own-bounds +Forces Pointer Bounds Checker to use narrowed bounds for the address of the +first field in the structure. By default a pointer to the first field has +the same bounds as a pointer to the whole structure. -@item ira-max-conflict-table-size -Although IRA uses a sophisticated algorithm to compress the conflict -table, the table can still require excessive amounts of memory for -huge functions. If the conflict table for a function could be more -than the size in MB given by this parameter, the register allocator -instead uses a faster, simpler, and lower-quality -algorithm that does not require building a pseudo-register conflict table. -The default value of the parameter is 2000. +@item -fchkp-narrow-to-innermost-array +@opindex fchkp-narrow-to-innermost-array +@opindex fno-chkp-narrow-to-innermost-array +Forces Pointer Bounds Checker to use bounds of the innermost arrays in +case of nested static array access. By default this option is disabled and +bounds of the outermost array are used. -@item ira-loop-reserved-regs -IRA can be used to evaluate more accurate register pressure in loops -for decisions to move loop invariants (see @option{-O3}). The number -of available registers reserved for some other purposes is given -by this parameter. The default value of the parameter is 2, which is -the minimal number of registers needed by typical instructions. -This value is the best found from numerous experiments. +@item -fchkp-optimize +@opindex fchkp-optimize +@opindex fno-chkp-optimize +Enables Pointer Bounds Checker optimizations. Enabled by default at +optimization levels @option{-O}, @option{-O2}, @option{-O3}. -@item lra-inheritance-ebb-probability-cutoff -LRA tries to reuse values reloaded in registers in subsequent insns. -This optimization is called inheritance. EBB is used as a region to -do this optimization. The parameter defines a minimal fall-through -edge probability in percentage used to add BB to inheritance EBB in -LRA. The default value of the parameter is 40. The value was chosen -from numerous runs of SPEC2000 on x86-64. +@item -fchkp-use-fast-string-functions +@opindex fchkp-use-fast-string-functions +@opindex fno-chkp-use-fast-string-functions +Enables use of @code{*_nobnd} versions of string functions (not copying bounds) +by Pointer Bounds Checker. Disabled by default. -@item loop-invariant-max-bbs-in-loop -Loop invariant motion can be very expensive, both in compilation time and -in amount of needed compile-time memory, with very large loops. Loops -with more basic blocks than this parameter won't have loop invariant -motion optimization performed on them. The default value of the -parameter is 1000 for @option{-O1} and 10000 for @option{-O2} and above. +@item -fchkp-use-nochk-string-functions +@opindex fchkp-use-nochk-string-functions +@opindex fno-chkp-use-nochk-string-functions +Enables use of @code{*_nochk} versions of string functions (not checking bounds) +by Pointer Bounds Checker. Disabled by default. -@item loop-max-datarefs-for-datadeps -Building data dapendencies is expensive for very large loops. This -parameter limits the number of data references in loops that are -considered for data dependence analysis. These large loops are no -handled by the optimizations using loop data dependencies. -The default value is 1000. +@item -fchkp-use-static-bounds +@opindex fchkp-use-static-bounds +@opindex fno-chkp-use-static-bounds +Allow Pointer Bounds Checker to generate static bounds holding +bounds of static variables. Enabled by default. -@item max-vartrack-size -Sets a maximum number of hash table slots to use during variable -tracking dataflow analysis of any function. If this limit is exceeded -with variable tracking at assignments enabled, analysis for that -function is retried without it, after removing all debug insns from -the function. If the limit is exceeded even without debug insns, var -tracking analysis is completely disabled for the function. Setting -the parameter to zero makes it unlimited. +@item -fchkp-use-static-const-bounds +@opindex fchkp-use-static-const-bounds +@opindex fno-chkp-use-static-const-bounds +Use statically-initialized bounds for constant bounds instead of +generating them each time they are required. By default enabled when +@option{-fchkp-use-static-bounds} is enabled. -@item max-vartrack-expr-depth -Sets a maximum number of recursion levels when attempting to map -variable names or debug temporaries to value expressions. This trades -compilation time for more complete debug information. If this is set too -low, value expressions that are available and could be represented in -debug information may end up not being used; setting this higher may -enable the compiler to find more complex debug expressions, but compile -time and memory use may grow. The default is 12. +@item -fchkp-treat-zero-dynamic-size-as-infinite +@opindex fchkp-treat-zero-dynamic-size-as-infinite +@opindex fno-chkp-treat-zero-dynamic-size-as-infinite +With this option, objects with incomplete type whose +dynamically-obtained size is zero are treated as having infinite size +instead by Pointer Bounds +Checker. This option may be helpful if a program is linked with a library +missing size information for some symbols. Disabled by default. -@item min-nondebug-insn-uid -Use uids starting at this parameter for nondebug insns. The range below -the parameter is reserved exclusively for debug insns created by -@option{-fvar-tracking-assignments}, but debug insns may get -(non-overlapping) uids above it if the reserved range is exhausted. +@item -fchkp-check-read +@opindex fchkp-check-read +@opindex fno-chkp-check-read +Instructs Pointer Bounds Checker to generate checks for all read +accesses to memory. Enabled by default. -@item ipa-sra-ptr-growth-factor -IPA-SRA replaces a pointer to an aggregate with one or more new -parameters only when their cumulative size is less or equal to -@option{ipa-sra-ptr-growth-factor} times the size of the original -pointer parameter. +@item -fchkp-check-write +@opindex fchkp-check-write +@opindex fno-chkp-check-write +Instructs Pointer Bounds Checker to generate checks for all write +accesses to memory. Enabled by default. -@item sra-max-scalarization-size-Ospeed -@item sra-max-scalarization-size-Osize -The two Scalar Reduction of Aggregates passes (SRA and IPA-SRA) aim to -replace scalar parts of aggregates with uses of independent scalar -variables. These parameters control the maximum size, in storage units, -of aggregate which is considered for replacement when compiling for -speed -(@option{sra-max-scalarization-size-Ospeed}) or size -(@option{sra-max-scalarization-size-Osize}) respectively. +@item -fchkp-store-bounds +@opindex fchkp-store-bounds +@opindex fno-chkp-store-bounds +Instructs Pointer Bounds Checker to generate bounds stores for +pointer writes. Enabled by default. -@item tm-max-aggregate-size -When making copies of thread-local variables in a transaction, this -parameter specifies the size in bytes after which variables are -saved with the logging functions as opposed to save/restore code -sequence pairs. This option only applies when using -@option{-fgnu-tm}. +@item -fchkp-instrument-calls +@opindex fchkp-instrument-calls +@opindex fno-chkp-instrument-calls +Instructs Pointer Bounds Checker to pass pointer bounds to calls. +Enabled by default. -@item graphite-max-nb-scop-params -To avoid exponential effects in the Graphite loop transforms, the -number of parameters in a Static Control Part (SCoP) is bounded. The -default value is 10 parameters. A variable whose value is unknown at -compilation time and defined outside a SCoP is a parameter of the SCoP. +@item -fchkp-instrument-marked-only +@opindex fchkp-instrument-marked-only +@opindex fno-chkp-instrument-marked-only +Instructs Pointer Bounds Checker to instrument only functions +marked with the @code{bnd_instrument} attribute +(@pxref{Function Attributes}). Disabled by default. -@item graphite-max-bbs-per-function -To avoid exponential effects in the detection of SCoPs, the size of -the functions analyzed by Graphite is bounded. The default value is -100 basic blocks. +@item -fchkp-use-wrappers +@opindex fchkp-use-wrappers +@opindex fno-chkp-use-wrappers +Allows Pointer Bounds Checker to replace calls to built-in functions +with calls to wrapper functions. When @option{-fchkp-use-wrappers} +is used to link a program, the GCC driver automatically links +against @file{libmpxwrappers}. See also @option{-static-libmpxwrappers}. +Enabled by default. -@item loop-block-tile-size -Loop blocking or strip mining transforms, enabled with -@option{-floop-block} or @option{-floop-strip-mine}, strip mine each -loop in the loop nest by a given number of iterations. The strip -length can be changed using the @option{loop-block-tile-size} -parameter. The default value is 51 iterations. +@item -fstack-protector +@opindex fstack-protector +Emit extra code to check for buffer overflows, such as stack smashing +attacks. This is done by adding a guard variable to functions with +vulnerable objects. This includes functions that call @code{alloca}, and +functions with buffers larger than 8 bytes. The guards are initialized +when a function is entered and then checked when the function exits. +If a guard check fails, an error message is printed and the program exits. -@item loop-unroll-jam-size -Specify the unroll factor for the @option{-floop-unroll-and-jam} option. The -default value is 4. +@item -fstack-protector-all +@opindex fstack-protector-all +Like @option{-fstack-protector} except that all functions are protected. -@item loop-unroll-jam-depth -Specify the dimension to be unrolled (counting from the most inner loop) -for the @option{-floop-unroll-and-jam}. The default value is 2. +@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 ipa-cp-value-list-size -IPA-CP attempts to track all possible values and types passed to a function's -parameter in order to propagate them and perform devirtualization. -@option{ipa-cp-value-list-size} is the maximum number of values and types it -stores per one formal parameter of a function. +@item -fstack-protector-explicit +@opindex fstack-protector-explicit +Like @option{-fstack-protector} but only protects those functions which +have the @code{stack_protect} attribute. -@item ipa-cp-eval-threshold -IPA-CP calculates its own score of cloning profitability heuristics -and performs those cloning opportunities with scores that exceed -@option{ipa-cp-eval-threshold}. +@item -fstack-check +@opindex fstack-check +Generate code to verify that you do not go beyond the boundary of the +stack. You should specify this flag if you are running in an +environment with multiple threads, but you only rarely need to specify it in +a single-threaded environment since stack overflow is automatically +detected on nearly all systems if there is only one stack. -@item ipa-cp-recursion-penalty -Percentage penalty the recursive functions will receive when they -are evaluated for cloning. +Note that this switch does not actually cause checking to be done; the +operating system or the language runtime must do that. The switch causes +generation of code to ensure that they see the stack being extended. -@item ipa-cp-single-call-penalty -Percentage penalty functions containg a single call to another -function will receive when they are evaluated for cloning. +You can additionally specify a string parameter: @samp{no} means no +checking, @samp{generic} means force the use of old-style checking, +@samp{specific} means use the best checking method and is equivalent +to bare @option{-fstack-check}. +Old-style checking is a generic mechanism that requires no specific +target support in the compiler but comes with the following drawbacks: -@item ipa-max-agg-items -IPA-CP is also capable to propagate a number of scalar values passed -in an aggregate. @option{ipa-max-agg-items} controls the maximum -number of such values per one parameter. +@enumerate +@item +Modified allocation strategy for large objects: they are always +allocated dynamically if their size exceeds a fixed threshold. -@item ipa-cp-loop-hint-bonus -When IPA-CP determines that a cloning candidate would make the number -of iterations of a loop known, it adds a bonus of -@option{ipa-cp-loop-hint-bonus} to the profitability score of -the candidate. +@item +Fixed limit on the size of the static frame of functions: when it is +topped by a particular function, stack checking is not reliable and +a warning is issued by the compiler. -@item ipa-cp-array-index-hint-bonus -When IPA-CP determines that a cloning candidate would make the index of -an array access known, it adds a bonus of -@option{ipa-cp-array-index-hint-bonus} to the profitability -score of the candidate. +@item +Inefficiency: because of both the modified allocation strategy and the +generic implementation, code performance is hampered. +@end enumerate -@item ipa-max-aa-steps -During its analysis of function bodies, IPA-CP employs alias analysis -in order to track values pointed to by function parameters. In order -not spend too much time analyzing huge functions, it gives up and -consider all memory clobbered after examining -@option{ipa-max-aa-steps} statements modifying memory. +Note that old-style stack checking is also the fallback method for +@samp{specific} if no target support has been added in the compiler. -@item lto-partitions -Specify desired number of partitions produced during WHOPR compilation. -The number of partitions should exceed the number of CPUs used for compilation. -The default value is 32. +@item -fstack-limit-register=@var{reg} +@itemx -fstack-limit-symbol=@var{sym} +@itemx -fno-stack-limit +@opindex fstack-limit-register +@opindex fstack-limit-symbol +@opindex fno-stack-limit +Generate code to ensure that the stack does not grow beyond a certain value, +either the value of a register or the address of a symbol. If a larger +stack is required, a signal is raised at run time. For most targets, +the signal is raised before the stack overruns the boundary, so +it is possible to catch the signal without taking special precautions. -@item lto-minpartition -Size of minimal partition for WHOPR (in estimated instructions). -This prevents expenses of splitting very small programs into too many -partitions. +For instance, if the stack starts at absolute address @samp{0x80000000} +and grows downwards, you can use the flags +@option{-fstack-limit-symbol=__stack_limit} and +@option{-Wl,--defsym,__stack_limit=0x7ffe0000} to enforce a stack limit +of 128KB@. Note that this may only work with the GNU linker. -@item cxx-max-namespaces-for-diagnostic-help -The maximum number of namespaces to consult for suggestions when C++ -name lookup fails for an identifier. The default is 1000. +You can locally override stack limit checking by using the +@code{no_stack_limit} function attribute (@pxref{Function Attributes}). -@item sink-frequency-threshold -The maximum relative execution frequency (in percents) of the target block -relative to a statement's original block to allow statement sinking of a -statement. Larger numbers result in more aggressive statement sinking. -The default value is 75. A small positive adjustment is applied for -statements with memory operands as those are even more profitable so sink. +@item -fsplit-stack +@opindex fsplit-stack +Generate code to automatically split the stack before it overflows. +The resulting program has a discontiguous stack which can only +overflow if the program is unable to allocate any more memory. This +is most useful when running threaded programs, as it is no longer +necessary to calculate a good stack size to use for each thread. This +is currently only implemented for the x86 targets running +GNU/Linux. -@item max-stores-to-sink -The maximum number of conditional stores paires that can be sunk. Set to 0 -if either vectorization (@option{-ftree-vectorize}) or if-conversion -(@option{-ftree-loop-if-convert}) is disabled. The default is 2. +When code compiled with @option{-fsplit-stack} calls code compiled +without @option{-fsplit-stack}, there may not be much stack space +available for the latter code to run. If compiling all code, +including library code, with @option{-fsplit-stack} is not an option, +then the linker can fix up these calls so that the code compiled +without @option{-fsplit-stack} always has a large stack. Support for +this is implemented in the gold linker in GNU binutils release 2.21 +and later. -@item allow-store-data-races -Allow optimizers to introduce new data races on stores. -Set to 1 to allow, otherwise to 0. This option is enabled by default -at optimization level @option{-Ofast}. +@item -fvtable-verify=@r{[}std@r{|}preinit@r{|}none@r{]} +@opindex fvtable-verify +This option is only available when compiling C++ code. +It turns on (or off, if using @option{-fvtable-verify=none}) the security +feature that verifies at run time, for every virtual call, that +the vtable pointer through which the call is made is valid for the type of +the object, and has not been corrupted or overwritten. If an invalid vtable +pointer is detected at run time, an error is reported and execution of the +program is immediately halted. -@item case-values-threshold -The smallest number of different values for which it is best to use a -jump-table instead of a tree of conditional branches. If the value is -0, use the default for the machine. The default is 0. +This option causes run-time data structures to be built at program startup, +which are used for verifying the vtable pointers. +The options @samp{std} and @samp{preinit} +control the timing of when these data structures are built. In both cases the +data structures are built before execution reaches @code{main}. Using +@option{-fvtable-verify=std} causes the data structures to be built after +shared libraries have been loaded and initialized. +@option{-fvtable-verify=preinit} causes them to be built before shared +libraries have been loaded and initialized. -@item tree-reassoc-width -Set the maximum number of instructions executed in parallel in -reassociated tree. This parameter overrides target dependent -heuristics used by default if has non zero value. +If this option appears multiple times in the command line with different +values specified, @samp{none} takes highest priority over both @samp{std} and +@samp{preinit}; @samp{preinit} takes priority over @samp{std}. -@item sched-pressure-algorithm -Choose between the two available implementations of -@option{-fsched-pressure}. Algorithm 1 is the original implementation -and is the more likely to prevent instructions from being reordered. -Algorithm 2 was designed to be a compromise between the relatively -conservative approach taken by algorithm 1 and the rather aggressive -approach taken by the default scheduler. It relies more heavily on -having a regular register file and accurate register pressure classes. -See @file{haifa-sched.c} in the GCC sources for more details. +@item -fvtv-debug +@opindex fvtv-debug +When used in conjunction with @option{-fvtable-verify=std} or +@option{-fvtable-verify=preinit}, causes debug versions of the +runtime functions for the vtable verification feature to be called. +This flag also causes the compiler to log information about which +vtable pointers it finds for each class. +This information is written to a file named @file{vtv_set_ptr_data.log} +in the directory named by the environment variable @env{VTV_LOGS_DIR} +if that is defined or the current working directory otherwise. -The default choice depends on the target. +Note: This feature @emph{appends} data to the log file. If you want a fresh log +file, be sure to delete any existing one. -@item max-slsr-cand-scan -Set the maximum number of existing candidates that are considered when -seeking a basis for a new straight-line strength reduction candidate. +@item -fvtv-counts +@opindex fvtv-counts +This is a debugging flag. When used in conjunction with +@option{-fvtable-verify=std} or @option{-fvtable-verify=preinit}, this +causes the compiler to keep track of the total number of virtual calls +it encounters and the number of verifications it inserts. It also +counts the number of calls to certain run-time library functions +that it inserts and logs this information for each compilation unit. +The compiler writes this information to a file named +@file{vtv_count_data.log} in the directory named by the environment +variable @env{VTV_LOGS_DIR} if that is defined or the current working +directory otherwise. It also counts the size of the vtable pointer sets +for each class, and writes this information to @file{vtv_class_set_sizes.log} +in the same directory. -@item asan-globals -Enable buffer overflow detection for global objects. This kind -of protection is enabled by default if you are using -@option{-fsanitize=address} option. -To disable global objects protection use @option{--param asan-globals=0}. +Note: This feature @emph{appends} data to the log files. To get fresh log +files, be sure to delete any existing ones. -@item asan-stack -Enable buffer overflow detection for stack objects. This kind of -protection is enabled by default when using @option{-fsanitize=address}. -To disable stack protection use @option{--param asan-stack=0} option. +@item -finstrument-functions +@opindex finstrument-functions +Generate instrumentation calls for entry and exit to functions. Just +after function entry and just before function exit, the following +profiling functions are called with the address of the current +function and its call site. (On some platforms, +@code{__builtin_return_address} does not work beyond the current +function, so the call site information may not be available to the +profiling functions otherwise.) -@item asan-instrument-reads -Enable buffer overflow detection for memory reads. This kind of -protection is enabled by default when using @option{-fsanitize=address}. -To disable memory reads protection use -@option{--param asan-instrument-reads=0}. +@smallexample +void __cyg_profile_func_enter (void *this_fn, + void *call_site); +void __cyg_profile_func_exit (void *this_fn, + void *call_site); +@end smallexample -@item asan-instrument-writes -Enable buffer overflow detection for memory writes. This kind of -protection is enabled by default when using @option{-fsanitize=address}. -To disable memory writes protection use -@option{--param asan-instrument-writes=0} option. +The first argument is the address of the start of the current function, +which may be looked up exactly in the symbol table. -@item asan-memintrin -Enable detection for built-in functions. This kind of protection -is enabled by default when using @option{-fsanitize=address}. -To disable built-in functions protection use -@option{--param asan-memintrin=0}. +This instrumentation is also done for functions expanded inline in other +functions. The profiling calls indicate where, conceptually, the +inline function is entered and exited. This means that addressable +versions of such functions must be available. If all your uses of a +function are expanded inline, this may mean an additional expansion of +code size. If you use @code{extern inline} in your C code, an +addressable version of such functions must be provided. (This is +normally the case anyway, but if you get lucky and the optimizer always +expands the functions inline, you might have gotten away without +providing static copies.) -@item asan-use-after-return -Enable detection of use-after-return. This kind of protection -is enabled by default when using @option{-fsanitize=address} option. -To disable use-after-return detection use -@option{--param asan-use-after-return=0}. +A function may be given the attribute @code{no_instrument_function}, in +which case this instrumentation is not done. This can be used, for +example, for the profiling functions listed above, high-priority +interrupt routines, and any functions from which the profiling functions +cannot safely be called (perhaps signal handlers, if the profiling +routines generate output or allocate memory). -@item asan-instrumentation-with-call-threshold -If number of memory accesses in function being instrumented -is greater or equal to this number, use callbacks instead of inline checks. -E.g. to disable inline code use -@option{--param asan-instrumentation-with-call-threshold=0}. +@item -finstrument-functions-exclude-file-list=@var{file},@var{file},@dots{} +@opindex finstrument-functions-exclude-file-list -@item chkp-max-ctor-size -Static constructors generated by Pointer Bounds Checker may become very -large and significantly increase compile time at optimization level -@option{-O1} and higher. This parameter is a maximum nubmer of statements -in a single generated constructor. Default value is 5000. +Set the list of functions that are excluded from instrumentation (see +the description of @option{-finstrument-functions}). If the file that +contains a function definition matches with one of @var{file}, then +that function is not instrumented. The match is done on substrings: +if the @var{file} parameter is a substring of the file name, it is +considered to be a match. -@item max-fsm-thread-path-insns -Maximum number of instructions to copy when duplicating blocks on a -finite state automaton jump thread path. The default is 100. +For example: -@item max-fsm-thread-length -Maximum number of basic blocks on a finite state automaton jump thread -path. The default is 10. +@smallexample +-finstrument-functions-exclude-file-list=/bits/stl,include/sys +@end smallexample -@item max-fsm-thread-paths -Maximum number of new jump thread paths to create for a finite state -automaton. The default is 50. +@noindent +excludes any inline function defined in files whose pathnames +contain @file{/bits/stl} or @file{include/sys}. -@item parloops-chunk-size -Chunk size of omp schedule for loops parallelized by parloops. The default -is 0. +If, for some reason, you want to include letter @samp{,} in one of +@var{sym}, write @samp{\,}. For example, +@option{-finstrument-functions-exclude-file-list='\,\,tmp'} +(note the single quote surrounding the option). -@item parloops-schedule -Schedule type of omp schedule for loops parallelized by parloops (static, -dynamic, guided, auto, runtime). The default is static. +@item -finstrument-functions-exclude-function-list=@var{sym},@var{sym},@dots{} +@opindex finstrument-functions-exclude-function-list + +This is similar to @option{-finstrument-functions-exclude-file-list}, +but this option sets the list of function names to be excluded from +instrumentation. The function name to be matched is its user-visible +name, such as @code{vector blah(const vector &)}, not the +internal mangled name (e.g., @code{_Z4blahRSt6vectorIiSaIiEE}). The +match is done on substrings: if the @var{sym} parameter is a substring +of the function name, it is considered to be a match. For C99 and C++ +extended identifiers, the function name must be given in UTF-8, not +using universal character names. -@item max-ssa-name-query-depth -Maximum depth of recursion when querying properties of SSA names in things -like fold routines. One level of recursion corresponds to following a -use-def chain. -@end table @end table + @node Preprocessor Options @section Options Controlling the Preprocessor @cindex preprocessor options @@ -11861,13 +12064,6 @@ can figure out the other form by either removing @samp{no-} or adding it. @table @gcctabopt -@item -fbounds-check -@opindex fbounds-check -For front ends that support it, generate additional code to check that -indices used to access arrays are within the declared range. This is -currently only supported by the Java and Fortran front ends, where -this option defaults to true and false respectively. - @item -fstack-reuse=@var{reuse-level} @opindex fstack_reuse This option controls stack space reuse for user declared local/auto variables @@ -12282,160 +12478,6 @@ code that is not binary compatible with code generated without that switch. Additionally, it makes the code suboptimal. Use it to conform to a non-default application binary interface. -@item -finstrument-functions -@opindex finstrument-functions -Generate instrumentation calls for entry and exit to functions. Just -after function entry and just before function exit, the following -profiling functions are called with the address of the current -function and its call site. (On some platforms, -@code{__builtin_return_address} does not work beyond the current -function, so the call site information may not be available to the -profiling functions otherwise.) - -@smallexample -void __cyg_profile_func_enter (void *this_fn, - void *call_site); -void __cyg_profile_func_exit (void *this_fn, - void *call_site); -@end smallexample - -The first argument is the address of the start of the current function, -which may be looked up exactly in the symbol table. - -This instrumentation is also done for functions expanded inline in other -functions. The profiling calls indicate where, conceptually, the -inline function is entered and exited. This means that addressable -versions of such functions must be available. If all your uses of a -function are expanded inline, this may mean an additional expansion of -code size. If you use @code{extern inline} in your C code, an -addressable version of such functions must be provided. (This is -normally the case anyway, but if you get lucky and the optimizer always -expands the functions inline, you might have gotten away without -providing static copies.) - -A function may be given the attribute @code{no_instrument_function}, in -which case this instrumentation is not done. This can be used, for -example, for the profiling functions listed above, high-priority -interrupt routines, and any functions from which the profiling functions -cannot safely be called (perhaps signal handlers, if the profiling -routines generate output or allocate memory). - -@item -finstrument-functions-exclude-file-list=@var{file},@var{file},@dots{} -@opindex finstrument-functions-exclude-file-list - -Set the list of functions that are excluded from instrumentation (see -the description of @option{-finstrument-functions}). If the file that -contains a function definition matches with one of @var{file}, then -that function is not instrumented. The match is done on substrings: -if the @var{file} parameter is a substring of the file name, it is -considered to be a match. - -For example: - -@smallexample --finstrument-functions-exclude-file-list=/bits/stl,include/sys -@end smallexample - -@noindent -excludes any inline function defined in files whose pathnames -contain @file{/bits/stl} or @file{include/sys}. - -If, for some reason, you want to include letter @samp{,} in one of -@var{sym}, write @samp{\,}. For example, -@option{-finstrument-functions-exclude-file-list='\,\,tmp'} -(note the single quote surrounding the option). - -@item -finstrument-functions-exclude-function-list=@var{sym},@var{sym},@dots{} -@opindex finstrument-functions-exclude-function-list - -This is similar to @option{-finstrument-functions-exclude-file-list}, -but this option sets the list of function names to be excluded from -instrumentation. The function name to be matched is its user-visible -name, such as @code{vector blah(const vector &)}, not the -internal mangled name (e.g., @code{_Z4blahRSt6vectorIiSaIiEE}). The -match is done on substrings: if the @var{sym} parameter is a substring -of the function name, it is considered to be a match. For C99 and C++ -extended identifiers, the function name must be given in UTF-8, not -using universal character names. - -@item -fstack-check -@opindex fstack-check -Generate code to verify that you do not go beyond the boundary of the -stack. You should specify this flag if you are running in an -environment with multiple threads, but you only rarely need to specify it in -a single-threaded environment since stack overflow is automatically -detected on nearly all systems if there is only one stack. - -Note that this switch does not actually cause checking to be done; the -operating system or the language runtime must do that. The switch causes -generation of code to ensure that they see the stack being extended. - -You can additionally specify a string parameter: @samp{no} means no -checking, @samp{generic} means force the use of old-style checking, -@samp{specific} means use the best checking method and is equivalent -to bare @option{-fstack-check}. - -Old-style checking is a generic mechanism that requires no specific -target support in the compiler but comes with the following drawbacks: - -@enumerate -@item -Modified allocation strategy for large objects: they are always -allocated dynamically if their size exceeds a fixed threshold. - -@item -Fixed limit on the size of the static frame of functions: when it is -topped by a particular function, stack checking is not reliable and -a warning is issued by the compiler. - -@item -Inefficiency: because of both the modified allocation strategy and the -generic implementation, code performance is hampered. -@end enumerate - -Note that old-style stack checking is also the fallback method for -@samp{specific} if no target support has been added in the compiler. - -@item -fstack-limit-register=@var{reg} -@itemx -fstack-limit-symbol=@var{sym} -@itemx -fno-stack-limit -@opindex fstack-limit-register -@opindex fstack-limit-symbol -@opindex fno-stack-limit -Generate code to ensure that the stack does not grow beyond a certain value, -either the value of a register or the address of a symbol. If a larger -stack is required, a signal is raised at run time. For most targets, -the signal is raised before the stack overruns the boundary, so -it is possible to catch the signal without taking special precautions. - -For instance, if the stack starts at absolute address @samp{0x80000000} -and grows downwards, you can use the flags -@option{-fstack-limit-symbol=__stack_limit} and -@option{-Wl,--defsym,__stack_limit=0x7ffe0000} to enforce a stack limit -of 128KB@. Note that this may only work with the GNU linker. - -You can locally override stack limit checking by using the -@code{no_stack_limit} function attribute (@pxref{Function Attributes}). - -@item -fsplit-stack -@opindex fsplit-stack -Generate code to automatically split the stack before it overflows. -The resulting program has a discontiguous stack which can only -overflow if the program is unable to allocate any more memory. This -is most useful when running threaded programs, as it is no longer -necessary to calculate a good stack size to use for each thread. This -is currently only implemented for the x86 targets running -GNU/Linux. - -When code compiled with @option{-fsplit-stack} calls code compiled -without @option{-fsplit-stack}, there may not be much stack space -available for the latter code to run. If compiling all code, -including library code, with @option{-fsplit-stack} is not an option, -then the linker can fix up these calls so that the code compiled -without @option{-fsplit-stack} always has a large stack. Support for -this is implemented in the gold linker in GNU binutils release 2.21 -and later. - @item -fleading-underscore @opindex fleading-underscore This option and its counterpart, @option{-fno-leading-underscore}, forcibly