diff options
| author | alk3pInjection <webmaster@raspii.tech> | 2024-02-04 16:16:35 +0800 |
|---|---|---|
| committer | alk3pInjection <webmaster@raspii.tech> | 2024-02-04 16:16:35 +0800 |
| commit | abdaadbcae30fe0c9a66c7516798279fdfd97750 (patch) | |
| tree | 00a54a6e25601e43876d03c1a4a12a749d4a914c /share/doc/gcc/Code-Gen-Options.html | |
https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads
Change-Id: I7303388733328cd98ab9aa3c30236db67f2e9e9c
Diffstat (limited to 'share/doc/gcc/Code-Gen-Options.html')
| -rw-r--r-- | share/doc/gcc/Code-Gen-Options.html | 809 |
1 files changed, 809 insertions, 0 deletions
diff --git a/share/doc/gcc/Code-Gen-Options.html b/share/doc/gcc/Code-Gen-Options.html new file mode 100644 index 0000000..fa77ede --- /dev/null +++ b/share/doc/gcc/Code-Gen-Options.html @@ -0,0 +1,809 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- This file documents the use of the GNU compilers. + +Copyright (C) 1988-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "Funding Free Software", the Front-Cover +Texts being (a) (see below), and with the Back-Cover Texts being (b) +(see below). A copy of the license is included in the section entitled +"GNU Free Documentation License". + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>Using the GNU Compiler Collection (GCC): Code Gen Options</title> + +<meta name="description" content="Using the GNU Compiler Collection (GCC): Code Gen Options"> +<meta name="keywords" content="Using the GNU Compiler Collection (GCC): Code Gen Options"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Indices.html#Indices" rel="index" title="Indices"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Invoking-GCC.html#Invoking-GCC" rel="up" title="Invoking GCC"> +<link href="Developer-Options.html#Developer-Options" rel="next" title="Developer Options"> +<link href="Directory-Options.html#Directory-Options" rel="previous" title="Directory Options"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en_US" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Code-Gen-Options"></a> +<div class="header"> +<p> +Next: <a href="Developer-Options.html#Developer-Options" accesskey="n" rel="next">Developer Options</a>, Previous: <a href="Directory-Options.html#Directory-Options" accesskey="p" rel="previous">Directory Options</a>, Up: <a href="Invoking-GCC.html#Invoking-GCC" accesskey="u" rel="up">Invoking GCC</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indices.html#Indices" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Options-for-Code-Generation-Conventions"></a> +<h3 class="section">3.17 Options for Code Generation Conventions</h3> +<a name="index-code-generation-conventions"></a> +<a name="index-options_002c-code-generation"></a> +<a name="index-run_002dtime-options"></a> + +<p>These machine-independent options control the interface conventions +used in code generation. +</p> +<p>Most of them have both positive and negative forms; the negative form +of <samp>-ffoo</samp> is <samp>-fno-foo</samp>. In the table below, only +one of the forms is listed—the one that is not the default. You +can figure out the other form by either removing ‘<samp>no-</samp>’ or adding +it. +</p> +<dl compact="compact"> +<dd><a name="index-fstack_005freuse"></a> +</dd> +<dt><code>-fstack-reuse=<var>reuse-level</var></code></dt> +<dd><p>This option controls stack space reuse for user declared local/auto variables +and compiler generated temporaries. <var>reuse_level</var> can be ‘<samp>all</samp>’, +‘<samp>named_vars</samp>’, or ‘<samp>none</samp>’. ‘<samp>all</samp>’ enables stack reuse for all +local variables and temporaries, ‘<samp>named_vars</samp>’ enables the reuse only for +user defined local variables with names, and ‘<samp>none</samp>’ disables stack reuse +completely. The default value is ‘<samp>all</samp>’. The option is needed when the +program extends the lifetime of a scoped local variable or a compiler generated +temporary beyond the end point defined by the language. When a lifetime of +a variable ends, and if the variable lives in memory, the optimizing compiler +has the freedom to reuse its stack space with other temporaries or scoped +local variables whose live range does not overlap with it. Legacy code extending +local lifetime is likely to break with the stack reuse optimization. +</p> +<p>For example, +</p> +<div class="smallexample"> +<pre class="smallexample"> int *p; + { + int local1; + + p = &local1; + local1 = 10; + .... + } + { + int local2; + local2 = 20; + ... + } + + if (*p == 10) // out of scope use of local1 + { + + } +</pre></div> + +<p>Another example: +</p><div class="smallexample"> +<pre class="smallexample"> + struct A + { + A(int k) : i(k), j(k) { } + int i; + int j; + }; + + A *ap; + + void foo(const A& ar) + { + ap = &ar; + } + + void bar() + { + foo(A(10)); // temp object's lifetime ends when foo returns + + { + A a(20); + .... + } + ap->i+= 10; // ap references out of scope temp whose space + // is reused with a. What is the value of ap->i? + } + +</pre></div> + +<p>The lifetime of a compiler generated temporary is well defined by the C++ +standard. When a lifetime of a temporary ends, and if the temporary lives +in memory, the optimizing compiler has the freedom to reuse its stack +space with other temporaries or scoped local variables whose live range +does not overlap with it. However some of the legacy code relies on +the behavior of older compilers in which temporaries’ stack space is +not reused, the aggressive stack reuse can lead to runtime errors. This +option is used to control the temporary stack reuse optimization. +</p> +<a name="index-ftrapv"></a> +</dd> +<dt><code>-ftrapv</code></dt> +<dd><p>This option generates traps for signed overflow on addition, subtraction, +multiplication operations. +The options <samp>-ftrapv</samp> and <samp>-fwrapv</samp> override each other, so using +<samp>-ftrapv</samp> <samp>-fwrapv</samp> on the command-line results in +<samp>-fwrapv</samp> being effective. Note that only active options override, so +using <samp>-ftrapv</samp> <samp>-fwrapv</samp> <samp>-fno-wrapv</samp> on the command-line +results in <samp>-ftrapv</samp> being effective. +</p> +<a name="index-fwrapv"></a> +</dd> +<dt><code>-fwrapv</code></dt> +<dd><p>This option instructs the compiler to assume that signed arithmetic +overflow of addition, subtraction and multiplication wraps around +using twos-complement representation. This flag enables some optimizations +and disables others. +The options <samp>-ftrapv</samp> and <samp>-fwrapv</samp> override each other, so using +<samp>-ftrapv</samp> <samp>-fwrapv</samp> on the command-line results in +<samp>-fwrapv</samp> being effective. Note that only active options override, so +using <samp>-ftrapv</samp> <samp>-fwrapv</samp> <samp>-fno-wrapv</samp> on the command-line +results in <samp>-ftrapv</samp> being effective. +</p> +<a name="index-fwrapv_002dpointer"></a> +</dd> +<dt><code>-fwrapv-pointer</code></dt> +<dd><p>This option instructs the compiler to assume that pointer arithmetic +overflow on addition and subtraction wraps around using twos-complement +representation. This flag disables some optimizations which assume +pointer overflow is invalid. +</p> +<a name="index-fstrict_002doverflow"></a> +</dd> +<dt><code>-fstrict-overflow</code></dt> +<dd><p>This option implies <samp>-fno-wrapv</samp> <samp>-fno-wrapv-pointer</samp> and when +negated implies <samp>-fwrapv</samp> <samp>-fwrapv-pointer</samp>. +</p> +<a name="index-fexceptions"></a> +</dd> +<dt><code>-fexceptions</code></dt> +<dd><p>Enable exception handling. Generates extra code needed to propagate +exceptions. For some targets, this implies GCC generates frame +unwind information for all functions, which can produce significant data +size overhead, although it does not affect execution. If you do not +specify this option, GCC enables it by default for languages like +C++ that normally require exception handling, and disables it for +languages like C that do not normally require it. However, you may need +to enable this option when compiling C code that needs to interoperate +properly with exception handlers written in C++. You may also wish to +disable this option if you are compiling older C++ programs that don’t +use exception handling. +</p> +<a name="index-fnon_002dcall_002dexceptions"></a> +</dd> +<dt><code>-fnon-call-exceptions</code></dt> +<dd><p>Generate code that allows trapping instructions to throw exceptions. +Note that this requires platform-specific runtime support that does +not exist everywhere. Moreover, it only allows <em>trapping</em> +instructions to throw exceptions, i.e. memory references or floating-point +instructions. It does not allow exceptions to be thrown from +arbitrary signal handlers such as <code>SIGALRM</code>. This enables +<samp>-fexceptions</samp>. +</p> +<a name="index-fdelete_002ddead_002dexceptions"></a> +</dd> +<dt><code>-fdelete-dead-exceptions</code></dt> +<dd><p>Consider that instructions that may throw exceptions but don’t otherwise +contribute to the execution of the program can be optimized away. +This does not affect calls to functions except those with the +<code>pure</code> or <code>const</code> attributes. +This option is enabled by default for the Ada and C++ compilers, as permitted by +the language specifications. +Optimization passes that cause dead exceptions to be removed are enabled independently at different optimization levels. +</p> +<a name="index-funwind_002dtables"></a> +</dd> +<dt><code>-funwind-tables</code></dt> +<dd><p>Similar to <samp>-fexceptions</samp>, except that it just generates any needed +static data, but does not affect the generated code in any other way. +You normally do not need to enable this option; instead, a language processor +that needs this handling enables it on your behalf. +</p> +<a name="index-fasynchronous_002dunwind_002dtables"></a> +</dd> +<dt><code>-fasynchronous-unwind-tables</code></dt> +<dd><p>Generate unwind table in DWARF format, if supported by target machine. The +table is exact at each instruction boundary, so it can be used for stack +unwinding from asynchronous events (such as debugger or garbage collector). +</p> +<a name="index-fno_002dgnu_002dunique"></a> +<a name="index-fgnu_002dunique"></a> +</dd> +<dt><code>-fno-gnu-unique</code></dt> +<dd><p>On systems with recent GNU assembler and C library, the C++ compiler +uses the <code>STB_GNU_UNIQUE</code> binding to make sure that definitions +of template static data members and static local variables in inline +functions are unique even in the presence of <code>RTLD_LOCAL</code>; this +is necessary to avoid problems with a library used by two different +<code>RTLD_LOCAL</code> plugins depending on a definition in one of them and +therefore disagreeing with the other one about the binding of the +symbol. But this causes <code>dlclose</code> to be ignored for affected +DSOs; if your program relies on reinitialization of a DSO via +<code>dlclose</code> and <code>dlopen</code>, you can use +<samp>-fno-gnu-unique</samp>. +</p> +<a name="index-fpcc_002dstruct_002dreturn"></a> +</dd> +<dt><code>-fpcc-struct-return</code></dt> +<dd><p>Return “short” <code>struct</code> and <code>union</code> values in memory like +longer ones, rather than in registers. This convention is less +efficient, but it has the advantage of allowing intercallability between +GCC-compiled files and files compiled with other compilers, particularly +the Portable C Compiler (pcc). +</p> +<p>The precise convention for returning structures in memory depends +on the target configuration macros. +</p> +<p>Short structures and unions are those whose size and alignment match +that of some integer type. +</p> +<p><strong>Warning:</strong> code compiled with the <samp>-fpcc-struct-return</samp> +switch is not binary compatible with code compiled with the +<samp>-freg-struct-return</samp> switch. +Use it to conform to a non-default application binary interface. +</p> +<a name="index-freg_002dstruct_002dreturn"></a> +</dd> +<dt><code>-freg-struct-return</code></dt> +<dd><p>Return <code>struct</code> and <code>union</code> values in registers when possible. +This is more efficient for small structures than +<samp>-fpcc-struct-return</samp>. +</p> +<p>If you specify neither <samp>-fpcc-struct-return</samp> nor +<samp>-freg-struct-return</samp>, GCC defaults to whichever convention is +standard for the target. If there is no standard convention, GCC +defaults to <samp>-fpcc-struct-return</samp>, except on targets where GCC is +the principal compiler. In those cases, we can choose the standard, and +we chose the more efficient register return alternative. +</p> +<p><strong>Warning:</strong> code compiled with the <samp>-freg-struct-return</samp> +switch is not binary compatible with code compiled with the +<samp>-fpcc-struct-return</samp> switch. +Use it to conform to a non-default application binary interface. +</p> +<a name="index-fshort_002denums"></a> +</dd> +<dt><code>-fshort-enums</code></dt> +<dd><p>Allocate to an <code>enum</code> type only as many bytes as it needs for the +declared range of possible values. Specifically, the <code>enum</code> type +is equivalent to the smallest integer type that has enough room. +</p> +<p><strong>Warning:</strong> the <samp>-fshort-enums</samp> switch causes GCC to generate +code that is not binary compatible with code generated without that switch. +Use it to conform to a non-default application binary interface. +</p> +<a name="index-fshort_002dwchar"></a> +</dd> +<dt><code>-fshort-wchar</code></dt> +<dd><p>Override the underlying type for <code>wchar_t</code> to be <code>short +unsigned int</code> instead of the default for the target. This option is +useful for building programs to run under WINE. +</p> +<p><strong>Warning:</strong> the <samp>-fshort-wchar</samp> switch causes GCC to generate +code that is not binary compatible with code generated without that switch. +Use it to conform to a non-default application binary interface. +</p> +<a name="index-fcommon"></a> +<a name="index-fno_002dcommon"></a> +<a name="index-tentative-definitions"></a> +</dd> +<dt><code>-fcommon</code></dt> +<dd><p>In C code, this option controls the placement of global variables +defined without an initializer, known as <em>tentative definitions</em> +in the C standard. Tentative definitions are distinct from declarations +of a variable with the <code>extern</code> keyword, which do not allocate storage. +</p> +<p>The default is <samp>-fno-common</samp>, which specifies that the compiler places +uninitialized global variables in the BSS section of the object file. +This inhibits the merging of tentative definitions by the linker so you get a +multiple-definition error if the same variable is accidentally defined in more +than one compilation unit. +</p> +<p>The <samp>-fcommon</samp> places uninitialized global variables in a common block. +This allows the linker to resolve all tentative definitions of the same variable +in different compilation units to the same object, or to a non-tentative +definition. This behavior is inconsistent with C++, and on many targets implies +a speed and code size penalty on global variable references. It is mainly +useful to enable legacy code to link without errors. +</p> +<a name="index-fno_002dident"></a> +<a name="index-fident"></a> +</dd> +<dt><code>-fno-ident</code></dt> +<dd><p>Ignore the <code>#ident</code> directive. +</p> +<a name="index-finhibit_002dsize_002ddirective"></a> +</dd> +<dt><code>-finhibit-size-directive</code></dt> +<dd><p>Don’t output a <code>.size</code> assembler directive, or anything else that +would cause trouble if the function is split in the middle, and the +two halves are placed at locations far apart in memory. This option is +used when compiling <samp>crtstuff.c</samp>; you should not need to use it +for anything else. +</p> +<a name="index-fverbose_002dasm"></a> +</dd> +<dt><code>-fverbose-asm</code></dt> +<dd><p>Put extra commentary information in the generated assembly code to +make it more readable. This option is generally only of use to those +who actually need to read the generated assembly code (perhaps while +debugging the compiler itself). +</p> +<p><samp>-fno-verbose-asm</samp>, the default, causes the +extra information to be omitted and is useful when comparing two assembler +files. +</p> +<p>The added comments include: +</p> +<ul> +<li> information on the compiler version and command-line options, + +</li><li> the source code lines associated with the assembly instructions, +in the form FILENAME:LINENUMBER:CONTENT OF LINE, + +</li><li> hints on which high-level expressions correspond to +the various assembly instruction operands. + +</li></ul> + +<p>For example, given this C source file: +</p> +<div class="smallexample"> +<pre class="smallexample">int test (int n) +{ + int i; + int total = 0; + + for (i = 0; i < n; i++) + total += i * i; + + return total; +} +</pre></div> + +<p>compiling to (x86_64) assembly via <samp>-S</samp> and emitting the result +direct to stdout via <samp>-o</samp> <samp>-</samp> +</p> +<div class="smallexample"> +<pre class="smallexample">gcc -S test.c -fverbose-asm -Os -o - +</pre></div> + +<p>gives output similar to this: +</p> +<div class="smallexample"> +<pre class="smallexample"> .file "test.c" +# GNU C11 (GCC) version 7.0.0 20160809 (experimental) (x86_64-pc-linux-gnu) + [...snip...] +# options passed: + [...snip...] + + .text + .globl test + .type test, @function +test: +.LFB0: + .cfi_startproc +# test.c:4: int total = 0; + xorl %eax, %eax # <retval> +# test.c:6: for (i = 0; i < n; i++) + xorl %edx, %edx # i +.L2: +# test.c:6: for (i = 0; i < n; i++) + cmpl %edi, %edx # n, i + jge .L5 #, +# test.c:7: total += i * i; + movl %edx, %ecx # i, tmp92 + imull %edx, %ecx # i, tmp92 +# test.c:6: for (i = 0; i < n; i++) + incl %edx # i +# test.c:7: total += i * i; + addl %ecx, %eax # tmp92, <retval> + jmp .L2 # +.L5: +# test.c:10: } + ret + .cfi_endproc +.LFE0: + .size test, .-test + .ident "GCC: (GNU) 7.0.0 20160809 (experimental)" + .section .note.GNU-stack,"",@progbits +</pre></div> + +<p>The comments are intended for humans rather than machines and hence the +precise format of the comments is subject to change. +</p> +<a name="index-frecord_002dgcc_002dswitches"></a> +</dd> +<dt><code>-frecord-gcc-switches</code></dt> +<dd><p>This switch causes the command line used to invoke the +compiler to be recorded into the object file that is being created. +This switch is only implemented on some targets and the exact format +of the recording is target and binary file format dependent, but it +usually takes the form of a section containing ASCII text. This +switch is related to the <samp>-fverbose-asm</samp> switch, but that +switch only records information in the assembler output file as +comments, so it never reaches the object file. +See also <samp>-grecord-gcc-switches</samp> for another +way of storing compiler options into the object file. +</p> +<a name="index-fpic"></a> +<a name="index-global-offset-table"></a> +<a name="index-PIC"></a> +</dd> +<dt><code>-fpic</code></dt> +<dd><p>Generate position-independent code (PIC) suitable for use in a shared +library, if supported for the target machine. Such code accesses all +constant addresses through a global offset table (GOT). The dynamic +loader resolves the GOT entries when the program starts (the dynamic +loader is not part of GCC; it is part of the operating system). If +the GOT size for the linked executable exceeds a machine-specific +maximum size, you get an error message from the linker indicating that +<samp>-fpic</samp> does not work; in that case, recompile with <samp>-fPIC</samp> +instead. (These maximums are 8k on the SPARC, 28k on AArch64 and 32k +on the m68k and RS/6000. The x86 has no such limit.) +</p> +<p>Position-independent code requires special support, and therefore works +only on certain machines. For the x86, GCC supports PIC for System V +but not for the Sun 386i. Code generated for the IBM RS/6000 is always +position-independent. +</p> +<p>When this flag is set, the macros <code>__pic__</code> and <code>__PIC__</code> +are defined to 1. +</p> +<a name="index-fPIC"></a> +</dd> +<dt><code>-fPIC</code></dt> +<dd><p>If supported for the target machine, emit position-independent code, +suitable for dynamic linking and avoiding any limit on the size of the +global offset table. This option makes a difference on AArch64, m68k, +PowerPC and SPARC. +</p> +<p>Position-independent code requires special support, and therefore works +only on certain machines. +</p> +<p>When this flag is set, the macros <code>__pic__</code> and <code>__PIC__</code> +are defined to 2. +</p> +<a name="index-fpie"></a> +<a name="index-fPIE"></a> +</dd> +<dt><code>-fpie</code></dt> +<dt><code>-fPIE</code></dt> +<dd><p>These options are similar to <samp>-fpic</samp> and <samp>-fPIC</samp>, but the +generated position-independent code can be only linked into executables. +Usually these options are used to compile code that will be linked using +the <samp>-pie</samp> GCC option. +</p> +<p><samp>-fpie</samp> and <samp>-fPIE</samp> both define the macros +<code>__pie__</code> and <code>__PIE__</code>. The macros have the value 1 +for <samp>-fpie</samp> and 2 for <samp>-fPIE</samp>. +</p> +<a name="index-fno_002dplt"></a> +<a name="index-fplt"></a> +</dd> +<dt><code>-fno-plt</code></dt> +<dd><p>Do not use the PLT for external function calls in position-independent code. +Instead, load the callee address at call sites from the GOT and branch to it. +This leads to more efficient code by eliminating PLT stubs and exposing +GOT loads to optimizations. On architectures such as 32-bit x86 where +PLT stubs expect the GOT pointer in a specific register, this gives more +register allocation freedom to the compiler. +Lazy binding requires use of the PLT; +with <samp>-fno-plt</samp> all external symbols are resolved at load time. +</p> +<p>Alternatively, the function attribute <code>noplt</code> can be used to avoid calls +through the PLT for specific external functions. +</p> +<p>In position-dependent code, a few targets also convert calls to +functions that are marked to not use the PLT to use the GOT instead. +</p> +<a name="index-fno_002djump_002dtables"></a> +<a name="index-fjump_002dtables"></a> +</dd> +<dt><code>-fno-jump-tables</code></dt> +<dd><p>Do not use jump tables for switch statements even where it would be +more efficient than other code generation strategies. This option is +of use in conjunction with <samp>-fpic</samp> or <samp>-fPIC</samp> for +building code that forms part of a dynamic linker and cannot +reference the address of a jump table. On some targets, jump tables +do not require a GOT and this option is not needed. +</p> +<a name="index-fno_002dbit_002dtests"></a> +<a name="index-fbit_002dtests"></a> +</dd> +<dt><code>-fno-bit-tests</code></dt> +<dd><p>Do not use bit tests for switch statements even where it would be +more efficient than other code generation strategies. +</p> +<a name="index-ffixed"></a> +</dd> +<dt><code>-ffixed-<var>reg</var></code></dt> +<dd><p>Treat the register named <var>reg</var> as a fixed register; generated code +should never refer to it (except perhaps as a stack pointer, frame +pointer or in some other fixed role). +</p> +<p><var>reg</var> must be the name of a register. The register names accepted +are machine-specific and are defined in the <code>REGISTER_NAMES</code> +macro in the machine description macro file. +</p> +<p>This flag does not have a negative form, because it specifies a +three-way choice. +</p> +<a name="index-fcall_002dused"></a> +</dd> +<dt><code>-fcall-used-<var>reg</var></code></dt> +<dd><p>Treat the register named <var>reg</var> as an allocable register that is +clobbered by function calls. It may be allocated for temporaries or +variables that do not live across a call. Functions compiled this way +do not save and restore the register <var>reg</var>. +</p> +<p>It is an error to use this flag with the frame pointer or stack pointer. +Use of this flag for other registers that have fixed pervasive roles in +the machine’s execution model produces disastrous results. +</p> +<p>This flag does not have a negative form, because it specifies a +three-way choice. +</p> +<a name="index-fcall_002dsaved"></a> +</dd> +<dt><code>-fcall-saved-<var>reg</var></code></dt> +<dd><p>Treat the register named <var>reg</var> as an allocable register saved by +functions. It may be allocated even for temporaries or variables that +live across a call. Functions compiled this way save and restore +the register <var>reg</var> if they use it. +</p> +<p>It is an error to use this flag with the frame pointer or stack pointer. +Use of this flag for other registers that have fixed pervasive roles in +the machine’s execution model produces disastrous results. +</p> +<p>A different sort of disaster results from the use of this flag for +a register in which function values may be returned. +</p> +<p>This flag does not have a negative form, because it specifies a +three-way choice. +</p> +<a name="index-fpack_002dstruct"></a> +</dd> +<dt><code>-fpack-struct[=<var>n</var>]</code></dt> +<dd><p>Without a value specified, pack all structure members together without +holes. When a value is specified (which must be a small power of two), pack +structure members according to this value, representing the maximum +alignment (that is, objects with default alignment requirements larger than +this are output potentially unaligned at the next fitting location. +</p> +<p><strong>Warning:</strong> the <samp>-fpack-struct</samp> switch causes GCC to generate +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. +</p> +<a name="index-fleading_002dunderscore"></a> +</dd> +<dt><code>-fleading-underscore</code></dt> +<dd><p>This option and its counterpart, <samp>-fno-leading-underscore</samp>, forcibly +change the way C symbols are represented in the object file. One use +is to help link with legacy assembly code. +</p> +<p><strong>Warning:</strong> the <samp>-fleading-underscore</samp> switch causes GCC to +generate code that is not binary compatible with code generated without that +switch. Use it to conform to a non-default application binary interface. +Not all targets provide complete support for this switch. +</p> +<a name="index-ftls_002dmodel"></a> +</dd> +<dt><code>-ftls-model=<var>model</var></code></dt> +<dd><p>Alter the thread-local storage model to be used (see <a href="Thread_002dLocal.html#Thread_002dLocal">Thread-Local</a>). +The <var>model</var> argument should be one of ‘<samp>global-dynamic</samp>’, +‘<samp>local-dynamic</samp>’, ‘<samp>initial-exec</samp>’ or ‘<samp>local-exec</samp>’. +Note that the choice is subject to optimization: the compiler may use +a more efficient model for symbols not visible outside of the translation +unit, or if <samp>-fpic</samp> is not given on the command line. +</p> +<p>The default without <samp>-fpic</samp> is ‘<samp>initial-exec</samp>’; with +<samp>-fpic</samp> the default is ‘<samp>global-dynamic</samp>’. +</p> +<a name="index-ftrampolines"></a> +</dd> +<dt><code>-ftrampolines</code></dt> +<dd><p>For targets that normally need trampolines for nested functions, always +generate them instead of using descriptors. Otherwise, for targets that +do not need them, like for example HP-PA or IA-64, do nothing. +</p> +<p>A trampoline is a small piece of code that is created at run time on the +stack when the address of a nested function is taken, and is used to call +the nested function indirectly. Therefore, it requires the stack to be +made executable in order for the program to work properly. +</p> +<p><samp>-fno-trampolines</samp> is enabled by default on a language by language +basis to let the compiler avoid generating them, if it computes that this +is safe, and replace them with descriptors. Descriptors are made up of data +only, but the generated code must be prepared to deal with them. As of this +writing, <samp>-fno-trampolines</samp> is enabled by default only for Ada. +</p> +<p>Moreover, code compiled with <samp>-ftrampolines</samp> and code compiled with +<samp>-fno-trampolines</samp> are not binary compatible if nested functions are +present. This option must therefore be used on a program-wide basis and be +manipulated with extreme care. +</p> +<p>For languages other than Ada, the <code>-ftrampolines</code> and +<code>-fno-trampolines</code> options currently have no effect, and +trampolines are always generated on platforms that need them +for nested functions. +</p> +<a name="index-fvisibility"></a> +</dd> +<dt><code>-fvisibility=<span class="roman">[</span>default<span class="roman">|</span>internal<span class="roman">|</span>hidden<span class="roman">|</span>protected<span class="roman">]</span></code></dt> +<dd><p>Set the default ELF image symbol visibility to the specified option—all +symbols are marked with this unless overridden within the code. +Using this feature can very substantially improve linking and +load times of shared object libraries, produce more optimized +code, provide near-perfect API export and prevent symbol clashes. +It is <strong>strongly</strong> recommended that you use this in any shared objects +you distribute. +</p> +<p>Despite the nomenclature, ‘<samp>default</samp>’ always means public; i.e., +available to be linked against from outside the shared object. +‘<samp>protected</samp>’ and ‘<samp>internal</samp>’ are pretty useless in real-world +usage so the only other commonly used option is ‘<samp>hidden</samp>’. +The default if <samp>-fvisibility</samp> isn’t specified is +‘<samp>default</samp>’, i.e., make every symbol public. +</p> +<p>A good explanation of the benefits offered by ensuring ELF +symbols have the correct visibility is given by “How To Write +Shared Libraries” by Ulrich Drepper (which can be found at +<a href="https://www.akkadia.org/drepper/">https://www.akkadia.org/drepper/</a><!-- /@w -->)—however a superior +solution made possible by this option to marking things hidden when +the default is public is to make the default hidden and mark things +public. This is the norm with DLLs on Windows and with <samp>-fvisibility=hidden</samp> +and <code>__attribute__ ((visibility("default")))</code> instead of +<code>__declspec(dllexport)</code> you get almost identical semantics with +identical syntax. This is a great boon to those working with +cross-platform projects. +</p> +<p>For those adding visibility support to existing code, you may find +<code>#pragma GCC visibility</code> of use. This works by you enclosing +the declarations you wish to set visibility for with (for example) +<code>#pragma GCC visibility push(hidden)</code> and +<code>#pragma GCC visibility pop</code>. +Bear in mind that symbol visibility should be viewed <strong>as +part of the API interface contract</strong> and thus all new code should +always specify visibility when it is not the default; i.e., declarations +only for use within the local DSO should <strong>always</strong> be marked explicitly +as hidden as so to avoid PLT indirection overheads—making this +abundantly clear also aids readability and self-documentation of the code. +Note that due to ISO C++ specification requirements, <code>operator new</code> and +<code>operator delete</code> must always be of default visibility. +</p> +<p>Be aware that headers from outside your project, in particular system +headers and headers from any other library you use, may not be +expecting to be compiled with visibility other than the default. You +may need to explicitly say <code>#pragma GCC visibility push(default)</code> +before including any such headers. +</p> +<p><code>extern</code> declarations are not affected by <samp>-fvisibility</samp>, so +a lot of code can be recompiled with <samp>-fvisibility=hidden</samp> with +no modifications. However, this means that calls to <code>extern</code> +functions with no explicit visibility use the PLT, so it is more +effective to use <code>__attribute ((visibility))</code> and/or +<code>#pragma GCC visibility</code> to tell the compiler which <code>extern</code> +declarations should be treated as hidden. +</p> +<p>Note that <samp>-fvisibility</samp> does affect C++ vague linkage +entities. This means that, for instance, an exception class that is +be thrown between DSOs must be explicitly marked with default +visibility so that the ‘<samp>type_info</samp>’ nodes are unified between +the DSOs. +</p> +<p>An overview of these techniques, their benefits and how to use them +is at <a href="https://gcc.gnu.org/wiki/Visibility">https://gcc.gnu.org/wiki/Visibility</a>. +</p> +<a name="index-fstrict_002dvolatile_002dbitfields"></a> +</dd> +<dt><code>-fstrict-volatile-bitfields</code></dt> +<dd><p>This option should be used if accesses to volatile bit-fields (or other +structure fields, although the compiler usually honors those types +anyway) should use a single access of the width of the +field’s type, aligned to a natural alignment if possible. For +example, targets with memory-mapped peripheral registers might require +all such accesses to be 16 bits wide; with this flag you can +declare all peripheral bit-fields as <code>unsigned short</code> (assuming short +is 16 bits on these targets) to force GCC to use 16-bit accesses +instead of, perhaps, a more efficient 32-bit access. +</p> +<p>If this option is disabled, the compiler uses the most efficient +instruction. In the previous example, that might be a 32-bit load +instruction, even though that accesses bytes that do not contain +any portion of the bit-field, or memory-mapped registers unrelated to +the one being updated. +</p> +<p>In some cases, such as when the <code>packed</code> attribute is applied to a +structure field, it may not be possible to access the field with a single +read or write that is correctly aligned for the target machine. In this +case GCC falls back to generating multiple accesses rather than code that +will fault or truncate the result at run time. +</p> +<p>Note: Due to restrictions of the C/C++11 memory model, write accesses are +not allowed to touch non bit-field members. It is therefore recommended +to define all bits of the field’s type as bit-field members. +</p> +<p>The default value of this option is determined by the application binary +interface for the target processor. +</p> +<a name="index-fsync_002dlibcalls"></a> +</dd> +<dt><code>-fsync-libcalls</code></dt> +<dd><p>This option controls whether any out-of-line instance of the <code>__sync</code> +family of functions may be used to implement the C++11 <code>__atomic</code> +family of functions. +</p> +<p>The default value of this option is enabled, thus the only useful form +of the option is <samp>-fno-sync-libcalls</samp>. This option is used in +the implementation of the <samp>libatomic</samp> runtime library. +</p> +</dd> +</dl> + +<hr> +<div class="header"> +<p> +Next: <a href="Developer-Options.html#Developer-Options" accesskey="n" rel="next">Developer Options</a>, Previous: <a href="Directory-Options.html#Directory-Options" accesskey="p" rel="previous">Directory Options</a>, Up: <a href="Invoking-GCC.html#Invoking-GCC" accesskey="u" rel="up">Invoking GCC</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indices.html#Indices" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> |